Westwind Computing
 206-522-3530
 Sales Information
 Customer Feedback
Westwind Computing
[New to Westwind?]  [Customers]  [News & Information] 



Reference


OS X's BSD/unix command-line

Single-User Mode Commands

By Gordon Davisson

Copyright (c) 2002, Westwind Computing inc.

Index:


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

Home | Specials | Products | Education | About Us | Services | Training | Support | Reference | Events | How-to
   Copyright © 2000-2004 Westwind Computing