| diskless.8 (107788) | diskless.8 (108228) |
|---|---|
| 1.\" Copyright (c) 1994 Gordon W. Ross, Theo de Raadt 2.\" Updated by Luigi Rizzo 3.\" All rights reserved. 4.\" 5.\" Redistribution and use in source and binary forms, with or without 6.\" modification, are permitted provided that the following conditions 7.\" are met: 8.\" 1. Redistributions of source code must retain the above copyright --- 10 unchanged lines hidden (view full) --- 19.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, 20.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 21.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 22.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 23.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 24.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF 25.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 26.\" | 1.\" Copyright (c) 1994 Gordon W. Ross, Theo de Raadt 2.\" Updated by Luigi Rizzo 3.\" All rights reserved. 4.\" 5.\" Redistribution and use in source and binary forms, with or without 6.\" modification, are permitted provided that the following conditions 7.\" are met: 8.\" 1. Redistributions of source code must retain the above copyright --- 10 unchanged lines hidden (view full) --- 19.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, 20.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 21.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 22.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 23.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 24.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF 25.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 26.\" |
| 27.\" $FreeBSD: head/share/man/man8/diskless.8 107788 2002-12-12 17:26:04Z ru $ | 27.\" $FreeBSD: head/share/man/man8/diskless.8 108228 2002-12-23 18:44:22Z dillon $ |
| 28.\" 29.Dd April 18, 2001 30.Dt DISKLESS 8 31.Os 32.Sh NAME 33.Nm diskless 34.Nd booting a system over the network 35.Sh DESCRIPTION 36The ability to boot a machine over the network is useful for 37.Em diskless 38or 39.Em dataless 40machines, or as a temporary measure while repairing or | 28.\" 29.Dd April 18, 2001 30.Dt DISKLESS 8 31.Os 32.Sh NAME 33.Nm diskless 34.Nd booting a system over the network 35.Sh DESCRIPTION 36The ability to boot a machine over the network is useful for 37.Em diskless 38or 39.Em dataless 40machines, or as a temporary measure while repairing or |
| 41re-installing file systems on a local disk. | 41re-installing filesystems on a local disk. |
| 42This file provides a general description of the interactions between 43a client and its server when a client is booting over the network. 44.Sh OPERATION 45When booting a system over the network, there are three 46phases of interaction between client and server: 47.Pp 48.Bl -enum -compact 49.It | 42This file provides a general description of the interactions between 43a client and its server when a client is booting over the network. 44.Sh OPERATION 45When booting a system over the network, there are three 46phases of interaction between client and server: 47.Pp 48.Bl -enum -compact 49.It |
| 50The stage-1 bootstrap loads a boot program, from | 50The stage-1 bootstrap, typically PXE built into your ethernet 51card, loads a second-stage boot program. |
| 51.It | 52.It |
| 52The boot program loads a kernel. | 53The second-stage boot program, typically 'pxeboot', loads modules and 54the kernel and boots the kernel. |
| 53.It | 55.It |
| 54The kernel does NFS mounts for root. | 56The kernel NFS mounts the root directory and continues from there. |
| 55.El 56.Pp 57Each of these phases are described in further detail below. 58.Pp | 57.El 58.Pp 59Each of these phases are described in further detail below. 60.Pp |
| 59In phase 1, the stage-1 bootstrap code loads a boot program, 60which is typically able to control the network card. 61The boot program can be stored in the BIOS, in a BOOT ROM 62located on the network card (PXE, etherboot, netboot), 63or come from a disk unit (e.g. etherboot or netboot). | 61First the stage-1 bootstrap loads the stage-2 boot program over 62the network. The stage-1 bootstrap typically uses BOOTP or DHCP 63to obtain the filename to load, then uses TFTP to load the file. 64This file is typically called "pxeboot" and should be copied from 65.Pa /boot/pxeboot 66into the tftp directory on the server, which is typically 67.Pa /tftpdir . |
| 64.Pp | 68.Pp |
| 65In phase 2, the boot program loads a kernel. 66Operation in 67this phase depends on the design of the boot program. 68Typically, the boot program uses the 69.Tn BOOTP 70or 71.Tn DHCP 72protocol to get the client's IP address and other boot 73information, including but not limited to 74the IP addresses of the NFS server, router and nameserver, 75and the name of the kernel to load. 76Then the kernel is loaded, either directly using NFS 77(as it is the case for etherboot and netboot), 78or through an intermediate loader called pxeboot and 79loaded using TFTP or NFS. | 69The stage-2 boot program then loads additional modules and the kernel. 70These files may not exist on the DHCP or BOOTP server. You can use the 71.Sy next-server 72option available in DHCP configurations to specify the server holding 73the second stage boot files and kernel. The stage-2 program uses 74NFS or TFTP to obtain these files. By default, NFS is used. 75If you are using pxeboot you can install a version that uses 76TFTP by setting LOADER_TFTP_SUPPORT=YES 77in your 78.Pa /etc/make.conf , 79then recompiling and reinstalling pxeboot via the command listed below. 80It is often necessary to use TFTP here so you can place a custom kernel 81in /tftpdir/. 82If you use NFS and do not have a custom root filesystem for the diskless 83client, the stage-2 boot will load your server's kernel as the kernel for 84the diskless machine, which may not be what you want to have happen. 85.Bd -literal -offset indent 86cd /usr/src/sys/i386/boot 87make clean; make; make install 88cp /boot/pxeboot /tftpdir/ 89.Ed |
| 80.Pp | 90.Pp |
| 81In phase 3, the kernel uses again DHCP or BOOTP to acquire | 91In phase 3, the kernel again uses DHCP or BOOTP to acquire |
| 82configuration information, and proceeds to mount the | 92configuration information, and proceeds to mount the |
| 83root file system and start operation. 84Some specific actions performed during the startup 85of a diskless system are listed in | 93root filesystem and start operation. The boot 94scripts recognize a diskless startup and peform 95the actions found in 96.Pa /etc/rc.d/initdiskless 97and 98.Pa /etc/rc.d/diskless . 99In older systems the scripts are located in |
| 86.Pa /etc/rc.diskless1 87and | 100.Pa /etc/rc.diskless1 101and |
| 88.Pa /etc/rc.diskless2 | 102.Pa /etc/rc.diskless2 . |
| 89.Sh CONFIGURATION 90In order to run a diskless client, you need the following: 91.Bl -bullet 92.It | 103.Sh CONFIGURATION 104In order to run a diskless client, you need the following: 105.Bl -bullet 106.It |
| 93an NFS server which exports a root and /usr partition with | 107An NFS server which exports a root and /usr partition with |
| 94appropriate permissions. | 108appropriate permissions. |
| 95The 96.Pa rc.diskless{1,2} | 109The diskless |
| 97scripts work with readonly partitions, as long as root is exported with 98.Fl maproot Ns =0 99so that some system files can be accessed. 100As an example, 101.Pa /etc/exports 102can contain the following lines: 103.Bd -literal -offset indent 104<ROOT> -ro -maproot=0 -alldirs <list of diskless clients> 105/usr -ro -alldirs <list of diskless clients> 106.Ed 107.Pp 108where 109.Aq ROOT 110is the mountpoint on the server of the root partition. 111The script 112.Pa /usr/share/examples/diskless/clone_root 113can be used to create a shared readonly root partition, | 110scripts work with readonly partitions, as long as root is exported with 111.Fl maproot Ns =0 112so that some system files can be accessed. 113As an example, 114.Pa /etc/exports 115can contain the following lines: 116.Bd -literal -offset indent 117<ROOT> -ro -maproot=0 -alldirs <list of diskless clients> 118/usr -ro -alldirs <list of diskless clients> 119.Ed 120.Pp 121where 122.Aq ROOT 123is the mountpoint on the server of the root partition. 124The script 125.Pa /usr/share/examples/diskless/clone_root 126can be used to create a shared readonly root partition, |
| 114but in same cases you can also decide to export | 127but in many cases you may decide to export |
| 115(again as readonly) the root directory used by 116the server itself. 117.It 118a 119.Tn BOOTP 120or 121.Tn DHCP 122server. --- 19 unchanged lines hidden (view full) --- 142.Pp 143where 144.Aq SERVER , 145.Aq GATEWAY 146and 147.Aq ROOT 148have the obvious meanings. 149.It | 128(again as readonly) the root directory used by 129the server itself. 130.It 131a 132.Tn BOOTP 133or 134.Tn DHCP 135server. --- 19 unchanged lines hidden (view full) --- 155.Pp 156where 157.Aq SERVER , 158.Aq GATEWAY 159and 160.Aq ROOT 161have the obvious meanings. 162.It |
| 150On the root partition, create the directory 151.Pa /conf/default/etc , 152and populate it with a copy of the contents of | 163A properly initialized root partition. 164The script 165.Pa /usr/share/examples/diskless/clone_root 166can help in creating it, using the server's root partition 167as a reference. If you are just starting out you should 168simply use the server's own root directory, 169.Pa / , 170and not try to clone it. 171.Pp 172You often do not want to use the same 173.Pa rc.conf 174or 175.Pa rc.local 176files for the diskless boot as you do on the server. The diskless boot 177scripts provide a mechanism through which you can override various files 178in 179.Pa /etc 180(as well as other subdirectories of root). The scripts provide four 181overriding directories situated in 182.Pa /conf/base , 183.Pa /conf/default , 184.Pa /conf/<broadcast-ip> , 185and 186.Pa /conf/<machine-ip> . 187You should always create 188.Pa /conf/base/etc , 189which will entirely replace the server's 190.Pa /etc 191on the diskless machine. 192You can clone the server's 193.Pa /etc 194here or you can create a special file which tells the diskless boot scripts 195to remount the server's 196.Pa /etc 197onto 198.Pa /conf/base/etc . 199You do this by creating the file 200.Pa /conf/base/etc/diskless_remount 201containing the mount point to use as a basis of the diskless machine's |
| 153.Pa /etc . | 202.Pa /etc . |
| 154The files and subdirectories within | 203For example, the file might contain: 204.Bd -literal -offset 4n 20510.0.0.1:/etc 206.Ed 207.Pp 208The diskless scripts create memory filesystems to hold the overriden 209directories. Only a 2MB partition is created by default, which may not 210be sufficient for your purposes. To override this you can create the 211file 212.Pa /conf/base/etc/md_size 213containing the size, in 512 byte sectors, of the memory disk to create 214for that directory. 215.Pp 216You then typically provide file-by-file overrides in the |
| 155.Pa /conf/default/etc | 217.Pa /conf/default/etc |
| 156are used to bootstrap the diskless environment's 157.Pa /etc 158memory file system. 159Be sure and copy the entirety of | 218directory. At a minimum you must provides overrides for 219.Pa /etc/fstab , 220.Pa /etc/rc.conf , 221and 222.Pa /etc/rc.local 223via 224.Pa /conf/default/etc/fstab , 225.Pa /conf/default/etc/rc.conf , 226and 227.Pa /conf/default/etc/rc.local . 228.Pp 229Overrides are hierarchical. You can supply network-specific defaults 230in the 231.Pa /conf/<BROADCASTIP>/etc 232directory, where <BROADCASTIP> represents the broadcast IP address of 233the diskless system as given to it via 234.Tn BOOTP . 235The 236.Pa diskless_remount 237and 238.Pa md_size 239features work in any of these directories. 240The configuration feature works on directories other then |
| 160.Pa /etc , | 241.Pa /etc , |
| 161and not just overrides. 162.It 163Additionally, one may supply per-network or per-host overrides for 164files in 165.Pa /etc 166by creating and populating the directories 167.Pa /conf/${i}/etc , 168where 169.Va i 170can be either the subnet broadcast address for the client, or the IP 171address of the client. | 242you simply create the directory you wish to replace or override in 243.Pa /conf/{base,default,<broadcast>,<ip>}/* 244and work it in the same way that you work 245.Pa /etc . |
| 172.Pp | 246.Pp |
| 173Files are copied from the above directories into | 247Since you normally clone the server's |
| 174.Pa /etc | 248.Pa /etc |
| 175(overriding the previous content of 176.Pa /etc ) 177starting from the most generic one by 178.Pa /etc/rc.diskless1 , 179before the main part of 180.Pa /etc/rc 181(including reading 182.Pa rc.conf ) 183is run. | 249using the 250.Pa /conf/base/etc/diskless_remount , 251you might wish to remove unneeded files from the memory filesystem. For 252example, if the server has a firewall but you do not, you might wish 253to remove 254.Pa /etc/ipfw.conf . 255You can do this by creating a 256.Pa /conf/base/<DIRECTORY>.remove 257file. For example, 258.Pa /conf/base/etc.remove , 259which contains a list of relative paths that the boot scripts should remove 260from the memory file systems. |
| 184.Pp 185As a minimum, you normally need to have the following in 186.Pa /conf/default/etc/fstab 187.Bd -literal -offset indent 188<SERVER>:<ROOT> / nfs ro 0 0 189<SERVER>:/usr /usr nfs ro 0 0 190proc /proc procfs rw 0 0 191.Ed 192.Pp | 261.Pp 262As a minimum, you normally need to have the following in 263.Pa /conf/default/etc/fstab 264.Bd -literal -offset indent 265<SERVER>:<ROOT> / nfs ro 0 0 266<SERVER>:/usr /usr nfs ro 0 0 267proc /proc procfs rw 0 0 268.Ed 269.Pp |
| 193and also a customized version of | 270You also need to create a customized version of |
| 194.Pa /conf/default/etc/rc.conf 195which should contain | 271.Pa /conf/default/etc/rc.conf 272which should contain |
| 196the startup options for the diskless client. | 273the startup options for the diskless client, and 274.Pa /conf/default/etc/rc.local 275which could be empty but prevents the server's own 276.Pa /etc/rc.local 277from leaking onto the diskless system. |
| 197.Pp | 278.Pp |
| 198Most likely | 279In 280.Pa rc.conf , 281most likely |
| 199you will not need to set 200.Va hostname 201and 202.Va ifconfig_* 203because these will be already set by the startup code. | 282you will not need to set 283.Va hostname 284and 285.Va ifconfig_* 286because these will be already set by the startup code. |
| 204You will also probably need to set 205.Va local_startup Ns = Ns Qq 206so that the server's 207local startup files will not be used. 208.Pp 209While an 210.Xr md 4 Ns -backed 211file system is mounted on 212.Pa /var 213by the startup scripts, 214some sites may want to disable the saving of entropy by setting 215.Va entropy_dir Ns = Ns Qq Li NO 216in 217.Pa /etc/defaults/rc.conf . 218.Pp | |
| 219Finally, it might be convenient to use a 220.Ic case 221statement using 222.Li `hostname` 223as the switch variable to do machine-specific configuration 224in case a number of diskless clients share the same configuration 225files. 226.It | 287Finally, it might be convenient to use a 288.Ic case 289statement using 290.Li `hostname` 291as the switch variable to do machine-specific configuration 292in case a number of diskless clients share the same configuration 293files. 294.It |
| 227build a kernel whose config file (e.g.\& 228.Pa /sys/i386/conf/DISKLESS ) 229has at least the following options and devices: | 295The kernel for the diskless clients, which will be loaded using 296NFS or TFTP, should be built with at least the following options: |
| 230.Bd -literal -offset indent | 297.Bd -literal -offset indent |
| 231device md | |
| 232options BOOTP 233options BOOTP_NFSROOT 234options BOOTP_COMPAT 235.Ed 236.Pp | 298options BOOTP 299options BOOTP_NFSROOT 300options BOOTP_COMPAT 301.Ed 302.Pp |
| 303In the devices section add: 304.Bd -literal -offset indent 305device md 306.Ed 307.Pp |
|
| 237If you use the firewall, remember to default to open or your kernel 238will not be able to send/receive the bootp packets. 239.El 240.Sh SECURITY ISSUES 241Be warned that using unencrypted NFS to mount root and user 242partitions may expose information such as 243encryption keys. 244.Sh BUGS 245This manpage is probably incomplete. 246.Pp 247.Fx 248sometimes requires to write onto | 308If you use the firewall, remember to default to open or your kernel 309will not be able to send/receive the bootp packets. 310.El 311.Sh SECURITY ISSUES 312Be warned that using unencrypted NFS to mount root and user 313partitions may expose information such as 314encryption keys. 315.Sh BUGS 316This manpage is probably incomplete. 317.Pp 318.Fx 319sometimes requires to write onto |
| 249the root partition, so the startup scripts create and mount 250.Xr md 4 Ns -backed 251file systems on some locations (e.g.\& | 320the root partition, so the startup scripts mount MFS 321filesystems on some locations (e.g.\& |
| 252.Pa /etc 253and 254.Pa /var ) , 255while 256trying to preserve the original content. 257The process might not handle all cases. 258.Sh SEE ALSO | 322.Pa /etc 323and 324.Pa /var ) , 325while 326trying to preserve the original content. 327The process might not handle all cases. 328.Sh SEE ALSO |
| 259.Xr md 4 , | |
| 260.Xr ethers 5 , 261.Xr exports 5 , 262.Xr bootpd 8 , 263.Xr mountd 8 , 264.Xr nfsd 8 , 265.Xr pxeboot 8 , 266.Xr reboot 8 , 267.Xr tftpd 8 , 268.Xr ports/net/etherboot | 329.Xr ethers 5 , 330.Xr exports 5 , 331.Xr bootpd 8 , 332.Xr mountd 8 , 333.Xr nfsd 8 , 334.Xr pxeboot 8 , 335.Xr reboot 8 , 336.Xr tftpd 8 , 337.Xr ports/net/etherboot |