diff options
| author | Jacob McDonnell <jacob@jacobmcdonnell.com> | 2026-04-25 15:32:58 -0400 |
|---|---|---|
| committer | Jacob McDonnell <jacob@jacobmcdonnell.com> | 2026-04-25 15:32:58 -0400 |
| commit | 5cb84ec742fd33f78c8022863fadaa8d0d93e176 (patch) | |
| tree | 1a81ca3665e6153923e40db7b0d988f8573ab59c /static/netbsd/man8/diskless.8 | |
| parent | a59214f344567c037d5776879bcfc5fcc1d4d5f6 (diff) | |
feat: Added NetBSD man pages
Diffstat (limited to 'static/netbsd/man8/diskless.8')
| -rw-r--r-- | static/netbsd/man8/diskless.8 | 898 |
1 files changed, 898 insertions, 0 deletions
diff --git a/static/netbsd/man8/diskless.8 b/static/netbsd/man8/diskless.8 new file mode 100644 index 00000000..4e1eb5f6 --- /dev/null +++ b/static/netbsd/man8/diskless.8 @@ -0,0 +1,898 @@ +.\" $NetBSD: diskless.8,v 1.35 2026/01/08 18:54:00 tsutsui Exp $ +.\" +.\" Copyright (c) 1994 Gordon W. Ross, Theo de Raadt +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. The name of the author may not be used to endorse or promote products +.\" derived from this software without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF +.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd January 8, 2026 +.Dt DISKLESS 8 +.Os +.Sh NAME +.Nm diskless +.Nd booting a system over the network +.Sh DESCRIPTION +The ability to boot a system over the network is useful for +two kinds of systems: +.Bl -tag -width diskless +.It Em diskless +a system with no attached mass storage media to boot or run from +.Pq e.g. a network computer . +.It Em dataless +a system with a hard drive that only contains system and application +software, and user data is mounted over the network from a central server. +.El +.Pp +It can also be done as a temporary measure while repairing or +re-installing file systems on a local disk. +This capability is necessarily platform dependent because of its +dependence on system firmware support; not all platforms supported by +.Nx +are capable of being network booted. +.Pp +The protocols used to obtain a network address +.Pq e.g. an \&IP host address , +include, but are not limited to: +.Pp +.Bl -tag -width BOOTP -offset indent -compact +.It Tn RARP +Reverse Address Resolution Protocol +.Pq Tn ARP +.It Tn DHCP +Dynamic Host Configuration Protocol +.It Tn BOOTP +Bootstrap Protocol +.El +.Pp +This information can also be derived from non-volatile +.Tn RAM +or by a transform of a network interface +.Pq e.g. Tn Ethernet +.Tn MAC +address. +.Pp +The protocols used to load a +.Nx +kernel over a network include, but are not limited to: +.Pp +.Bl -tag -width TFTP -offset indent -compact +.It Tn TFTP +Trivial File Transfer Protocol +.It Tn NFS +.Tn Sun +Network File System +.It Tn RMP +.Tn \&HP +Remote Maintenance Protocol +.It Tn MOP +.Tn DEC +Maintenance Operations Protocol +.El +.Pp +Derivation of the filename of the secondary bootstrap program can +be done by a transform of a network interface +.Tn MAC +address +.Pq or other protocol address , +or provided by a server as with +.Tn BOOTP , +and +.Tn DHCP . +How this is done is platform dependent; see +.Xr boot 8 . +.Pp +The +.Nx +kernel doesn't care how it gets loaded and started. +The protocols used to boot +.Nx +can be completely different from the ones that +.Nx +uses operationally, i.e. you can netboot the system using +.Tn \&HP +.Tn RMP +and the +.Nx +kernel can use +.Tn \&IP +to communicate after bootstrap. +.Pp +There is no standard way to pass all the required information +from a boot loader to an operating system kernel, so the +.Nx +kernel usually has to recapitulate the same +.Pq or similar +protocol exchanges over the network to obtain a network address, +determine which servers to use, and so on. +.Nx +supports obtaining this information from +.Tn RARP , +.Tn BOOTP , +.Tn DHCP , +and +.Tn Sun RPC +.Qq bootparams . +See +.Xr options 4 +for a list of methods that can be compiled into a +.Nx +kernel. +.Pp +.Nx +only supports the +.Tn Sun +Network File System +.Pq Tn NFS +for mounting its root file system over a network. +.Nx +can use any local mass storage device for which it has a driver, +after bootstrap, even if that device is not supported by the system's +firmware for booting. +.Pp +.Sy N.B. +.Tn DHCP +is essentially a series of extensions to +.Tn BOOTP ; +the +.Nx +.Xr dhcpd 8 +is capable of responding to both kinds of protocol requests. +.Pp +In the majority of configurations, network boot servers and clients +are attached to the same +.Tn LAN +so that broadcast queries from the clients can be heard by the servers. +Unless specially configured, routers block broadcasts from propagating from +.Tn LAN +to +.Tn LAN ; +some routers can be configured to +.Qq forward +broadcast +.Tn BOOTP +packets to another +.Tn LAN +attached to that router, which permits a server on that remote +.Tn LAN +to respond to the client's broadcast query. +.Sh OPERATION +When booting a system over the network, there are three +phases of interaction between client and server: +.Pp +.Bl -enum -compact +.It +The system firmware +.Pq or stage-1 bootstrap +loads a boot program. +.It +The boot program loads a +.Nx +kernel. +.It +The +.Nx +kernel performs an +.Tn NFS +mount of the root file system. +.El +.Pp +Each of these phases is described in further detail below. +.Ss 1. loading a boot program +In phase 1, the system firmware loads a boot program. +Firmware designs vary widely, +so this phase is inherently machine-specific. +Some examples: +.Pp +.Tn DEC +Alpha systems use +.Tn BOOTP +to determine the client's +.Tn \&IP +address and then use +.Tn TFTP +to load a secondary bootstrap program from the server and filename +specified in the +.Tn BOOTP +reply. +.Tn DEC +Alpha systems can also use +.Tn MOP +to load a program to run the system. +.Pp +.Tn Sun +systems use +.Tn RARP +to determine the client's +.Tn \&IP +address, transform that address to a hexadecimal string to form +the filename of the secondary boot program, and then use +.Tn TFTP +to download the boot program from the server that sent the +.Tn RARP +reply. +.Pp +.Tn \&HP +300-series systems use the +.Tn \&HP +.Tn RMP +to download a boot program. +.Pp +Typical personal computers may load a network boot program either +from diskette or from a +.Tn PROM +on a Network Interface Card +.Pq Tn NIC . +Some +.Tn BIOS Ns No \&es +support booting from a network interface. +.Ss 2. loading a kernel +In phase 2, the secondary boot program loads a kernel. +Operation in this phase depends on the design of the boot program. +A secondary bootstrap program that uses +.Tn RARP +and +.Tn Sun RPC BOOTPARAMS +typically does the following: +.Pp +.Bl -enum -compact +.It +gets the client +.Tn \&IP +address using +.Tn RARP . +.It +gets the client name and server +.Tn \&IP +address by broadcasting an +.Tn RPC / BOOTPARAMS / WHOAMI +request with the client +.Tn \&IP +address. +.It +gets the server path for this client's +root using an +.Tn RPC / BOOTPARAMS / GETFILE +request with the client name. +.It +gets the root file handle by calling +.Xr mountd 8 +with the server path for the client root file system. +.It +gets the kernel file handle by calling +.Tn NFS +.Fn lookup +on the root file handle. +.It +loads the kernel using +.Tn NFS +read calls on the kernel file handle. +.It +transfers control to the kernel entry point. +.El +.Pp +A secondary bootstrap program that uses +.Tn BOOTP +and/or +.Tn DHCP +typically does the following: +.Pp +.Bl -enum -compact +.It +query for the client's bootstrap parameters. +The response must include the client's +.Tn \&IP +address, server's +.Tn \&IP +address, an +.Tn NFS +root path, and a filename to load the +.Nx +kernel from. +.It +gets the root file handle by calling +.Xr mountd 8 +with the server path for the client root file system. +.It +gets the kernel file handle by calling +.Tn NFS +.Fn lookup +on the root file handle. +.It +loads the kernel using +.Tn NFS +read calls on the kernel file handle. +.It +transfers control to the kernel entry point. +.El +.Ss 3. NFS mounting the root file system +In phase 3, the kernel performs an +.Tn NFS +mount of the root file system. +The kernel repeats much of the work done by the boot program +because there is no standard way for the boot program to pass +the information it gathered on to the kernel. +.Pp +In general, the GENERIC kernel +.Xr config 1 +file for any particular architecture will specify compile-time +options to use the same protocol used by the secondary boot program +for that architecture. +A +.Nx +kernel can be compiled to use any of +.Tn BOOTP , +.Tn DHCP , +or +.Tn Sun RPC BOOTPARAMS ; +see +.Xr options 4 . +.Pp +The procedure typically used by the kernel is as follows: +.Pp +.Bl -enum -compact +.It +The kernel finds a boot server using the same procedures +as described above to determine the client's +.Tn \&IP +address, an +.Tn NFS +server, etc. +.It +The kernel gets the +.Tn NFS +file handle for root using the same procedure as described above. +.It +The kernel calls the +.Tn NFS +.Fn getattr +function to get the last-modified time of the root +directory, and uses it to check the system clock. +.El +.Sh SERVER CONFIGURATION +Before a client can bootstrap over the network, +its server must be configured. +Each daemon that implements these protocols must be set up so +that it can answer queries from the clients. +Some of these daemons are invoked as packets come in, by +.Xr inetd 8 , +and some must run independently, started from +.Pa /etc/rc ; +see +.Xr rc.conf 5 . +.Bl -column "Protocol" "rpc.bootparamd" "inetd.conf(5)" -offset indent +.It Sy Protocol Ta Sy Program Ta Sy Startup +.It RARP Ta rarpd Ta Xr rc.conf 5 +.It DHCP Ta dhcpd Ta Xr rc.conf 5 +.It BOOTP Ta bootpd Ta Xr inetd.conf 5 +.It TFTP Ta tftpd Ta Xr inetd.conf 5 +.It Sun RPC Ta rpcbind Ta Xr rc.conf 5 +.It Sun RPC Ta rpc.bootparamd Ta Xr rc.conf 5 +.It Sun NFS Ta mountd Ta Xr rc.conf 5 +.It Sun NFS Ta nfsiod Ta Xr rc.conf 5 +.It \&HP RMP Ta rbootd Ta Xr rc.conf 5 +.El +.Pp +.Sy N.B. +.Tn DHCP +is essentially a series of extensions to +.Tn BOOTP ; +the +.Nx +.Xr dhcpd 8 +is capable of responding to both kinds of protocol requests. +Since they both bind to the same +.Tn UDP +port, only one may be run on a given server. +.Pp +In the following examples, the client's hostname is +.Sy myclient ; +the server is +.Sy myserver , +and the addresses are all fictional. +In these examples +the hostnames may be Fully Qualified Domain Names +.Pq FQDN, e.g. Qq myclient.mydomain.com +provided that they are used consistently. +.Ss RARP +For clients that use +.Tn RARP +to obtain their +.Tn \&IP +address, +an entry must be added for each client to +.Pa /etc/ethers +with the client's +.Tn Ethernet +.Tn MAC +address and Internet hostname: +.Pp +.Bd -literal -offset indent -compact +8:0:20:7:c5:c7 myclient +.Ed +.Pp +This will be used by +.Xr rarpd 8 +to reply to queries from the clients. +There must be one entry per client system. +.Pp +A client system's +.Tn Ethernet +.Tn MAC +address is often printed on the system case, or on a chip on its +motherboard, or on the +.Tn NIC . +If not, +.Qq sniffing +the network with +.Xr tcpdump 8 +when the client is powered-on should reveal its +.Tn Ethernet +.Tn MAC +address. +.Pp +Each client system that uses +.Tn RARP +must have its own, unique +.Tn \&IP +address assigned to it. +Assign an +.Tn \&IP +address for myclient in your +.Pa /etc/hosts +file, or in the master file for your +.Tn DNS +zone. +For +.Pa /etc/hosts +the entry should look like: +.Pp +.Bd -literal -offset indent -compact +192.197.96.12 myclient +.Ed +.Ss DHCP/BOOTP +The +.Nx +.Tn DHCP +server +.Xr dhcpd 8 +was developed by the Internet Software Consortium +.Pq Lk http://www.isc.org/ "ISC" . +.Pp +.Tn DHCP +can provide a wide range of information to a requesting client; +the key data for bootstrapping a diskless client are: +.Pp +.Bl -enum -compact +.It +an +.Tn \&IP +address +.It +a subnet mask +.It +a +.Tn TFTP +server address for loading the secondary bootstrap and the +.Nx +kernel +.It +a filename of the secondary bootstrap +.It +an +.Tn NFS +server address for the client's file system +.It +the client's root file system path, to be +.Tn NFS +mounted. +.El +.Pp +An example for +.Pa /etc/dhcpd.conf +.Bd -literal -offset indent +host myclient { + hardware ethernet 8:0:20:7:c5:c7; + fixed-address myclient; # client's assigned IP address + filename "myclient.netboot"; # secondary bootstrap + next-server myserver; # TFTP server for secondary bootstrap + option swap-server myserver; # NFS server for root filesystem + option root-path "/export/myclient/root"; +} +.Ed +.Pp +That +.Sy host +declaration goes inside a +.Sy subnet +declaration, which gives parameters for all hosts on the subnet +that will be using +.Tn DHCP , +such as the +.Qq routers +.Pq the default route , +.Qq subnet-mask , +.Qq broadcast-address , +.Qq domain-name-servers , +etc. +See +.Xr dhcpd.conf 5 +for details. +In that example, +.Sy myclient +has an assigned IP address. +.Pp +The +.Tn DHCP +parameters required for network bootstrapping a system will vary +from platform to platform, as dictated by each system's firmware. +In particular, because +.Tn DHCP +is extensible, some hardware vendors have specified +.Tn DHCP +options to return information to requesting clients that are specific +to that platform. +Please see your platform's +.Xr boot 8 +for details. +.Ss TFTP +If booting a +.Tn Sun +system, or other system that expects to use +.Tn TFTP , +ensure that +.Xr inetd 8 +is configured to run +.Xr tftpd 8 . +The +.Xr tftpd 8 +server should be set up to serve the directory +.Pa /tftpboot . +.Pp +If booting a +.Tn SPARC +system, install a copy of the appropriate diskless secondary boot +loader +.Po +such as +.Pa /usr/mdec/boot +or +.Pa ofwboot.net +.Pc +in the +.Pa /tftpboot +directory. +Make a link such that the boot program is +accessible by a filename composed of the client's +.Tn \&IP +address in hexadecimal, a dot, and the architecture name +.Pq all upper case . +For example: +.Pp +.Bd -literal -offset indent -compact +# cd /tftpboot +# ln -s boot C0C5600C.SUN4 +.Ed +.Pp +For a +.Tn Sun-3 +or +.Tn UltraSPARC +system, the filename would be just C0C5600C +.Po +these systems' firmware does not append the architecture name +.Pc . +The name used is architecture dependent, it simply has to match +what the booting client's system firmware wishes it to be. +.Pp +If the client's system firmware fails to fetch the expected file, +.Xr tcpdump 8 +can be used to discover which filename the client is requesting. +Also, examination of +.Xr tftpd 8 +log entries +.Po +typically in +.Pa /var/log/messages +.Pc +should show whether the server is hearing the client system, and +what filename the client is asking for. +.Ss HP RMP +If booting an +.Tn HP +300-series system, ensure that +.Pa /etc/rbootd.conf +is configured properly to transfer the boot program to the client. +An entry might look like this: +.Pp +.Bd -literal -offset indent -compact +08:00:09:01:23:E6 SYS_UBOOT # myclient +.Ed +.Pp +The secondary bootstrap program for an +.Tn \&HP +300-series system +.Pa SYS_UBOOT +.Po +which may be called +.Pa uboot.lif +before installation +.Pc +must be installed in the directory +.Pa /usr/mdec/rbootd . +.Pp +See the +.Xr rbootd 8 +manual page for more information. +.Ss Sun RPC BOOTPARAMS +Add +.Sy myclient +to the bootparams database in +.Pa /etc/bootparams : +.Pp +.Bd -literal -offset indent -compact +myclient root=myserver:/export/myclient/root \\ + swap=myserver:/export/myclient/root/swap \\ + dump=myserver:/export/myclient/root/swap +.Ed +.Pp +and ensure that +.Xr rpc.bootparamd 8 +and +.Xr rpcbind 8 +are running. +Both +.Sy myclient +and +.Sy myserver +must have +.Tn \&IP +addresses in the +.Tn DNS +or +.Pa /etc/hosts . +.Ss Diskless Client File Systems +Build the swap file for +.Sy myclient +on the +.Tn NFS +server: +.Pp +.Bd -literal -offset indent -compact +# cd /export/myclient/root +# dd if=/dev/zero of=swap bs=16k count=1024 +.Ed +.Pp +This creates a 16 megabyte swap file. +.Pp +Populate +.Sy myclient Ns No 's +root file system on the +.Tn NFS +server. +How this is done depends on the client architecture and the version +of the +.Nx +distribution. +It can be as simple as copying and modifying the server's root +file system, or unpack a complete +.Nx +binary distribution for the appropriate platform. +.Pp +If the +.Tn NFS +server is going to support multiple different architectures +.Po +e.g. +.Tn Alpha , +.Tn PowerPC , +.Tn SPARC , +.Tn MIPS +.Pc , +then it is important to think carefully about how to lay out the +.Tn NFS +server's exported file systems, to share what can be shared +.Pq e.g. text files, configuration files, user home directories , +and separate that which is distinct to each architecture +.Pq e.g. binary executables, libraries . +.Ss NFS +Export the client-populated file systems on the +.Tn NFS +server in +.Pa /etc/exports : +.Pp +.Bd -literal -offset indent -compact +/usr -ro myclient +# for SunOS: +# /export/myclient -rw=myclient,root=myclient +# for NetBSD: +/export/myclient -maproot=root -alldirs myclient +.Ed +.Pp +If the server and client are of the same architecture, then the client +can share the server's +.Pa /usr +file system +.Pq as is done above . +If not, you must build a properly fleshed out +.Pa /usr +partition for the client in some other part of the server's +file system, to serve to the client. +.Pp +If your server is a +.Tn SPARC , +and your client a +.Tn Sun-3 , +you might create and fill +.Pa /export/usr.sun3 +and then use the following +.Pa /etc/exports +lines: +.Pp +.Bd -literal -offset indent -compact +/export/usr.sun3 -ro myclient +/export/myclient -rw=myclient,root=myclient +.Ed +.Pp +Of course, in either case you will have to have an +.Tn NFS +server running on the server side. +.Sh CLIENT CONFIGURATION +Copy and customize at least the following files in +.Pa /export/myclient/root : +.Pp +.Bd -literal -offset indent -compact +# cd /export/myclient/root/etc +# vi fstab +# cp /etc/hosts hosts +# echo 'hostname="myclient"' >> rc.conf +# echo "inet 192.197.96.12" > ifconfig.le0 +.Ed +.Pp +Note that "le0" above should be replaced with the name of +the network interface that the client will use for booting; +the network interface name is device dependent in +.Nx . +.Pp +Correct the critical mount points and the swap file in the client's +.Pa /etc/fstab +.Po +which will be +.Pa /export/myclient/root/etc/fstab +.Pc +i.e. +.Pp +.Bd -literal -offset indent -compact +myserver:/export/myclient/root / nfs rw 0 0 +myserver:/usr /usr nfs rw 0 0 +/swap none swap sw 0 0 +.Ed +.Pp +Note, you +.Em must +specify the swap file in +.Pa /etc/fstab +or it will not be used! +See +.Xr swapctl 8 . +.Pp +It may be useful to set +.Dq flushroutes=NO +in +.Pa /etc/rc.conf +to avoid the default route supplied by the boot setup +disappearing mid-boot. +.Sh FILES +.Bl -tag -width /usr/mdec/rbootd -compact +.It Pa /etc/hosts +table of associated +.Tn \&IP +addresses and +.Tn \&IP +host names; see +.Xr hosts 5 +.It Pa /etc/ethers +table of associated +.Tn Ethernet +.Tn MAC +addresses and +.Tn \&IP +host names used by +.Xr rarpd 8 ; +see +.Xr ethers 5 +.It Pa /etc/bootparams +client root pathname and swap pathname; see +.Xr bootparams 5 +.It Pa /etc/exports +exported +.Tn NFS +mount points; see +.Xr exports 5 +.It Pa /etc/rbootd.conf +configuration file for +.Tn \&HP RMP ; +see +.Xr rbootd 8 +.It Pa /usr/mdec/rbootd +location of boot programs offered by +.Xr rbootd 8 +.It Pa /tftpboot +location of boot programs offered by +.Xr tftpd 8 +.El +.Sh SEE ALSO +.Xr bootparams 5 , +.Xr dhcpd.conf 5 , +.Xr ethers 5 , +.Xr exports 5 , +.Xr fstab 5 , +.Xr hosts 5 , +.Xr networks 5 , +.Xr boot 8 , +.Xr dhcpd 8 , +.Xr mopd 8 , +.Xr mountd 8 , +.Xr nfsd 8 , +.Xr rarpd 8 , +.Xr rbootd 8 , +.Xr reboot 8 , +.Xr rpc.bootparamd 8 , +.Xr tftpd 8 +.Rs +.%R RFC +.%N 903 +.%D June 1984 +.%T "Reverse Address Resolution Protocol" +.Re +.Rs +.%R RFC +.%N 906 +.%D June 1984 +.%T "Bootstrap Loading using TFTP" +.Re +.Rs +.%R RFC +.%N 951 +.%D September 1985 +.%T "Bootstrap Protocol" +.Re +.Rs +.%R RFC +.%N 1350 +.%D July 1992 +.%T "The TFTP Protocol (Revision 2)" +.Re +.Rs +.%R RFC +.%N 2131 +.%D March 1997 +.%T "Dynamic Host Configuration Protocol" +.Re +.Rs +.%R RFC +.%N 2132 +.%D March 1997 +.%T "DHCP Options and BOOTP Vendor Extensions" +.Re +.Pp +.Lk http://www.rfc-editor.org/ "RFC Editor" |
