sys/man/8/boot

   1 .TH BOOT 8
   2 .SH NAME
   3 boot, bootrc \- connect to the root file server
   4 .SH SYNOPSIS
   5 .B /boot/boot
   6 .SH DESCRIPTION
   7 .I Boot
   8 is the first program run after a kernel has been loaded. It
   9 mounts
  10 .BR bootfs.paq ,
  11 a compressed filesystem contained in
  12 .IR root (3),
  13 sets up the
  14 .IR rc (1)
  15 environment and executes
  16 .I bootrc
  17 passing on its arguments.
  18 .I Bootrc
  19 connects to the file server that will serve the root, performs any
  20 authentication needed to connect to that server, and executes the
  21 .IR init (8)
  22 program. Both
  23 .I boot
  24 and
  25 .I bootrc
  26 are started by the kernel, never run directly by the user.
  27 See
  28 .IR booting (8)
  29 for information about the process of loading the kernel (and
  30 .IR boot )
  31 into memory.
  32 .PP
  33 Once loaded, the kernel initializes its data structures and devices.
  34 It sets the two environment variables
  35 .B /env/cputype
  36 and
  37 .B /env/terminal
  38 to describe the processor.
  39 It then binds a place-holder file server,
  40 .IR root (3),
  41 onto
  42 .B /
  43 and crafts an initial process whose sole function is to
  44 .IR exec (2)
  45 .BR /boot/boot ,
  46 a binary which is compiled into
  47 .IR root (3).
  48 .PP
  49 The command line passed depends
  50 on the information passed from boot ROM
  51 to kernel.
  52 Machines that boot directly from ROM (that is, most machines other than PCs)
  53 pass the boot line given to the ROM directly to
  54 .IR boot .
  55 .PP
  56 On the PC, each line in the file
  57 .IR plan9.ini (8)
  58 of the form
  59 .IB name = value
  60 is passed to the boot program as an environment
  61 variable with the same name and value.
  62 .PP
  63 After
  64 .I boot
  65 passed its execution to
  66 .I bootrc,
  67 it must determine the fileserver to use and a
  68 .I method
  69 with which to connect to it.
  70 Typically
  71 .I device
  72 will name a local disk partition or ethernet interface.
  73 The complete list of methods is given below.
  74 .PP
  75 .I Bootrc
  76 must also set a user name to be used
  77 as the owner of devices and all console
  78 processes and an encryption key to be used
  79 when challenged.
  80 .I Bootrc
  81 will prompt for these.
  82 .PP
  83 Method and device are prompted for first.
  84 The prompt lists all valid methods, with the default in brackets, for example:
  85 .IP
  86 .EX
  87 bootargs is (tcp, il, local!device) [local!/dev/sdC0/fscache]
  88 .EE
  89 .PP
  90 A newline picks the default. Entering
  91 .B !rc
  92 breaks into the
  93 .IR rc (1)
  94 shell.
  95 Other possible responses are
  96 .IR method ,
  97 .IB method ! device
  98 or
  99 .IB method ! device
 100 .IR args .
 101 .PP
 102 The other interactions depend on whether the system
 103 is a
 104 terminal or a CPU server.
 105 .SS Terminal
 106 A terminal must have a
 107 .I username
 108 set.
 109 If not specified with the
 110 .B user=
 111 .IR plan9.ini (8)
 112 parameter,
 113 .I boot
 114 will prompt for one on the console:
 115 .IP
 116 .EX
 117 user:
 118 .EE
 119 .PP
 120 The user will also be prompted for a password to
 121 be used as an encryption key on each
 122 .IR attach (5):
 123 .IP
 124 .EX
 125 password:
 126 .EE
 127 .PP
 128 Once connected,
 129 .I boot
 130 mounts
 131 the root file system before
 132 .B /
 133 and makes the connection available as
 134 .B #s/boot
 135 for subsequent processes to
 136 .B mount
 137 (see
 138 .IR bind (2)).
 139 .I Boot
 140 completes by
 141 .IR exec (2)'ing
 142 .B /$cputype/init
 143 .BR -t .
 144 If the
 145 .B -m
 146 option is given it is also passed as an option to
 147 .IR init .
 148 If the environment variable
 149 .B init
 150 is set (via
 151 .IR plan9.ini (8)),
 152 it is used as an argument to
 153 .IR exec (2)
 154 instead.
 155 .PP
 156 If the
 157 .I bootfs.paq
 158 has been built with the cache file system,
 159 .IR cfs (4),
 160 the local disk partition
 161 .BI /dev/sd XX /cache
 162 (where
 163 .B XX
 164 is a unit specifier)
 165 exists, and the root file system is from a remote server,
 166 then
 167 .I bootrc
 168 will insert a user level cache
 169 process between the remote server and the local namespace
 170 that caches all remote accesses on the local partition.
 171 .SS CPU Servers
 172 The user owning devices and console processes on CPU servers
 173 and that user's domain and encryption key are
 174 read from NVRAM on all machines except PCs.
 175 PCs keep the information in the disk partition
 176 .BI /dev/sd XX /nvram.
 177 .IP
 178 .EX
 179 password:
 180 authid: bootes
 181 authdom: research.bell-labs.com
 182 .EE
 183 .PP
 184 The key is used for mutual authentication of the server and its clients.
 185 The domain and id identify the owner of the key.
 186 .PP
 187 Once connected,
 188 .I boot
 189 behaves as on the terminal except for
 190 .IR exec (2)'ing
 191 .B /$cputype/init
 192 .BR -c .
 193 .SS Booting Methods
 194 The methods available to any system depend on what was
 195 compiled into the kernel.
 196 The complete list of booting methods are listed below.
 197 .TP 8
 198 .BR tcp
 199 connect via Ethernet using the TCP protocol.
 200 The
 201 .I device
 202 and
 203 .I args
 204 are passed to
 205 .IR ipconfig (8)
 206 when configuring the IP stack.
 207 The
 208 .IR plan9.ini (8)
 209 variables
 210 .B fs
 211 and
 212 .BR auth
 213 override the file server and authentication servers
 214 obtained (if any) from DHCP during
 215 .IR ipconfig (8).
 216 .TP 8
 217 .BR il
 218 the same as
 219 .B tcp
 220 but uses the IL protocol to connect to the fileserver.
 221 .TP 8
 222 .BR local
 223 connect to the local file system.
 224 The
 225 .I device
 226 is a disk partition file holding a file system.
 227 .I Bootrc
 228 inspects the disk partition with
 229 .IR fstype (1)
 230 to determine the file system type and starts the
 231 appropriate server with
 232 .IR args .
 233 .RE
 234 .SH EXAMPLES
 235 On PCs, the default arguments to boot are constructed using
 236 the
 237 .B bootargs
 238 variable in
 239 .IR plan9.ini (8).
 240 .PP
 241 Start
 242 .IR cwfs (4)
 243 in config mode:
 244 .IP
 245 .EX
 246 bootargs=local!/dev/sdC0/fscache -c
 247 .EE
 248 .LP
 249 Use an IP stack on an alternate ethernet interface
 250 with a static address and fixed file server and authentication
 251 server addresses.
 252 .IP
 253 .EX
 254 fs=192.168.0.2
 255 auth=192.168.0.3
 256 bootargs=tcp!-g 192.168.0.1 ether /net/ether1 \e
 257     192.168.0.50 255.255.255.0
 258 .EE
 259 .LP
 260 (The
 261 .B bootargs
 262 line is split only for presentation; it is one line in the file.)
 263 .SH FILES
 264 .B #s/boot
 265 .br
 266 .B #//boot/boot
 267 .br
 268 .B #//boot/bootfs.paq
 269 .SH SOURCE
 270 .B /sys/src/9/boot
 271 .SH "SEE ALSO"
 272 .IR root (3),
 273 .IR dhcpd (8),
 274 .IR init (8)
 275 .SH BUGS
 276 The use of
 277 .B bootargs
 278 in general is odd.
 279 .SH HISTORY
 280 .I Boot
 281 first appeared in Plan 9 from Bell Labs. It was rewritten
 282 in
 283 .I rc
 284 for 9front (April, 2011).