boot 8.2 KB

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