sys/man/8/boot

   1 .TH BOOT 8
   2 .SH NAME
   3 boot \- 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.
  21 It connects to the file server that will serve the
  22 root, performs any authentication needed to
  23 connect to that server, and
  24 .IR exec (2)'s
  25 the
  26 .IR init (8)
  27 program.
  28 It is started by the kernel, never run directly by the user.  See
  29 .IR booting (8)
  30 for information about the process of loading the kernel (and
  31 .IR boot )
  32 into memory.
  33 .PP
  34 Once loaded, the kernel initializes its data structures and devices.
  35 It sets the two environment variables
  36 .B /env/cputype
  37 and
  38 .B /env/terminal
  39 to describe the processor.
  40 It then binds a place-holder file server,
  41 .IR root (3),
  42 onto
  43 .B /
  44 and crafts an initial process whose sole function is to
  45 .IR exec (2)
  46 .BR /boot/boot ,
  47 a binary which is compiled into
  48 .IR root (3).
  49 .PP
  50 The command line passed depends
  51 on the information passed from boot ROM
  52 to kernel.
  53 Machines that boot directly from ROM (that is, most machines other than PCs)
  54 pass the boot line given to the ROM directly to
  55 .IR boot .
  56 .PP
  57 On the PC, each line in the DOS file
  58 .B plan9.ini
  59 of the form
  60 .IB name = value
  61 is passed to the boot program as an environment
  62 variable with the same name and value.
  63 The command line is
  64 .IP
  65 .B /386/9dos
  66 .IB method ! server
  67 .PP
  68 (The first argument is ignored by
  69 .IR boot .)
  70 .I Boot
  71 must determine the file
  72 .I server
  73 to use
  74 and a
  75 .I method
  76 with which to connect to it.
  77 Typically this will name a file server on the network,
  78 or state that the root file system is on local disk and name the partition.
  79 The complete list of methods is given below.
  80 .PP
  81 .I Boot
  82 must also set a user name to be used
  83 as the owner of devices and all console
  84 processes and an encryption key to be used
  85 when challenged.
  86 .I Boot
  87 will prompt for these.
  88 .PP
  89 Method and address are prompted for first.
  90 The prompt lists all valid methods, with the default in brackets, for example:
  91 .IP
  92 .EX
  93 root is from (tcp, local!#S/sdC0/fs)[tcp]:
  94 .EE
  95 .PP
  96 A newline picks the default.
  97 Other possible responses are
  98 .I method
  99 or
 100 .IB method ! address\f1.
 101 To aid in automatic reboot, the default is automatically
 102 taken on CPU servers if nothing is typed within 15 seconds.
 103 .PP
 104 The other interactions depend on whether the system
 105 is a
 106 terminal or a CPU server.
 107 .SS Terminal
 108 The terminal must have a
 109 .I username
 110 to set.
 111 If none is specified with the
 112 .B -u
 113 option,
 114 .I boot
 115 will prompt for one on the console:
 116 .IP
 117 .EX
 118 user:
 119 .EE
 120 .PP
 121 The user will also be prompted for a password to
 122 be used as an encryption key on each
 123 .IR attach (5):
 124 .IP
 125 .EX
 126 password:
 127 .EE
 128 .PP
 129 With most
 130 .I methods
 131 .I boot
 132 can now connect to the file server.
 133 However, with the serial line
 134 .I methods
 135 .B 9600
 136 and
 137 .BR 19200 ,
 138 the actual mechanics of setting up the complete connection
 139 are too varied to put into the boot program.
 140 Instead
 141 .I boot
 142 lets the user set up the connection.
 143 It prints a prompt on the console and then simulates
 144 a dumb terminal between the user and the serial line:
 145 .IP
 146 .EX
 147 Connect to file system now, type ctrl-d when done.
 148 (Use the view or down arrow key to send a break)
 149 .EE
 150 .PP
 151 The user can now type at the modem to
 152 dial the number.  What is typed depends on
 153 the modem and is beyond this discussion.
 154 .PP
 155 When the user types a control-D,
 156 .I boot
 157 stops simulating a terminal and starts the file
 158 system protocol over the serial line.
 159 .PP
 160 Once connected,
 161 .I boot
 162 mounts
 163 the root file system before
 164 .B /
 165 and makes the connection available as
 166 .B #s/boot
 167 for subsequent processes to
 168 .B mount
 169 (see
 170 .IR bind (2)).
 171 .I Boot
 172 completes by
 173 .IR exec (2)'ing
 174 .B /$objtype/init
 175 .BR -t .
 176 If the
 177 .B -m
 178 option is given it is also passed as an option to
 179 .IR init .
 180 If the environment variable
 181 .B init
 182 is set (via
 183 .IR plan9.ini (8)),
 184 it is used as a command line to exec instead.
 185 .PP
 186 If the kernel has been built with the cache file system,
 187 .IR cfs (4),
 188 the local disk partition
 189 .BI /dev/sd XX /cache
 190 (where
 191 .B XX
 192 is a unit specifier)
 193 exists, and the root file system is from a remote server,
 194 then the kernel will insert a user level cache
 195 process between the remote server and the local namespace
 196 that caches all remote accesses on the local partition.
 197 The
 198 .B -f
 199 flag commands
 200 .B cfs
 201 to reformat the cache partition.
 202 .SS CPU Servers
 203 The user owning devices and console processes on CPU servers
 204 and that user's domain and encryption key are
 205 read from NVRAM on all machines except PC's.
 206 PC's keep the information in the disk partition
 207 .BI /dev/sd XX /nvram\f1.
 208 If a
 209 .B -k
 210 option is given or if no stored information is found
 211 .I boot
 212 will prompt for all three items and store them.
 213 .IP
 214 .EX
 215 password:
 216 authid: bootes
 217 authdom: research.bell-labs.com
 218 .EE
 219 .PP
 220 The key is used for mutual authentication of the server and its clients.
 221 The domain and id identify the owner of the key.
 222 .PP
 223 Once connected,
 224 .I boot
 225 behaves as on the terminal except for
 226 .IR exec (2)'ing
 227 .B /$objtype/init
 228 .BR -c .
 229 .SS Booting Methods
 230 The methods available to any system depend on what was
 231 compiled into the kernel.
 232 The complete list of booting methods are listed below.
 233 .TP 8
 234 .BR tcp
 235 connect via Ethernet using the TCP protocol.
 236 The
 237 .I args
 238 are passed to
 239 .IR ipconfig (8)
 240 when configuring the IP stack.
 241 The
 242 .IR plan9.ini (8)
 243 variables
 244 .B fs
 245 and
 246 .B auth
 247 override the file server and authentication server IP addresses
 248 obtained (if any) from DHCP during
 249 .IR ipconfig (8).
 250 .TP 8
 251 .B local
 252 connect to the local file system.
 253 The first argument is a disk holding a file system.
 254 .I Boot
 255 inspects the disk.
 256 If the disk is a
 257 .IR fossil (4)
 258 file system, it invokes
 259 .B /boot/fossil
 260 to serve it.
 261 If the
 262 .B venti
 263 environment variable (really,
 264 .IR plan9.ini (8)
 265 variable) is set,
 266 .I boot
 267 first arranges for fossil to be able to
 268 contact the named
 269 .IR venti (8)
 270 server.
 271 The variable's value can take the following forms:
 272 .RS
 273 .TP
 274 .B /dev/sdC0/arenas
 275 the file should be a venti partition with a configuration
 276 stored on it using
 277 .I venti/conf
 278 (see
 279 .IR venti-fmt (8)).
 280 .I Boot
 281 will start a loopback IP interface on 127.0.0.1
 282 and start
 283 .I venti
 284 announcing on
 285 .B tcp!127.1!17034
 286 for venti service
 287 and
 288 .B tcp!127.1!8000
 289 for web service,
 290 using the configuration stored in that partition.
 291 .TP
 292 .B /dev/sdC0/arenas tcp!*!17034
 293 same as the last but specify an alternate venti service address.
 294 In this example, using
 295 .B *
 296 will announce on all available IP interfaces (even ones configured later)
 297 rather than just the loopback device.
 298 The loopback interface is still configured.
 299 .TP
 300 .B /dev/sdC0/arenas tcp!*!17034 tcp!*!80
 301 same as the last but specify alternate venti service and web addresses.
 302 The loopback interface is still configured.
 303 .TP
 304 .B tcp!135.104.9.2!17034 \fR[ \fIargs\fR ]
 305 the network address of a venti server running on a separate machine.
 306 .I Boot
 307 will configure the IP stack by passing
 308 .IR args ,
 309 if any, to
 310 .IR ipconfig (8).
 311 .RE
 312 .PP
 313 If the disk is not a
 314 .IR fossil (4)
 315 partition,
 316 .I boot
 317 invokes
 318 .BR /boot/kfs .
 319 A variety of programs, like
 320 .I 9660srv
 321 and
 322 .IR dossrv (4)
 323 masquerade as
 324 .I kfs
 325 to allow booting from alternate media formats,
 326 so as long as the disk is not a
 327 .I fossil
 328 disk, no check is made that the disk is in fact
 329 a
 330 .I kfs
 331 disk.
 332 The args are passed to
 333 .IR kfs (4).
 334 .PP
 335 For the
 336 .B tcp
 337 method,
 338 the address must be a numeric IP address.
 339 If no address is specified,
 340 a file server address will be found from another
 341 system on the network using the BOOTP protocol and
 342 the Plan 9 vendor-specific fields.
 343 .SH EXAMPLES
 344 On PCs, the default arguments to boot are constructed using
 345 the
 346 .B bootargs
 347 variable in
 348 .IR plan9.ini (8).
 349 .PP
 350 Start
 351 .IR kfs (4)
 352 with extra disk buffers:
 353 .IP
 354 .EX
 355 bootargs=local!#S/sdC0/fs -B 4096
 356 .EE
 357 .LP
 358 Use an IP stack on an alternate ethernet interface
 359 with a static address and fixed file server and authentication
 360 server addresses.
 361 .IP
 362 .EX
 363 fs=192.168.0.2
 364 auth=192.168.0.3
 365 bootargs=tcp -g 192.168.0.1 ether /net/ether1 \e
 366     192.168.0.50 255.255.255.0
 367 .EE
 368 .LP
 369 (The
 370 .B bootargs
 371 line is split only for presentation; it is one line in the file.)
 372 .SH FILES
 373 .B #s/boot
 374 .br
 375 .B #//boot/boot
 376 .SH SOURCE
 377 .B /sys/src/9/boot
 378 .SH "SEE ALSO"
 379 .IR root (3),
 380 .IR dhcpd (8),
 381 .IR init (8)
 382 .SH BUGS
 383 The use of
 384 .B bootargs
 385 in general is odd.
 386 The configuration specification
 387 for fossil and venti servers
 388 is particularly odd, but it does
 389 cover the common cases well.