3 plan9.ini \- configuration file for PCs
7 When booting Plan 9 on a PC, the DOS program
10 containing configuration information from the boot disk.
13 looks like a shell script containing lines of the form
19 each of which defines a kernel or device parameter.
26 comments are ignored, but are only recognised if
28 appears at the start of a line.
30 For devices, the generic format of
35 type=TYPE [port=N] [irq=N] [mem=N] [size=N] [dma=N] [ea=N]
38 specifying the controller type,
39 the base I/O port of the interface, its interrupt
40 level, the physical starting address of any mapped memory,
41 the length in bytes of that memory, the DMA channel,
42 and for Ethernets an override of the physical network address.
43 Not all elements are relevant to all devices; the relevant values
44 and their defaults are defined below in the description of each device.
48 and the kernel to configure the hardware available.
49 The information it contains is also passed to the boot
50 process, and subsequently other programs,
51 as environment variables
54 However, values whose names begin with an asterisk
56 are used by the kernel and are not converted into environment variables.
58 The following sections describe how variables are used.
60 .SS \fLetherX=value\fP
61 This defines an Ethernet interface.
63 a unique monotonically increasing number beginning at 0,
64 identifies an Ethernet card to be probed at system boot.
65 Probing stops when a card is found or there is no line for
67 After probing as directed by the
69 lines, any remaining Ethernet cards that can be automatically
71 Almost all cards can be automatically detected.
72 For debugging purposes, automatic probing can
73 be disabled by specifying the line
75 This automatic probing is only done by the kernel, not by
77 Thus, if you want to load a kernel over the Ethernet, you need
82 can find the Ethernet card, even if the kernel would
83 have automatically detected it.
85 Some cards are software configurable and do not require all options.
86 Unspecified options default to the factory defaults.
96 The Intel 8254X Gigabit Ethernet controllers,
97 as found on the Intel PRO/1000 adapters for copper (not fiber).
98 Completely configurable.
101 The Intel 8256[36], 8257[12], and 82573[ev] Gigabit Ethernet
102 PCI-Express controllers.
103 Completely configurable.
106 The Realtek 8169 Gigabit Ethernet controller.
107 Completely configurable.
110 Netgear GA620 and GA620T Gigabit Ethernet cards,
111 and other cards using the Alteon Acenic chip such as the
112 Alteon Acenic fiber and copper cards,
113 the DEC DEGPA-SA and the SGI Acenic.
114 Completely configurable.
117 National Semiconductor DP83820-based Gigabit Ethernet adapters, notably
119 Completely configurable.
122 The VIA Velocity Gigabit Ethernet controller.
123 Known to drive the VIA8237 (ABIT AV8), but at 100Mb/s full-duplex only.
126 The Myricom 10-Gigabit Ethernet 10G-PCIE-8A controller.
127 Completely configurable.
128 Can't boot through these due to enormous firmware loads.
131 The Intel 8259[89] 10-Gigabit Ethernet PCI-Express controllers.
132 Completely configurable.
133 Can't boot through these due to lack of a
138 Cards using the Intel 8255[789] Fast Ethernet PCI Bus LAN Controller such as the
139 Intel EtherExpress PRO/100B.
140 Completely configurable, no options need be given.
141 If you need to force the media, specify
142 one of the options (no value)
153 Completely configurable.
156 Cards using the Digital Equipment (now Intel) 2114x PCI Fast Ethernet Adapter Controller,
157 for example the Netgear FA310.
158 Completely configurable, no options need be given.
159 Media can be specified the same was as for the
165 near-clone chips may also work.
168 National Semiconductor DP83815-based adapters, notably
169 the Netgear FA311, Netgear FA312, and various SiS built-in
170 controllers such as the SiS900.
171 On the SiS controllers, the Ethernet address is not detected properly;
175 Completely configurable.
178 The Realtek 8139 Fast Ethernet controller.
179 Completely configurable.
182 The VIA VT6102 Fast Ethernet Controller (Rhine II).
185 SMC 91cXX chip-based PCMCIA adapters, notably the SMC EtherEZ card.
188 The 3COM Etherlink III series of cards including the 5x9, 59x, and 905 and 905B.
189 Completely configurable, no options need be given.
190 The media may be specified by setting
200 If you need to force full duplex, because for example the Ethernet switch does not negotiate correctly,
201 just name the word (no value)
205 Similarly, to force 100Mbit operation, specify
207 Port 0x110 is used for the little ISA configuration dance.
210 The 3COM 3C589 series PCMCIA cards, including the
212 There is no support for the modem on the 3C562.
213 Completely configurable, no options need be given.
218 The media may be specified as
224 The Linksys Combo PCMCIA EthernetCard (EC2T),
225 EtherFast 10/100 PCMCIA cards (PCMPC100) and integrated controllers (PCM100),
226 the Netgear FA410TX 10/100 PCMCIA card
227 and the Accton EtherPair-PCMCIA (EN2216).
228 Completely configurable, no options need be given.
233 These cards are NE2000 clones.
234 Other NE2000 compatible PCMCIA cards may be tried
241 is a unique identifier string contained in the attribute
242 memory of the card (see
244 unlike most options in
246 this string is case-sensitive.
249 can be used to turn off (0) or on (1) a dummy remote read in the driver
251 depending on how NE2000 compatible they are.
254 Not software configurable iff ISA;
255 PCI clones or supersets are software configurable;
256 includes the Realtek 8029 clone used by Parallels.
260 port=0x300 irq=2 mem=0x04000 size=0x4000
262 The option (no value)
264 is needed on some (near) clones to turn off a dummy remote read in the driver.
267 The AMD PCnet PCI Ethernet Adapter (AM79C970).
268 (This is the Ethernet adapter used by VMware.)
269 Completely configurable, no options need be given.
272 Includes WD8013 and SMC Elite and Elite Ultra cards. There are varying degrees
273 of software configurability. Cards may be in either 8-bit or 16-bit slots.
276 port=0x280 irq=3 mem=0xD0000 size=0x2000
278 BUG: On many machines only the 16 bit card works.
283 for Ethernet packets \(em the interface discards sent
284 packets and never receives any.
285 This is used to provide a test bed for
286 some experimental Ethernet bridging software.
289 Lucent Wavelan (Orinoco) IEEE 802.11b
290 and compatible PCMCIA cards.
291 Compatible cards include the Dell TrueMobile 1150
292 and the Linksys Instant Wireless Network PC Card.
293 Port and IRQ defaults are 0x180 and 3 respectively.
295 These cards take a number of unique options to aid in
296 identifying the card correctly on the 802.11b network.
301 (i.e. use an access point):
303 mode=[adhoc, managed]
307 The 802.11b network to attach to
317 and defaults to a null string.
318 The card station name is given by
324 The channel to use is given by
330 lies in the range 1 to 16 inclusive;
331 the channel is normally negotiated automatically.
333 If the card is capable of encryption,
334 the following options may be used:
343 sets the encryption key
347 is in the range 1 to 4 inclusive) to
349 this will also set the transmit key to
352 There are two formats for
354 which depend on the length of the string.
355 If it is exactly 5 or 13 characters long it is assumed
356 to be an alphanumeric key; if it is exactly 10 or 26 characters
357 long the key is assumed to be in hex format (without a leading
359 The lengths are checked,
360 as is the format of a hex key.
364 sets the transmit key to use to be
366 in the range 1 to 4 inclusive.
367 If it is desired to exclude or include unencrypted packets
371 configures reception and defaults to inclusion.
373 The defaults are intended to match the common case of
374 a managed network with encryption and a typical entry would
375 only require, for example
377 essid=left-armpit key1=afish key2=calledraawaru
379 if the port and IRQ defaults are used.
380 These options may be set after boot by writing to the device's
382 file using a space as the separator between option and value, e.g.
384 echo 'key2 1d8f65c9a52d83c8e4b43f94af' >/net/ether0/0/ctl
387 Card-specific power management may be enabled/disabled by
393 PCI Ethernet adapters that use the same Wavelan
394 programming interface.
395 Currently the only tested cards are those based on the
396 Intersil Prism 2.5 chipset.
399 (S)ATA controllers are autodetected.
400 .SS \fLusbX=type=uhci\fP
401 .SS \fLusbX=type=ohci\fP
402 This specifies the settings for a USB UHCI or OHCI controller.
403 Like the Ethernet controllers, USB controllers are autodetected
404 after scanning for the ones listed in
406 Thus, most systems will not need a
409 Also like the Ethernet controllers, USB autoprobing can be
410 disabled by specifying the line
412 .SS \fLscsiX=value\fP
413 This defines a SCSI interface which cannot be automatically detected
421 Adaptec 154x series of controllers (and clones).
422 Almost completely configurable, only the
426 option need be given.
428 NCR/Symbios/LSI-Logic 53c8xx-based adapters
429 and Mylex MultiMaster (Buslogic BT-*) adapters are
430 automatically detected and need no entries.
432 By default, the NCR 53c8xx driver searches for up to 32 controllers.
433 This can be changed by setting the variable
436 By default the Mylex driver resets SCSI cards by using
437 both the hard reset and SCSI bus reset flags in the driver interface.
440 is defined, the SCSI bus reset flag is omitted.
441 .SS \fLaoeif=\fP\fIlist\fP
442 This specifies a space-separated
444 of Ethernet interfaces to be bound at boot to the ATA-over-Ethernet driver,
447 .LR "aoeif=ether0 ether1" .
448 Only interfaces on this list will initially be accessible via AoE.
449 .SS \fLaoedev=e!#æ/aoe/\fIshelf\fL.\fIslot\fR
450 This specifies an ATA-over-Ethernet device accessible via the interfaces
457 to use as a root device for bootstrapping.
459 .SS \fLaudioX=value\fP
460 This defines a sound interface.
470 A Sound Blaster clone.
472 The DMA channel may be any of 5, 6, or 7.
476 port=0x220 irq=7 dma=5
479 Plan 9 automatically configures COM1 and COM2, if found,
487 These devices can be disabled by adding a line:
493 This is typically done in order to reuse the IRQ for
496 Plan 9 used to support various serial concentrators,
497 including the TTC 8 serial line card and various models
498 in the Star Gate Avanstar series of intelligent serial boards.
499 These are no longer supported; the much simpler
500 Perle PCI-Fast4, PCI-Fast8, and PCI-Fast16 controllers
501 have taken their places.
502 These latter cards are automatically detected
503 and need no configuration lines.
507 can be used to specify settings for a PCMCIA modem.
508 .SS \fLmouseport=value\fP
509 This specifies where the mouse is attached.
514 the PS2 mouse/keyboard port. The BIOS setup procedure
515 should be used to configure the machine appropriately.
518 an Intellimouse on the PS2 port.
525 .SS \fLmodemport=value\fP
526 Picks the UART line to call out on.
527 This is used when connecting to a file server over
530 is the number of the port.
531 .SS \fLconsole=value params\fP
532 This is used to specify the console device.
545 A serial console is initially configured with the
552 specifying 9600 baud,
553 8 bit bytes, no parity, and one stop bit.
556 is given, it will be used to further
558 Notice that there is no
569 would use COM1 at 19,200 baud
572 .SS \fLpccard0=disabled\fP
573 Disable probing for and automatic configuration of PC card controllers.
574 .SS \fLpcmciaX=type=XXX irq=value\fP
575 If the default IRQ for the
577 is correct, this entry can be omitted. The value of
580 .SS \fLpcmcia0=disabled\fP
581 Disable probing for and automatic configuration of PCMCIA controllers.
583 .SS \fLbootfile=value\fP
584 This is used to direct the actions of
586 by naming the device and file from which to load the kernel.
587 .SS \fLrootdir=dir\fP
588 .SS \fLrootspec=spec\fP
591 to identify the directory
593 to make the root directory for the kernel, and the
594 file system specifier
600 on which it can be found.
601 These are usually used to test variant file systems for distributions, etc.
602 .SS \fLbootargs=value\fP
603 The value of this variable is passed to
605 by the kernel as the name of the root file system.
606 It is typically used to specify additional arguments to
611 For example, if the system is to run from a local
613 partition, the definition might read
614 .BR bootargs=local!#S/sdC0/fs .
618 .SS \fLnobootprompt=value\fP
623 as the answer instead.
629 as the answer instead.
630 .SS \fLdebugfactotum=\fP
637 option, so that it can be debugged.
638 .SS \fLfactotumopts=options\fP
645 which must be a single word (i.e., contain no whitespace).
646 .SS \fLventi=value\fP
647 When booting from a local fossil server backed by a local
648 or remote venti server,
649 this variable specifies how to establish the connection to the
655 This gives the name of the file holding the disk partition
656 for the cache file system,
660 example, one would write
661 .BR cfs=#S/sdC0/cache .
662 .SS \fLbootdisk=value\fP
663 This deprecated variable was used to specify the disk used by
664 the cache file system and other disk-resident services.
669 .SS \fLpartition=value\fP
670 This defines the partition table
672 will examine to find disk partitioning information.
673 By default, a partition table in a Plan 9 partition
674 is consulted; if no such table is found, an old-Plan 9
675 partition table on the next-to-last or last sector
676 of the disk is consulted.
679 consults only the first table,
683 .SS \fLauth=a.b.c.d\fP
684 These specify the IP address of the file and authentication server
685 to use when mounting a network-provided root file system.
686 They are used only if the addresses cannot be determined via DHCP.
688 .SS \fL*norealmode=\fP
689 The PC kernel switches the processor to 16-bit real mode
690 to run BIOS interrupts, for example to find the memory map or to enable VESA.
691 This variable disables such switches.
692 .SS \fL*noe820scan=\fP
693 When available, the PC kernel uses the BIOS E820 memory map
694 to size memory. This variable disables the scan.
695 .SS \fL*maxmem=value\fP
696 This defines the maximum physical address that the system will scan when sizing memory.
697 By default the PC operating system will scan up to 3.75 gigabytes
698 (0xF0000000, the base of kernel virtual address space), but setting
702 must be less than 3.75 gigabytes.
703 This variable is not consulted if using the E820 memory map.
704 .SS \fL*kernelpercent=value\fP
705 This defines what percentage of available memory is reserved for the kernel allocation pool.
706 The remainder is left for user processes. The default
712 on terminals with less than 16MB of memory,
715 on terminals with memories of 16MB or more.
716 Terminals use more kernel memory because
718 maintains its graphic images in kernel memory.
719 This deprecated option is rarely necessary in newer kernels.
720 .SS \fL*nomce=value\fP
721 If machine check exceptions are supported by the processor,
722 then they are enabled by default.
723 Setting this variable to
725 causes them to be disabled even when available.
727 A multiprocessor machine will enable all processors by default.
730 restricts the kernel to starting only one processor and using the
731 traditional interrupt controller.
732 .SS \fL*ncpu=value\fP
735 restricts the kernel to starting at most
738 .SS \fL*pcimaxbno=value\fP
739 This puts a limit on the maximum bus number probed
740 on a PCI bus (default 7).
743 of 1 should suffice on a 'standard' motherboard with an AGP slot.
746 below are rarely used and only on troublesome or suspect hardware.
747 .SS \fL*pcimaxdno=value\fP
748 This puts a limit on the maximum device number probed
749 on a PCI bus (default 31).
750 .SS \fL*nopcirouting=\fP
751 Disable pci routing during boot. May solve interrupt routing
752 problems on certain machines.
753 .SS \fL*nodumpstack=\fP
754 Disable printing a stack dump on panic.
755 Useful if there is only a limited cga screen available,
756 otherwise the textual information about the panic may scroll off.
757 .\" .SS \fL*nobios=\fP
758 .\" what does this do? something with pci
759 .SS \fLioexclude=value\fP
760 Specifies a list of ranges of I/O ports to exclude from use by drivers.
761 Ranges are inclusive on both ends and separated by commas.
764 ioexclude=0x330-0x337,0x430-0x43F
766 .SS \fLumbexclude=value\fP
767 Specifies a list of ranges of UMB to exclude from use by drivers.
768 Ranges are inclusive on both ends and separated by commas.
771 umbexclude=0xD1800-0xD3FFF
774 This enables the ``advanced power management'' interface
779 The main feature of the interface is the ability to watch
782 It is not on by default because it causes problems on some laptops.
784 .SS \fLmonitor=value\fP
785 .SS \fLvgasize=value\fP
786 These are used not by the kernel but by
792 .SS \fL*dpms=value\fP
793 This is used to specify the screen blanking behavior of the MGA4xx
800 The first two specify differing levels of power saving;
801 the third turns the monitor off completely.
804 .SS \fLnvrlen=length\fP
805 .SS \fLnvroff=offset\fP
806 This is used to specify an nvram device and optionally the length of the ram
807 and read/write offset to use.
808 These values are consulted by
812 The most common use of the nvram is to hold a
817 This is used by the WORM file server kernel to locate a file holding information
818 to configure the file system.
819 The file cannot live on a SCSI disk.
825 is set, in which case it is
835 is the numeric unit id.
836 This variant syntax is a vestige of the file server kernel's origins.
837 .SH Multiple Configurations
841 file may contain multiple configurations,
842 each within a block beginning with a line
846 A special block with the tag
848 gives a list of blocks from which the user may
849 interactively select the contents of
851 There may also be multiple blocks with the tag
853 which will be included in all selections;
854 if any lines appear in
856 before the first block,
857 they are treated as a
863 block the following configuration lines are allowed:
864 .SS \fLmenuitem=tag[, description]
865 The block identified by
867 will appear in the presented menu.
868 The menu entry will consist of the
873 .SS \fLmenudefault=tag[, timeout]
874 Identifies a default block to be given in the
875 menu selection prompt.
878 is given (in seconds),
879 the default block will be selected if there is no user
880 input within the timeout period.
881 .SS \fLmenuconsole=value[, baud]
882 Selects a serial console upon which to present the menu
887 configuration information will have been processed yet
890 contents are still to be decided...).
892 In response to the menu being printed,
893 the user is prompted to select a menu item from the list.
894 If the numeric response is followed by a
896 the selected configuration is printed and the menu presented
903 is prefixed to the selected configuration as an aid to
904 user-level initialization scripts.
911 % cat /n/c:/plan9.ini
915 serial0=type=generic port=0x3E8 irq=5
921 Minimum CONFIG.SYS and AUTOEXEC.BAT files to use
925 % cat /n/c:/config.sys
926 SHELL=COMMAND.COM COM2 /P
927 % cat /n/c:/autoexec.bat
938 with multiple configurations:
942 menuitem=vga, Plan 9 with VGA
943 menuitem=novga, Plan 9 no automatic VGA
954 audio0=type=sb16 port=0x220 irq=5 dma=1
957 With this, the following menu will be presented on boot:
963 2. Plan 9 no automatic VGA
964 Selection[default==1]:
967 Selecting item 1 generates the following
969 to be used by the remainder of the bootstrap process:
976 audio0=type=sb16 port=0x220 irq=5 dma=1
979 and selecting item 2:
984 audio0=type=sb16 port=0x220 irq=5 dma=1
991 Being able to set the console device to other than a
992 display is marginally useful on file servers; MS-DOS
993 and the programs which run under it are so tightly bound
994 to the display that it is necessary to have a display if any
995 setup or reconfiguration programs need to be run.
996 Also, the delay before any messages appear at boot time
997 is disconcerting, as any error messages from the BIOS
1000 This idea is at best an interesting experiment that needs another iteration.