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