diff options
author | Matt Fleming <matt.fleming@intel.com> | 2013-06-24 10:28:58 +0100 |
---|---|---|
committer | Matt Fleming <matt.fleming@intel.com> | 2013-06-24 10:29:52 +0100 |
commit | c9c90411958eb6c68da05de745d0ffa7f322fe20 (patch) | |
tree | 0226fbea7d391d7d67f7779824ea4953f1599638 | |
parent | 022cdd1d56512e8759e8374c10a7420201db93c0 (diff) | |
parent | 2e6ccfe2bc38f11dd4696ea1bb4b1c32f47c9c91 (diff) | |
download | syslinux-c9c90411958eb6c68da05de745d0ffa7f322fe20.tar.gz |
Merge branch 'doc-for-mfleming' of git://github.com/geneC/syslinux into elflink
Pull txt/ and doc/ updates from Gene Cumm,
* 'doc-for-mfleming' of git://github.com/geneC/syslinux:
txt/syslinux.txt: rewrap long command
txt/Makefile: add isolinux.txt, pxelinux.txt
txt/: Add isolinux.txt, pxelinux.txt
txt/syslinux-cli.txt: Version on Ctrl-N
txt/Makefile: order-only prerequisite
txt/: Add common file for derivatives
txt/syslinux.cfg.txt: Updates
txt/syslinux.txt: synopsis, extlinux.sys, wrap long command
txt/syslinux-cli.txt: Path rules
txt/syslinux.cfg.txt: Add SENDCOOKIES, example config
txt/syslinux.cfg.txt: Add SYSAPPEND
doc/syslinux.txt: grammar
Fix SERIAL directive in docs
-rw-r--r-- | doc/syslinux.txt | 4 | ||||
-rw-r--r-- | txt/Makefile | 12 | ||||
-rw-r--r-- | txt/com-derv.txt | 11 | ||||
-rw-r--r-- | txt/isolinux.txt | 116 | ||||
-rw-r--r-- | txt/pxelinux.txt | 461 | ||||
-rw-r--r-- | txt/syslinux-cli.txt | 30 | ||||
-rw-r--r-- | txt/syslinux.cfg.txt | 167 | ||||
-rw-r--r-- | txt/syslinux.txt | 14 |
8 files changed, 779 insertions, 36 deletions
diff --git a/doc/syslinux.txt b/doc/syslinux.txt index a4b201fd..a81cc649 100644 --- a/doc/syslinux.txt +++ b/doc/syslinux.txt @@ -234,7 +234,7 @@ IPAPPEND bitmask 0x08000 BIOSVERSION= BIOS version 0x10000 SYSFF= System form factor - If these strings contain whitespace they it is replaced with + If these strings contain whitespace they are replaced with underscores (_). The system form factor value is a number defined in the SMBIOS @@ -426,7 +426,7 @@ ONERROR kernel options... xyzzy plugh foo bar baz -SERIAL port [[baudrate] flowcontrol] +SERIAL port [baudrate [flowcontrol]] Enables a serial port to act as the console. "port" is a number (0 = /dev/ttyS0 = COM1, etc.) or an I/O port address (e.g. 0x3F8); if "baudrate" is omitted, the baud rate defaults diff --git a/txt/Makefile b/txt/Makefile index 03655775..8ee80845 100644 --- a/txt/Makefile +++ b/txt/Makefile @@ -26,8 +26,10 @@ A2X_OPTS = -k # A2X_OPTS += -v A2X_MAN_OPTS = -D man -f manpage -DOCS = syslinux.txt syslinux-cli.txt syslinux.cfg.txt -MAN_DOCS = man/syslinux.1 man/syslinux-cli.1 man/syslinux.cfg.5 +DOCS = syslinux.txt syslinux-cli.txt syslinux.cfg.txt \ + isolinux.txt pxelinux.txt +MAN_DOCS = man/syslinux.1 man/syslinux-cli.1 man/syslinux.cfg.5 \ + man/isolinux.1 man/pxelinux.1 HTML_DOCS := $(patsubst %.txt,html/%.html,$(DOCS)) XHTML_DOCS := $(patsubst %.txt,%.html,$(DOCS)) # MAN_DOCS := $(patsubst %.txt,man/%.1,$(DOCS1)) $(patsubst %.txt,man/%.5,$(DOCS5)) @@ -72,7 +74,7 @@ syslinux.cfg.txt: com-bug.txt com-rpt.txt html/ man/ text/ xhtml/: mkdir $@ -html/%.html: %.txt html/ +html/%.html: %.txt | html/ asciidoc -o $@ $< # As of AsciiDoc-8.5.2, altering the output filename for a2x does not appear possible @@ -88,10 +90,10 @@ html/%.html: %.txt html/ %.html: %.xml %.txt a2x $(A2X_OPTS) -f xhtml $< -man/%.1: %.txt man/ +man/%.1: %.txt | man/ a2x $(A2X_MAN_OPTS) $< -man/%.5: %.txt man/ +man/%.5: %.txt | man/ a2x $(A2X_MAN_OPTS) $< %.text: %.xml %.txt diff --git a/txt/com-derv.txt b/txt/com-derv.txt new file mode 100644 index 00000000..21c70c79 --- /dev/null +++ b/txt/com-derv.txt @@ -0,0 +1,11 @@ + +// == DERIVATIVES == + +The *Syslinux* suite contains several boot loader (core) derivatives (variants), currently based solely on the boot media: + + *SYSLINUX* - Disk (floppy/hard disk) based + *PXELINUX* - PXE network booting + *ISOLINUX* - ISO9660 (CD/DVD; El Torito) based + +Prior to v4.00, *SYSLINUX* was only for FAT12/FAT16/FAT32 and another derivative, *EXTLINUX*, was for ext2/ext3 file systems, whose functionality has been merged into *SYSLINUX*. + diff --git a/txt/isolinux.txt b/txt/isolinux.txt new file mode 100644 index 00000000..55e7d7c5 --- /dev/null +++ b/txt/isolinux.txt @@ -0,0 +1,116 @@ += isolinux(1) = +:doctype: manpage +:revdate: 2013-06-12 +:author: H. Peter Anvin +:author-email: hpa@zytor.com +:editor1: Gene Cumm +:editor1-email: gene.cumm@gmail.com +:editor1-revlast: 2013-06-12 + + +== NAME == +isolinux - The Syslinux derivative ISOLINUX for ISO9660 CD/DVD media + + +== SYNOPSIS == +[verse] +*mkisofs* -o 'isoimage' \ + -b 'isolinux/isolinux.bin' -c 'isolinux/boot.cat' \ + -no-emul-boot -boot-load-size 4 -boot-info-table \ + 'root-of-iso-tree' + + +== DESCRIPTION == +ISOLINUX is a boot loader for Linux/i386 that operates off ISO 9660/El +Torito CD-ROMs in "no emulation" mode. This avoids the need to create +an "emulation disk image" with limited space (for "floppy emulation") +or compatibility problems (for "hard disk emulation".) + +To create an image, create a directory called "isolinux/" (or, if you +prefer, "boot/isolinux/") underneath the root directory of your ISO image +master file tree. Copy isolinux.bin, a config file called +"isolinux.cfg" (see *syslinux.cfg*(5) for details on the configuration file), +and all necessary files (kernels, initrd, display files, etc.) into this +directory, then use the above command to create your ISO image (add +additional options as appropriate, such as -J or -R). If you named the +directory boot/isolinux that should of course be + + -b boot/isolinux/isolinux.bin -c boot/isolinux/boot.cat. + + +== CONFIG FILE DIRECTORY == + +ISOLINUX will search for the config file directory in the order +/boot/isolinux, /isolinux, /. The first directory that exists is +used, even if it contains no files. Therefore, please make sure that +these directories don't exist if you don't want ISOLINUX to use them. + + +== HYBRID CD-ROM/HARD DISK MODE == + +Starting in version 3.72, ISOLINUX supports a "hybrid mode" which can +be booted from either CD-ROM or from a device which BIOS considers a +hard disk or ZIP disk, e.g. a USB key or similar. + +To enable this mode, the .iso image should be postprocessed with the +"isohybrid" script from the utils directory: + + isohybrid filename.iso + +This script creates the necessary additional information to be able to +boot in hybrid mode. It also pads out the image to an even multiple +of 1 MB. + +This image can then be copied using any raw disk writing tool (on Unix +systems, typically "dd" or "cat") to a USB disk, or written to a +CD-ROM using standard CD burning tools. + +The ISO 9660 filesystem is encapsulated in a partition (which starts +at offset zero, which may confuse some systems.) This makes it +possible for the operating system, once booted, to use the remainder +of the device for persistent storage by creating a second partition. + + +== MISCELLANEOUS == +Make sure you have a recent enough version of mkisofs. I recommend +mkisofs 1.13 (distributed with cdrecord 1.9), but 1.12 might work as +well (not tested.) + +ISOLINUX resolves pathnames the following way: + +- A pathname consists of names separated by slashes, Unix-style. +- A leading / means it searches from the root directory; otherwise the + search is from the isolinux directory (think of this as the "current + directory".) +- . and .. in pathname searches are not supported. +- The maximum length of any pathname is 255 characters. + +Note that ISOLINUX only uses the "plain" ISO 9660 filenames, i.e. it +does not support Rock Ridge or Joliet filenames. It can still be used +on a disk which uses Rock Ridge and/or Joliet extensions, of course. +Under Linux, you can verify the plain filenames by mounting with the +"-o norock,nojoliet" option to the mount command. Note, however, that +ISOLINUX does support "long" (level 2) ISO 9660 plain filenames, so if +compatibility with short-names-only operating systems like MS-DOS is +not an issue, you can use the "-l" or "-iso-level 2" option to mkisofs +to generate long (up to 31 characters) plain filenames. + +ISOLINUX does not support discontiguous files, interleaved mode, or +logical block and sector sizes other than 2048. This should normally +not be a problem. + +ISOLINUX is by default built in two versions, one version with extra +debugging messages enabled. If you are having problems with ISOLINUX, +I would greatly appreciate if you could try out the debugging version +(isolinux-debug.bin) and let me know what it reports. The debugging +version does not include hybrid mode support (see below.) + + +== SEE ALSO == +*syslinux.cfg*(5), *syslinux-cli*(1), *lilo*(8), *keytab-lilo.pl*(8), +*fdisk*(8), *mkfs*(8), *superformat*(1). + + +== AUTHOR == +This AsciiDoc derived document is a modified version of the original +*SYSLINUX* documentation by {author} <{author-email}>. The conversion +to an AsciiDoc was made by {editor1} <{editor1-email}> diff --git a/txt/pxelinux.txt b/txt/pxelinux.txt new file mode 100644 index 00000000..77d34fdd --- /dev/null +++ b/txt/pxelinux.txt @@ -0,0 +1,461 @@ += pxelinux(1) = +:doctype: manpage +:revdate: 2013-06-12 +:author: H. Peter Anvin +:author-email: hpa@zytor.com +:editor1: Gene Cumm +:editor1-email: gene.cumm@gmail.com +:editor1-revlast: 2013-06-12 + + +== NAME == +pxelinux - The Syslinux derivative PXELINUX for PXE network booting + + +== SYNOPSIS == +[verse] +pxelinux.0 + + +== DESCRIPTION == +*PXELINUX* is a Syslinux derivative, for booting Linux off a network +server, using a network ROM conforming to the Intel PXE (Pre-Execution +Environment) specification. *PXELINUX* is _*not*_ a program that is +intended to be flashed or burned into a PROM on the network card; if +you want that, check out Etherboot (http://www.etherboot.org/). +Etherboot 5.4 or later can also be used to create a PXE-compliant boot +PROM for many network cards. +//FIXME: Needs gPXE/iPXE note + +PXELINUX generally requires that full file pathnames are 127 characters or shorter in length. +//FIXME: why? many tftpds limiting to 127+null? outdated? + + +== CURRENT DIRECTORY == +The initial current working directory is either as supplied by DHCP +option 210 (pxelinux.pathprefix), the hardcoded path-prefix or the +parent directory of the PXELINUX file, as indicated by DHCP fields +'sname' and 'file' (sname="192.168.2.3" and file="boot/pxelinux.0" +results in "tftp://192.168.2.3/boot/", "192.168.2.3::boot/" in older +PXELINUX format) with precedence specified under *OPTIONS*. + +All unqualified filenames are relative to the current directory. + + +== CONFIGURATION == +See *syslinux.cfg*(5) for the format of the contents. + +Because more than one system may be booted from the same server, the +configuration file name depends on the IP address of the booting +machine. After attempting the file as specified in the DHCP or +hardcoded options, PXELINUX will probe the following paths, prefixed +with "pxelinux.cfg/", under the initial current working directory: + +- The client UUID if provided by the PXE stack (note, some BIOSes don't +have a valid UUID, and you might end up with something like all 1's.) +This is in the standard UUID format using lower case hexadecimal digits, +e.g. b8945908-d6a6-41a9-611d-74a6ab80b83d. + +- The hardware type (using its ARP type code) and address, all in lower +case hexadecimal with dash separators; for example, for an Ethernet (ARP +type 1) with address 88:99:AA:BB:CC:DD it would search for the filename +01-88-99-aa-bb-cc-dd. + +- The client's IPv4 address in upper-case hexidecimal (ie 192.168.2.91 +-> C0A8025B; you can use the included progam "gethostip" to compute the +hexadecimal IP address for any host.) followed by removing characters, +one at a time, from the end. + +- "default" + +Starting in release 3.20, if PXELINUX can not find a configuration file, +it will reboot after the timeout interval has expired. This keeps a +machine from getting stuck indefinitely due to a boot server failure. + + +== OPTIONS == +*PXELINUX* (starting with version 1.62) supports the following +nonstandard DHCP options, which depending on your DHCP server you may be +able to use to customize the specific behaviour of *PXELINUX*. See RFC +5071 for some additional information about these options. Options for +*PXELINUX* can be specified by DHCP options or hardcoded into the +binary. + +=== Option Priority === +Hardcoded after-options are applied after DHCP options (and overrride) +while hardcoded before-options are applied prior to DHCP options and +default behavior takes the lowest priority. + +=== DHCP options === +*Option 208* (pxelinux.magic):: +Earlier versions of *PXELINUX* required this to be set to F1:00:74:7E +(241.0.116.126) for *PXELINUX* to recognize any special DHCP options +whatsoever. As of *PXELINUX* 3.55, this option is deprecated and is no +longer required. + +*Option 209* (pxelinux.configfile):: +Specifies the initial *PXELINUX* configuration file name which may be +qualified or unqualified. + +*Option 210* (pxelinux.pathprefix):: +Specifies the *PXELINUX* common path prefix, instead of deriving it from +the boot file name. This almost certainly needs to end in whatever +character the TFTP server OS uses as a pathname separator, e.g. slash +(/) for Unix. + +*Option 211* (pxelinux.reboottime):: +Specifies, in seconds, the time to wait before reboot in the event of +TFTP failure. 0 means wait "forever" (in reality, it waits +approximately 136 years.) + +=== Hardcoded options === +Since version 3.83, the program "pxelinux-options" can be used to +hard-code DHCP options into the pxelinux.0 image file; this is +sometimes useful when the DHCP server is under different +administrative control. Hardcoded options + + 6 => 'domain-name-servers', + 15 => 'domain-name', + 54 => 'next-server', + 209 => 'config-file', + 210 => 'path-prefix', + 211 => 'reboottime' + + +== HTTP/FTP == +Since version 5.10, a special PXELINUX binary, lpxelinux.0, natively +supports HTTP and FTP transfers, greatly increasing load speed and +allowing for standard HTTP scripts to present PXELINUX's configuration +file. To use http or ftp, use standard URL syntax as filename; use the +DHCP options below to transmit a suitable URL prefix to the client, or +use the "pxelinux-options" tool provided in the utils directory to +program it directly into the lpxelinux.0 file. + + +== FILENAME SYNTAX == +//FIXME +PXELINUX supports the following special pathname conventions: + +*::filename*:: +Suppresses the common filename prefix, i.e. passes the string "filename" +unmodified to the server. + +*IP address::filename* (e.g. 192.168.2.3::filename):: +Suppresses the common filename prefix, *and* sends a request to an alternate TFTP server. Instead of an IP address, a DNS name can be used. It will be assumed to be fully qualified if it contains dots; otherwise the local domain as reported by the DHCP server (option 15) will be added. + +:: was chosen because it is unlikely to conflict with operating system +usage. However, if you happen to have an environment for which the +special treatment of :: is a problem, please contact the Syslinux +mailing list. + +Since version 4.00, PXELINUX also supports standard URL syntax. + + +== KEEPPXE == +Normally, PXELINUX will unload the PXE and UNDI stacks before invoking +the kernel. In special circumstances (for example, when using MEMDISK +to boot an operating system with an UNDI network driver) it might be +desirable to keep the PXE stack in memory. If the option "keeppxe" +is given on the kernel command line, PXELINUX will keep the PXE and +UNDI stacks in memory. (If you don't know what this means, you +probably don't need it.) + + +== EXAMPLES == + +=== Configuration filename === +For DHCP siaddr 192.168.2.3, file 'mybootdir/pxelinux.0', client UUID +b8945908-d6a6-41a9-611d-74a6ab80b83d, Ethernet MAC address +88:99:AA:BB:CC:DD and IPv4 address 192.168.2.91, the following files in +this order will be attempted (after config-file options): + + mybootdir/pxelinux.cfg/b8945908-d6a6-41a9-611d-74a6ab80b83d + mybootdir/pxelinux.cfg/01-88-99-aa-bb-cc-dd + mybootdir/pxelinux.cfg/C0A8025B + mybootdir/pxelinux.cfg/C0A8025 + mybootdir/pxelinux.cfg/C0A802 + mybootdir/pxelinux.cfg/C0A80 + mybootdir/pxelinux.cfg/C0A8 + mybootdir/pxelinux.cfg/C0A + mybootdir/pxelinux.cfg/C0 + mybootdir/pxelinux.cfg/C + mybootdir/pxelinux.cfg/default + + +=== TFTP servers === +For best results, use a TFTP server which supports the "tsize" TFTP +option (RFC 1784/RFC 2349). The "tftp-hpa" TFTP server, which support +options, is available at: + + http://www.kernel.org/pub/software/network/tftp/ + ftp://www.kernel.org/pub/software/network/tftp/ + +and on any kernel.org mirror (see http://www.kernel.org/mirrors/). + +Another TFTP server which supports this is atftp by Jean-Pierre +Lefebvre: + + ftp://ftp.mamalinux.com/pub/atftp/ + +If your boot server is running Windows (and you can't fix that), try +tftpd32 by Philippe Jounin (you need version 2.11 or later; previous +versions had a bug which made it incompatible with PXELINUX): + + http://tftpd32.jounin.net/ + + +=== DHCP config: Simple === +The PXE protocol uses a very complex set of extensions to DHCP or +BOOTP. However, most PXE implementations -- this includes all Intel +ones version 0.99n and later -- seem to be able to boot in a +"conventional" DHCP/TFTP configuration. Assuming you don't have to +support any very old or otherwise severely broken clients, this is +probably the best configuration unless you already have a PXE boot +server on your network. + +A sample DHCP setup, using the "conventional TFTP" configuration, +would look something like the following, using ISC dhcp 2.0 dhcpd.conf +syntax: + +----- +allow booting; +allow bootp; + +# Standard configuration directives... + +option domain-name "<domain name>"; +option subnet-mask <subnet mask>; +option broadcast-address <broadcast address>; +option domain-name-servers <dns servers>; +option routers <default router>; + +# Group the PXE bootable hosts together +group { + # PXE-specific configuration directives... + next-server <TFTP server address>; + filename "/tftpboot/pxelinux.0"; + + # You need an entry like this for every host + # unless you're using dynamic addresses + host <hostname> { + hardware ethernet <ethernet address>; + fixed-address <hostname>; + } +} +----- + +Note that if your particular TFTP daemon runs under chroot (tftp-hpa +will do this if you specify the -s (secure) option; this is highly +recommended), you almost certainly should not include the /tftpboot +prefix in the filename statement. + + +=== DHCP Config: PXE-1 === +If the simple config does not work for your environment, you probably +should set up a "PXE boot server" on port 4011 of your TFTP server; a +free PXE boot server is available at: + +http://www.kano.org.uk/projects/pxe/ + +With such a boot server defined, your DHCP configuration should look +the same except for an "option dhcp-class-identifier" ("option +vendor-class-identifier" if you are using DHCP 3.0): + +---- +allow booting; +allow bootp; + +# Standard configuration directives... + +option domain-name "<domain name>"; +option subnet-mask <subnet mask>; +option broadcast-address <broadcast address>; +option domain-name-servers <dns servers>; +option routers <default router>; + +# Group the PXE bootable hosts together +group { + # PXE-specific configuration directives... + option dhcp-class-identifier "PXEClient"; + next-server <pxe boot server address>; + + # You need an entry like this for every host + # unless you're using dynamic addresses + host <hostname> { + hardware ethernet <ethernet address>; + fixed-address <hostname>; + } +} +---- + +Here, the boot file name is obtained from the PXE server. + + +=== DHCP Config: Encapsulated === +If the "conventional TFTP" configuration doesn't work on your clients, +and setting up a PXE boot server is not an option, you can attempt the +following configuration. It has been known to boot some +configurations correctly; however, there are no guarantees: +---- +allow booting; +allow bootp; + +# Standard configuration directives... + +option domain-name "<domain name>"; +option subnet-mask <subnet mask>; +option broadcast-address <broadcast address>; +option domain-name-servers <dns servers>; +option routers <default router>; + +# Group the PXE bootable hosts together +group { + # PXE-specific configuration directives... + option dhcp-class-identifier "PXEClient"; + option vendor-encapsulated-options 09:0f:80:00:0c:4e:65:74:77:6f:72:6b:20:62:6f:6f:74:0a:07:00:50:72:6f:6d:70:74:06:01:02:08:03:80:00:00:47:04:80:00:00:00:ff; + next-server <TFTP server>; + filename "/tftpboot/pxelinux.0"; + + # You need an entry like this for every host + # unless you're using dynamic addresses + host <hostname> { + hardware ethernet <ethernet address>; + fixed-address <hostname>; + } +} +---- +Note that this *will not* boot some clients that *will* boot with the +"conventional TFTP" configuration; Intel Boot Client 3.0 and later are +known to fall into this category. + + +=== DHCP Config: ISC dhcpd options === +ISC dhcp 3.0 supports a rather nice syntax for specifying custom +options; you can use the following syntax in dhcpd.conf if you are +running this version of dhcpd: +---- +option space pxelinux; +option pxelinux.magic code 208 = string; +option pxelinux.configfile code 209 = text; +option pxelinux.pathprefix code 210 = text; +option pxelinux.reboottime code 211 = unsigned integer 32; +---- + NOTE: In earlier versions of PXELINUX, this would only work as a + "site-option-space". Since PXELINUX 2.07, this will work both as a + "site-option-space" (unencapsulated) and as a "vendor-option-space" + (type 43 encapsulated.) This may avoid messing with the + dhcp-parameter-request-list, as detailed below. + +Then, inside your PXELINUX-booting group or class (whereever you have +the PXELINUX-related options, such as the filename option), you can +add, for example: +---- +# Always include the following lines for all PXELINUX clients +site-option-space "pxelinux"; +option pxelinux.magic f1:00:74:7e; +if exists dhcp-parameter-request-list { + # Always send the PXELINUX options (specified in hexadecimal) + option dhcp-parameter-request-list = concat(option dhcp-parameter-request-list,d0,d1,d2,d3); +} +# These lines should be customized to your setup +option pxelinux.configfile "configs/common"; +option pxelinux.pathprefix "/tftpboot/pxelinux/files/"; +option pxelinux.reboottime 30; +filename "/tftpboot/pxelinux/pxelinux.bin"; +---- +Note that the configfile is relative to the pathprefix: this will look +for a config file called /tftpboot/pxelinux/files/configs/common on +the TFTP server. + +The "option dhcp-parameter-request-list" statement forces the DHCP +server to send the PXELINUX-specific options, even though they are not +explicitly requested. Since the DHCP request is done before PXELINUX +is loaded, the PXE client won't know to request them. + +Using ISC dhcp 3.0 you can create a lot of these strings on the fly. +For example, to use the hexadecimal form of the hardware address as +the configuration file name, you could do something like: +---- +site-option-space "pxelinux"; +option pxelinux.magic f1:00:74:7e; +if exists dhcp-parameter-request-list { + # Always send the PXELINUX options (specified in hexadecimal) + option dhcp-parameter-request-list = concat(option dhcp-parameter-request-list,d0,d1,d2,d3); +} +option pxelinux.configfile = + concat("pxelinux.cfg/", binary-to-ascii(16, 8, ":", hardware)); +filename "/tftpboot/pxelinux.bin"; +---- +If you used this from a client whose Ethernet address was +58:FA:84:CF:55:0E, this would look for a configuration file named +"/tftpboot/pxelinux.cfg/1:58:fa:84:cf:55:e". + + +== KNOWN ISSUES == +The following problems are known with PXELINUX, so far: + +- The error recovery routine doesn't work quite right. For right now, + it just does a hard reset - seems good enough. +- We should probably call the UDP receive function in the keyboard + entry loop, so that we answer ARP requests. +- Boot sectors/disk images are not supported yet. + +If you have additional problems, please contact the Syslinux mailing +list (see syslinux.txt for the address.) + +=== Broken PXE stacks === +Lots of PXE stacks, especially old ones, have various problems of +varying degrees of severity. Please see: + + http://syslinux.zytor.com/hardware.php + +... for a list of currently known hardware problems, with workarounds +if known. + +There are a number of extremely broken PXE stacks in the field. The +gPXE project (formerly known as Etherboot) provides an open-source PXE +stack that works with a number of cards, and which can be loaded from +a CD-ROM, USB key, or floppy if desired. + +Information on gPXE is available from: + + http://www.etherboot.org/ + +... and ready-to-use ROM or disk images from: + + http://www.rom-o-matic.net/ + +Some cards, like may systems with the SiS 900, has a PXE stack which +works just barely well enough to load a single file, but doesn't +handle the more advanced items required by PXELINUX. If so, it is +possible to use the built-in PXE stack to load gPXE, which can then +load PXELINUX. See: + + http://www.etherboot.org/wiki/pxechaining + + +== NOTES == +=== MTFTP === +PXELINUX does not support MTFTP, and there are no plans of doing so, as +MTFTP is inherently broken for files more than 65535 packets (about 92 +MB) in size. It is of course possible to use MTFTP for the initial +boot, if you have such a setup. MTFTP server setup is beyond the scope +of this document. + +=== Error Recovery === +If the boot fails, PXELINUX (unlike SYSLINUX) will not wait forever; +rather, if it has not received any input for approximately five +minutes after displaying an error message, it will reset the machine. +This allows an unattended machine to recover in case it had bad enough +luck of trying to boot at the same time the TFTP server goes down. + + +== SEE ALSO == +*syslinux.cfg*(5), *syslinux-cli*(1), *lilo*(8), *keytab-lilo.pl*(8), +*fdisk*(8), *mkfs*(8), *superformat*(1). + + +== AUTHOR == +This AsciiDoc derived document is a modified version of the original +*SYSLINUX* documentation by {author} <{author-email}>. The conversion +to an AsciiDoc was made by {editor1} <{editor1-email}> diff --git a/txt/syslinux-cli.txt b/txt/syslinux-cli.txt index fa6a4dc5..774e8e27 100644 --- a/txt/syslinux-cli.txt +++ b/txt/syslinux-cli.txt @@ -32,7 +32,7 @@ The command line prompt supports the following keystrokes: <Ctrl-F><digit> equivalent to F1..F10 <Ctrl-C> interrupt boot in progress <Esc> interrupt boot in progress - <Ctrl-N> display network information (PXELINUX only) + <Ctrl-N> display network information (PXELINUX only; 3.50-4.06) === WORKING DIRECTORY === @@ -59,6 +59,34 @@ the file is not found in the following order: .0[*PXELINUX* only], // Is this true of file names specified in a config? As of when? +=== PATH RULES === + +The current working directory is *always* searched first, before PATH, +when attempting to open a filename. The current working directory is +not affected when specifying a file with an absolute path. For +example, given the following file system layout, + +.... +/boot/ + /bin/ + ls.c32 + libls.c32 + /foo/ + libls.c32 +.... + +assuming that the current working directory is /boot/foo, and assuming +that libls.c32 is a dependency of ls.c32, executing /boot/bin/ls.c32 +will cause /boot/foo/libls.c32 to be loaded, not /boot/bin/libls.c32, +even if /boot/bin is specified in the PATH directive of a config file. + +The reason that things work this way is that typically a user will +install all library files in the Syslinux installation directory, as +specified with the --directory installer option. This method allows +the user to omit the PATH directive from their config file and still +have things work correctly. + + == AUTHOR == This AsciiDoc derived document is a modified version of the original *SYSLINUX* documentation by {author} <{author-email}>. The conversion diff --git a/txt/syslinux.cfg.txt b/txt/syslinux.cfg.txt index 16abe0e2..ff5d5337 100644 --- a/txt/syslinux.cfg.txt +++ b/txt/syslinux.cfg.txt @@ -57,9 +57,10 @@ file. Files can currently be nested up to 16 levels deep, but it is not guaranteed that more than 8 levels will be supported in the future. *DEFAULT* 'kernel' 'options...':: -Sets the default command line. If *Syslinux* boots automatically, it -will act just as if the entries after *DEFAULT* had been typed in at the -'boot:' prompt. Multiple uses will result in an override. +Sets the default command line (which often references a LABEL). If +*Syslinux* boots automatically, it will act just as if the entries after +*DEFAULT* had been typed in at the 'boot:' prompt. Multiple uses will +result in an override. + If no configuration file is present, or no *DEFAULT* or *UI* entry is present in the config file, an error message is displayed and the @@ -69,8 +70,9 @@ present in the config file, an error message is displayed and the Selects a specific user interface 'module' (typically menu.c32 or vesamenu.c32). The command-line interface treats this as a directive that overrides the *DEFAULT* directive to load this module instead at -startup and for an empty command line and *PROMPT* directive to not -prompt. Multiple uses will result in an override. +startup, for an empty command line and at timeout and *PROMPT* directive +to not prompt (but these directives may have effects on other +configuration parsers). Multiple uses will result in an override. *LABEL* 'mylabel':: Begin a new *LABEL* clause. If 'mylabel' is entered as the kernel to @@ -121,14 +123,17 @@ Append nothing. *APPEND* with a single hyphen as argument in a *LABEL* section can be used to override a global *APPEND*. //[FIXME: Shorten subdefinitions] -*IPAPPEND* 'flag_val':: -(*PXELINUX* only) The *IPAPPEND* option is available only on *PXELINUX*. - The flag_val is an OR (sum) of the following integer options: +*SYSAPPEND* 'bitmask':: +*IPAPPEND* 'bitmask':: +(*SYSAPPEND*: 5.10+; *IPAPPEND*: *PXELINUX* only) +The *SYSAPPEND* option was introduced in *Syslinux* 5.10; it is an +enhancement of a previous option *IPAPPEND* which was only available on +*PXELINUX*. The 'bitmask' is an OR (sum) of the following integer options: ifndef::doctype-manpage[[horizontal]] *1*::: An option of the following format should be generated, based on the input from the DHCP/BOOTP or PXE boot server and added to the kernel -command line(see note below): +command line(see note below; empty for non-PXELINUX variants): + ---- ip=<client-ip>:<boot-server-ip>:<gw-ip>:<netmask> @@ -144,7 +149,7 @@ server. dash-separated hexadecimal with leading hardware type (same as for the configuration file; see pxelinux.txt.) and added to the kernel command line, allowing an initrd program to determine from which interface the -system booted: +system booted(empty for non-PXELINUX variants): + ---- BOOTIF=<hardware-address-of-boot-interface> @@ -158,6 +163,83 @@ line: ---- SYSUUID=<system uuid> ---- ++ +*8*::: (5.10+) indicate the CPU family and certain particularly +significant CPU feature bits: ++ +---- +CPU=<family><features> +---- ++ +The <family> is a single digit from 3 (i386) to 6 (i686 or higher.) The +following CPU features are currently reported; additional flags may be +added in the future: ++ +.... +P Physical Address Extension (PAE) +V Intel Virtualization Technology (VT/VMX) +T Intel Trusted Exection Technology (TXT/SMX) +X Execution Disable (XD/NX) +L Long Mode (x86-64) +S AMD SMX virtualization +.... ++ +*DMI*::: (5.10+) The following strings are derived from DMI/SMBIOS +information if available: ++ + Bit String Significance + ------------------------------------------------------------- + 0x00010 SYSVENDOR= System vendor name + 0x00020 SYSPRODUCT= System product name + 0x00040 SYSVERSION= System version + 0x00080 SYSSERIAL= System serial number + 0x00100 SYSSKU= System SKU + 0x00200 SYSFAMILY= System family + 0x00400 MBVENDOR= Motherboard vendor name + 0x00800 MBVERSION= Motherboard version + 0x01000 MBSERIAL= Motherboard serial number + 0x02000 MBASSET= Motherboard asset tag + 0x04000 BIOSVENDOR= BIOS vendor name + 0x08000 BIOSVERSION= BIOS version + 0x10000 SYSFF= System form factor ++ +If these strings contain white-space characters, they are replaced with +underscores (_). ++ +The system form factor value is a number defined in the SMBIOS +specification, available at http://www.dmtf.org/. As of version 2.7.1 +of the specification, the following values are defined: ++ + 1 Other + 2 Unknown + 3 Desktop + 4 Low profile desktop + 5 Pizza box + 6 Mini tower + 7 Tower + 8 Portble + 9 Laptop + 10 Notebook + 11 Handheld + 12 Docking station + 13 All-in-one + 14 Subnotebook + 15 Space-saving + 16 Lunch box + 17 Main server chassis + 18 Expansion chassis + 19 Subchassis + 20 Bus expansion chassis + 21 Peripheral chassis + 22 RAID chassis + 23 Rack mount chasss + 24 Sealed-case PC + 25 Multi-system chassis + 26 Compact PCI + 27 Advanced TCI + 28 Blade + 29 Blade enclosure + == KERNEL-LIKE DIRECTIVES == @@ -249,15 +331,16 @@ explicitly named in a *LABEL* statement. The default is 1. Indicates how long to wait at the 'boot:' prompt until booting automatically, in units of 1/10 s. The timeout is cancelled as soon as the user types anything on the keyboard, the assumption being that the -user will complete the command line already begun. A timeout of zero -(the default) will disable the timeout completely. +user will complete the command line already begun. The timer is reset +to 0 upon return from an unsuccessful attempt to boot or from a module. +A timeout of zero (the default) will disable the timeout completely. *TOTALTIMEOUT* 'timeout':: Indicates how long to wait until booting automatically, in units of 1/10 s. This timeout is *not* cancelled by user input, and can thus be used to deal with serial port glitches or "the user walked away" type -situations. A timeout of zero will disable the timeout completely, this -is also the default. +situations. A timeout of zero (the default) will disable the timeout +completely. + Both *TIMEOUT* and *TOTALTIMEOUT* can be used together, for example: + @@ -270,9 +353,8 @@ TOTALTIMEOUT 9000 // FIXME: be consistent *ONTIMEOUT* 'kernel options...':: -Sets the command line invoked on a timeout. Normally this is the same -thing as invoked by 'DEFAULT'. If this is specified, then 'DEFAULT' is -used only if the user presses <Enter> to boot. +Sets the command line invoked on a timeout (which often references a +LABEL). If not specified, 'UI' (if used) or 'DEFAULT is used. *ONERROR* 'kernel options...':: If a kernel image is not found (either due to it not existing, or @@ -296,7 +378,7 @@ foo bar baz xyzzy plugh foo bar baz ---- -*SERIAL* 'port [[baudrate] flowcontrol]':: +*SERIAL* 'port [baudrate [flowcontrol]]':: Enables a serial port to act as the console. 'port' is a number (0 = /dev/ttyS0 = COM1, etc.) or an I/O port address (e.g. 0x3F8); if 'baudrate' is omitted, the baud rate defaults to 9600 bps. The serial @@ -341,6 +423,9 @@ values 0x3F8, 0x2F8, 0x3E8, 0x2E8. Enabling interrupts (setting the 0x008 bit) may give better responsiveness without setting the *NOHALT* option, but could potentially cause problems with buggy BIOSes. ++ +This option is "sticky" and is not automatically reset when loading a +new configuration file with the CONFIG command. *NOHALT* 'flag_val':: If 'flag_val' is 1, don't halt the processor while idle. Halting the @@ -424,10 +509,24 @@ screens, e.g. <Ctrl-F><2> to get to the F2 screen. For F10-F12, hit versions, F10 can also be entered as <Ctrl-F>0. *PATH* 'path':: -(5.00+) Specify a colon-separated (':') list of directories to search when -attempting to load modules. This directive is useful for specifying the -directories containing the lib*.c32 library files as other modules may -be dependent on these files, but may not reside in the same directory. +(5.00+) Specify a space-separated (' '; 5.00-5.10 was a colon ':') list +of directories to search when attempting to load modules. This directive +is useful for specifying the directories containing the lib*.c32 library +files as other modules may be dependent on these files, but may not +reside in the same directory. Multiple instances will append additional +paths. + +*SENDCOOKIES* 'bitmask':: +(*PXELINUX* 5.10+) When downloading files over http, the SYSAPPEND +strings are prepended with _Syslinux_ and sent to the server as cookies. +The cookies are URL-encoded; whitespace is *not* replaced with +underscores. ++ +This command limits the cookies send; 0 means no cookies. The default +is -1, meaning send all cookies. ++ +This option is "sticky" and is not automatically reset when loading a +new configuration file with the CONFIG command. == DISPLAY FILE FORMAT == @@ -557,6 +656,30 @@ if so is convenient; *Syslinux* ignores all file attributes. The *SYSLINUX* installer automatically sets the readonly/hidden/system attributes on LDLINUX.SYS. +== EXAMPLE == +Here are some sample config files: +---- +# SERIAL 0 115200 +DEFAULT linux +PROMPT 1 +TIMEOUT 600 + +LABEL linux + LINUX vmlinuz + APPEND initrd=initrd1.gz,initrd2.gz + +LABEL m + COM32 menu.c32 +---- +In this example, serial port use is disabled but can be enabled by +uncommenting the first line and utilize serial port 0 at 115200 bps. If +'linux' is typed on the command line, the kernel-like file 'vmlinuz' is +executed as a Linux kernel, initrd files initrd1.gz and initrd2.gz are +loaded as initial ramdisk files (like cpio.gz files for initramfs). If +'m' is typed on the command line, the COM32 module 'menu.c32' is +executed to launch a menu system. + + == KNOWN BUGS == include::com-bug.txt[] diff --git a/txt/syslinux.txt b/txt/syslinux.txt index 33b03d71..59666635 100644 --- a/txt/syslinux.txt +++ b/txt/syslinux.txt @@ -1,11 +1,11 @@ = syslinux(1) = :doctype: manpage -:revdate: 2012-10-28 +:revdate: 2013-06-12 :author: H. Peter Anvin :author-email: hpa@zytor.com :editor1: Gene Cumm :editor1-email: gene.cumm@gmail.com -:editor1-revlast: 2012-10-28 +:editor1-revlast: 2013-06-12 == NAME == @@ -16,8 +16,8 @@ syslinux - Install SYSLINUX to a file system [verse] *syslinux* ['OPTIONS'] 'DEVICE' *extlinux* ['OPTIONS'] 'PATH' -*syslinux* [-h | --help] -*extlinux* [-h | --help] +*syslinux* [-h | --help | -v | --version] +*extlinux* [-h | --help | -v | --version] == DESCRIPTION == @@ -47,7 +47,8 @@ Please note, the ldlinux.sys boot loader file is flagged as immutable (where applicable) and is modified after copying in to help ensure boot-time integrity. File systems with a sufficiently large boot loader reserved area, like btrfs, will have ldlinux.sys installed there rather -than as a normal file. +than as a normal file. Prior to version 4.00, extlinux would install a +file extlinux.sys which versions 4.00 and later installers will replace with ldlinux.sys. == OPTIONS == @@ -190,7 +191,8 @@ the partition as active. For altmbr.bin, an easy way to overwrite the MBR boot block and specify the partion number is: + - printf '\1' | cat altmbr.bin - | dd bs=440 count=1 iflag=fullblock conv=notrunc of=/dev/sda + printf '\1' | cat altmbr.bin - | dd bs=440 count=1 \ + iflag=fullblock conv=notrunc of=/dev/sda + Note: using 'cat' for writing the MBR can under some circumstances cause data loss or overwritting. For this reason, using 'dd' is recommended |