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