share/examples/diskless/README.BOOTP

   1 IMPORTANT NOTE:
   2
   3 As of Feb. 11, 2002 (and indeed, for quite some time before that),
   4 the /etc/rc.diskless{1,2} scripts support a slightly different
   5 diskless boot process than the one documented in the rest of
   6 this file (which is 3 years old).
   7
   8 I am not deleting the information below because it contains some
   9 useful background information on diskless operation, but for the
  10 actual details you should look at /etc/rc.diskless1, /etc/rc.diskless2,
  11 and the /usr/share/examples/diskless/clone_root script which can
  12 be useful to set up clients and server for diskless boot.
  13
  14 --- $FreeBSD$ ---
  15 ------------------------------------------------------------------------
  16
  17                         BOOTP configuration mechanism
  18
  19                             Matthew Dillon
  20                             dillon@backplane.com
  21
  22     BOOTP kernels automatically configure the machine's IP address, netmask,
  23     optional NFS based swap, and NFS based root mount.  The NFS server will
  24     typically export a shared read-only /, /usr, and /var to any number of
  25     workstations.  The shared read-only root is typically either the server's
  26     own root or, if you are more security conscious, a contrived root.
  27
  28     The key issue with starting up a BOOTP kernel is that you typically want
  29     to export read-only NFS partitions from the server, yet still be able to
  30     customize each workstation ( or not ).
  31
  32     /etc/rc.diskless1 is responsible for doing core mounts and for retargeting
  33     /conf/ME ( part of the read-only root NFS mount ) to /conf/$IP_OF_CLIENT.
  34     /etc/rc.conf.local and /etc/rc.local, along with other machine-specific
  35     configuration files, are typically softlinks to /conf/ME/<filename>.
  36
  37     In the BOOTP workstation /conf/$IP/rc.conf.local, you must typically
  38     turn *OFF* most of the system option defaults in /etc/rc.conf as well
  39     as do additional custom configuration of your environment
  40
  41     The /usr/src/share/examples/diskless directory contains a typical
  42     X session / sshd based workstation configuration.  The directories
  43     involved are HT.DISKLESS/ and 192.157.86.12/.
  44
  45     Essentially, the $IP/ directory ( which rc.diskless looks for in
  46     /conf/$IP/ ) contains all the junk.  The HT.DISKLESS directory exists
  47     to hold common elements of your custom configuration so you do not have
  48     to repeat those elements for each workstation.  The example /conf
  49     structure included here shows how to create a working sshd setup ( so
  50     you can sshd into the diskless workstation ), retarget xdm's pid and error
  51     files to R+W directories if /usr is mounted read-only, and retarget
  52     syslogd and other programs.  This example is not designed to run out of
  53     the box and some modifications are required.
  54
  55     >> NOTE <<  HT.DISKLESS/ttys contains the typical configuration required
  56     to bring X up at boot time.  Essentially, it runs xdm in the foreground
  57     with the appropriate arguments rather then a getty on ttyv0.  You must
  58     run xdm on ttyv0 in order to prevent xdm racing with getty on a virtual
  59     terminal.  Such a race can cause your keyboard to be directed away from
  60     the X session, essentially making the session unusable.
  61
  62     Typically you should start with a clean slate by tar-copying this example
  63     directory to /conf and then hack on it in /conf rather then in
  64     /usr/share/examples/diskless.
  65
  66                                 BOOTP CLIENT SETUP
  67
  68     Here is a typical kernel configuration.  If you have only one ethernet
  69     interface you do not need to wire BOOTP to a specific interface name.
  70     BOOTP requires NFS and NFS_ROOT, and our boot scripts require MFS.  If
  71     your /tmp is *not* a softlink to /var/tmp, the scripts also require NULLFS
  72
  73 # BootP
  74 #
  75 options         BOOTP           # Use BOOTP to obtain IP address/hostname
  76 options         BOOTP_NFSROOT   # NFS mount root filesystem using BOOTP info
  77 options         "BOOTP_NFSV3"   # Use NFS v3 to NFS mount rootoptions
  78 options         BOOTP_COMPAT    # Workaround for broken bootp daemons.
  79 #options         "BOOTP_WIRED_TO=de0"
  80
  81 options         MFS                     # Memory File System
  82 options         NFS                     # Network Filesystem
  83 options         NFS_ROOT                # Nfs can be root
  84 options         NULLFS                  # nullfs to map /var/tmp to /tmp
  85
  86                                 BOOTP SERVER SETUP
  87
  88     The BOOTP server must be running on the same logical LAN as the the
  89     BOOTP client(s).  You need to setup two things:
  90
  91     (1) You need to NFS-export /, /usr, and /var.
  92
  93     (2) You need to run a BOOTP server.  DHCPD can do this.
  94
  95
  96     NFS Export:
  97
  98         Here is an example "/etc/exports" file.
  99
 100 / -ro -maproot=root: -network 192.157.86.0 -mask 255.255.255.192
 101 /usr -ro -maproot=root: -network 192.157.86.0 -mask 255.255.255.192
 102 /var -ro -maproot=root: -network 192.157.86.0 -mask 255.255.255.192
 103
 104     In order to be an NFS server, the server must run portmap, mountd,
 105     nfsd, and rpc.statd.  The standard NFS server options in /etc/rc.conf
 106     will work ( you should put your overrides in /etc/rc.conf.local on the
 107     server and not edit the distribution /etc/rc.conf, though ).
 108
 109     BOOTP Server:
 110
 111         This configuration file "/etc/dhcpd.conf" example is for
 112         the '/usr/ports/net/isc-dhcp' dhcpd port.
 113
 114             subnet 192.157.86.0 netmask 255.255.255.192 {
 115                 # range if you want to run the core dhcpd service of
 116                 # dynamic IP assignment, but it is not used with BOOTP
 117                 # workstations
 118                 range 192.157.86.32 192.157.86.62;
 119
 120                 # misc configuration.
 121                 #
 122                 option routers 192.157.86.2;
 123                 option domain-name-servers 192.157.86.2;
 124
 125                 server-name "apollo.fubar.com";
 126                 option subnet-mask 255.255.255.192;
 127                 option domain-name-servers 192.157.86.2;
 128                 option domain-name "fubar.com";
 129                 option broadcast-address 192.157.86.63;
 130                 option routers 192.157.86.2;
 131             }
 132
 133             host test1 {
 134                 hardware ethernet 00:a0:c9:d3:38:25;
 135                 fixed-address 192.157.86.11;
 136                 option root-path "192.157.86.2:/";
 137                 option option-128 "192.157.86.2:/images/swap";
 138             }
 139
 140             host test2 {
 141             #    hardware ethernet 00:e0:29:1d:16:09;
 142                 hardware ethernet 00:10:5a:a8:94:0e;
 143                 fixed-address 192.157.86.12;
 144                 option root-path "192.157.86.2:/";
 145                 option option-128 "192.157.86.2:/images/swap";
 146             }
 147
 148     SWAP.  This example includes options to automatically BOOTP configure
 149     NFS swap on each workstation.  In order to use this capabilities you
 150     need to NFS-export a swap directory READ+WRITE to the workstations.
 151
 152     You must then create a swap directory for each workstation you wish to
 153     assign swap to.  In this example I created a dummy user 'lander' and
 154     did an NFS export of /images/swap enforcing a UID of 'lander' for
 155     all accesses.
 156
 157         apollo:/usr/ports/net# ls -la /images/swap
 158         total 491786
 159         drwxr-xr-x  2 root    wheel        512 Dec 28 07:00 .
 160         drwxr-xr-x  8 root    wheel        512 Jan 20 10:54 ..
 161         -rw-r--r--  1 lander  wheel   33554432 Dec 23 14:35 swap.192.157.86.11
 162         -rw-r--r--  1 lander  wheel  335544320 Jan 24 16:55 swap.192.157.86.12
 163         -rw-r--r--  1 lander  wheel  134217728 Jan 21 17:19 swap.192.157.86.6
 164
 165     A swap file is best created with dd:
 166
 167         # create a 32MB swap file for a BOOTP workstation
 168         dd if=/dev/zero of=swap.IPADDRESS bs=1m count=32
 169
 170     It is generally a good idea to give your workstations some swap space,
 171     but not a requirement if they have a lot of memory.
 172