BOOT(8)BOOT(8)NAMEboot - connect to the root file server
/boot/boot [ -fkm ] [ -uusername ] [ method!fs-addr ] [ args ]
Boot is the first program run after a kernel has been loaded. It con‐
nects to the file server that will serve the root, performs any authen‐
tication needed to connect to that server, and exec(2)'s the init(8)
program. It is started by the kernel, never run directly by the user.
See booting(8) for information about the process of loading the kernel
(and boot) into memory.
Once loaded, the kernel initializes its data structures and devices.
It sets the two environment variables /env/cputype and /env/terminal to
describe the processor. It then binds a place-holder file server,
root(3), onto / and crafts an initial process whose sole function is to
exec(2) /boot/boot, a binary which is compiled into root(3).
The command line passed depends on the information passed from boot ROM
to kernel. Machines that boot directly from ROM (that is, most
machines other than PCs) pass the boot line given to the ROM directly
On the PC, each line in the DOS file plan9.ini of the form name=value
is passed to the boot program as an environment variable with the same
name and value. The command line is
(The first argument is ignored by boot.) Boot must determine the file
server to use and a method with which to connect to it. Typically this
will name a file server on the network, or state that the root file
system is on local disk and name the partition. The complete list of
methods is given below.
Boot must also set a user name to be used as the owner of devices and
all console processes and an encryption key to be used when challenged.
Boot will prompt for these.
Method and address are prompted for first. The prompt lists all valid
methods, with the default in brackets, for example:
root is from (tcp, local!#S/sdC0/fs)[tcp]:
A newline picks the default. Other possible responses are method or
method!address. To aid in automatic reboot, the default is automati‐
cally taken on CPU servers if nothing is typed within 15 seconds.
The other interactions depend on whether the system is a terminal or a
The terminal must have a username to set. If none is specified with
the -u option, boot will prompt for one on the console:
The user will also be prompted for a password to be used as an encryp‐
tion key on each attach(5):
With most methods boot can now connect to the file server. However,
with the serial line methods 9600 and 19200, the actual mechanics of
setting up the complete connection are too varied to put into the boot
program. Instead boot lets the user set up the connection. It prints
a prompt on the console and then simulates a dumb terminal between the
user and the serial line:
Connect to file system now, type ctrl-d when done.
(Use the view or down arrow key to send a break)
The user can now type at the modem to dial the number. What is typed
depends on the modem and is beyond this discussion.
When the user types a control-D, boot stops simulating a terminal and
starts the file system protocol over the serial line.
Once connected, boot mounts the root file system before / and makes the
connection available as #s/boot for subsequent processes to mount (see
bind(2)). Boot completes by exec(2)'ing /$cputype/init -t. If the -m
option is given it is also passed as an option to init. If the envi‐
ronment variable init is set (via plan9.ini(8)), it is used as a com‐
mand line to exec instead.
If the kernel has been built with the cache file system, cfs(4), the
local disk partition /dev/sdXX/cache (where XX is a unit specifier)
exists, and the root file system is from a remote server, then the ker‐
nel will insert a user level cache process between the remote server
and the local namespace that caches all remote accesses on the local
partition. The -f flag commands cfs to reformat the cache partition.
The user owning devices and console processes on CPU servers and that
user's domain and encryption key are read from NVRAM on all machines
except PC's. PC's keep the information in the disk partition
/dev/sdXX/nvram. If a -k option is given or if no stored information
is found boot will prompt for all three items and store them.
The key is used for mutual authentication of the server and its
clients. The domain and id identify the owner of the key.
Once connected, boot behaves as on the terminal except for exec(2)'ing
The methods available to any system depend on what was compiled into
the kernel. The complete list of booting methods are listed below.
tcp connect via Ethernet using the TCP protocol. The args are
passed to ipconfig(8) when configuring the IP stack. The
plan9.ini(8) variables fs and auth override the file server and
authentication server IP addresses obtained (if any) from DHCP
local connect to the local file system. The first argument is a disk
holding a file system. Boot inspects the disk. If the disk is
a fossil(4) file system, it invokes /boot/fossil to serve it.
If the venti environment variable (really, plan9.ini(8) vari‐
able) is set, boot first arranges for fossil to be able to con‐
tact the named venti(8) server. The variable's value can take
the following forms:
the file should be a venti partition with a configura‐
tion stored on it using venti/conf (see venti-fmt(8)).
Boot will start a loopback IP interface on 127.0.0.1 and
start venti announcing on tcp!127.1!17034 for venti ser‐
vice and tcp!127.1!8000 for web service, using the con‐
figuration stored in that partition.
same as the last but specify an alternate venti service
address. In this example, using * will announce on all
available IP interfaces (even ones configured later)
rather than just the loopback device. The loopback
interface is still configured.
/dev/sdC0/arenas tcp!*!17034 tcp!*!80
same as the last but specify alternate venti service and
web addresses. The loopback interface is still config‐
tcp!126.96.36.199!17034 [ args ]
the network address of a venti server running on a sepa‐
rate machine. Boot will configure the IP stack by pass‐
ing args, if any, to ipconfig(8).
Fossil is invoked as
/boot/fossil -f partition -c 'srv -A fboot' -c 'srv -p fscons'
and boot then renames to so fossil.conf should not use the srv
command to create nor
If the disk is not a fossil(4) partition, boot invokes
/boot/kfs. A variety of programs, like 9660srv and dossrv(4)
masquerade as kfs to allow booting from alternate media for‐
mats, so as long as the disk is not a fossil disk, no check is
made that the disk is in fact a kfs disk. The args are passed
For the tcp method, the address must be a numeric IP address.
If no address is specified, a file server address will be found
from another system on the network using the BOOTP protocol and
the Plan 9 vendor-specific fields.
On PCs, the default arguments to boot are constructed using the
bootargs variable in plan9.ini(8).
Start kfs(4) with extra disk buffers:
bootargs=local!#S/sdC0/fs -B 4096
Use an IP stack on an alternate ethernet interface with a static
address and fixed file server and authentication server addresses.
bootargs=tcp -g 192.168.0.1 ether /net/ether1 \
(The bootargs line is split only for presentation; it is one line in
SEE ALSOroot(3), factotum(4), dhcpd(8), init(8)BUGS
The use of bootargs in general is odd. The configuration specification
for fossil and venti servers is particularly odd, but it does cover the
common cases well.