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