diff options
Diffstat (limited to 'txt')
-rw-r--r-- | txt/isolinux.txt | 116 | ||||
-rw-r--r-- | txt/pxelinux.txt | 461 |
2 files changed, 577 insertions, 0 deletions
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}> |