mirror of
https://github.com/opnsense/src.git
synced 2026-06-11 01:30:30 -04:00
Bring the diskless manual page more up-to-date. It still needs a lot of work.
This commit is contained in:
Matthew Dillon
parent
463cfa804d
commit
c2095e2b12
1 changed files with 160 additions and 91 deletions
|
|
@ -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
|
||||
.Pa /etc .
|
||||
The files and subdirectories within
|
||||
.Pa /conf/default/etc
|
||||
are used to bootstrap the diskless environment's
|
||||
.Pa /etc
|
||||
memory file system.
|
||||
Be sure and copy the entirety of
|
||||
.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.
|
||||
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
|
||||
Files are copied from the above directories into
|
||||
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
|
||||
(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.
|
||||
(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 .
|
||||
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
|
||||
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 ,
|
||||
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
|
||||
Since you normally clone the server's
|
||||
.Pa /etc
|
||||
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 ,
|
||||
|
|
|
|||
Loading…
Reference in a new issue