diff options
author | dillon <dillon@FreeBSD.org> | 2002-12-23 18:44:22 +0000 |
---|---|---|
committer | dillon <dillon@FreeBSD.org> | 2002-12-23 18:44:22 +0000 |
commit | f3a396d49d13acd0ddc7949480370856fa816ed8 (patch) | |
tree | 1b3700a6ca1341b5c8a9251445aff2e1be46319b /share/man/man8 | |
parent | 301b96498bdf7a9b644bd2cc5088e7f38cb222d7 (diff) | |
download | FreeBSD-src-f3a396d49d13acd0ddc7949480370856fa816ed8.zip FreeBSD-src-f3a396d49d13acd0ddc7949480370856fa816ed8.tar.gz |
Bring the diskless manual page more up-to-date. It still needs a lot of work.
Diffstat (limited to 'share/man/man8')
-rw-r--r-- | share/man/man8/diskless.8 | 245 |
1 files changed, 157 insertions, 88 deletions
diff --git a/share/man/man8/diskless.8 b/share/man/man8/diskless.8 index e6a49f1..f368a5e 100644 --- a/share/man/man8/diskless.8 +++ b/share/man/man8/diskless.8 @@ -38,7 +38,7 @@ The ability to boot a machine over the network is useful for or .Em dataless machines, or as a temporary measure while repairing or -re-installing file systems on a local disk. +re-installing filesystems on a local disk. This file provides a general description of the interactions between a client and its server when a client is booting over the network. .Sh OPERATION @@ -47,53 +47,66 @@ phases of interaction between client and server: .Pp .Bl -enum -compact .It -The stage-1 bootstrap loads a boot program, from +The stage-1 bootstrap, typically PXE built into your ethernet +card, loads a second-stage boot program. .It -The boot program loads a kernel. +The second-stage boot program, typically 'pxeboot', loads modules and +the kernel and boots the kernel. .It -The kernel does NFS mounts for root. +The kernel NFS mounts the root directory and continues from there. .El .Pp Each of these phases are described in further detail below. .Pp -In phase 1, the stage-1 bootstrap code loads a boot program, -which is typically able to control the network card. -The boot program can be stored in the BIOS, in a BOOT ROM -located on the network card (PXE, etherboot, netboot), -or come from a disk unit (e.g. etherboot or netboot). +First the stage-1 bootstrap loads the stage-2 boot program over +the network. The stage-1 bootstrap typically uses BOOTP or DHCP +to obtain the filename to load, then uses TFTP to load the file. +This file is typically called "pxeboot" and should be copied from +.Pa /boot/pxeboot +into the tftp directory on the server, which is typically +.Pa /tftpdir . .Pp -In phase 2, the boot program loads a kernel. -Operation in -this phase depends on the design of the boot program. -Typically, the boot program uses the -.Tn BOOTP -or -.Tn DHCP -protocol to get the client's IP address and other boot -information, including but not limited to -the IP addresses of the NFS server, router and nameserver, -and the name of the kernel to load. -Then the kernel is loaded, either directly using NFS -(as it is the case for etherboot and netboot), -or through an intermediate loader called pxeboot and -loaded using TFTP or NFS. +The stage-2 boot program then loads additional modules and the kernel. +These files may not exist on the DHCP or BOOTP server. You can use the +.Sy next-server +option available in DHCP configurations to specify the server holding +the second stage boot files and kernel. The stage-2 program uses +NFS or TFTP to obtain these files. By default, NFS is used. +If you are using pxeboot you can install a version that uses +TFTP by setting LOADER_TFTP_SUPPORT=YES +in your +.Pa /etc/make.conf , +then recompiling and reinstalling pxeboot via the command listed below. +It is often necessary to use TFTP here so you can place a custom kernel +in /tftpdir/. +If you use NFS and do not have a custom root filesystem for the diskless +client, the stage-2 boot will load your server's kernel as the kernel for +the diskless machine, which may not be what you want to have happen. +.Bd -literal -offset indent +cd /usr/src/sys/i386/boot +make clean; make; make install +cp /boot/pxeboot /tftpdir/ +.Ed .Pp -In phase 3, the kernel uses again DHCP or BOOTP to acquire +In phase 3, the kernel again uses DHCP or BOOTP to acquire configuration information, and proceeds to mount the -root file system and start operation. -Some specific actions performed during the startup -of a diskless system are listed in +root filesystem and start operation. The boot +scripts recognize a diskless startup and peform +the actions found in +.Pa /etc/rc.d/initdiskless +and +.Pa /etc/rc.d/diskless . +In older systems the scripts are located in .Pa /etc/rc.diskless1 and -.Pa /etc/rc.diskless2 +.Pa /etc/rc.diskless2 . .Sh CONFIGURATION In order to run a diskless client, you need the following: .Bl -bullet .It -an NFS server which exports a root and /usr partition with +An NFS server which exports a root and /usr partition with appropriate permissions. -The -.Pa rc.diskless{1,2} +The diskless scripts work with readonly partitions, as long as root is exported with .Fl maproot Ns =0 so that some system files can be accessed. @@ -111,7 +124,7 @@ is the mountpoint on the server of the root partition. The script .Pa /usr/share/examples/diskless/clone_root can be used to create a shared readonly root partition, -but in same cases you can also decide to export +but in many cases you may decide to export (again as readonly) the root directory used by the server itself. .It @@ -147,40 +160,104 @@ and .Aq ROOT have the obvious meanings. .It -On the root partition, create the directory -.Pa /conf/default/etc , -and populate it with a copy of the contents of +A properly initialized root partition. +The script +.Pa /usr/share/examples/diskless/clone_root +can help in creating it, using the server's root partition +as a reference. If you are just starting out you should +simply use the server's own root directory, +.Pa / , +and not try to clone it. +.Pp +You often do not want to use the same +.Pa rc.conf +or +.Pa rc.local +files for the diskless boot as you do on the server. The diskless boot +scripts provide a mechanism through which you can override various files +in +.Pa /etc +(as well as other subdirectories of root). The scripts provide four +overriding directories situated in +.Pa /conf/base , +.Pa /conf/default , +.Pa /conf/<broadcast-ip> , +and +.Pa /conf/<machine-ip> . +You should always create +.Pa /conf/base/etc , +which will entirely replace the server's +.Pa /etc +on the diskless machine. +You can clone the server's +.Pa /etc +here or you can create a special file which tells the diskless boot scripts +to remount the server's +.Pa /etc +onto +.Pa /conf/base/etc . +You do this by creating the file +.Pa /conf/base/etc/diskless_remount +containing the mount point to use as a basis of the diskless machine's .Pa /etc . -The files and subdirectories within +For example, the file might contain: +.Bd -literal -offset 4n +10.0.0.1:/etc +.Ed +.Pp +The diskless scripts create memory filesystems to hold the overriden +directories. Only a 2MB partition is created by default, which may not +be sufficient for your purposes. To override this you can create the +file +.Pa /conf/base/etc/md_size +containing the size, in 512 byte sectors, of the memory disk to create +for that directory. +.Pp +You then typically provide file-by-file overrides in the .Pa /conf/default/etc -are used to bootstrap the diskless environment's -.Pa /etc -memory file system. -Be sure and copy the entirety of +directory. At a minimum you must provides overrides for +.Pa /etc/fstab , +.Pa /etc/rc.conf , +and +.Pa /etc/rc.local +via +.Pa /conf/default/etc/fstab , +.Pa /conf/default/etc/rc.conf , +and +.Pa /conf/default/etc/rc.local . +.Pp +Overrides are hierarchical. You can supply network-specific defaults +in the +.Pa /conf/<BROADCASTIP>/etc +directory, where <BROADCASTIP> represents the broadcast IP address of +the diskless system as given to it via +.Tn BOOTP . +The +.Pa diskless_remount +and +.Pa md_size +features work in any of these directories. +The configuration feature works on directories other then .Pa /etc , -and not just overrides. -.It -Additionally, one may supply per-network or per-host overrides for -files in -.Pa /etc -by creating and populating the directories -.Pa /conf/${i}/etc , -where -.Va i -can be either the subnet broadcast address for the client, or the IP -address of the client. +you simply create the directory you wish to replace or override in +.Pa /conf/{base,default,<broadcast>,<ip>}/* +and work it in the same way that you work +.Pa /etc . .Pp -Files are copied from the above directories into +Since you normally clone the server's .Pa /etc -(overriding the previous content of -.Pa /etc ) -starting from the most generic one by -.Pa /etc/rc.diskless1 , -before the main part of -.Pa /etc/rc -(including reading -.Pa rc.conf ) -is run. +using the +.Pa /conf/base/etc/diskless_remount , +you might wish to remove unneeded files from the memory filesystem. For +example, if the server has a firewall but you do not, you might wish +to remove +.Pa /etc/ipfw.conf . +You can do this by creating a +.Pa /conf/base/<DIRECTORY>.remove +file. For example, +.Pa /conf/base/etc.remove , +which contains a list of relative paths that the boot scripts should remove +from the memory file systems. .Pp As a minimum, you normally need to have the following in .Pa /conf/default/etc/fstab @@ -190,32 +267,23 @@ As a minimum, you normally need to have the following in proc /proc procfs rw 0 0 .Ed .Pp -and also a customized version of +You also need to create a customized version of .Pa /conf/default/etc/rc.conf which should contain -the startup options for the diskless client. +the startup options for the diskless client, and +.Pa /conf/default/etc/rc.local +which could be empty but prevents the server's own +.Pa /etc/rc.local +from leaking onto the diskless system. .Pp -Most likely +In +.Pa rc.conf , +most likely you will not need to set .Va hostname and .Va ifconfig_* because these will be already set by the startup code. -You will also probably need to set -.Va local_startup Ns = Ns Qq -so that the server's -local startup files will not be used. -.Pp -While an -.Xr md 4 Ns -backed -file system is mounted on -.Pa /var -by the startup scripts, -some sites may want to disable the saving of entropy by setting -.Va entropy_dir Ns = Ns Qq Li NO -in -.Pa /etc/defaults/rc.conf . -.Pp Finally, it might be convenient to use a .Ic case statement using @@ -224,16 +292,19 @@ as the switch variable to do machine-specific configuration in case a number of diskless clients share the same configuration files. .It -build a kernel whose config file (e.g.\& -.Pa /sys/i386/conf/DISKLESS ) -has at least the following options and devices: +The kernel for the diskless clients, which will be loaded using +NFS or TFTP, should be built with at least the following options: .Bd -literal -offset indent -device md options BOOTP options BOOTP_NFSROOT options BOOTP_COMPAT .Ed .Pp +In the devices section add: +.Bd -literal -offset indent +device md +.Ed +.Pp If you use the firewall, remember to default to open or your kernel will not be able to send/receive the bootp packets. .El @@ -246,9 +317,8 @@ This manpage is probably incomplete. .Pp .Fx sometimes requires to write onto -the root partition, so the startup scripts create and mount -.Xr md 4 Ns -backed -file systems on some locations (e.g.\& +the root partition, so the startup scripts mount MFS +filesystems on some locations (e.g.\& .Pa /etc and .Pa /var ) , @@ -256,7 +326,6 @@ while trying to preserve the original content. The process might not handle all cases. .Sh SEE ALSO -.Xr md 4 , .Xr ethers 5 , .Xr exports 5 , .Xr bootpd 8 , |