UNIX Intro to Single-user mode

To get to single-user mode, hold down the command (i.e. cloverleaf or Apple)
and “s” keys as the system begins to boot. This will drop you into a command
line interface before the system has fully started up, giving you the chance
to check/repair things before much of the normal OS X environment starts up.

Single-user mode starts you with an extremely minimal environment — not
only is the normal graphical interface not running, neither are most of
the normal system daemons (init
and mach-init are the only ones), and the boot disk isn’t even fully mounted!
Usually, you want to bring at least a little more of OS X up in order to
get anything useful done. Exactly how much depends on what you want to do,
but usually you want to either just mount the boot volume
for write access
, or do that and then start the
various system daemons and components
(e.g. networking) that make up
most of the non-graphical parts of Mac OS X.


Mounting the boot volume for write access:

fsck -y
  – Check the boot volume’s file system, and repair if necessary
(the “-y” means “Yes, go ahead and fix any problems you find”). Always
do this first. Note that this may not be able to fix all problems in a
single pass, so if it finds and fixes anything (it’ll print “***** FILE
SYSTEM WAS MODIFIED *****”), run it again, and keep running it until it
comes back with something like “The volume Macintosh HD appears to be
ok.”

Note: If the volume has journalling enabled, you should get a message like

fsck_hfs: Volume is journaled. No checking performed.
fsck_hfs: Use the -f option to force checking.

In this case it should be reasonably safe to go ahead and mount the volume,
since the journal should have taken care of any necessary repairs. But I’m
paranoid, so I tend to recommend using fsck -yf to force a full
check.

See Apple’s TIL article
#106214
for more info.

mount -uw /
  – Remount the boot volume,
enabling write access. You need to do this before you can change anything on
disk, but always run fsck first.

Note: if this command works, it won’t give you any output (other than another
shell prompt). If it prints something like:
 root_device on / (local, read-only)
 devfs on /dev (local)


then you probably mistyped the command.


Starting system daemons and components:

Depending on what you need to accomplish in single-user mode, you may (or
may not) need to start up more of the operating system’s normal components
(access to disks other than the boot volume, networking, etc). This part of
the process works a bit differently depending on what version of Mac OS X
you’re using. Under 10.0 through 10.2, the
SystemStarter
command is all it takes. Under 10.3, you need
to register the Mach services, then launch
netinfod manually, then finally invoke
SystemStarter to finish the job.
Under 10.4, it gets easy again: you can use /etc/rc to
do the work for you.

After running any of these commands, do not attempt to continue the boot
with the exit command. If you aren’t sure what
version you have, use sw_vers to find out.

Starting daemons under 10.4:

sh /etc/rc
  – Under version 10.4, the normal startup script can be run by hand,
and it’ll do the necessary work of getting the system (mostly) up and
running, but not exit single-user mode or start the GUI.

Starting daemons under 10.3:

/usr/libexec/register_mach_bootstrap_servers
/etc/mach_init.d

  – This registers a bunch of programs to be triggered by mach-init,
which take care of setting up networking, directory services, disk arbitration,
etc. — see the config files in /etc/mach_init.d/ and

Apple’s web page on the boot process

(look for the section on Bootstrap Daemons) for more information.

Note: after this command finishes, several of the things it triggers will
print messages on the screen, possibly mixing in with whatever command you’re
trying to type, and making things generally confusing. You can force it
to reprint the command you’re working on by typing ^p^n (that is, hold down
the control key while pressing “p” and then “n”). Also, one of the messages
may imply that lookupd has failed; don’t worry, it seems to get restarted
normally.

(cd /var/db/netinfo; netinfod -s local)
  – Start up a netinfo server to handle the local domain (i.e. users,
groups, etc defined on this computer).

SystemStarter
  – Start up more of the system, including networking, NFS, and
many background daemons (basically, it runs all of the StartupItems). It does
not, however, start the Aqua interface; it leaves you with the single-user
command line when it’s done.

Note: this command prints out even more stuff than
/usr/libexec/register_mach_bootstrap_servers did. Don’t even try
to get a word in edgewise; I just wait until it finishes (it’ll print
“Startup complete.”), then press return to get a new command prompt.

Starting daemons under 10.0-10.2:

SystemStarter
  – Up through 10.2, this command would take care of starting pretty
much everything (except the GUI)… including everything that
register_mach_bootstrap_servers
and netinfod are needed for under 10.3.


Other Commands useful in Single-user mode:

