changelog shortlog tags branches changeset files revisions annotate raw help

Mercurial > hg > plan9front / sys/man/8/boot

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