Put in remaining pages and wiki contents.

[ikiwiki.git] / docs / handbook / handbook-network-diskless.mdwn

\r
\r
## 19.7 Diskless Operation \r
\r
***Updated by Jean-Fran�ois Dock�s. ******Reorganized and enhanced by Alex Dupre. ***\r
\r
A DragonFly machine can boot over the network and operate without a local disk, using filesystems mounted from an NFS server. No system modification is necessary, beyond standard configuration files. Such a system is relatively easy to set up because all the necessary elements are readily available:\r
\r

* There are at least two possible methods to load the kernel over the network:\r

* PXE: The Intel® Preboot Execution Environment system is a form of smart boot ROM built into some networking cards or motherboards. See [pxeboot(8)](http://leaf.dragonflybsd.org/cgi/web-man?command#pxeboot&section8) for more details.\r

* The  **etherboot**  port ([`net/etherboot`](http://pkgsrc.se/net/etherboot)) produces ROM-able code to boot kernels over the network. The code can be either burnt into a boot PROM on a network card, or loaded from a local floppy (or hard) disk drive, or from a running MS-DOS® system. Many network cards are supported.\r

* A sample script (`/usr/share/examples/diskless/clone_root`) eases the creation and maintenance of the workstation's root filesystem on the server. The script will probably require a little customization but it will get you started very quickly.\r

* Standard system startup files exist in `/etc` to detect and support a diskless system startup.\r

* Swapping, if needed, can be done either to an NFS file or to a local disk.\r
\r
There are many ways to set up diskless workstations. Many elements are involved, and most can be customized to suit local taste. The following will describe variations on the setup of a complete system, emphasizing simplicity and compatibility with the standard DragonFly startup scripts. The system described has the following characteristics:\r
\r

* The diskless workstations use a shared read-only `root` filesystem, and a shared read-only `/usr`.\r
  The `root` filesystem is a copy of a standard DragonFly root (typically the server's), with some configuration files overridden by ones specific to diskless operation or, possibly, to the workstation they belong to.\r
  The parts of the `root` which have to be writable are overlaid with [mfs(8)](http://leaf.dragonflybsd.org/cgi/web-man?command#mfs&section8) filesystems. Any changes will be lost when the system reboots.\r

* The kernel is transferred and loaded either with  **etherboot**  or PXE as some situations may mandate the use of either method.\r
\r
 **Caution:** As described, this system is insecure. It should live in a protected area of a network, and be untrusted by other hosts.\r
\r
### 19.7.1 Background Information \r
\r
Setting up diskless workstations is both relatively straightforward and prone to errors. These are sometimes difficult to diagnose for a number of reasons. For example:\r
\r

* Compile time options may determine different behaviours at runtime.\r

* Error messages are often cryptic or totally absent.\r
\r
In this context, having some knowledge of the background mechanisms involved is very useful to solve the problems that may arise.\r
\r
Several operations need to be performed for a successful bootstrap:\r
\r

* The machine needs to obtain initial parameters such as its IP address, executable filename, server name, root path. This is done using the DHCP or BOOTP protocols. DHCP is a compatible extension of BOOTP, and uses the same port numbers and basic packet format.\r
  It is possible to configure a system to use only BOOTP. The [bootpd(8)](http://leaf.dragonflybsd.org/cgi/web-man?command#bootpd&section8) server program is included in the base DragonFly system.\r
  However, DHCP has a number of advantages over BOOTP (nicer configuration files, possibility of using PXE, plus many others not directly related to diskless operation), and we will describe mainly a DHCP configuration, with equivalent exemples using [bootpd(8)](http://leaf.dragonflybsd.org/cgi/web-man?command#bootpd&section8) when possible. The sample configuration will use the  **ISC DHCP**  software package (release 3.0.1.r12 was installed on the test server).\r

* The machine needs to transfer one or several programs to local memory. Either TFTP or NFS are used. The choice between TFTP and NFS is a compile time option in several places. A common source of error is to specify filenames for the wrong protocol: TFTP typically transfers all files from a single directory on the server, and would expect filenames relative to this directory. NFS needs absolute file paths.\r

* The possible intermediate bootstrap programs and the kernel need to be initialized and executed. There are several important variations in this area:\r

* PXE will load [pxeboot(8)](http://leaf.dragonflybsd.org/cgi/web-man?command#pxeboot&section8), which is a modified version of the DragonFly third stage loader. The [loader(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=loader&section=8) will obtain most parameters necessary to system startup, and leave them in the kernel environment before transferring control. It is possible to use a `GENERIC` kernel in this case.\r

*  **etherboot** , will directly load the kernel, with less preparation. You will need to build a kernel with specific options.\r

* Finally, the machine needs to access its filesystems. NFS is used in all cases.\r
\r
See also [diskless(8)](http://leaf.dragonflybsd.org/cgi/web-man?command#diskless&section8) manual page.\r
\r
### 19.7.2 Setup Instructions \r
\r
#### 19.7.2.1 Configuration Using  **ISC DHCP**  \r
\r
The  **ISC DHCP**  server can answer both BOOTP and DHCP requests.\r
\r
 **ISC DHCP**  needs a configuration file to run, (normally named `/usr/local/etc/dhcpd.conf`). Here follows a commented example, where host `margaux` uses  **etherboot**  and host `corbieres` uses PXE:\r
\r
    \r
    default-lease-time 600;\r
    max-lease-time 7200;\r
    authoritative;\r
    \r
    option domain-name "example.com";\r
    option domain-name-servers 192.168.4.1;\r
    option routers 192.168.4.1;\r
    \r
    subnet 192.168.4.0 netmask 255.255.255.0 {\r
      use-host-decl-names on; ./imagelib/callouts/1.png\r
      option subnet-mask 255.255.255.0;\r
      option broadcast-address 192.168.4.255;\r
    \r
      host margaux {\r
        hardware ethernet 01:23:45:67:89:ab;\r
        fixed-address margaux.example.com;\r
        next-server 192.168.4.4; ./imagelib/callouts/2.png\r
        filename "/data/misc/kernel.diskless"; ./imagelib/callouts/3.png\r
        option root-path "192.168.4.4:/data/misc/diskless"; ./imagelib/callouts/4.png\r
      }\r
      host corbieres {\r
        hardware ethernet 00:02:b3:27:62:df;\r
        fixed-address corbieres.example.com;\r
        next-server 192.168.4.4;\r
        filename "pxeboot";\r
        option root-path "192.168.4.4:/data/misc/diskless";\r
      }\r
    }\r
    \r
\r
\r
[network-diskless.html#CO-DHCP-HOST-NAME ./imagelib/callouts/1.png]:: This option tells  **dhcpd**  to send the value in the `host` declarations as the hostname for the diskless host. An alternate way would be to add an `option host-name `***margaux****** inside the host declarations.[network-diskless.html#CO-DHCP-NEXT-SERVER ./imagelib/callouts/2.png]:: The `next-server` directive designates the TFTP or NFS server to use for loading loader or kernel file (the default is to use the same host as the DHCP server).[network-diskless.html#CO-DHCP-FILENAME ./imagelib/callouts/3.png]:: The `filename` directive defines the file that  **etherboot**  or PXE will load for the next execution step. It must be specified according to the transfer method used.  **etherboot**  can be compiled to use NFS or TFTP. The DragonFly port configures NFS by default. PXE uses TFTP, which is why a relative filename is used here (this may depend on the TFTP server configuration, but would be fairly typical). Also, PXE loads `pxeboot`, not the kernel. There are other interesting possibilities, like loading `pxeboot` from a DragonFly CD-ROM `/boot` directory (as [pxeboot(8)](http://leaf.dragonflybsd.org/cgi/web-man?command#pxeboot&section8) can load a `GENERIC` kernel, this makes it possible to use PXE to boot from a remote CD-ROM).[network-diskless.html#CO-DHCP-ROOT-PATH ./imagelib/callouts/4.png]:: The `root-path` option defines the path to the root filesystem, in usual NFS notation. When using PXE, it is possible to leave off the host's IP as long as you do not enable the kernel option BOOTP. The NFS server will then be the same as the TFTP one.\r
\r
#### 19.7.2.2 Configuration Using BOOTP \r
\r
Here follows an equivalent  **bootpd**  configuration (reduced to one client). This would be found in `/etc/bootptab`.\r
\r
Please note that  **etherboot**  must be compiled with the non-default option `NO_DHCP_SUPPORT` in order to use BOOTP, and that PXE ***needs*** DHCP. The only obvious advantage of  **bootpd**  is that it exists in the base system.\r
\r
    \r
    .def100:\\r
      :hn:ht#1:sa192.168.4.4:vm=rfc1048:\\r
      :sm=255.255.255.0:\\r
      :ds=192.168.4.1:\\r
      :gw=192.168.4.1:\\r
      :hd="/tftpboot":\\r
      :bf="/kernel.diskless":\\r
      :rp="192.168.4.4:/data/misc/diskless":\r
    \r
    margaux:ha#0123456789ab:tc.def100\r
    \r
\r
\r
#### 19.7.2.3 Booting with PXE \r
\r
By default, the [pxeboot(8)](http://leaf.dragonflybsd.org/cgi/web-man?command#pxeboot&section8) loader loads the kernel via NFS. It can be compiled to use TFTP instead by specifying the `LOADER_TFTP_SUPPORT` option in `/etc/make.conf`. See the comments in `/etc/defaults/make.conf` (or `/usr/share/examples/etc/make.conf` for 5.X systems) for instructions.\r
\r
There are two other undocumented `make.conf` options which may be useful for setting up a serial console diskless machine: `BOOT_PXELDR_PROBE_KEYBOARD`, and `BOOT_PXELDR_ALWAYS_SERIAL`.\r
\r
To use PXE when the machine starts, you will usually need to select the `Boot from network` option in your BIOS setup, or type a function key during the PC initialization.\r
\r
#### 19.7.2.4 Configuring the TFTP and NFS Servers \r
\r
If you are using PXE or  **etherboot**  configured to use TFTP, you need to enable  **tftpd**  on the file server:\r
\r
  1. Create a directory from which  **tftpd**  will serve the files, e.g. `/tftpboot`.\r
  1. Add this line to your `/etc/inetd.conf`:\r
      \r
      tftp      dgram   udp     wait    root    /usr/libexec/tftpd      tftpd -l -s /tftpboot\r
  \r
   **Note:** It appears that at least some PXE versions want the TCP version of TFTP. In this case, add a second line, replacing `dgram udp` with `stream tcp`.\r
  1. Tell  **inetd**  to reread its configuration file:\r
      \r
      # kill -HUP `cat /var/run/inetd.pid`\r
  \r
\r
You can place the `tftpboot` directory anywhere on the server. Make sure that the location is set in both `inetd.conf` and `dhcpd.conf`.\r
\r
In all cases, you also need to enable NFS and export the appropriate filesystem on the NFS server.\r
\r
  1. Add this to `/etc/rc.conf`:\r
      \r
      nfs_server_enable="YES"\r
  \r
  1. Export the filesystem where the diskless root directory is located by adding the following to `/etc/exports` (adjust the volume mount point and replace `***margaux corbieres***` with the names of the diskless workstations):\r
      \r
      `***/data/misc***` -alldirs -ro `***margaux corbieres***`\r
  \r
  1. Tell  **mountd**  to reread its configuration file. If you actually needed to enable NFS in `/etc/rc.conf` at the first step, you probably want to reboot instead.\r
      \r
      # kill -HUP `cat /var/run/mountd.pid`\r
  \r
\r
#### 19.7.2.5 Building a Diskless Kernel \r
\r
If using  **etherboot** , you need to create a kernel configuration file for the diskless client with the following options (in addition to the usual ones):\r
\r
    \r
    options     BOOTP          # Use BOOTP to obtain IP address/hostname\r
    options     BOOTP_NFSROOT  # NFS mount root filesystem using BOOTP info\r
    \r
\r
\r
You may also want to use `BOOTP_NFSV3`, `BOOT_COMPAT` and `BOOTP_WIRED_TO` (refer to `LINT`.\r
\r
These option names are historical and slightly misleading as they actually enable indifferent use of DHCP and BOOTP inside the kernel (it is also possible to force strict BOOTP or DHCP use).\r
\r
Build the kernel (see [kernelconfig.html Chapter 9]), and copy it to the place specified in `dhcpd.conf`.\r
\r
 **Note:** When using PXE, building a kernel with the above options is not strictly necessary (though suggested). Enabling them will cause more DHCP requests to be issued during kernel startup, with a small risk of inconsistency between the new values and those retrieved by [pxeboot(8)](http://leaf.dragonflybsd.org/cgi/web-man?command#pxeboot&section8) in some special cases. The advantage of using them is that the host name will be set as a side effect. Otherwise you will need to set the host name by another method, for example in a client-specific `rc.conf` file.\r
\r
#### 19.7.2.6 Preparing the Root Filesystem \r
\r
You need to create a root filesystem for the diskless workstations, in the location listed as `root-path` in `dhcpd.conf`. The following sections describe two ways to do it.\r
\r
##### 19.7.2.6.1 Using the `clone_root` Script \r
\r
This is the quickest way to create a root filesystem. but This shell script is located at `/usr/share/examples/diskless/clone_root` and needs customization, at least to adjust the place where the filesystem will be created (the `DEST` variable).\r
\r
Refer to the comments at the top of the script for instructions. They explain how the base filesystem is built, and how files may be selectively overridden by versions specific to diskless operation, to a subnetwork, or to an individual workstation. They also give examples for the diskless `/etc/fstab` and ` /etc/rc.conf` files.\r
\r
The `README` files in `/usr/share/examples/diskless` contain a lot of interesting background information, but, together with the other examples in the `diskless` directory, they actually document a configuration method which is distinct from the one used by `clone_root` and the system startup scripts in `/etc`, which is a little confusing. Use them for reference only, except if you prefer the method that they describe, in which case you will need customized `rc` scripts.\r
\r
##### 19.7.2.6.2 Using the Standard `make world` Procedure \r
\r
This method will install a complete virgin system (not only the root filesystem) into `DESTDIR`. All you have to do is simply execute the following script:\r
\r
    \r
    #!/bin/sh\r
    export DESTDIR=/data/misc/diskless\r
    mkdir -p ${DESTDIR}\r
    cd /usr/src; make world && make kernel\r
    cd /usr/src/etc; make distribution\r
\r
\r
Once done, you may need to customize your `/etc/rc.conf` and `/etc/fstab` placed into `DESTDIR` according to your needs.\r
\r
#### 19.7.2.7 Configuring Swap \r
\r
If needed, a swap file located on the server can be accessed via NFS.\r
\r
##### 19.7.2.7.1 NFS Swap with DragonFly \r
\r
The swap file location and size can be specified with BOOTP/DHCP DragonFly-specific options 128 and 129. Examples of configuration files for ***'ISC DHCP 3.0 ** or** bootpd***' follow:\r
\r
  1. Add the following lines to `dhcpd.conf`:\r
      \r
      # Global section\r
      option swap-path code 128 = string;\r
      option swap-size code 129 = integer 32;\r
      host margaux {\r
        ... # Standard lines, see above\r
        option swap-path `***"192.168.4.4:/netswapvolume/netswap"***`;\r
        option swap-size `***64000***`;\r
      }\r
  \r
  `swap-path` is the path to a directory where swap files will be located. Each file will be named `swap.`***client-ip******.\r
  Older versions of  **dhcpd**  used a syntax of `option option-128 "...`, which is no longer supported.\r
  `/etc/bootptab` would use the following syntax instead:\r
      \r
      T128#"192.168.4.4:/netswapvolume/netswap":T1290000fa00\r
  \r
   **Note:** In `/etc/bootptab`, the swap size must be expressed in hexadecimal format.\r
  1. On the NFS swap file server, create the swap file(s)\r
      \r
      # mkdir `***/netswapvolume/netswap***`\r
      # cd `***/netswapvolume/netswap***`\r
      # dd if#/dev/zero bs1024 count=`***64000***` of=swap.`***192.168.4.6***`\r
      # chmod 0600 swap.`***192.168.4.6***`\r
  \r
  `***192.168.4.6***` is the IP address for the diskless client.\r
  1. On the NFS swap file server, add the following line to `/etc/exports`:\r
      \r
      `***/netswapvolume***`  -maproot=0:10 -alldirs `***margaux corbieres***`\r
  \r
  Then tell  **mountd**  to reread the exports file, as above.\r
\r
#### 19.7.2.8 Miscellaneous Issues \r
\r
##### 19.7.2.8.1 Running with a Read-only `/usr` \r
\r
If the diskless workstation is configured to run X, you will have to adjust the xdm configuration file, which puts the error log on `/usr` by default.\r
\r
##### 19.7.2.8.2 Using a Non-DragonFly Server \r
\r
When the server for the root filesystem is not running DragonFly, you will have to create the root filesystem on a DragonFly machine, then copy it to its destination, using `tar` or `cpio`.\r
\r
In this situation, there are sometimes problems with the special files in `/dev`, due to differing major/minor integer sizes. A solution to this problem is to export a directory from the non-DragonFly server, mount this directory onto a DragonFly machine, and run `MAKEDEV` on the DragonFly machine to create the correct device entries.\r
\r
\r
\r
CategoryHandbook\r
CategoryHandbook-advancednetworking\r