pico
  – Edit text files (see the main entry for ).
The second line from the top of the screen may contain gibberish, and the keyboard
arrow-keys may not work (use control-characters
instead) but other than that it works normally. vi and emacs
are also available in single-user mode, although vi seems to have
problems with screen updating under at least some versions of OS X.

nicl -raw /var/db/netinfo/local.nidb
  – Edit the local Netinfo database (users & groups, etc) without going
through the netinfo daemon. Handy if the system can’t boot properly because
of a Netinfo configuration problem.

Note: do not use this form of the nicl command after starting the netinfod
server (either manually or with
SystemStarter).

Examples:

nicl -raw /var/db/netinfo/local.nidb

  create disabled

  move mounts disabled
  quit
Disable the NFS “mounts” directory (by creating a “disabled” directory and
moving mounts into it), which can bypass a hang at startup if the computer
tries to mount an unavailable NFS server.
nicl -raw /var/db/netinfo/local.nidb

  delete /localconfig/autologin username

  quit
Disable automatic login at boot time (normally controlled from the Login
pane in System Preferences), in order to avoid logging into a damaged account.

bless
  – Change the system’s boot settings (the “blessed” system). Useful to switch
back to OS 9 if OS X isn’t bootable, and you don’t want to juggle boot CDs.

Example:

bless -folder9 "/System Folder" -use9
Bless the OS-9 system folder named “System Folder” on the current (OS-X) boot
volume, and make OS-9 the default for booting from this volume.

tail
  – Print the last few entries in a log (or other text file). Useful to find
out what happened to get you into this mess.

Examples:

tail /var/log/system.log
print the last screenful of
entries from the main system log.
tail -1000 /var/log/system.log | more
print the last 1000
entries from the main system log, using more to
display them one screenful at a time (remember: in single-user mode, there’s
no way to scroll back like you can in a terminal window).

sw_vers
  – Check the operating system version. Useful to find out which procedure
to use to start system daemons.


Important files:

/var/db/.AppleSetupDone
  – This file, simply by existing, indicates that the computer has had
basic setup performed. If you delete this file, the Setup Assistant will
run on the next reboot, allowing you to create a new local admin account,
re-setup networking, etc.

/Library/Preferences/SystemConfiguration/
(10.3) or

/var/db/SystemConfiguration/ (10.0 – 10.2)
  – Despite its generic-sounding name, this directory is actually where
most of the computer’s network settings are stored (especially in the file
named “preferences.plist”). Moving or renaming this directory will force the
OS to build a default set of network settings on the next reboot (i.e. one
location named “Automatic”, DHCP on all ethernet & AirPort interfaces, etc).
If your network settings get hosed to the point where the computer won’t boot,
this is the easy way out.

/Library/Logs/ and

/var/log/
  – Where the log files are kept. Generally, logs relating to the core
unix (Darwin) parts of the operating system can be found in /var/log/,
while the Apple-proprietary system components log to /Library/Logs/.
When in doubt, look both places. And check out the main system log,
/var/log/system.log — all sorts of interesting events wind up there.
Note: old logs are often archived in gzip (compressed) format; to read these,
you can do something like:

zcat /var/log/system.log.1.gz | more
decompress the
most recent archived system log, and use more to display it one
screenful at a time.

Getting Out of Single-user mode:

exit
  – Continue the boot process (i.e. go to multi-user mode). Note that
if you’ve made any significant changes (or started any daemons, run
SystemStarter, or anything like that),
it’s safer to reboot instead.

reboot
  – Reboot the computer.

shutdown -h now
  – Shut the computer down.


Misc. Notes:

In single-user mode, the shell behaves a little differently than normal (more
so under earlier versions of OS X). For one thing, the default shell may be
different (zsh under 10.0-10.2, bash under 10.3); unless you’re extremely
familiar with the peculiarities of your regular shell, you probably won’t
notice this (except that the shell prompt’ll be different from normal).

Also, the keyboard may not be fully configured in
single-user mode
, so the arrow keys don’t work for command line editing (or
in text editors, either); but you can use control characters (i.e. hold down
the control key – that’s control, not command – and type a letter) instead:
 ^p – previous line, equivalent to up-arrow

 ^n – next line, equivalent to down-arrow

 ^b – back a character, equivalent to left-arrow

 ^f – forward a character, equivalent to right-arrow

 ^a – back to the beginning of the line

 ^e – forward to the end of the line

Leave a Reply