3 plan9.ini \- configuration file for PCs
7 When booting Plan 9 on a PC, the bootloader program
9 first reads configuration information from a file
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.
46 The file is used by the kernel to configure the hardware available.
47 The information it contains is also passed to the boot
48 process, and subsequently other programs,
49 as environment variables
52 However, values whose names begin with an asterisk
54 are used by the kernel and are not converted into environment variables.
56 The following sections describe how variables are used.
58 .SS \fLether\fIX\fL=\fIvalue\fP
59 This defines an Ethernet interface.
61 a unique monotonically increasing number beginning at 0,
62 identifies an Ethernet card to be probed at system boot.
63 Probing stops when a card is found or there is no line for
65 After probing as directed by the
67 lines, any remaining Ethernet cards that can be automatically
69 Almost all cards can be automatically detected.
70 For debugging purposes, automatic probing can
71 be disabled by specifying the line
74 Some cards are software configurable and do not require all options.
75 Unspecified options default to the factory defaults.
85 The Intel 8254X Gigabit Ethernet controllers,
86 as found on the Intel PRO/1000 adapters for copper (not fiber).
87 Completely configurable.
90 The Intel 8256[36], 8257[12], and 82573[ev] Gigabit Ethernet
91 PCI-Express controllers.
92 Completely configurable.
95 The Realtek 8169 Gigabit Ethernet controller.
96 Completely configurable.
99 Netgear GA620 and GA620T Gigabit Ethernet cards,
100 and other cards using the Alteon Acenic chip such as the
101 Alteon Acenic fiber and copper cards,
102 the DEC DEGPA-SA and the SGI Acenic.
103 Completely configurable.
106 National Semiconductor DP83820-based Gigabit Ethernet adapters, notably
108 Completely configurable.
111 The VIA Velocity Gigabit Ethernet controller.
112 Known to drive the VIA8237 (ABIT AV8), but at 100Mb/s full-duplex only.
115 The Myricom 10-Gigabit Ethernet 10G-PCIE-8A controller.
116 Completely configurable.
117 Can't boot through these due to enormous firmware loads.
120 The Intel 8259[89] 10-Gigabit Ethernet PCI-Express controllers.
121 Completely configurable.
124 Cards using the Intel 8255[789] Fast Ethernet PCI Bus LAN Controller such as the
125 Intel EtherExpress PRO/100B.
126 Completely configurable, no options need be given.
127 If you need to force the media, specify
128 one of the options (no value)
139 Completely configurable.
142 Cards using the Digital Equipment (now Intel) 2114x PCI Fast Ethernet Adapter Controller,
143 for example the Netgear FA310.
144 Completely configurable, no options need be given.
145 Media can be specified the same was as for the
151 near-clone chips may also work.
154 National Semiconductor DP83815-based adapters, notably
155 the Netgear FA311, Netgear FA312, and various SiS built-in
156 controllers such as the SiS900.
157 On the SiS controllers, the Ethernet address is not detected properly;
161 Completely configurable.
164 The Realtek 8139 Fast Ethernet controller.
165 Completely configurable.
168 The VIA VT6102 Fast Ethernet Controller (Rhine II).
171 SMC 91cXX chip-based PCMCIA adapters, notably the SMC EtherEZ card.
174 The 3COM Etherlink III series of cards including the 5x9, 59x, and 905 and 905B.
175 Completely configurable, no options need be given.
176 The media may be specified by setting
186 If you need to force full duplex, because for example the Ethernet switch does not negotiate correctly,
187 just name the word (no value)
191 Similarly, to force 100Mbit operation, specify
193 Port 0x110 is used for the little ISA configuration dance.
196 The 3COM 3C589 series PCMCIA cards, including the
198 There is no support for the modem on the 3C562.
199 Completely configurable, no options need be given.
204 The media may be specified as
210 The Linksys Combo PCMCIA EthernetCard (EC2T),
211 EtherFast 10/100 PCMCIA cards (PCMPC100) and integrated controllers (PCM100),
212 the Netgear FA410TX 10/100 PCMCIA card
213 and the Accton EtherPair-PCMCIA (EN2216).
214 Completely configurable, no options need be given.
219 These cards are NE2000 clones.
220 Other NE2000 compatible PCMCIA cards may be tried
227 is a unique identifier string contained in the attribute
228 memory of the card (see
230 unlike most options in
232 this string is case-sensitive.
235 can be used to turn off (0) or on (1) a dummy remote read in the driver
237 depending on how NE2000 compatible they are.
240 Not software configurable iff ISA;
241 PCI clones or supersets are software configurable;
242 includes the Realtek 8029 clone used by Parallels.
246 port=0x300 irq=2 mem=0x04000 size=0x4000
248 The option (no value)
250 is needed on some (near) clones to turn off a dummy remote read in the driver.
253 The AMD PCnet PCI Ethernet Adapter (AM79C970).
254 (This is the Ethernet adapter used by VMware.)
255 Completely configurable, no options need be given.
258 Includes WD8013 and SMC Elite and Elite Ultra cards. There are varying degrees
259 of software configurability. Cards may be in either 8-bit or 16-bit slots.
262 port=0x280 irq=3 mem=0xD0000 size=0x2000
264 BUG: On many machines only the 16 bit card works.
267 Broadcom BCM57xx Gigabit Ethernet controllers.
268 Completely configurable, no options need be given.
271 Marvell 88e8057 Yukon2 Gigabit Ethernet controller.
272 Completely configurable, no options need be given.
275 Virtual Ethernet interface provided by QEMU/KVM and VirtualBox.
276 No options need be given. The MAC address can be changed with the
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.
400 Intel Wireless WiFi Link mini PCI-Express adapters require
402 .B http://firmware.openbsd.org/firmware/*/iwn-firmware*.tgz
403 to be present on attach in
407 To limit the selected APs the options
411 may be set at boot or in the ether interface clone file
412 using a space as the separator between option and value, e.g.
414 echo essid left-armpit >/net/ether1/clone
416 Scan results appear in the
418 file and can be read out like:
420 cat /net/ether1/ifstats
422 Ad-hoc mode or WEP encryption is currently not supported.
425 Ralink Technology PCI/PCI-Express wireless adapters require
427 .B http://firmware.openbsd.org/firmware/*/ral-firmware*.tgz
428 to be present on attach in
432 See iwl section above for configuration details.
435 Intel PRO Wireless 3945abg PCI/PCI-Express wireless adapters require
437 .B http://firmware.openbsd.org/firmware/*/wpi-firmware*.tgz
438 to be present on attach in
442 See iwl section above for configuration details.
443 .SS \fLwpapsk\fI=password\fP
445 is detected automatically and a prompt for the
447 will appear when using the WIFI interface for netbooting.
448 To avoid the prompt, the
450 can be specified with the boot parameter above.
452 Disable automatic IPv6 configuration from incoming router advertisements.
454 (S)ATA controllers are autodetected.
456 disables dma on ata devices.
457 .SS \fL*sd\fIXX\fLdma=on\fP
458 explicitly enables dma on a specific ata device.
459 .SS \fLscsi\fIX\fL=value\fP
460 This defines a SCSI interface which cannot be automatically detected
468 Adaptec 154x series of controllers (and clones).
469 Almost completely configurable, only the
473 option need be given.
475 NCR/Symbios/LSI-Logic 53c8xx-based adapters
476 and Mylex MultiMaster (Buslogic BT-*) adapters are
477 automatically detected and need no entries.
479 By default, the NCR 53c8xx driver searches for up to 32 controllers.
480 This can be changed by setting the variable
483 By default the Mylex driver resets SCSI cards by using
484 both the hard reset and SCSI bus reset flags in the driver interface.
487 is defined, the SCSI bus reset flag is omitted.
488 .SS \fLaoeif=\fP\fIlist\fP
489 This specifies a space-separated
491 of Ethernet interfaces to be bound at boot to the ATA-over-Ethernet driver,
494 .LR "aoeif=ether0 ether1" .
495 Only interfaces on this list will initially be accessible via AoE.
496 .SS \fLaoedev=e!#æ/aoe/\fIshelf\fL.\fIslot\fR
497 This specifies an ATA-over-Ethernet device accessible via the interfaces
504 to use as a root device for bootstrapping.
505 .SS \fLramdisk\fIX\fL=\fIsize\fP
506 .SS \fLramdisk\fIX\fL=\fIsize sectorsize\fP
507 .SS \fLramdisk\fIX\fL=\fIaddress size sectorsize\fP
508 This reserves physical memory as a ramdisk that will appear as
510 device \fLsdZ\fIX\fR.
513 argument is omited or zero, then the ramdisk will be allocated
514 from the top of physical memory.
516 .SS \fLaudio\fIX\fL=\fIvalue\fP
517 This defines a sound interface. PCI based audio devices such as
518 Intel HD audio or AC97 are autodetected and do not require any settings.
534 A Sound Blaster clone.
536 The DMA channel may be any of 5, 6, or 7.
540 port=0x220 irq=7 dma=5
543 Plan 9 automatically configures COM1 and COM2, if found,
551 These devices can be disabled by adding a line:
557 This is typically done in order to reuse the IRQ for
561 Additional i8250 (ISA) uarts (uart2 to uart5) can be
565 uart\fIX\fP=type=isa port=\fIport\fP irq=\fIirq
568 Perle PCI-Fast4, PCI-Fast8, and PCI-Fast16 controllers
569 are automatically detected and need no configuration lines.
573 can be used to specify settings for a PCMCIA modem.
574 .SS \fLkbmap=\fIvalue\fP
575 This specifies the keyboard map to use.
577 can be a map file found in
584 .SS \fLmouseport=\fIvalue\fP
585 This specifies where the mouse is attached.
587 can be a map file found in
592 the PS2 mouse/keyboard port. The BIOS setup procedure
593 should be used to configure the machine appropriately.
596 an Intellimouse on the PS2 port.
603 .SS \fLmodemport=\fIvalue\fP
604 Picks the UART line to call out on.
605 This is used when connecting to a file server over
608 is the number of the port.
609 .SS \fLconsole=\fIvalue params\fP
610 This is used to specify the console device.
624 A serial console is initially configured with the
631 specifying 9600 baud,
632 8 bit bytes, no parity, and one stop bit.
635 is given, it will be used to further
637 Notice that there is no
648 would use COM1 at 19,200 baud
653 specifies ``netconsole'' which sends console messages as UDP packets over the network.
654 It bypasses the IP stack and writes Ethernet packets directly to the NIC.
657 is mandatory and takes the form
659 \fIsrcip\fR [ \fB!\fIsrcport \fR] [ \fB/\fIdevno \fR] \fB, \fIdstip\fR [ \fB!\fIdstport \fR] [ \fB/\fIdstmac \fR]
661 \fISrcip\fR, \fIsrcport\fR (default 6665), \fIdstip\fR and \fIdstport\fR (default 6666) specify the source IP address, source port, destination IP address and destination port, respectively.
662 \fIDevno\fR (default 0) specifies which NIC to use, a value of \fIn\fR corresponds to NIC at \fL#l\fIn\fR (see
664 \fIDstmac\fR specifies the destination MAC address; broadcast packets are sent if it is unspecified.
665 Note that it is possible, but not recommended, to send packets to a host outside the local network by specifying the MAC address of the gateway as \fIdstmac\fR.
669 console=net 192.168.0.4,192.168.0.8
670 console=net 192.168.2.10!1337/1,192.168.2.3!1337/0ea7deadbeef
674 .SS \fLpccard0=disabled\fP
675 Disable probing for and automatic configuration of PC card controllers.
676 .SS \fLpcmcia\fIX\fL=type=XXX irq=\fIvalue\fP
677 If the default IRQ for the
679 is correct, this entry can be omitted. The value of
682 .SS \fLpcmcia0=disabled\fP
683 Disable probing for and automatic configuration of PCMCIA controllers.
685 .SS \fLbootfile=\fIvalue\fP
686 This is used to direct the actions of
688 by naming the file from which to load the kernel in
689 the current BIOS boot device.
690 .SS \fLbootargs=\fIvalue\fP
693 of this variable is passed to
695 by the kernel as the name of the root file system to
696 automatically mount and boot into.
697 It is typically used to specify additional arguments to
702 For example, if the system is to run from a local
704 partition, the definition might read
705 .BR bootargs=local!/dev/sdC0/fscache .
709 .SS \fLnobootprompt=\fIvalue\fP
714 as the answer instead.
715 .SS \fLrootdir=\fB/root/\fIdir\fP
716 .SS \fLrootspec=\fIspec\fP
717 Changes the mount arguments for the root file server
718 that was specified by
725 a different sub-directory on the root file server
726 can be used as the system root. see
729 .SS \fLuser=\fIvalue\fP
734 as the answer instead.
735 .SS \fLservice=\fIvalue\fP
736 Changes the systems default role. Possible
743 .SS \fLdebugfactotum=\fP
750 option, so that it can be debugged.
751 .SS \fLcfs=\fIvalue\fP
752 This gives the name of the file holding the disk partition
753 for the cache file system,
757 example, one would write
758 .BR cfs=#S/sdC0/cache .
759 .SS \fLbootdisk=\fIvalue\fP
760 This deprecated variable was used to specify the disk used by
761 the cache file system and other disk-resident services.
766 .SS \fLfs=\fIaddress\fP
767 .SS \fLauth=\fIaddress\fP
768 .SS \fLsecstore=\fIaddress\fP
769 These specify the network address (IP or domain name)
770 of the file, authentication and secstore server
771 to use when mounting a network-provided root file system.
772 When not specified, then these settings are determined via DHCP.
775 is not specified, then the authentication server is used.
777 .SS \fL*e820=\fItype \fB0x\fIstart \fB0x\fIend ...\fP
778 This variable is automatically generated by the boot loader (see
780 by doing a BIOS E820 memory scan while still in realmode and
781 passed to the kernel. The format is a unordered list of
784 and hexadecimal 64-bit
788 addresses of the area.
789 .SS \fL*maxmem=\fIvalue\fP
790 This defines the maximum physical address that the system will scan when sizing memory.
791 By default the PC operating system will scan up to 3.75 gigabytes
792 (0xF0000000, the base of kernel virtual address space), but setting
796 must be less than 3.75 gigabytes.
797 This variable is not consulted if using the E820 memory map.
798 .SS \fL*kernelpercent=\fIvalue\fP
799 This defines what percentage of available memory is reserved for the kernel allocation pool.
800 The remainder is left for user processes. The default
806 on terminals with less than 16MB of memory,
809 on terminals with memories of 16MB or more.
810 Terminals use more kernel memory because
812 maintains its graphic images in kernel memory.
813 This deprecated option is rarely necessary in newer kernels.
814 .SS \fL*imagemaxmb=\fIvalue\fP
815 This limits the maximum amount of memory (in megabytes) the graphics
816 image memory pool can grow. The default is unlimited for terminals
819 Disables AVX and AVX2 on AMD64 CPUs.
821 If machine check exceptions are supported by the processor,
822 then they are enabled by default.
825 causes them to be disabled even when available.
827 A multiprocessor machine will enable all processors by default.
830 restricts the kernel to starting only one processor and using the
831 traditional interrupt controller.
832 .SS \fL*ncpu=\fIvalue\fP
835 restricts the kernel to starting at most
838 .SS \fL*apicdebug=\fP
839 Prints a summary of the multiprocessor APIC interrupt configuration.
841 Disables message signaled interrupts for PCI devices.
842 This option has no effect when
846 Disables memory type range register (MTRR) support when set. (debug)
848 Disables the use of the per processor timestamp counter registers
849 as high resolution clock.
851 Disables the HPET timer to be used as the high resolution clock.
852 .SS \fL*pcimaxbno=value\fP
853 This puts a limit on the maximum bus number probed
854 on a PCI bus (default 7).
857 of 1 should suffice on a 'standard' motherboard with an AGP slot.
860 below are rarely used and only on troublesome or suspect hardware.
861 .SS \fL*pcimaxdno=\fIvalue\fP
862 This puts a limit on the maximum device number probed
863 on a PCI bus (default 31).
864 .SS \fL*nopcirouting=\fP
865 Disable pci routing during boot. May solve interrupt routing
866 problems on certain machines.
868 Prints a summary of the detected PCI busses and devices.
869 .SS \fL*nodumpstack=\fP
870 Disable printing a stack dump on panic.
871 Useful if there is only a limited cga screen available,
872 otherwise the textual information about the panic may scroll off.
873 .\" .SS \fL*nobios=\fP
874 .\" what does this do? something with pci
875 .SS \fLioexclude=\fIvalue\fP
876 Specifies a list of ranges of I/O ports to exclude from use by drivers.
877 Ranges are inclusive on both ends and separated by commas.
880 ioexclude=0x330-0x337,0x430-0x43F
882 .SS \fLumbexclude=\fIvalue\fP
883 Specifies a list of ranges of UMB to exclude from use by drivers.
884 Ranges are inclusive on both ends and separated by commas.
887 umbexclude=0xD1800-0xD3FFF
889 .SS \fL*acpi=\fIvalue\fP
890 This option controls the search for ACPI tables by the kernel.
893 is the hexadecimal physical address of the RSD structure
894 and is passed by the EFI bootloer
899 of 1 or empty make the kernel search for the structure
900 in BIOS memory area (This is the default).
904 of 0 will disable ACPI support (for interrupt routing)
906 but still make table data available in
912 This enables the ``advanced power management'' interface
917 The main feature of the interface is the ability to watch
920 It is not on by default because it causes problems on some laptops.
922 .SS \fL*nousbprobe=\fP
923 Disable USB host controller detection.
924 .SS \fL*nousbohci=\fP
925 .SS \fL*nousbuhci=\fP
926 .SS \fL*nousbehci=\fP
927 .SS \fL*nousbxhci=\fP
928 Disable specific USB host controller types.
932 startup at boot time.
933 .SS \fLnousbhname=\fP
936 will use the dynamically assigned usb device address to name
937 usb devices instead of the device unique name.
939 .SS \fLmonitor=\fIvalue\fP
940 .SS \fLvgasize=\fIvalue\fP
941 These are used not by the kernel but by
951 then the user is prompted for a choice on boot.
952 .SS \fL*bootscreen=\fIvalue\fP
953 This is used by the kernel to attach a pre-initialized
954 linear framebuffer that was setup by the bootloader
958 has four space separated fields: the resolution and bitdepth
959 of the screen, the color channel descriptor, the physical
960 address of the framebuffer and a optional aperture size.
962 *bootscreen=800x600x32 x8r8g8b8 0x80000000 0x001d4c00
964 .SS \fL*dpms=\fIvalue\fP
965 This is used to specify the screen blanking behavior of the MGA4xx
972 The first two specify differing levels of power saving;
973 the third turns the monitor off completely.
975 .SS \fLnvram=\fIfile\fP
976 .SS \fLnvrlen=\fIlength\fP
977 .SS \fLnvroff=\fIoffset\fP
978 This is used to specify an nvram device and optionally the length of the ram
979 and read/write offset to use.
980 These values are consulted by
984 The most common use of the nvram is to hold a
988 .SS \fLnvr=\fIvalue\fP
989 This is used by the WORM file server kernel to locate a file holding information
990 to configure the file system.
991 The file cannot live on a SCSI disk.
997 is set, in which case it is
1001 The syntax is either
1007 is the numeric unit id.
1008 This variant syntax is a vestige of the file server kernel's origins.
1015 % cat /n/9fat:/plan9.ini
1019 serial0=type=generic port=0x3E8 irq=5