<!-- $Id$ -->
<!-- The FreeBSD Documentation Project -->

<sect><heading>Diskless operation<label id="diskless"></heading>

<p><em>Contributed by &a.martin;.</em>

        <tt>netboot.com/netboot.rom</tt> allow you to boot your
	FreeBSD machine over the network and run FreeBSD without
	having a disk on your client.  Under 2.0 it is now
	possible to have local swap.  Swapping over NFS is also
	still supported.

	Supported Ethernet cards include: Western Digital/SMC
	8003, 8013, 8216 and compatibles; NE1000/NE2000 and
	compatibles (requires recompile)

    <sect1>
      <heading>Setup Instructions</heading>

      <p><enum> 
	  <item> Find a machine that will be your server.  This
	    machine will require enough disk space to hold the
	    FreeBSD 2.0 binaries and have bootp, tftp and NFS
	    services available.

	    Tested machines:
	      <itemize>
		<item>HP9000/8xx running HP-UX 9.04 or later (pre
		  9.04 doesn't work)</item> 
		<item>Sun/Solaris 2.3. (you may need to get
		  bootp)</item>
	      </itemize>
	    
	  <item>Set up a bootp server to provide the client with
	    IP, gateway, netmask.
<tscreen><verb>
diskless:\
        :ht=ether:\
        :ha=0000c01f848a:\
        :sm=255.255.255.0:\
        :hn:\
        :ds=192.1.2.3:\
        :ip=192.1.2.4:\
        :gw=192.1.2.5:\
        :vm=rfc1048:
</verb></tscreen></item>

	<item>Set up a TFTP server (on same machine as bootp
	    server) to provide booting information to client.
	    The name of this file is <tt>cfg.X.X.X.X</tt> (or
	    <tt>/tftpboot/cfg.X.X.X.X</tt>, it will try both)
	    where <tt>X.X.X.X</tt> is the IP address of the
	    client.  The contents of this file can be any valid
	    netboot commands.  Under 2.0, netboot has the
	    following commands:
<tscreen><verb>
help			- print help list
ip <X.X.X.X>		- print/set client's IP address
server <X.X.X.X>	- print/set bootp/tftp server address
netmask <X.X.X.X>	- print/set netmask
hostname <name>		- print/set hostname
kernel <name>		- print/set kernel name
rootfs <ip:/fs>		- print/set root filesystem
swapfs <ip:/fs>		- print/set swap filesystem
swapsize <size>		- set diskless swapsize in Kbytes
diskboot		- boot from disk
autoboot		- continue boot process
trans <on|off>		- turn transceiver on|off
flags [bcdhsv]		- set boot flags
</verb></tscreen>
    A typical completely diskless cfg file might contain:
<tscreen><verb>
rootfs 192.1.2.3:/rootfs/myclient
swapfs 192.1.2.3:/swapfs
swapsize 20000
hostname myclient.mydomain
</verb></tscreen>
    A cfg file for a machine with local swap might contain:
<tscreen><verb>
rootfs 192.1.2.3:/rootfs/myclient
hostname myclient.mydomain
</verb></tscreen>

	  <item>Ensure that your NFS server has exported the root
	    (and swap if applicable) filesystems to your client,
	    and that the client has root access to these
	    filesystems

	    A typical <tt>/etc/exports</tt> file on FreeBSD might
	    look like:
<tscreen><verb>
/rootfs/myclient -maproot=0:0 myclient.mydomain
/swapfs -maproot=0:0 myclient.mydomain
</verb></tscreen>

	    And on HP-UX:
<tscreen><verb>
/rootfs/myclient -root=myclient.mydomain
/swapfs -root=myclient.mydomain
</verb></tscreen>

	  <item>If you are swapping over NFS (completely diskless
	    configuration) create a swap file for your client
	    using <tt>dd</tt>.  If your <tt>swapfs</tt> command has the
	    arguments <tt>/swapfs</tt> and the size 20000 as in the
            example above, the swapfile for myclient will be called
	    <tt>/swapfs/swap.X.X.X.X</tt> where <tt>X.X.X.X</tt>
	    is the client's IP addr, eg:   
<tscreen><verb>
# dd if=/dev/zero of=/swapfs/swap.192.1.2.4 bs=1k count=20000
</verb></tscreen>

            Also, the client's swap space might contain sensitive
            information once swapping starts, so make sure to
            restrict read and write access to this file to prevent
            unauthorized access:
<tscreen><verb>
# chmod 0600 /swapfs/swap.192.1.2.4
</verb></tscreen>

	  <item> Unpack the root filesystem in the directory the
	    client will use for its root filesystem
	    (<tt>/rootfs/myclient</tt> in the example above).

	    <itemize>

	      <item> On HP-UX systems: The server should be
		running HP-UX 9.04 or later for HP9000/800 series
		machines.  Prior versions do not allow the
		creation of device files over NFS.

	      <item> When extracting <tt>/dev</tt> in
		<tt>/rootfs/myclient</tt>, beware that some
		systems (HPUX) will not create device files that
		FreeBSD is happy with.  You may have to go to
		single user mode on the first bootup (press
		control-c during the bootup phase), cd
		<tt>/dev</tt> and do a "<tt>sh ./MAKEDEV
		all</tt>" from the client to fix this.
	    </itemize>

	  <item>Run <tt>netboot.com</tt> on the client or make an EPROM
	    from the <tt>netboot.rom</tt> file
	</enum>

    <sect1>
      <heading>Using Shared <tt>/</tt> and <tt>/usr</tt> filesystems</heading>

      <p>At present there isn't an officially sanctioned way of
	doing this, although I have been using a shared <tt>/usr</tt>
	filesystem and individual <tt>/</tt> filesystems for each client.
	If anyone has any suggestions on how to do this cleanly,
	please let me and/or the &a.core; know.

    <sect1>
      <heading>Compiling netboot for specific setups</heading>

      <p>Netboot can be compiled to support NE1000/2000 cards by
	changing the configuration in
	<tt>/sys/i386/boot/netboot/Makefile</tt>.  See the
	comments at the top of this file.

