Commit | Line | Data |
---|---|---|
80fd0e4c KM |
1 | .\" Copyright (c) 1983 Regents of the University of California. |
2 | .\" All rights reserved. The Berkeley software License Agreement | |
3 | .\" specifies the terms and conditions for redistribution. | |
4 | .\" | |
57349e41 | 5 | .\" @(#)4.t 6.2 (Berkeley) %G% |
80fd0e4c | 6 | .\" |
57349e41 MK |
7 | .\".ds RH "Configuration File Syntax |
8 | .ne 2i | |
9 | .NH | |
10 | CONFIGURATION FILE SYNTAX | |
80fd0e4c KM |
11 | .PP |
12 | In this section we consider the specific rules used in writing | |
13 | a configuration file. A complete grammar for the input language | |
14 | can be found in Appendix A and may be of use if you should have | |
15 | problems with syntax errors. | |
16 | .PP | |
17 | A configuration file is broken up into three logical pieces: | |
18 | .IP \(bu 3 | |
19 | configuration parameters global to all system images | |
20 | specified in the configuration file, | |
21 | .IP \(bu 3 | |
22 | parameters specific to each | |
23 | system image to be generated, and | |
24 | .IP \(bu 3 | |
25 | device specifications. | |
26 | .NH 2 | |
27 | Global configuration parameters | |
28 | .PP | |
29 | The global configuration parameters are the type of machine, | |
30 | cpu types, options, timezone, system identifier, and maximum users. | |
31 | Each is specified with a separate line in the configuration file. | |
32 | .IP "\fBmachine\fP \fItype\fP" | |
33 | .br | |
34 | The system is to run on the machine type specified. No more than | |
35 | one machine type can appear in the configuration file. Legal values | |
36 | are | |
37 | .B vax | |
38 | and | |
39 | \fBsun\fP. | |
40 | .IP "\fBcpu\fP ``\fItype\fP''" | |
41 | .br | |
42 | This system is to run on the cpu type specified. | |
43 | More than one cpu type specification | |
44 | can appear in a configuration file. | |
45 | Legal types for a | |
46 | .B vax | |
47 | machine are | |
57349e41 MK |
48 | \fBVAX8600\fP, \fBVAX780\fP, \fBVAX750\fP, |
49 | \fBVAX730\fP | |
80fd0e4c | 50 | and |
57349e41 MK |
51 | \fBVAX630\fP (MicroVAX II). |
52 | The 8650 is listed as an 8600, the 785 as a 780, and a 725 as a 730. | |
80fd0e4c KM |
53 | .IP "\fBoptions\fP \fIoptionlist\fP" |
54 | .br | |
55 | Compile the listed optional code into the system. | |
56 | Options in this list are separated by commas. | |
57 | Possible options are listed at the top of the generic makefile. | |
58 | A line of the form ``options FUNNY,HAHA'' generates global ``#define''s | |
59 | \-DFUNNY \-DHAHA in the resultant makefile. | |
60 | An option may be given a value by following its name with ``\fB=\fP'', | |
57349e41 MK |
61 | then the value enclosed in (double) quotes. |
62 | The following are major options are currently in use: | |
63 | COMPAT (include code for compatibility with 4.1BSD binaries), | |
80fd0e4c | 64 | INET (Internet communication protocols), |
57349e41 | 65 | NS (Xerox NS communication protocols), |
80fd0e4c KM |
66 | and |
67 | QUOTA (enable disk quotas). | |
57349e41 MK |
68 | Other kernel options controlling system sizes and limits |
69 | are listed in Appendix D; | |
70 | options for the network are found in Appendix E. | |
80fd0e4c KM |
71 | There are additional options which are associated with certain |
72 | peripheral devices; those are listed in the Synopsis section | |
73 | of the manual page for the device. | |
57349e41 MK |
74 | .IP "\fBmakeoptions\fP \fIoptionlist\fP" |
75 | .br | |
76 | Options that are used within the system makefile | |
77 | and evaluated by | |
78 | .I make | |
79 | are listed as | |
80 | .IR makeoptions . | |
81 | Options are listed with their values with the form | |
82 | ``makeoptions name=value,name2=value2.'' | |
83 | The values must be enclosed in double quotes if they include numerals | |
84 | or begin with a dash. | |
80fd0e4c KM |
85 | .IP "\fBtimezone\fP \fInumber\fP [ \fBdst\fP [ \fInumber\fP ] ]" |
86 | .br | |
57349e41 | 87 | Specifies the timezone used by the system. This is measured in the |
80fd0e4c KM |
88 | number of hours your timezone is west of GMT. |
89 | EST is 5 hours west of GMT, PST is 8. Negative numbers | |
90 | indicate hours east of GMT. If you specify | |
91 | \fBdst\fP, the system will operate under daylight savings time. | |
92 | An optional integer or floating point number may be included | |
93 | to specify a particular daylight saving time correction algorithm; | |
94 | the default value is 1, indicating the United States. | |
95 | Other values are: 2 (Australian style), 3 (Western European), | |
96 | 4 (Middle European), and 5 (Eastern European). See | |
97 | \fIgettimeofday\fP\|(2) and \fIctime\fP\|(3) for more information. | |
98 | .IP "\fBident\fP \fIname\fP" | |
99 | .br | |
100 | This system is to be known as | |
101 | .IR name . | |
102 | This is usually a cute name like ERNIE (short for Ernie Co-Vax) or | |
103 | VAXWELL (for Vaxwell Smart). | |
57349e41 MK |
104 | This value is defined for use in conditional compilation, |
105 | and is also used to locate an optional list of source files specific | |
106 | to this system. | |
80fd0e4c KM |
107 | .IP "\fBmaxusers\fP \fInumber\fP" |
108 | .br | |
109 | The maximum expected number of simultaneously active user on this system is | |
110 | .IR number . | |
111 | This number is used to size several system data structures. | |
112 | .NH 2 | |
113 | System image parameters | |
114 | .PP | |
115 | Multiple bootable images may be specified in a single configuration | |
116 | file. The systems will have the same global configuration parameters | |
117 | and devices, but the location of the root file system and other | |
118 | system specific devices may be different. A system image is specified | |
119 | with a ``config'' line: | |
120 | .IP | |
121 | \fBconfig\fP\ \fIsysname\fP\ \fIconfig-clauses\fP | |
122 | .LP | |
123 | The | |
124 | .I sysname | |
125 | field is the name given to the loaded system image; almost everyone | |
126 | names their standard system image ``vmunix''. The configuration clauses | |
127 | are one or more specifications indicating where the root file system | |
57349e41 | 128 | is located and the number and location of paging devices. |
80fd0e4c KM |
129 | The device used by the system to process argument lists during |
130 | .IR execve (2) | |
131 | calls may also be specified, though in practice this is almost | |
132 | always selected by | |
133 | .I config | |
134 | using one of its rules for selecting default locations for | |
135 | system devices. | |
136 | .PP | |
137 | A configuration clause is one of the following | |
138 | .IP | |
139 | .nf | |
140 | \fBroot\fP [ \fBon\fP ] \fIroot-device\fP | |
57349e41 | 141 | \fBswap\fP [ \fBon\fP ] \fIswap-device\fP [ \fBand\fP \fIswap-device\fP ] ... |
80fd0e4c KM |
142 | \fBdumps\fP [ \fBon\fP ] \fIdump-device\fP |
143 | \fBargs\fP [ \fBon\fP ] \fIarg-device\fP | |
144 | .LP | |
145 | (the ``on'' is optional.) Multiple configuration clauses | |
146 | are separated by white space; | |
147 | .I config | |
148 | allows specifications to be continued across multiple lines | |
149 | by beginning the continuation line with a tab character. | |
150 | The ``root'' clause specifies where the root file system | |
151 | is located, the ``swap'' clause indicates swapping and paging | |
152 | area(s), the ``dumps'' clause can be used to force system dumps | |
153 | to be taken on a particular device, and the ``args'' clause | |
154 | can be used to specify that argument list processing for | |
155 | .I execve | |
57349e41 | 156 | should be done on a particular device. |
80fd0e4c KM |
157 | .PP |
158 | The device names supplied in the clauses may be fully specified | |
159 | as a device, unit, and file system partition; or underspecified | |
160 | in which case | |
161 | .I config | |
162 | will use builtin rules to select default unit numbers and file | |
163 | system partitions. The defaulting rules are a bit complicated | |
164 | as they are dependent on the overall system configuration. | |
165 | For example, the swap area need not be specified at all if | |
166 | the root device is specified; in this case the swap area is | |
167 | placed in the ``b'' partition of the same disk where the root | |
168 | file system is located. Appendix B contains a complete list | |
169 | of the defaulting rules used in selecting system configuration | |
170 | devices. | |
171 | .PP | |
172 | The device names are translated to the | |
173 | appropriate major and minor device | |
174 | numbers on a per-machine basis. A file, | |
175 | ``/sys/conf/devices.machine'' (where ``machine'' | |
176 | is the machine type specified in the configuration file), | |
177 | is used to map a device name to its major block device number. | |
178 | The minor device number is calculated using the standard | |
179 | disk partitioning rules: on unit 0, partition ``a'' is minor device | |
180 | 0, partition ``b'' is minor device 1, and so on; for units | |
181 | other than 0, add 8 times the unit number to get the minor | |
182 | device. | |
183 | .PP | |
184 | If the default mapping of device name to major/minor device | |
185 | number is incorrect for your configuration, it can be replaced | |
186 | by an explicit specification of the major/minor device. | |
187 | This is done by substituting | |
188 | .IP | |
189 | \fBmajor\fP \fIx\fP \fBminor\fP \fIy\fP | |
190 | .LP | |
191 | where the device name would normally be found. For example, | |
192 | .IP | |
193 | .nf | |
194 | \fBconfig\fP vmunix \fBroot\fP \fBon\fP \fBmajor\fP 99 \fBminor\fP 1 | |
195 | .fi | |
196 | .PP | |
197 | Normally, the areas configured for swap space are sized by the system | |
57349e41 MK |
198 | at boot time. If a non-standard size is to be used for one |
199 | or more swap areas (less than the full partition), | |
200 | this can also be specified. To do this, the | |
80fd0e4c KM |
201 | device name specified for a swap area should have a ``size'' |
202 | specification appended. For example, | |
203 | .IP | |
204 | .nf | |
205 | \fBconfig\fP vmunix \fBroot\fP \fBon\fP hp0 \fBswap\fP \fBon\fP hp0b \fBsize\fP 1200 | |
206 | .fi | |
207 | .LP | |
208 | would force swapping to be done in partition ``b'' of ``hp0'' and | |
209 | the swap partition size would be set to 1200 sectors. A swap area | |
210 | sized larger than the associated disk partition is trimmed to the | |
211 | partition size. | |
212 | .PP | |
213 | To create a generic configuration, only the clause ``swap generic'' | |
214 | should be specified; any extra clauses will cause an error. | |
215 | .NH 2 | |
216 | Device specifications | |
217 | .PP | |
218 | Each device attached to a machine must be specified | |
219 | to | |
220 | .I config | |
221 | so that the system generated will know to probe for it during | |
222 | the autoconfiguration process carried out at boot time. Hardware | |
223 | specified in the configuration need not actually be present on | |
224 | the machine where the generated system is to be run. Only the | |
225 | hardware actually found at boot time will be used by the system. | |
226 | .PP | |
227 | The specification of hardware devices in the configuration file | |
228 | parallels the interconnection hierarchy of the machine to be | |
57349e41 | 229 | configured. On the VAX, this means that a configuration file must |
80fd0e4c | 230 | indicate what MASSBUS and UNIBUS adapters are present, and to |
57349e41 | 231 | which \fInexi\fP they might be connected.* |
80fd0e4c KM |
232 | .FS |
233 | * While VAX-11/750's and VAX-11/730 do not actually have | |
234 | nexi, the system treats them as having | |
235 | .I "simulated nexi" | |
236 | to simplify device configuration. | |
237 | .FE | |
238 | Similarly, devices | |
239 | and controllers must be indicated as possibly being connected | |
240 | to one or more adapters. A device description may provide a | |
241 | complete definition of the possible configuration parameters | |
242 | or it may leave certain parameters undefined and make the system | |
243 | probe for all the possible values. The latter allows a single | |
244 | device configuration list to match many possible physical | |
245 | configurations. For example, a disk may be indicated as present | |
246 | at UNIBUS adapter 0, or at any UNIBUS adapter which the system | |
247 | locates at boot time. The latter scheme, termed | |
248 | .IR wildcarding , | |
249 | allows more flexibility in the physical configuration of a system; | |
250 | if a disk must be moved around for some reason, the system will | |
251 | still locate it at the alternate location. | |
252 | .PP | |
253 | A device specification takes one of the following forms: | |
254 | .IP | |
255 | .nf | |
256 | \fBmaster\fP \fIdevice-name\fP \fIdevice-info\fP | |
257 | \fBcontroller\fP \fIdevice-name\fP \fIdevice-info\fP [ \fIinterrupt-spec\fP ] | |
258 | \fBdevice\fP \fIdevice-name\fP \fIdevice-info\fP \fIinterrupt-spec\fP | |
259 | \fBdisk\fP \fIdevice-name\fP \fIdevice-info\fP | |
260 | \fBtape\fP \fIdevice-name\fP \fIdevice-info\fP | |
261 | .fi | |
262 | .LP | |
263 | A ``master'' is a MASSBUS tape controller; a ``controller'' is a | |
264 | disk controller, a UNIBUS tape controller, a MASSBUS adapter, or | |
265 | a UNIBUS adapter. A ``device'' is an autonomous device which | |
266 | connects directly to a UNIBUS adapter (as opposed to something | |
267 | like a disk which connects through a disk controller). ``Disk'' | |
268 | and ``tape'' identify disk drives and tape drives connected to | |
57349e41 | 269 | a ``controller'' or ``master.'' |
80fd0e4c KM |
270 | .PP |
271 | The | |
272 | .I device-name | |
273 | is one of the standard device names, as | |
274 | indicated in section 4 of the UNIX Programmers Manual, | |
275 | concatenated with the | |
276 | .I logical | |
277 | unit number to be assigned the device (the | |
278 | .I logical | |
279 | unit number may be different than the | |
280 | .I physical | |
281 | unit number indicated on the front of something | |
282 | like a disk; the | |
283 | .I logical | |
284 | unit number is used to refer to the UNIX device, not | |
285 | the physical unit number). For example, ``hp0'' is logical | |
286 | unit 0 of a MASSBUS storage device, even though it might | |
287 | be physical unit 3 on MASSBUS adapter 1. | |
288 | .PP | |
289 | The | |
290 | .I device-info | |
291 | clause specifies how the hardware is | |
292 | connected in the interconnection hierarchy. On the VAX, | |
293 | UNIBUS and MASSBUS adapters are connected to the internal | |
294 | system bus through | |
295 | a \fInexus\fP. | |
296 | Thus, one of the following | |
297 | specifications would be used: | |
298 | .IP | |
299 | .ta 1.5i 2.5i 4.0i | |
300 | .nf | |
301 | \fBcontroller\fP mba0 \fBat\fP \fBnexus\fP \fIx\fP | |
302 | \fBcontroller\fP uba0 \fBat\fP \fBnexus\fP \fIx\fP | |
303 | .fi | |
304 | .LP | |
305 | To tie a controller to a specific nexus, ``x'' would be supplied | |
306 | as the number of that nexus; otherwise ``x'' may be specified as | |
307 | ``?'', in which | |
308 | case the system will probe all nexi present looking | |
309 | for the specified controller. | |
310 | .PP | |
311 | The remaining interconnections on the VAX are: | |
312 | .IP \(bu 3 | |
313 | a controller | |
314 | may be connected to another controller (e.g. a disk controller attached | |
315 | to a UNIBUS adapter), | |
316 | .IP \(bu 3 | |
57349e41 | 317 | a master is always attached to a controller (a MASSBUS adapter), |
80fd0e4c KM |
318 | .IP \(bu 3 |
319 | a tape is always attached to a master (for MASSBUS | |
320 | tape drives), | |
321 | .IP \(bu 3 | |
322 | a disk is always attached to a controller, and | |
323 | .IP \(bu 3 | |
324 | devices | |
325 | are always attached to controllers (e.g. UNIBUS controllers attached | |
326 | to UNIBUS adapters). | |
327 | .LP | |
328 | The following lines give an example of each of these interconnections: | |
329 | .IP | |
330 | .ta 1.5i 2.5i 4.0i | |
331 | .nf | |
332 | \fBcontroller\fP hk0 \fBat\fP uba0 ... | |
333 | \fBmaster\fP ht0 \fBat\fP mba0 ... | |
57349e41 | 334 | \fBdisk\fP hp0 \fBat\fP mba0 ... |
80fd0e4c KM |
335 | \fBtape\fP tu0 \fBat\fP ht0 ... |
336 | \fBdisk\fP rk1 \fBat\fP hk0 ... | |
337 | \fBdevice\fP dz0 \fBat\fP uba0 ... | |
338 | .fi | |
339 | .LP | |
340 | Any piece of hardware which may be connected to a specific | |
341 | controller may also be wildcarded across multiple controllers. | |
342 | .PP | |
343 | The final piece of information needed by the system to configure | |
344 | devices is some indication of where or how a device will interrupt. | |
345 | For tapes and disks, simply specifying the \fIslave\fP or \fIdrive\fP | |
346 | number is sufficient to locate the control status register for the | |
57349e41 MK |
347 | device. |
348 | \fIDrive\fP numbers may be wildcarded | |
349 | on MASSBUS devices, but not on disks on a UNIBUS controller. | |
350 | For controllers, the control status register must be | |
351 | given explicitly, as well the number of interrupt vectors used and | |
80fd0e4c KM |
352 | the names of the routines to which they should be bound. |
353 | Thus the example lines given above might be completed as: | |
354 | .IP | |
355 | .ta 1.5i 2.5i 4.0i | |
356 | .nf | |
357 | \fBcontroller\fP hk0 \fBat\fP uba0 \fBcsr\fP 0177440 \fBvector\fP rkintr | |
358 | \fBmaster\fP ht0 \fBat\fP mba0 \fBdrive\fP 0 | |
57349e41 | 359 | \fBdisk\fP hp0 \fBat\fP mba0 \fBdrive\fP ? |
80fd0e4c KM |
360 | \fBtape\fP tu0 \fBat\fP ht0 \fBslave\fP 0 |
361 | \fBdisk\fP rk1 \fBat\fP hk0 \fBdrive\fP 1 | |
362 | \fBdevice\fP dz0 \fBat\fP uba0 \fBcsr\fP 0160100 \fBvector\fP dzrint dzxint | |
363 | .fi | |
364 | .PP | |
365 | Certain device drivers require extra information passed to them | |
366 | at boot time to tailor their operation to the actual hardware present. | |
367 | The line printer driver, for example, needs to know how many columns | |
368 | are present on each non-standard line printer (i.e. a line printer | |
369 | with other than 80 columns). The drivers for the terminal multiplexors | |
370 | need to know which lines are attached to modem lines so that no one will | |
371 | be allowed to use them unless a connection is present. For this reason, | |
372 | one last parameter may be specified to a | |
373 | .IR device , | |
374 | a | |
375 | .I flags | |
376 | field. It has the syntax | |
377 | .IP | |
378 | \fBflags\fP \fInumber\fP | |
379 | .LP | |
380 | and is usually placed after the | |
381 | .I csr | |
382 | specification. The | |
383 | .I number | |
384 | is passed directly to the associated driver. The manual pages | |
385 | in section 4 should be consulted to determine how each driver | |
386 | uses this value (if at all). | |
387 | Communications interface drivers commonly use the flags | |
388 | to indicate whether modem control signals are in use. | |
389 | .PP | |
390 | The exact syntax for each specific device is given in the Synopsis | |
391 | section of its manual page in section 4 of the manual. | |
392 | .NH 2 | |
393 | Pseudo-devices | |
394 | .PP | |
395 | A number of drivers and software subsystems | |
396 | are treated like device drivers without any associated hardware. | |
397 | To include any of these pieces, a ``pseudo-device'' specification | |
398 | must be used. A specification for a pseudo device takes the form | |
399 | .IP | |
400 | .DT | |
401 | .nf | |
402 | \fBpseudo-device\fP \fIdevice-name\fP [ \fIhowmany\fP ] | |
403 | .fi | |
404 | .PP | |
57349e41 | 405 | Examples of pseudo devices are |
80fd0e4c KM |
406 | \fBpty\fP, the pseudo terminal driver (where the optional |
407 | .I howmany | |
408 | value indicates the number of pseudo terminals to configure, 32 default), | |
57349e41 MK |
409 | and \fBloop\fP, the software loopback network pseudo-interface. |
410 | Other pseudo devices for the network include | |
411 | \fBimp\fP (required when a CSS or ACC imp is configured) | |
80fd0e4c | 412 | and \fBether\fP (used by the Address Resolution Protocol |
57349e41 | 413 | on 10 Mb/sec Ethernets). |
80fd0e4c KM |
414 | More information on configuring each of these can also be found |
415 | in section 4 of the manual. |