boot 8.4 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415
  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. .IP
  313. .I Fossil
  314. is invoked as
  315. .RS
  316. .IP
  317. .EX
  318. /boot/fossil -f \fIpartition\fP -c 'srv -A fboot' -c 'srv -p fscons'
  319. .EE
  320. .RE
  321. .IP
  322. and
  323. .I boot
  324. then renames
  325. .L /srv/fboot
  326. to
  327. .LR /srv/boot ,
  328. so
  329. .B fossil.conf
  330. should not use the
  331. .B srv
  332. command to create
  333. .LR fboot ,
  334. .LR boot ,
  335. nor
  336. .LR fscons .
  337. .IP
  338. If the disk is not a
  339. .IR fossil (4)
  340. partition,
  341. .I boot
  342. invokes
  343. .BR /boot/kfs .
  344. A variety of programs, like
  345. .I 9660srv
  346. and
  347. .IR dossrv (4)
  348. masquerade as
  349. .I kfs
  350. to allow booting from alternate media formats,
  351. so as long as the disk is not a
  352. .I fossil
  353. disk, no check is made that the disk is in fact
  354. a
  355. .I kfs
  356. disk.
  357. The args are passed to
  358. .IR kfs (4).
  359. .IP
  360. For the
  361. .B tcp
  362. method,
  363. the address must be a numeric IP address.
  364. If no address is specified,
  365. a file server address will be found from another
  366. system on the network using the BOOTP protocol and
  367. the Plan 9 vendor-specific fields.
  368. .SH EXAMPLES
  369. On PCs, the default arguments to boot are constructed using
  370. the
  371. .B bootargs
  372. variable in
  373. .IR plan9.ini (8).
  374. .PP
  375. Start
  376. .IR kfs (4)
  377. with extra disk buffers:
  378. .IP
  379. .EX
  380. bootargs=local!#S/sdC0/fs -B 4096
  381. .EE
  382. .LP
  383. Use an IP stack on an alternate ethernet interface
  384. with a static address and fixed file server and authentication
  385. server addresses.
  386. .IP
  387. .EX
  388. fs=192.168.0.2
  389. auth=192.168.0.3
  390. bootargs=tcp -g 192.168.0.1 ether /net/ether1 \e
  391. 192.168.0.50 255.255.255.0
  392. .EE
  393. .LP
  394. (The
  395. .B bootargs
  396. line is split only for presentation; it is one line in the file.)
  397. .SH FILES
  398. .B #s/boot
  399. .br
  400. .B #//boot/boot
  401. .SH SOURCE
  402. .B /sys/src/9/boot
  403. .SH "SEE ALSO"
  404. .IR root (3),
  405. .IR factotum (4),
  406. .IR dhcpd (8),
  407. .IR init (8)
  408. .SH BUGS
  409. The use of
  410. .B bootargs
  411. in general is odd.
  412. The configuration specification
  413. for fossil and venti servers
  414. is particularly odd, but it does
  415. cover the common cases well.