os/doc
3
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity

Reorganize and enhance the diskless section (especially for PXE and 5.X).

Browse source 
Mainly inspired by

PR:		docs/62834
Submitted by:	Jean-Francois Dockes <dockes@wanadoo.fr>
Approved by:	blackend (mentor)
This commit is contained in:
Alex Dupre 2004-03-12 19:51:51 +00:00
parent fefa49d629
commit 50bdcb4b88
Notes: svn2git 2020-12-08 03:00:23 +00:00 
svn path=/head/; revision=20322
1 changed files with 326 additions and 110 deletions
Download patch file Download diff file Expand all files Collapse all files

436
en_US.ISO8859-1/books/handbook/advanced-networking/chapter.sgml
View file

@ -2395,6 +2395,13 @@ Exports list on foobar:
<contrib>Updated by </contrib> <contrib>Updated by </contrib>
</author> </author>
</authorgroup> </authorgroup>
<authorgroup>
<author>
<firstname>Alex</firstname>
<surname>Dupre</surname>
<contrib>Reorganized and enhanced by </contrib>
</author>
</authorgroup>
</sect1info> </sect1info>
<title>Diskless Operation</title> <title>Diskless Operation</title>
@ -2402,9 +2409,9 @@ Exports list on foobar:
<indexterm><primary>diskless operation</primary></indexterm> <indexterm><primary>diskless operation</primary></indexterm>
<para>A FreeBSD machine can boot over the network and operate without a <para>A FreeBSD machine can boot over the network and operate without a
local disk, using filesystems mounted from an NFS server. No system local disk, using filesystems mounted from an <acronym>NFS</acronym> server. No system
modification is necessary, beyond standard configuration files. modification is necessary, beyond standard configuration files.
Such a system is easy to set up because all the necessary elements Such a system is relatively easy to set up because all the necessary elements
are readily available:</para> are readily available:</para>
<itemizedlist> <itemizedlist>
<listitem> <listitem>
@ -2444,14 +2451,14 @@ Exports list on foobar:
</listitem> </listitem>
<listitem> <listitem>
<para>Swapping, if needed, can be done either to an NFS file or to <para>Swapping, if needed, can be done either to an <acronym>NFS</acronym> file or to
a local disk.</para> a local disk.</para>
</listitem> </listitem>
</itemizedlist> </itemizedlist>
<para>There are many ways to set up diskless workstations. Many <para>There are many ways to set up diskless workstations. Many
elements are involved, and most can be customized to suit local elements are involved, and most can be customized to suit local
taste. The following will describe the setup of a complete system, taste. The following will describe variations on the setup of a complete system,
emphasizing simplicity and compatibility with the emphasizing simplicity and compatibility with the
standard FreeBSD startup scripts. The system described has the standard FreeBSD startup scripts. The system described has the
following characteristics:</para> following characteristics:</para>
@ -2466,12 +2473,13 @@ Exports list on foobar:
configuration files overridden by ones specific to diskless configuration files overridden by ones specific to diskless
operation or, possibly, to the workstation they belong to.</para> operation or, possibly, to the workstation they belong to.</para>
<para>The parts of the <filename>root</filename> which have to be <para>The parts of the <filename>root</filename> which have to be
writable are overlaid with &man.mfs.8; filesystems. Any changes writable are overlaid with &man.mfs.8; (&os;&nbsp;4.X) or &man.md.4; (&os;&nbsp;5.X) filesystems. Any changes
will be lost when the system reboots.</para> will be lost when the system reboots.</para>
</listitem> </listitem>
<listitem> <listitem>
<para>The kernel is loaded by <application>etherboot <para>The kernel is transferred and loaded either with
</application>, using DHCP (or BOOTP) and TFTP.</para> <application>etherboot</application> or <acronym>PXE</acronym>
as some situations may mandate the use of either method.</para>
</listitem> </listitem>
</itemizedlist> </itemizedlist>
@ -2480,63 +2488,138 @@ Exports list on foobar:
other hosts.</para> other hosts.</para>
</caution> </caution>
<para>All the information in this section has been tested
using &os; releases 4.9-RELEASE and 5.2.1-RELEASE. The text is
primarily structured for 4.X usage. Notes have been inserted where
appropriate to indicate 5.X changes.</para>
<sect2>
<title>Background Information</title>
<para>Setting up diskless workstations is both relatively
straightforward and prone to errors. These are sometimes
difficult to diagnose for a number of reasons. For example:</para>
<itemizedlist>
<listitem>
<para>Compile time options may determine different behaviours at
runtime.</para>
</listitem>
<listitem>
<para>Error messages are often cryptic or totally absent.</para>
</listitem>
</itemizedlist>
<para>In this context, having some knowledge of the background
mechanisms involved is very useful to solve the problems that
may arise.</para>
<para>Several operations need to be performed for a successful
bootstrap:</para>
<itemizedlist>
<listitem>
<para>The machine needs to obtain initial parameters such as its IP
address, executable filename, server name, root path. This is
done using the <acronym>DHCP</acronym> or BOOTP protocols.
<acronym>DHCP</acronym> is a compatible extension of BOOTP, and
uses the same port numbers and basic packet format.</para>
<para>It is possible to configure a system to use only BOOTP.
The &man.bootpd.8; server program is included in the base &os;
system.</para>
<para>However, <acronym>DHCP</acronym> has a number of advantages
over BOOTP (nicer configuration files, possibility of using
<acronym>PXE</acronym>, plus many others not directly related to
diskless operation), and we will describe mainly a
<acronym>DHCP</acronym> configuration, with equivalent exemples
using &man.bootpd.8; when possible. The sample configuration will
use the <application>ISC DHCP</application> software package
(release 3.0.1.r12 was installed on the test server).</para>
</listitem>
<listitem>
<para>The machine needs to transfer one or several programs to local
memory. Either <acronym>TFTP</acronym> or <acronym>NFS</acronym>
are used. The choice between <acronym>TFTP</acronym> and
<acronym>NFS</acronym> is a compile time option in several places.
A common source of error is to specify filenames for the wrong
protocol: <acronym>TFTP</acronym> typically transfers all files from
a single directory on the server, and would expect filenames
relative to this directory. <acronym>NFS</acronym> needs absolute
file paths.</para>
</listitem>
<listitem>
<para>The possible intermediate bootstrap programs and the kernel
need to be initialized and executed. There are several important
variations in this area:</para>
<itemizedlist>
<listitem>
<para><acronym>PXE</acronym> will load &man.pxeboot.8;, which is
a modified version of the &os; third stage loader. The
&man.loader.8; will obtain most parameters necessary to system
startup, and leave them in the kernel environment before
transferring control. It is possible to use a
<filename>GENERIC</filename> kernel in this case.</para>
</listitem>
<listitem>
<para><application>etherboot</application>, will directly
load the kernel, with less preparation. You will need to
build a kernel with specific options.</para>
</listitem>
</itemizedlist>
<para><acronym>PXE</acronym> and <application>etherboot</application>
work equally well with 4.X systems. Because 5.X kernels
normally let the &man.loader.8; do more work for them,
<acronym>PXE</acronym> is preferred for 5.X systems.</para>
<para>If your <acronym>BIOS</acronym> and network cards support
<acronym>PXE</acronym>, you should probably use it. However,
it is still possible to start a 5.X system with
<application>etherboot</application>.</para>
</listitem>
<listitem>
<para>Finally, the machine needs to access its filesystems.
<acronym>NFS</acronym> is used in all cases.</para>
</listitem>
</itemizedlist>
<para>See also &man.diskless.8; manual page.</para>
</sect2>
<sect2> <sect2>
<title>Setup Instructions</title> <title>Setup Instructions</title>
<sect3> <sect3>
<title>Configuring DHCP/BOOTP</title> <title>Configuration Using <application>ISC DHCP</application></title>
<indexterm>
<primary>diskless operation</primary>
<secondary>booting</secondary>
</indexterm>
<para>There are two protocols that are commonly used to boot a
workstation that retrieves its configuration over the network: BOOTP
and DHCP. They are used at several points in the workstation
bootstrap:</para>
<itemizedlist>
<listitem><para><application>etherboot</application> uses
DHCP (by default) or BOOTP (needs a configuration option) to
find the kernel. (PXE uses DHCP).</para>
</listitem>
<listitem><para>The kernel uses BOOTP to locate the NFS
root.</para>
</listitem>
</itemizedlist>
<para>It is possible to configure a system to use only BOOTP.
The &man.bootpd.8; server program is included in the
base FreeBSD system.</para>
<para>However, DHCP has a number of advantages over BOOTP (nicer
configuration files, possibility of using PXE, plus many others
not directly related to diskless operation), and we shall describe
both a pure BOOTP, and a BOOTP+DHCP configuration, with an
emphasis on the latter, which will use the ISC DHCP software
package.</para>
<sect4>
<title>Configuration Using ISC DHCP</title>
<indexterm> <indexterm>
<primary>DHCP</primary> <primary>DHCP</primary>
<secondary>diskless operation</secondary> <secondary>diskless operation</secondary>
</indexterm> </indexterm>
<para>The <application>isc-dhcp</application> server can answer <para>The <application>ISC DHCP</application> server can answer
both BOOTP and DHCP requests.</para> both BOOTP and <acronym>DHCP</acronym> requests.</para>
<para>As of release 4.4, <application>isc-dhcp <para>As of release 4.9, <application>ISC DHCP
3.0</application> is not part of the base 3.0</application> is not part of the base
system. You will first need to install the system. You will first need to install the
<filename role="package">net/isc-dhcp3-server</filename> port or the <filename role="package">net/isc-dhcp3-server</filename> port or the
corresponding package. Please refer to <xref linkend="ports"> corresponding package. Please refer to <xref linkend="ports">
for general information about ports and packages.</para> for general information about ports and packages.</para>
<para>Once <application>isc-dhcp</application> is installed, it <para>Once <application>ISC DHCP</application> is installed, it
needs a configuration file to run, (normally named needs a configuration file to run, (normally named
<filename>/usr/local/etc/dhcpd.conf</filename>). Here follows <filename>/usr/local/etc/dhcpd.conf</filename>). Here follows
a commented example:</para> a commented example, where host <hostid>margaux</hostid>
uses <application>etherboot</application> and host
<hostid>corbieres</hostid> uses <acronym>PXE</acronym>:</para>
<programlisting> <programlisting>
default-lease-time 600; default-lease-time 600;
@ -2555,16 +2638,23 @@ Exports list on foobar:
host margaux { host margaux {
hardware ethernet 01:23:45:67:89:ab; hardware ethernet 01:23:45:67:89:ab;
fixed-address margaux.example.com; fixed-address margaux.example.com;
next-server 192.168.4.4;<co id="co-dhcp-next-server"> next-server 192.168.4.4; <co id="co-dhcp-next-server">
filename "/tftpboot/kernel.diskless";<co id="co-dhcp-filename"> filename "/data/misc/kernel.diskless"; <co id="co-dhcp-filename">
option root-path "192.168.4.4:/data/misc/diskless";<co id="co-dhcp-root-path"> option root-path "192.168.4.4:/data/misc/diskless"; <co id="co-dhcp-root-path">
}
host corbieres {
hardware ethernet 00:02:b3:27:62:df;
fixed-address corbieres.example.com;
next-server 192.168.4.4;
filename "pxeboot";
option root-path "192.168.4.4:/data/misc/diskless";
} }
} }
</programlisting> </programlisting>
<calloutlist> <calloutlist>
<callout arearefs="co-dhcp-host-name"><para>This option tells <callout arearefs="co-dhcp-host-name"><para>This option tells
<command>dhcpd</command> to send the value in the <application>dhcpd</application> to send the value in the
<literal>host</literal> declarations as the hostname for the <literal>host</literal> declarations as the hostname for the
diskless host. An alternate way would be to add an diskless host. An alternate way would be to add an
<literal>option host-name <literal>option host-name
@ -2574,44 +2664,59 @@ Exports list on foobar:
<callout arearefs="co-dhcp-next-server"><para>The <callout arearefs="co-dhcp-next-server"><para>The
<literal>next-server</literal> directive designates <literal>next-server</literal> directive designates
the TFTP server (the default is to use the same host as the the <acronym>TFTP</acronym> or <acronym>NFS</acronym> server to
DHCP server).</para> use for loading loader or kernel file (the default is to use
the same host as the
<acronym>DHCP</acronym> server).</para>
</callout> </callout>
<callout arearefs="co-dhcp-filename"><para>The <callout arearefs="co-dhcp-filename"><para>The
<literal>filename</literal> directive defines the file that <literal>filename</literal> directive defines the file that
<application>etherboot</application> will load as a <application>etherboot</application> or <acronym>PXE</acronym>
kernel. will load for the next execution step. It must be specified
<note><para>PXE appears to prefer a relative file according to the transfer method used.
name, and it loads <command>pxeboot</command>, not the <application>etherboot</application> can be compiled to use
kernel (<literal>option filename <acronym>NFS</acronym> or <acronym>TFTP</acronym>. The &os;
"pxeboot"</literal>).</para> port configures <acronym>NFS</acronym> by default.
</note> <acronym>PXE</acronym> uses <acronym>TFTP</acronym>, which is
</para> why a relative filename is used here (this may depend on the
<acronym>TFTP</acronym> server configuration, but would be
fairly typical). Also, <acronym>PXE</acronym> loads
<filename>pxeboot</filename>, not the kernel. There are other
interesting possibilities, like loading
<filename>pxeboot</filename> from a &os; CD-ROM
<filename role="directory">/boot</filename> directory (as
&man.pxeboot.8; can load a <filename>GENERIC</filename> kernel,
this makes it possible to use <acronym>PXE</acronym> to boot
from a remote CD-ROM).</para>
</callout> </callout>
<callout arearefs="co-dhcp-root-path"><para>The <callout arearefs="co-dhcp-root-path"><para>The
<literal>root-path</literal> option defines the path to <literal>root-path</literal> option defines the path to
the root filesystem, in usual NFS notation.</para> the root filesystem, in usual <acronym>NFS</acronym> notation.
When using <acronym>PXE</acronym>, it is possible to leave off
the host's IP as long as you do not enable the kernel option
BOOTP. The <acronym>NFS</acronym> server will then be
the same as the <acronym>TFTP</acronym> one.</para>
</callout> </callout>
</calloutlist> </calloutlist>
</sect4> </sect3>
<sect4> <sect3>
<title>Configuration Using BOOTP</title> <title>Configuration Using BOOTP</title>
<indexterm> <indexterm>
<primary>BOOTP</primary> <primary>BOOTP</primary>
<secondary>diskless operation</secondary> <secondary>diskless operation</secondary>
</indexterm> </indexterm>
<para>Here follows an equivalent <command>bootpd</command> <para>Here follows an equivalent <application>bootpd</application>
configuration. This would be found in configuration (reduced to one client). This would be found in
<filename>/etc/bootptab</filename>.</para> <filename>/etc/bootptab</filename>.</para>
<para>Please note that <application>etherboot</application> <para>Please note that <application>etherboot</application>
must be compiled with the non-default option must be compiled with the non-default option
<literal>NO_DHCP_SUPPORT</literal> in order to use BOOTP, <literal>NO_DHCP_SUPPORT</literal> in order to use BOOTP,
and that PXE <emphasis>needs</emphasis> DHCP. The only and that <acronym>PXE</acronym> <emphasis>needs</emphasis> <acronym>DHCP</acronym>. The only
obvious advantage of <application>bootpd</application> is obvious advantage of <application>bootpd</application> is
that it exists in the base system.</para> that it exists in the base system.</para>
@ -2627,7 +2732,6 @@ Exports list on foobar:
margaux:ha=0123456789ab:tc=.def100 margaux:ha=0123456789ab:tc=.def100
</programlisting> </programlisting>
</sect4>
</sect3> </sect3>
<sect3> <sect3>
@ -2656,8 +2760,14 @@ Exports list on foobar:
of everything. Else refer to <xref linkend="ports"> for of everything. Else refer to <xref linkend="ports"> for
information about ports and packages.</para> information about ports and packages.</para>
<para>You can change the <application>etherboot</application>
configuration (i.e. to use <acronym>TFTP</acronym> instead of
<acronym>NFS</acronym>) by editing the <filename>Config</filename>
file in the <application>etherboot</application> source
directory.</para>
<para>For our setup, we shall use a boot floppy. For other methods <para>For our setup, we shall use a boot floppy. For other methods
(PROM, or dos program), please refer to the (PROM, or &ms-dos; program), please refer to the
<application>etherboot</application> documentation.</para> <application>etherboot</application> documentation.</para>
<para>To make a boot floppy, insert a floppy in the drive on the <para>To make a boot floppy, insert a floppy in the drive on the
@ -2677,9 +2787,32 @@ Exports list on foobar:
</sect3> </sect3>
<sect3>
<title>Booting with <acronym>PXE</acronym></title>
<para>By default, the &man.pxeboot.8; loader loads the kernel via
<acronym>NFS</acronym>. It can be compiled to use
<acronym>TFTP</acronym> instead by specifying the
<literal>LOADER_TFTP_SUPPORT</literal> option in
<filename>/etc/make.conf</filename>. See the comments in
<filename>/etc/defaults/make.conf</filename> (or
<filename>/usr/share/examples/etc/make.conf</filename> for 5.X
systems) for instructions.</para>
<para>There are two other undocumented <filename>make.conf</filename>
options which may be useful for setting up a serial console diskless
machine: <literal>BOOT_PXELDR_PROBE_KEYBOARD</literal>, and
<literal>BOOT_PXELDR_ALWAYS_SERIAL</literal> (the latter only exists
on &os;&nbsp;5.X).</para>
<para>To use <acronym>PXE</acronym> when the machine starts, you will
usually need to select the <literal>Boot from network</literal>
option in your <acronym>BIOS</acronym> setup, or type a function key
during the PC initialization.</para>
</sect3>
<sect3> <sect3>
<title>Configuring the TFTP and NFS Servers</title> <title>Configuring the <acronym>TFTP</acronym> and <acronym>NFS</acronym> Servers</title>
<indexterm> <indexterm>
<primary>TFTP</primary> <primary>TFTP</primary>
@ -2690,11 +2823,13 @@ Exports list on foobar:
<secondary>diskless operation</secondary> <secondary>diskless operation</secondary>
</indexterm> </indexterm>
<para>You need to enable <command>tftpd</command> on the TFTP <para>If you are using <acronym>PXE</acronym> or
server:</para> <application>etherboot</application> configured to use
<acronym>TFTP</acronym>, you need to enable
<application>tftpd</application> on the file server:</para>
<procedure> <procedure>
<step> <step>
<para>Create a directory from which <command>tftpd</command> <para>Create a directory from which <application>tftpd</application>
will serve the files, e.g. <filename>/tftpboot</filename>.</para> will serve the files, e.g. <filename>/tftpboot</filename>.</para>
</step> </step>
@ -2702,16 +2837,16 @@ Exports list on foobar:
<para>Add this line to your <para>Add this line to your
<filename>/etc/inetd.conf</filename>:</para> <filename>/etc/inetd.conf</filename>:</para>
<programlisting>tftp dgram udp wait root /usr/libexec/tftpd tftpd -s /tftpboot</programlisting> <programlisting>tftp dgram udp wait root /usr/libexec/tftpd tftpd -l -s /tftpboot</programlisting>
<note><para>It appears that at least some PXE versions want <note><para>It appears that at least some <acronym>PXE</acronym> versions want
the TCP version of TFTP. In this case, add a second line, the <acronym>TCP</acronym> version of <acronym>TFTP</acronym>. In this case, add a second line,
replacing <literal>dgram udp</literal> with <literal>stream replacing <literal>dgram udp</literal> with <literal>stream
tcp</literal>.</para> tcp</literal>.</para>
</note> </note>
</step> </step>
<step> <step>
<para>Tell <command>inetd</command> to reread its configuration <para>Tell <application>inetd</application> to reread its configuration
file:</para> file:</para>
<screen>&prompt.root; <userinput>kill -HUP `cat /var/run/inetd.pid`</userinput></screen> <screen>&prompt.root; <userinput>kill -HUP `cat /var/run/inetd.pid`</userinput></screen>
</step> </step>
@ -2722,8 +2857,8 @@ Exports list on foobar:
location is set in both <filename>inetd.conf</filename> and location is set in both <filename>inetd.conf</filename> and
<filename>dhcpd.conf</filename>.</para> <filename>dhcpd.conf</filename>.</para>
<para>You also need to enable NFS and export the <para>In all cases, you also need to enable <acronym>NFS</acronym> and export the
appropriate filesystem on the NFS server.</para> appropriate filesystem on the <acronym>NFS</acronym> server.</para>
<procedure> <procedure>
<step> <step>
@ -2735,14 +2870,14 @@ Exports list on foobar:
<para>Export the filesystem where the diskless root directory <para>Export the filesystem where the diskless root directory
is located by adding the following to is located by adding the following to
<filename>/etc/exports</filename> (adjust the volume mount <filename>/etc/exports</filename> (adjust the volume mount
point and replace <replaceable>margaux</replaceable> point and replace <replaceable>margaux corbieres</replaceable>
with the name of the diskless workstation):</para> with the names of the diskless workstations):</para>
<programlisting><replaceable>/data/misc</replaceable> -alldirs -ro <replaceable>margaux</replaceable></programlisting> <programlisting><replaceable>/data/misc</replaceable> -alldirs -ro <replaceable>margaux corbieres</replaceable></programlisting>
</step> </step>
<step> <step>
<para>Tell <command>mountd</command> to reread its configuration <para>Tell <application>mountd</application> to reread its configuration
file. If you actually needed to enable NFS in file. If you actually needed to enable <acronym>NFS</acronym> in
<filename>/etc/rc.conf</filename> <filename>/etc/rc.conf</filename>
at the first step, you probably want to reboot instead.</para> at the first step, you probably want to reboot instead.</para>
<screen>&prompt.root; <userinput>kill -HUP `cat /var/run/mountd.pid`</userinput></screen> <screen>&prompt.root; <userinput>kill -HUP `cat /var/run/mountd.pid`</userinput></screen>
@ -2759,23 +2894,50 @@ Exports list on foobar:
<secondary>kernel configuration</secondary> <secondary>kernel configuration</secondary>
</indexterm> </indexterm>
<para>Create a kernel configuration file for the diskless client <para>If using <application>etherboot</application>, you need to
with the following options (in addition to the usual create a kernel configuration file for the diskless client
ones):</para> with the following options (in addition to the usual ones):</para>
<programlisting> <programlisting>
options BOOTP # Use BOOTP to obtain IP address/hostname options BOOTP # Use BOOTP to obtain IP address/hostname
options BOOTP_NFSROOT # NFS mount root filesystem using BOOTP info options BOOTP_NFSROOT # NFS mount root filesystem using BOOTP info
options BOOTP_COMPAT # Workaround for broken bootp daemons.
</programlisting> </programlisting>
<para>You may also want to use <literal>BOOTP_NFSV3</literal> and <para>You may also want to use <literal>BOOTP_NFSV3</literal>,
<literal>BOOTP_WIRED_TO</literal> (refer to <filename>LINT</filename>).</para> <literal>BOOT_COMPAT</literal> and <literal>BOOTP_WIRED_TO</literal>
(refer to <filename>LINT</filename> in 4.X or
<filename>NOTES</filename> on 5.X).</para>
<para>Build the kernel (See <xref linkend="kernelconfig">), <para>These option names are historical and slightly misleading as
and copy it to the tftp directory, under the name listed they actually enable indifferent use of <acronym>DHCP</acronym> and
BOOTP inside the kernel (it is also possible to force strict BOOTP
or <acronym>DHCP</acronym> use).</para>
<para>Build the kernel (see <xref linkend="kernelconfig">),
and copy it to the place specified
in <filename>dhcpd.conf</filename>.</para> in <filename>dhcpd.conf</filename>.</para>
<note>
<para>When using <acronym>PXE</acronym>, building a kernel with the
above options is not strictly necessary (though suggested).
Enabling them will cause more <acronym>DHCP</acronym> requests to be
issued during kernel startup, with a small risk of inconsistency
between the new values and those retrieved by &man.pxeboot.8; in some
special cases. The advantage of using them is that the host name
will be set as a side effect. Otherwise you will need to set the
host name by another method, for example in a client-specific
<filename>rc.conf</filename> file.</para>
</note>
<note>
<para>In order to be loadable with
<application>etherboot</application>, a 5.X kernel needs to have
the device hints compiled in. You would typically set the
following option in the configuration file (see the
<filename>NOTES</filename> configuration comments file):</para>
<programlisting>hints "GENERIC.hints"</programlisting>
</note>
</sect3> </sect3>
@ -2790,11 +2952,17 @@ Exports list on foobar:
<para>You need to create a root filesystem for the diskless <para>You need to create a root filesystem for the diskless
workstations, in the location listed as workstations, in the location listed as
<literal>root-path</literal> in <literal>root-path</literal> in
<filename>dhcpd.conf</filename>.</para> <filename>dhcpd.conf</filename>. The following sections describe
two ways to do it.</para>
<para>The easiest way to do this is to use the <sect4>
<title>Using the <filename>clone_root</filename> Script</title>
<para>This is the quickest way to create a root filesystem, but
currently it is only supported on &os;&nbsp;4.X. This shell script
is located at
<filename>/usr/share/examples/diskless/clone_root</filename> <filename>/usr/share/examples/diskless/clone_root</filename>
shell script. This script needs customization, at least to adjust and needs customization, at least to adjust
the place where the filesystem will be created (the the place where the filesystem will be created (the
<literal>DEST</literal> variable).</para> <literal>DEST</literal> variable).</para>
@ -2812,21 +2980,51 @@ Exports list on foobar:
other examples in the <filename>diskless</filename> directory, other examples in the <filename>diskless</filename> directory,
they actually document a configuration method which is distinct they actually document a configuration method which is distinct
from the one used by <filename>clone_root</filename> and from the one used by <filename>clone_root</filename> and
<filename>/etc/rc.diskless[12]</filename>, which is a little the system startup scripts in
confusing. Use them for reference only, except if you prefer <filename role="directory">/etc</filename>, which is a little
confusing. Use them for reference only, except if you prefer
the method that they describe, in which case you will need the method that they describe, in which case you will need
customized <filename>rc</filename> scripts.</para> customized <filename>rc</filename> scripts.</para>
</sect4>
<sect4>
<title>Using the Standard <command>make world</command>
Procedure</title>
<para>This method can be applied to either &os;&nbsp;4.X or 5.X and
will install a complete virgin system (not only the root filesystem)
into <envar>DESTDIR</envar>.
All you have to do is simply execute the following script:</para>
<programlisting>#!/bin/sh
export DESTDIR=/data/misc/diskless
mkdir -p ${DESTDIR}
cd /usr/src; make world && make kernel
cd /usr/src/etc; make distribution</programlisting>
<para>Once done, you may need to customize your
<filename>/etc/rc.conf</filename> and
<filename>/etc/fstab</filename> placed into
<envar>DESTDIR</envar> according to your needs.</para>
</sect4>
</sect3> </sect3>
<sect3> <sect3>
<title>Configuring Swap</title> <title>Configuring Swap</title>
<para>If needed, a swap file located on the server can be <para>If needed, a swap file located on the server can be
accessed via NFS. The exact <filename>bootptab</filename> accessed via <acronym>NFS</acronym>. One of the methods commonly
or <filename>dhcpd.conf</filename> options are not clearly used to do this has been discontinued in release 5.X.</para>
documented at this time. The following configuration
suggestions have been reported to work in some installations <sect4>
using isc-dhcp 3.0rc11.</para> <title><acronym>NFS</acronym> Swap with &os;&nbsp;4.X</title>
<para>The swap file location and size can be specified with
BOOTP/<acronym>DHCP</acronym> &os;-specific options 128 and 129.
Examples of configuration files for
<application>ISC DHCP 3.0</application> or
<application>bootpd</application> follow:</para>
<procedure> <procedure>
<step><para>Add the following lines to <step><para>Add the following lines to
<filename>dhcpd.conf</filename>:</para> <filename>dhcpd.conf</filename>:</para>
@ -2841,24 +3039,25 @@ Exports list on foobar:
option swap-size <replaceable>64000</replaceable>; option swap-size <replaceable>64000</replaceable>;
} }
</programlisting> </programlisting>
<para>The idea is that, at least for a FreeBSD client,
DHCP/BOOTP option code 128 is the path to the NFS swap file, <para><literal>swap-path</literal> is the path to a directory
and option code 129 is the swap size in kilobytes. Older where swap files will be located. Each file will be named
versions of <command>dhcpd</command> allowed a syntax of <filename>swap.<replaceable>client-ip</replaceable></filename>.</para>
<para>Older versions of <application>dhcpd</application> used a syntax of
<literal>option option-128 "...</literal>, which is no <literal>option option-128 "...</literal>, which is no
longer supported.</para> longer supported.</para>
<para><filename>/etc/bootptab</filename> would use the <para><filename>/etc/bootptab</filename> would use the
following syntax instead:</para> following syntax instead:</para>
<para><literal>T128="192.168.4.4:/netswapvolume/netswap":T129=0000fa00 <programlisting>T128="192.168.4.4:/netswapvolume/netswap":T129=0000fa00</programlisting>
</literal></para>
<note><para>In <filename>/etc/bootptab</filename>, the swap <note><para>In <filename>/etc/bootptab</filename>, the swap
size must be expressed in hexadecimal format.</para></note> size must be expressed in hexadecimal format.</para></note>
</step> </step>
<step> <step>
<para>On the NFS swap file server, create the swap <para>On the <acronym>NFS</acronym> swap file server, create the swap
file(s)</para> file(s)</para>
<screen> <screen>
&prompt.root; <userinput>mkdir <replaceable>/netswapvolume/netswap</replaceable></userinput> &prompt.root; <userinput>mkdir <replaceable>/netswapvolume/netswap</replaceable></userinput>
@ -2871,16 +3070,33 @@ Exports list on foobar:
</step> </step>
<step> <step>
<para>On the NFS swap file server, add the following line to <para>On the <acronym>NFS</acronym> swap file server, add the following line to
<filename>/etc/exports</filename>:</para> <filename>/etc/exports</filename>:</para>
<programlisting> <programlisting>
<replaceable>/netswapvolume</replaceable> -maproot=0:10 -alldirs <replaceable>margaux</replaceable> <replaceable>/netswapvolume</replaceable> -maproot=0:10 -alldirs <replaceable>margaux corbieres</replaceable>
</programlisting> </programlisting>
<para>Then tell <application>mountd</application> to reread the <para>Then tell <application>mountd</application> to reread the
exports file, as above.</para> exports file, as above.</para>
</step> </step>
</procedure> </procedure>
</sect4>
<sect4>
<title><acronym>NFS</acronym> Swap with &os&nbsp;5.X</title>
<para>The kernel does not support enabling <acronym>NFS</acronym>
swap at boot time. Swap must be enabled by the startup scripts,
by mounting a writeable file system and creating and enabling a
swap file. To create a swap file of appropriate size, you can do
like this:</para>
<screen>&prompt.root; <userinput>dd if=/dev/zero of=<replaceable>/path/to/swapfile</replaceable> bs=1k count=1 oseek=<replaceable>100000</replaceable></userinput></screen>
<para>To enable it you have to add the following line to your
<filename>rc.conf</filename>:</para>
<programlisting>swapfile=<replaceable>/path/to/swapfile</replaceable></programlisting>
</sect4>
</sect3> </sect3>
<sect3> <sect3>
@ -2915,7 +3131,7 @@ Exports list on foobar:
to create the correct device entries (FreeBSD 5.0 and later to create the correct device entries (FreeBSD 5.0 and later
use &man.devfs.5; to allocate device nodes transparently for use &man.devfs.5; to allocate device nodes transparently for
the user, running <command>MAKEDEV</command> on these the user, running <command>MAKEDEV</command> on these
versions is useless).</para> versions is pointless).</para>
</sect4> </sect4>