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)[/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 none is specified with the
 126 .B -u
 127 option,
 128 .I boot
 129 will prompt for one on the console:
 130 .IP
 131 .EX
 132 user:
 133 .EE
 134 .PP
 135 The user will also be prompted for a password to
 136 be used as an encryption key on each
 137 .IR attach (5):
 138 .IP
 139 .EX
 140 password:
 141 .EE
 142 .PP
 143 Once connected,
 144 .I boot
 145 mounts
 146 the root file system before
 147 .B /
 148 and makes the connection available as
 149 .B #s/boot
 150 for subsequent processes to
 151 .B mount
 152 (see
 153 .IR bind (2)).
 154 .I Boot
 155 completes by
 156 .IR exec (2)'ing
 157 .B /$objtype/init
 158 .BR -t .
 159 If the
 160 .B -m
 161 option is given it is also passed as an option to
 162 .IR init .
 163 If the environment variable
 164 .B init
 165 is set (via
 166 .IR plan9.ini (8)),
 167 it is used as an argument to
 168 .IR exec (2)
 169 instead.
 170 .PP
 171 If the
 172 .I bootfs.paq
 173 has been built with the cache file system,
 174 .IR cfs (4),
 175 the local disk partition
 176 .BI /dev/sd XX /cache
 177 (where
 178 .B XX
 179 is a unit specifier)
 180 exists, and the root file system is from a remote server,
 181 then
 182 .I bootrc
 183 will insert a user level cache
 184 process between the remote server and the local namespace
 185 that caches all remote accesses on the local partition.
 186 The
 187 .B -f
 188 flag commands
 189 .IR cfs (4)
 190 to reformat the cache partition.
 191 .SS CPU Servers
 192 The user owning devices and console processes on CPU servers
 193 and that user's domain and encryption key are
 194 read from NVRAM on all machines except PCs.
 195 PCs keep the information in the disk partition
 196 .BI /dev/sd XX /nvram.
 197 If a
 198 .B -k
 199 option is given or if no stored information is found
 200 .I boot
 201 will prompt for all three items and store them.
 202 .IP
 203 .EX
 204 password:
 205 authid: bootes
 206 authdom: research.bell-labs.com
 207 .EE
 208 .PP
 209 The key is used for mutual authentication of the server and its clients.
 210 The domain and id identify the owner of the key.
 211 .PP
 212 Once connected,
 213 .I boot
 214 behaves as on the terminal except for
 215 .IR exec (2)'ing
 216 .B /$objtype/init
 217 .BR -c .
 218 .SS Booting Methods
 219 The methods available to any system depend on what was
 220 compiled into the kernel.
 221 The complete list of booting methods are listed below.
 222 .TP 8
 223 .BR tcp
 224 connect via Ethernet using the TCP protocol.
 225 The
 226 .I args
 227 are passed to
 228 .IR ipconfig (8)
 229 when configuring the IP stack.
 230 The
 231 .IR plan9.ini (8)
 232 variables
 233 .B fs
 234 and
 235 .BR auth
 236 override the file server and authentication server IP addresses
 237 obtained (if any) from DHCP during
 238 .IR ipconfig (8).
 239 .TP 8
 240 .B local
 241 connect to the local file system.
 242 The first argument is a disk holding a file system.
 243 .I Boot
 244 inspects the disk.
 245 .I Boot
 246 will configure the IP stack by passing
 247 .IR args ,
 248 if any, to
 249 .IR ipconfig (8).
 250 .RE
 251 .PP
 252 For the
 253 .B tcp
 254 method,
 255 the address must be a numeric IP address.
 256 If no address is specified,
 257 a file server address will be found from another
 258 system on the network using the BOOTP protocol and
 259 the Plan 9 vendor-specific fields.
 260 .SH EXAMPLES
 261 On PCs, the default arguments to boot are constructed using
 262 the
 263 .B bootargs
 264 variable in
 265 .IR plan9.ini (8).
 266 .PP
 267 Start
 268 .IR cwfs (4)
 269 in config mode:
 270 .IP
 271 .EX
 272 bootargs=local!/dev/sdC0/fscache -c
 273 .EE
 274 .LP
 275 Use an IP stack on an alternate ethernet interface
 276 with a static address and fixed file server and authentication
 277 server addresses.
 278 .IP
 279 .EX
 280 fs=192.168.0.2
 281 auth=192.168.0.3
 282 bootargs=tcp!-g 192.168.0.1 ether /net/ether1 \e
 283     192.168.0.50 255.255.255.0
 284 .EE
 285 .LP
 286 (The
 287 .B bootargs
 288 line is split only for presentation; it is one line in the file.)
 289 .SH FILES
 290 .B #s/boot
 291 .br
 292 .B #//boot/boot
 293 .br
 294 .B #//boot/bootfs.paq
 295 .SH SOURCE
 296 .B /sys/src/9/boot
 297 .SH "SEE ALSO"
 298 .IR root (3),
 299 .IR dhcpd (8),
 300 .IR init (8)
 301 .SH BUGS
 302 The use of
 303 .B bootargs
 304 in general is odd.