diff options
Diffstat (limited to 'share/man/man8')
| -rw-r--r-- | share/man/man8/MAKEDEV.8 | 46 | ||||
| -rw-r--r-- | share/man/man8/Makefile | 29 | ||||
| -rw-r--r-- | share/man/man8/crash.8 | 220 | ||||
| -rw-r--r-- | share/man/man8/diskless.8 | 480 | ||||
| -rw-r--r-- | share/man/man8/intro.8 | 95 | ||||
| -rw-r--r-- | share/man/man8/nanobsd.8 | 337 | ||||
| -rw-r--r-- | share/man/man8/picobsd.8 | 663 | ||||
| -rw-r--r-- | share/man/man8/rc.8 | 542 | ||||
| -rw-r--r-- | share/man/man8/rc.sendmail.8 | 263 | ||||
| -rw-r--r-- | share/man/man8/rc.subr.8 | 890 | ||||
| -rw-r--r-- | share/man/man8/rescue.8 | 184 | ||||
| -rw-r--r-- | share/man/man8/sticky.8 | 82 | ||||
| -rw-r--r-- | share/man/man8/yp.8 | 574 |
13 files changed, 4405 insertions, 0 deletions
diff --git a/share/man/man8/MAKEDEV.8 b/share/man/man8/MAKEDEV.8 new file mode 100644 index 0000000..8b42493 --- /dev/null +++ b/share/man/man8/MAKEDEV.8 @@ -0,0 +1,46 @@ +.\" Copyright (c) 2003, Giorgos Keramidas +.\" 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. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``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 OR CONTRIBUTORS 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. +.\" +.\" $FreeBSD$ +.\" +.Dd March 25, 2003 +.Dt MAKEDEV 8 +.Os +.Sh NAME +.Nm MAKEDEV +.Nd old script for creating device nodes +.Sh DESCRIPTION +The +.Nm +script was deprecated by +.Xr devfs 5 +and removed from +.Fx +after +.Xr devfs 5 +became mandatory. +.Sh SEE ALSO +.Xr intro 4 , +.Xr devfs 5 , +.Xr intro 8 diff --git a/share/man/man8/Makefile b/share/man/man8/Makefile new file mode 100644 index 0000000..279a874 --- /dev/null +++ b/share/man/man8/Makefile @@ -0,0 +1,29 @@ +# @(#)Makefile 8.1 (Berkeley) 6/5/93 +# $FreeBSD$ + +MAN= crash.8 \ + diskless.8 \ + intro.8 \ + MAKEDEV.8 \ + nanobsd.8 \ + picobsd.8 \ + rc.8 \ + rc.sendmail.8 \ + rc.subr.8 \ + rescue.8 \ + sticky.8 \ + yp.8 + +MLINKS= rc.8 rc.atm.8 \ + rc.8 rc.d.8 \ + rc.8 rc.firewall.8 \ + rc.8 rc.local.8 \ + rc.8 rc.network.8 \ + rc.8 rc.pccard.8 \ + rc.8 rc.serial.8 \ + rc.8 rc.shutdown.8 +MLINKS+=yp.8 NIS.8 \ + yp.8 nis.8 \ + yp.8 YP.8 + +.include <bsd.prog.mk> diff --git a/share/man/man8/crash.8 b/share/man/man8/crash.8 new file mode 100644 index 0000000..94a0ecc --- /dev/null +++ b/share/man/man8/crash.8 @@ -0,0 +1,220 @@ +.\" FreeBSD version Copyright (c) 1996 +.\" Mike Pritchard <mpp@FreeBSD.org>. All rights reserved. +.\" +.\" Adapted from share/man/man8/man8.hp300/crash.8 +.\" +.\" Copyright (c) 1990, 1991, 1993 +.\" The Regents of the University of California. 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. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``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 REGENTS OR CONTRIBUTORS 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. +.\" +.\" $FreeBSD$ +.\" +.Dd February 2, 1996 +.Dt CRASH 8 +.Os +.Sh NAME +.Nm crash +.Nd FreeBSD system failures +.Sh DESCRIPTION +This section explains a bit about system crashes +and (very briefly) how to analyze crash dumps. +.Pp +When the system crashes voluntarily it prints a message of the form +.Bl -diag -offset indent +.It "panic: why i gave up the ghost" +.El +.Pp +on the console, and if dumps have been enabled (see +.Xr dumpon 8 ) , +takes a dump on a mass storage peripheral, +and then invokes an automatic reboot procedure as +described in +.Xr reboot 8 . +Unless some unexpected inconsistency is encountered in the state +of the file systems due to hardware or software failure, the system +will then resume multi-user operations. +.Pp +The system has a large number of internal consistency checks; if one +of these fails, then it will panic with a very short message indicating +which one failed. +In many instances, this will be the name of the routine which detected +the error, or a two-word description of the inconsistency. +A full understanding of most panic messages requires perusal of the +source code for the system. +.Pp +The most common cause of system failures is hardware failure, which +can reflect itself in different ways. +Here are the messages which +are most likely, with some hints as to causes. +Left unstated in all cases is the possibility that hardware or software +error produced the message in some unexpected way. +.Pp +.Bl -diag -compact +.It "cannot mount root" +This panic message results from a failure to mount the root file system +during the bootstrap process. +Either the root file system has been corrupted, +or the system is attempting to use the wrong device as root file system. +Usually, an alternate copy of the system binary or an alternate root +file system can be used to bring up the system to investigate. +Most often +this is done by the use of the boot floppy you used to install the system, +and then using the +.Dq fixit +floppy. +.Pp +.It "init: not found" +This is not a panic message, as reboots are likely to be futile. +Late in the bootstrap procedure, the system was unable to locate +and execute the initialization process, +.Xr init 8 . +The root file system is incorrect or has been corrupted, or the mode +or type of +.Pa /sbin/init +forbids execution or is totally missing. +.Pp +.It "ffs_realloccg: bad optim" +.It "ffs_valloc: dup alloc" +.It "ffs_alloccgblk: cyl groups corrupted" +.It "ffs_alloccg: map corrupted" +.It "blkfree: freeing free block" +.It "blkfree: freeing free frag" +.It "ifree: freeing free inode" +These panic messages are among those that may be produced +when file system inconsistencies are detected. +The problem generally results from a failure to repair damaged file systems +after a crash, hardware failures, or other condition that should not +normally occur. +A file system check will normally correct the problem. +.Pp +.It "timeout table full" +This really should not be a panic, but until the data structure +involved is made to be extensible, running out of entries causes a crash. +If this happens, make the timeout table bigger. +.Pp +.\" .It "trap type %d, code = %x, v = %x" +.\" An unexpected trap has occurred within the system; the trap types are: +.\" .Bl -column xxxx -offset indent +.\" 0 bus error +.\" 1 address error +.\" 2 illegal instruction +.\" 3 divide by zero +.\" .No 4\t Em chk No instruction +.\" .No 5\t Em trapv No instruction +.\" 6 privileged instruction +.\" 7 trace trap +.\" 8 MMU fault +.\" 9 simulated software interrupt +.\" 10 format error +.\" 11 FP coprocessor fault +.\" 12 coprocessor fault +.\" 13 simulated AST +.\" .El +.\" .Pp +.\" The favorite trap type in system crashes is trap type 8, +.\" indicating a wild reference. +.\" ``code'' (hex) is the concatenation of the +.\" MMU +.\" status register +.\" (see <hp300/cpu.h>) +.\" in the high 16 bits and the 68020 special status word +.\" (see the 68020 manual, page 6-17) +.\" in the low 16. +.\" ``v'' (hex) is the virtual address which caused the fault. +.\" Additionally, the kernel will dump about a screenful of semi-useful +.\" information. +.\" ``pid'' (decimal) is the process id of the process running at the +.\" time of the exception. +.\" Note that if we panic in an interrupt routine, +.\" this process may not be related to the panic. +.\" ``ps'' (hex) is the 68020 processor status register ``ps''. +.\" ``pc'' (hex) is the value of the program counter saved +.\" on the hardware exception frame. +.\" It may +.\" .Em not +.\" be the PC of the instruction causing the fault. +.\" ``sfc'' and ``dfc'' (hex) are the 68020 source/destination function codes. +.\" They should always be one. +.\" ``p0'' and ``p1'' are the +.\" VAX-like +.\" region registers. +.\" They are of the form: +.\" .Pp +.\" .Bd -ragged -offset indent +.\" <length> '@' <kernel VA> +.\" .Ed +.\" .Pp +.\" where both are in hex. +.\" Following these values are a dump of the processor registers (hex). +.\" Finally, is a dump of the stack (user/kernel) at the time of the offense. +.\" .Pp +.It "init died (signal #, exit #)" +The system initialization process has exited with the specified +signal number and exit code. +This is bad news, as no new users will then be able to log in. +Rebooting is the only fix, so the +system just does it right away. +.El +.Pp +That completes the list of panic types you are likely to see. +.Pp +If the system has been configured to take crash dumps (see +.Xr dumpon 8 ) , +then when it crashes it will write (or at least attempt to write) +an image of memory into the back end of the dump device, +usually the same as the primary swap +area. +After the system is rebooted, the program +.Xr savecore 8 +runs and preserves a copy of this core image and the current +system in a specified directory for later perusal. +See +.Xr savecore 8 +for details. +.Pp +To analyze a dump you should begin by running +.Xr kgdb 1 +on the system load image and core dump. +If the core image is the result of a panic, +the panic message is printed. +For more details consult the chapter on kernel debugging in +the +.%B "FreeBSD Developers' Handbook" +.Pq Pa http://www.FreeBSD.org/ . +.Sh SEE ALSO +.Xr kgdb 1 , +.Xr dumpon 8 , +.Xr reboot 8 , +.Xr savecore 8 +.Sh HISTORY +The +.Nm +manual page first appeared in +.Fx 2.2 . diff --git a/share/man/man8/diskless.8 b/share/man/man8/diskless.8 new file mode 100644 index 0000000..a7282ea --- /dev/null +++ b/share/man/man8/diskless.8 @@ -0,0 +1,480 @@ +.\" Copyright (c) 1994 Gordon W. Ross, Theo de Raadt +.\" Updated by Luigi Rizzo, Robert Watson +.\" 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. +.\" +.\" $FreeBSD$ +.\" +.Dd December 10, 2005 +.Dt DISKLESS 8 +.Os +.Sh NAME +.Nm diskless +.Nd booting a system over the network +.Sh DESCRIPTION +The ability to boot a machine over the network is useful for +.Em diskless +or +.Em dataless +machines, or as a temporary measure while repairing or +re-installing file systems 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 +When booting a system over the network, there are three +phases of interaction between client and server: +.Bl -enum +.It +The stage-1 bootstrap, typically PXE built into your Ethernet +card, loads a second-stage boot program. +.It +The second-stage boot program, typically +.Xr pxeboot 8 , +loads modules and +the kernel, and boots the kernel. +.It +The kernel +.Tn NFS +mounts the root directory and continues from there. +.El +.Pp +Each of these phases are described in further detail below. +.Pp +First, the stage-1 bootstrap loads the stage-2 boot program over +the network. +The stage-1 bootstrap typically uses +.Tn BOOTP +or +.Tn DHCP +to obtain the filename to load, then uses +.Tn TFTP +to load the file. +This file is typically called +.Pa pxeboot , +and should be copied from +.Pa /boot/pxeboot +into the +.Tn TFTP +directory on the server, which is typically +.Pa /tftpdir . +.Pp +The stage-2 boot program then loads additional modules and the kernel. +These files may not exist on the +.Tn DHCP +or +.Tn BOOTP +server. +You can use the +.Ic next-server +option available in +.Tn DHCP +configurations to specify the server holding +the second stage boot files and kernel. +The stage-2 program uses +.Tn NFS +or +.Tn TFTP +to obtain these files. +By default, +.Tn NFS +is used. +If you are using +.Xr pxeboot 8 , +you can install a version that uses +.Tn TFTP +by setting +.Li LOADER_TFTP_SUPPORT=YES +in your +.Xr make.conf 5 , +then recompiling and reinstalling +.Xr pxeboot 8 +via the command listed below. +It is often necessary to use +.Tn TFTP +here so you can place a custom kernel +in +.Pa /tftpdir/ . +If you use +.Tn NFS +and do not have a custom root file system for the +.Nm +client, the stage-2 boot will load your server's kernel as the kernel for +the +.Nm +machine, which may not be what you want to have happen. +.Bd -literal -offset indent +cd /usr/src/sys/boot/i386 +make clean; make; make install +cp /boot/pxeboot /tftpdir/ +.Ed +.Pp +In phase 3, the kernel acquires IP networking configuration in one +of two ways, and then proceeds to mount the root file system and start +operation. +If the phase 2 loader supports passing network configuration to the +kernel using the kernel environment, then the kernel will configure +the network interface using that information. +Otherwise, it must use +.Tn DHCP +or +.Tn BOOTP +to acquire +configuration information. +The boot +scripts recognize a +.Nm +startup and perform +the actions found in +.Pa /etc/rc.d/resolv , +.Pa /etc/rc.d/tmp , +.Pa /etc/rc.d/var , +and +.Pa /etc/rc.initdiskless . +.Sh CONFIGURATION +In order to run a +.Nm +client, you need the following: +.Bl -bullet +.It +An +.Tn NFS +server which exports a root and +.Pa /usr +partitions with appropriate permissions. +The +.Nm +scripts work with read-only partitions, as long as root is exported with +.Fl maproot Ns =0 +so that some system files can be accessed. +As an example, +.Pa /etc/exports +can contain the following lines: +.Bd -literal -offset indent +<ROOT> -ro -maproot=0 -alldirs <list of diskless clients> +/usr -ro -alldirs <list of diskless clients> +.Ed +.Pp +where +.Aq ROOT +is the mount point on the server of the root partition. +The script +.Pa /usr/share/examples/diskless/clone_root +can be used to create a shared read-only root partition, +but in many cases you may decide to export +(again as read-only) the root directory used by +the server itself. +.It +A +.Tn BOOTP +or +.Tn DHCP +server. +.Xr bootpd 8 +can be enabled by +uncommenting the +.Dq Li bootps +line in +.Pa /etc/inetd.conf . +A sample +.Pa /etc/bootptab +can be the following: +.Bd -literal -offset indent + .default:\\ + hn:ht=1:vm=rfc1048:\\ + :sm=255.255.255.0:\\ + :sa=<SERVER>:\\ + :gw=<GATEWAY>:\\ + :rp="<SERVER>:<ROOT>": + +<CLIENT>:ha=0123456789ab:tc=.default +.Ed +.Pp +where +.Aq SERVER , +.Aq GATEWAY +and +.Aq ROOT +have the obvious meanings. +.It +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 +.Nm +boot as you do on the server. +The +.Nm +boot +scripts provide a mechanism through which you can override various files +in +.Pa /etc +(as well as other subdirectories of root). +.Pp +One difference that you should pay particular attention to is +the value of +.Va local_startup +in +.Pa /etc/defaults/rc.conf . +A typical value for a +.Nm +boot is +.Va mountcritremote , +however your needs may be different. +.Pp +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 +.Nm +machine. +You can clone the server's +.Pa /etc +here or you can create a special file which tells the +.Nm +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 +.Nm +machine's +.Pa /etc . +For example, the file might contain: +.Pp +.Dl 10.0.0.1:/etc +.Pp +Alternatively, if the server contains several independent roots, the file +might contain: +.Pp +.Dl 10.0.0.1:/usr/diskless/4.7-RELEASE/etc +.Pp +This would work, but if you copied +.Pa /usr/diskless/4.7-RELEASE +to +.Pa /usr/diskless/4.8-RELEASE +and upgraded the installation, you would need to modify the +.Pa diskless_remount +files to reflect that move. +To avoid that, paths in +.Pa diskless_remount +files beginning with +.Pa / +have the actual path of the client's root prepended to them so the file +could instead contain: +.Pp +.Dl /etc +.Pp +The +.Nm +scripts create memory file systems to hold the overridden +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 provide overrides for +.Pa /etc/fstab , /etc/rc.conf , +and +.Pa /etc/rc.local +via +.Pa /conf/default/etc/fstab , /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/ Ns Ao Ar BROADCASTIP Ac Ns Pa /etc +directory, where +.Aq Ar BROADCASTIP +represents the broadcast IP address of +the +.Nm +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 file system. +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/ Ns Ao Ar DIRECTORY Ac Ns Pa .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 +.Bd -literal -offset indent +<SERVER>:<ROOT> / nfs ro 0 0 +<SERVER>:/usr /usr nfs ro 0 0 +.Ed +.Pp +You also need to create a customized version of +.Pa /conf/default/etc/rc.conf +which should contain +the startup options for the +.Nm +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 +.Nm +system. +.Pp +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. +Finally, it might be convenient to use a +.Ic case +statement using +.Li `hostname` +as the switch variable to do machine-specific configuration +in case a number of +.Nm +clients share the same configuration +files. +.It +The kernel for the +.Nm +clients, which will be loaded using +.Tn NFS +or +.Tn TFTP , +must include support for the NFS client: +.Pp +.D1 Cd "options NFSCLIENT" +.D1 Cd "options NFS_ROOT" +.Pp +If you are using a boot mechanism that does not pass network configuration +to the kernel using the kernel environment, you will also need to include +the following options: +.Pp +.D1 Cd "options BOOTP" +.D1 Cd "options BOOTP_NFSROOT" +.D1 Cd "options BOOTP_COMPAT" +.Pp +.Em Note : +the PXE environment does not require these options. +.Pp +The +.Nm +booting environment relies on memory-backed file systems to +support temporary local storage in the event that the root file system +is mounted read-only; as such, it is necessary to add the following +to the device section of the kernel configuration: +.Pp +.D1 Cd "device md" +.Pp +If you use the firewall, remember to default to +.Dq open , +or your kernel +will not be able to send/receive the +.Tn BOOTP +packets. +.El +.Sh SECURITY ISSUES +Be warned that using unencrypted +.Tn NFS +to mount root and user +partitions may expose information such as +encryption keys. +.Sh SEE ALSO +.Xr ethers 5 , +.Xr exports 5 , +.Xr make.conf 5 , +.Xr bootpd 8 , +.Xr mountd 8 , +.Xr nfsd 8 , +.Xr pxeboot 8 , +.Xr reboot 8 , +.Xr tftpd 8 +.Pp +.Pa ports/net/etherboot +.Sh BUGS +This manpage is probably incomplete. +.Pp +.Fx +sometimes requires to write onto +the root partition, so the startup scripts mount MFS +file systems on some locations (e.g.\& +.Pa /etc +and +.Pa /var ) , +while +trying to preserve the original content. +The process might not handle all cases. diff --git a/share/man/man8/intro.8 b/share/man/man8/intro.8 new file mode 100644 index 0000000..9640693 --- /dev/null +++ b/share/man/man8/intro.8 @@ -0,0 +1,95 @@ +.\" Copyright (c) 1983, 1991, 1993 +.\" The Regents of the University of California. 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. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``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 REGENTS OR CONTRIBUTORS 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. +.\" +.\" @(#)intro.8 8.2 (Berkeley) 12/11/93 +.\" $FreeBSD$ +.\" +.Dd October 22, 2006 +.Dt INTRO 8 +.Os +.Sh NAME +.Nm intro +.Nd "introduction to system maintenance procedures and commands" +.Sh DESCRIPTION +This section contains information related to system operation +and maintenance. +.Pp +It describes commands used to create new file systems +.Pq Xr newfs 8 , +verify the integrity of the file systems +.Pq Xr fsck 8 , +control disk usage +.Pq Xr edquota 8 , +maintain system backups +.Pq Xr dump 8 , +and recover files when disks die an untimely death +.Pq Xr restore 8 . +.\" The +.\" .Xr format 8 +.\" manual +.\" for the specific architecture the system is running on should be +.\" consulted when formatting disks and tapes. +Network related services like +.Xr inetd 8 +and +.Xr ftpd 8 +are also described. +.Pp +All commands set an exit status. +Its value may be tested +to see if the command completed normally. +Unless otherwise noted (rare), the value 0 signifies successful +completion of the command, while a value >0 indicates an error. +Some commands attempt to describe the nature of the failure by using +error codes defined in +.Xr sysexits 3 , +or set the status to arbitrary values >0 (typically 1), but many +such values are not described in the manual. +.Pp +A number of pages in this section describe general system +management topics. +.Pp +For example, the +.Xr boot 8 +manual page describes the system bootstrapping procedures, +and the +.Xr diskless 8 +manual page describes how to boot a system over a network. +The +.Xr crash 8 +manual page +should be consulted to understand how to interpret system +crash dumps. +.Sh HISTORY +The +.Nm +section manual page appeared in +.Bx 4.2 . diff --git a/share/man/man8/nanobsd.8 b/share/man/man8/nanobsd.8 new file mode 100644 index 0000000..0309c4e --- /dev/null +++ b/share/man/man8/nanobsd.8 @@ -0,0 +1,337 @@ +.\" Copyright (c) 2006 Daniel Gerzo <danger@FreeBSD.org> +.\" 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. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHORS AND CONTRIBUTORS ``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 AUTHORS OR CONTRIBUTORS 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. +.\" +.\" $FreeBSD$ +.\" +.Dd May 20, 2010 +.Dt NANOBSD 8 +.Os +.Sh NAME +.Nm nanobsd.sh +.Nd utility used to create a FreeBSD system image suitable for embedded +applications +.Sh SYNOPSIS +.Nm +.Op Fl bhknw +.Op Fl c Ar config-file +.Sh DESCRIPTION +The +.Nm +utility is a script which produces a minimal implementation of +.Fx +(called +.Nm NanoBSD ) , +which typically fits on a small media such as a Compact Flash card, +or other mass storage medium. +It can be used to build specialized install images, designed for easy +installation and maintenance. +.Pp +The following options are available: +.Bl -tag -width ".Fl c Ar config-file" -offset indent +.It Fl b +Skip the build stages (both for kernel and world). +.It Fl c Ar config-file +Specify the configuration file to use. +.It Fl h +Display usage information. +.It Fl k +Skip the +.Cm buildkernel +stage of the build. +.It Fl n +Do not cleanup before each build stage. +This suppresses the normal cleanup work done before the +.Cm buildworld +stage and adds -DNO_CLEAN to the make command line +used for each build stage (world and kernel). +.It Fl w +Skip the +.Cm buildworld +stage of the build. +.El +.Pp +The features of +.Nm NanoBSD +include: +.Pp +.Bl -bullet -offset indent -compact +.It +Ports and packages work as in +.Fx . +Every single application can be installed and used in a +.Nm NanoBSD +image, the same way as in +.Fx . +.It +No missing functionality. +If it is possible to do something with +.Fx , +it is possible to do the same thing with +.Nm NanoBSD , +unless the specific feature or features were explicitly removed from the +.Nm NanoBSD +image when it was created. +.It +Everything is read-only at run-time. +It is safe to pull the power-plug. +There is no necessity to run +.Xr fsck 8 +after a non-graceful shutdown of the system. +.It +Easy to build and customize. +Making use of just one shell script and one configuration file it is +possible to build reduced and customized images satisfying any arbitrary +set of requirements. +.El +.Ss Nm NanoBSD Ss Media Layout +The mass storage medium is divided into three parts by default (which +are normally mounted read-only): +.Pp +.Bl -bullet -offset indent -compact +.It +Two image partitions: +.Li code#1 +and +.Li code#2 . +.It +The configuration file partition, which can be mounted under the +.Pa /cfg +directory at run time. +.El +.Pp +The +.Pa /etc +and +.Pa /var +directories are +.Xr md 4 +(malloc backed) disks. +.Pp +The configuration file partition persists under the +.Pa /cfg +directory. +It contains files for +.Pa /etc +directory and is briefly mounted read-only right after the system boot, +therefore it is required to copy modified files from +.Pa /etc +back to the +.Pa /cfg +directory if changes are expected to persist after the system restarts. +.Sh BUILDING Nm NanoBSD +A +.Nm NanoBSD +image is built using a simple +.Nm +shell script, which can be +found in the +.Pa src/tools/tools/nanobsd +directory. +This script creates a bootable image, which can be copied on the storage +medium using the +.Xr dd 1 +utility. +.Pp +The necessary commands to build and install a +.Nm NanoBSD +image are: +.Bd -literal -offset indent +cd /usr/src/tools/tools/nanobsd +sh nanobsd.sh +cd /usr/obj/nanobsd.full +dd if=_.disk.full of=/dev/da0 bs=64k +.Ed +.Sh CUSTOMIZING Nm NanoBSD +This is probably the most important and most interesting feature of +.Nm NanoBSD . +This is also where you will be spending most of the time when developing with +.Nm NanoBSD . +.Pp +Customization is done in two ways: +.Pp +.Bl -bullet -offset indent -compact +.It +Configuration options. +.It +Custom functions. +.El +.Pp +With configuration settings, it is possible to configure options passed +to both the +.Cm buildworld +and +.Cm installworld +stages of the +.Nm NanoBSD +build process, as well as internal options passed to the main build +process of +.Nm NanoBSD . +Through these options it is possible to cut the system down, so it will +fit on as little as 64MB. +You can use the configuration options to trim down the system +even more, until it will consist of just the kernel and two or three +files in the userland. +.Pp +The configuration file consists of configuration options, which override +the default values. +The most important directives are: +.Bl -tag -width ".Va CONF_INSTALL" -offset indent +.It Va NANO_NAME +Build name (used to construct the working directory names). +.It Va NANO_SRC +Path to the source tree used to build the image. +.It Va NANO_KERNEL +Name of the kernel configuration file used to build the kernel. +.It Va NANO_ARCH +Machine processor architecture to build. Defaults to output of +.Cm uname -p . +.It Va NANO_BOOT0CFG +Controls the options passed to +.Xr boot0cfg 8 ; +these dictate +.Nm boot0 Ns 's +behaviour. +.It Va NANO_BOOTLOADER +The +.Nm boot0 +loader to use relative to the +.Va NANO_WORLDDIR +variable. +This defaults to +.Pa boot/boot0sio +and should be overridden to +.Pa boot/boot0 +to provide a VGA +console. +.It Va CONF_BUILD +Options passed to the +.Cm buildworld +stage of the build. +.It Va CONF_INSTALL +Options passed to the +.Cm installworld +stage of the build. +.It Va CONF_WORLD +Options passed to both the +.Cm buildworld +and +.Cm installworld +stages of the build. +.It Va FlashDevice +Defines the type of media to use. +Check the +.Pa FlashDevice.sub +file for more details. +.El +.Pp +For more configuration options, please check the +.Nm +script. +.Pp +To build +.Nm NanoBSD +image using the +.Pa nanobsd.conf +configuration file, use the following command: +.Bd -literal -offset indent +sh nanobsd.sh -c nanobsd.conf +.Ed +.Pp +It is possible to fine-tune +.Nm NanoBSD +using shell functions in the configuration file. +The following example illustrates the basic model of custom functions: +.Bd -literal -offset indent +cust_foo () ( + echo "bar=topless" > \\ + ${NANO_WORLDDIR}/etc/foo +) +customize_cmd cust_foo +.Ed +.Pp +There are a few pre-defined customization functions ready for use: +.Bl -tag -width ".Cm cust_allow_ssh_root" -offset indent +.It Cm cust_comconsole +Disables +.Xr getty 8 +on the virtual +.Xr syscons 4 +terminals +.Pq Pa /dev/ttyv* +and enables the use of the first serial port as the system +console. +.It Cm cust_allow_ssh_root +Allow root to log in via +.Xr sshd 8 . +.It Cm cust_install_files +Installs files from the +.Pa nanobsd/Files +directory, which contains some useful scripts for system administration. +.El +.Sh FILES +.Bl -tag -width ".Pa src/tools/tools/nanobsd" -compact +.It Pa src/tools/tools/nanobsd +Base directory of the +.Nm NanoBSD +build script. +.El +.Sh EXAMPLES +Making persistent changes to +.Pa /etc/resolv.conf : +.Bd -literal -offset indent +vi /etc/resolv.conf +\&... +mount /cfg +cp /etc/resolv.conf /cfg +umount /cfg +.Ed +.Pp +A more useful example of a customization function is the following, +which changes the default size of the +.Pa /etc +directory from 5MB to 30MB: +.Bd -literal -offset indent +cust_etc_size () ( + cd ${NANO_WORLDDIR}/conf + echo 30000 > default/etc/md_size +) +customize_cmd cust_etc_size +.Ed +.Sh SEE ALSO +.Xr make.conf 5 , +.Xr boot 8 , +.Xr boot0cfg 8 , +.Xr picobsd 8 +.Sh HISTORY +The +.Nm +utility first appeared in +.Fx 6.0 . +.Sh AUTHORS +.An -nosplit +.Nm NanoBSD +was developed by +.An Poul-Henning Kamp Aq phk@FreeBSD.org . +This manual page was written by +.An Daniel Gerzo Aq danger@FreeBSD.org . diff --git a/share/man/man8/picobsd.8 b/share/man/man8/picobsd.8 new file mode 100644 index 0000000..c6c6c94 --- /dev/null +++ b/share/man/man8/picobsd.8 @@ -0,0 +1,663 @@ +.\" -*- nroff-fill -*- +.\" $FreeBSD$ +.Dd June 25, 2009 +.Dt PICOBSD 8 +.Os +.Sh NAME +.Nm picobsd +.Nd building small FreeBSD disk images +.Sh SYNOPSIS +.Nm +.Op Ar options +.Op Ar config-name Op Ar site-name +.Sh DESCRIPTION +The +.Nm +utility is a script which produces a minimal implementation of +.Fx +(historically called +.Nm PicoBSD ) +which typically fits on a small media such as a floppy disk, +or can be downloaded as a +single image file from some media such as CDROM, flash memory, or through +.Xr etherboot . +.Pp +The +.Nm +utility was originally created to build simple standalone systems +such as firewalls or bridges, but because of the ability to +cross-build images with different source trees than the one +in the server, it can be extremely useful to developers to +test their code without having to reinstall the system. +.Pp +The boot media (historically a floppy disk, but also small +CDROM or USB keys) contains a boot loader and a +compressed kernel which includes a memory file system. +Depending on the media, it might also contain a number of +additional files, which can be updated at run time, and are +used to override/update those in the memory file system. +.Pp +The system loads the kernel in the normal way, uncompresses +the memory file system and mounts it as root. +It then updates the memory +file system with files from the boot media (if present), +and executes a specialized version of +.Pa /etc/rc . +The boot media (floppy, etc.) is +required for loading only, and typically used read-only. +After the boot phase, the system runs entirely from RAM. +.Pp +The following options are available (but also check the +.Nm +script for more details). +The most important options for common operations are +.Fl src , +.Fl init , +.Fl n and +.Fl v. +.Pp +.Bl -tag -width indent +.\" +.It Fl -all_in_mfs +Put the entire contents of the file system in the +memory file system image which is contained in the +kernel. +This is the default behaviour, and is +extremely useful as the kernel itself can be loaded, +using +.Xr etherboot +or +.Xr pxeboot 8 , +.\" +.It Fl c , Fl clean +Clean the product of previous builds. +.\" +.It Fl -cfg Ar file +Specify a file that contains additional config commands. +.\" +.It Fl -floppy_size Ar size +Set the size of the disk image. +Typical values for a floppy disk are 1440 or 2880, +but other values can be used for other media (flash memories, +CDROM, network booted kernels). +Note that this option is overridden by the content of the +config files (config in the image tree, or the one +specified with +.Fl Fl cfg ) +.\" +.It Fl -init +When used together with the +.Fl -src +option, this initializes the +.Ao Ar SRC_PATH Ac Ns Pa /../usr +subtree as necessary to subsequently build +.Nm +images. +.\" +.It Fl -iso +Generate an ISO image, picobsd.iso, in addition to the disk image picobsd.bin +.\" +.It Fl -modules +Also build kernel modules. +These are not stored on the +.Nm +image but are left available in the build directory. +.\" +.It Fl n +Make the script non-interactive, skipping the initial menu +and proceeding with the build process without requiring user input. +.\" +.It Fl -no_all_in_mfs +Leaves files contained in the +.Pa floppy.tree +on the +.Nm +image, so they can be loaded separately +from the kernel (and updated individually to +customize the image). +.\" +.It Fl -no_loader +Omit /boot/loader, just rely on boot2 to load the kernel. +This saves some space but may have problems with kernels > 4MB. +.\" +.It Fl -objdir Ar directory +Specify a directory with the result of a previous buildworld. +This saves the need for an +.Fl Fl init +call before creating an image. +.\" +.It Fl -src Ar SRC_PATH +Use the source tree at +.Ar SRC_PATH +instead the one at +.Pa /usr/src . +This can be useful for cross-building +.Nm +images. +When using this option, you must also create and initialize the subtree at +.Ao Ar SRC_PATH Ac Ns Pa /../usr +with the correct header files, libraries, and tools (such as the +.Xr config 8 +program) that are necessary for the cross-build (see the +.Fl -init +option). +The source files are unmodified by the +.Nm +script. +However the source tree is not completely read-only, +because +.Xr config 8 +expects the kernel configuration file to be in one of +its subdirectories, and also the process of initializing the +.Pa usr +subtree touches some parts of the source tree (this is a bug +in the release build scripts which might go away with time). +.\" +.It Fl v +Make the script verbose, showing +commands to be executed and waiting for user +input before executing each of them. +Useful for debugging. +as a fully functional system. +.El +.Sh ENVIRONMENT +As a result of extreme size limitations, the +.Nm +environment differs from the normal +.Fx +in a number of ways: +.Bl -bullet +.It +There are no dynamic libraries, and there is no directory +.Pa /usr/lib . +As a result, only static executables may be executed. +.It +In order to reduce the size of the executables, all executables on a specific +floppy are joined together as a single executable built with +.Xr crunchgen 1 . +.It +Some programs are supplied in minimalistic versions, specifically +.Nm ns , +a cut-down version of +.Xr netstat 1 , +and +.Nm vm , +a cut-down version of +.Xr vmstat 8 . +.El +.Sh BUILDING PicoBSD +The +.Nm +sources reside in the hierarchy +.Pa /usr/src/release/picobsd . +In the following discussion, all relative path names are relative to this +directory. +.Pp +The supported build script is +.Pa /usr/src/release/picobsd/build/picobsd +which can be run from anywhere, and relies on the +.Xr sysutils/makefs +port to build a filesystem without requiring +.Xr mdconfig +or root privileges to mount a filesystem. +When run in interactive mode (the default without the +.Fl n +option), the script will let you configure the various parameters +used to build the PicoBSD image. +An image is configured +using the files and directories described below. +The base system contains a template, called +.Pa bridge +for historical reasons, +that can be used as a base for building various kinds +of network appliances. +.Pp +You can define your own PicoBSD configuration, by creating a directory +with a name of your choice (e.g.\& +.Pa FOO ) +which contains +some of the following files and directories. +For more +information on how to construct these files, look at one +of the standard +.Nm +configurations as a reference. +.Bl -tag -width indent +.It Pa PICOBSD +The kernel configuration file (required). +This is a mostly standard +kernel configuration file, possibly stripped down by removing +unnecessary drivers and options to reduce the kernel's size. +.Pp +To be recognised as a +.Nm +kernel config file, the file must also contain the line +beginning with +.Dq Li #PicoBSD +below, and a matching +.Dv MD_ROOT_SIZE +option: +.Bd -literal -offset indent +#marker def_sz init MFS_inodes floppy_inodes +#PicoBSD 4200 init 8192 32768 +options MD_ROOT_SIZE=4200 # same as def_sz +.Ed +.Pp +This informs the script of the size of the memory file system and +provides a few other details on how to build the image. +.It Pa crunch.conf +.Xr crunchgen 1 +configuration (required). +It contains the list of directories containing program sources, +the list of binaries to be built, and the list of libraries that +these programs use. +See the +.Xr crunchgen 1 +manpage for the exact details on the syntax of this file. +.Pp +The following issues are particularly important when dealing +with +.Nm +configurations: +.Bl -bullet +.It +We can pass build options to those makefiles which understand +that, in order to reduce the size of the programs. +This is achieved with a line of the form +.Pp +.Dl "buildopts -DNO_PAM -DRELEASE_CRUNCH ..." +.It +When providing the list of directories where source files are, it +is convenient to list the following entry first: +.Pp +.Dl "srcdirs /usr/src/release/picobsd/tinyware" +.Pp +so that +.Nm Ns -specific +versions of the programs will be found there. +.It +The string +.Dq Li @__CWD__@ +is replaced with the full pathname of the directory where the +.Nm +configuration resides (i.e., the one where we find +.Pa PICOBSD , crunch.conf , +and so on). +This can be useful to refer source code that resides within a +configuration, e.g.\& +.Pp +.Dl "srcdirs @__CWD__@/src" +.El +.It Pa config +Shell variables, sourced by the +.Nm +script (optional). +The most important variables here are: +.Bl -tag -width ".Va MY_DEVS" +.It Va MY_DEVS +(Not used in +.Fx 5.0 +where we have +.Xr devfs 5 ) . +Should be set to the list of devices to be created in the +.Pa /dev +directory of the image (it is really the argument passed to +.Xr MAKEDEV 8 , +so refer to that manpage for the names). +.It Va fd_size +Size (in kilobytes) of the +.Nm +image. +By default, +.Va fd_size +is set to 1440 +which produces an image suitable for a standard floppy. +.Pp +If you plan to store the image on a CDROM (e.g.\& using +the +.Dq "El Torito" +floppy emulation), you can set +.Va fd_size +equal to 2880. +If you are planning to dump the image onto a hard disk +(either in a partition or on the whole disk), you +are not restricted to one of the standard floppy sizes. +Using a large image size per se does not waste RAM at runtime, +because only the files that are actually loaded from the image +contribute to the memory usage. +.It Va import_files +Contains a list of files to be imported in the floppy tree. +Absolute names refer to the standard file system, relative +names refer to the root of the source tree being used +(i.e.\& +.Va SRC_PATH/.. ) . +You can normally use this option if you want to import +files such as shared libraries, or databases, without +having to replicate them first in your configuration +under the +.Pa floppy.tree/ +directory. +.El +.It Pa floppy.tree.exclude +List of files from the standard floppy tree which +we do not want to be copied (optional). +.It Pa floppy.tree/ +Local additions to the standard floppy tree (optional). +The content of this subtree will be copied as-is into the +floppy image. +.It Pa floppy.tree. Ns Aq Ar site-name +Same as above, but site-specific (optional). +.El +.Pp +More information on the build process can be found in the +comments in the +.Nm +script. +.Sh USING ALTERNATE SOURCE TREES +The build script can be instructed to use an alternate source tree +using the +.Fl -src Ar SRC_PATH +option. +The tree that you specify must contain full sources for the kernel +and for all programs that you want to include in your image. +As an example, to cross-build the +.Pa bridge +floppy +using RELENG_4 sources, you can do the following: +.Bd -literal -offset indent +cd <some_empty_directory> +mkdir FOO +(cd FOO; cvs -d<my_repository> co -rRELENG_4 src) +picobsd --src FOO/src --init # this is needed only once +picobsd --src FOO/src -n -v bridge +.Ed +.Pp +If the build is successful, the directory +.Pa build_dir-bridge/ +will contain a +.Pa kernel +that can be downloaded with +.Xr etherboot , +a floppy image called +.Pa picobsd.bin , +plus the products of the compilation in other directories. +If you want to modify the source tree in +.Pa FOO/src , +a new image can be produced by simply running +.Pp +.Dl "picobsd --src FOO/src -n -v bridge" +.Pp +whereas if the change affects include files or libraries +you first need to update them, e.g.\& by re-running +.Pp +.Dl "picobsd --src FOO/src --init # this is needed only once" +.Pp +as you would normally do for any change of this kind. +.Sh INSTALLING PicoBSD +.Ss Floppy Install +Historically, +.Nm +is run from a floppy disk, where it can be installed with a simple +.Pp +.Dl "dd if=picobsd.bin of=/dev/rfd0" +.Pp +and the floppy is ready to boot. +.Ss Hard Disk Install +The same process can be used to store the image on a hard disk +(entire volume or one of the slices): +.Bd -literal -offset indent +dd if=picobsd.bin of=/dev/ad2 +dd if=picobsd.bin of=/dev/ad2s3 +dd if=picobsd.bin of=/dev/ad2 oseek=NN +.Ed +.Pp +The first form will install the image on the entire disk, and it +should work in the same way as for a floppy. +.Pp +The second form will install the image +on slice number 3 (which should be large enough to store the +contents of the image). +However, the process will only have success if the +partition does not contain a valid disklabel, otherwise the kernel will +likely prevent overwriting the label. +In this case you can use the +third form, replacing +.Ar NN +with the actual start of the partition +(which you can determine using +.Xr fdisk 8 ) . +Note that after saving the image to the slice, it will not yet be +recognised. +You have to use the +.Xr disklabel 8 +command to properly initialize the label (do not ask why!). +One way to do this is +.Bd -literal -offset indent +disklabel -w ad0s2 auto +disklabel -e ad0s2 +.Ed +.Pp +and from the editor enter a line corresponding to the actual partition, e.g.\& +if the image has 2.88MB (5760 sectors) you need to enter the following +line for the partition: +.Pp +.Dl "a: 5760 0 4.2BSD 512 4096" +.Pp +At this point the partition is bootable. +Note that the image size can be smaller than the slice size +(indicated as partition +.Dq Li c: ) . +.Ss CDROM Install +.Nm +can produce an ISO image named picobsd.iso, +which does not use +.Dq "El Torito" +emulation, so it has no size restrictions. +Installing means just burning a media with the file. +.Ss Booting From The Network +Yet another way to use +.Nm +is to boot the image off the network. +For this purpose you should use the uncompressed kernel which is +available as a byproduct of the compilation. +Refer to the documentation +for network booting for more details, the +.Nm +kernel is bootable as a standard +.Fx +kernel. +.Sh BOOTING PicoBSD +To boot +.Nm , +insert the floppy and reset the machine. +The boot procedure is similar to the +standard +.Fx +boot. +Booting from a floppy is normally rather slow (in the order of 1-2 +minutes), things are much faster if you store your image on +a hard disk, Compact Flash, or CDROM. +.Pp +You can also use +.Xr etherboot +to load the preloaded, uncompressed kernel image +which is a byproduct of the +.Nm +build. +In this case +the load time is a matter of a few seconds, even on a 10Mbit/s +ethernet. +.Pp +After booting, +.Nm +loads the root file system from the memory file system, starts +.Pa /sbin/init , +and passes control to a first startup script, +.Pa /etc/rc . +The latter populates the +.Pa /etc +and +.Pa /root +directories with the default files, then tries to identify the boot +device (floppy, hard disk partition) and possibly override the contents +of the root file system with files read from the boot device. +This allows you to store local configuration on the same media. +After this phase the boot device is no longer used, unless the +user specifically does it. +.Pp +After this, control is transferred to a second script, +.Pa /etc/rc1 +(which can be overridden from the boot device). +This script tries to associate a hostname to the system by using +the MAC address of the first ethernet interface as a key, and +.Pa /etc/hosts +as a lookup table. +Then control is passed to the main user configuration script, +.Pa /etc/rc.conf , +which is supposed to override the value of a number of configuration +variables which have been pre-set in +.Pa /etc/rc.conf.defaults . +You can use the +.Va hostname +variable to create different configurations from the same file. +After taking control back, +.Pa /etc/rc1 +completes the initializations, and as part of this +it configures network interfaces and optionally calls the +firewall configuration script, +.Pa /etc/rc.firewall , +where the user can store his own firewall configuration. +.Pp +Note that by default +.Nm +runs entirely from main memory, and has no swap space, unless you +explicitly request it. +The boot device is also not used anymore after +.Pa /etc/rc1 +takes control, again, unless you explicitly request it. +.Sh CONFIGURING a PicoBSD system +The operation of a +.Nm +system can be configured through a few files which are read at boot +time, very much like a standard +.Fx +system. +There are, however, some minor differences to reduce the +number of files to store and/or customize, thus saving space. +Among the files to configure we have the following: +.Bl -tag -width indent +.It Pa /etc/hosts +Traditionally, this file contains the IP-to-hostname mappings. +In addition to this, the +.Nm +version of this file also contains +a mapping between Ethernet (MAC) addresses and hostnames, as follows: +.Bd -literal -offset indent +#ethertable start of the ethernet->hostname mapping +# mac_address hostname +# 00:12:34:56:78:9a pinco +# 12:34:56:* pallino +# * this-matches-all +.Ed +.Pp +where the line containing +.Dq Li #ethertable +marks the start of the table. +.Pp +If the MAC address is not found, the script will prompt you to +enter a hostname and IP address for the system, and this +information will be stored in the +.Pa /etc/hosts +file (in memory) so you can simply store them on disk later. +.Pp +Note that you can use wildcards in the address part, so a line +like the last one in the example will match any MAC address and +avoid the request. +.It Pa /etc/rc.conf +This file contains a number of variables which control the +operation of the system, such as interface configuration, +router setup, network service startup, etc. +For the exact list and meaning of these variables see +.Pa /etc/rc.conf.defaults . +.Pp +It is worth mentioning that some of the variables let you +overwrite the contents of some files in +.Pa /etc . +This option is available at the moment for +.Pa /etc/host.conf +and +.Pa /etc/resolv.conf , +whose contents are generally very short and suitable for this +type of updating. +In case you use these variables, remember to use newlines +as appropriate, e.g.\& +.Bd -literal -offset indent +host_conf="# this goes into /etc/host.conf +hosts +bind" +.Ed +.Pp +Although not mandatory, in this file you should only set the +variables indicated in +.Pa /etc/rc.conf.defaults , +and avoid starting services which depend on having the network running. +This can be done at a later time: if you set +.Va firewall_enable Ns = Ns Qq Li YES , +the +.Pa /etc/rc.firewall +script will be run after configuring the network interfaces, +so you can set up your firewall and safely start network services or enable +things such as routing and bridging. +.It Pa /etc/rc.firewall +This script can be used to configure the +.Xr ipfw 4 +firewall. +On entry, the +.Va fwcmd +variable is set to the pathname of the firewall command, +.Va firewall_type +contains the value set in +.Pa /etc/rc.conf , +and +.Va hostname +contains the name assigned to the host. +.El +.Pp +There is a small script called +.Nm update +which can be used to edit and/or save to disk a copy of the files +you have modified after booting. +The script takes one or more absolute pathnames, runs the +editor on the files passed as arguments, and then saves a +compressed copy of the files on the disk (mounting and +unmounting the latter around the operation). +.Pp +If invoked without arguments, +.Nm update +edits and saves +.Pa rc.conf , rc.firewall , +and +.Pa master.passwd . +.Pp +If one of the arguments is +.Pa /etc +(the directory name alone), +then the command saves to disk (without editing) +all the files in the directory for which a copy +already exists on disk (e.g.\& as a result of a previous update). +.Sh SEE ALSO +.Xr crunchgen 1 , +.Xr mdconfig 8 , +.Xr swapon 8 +.Sh AUTHORS +.An -nosplit +.An Andrzej Bialecki Aq abial@FreeBSD.org , +with subsequent work on the scripts by +.An Luigi Rizzo Aq luigi@iet.unipi.it +and others. +Man page and +.Pa Makefiles +created by +.An Greg Lehey Aq grog@lemis.com . +.Sh BUGS +Documentation is still incomplete. diff --git a/share/man/man8/rc.8 b/share/man/man8/rc.8 new file mode 100644 index 0000000..4f24a36 --- /dev/null +++ b/share/man/man8/rc.8 @@ -0,0 +1,542 @@ +.\" Copyright (c) 1980, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Portions of this manual page are Copyrighted by +.\" The NetBSD Foundation. +.\" +.\" 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. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``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 REGENTS OR CONTRIBUTORS 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. +.\" +.\" @(#)rc.8 8.2 (Berkeley) 12/11/93 +.\" $FreeBSD$ +.\" +.Dd November 17, 2009 +.Dt RC 8 +.Os +.Sh NAME +.Nm rc +.Nd command scripts for auto-reboot and daemon startup +.Sh SYNOPSIS +.Nm +.Nm rc.conf +.Nm rc.conf.local +.Nm rc.d/ +.Nm rc.firewall +.Nm rc.local +.Nm rc.shutdown +.Nm rc.subr +.Sh DESCRIPTION +The +.Nm +utility is the command script which controls the automatic boot process +after being called by +.Xr init 8 . +The +.Nm rc.local +script contains commands which are pertinent only +to a specific site. +Typically, the +.Pa /usr/local/etc/rc.d/ +mechanism is used instead of +.Nm rc.local +these days but if +you want to use +.Nm rc.local , +it is still supported. +In this case, it should source +.Pa /etc/rc.conf +and contain additional custom startup code for your system. +The best way to handle +.Nm rc.local , +however, is to separate it out into +.Nm rc.d/ +style scripts and place them under +.Pa /usr/local/etc/rc.d/ . +The +.Nm rc.conf +file contains the global system configuration information referenced +by the startup scripts, while +.Nm rc.conf.local +contains the local system configuration. +See +.Xr rc.conf 5 +for more information. +.Pp +The +.Nm rc.d/ +directories contain scripts which will be automatically +executed at boot time and shutdown time. +.Ss Operation of Nm +.Bl -enum +.It +If autobooting, set +.Va autoboot Ns = Ns Li yes +and enable a flag +.Pq Va rc_fast Ns = Ns Li yes , +which prevents the +.Nm rc.d/ +scripts from performing the check for already running processes +(thus speeding up the boot process). +This +.Va rc_fast Ns = Ns Li yes +speedup will not occur when +.Nm +is started up after exiting the single-user shell. +.It +Determine whether the system is booting diskless, +and if so run the +.Pa /etc/rc.initdiskless +script. +.It +Source +.Pa /etc/rc.subr +to load various +.Xr rc.subr 8 +shell functions to use. +.It +Load the configuration files. +.It +Determine if booting in a jail, +and add +.Dq Li nojail +to the list of KEYWORDS to skip in +.Xr rcorder 8 . +.It +Invoke +.Xr rcorder 8 +to order the files in +.Pa /etc/rc.d/ +that do not have a +.Dq Li nostart +KEYWORD (refer to +.Xr rcorder 8 Ns 's +.Fl s +flag). +.It +Call each script in turn using +.Fn run_rc_script +(from +.Xr rc.subr 8 ) , +which sets +.Va $1 +to +.Dq Li start , +and sources the script in a subshell. +If the script has a +.Pa .sh +suffix then it is sourced directly into the current shell. +Stop processing when the script that is the value of the +.Va $early_late_divider +has been run. +.It +Re-run +.Xr rcorder 8 , +this time including the scripts in the +.Va $local_startup +directories. +Ignore everything up to the +.Va $early_late_divider , +then start executing the scripts as described above. +.El +.Ss Operation of Nm rc.shutdown +.Bl -enum +.It +Source +.Pa /etc/rc.subr +to load various +.Xr rc.subr 8 +shell functions to use. +.It +Load the configuration files. +.It +Invoke +.Xr rcorder 8 +to order the files in +.Pa /etc/rc.d/ +and the +.Va $local_startup +directories +that have a +.Dq Li shutdown +KEYWORD (refer to +.Xr rcorder 8 Ns 's +.Fl k +flag), +reverse that order, and assign the result to a variable. +.It +Call each script in turn using +.Fn run_rc_script +(from +.Xr rc.subr 8 ) , +which sets +.Va $1 +to +.Dq Li stop , +and sources the script in a subshell. +If the script has a +.Pa .sh +suffix then it is sourced directly into the current shell. +.El +.Ss Contents of Nm rc.d/ +.Nm rc.d/ +is located in +.Pa /etc/rc.d/ . +The following file naming conventions are currently used in +.Nm rc.d/ : +.Bl -tag -width ".Pa ALLUPPERCASE" -offset indent +.It Pa ALLUPPERCASE +Scripts that are +.Dq placeholders +to ensure that certain operations are performed before others. +In order of startup, these are: +.Bl -tag -width ".Pa NETWORKING" +.It Pa NETWORKING +Ensure basic network services are running, including general +network configuration. +.It Pa SERVERS +Ensure basic services +exist for services that start early (such as +.Pa named ) , +because they are required by +.Pa DAEMON +below. +.It Pa DAEMON +Check-point before all general purpose daemons such as +.Pa lpd +and +.Pa ntpd . +.It Pa LOGIN +Check-point before user login services +.Pa ( inetd +and +.Pa sshd ) , +as well as services which might run commands as users +.Pa ( cron +and +.Pa sendmail ) . +.El +.It Pa foo.sh +Scripts that are to be sourced into the current shell rather than a subshell +have a +.Pa .sh +suffix. +Extreme care must be taken in using this, as the startup sequence will +terminate if the script does. +.It Pa bar +Scripts that are sourced in a subshell. +The boot does not stop if such a script terminates with a non-zero status, +but a script can stop the boot if necessary by invoking the +.Fn stop_boot +function (from +.Xr rc.subr 8 ). +.El +.Pp +Each script should contain +.Xr rcorder 8 +keywords, especially an appropriate +.Dq Li PROVIDE +entry, and if necessary +.Dq Li REQUIRE +and +.Dq Li BEFORE +keywords. +.Pp +Each script is expected to support at least the following arguments, which +are automatically supported if it uses the +.Fn run_rc_command +function: +.Bl -tag -width ".Cm restart" -offset indent +.It Cm start +Start the service. +This should check that the service is to be started as specified by +.Xr rc.conf 5 . +Also checks if the service is already running and refuses to start if +it is. +This latter check is not performed by standard +.Fx +scripts if the system is starting directly to multi-user mode, to +speed up the boot process. +If +.Cm forcestart +is given, ignore the +.Xr rc.conf 5 +check and start anyway. +.It Cm stop +If the service is to be started as specified by +.Xr rc.conf 5 , +stop the service. +This should check that the service is running and complain if it is not. +If +.Cm forcestop +is given, ignore the +.Xr rc.conf 5 +check and attempt to stop. +.It Cm restart +Perform a +.Cm stop +then a +.Cm start . +.It Cm status +If the script starts a process (rather than performing a one-off +operation), show the status of the process. +Otherwise it is not necessary to support this argument. +Defaults to displaying the process ID of the program (if running). +.It Cm poll +If the script starts a process (rather than performing a one-off +operation), wait for the command to exit. +Otherwise it is not necessary to support this argument. +.It Cm rcvar +Display which +.Xr rc.conf 5 +variables are used to control the startup of the service (if any). +.El +.Pp +If a script must implement additional commands it can list them in +the +.Va extra_commands +variable, and define their actions in a variable constructed from +the command name (see the +.Sx EXAMPLES +section). +.Pp +The following key points apply to old-style scripts in +.Pa /usr/local/etc/rc.d/ : +.Pp +.Bl -bullet +.It +Scripts are only executed if their +.Xr basename 1 +matches the shell globbing pattern +.Pa *.sh , +and they are executable. +Any other files or directories present within the directory are silently +ignored. +.It +When a script is executed at boot time, it is passed the string +.Dq Li start +as its first and only argument. +At shutdown time, it is passed the string +.Dq Li stop +as its first and only argument. +All +.Nm rc.d/ +scripts are expected to handle these arguments appropriately. +If no action needs to be taken at a given time +(either boot time or shutdown time), +the script should exit successfully and without producing an error message. +.It +The scripts within each directory are executed in lexicographical order. +If a specific order is required, +numbers may be used as a prefix to the existing filenames, +so for example +.Pa 100.foo +would be executed before +.Pa 200.bar ; +without the numeric prefixes the opposite would be true. +.It +The output from each script is traditionally a space character, +followed by the name of the software package being started or shut down, +.Em without +a trailing newline character (see the +.Sx EXAMPLES +section). +.El +.Sh SCRIPTS OF INTEREST +When an automatic reboot is in progress, +.Nm +is invoked with the argument +.Cm autoboot . +One of the scripts run from +.Pa /etc/rc.d/ +is +.Pa /etc/rc.d/fsck . +This script runs +.Xr fsck 8 +with option +.Fl p +and +.Fl F +to +.Dq preen +all the disks of minor inconsistencies resulting +from the last system shutdown. +If this fails, then checks/repairs of serious inconsistencies +caused by hardware or software failure will be performed +in the background at the end of the booting process. +If +.Cm autoboot +is not set, when going from single-user to multi-user mode for example, +the script does not do anything. +.Pp +The +.Pa /etc/rc.d/local +script can execute scripts from multiple +.Nm rc.d/ +directories. +The default location includes +.Pa /usr/local/etc/rc.d/ , +but these may be overridden with the +.Va local_startup +.Xr rc.conf 5 +variable. +.Pp +The +.Pa /etc/rc.d/serial +script is used to set any special configurations for serial devices. +.Pp +The +.Nm rc.firewall +script is used to configure rules for the kernel based firewall +service. +It has several possible options: +.Pp +.Bl -tag -width ".Ar filename" -compact -offset indent +.It Cm open +will allow anyone in +.It Cm client +will try to protect just this machine +.It Cm simple +will try to protect a whole network +.It Cm closed +totally disables IP services except via +.Pa lo0 +interface +.It Cm UNKNOWN +disables the loading of firewall rules +.It Ar filename +will load the rules in the given filename (full path required). +.El +.Pp +The +.Pa /etc/rc.d/atm* +scripts are used to configure ATM network interfaces. +The interfaces are configured in three passes. +The first pass performs the initial interface configuration. +The second pass completes the interface configuration and defines PVCs and +permanent ATMARP entries. +The third pass starts any ATM daemons. +.Pp +Most daemons, including network related daemons, have their own script in +.Pa /etc/rc.d/ , +which can be used to start, stop, and check the status of the service. +.Pp +Any architecture specific scripts, such as +.Pa /etc/rc.d/apm +for example, specifically check that they are on that architecture +before starting the daemon. +.Pp +Following tradition, all startup files reside in +.Pa /etc . +.Sh FILES +.Bl -tag -compact +.It Pa /etc/rc +.It Pa /etc/rc.conf +.It Pa /etc/rc.conf.local +.It Pa /etc/rc.d/ +.It Pa /etc/rc.firewall +.It Pa /etc/rc.local +.It Pa /etc/rc.shutdown +.It Pa /etc/rc.subr +.It Pa /var/run/dmesg.boot +.Xr dmesg 8 +results soon after the +.Nm +process begins. +Useful when +.Xr dmesg 8 +buffer in the kernel no longer has this information. +.El +.Sh EXAMPLES +The following is a minimal +.Nm rc.d/ +style script. +Most scripts require little more than the following. +.Bd -literal -offset indent +#!/bin/sh +# + +# PROVIDE: foo +# REQUIRE: bar_service_required_to_precede_foo + +\&. /etc/rc.subr + +name="foo" +rcvar=`set_rcvar` +command="/usr/local/bin/foo" + +load_rc_config $name +run_rc_command "$1" +.Ed +.Pp +Certain scripts may want to provide enhanced functionality. +The user may access this functionality through additional commands. +The script may list and define as many commands at it needs. +.Bd -literal -offset indent +#!/bin/sh +# + +# PROVIDE: foo +# REQUIRE: bar_service_required_to_precede_foo +# BEFORE: baz_service_requiring_foo_to_precede_it + +\&. /etc/rc.subr + +name="foo" +rcvar=`set_rcvar` +command="/usr/local/bin/foo" +extra_commands="nop hello" +hello_cmd="echo Hello World." +nop_cmd="do_nop" + +do_nop() +{ + echo "I do nothing." +} + +load_rc_config $name +run_rc_command "$1" +.Ed +.Pp +As all processes are killed by +.Xr init 8 +at shutdown, the explicit +.Xr kill 1 +is unnecessary, but is often included. +.Sh SEE ALSO +.Xr kill 1 , +.Xr rc.conf 5 , +.Xr init 8 , +.Xr rcorder 8 , +.Xr rc.subr 8 , +.Xr reboot 8 , +.Xr savecore 8 +.Sh HISTORY +The +.Nm +utility appeared in +.Bx 4.0 . diff --git a/share/man/man8/rc.sendmail.8 b/share/man/man8/rc.sendmail.8 new file mode 100644 index 0000000..7b05ced --- /dev/null +++ b/share/man/man8/rc.sendmail.8 @@ -0,0 +1,263 @@ +.\" Copyright (c) 1995 +.\" Jordan K. Hubbard +.\" Copyright (c) 2002 The FreeBSD Project +.\" 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. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``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 OR CONTRIBUTORS 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. +.\" +.\" $FreeBSD$ +.\" +.Dd March 30, 2002 +.Dt RC.SENDMAIL 8 +.Os +.Sh NAME +.Nm rc.sendmail +.Nd +.Xr sendmail 8 +startup script +.Sh DESCRIPTION +The +.Nm +script is used by +.Pa /etc/rc +at boot time to start +.Xr sendmail 8 . +It is meant to be +.Xr sendmail 8 +specific and not a generic script for all MTAs. +It is only called by +.Pa /etc/rc +if the +.Xr rc.conf 5 +.Va mta_start_script +variable is set to +.Pa /etc/rc.sendmail . +.Pp +The +.Nm +script can take an optional argument specifying the action to +perform. +The available actions are: +.Bl -tag -width ".Cm restart-mspq" +.It Cm start +Starts both the MTA and the MSP queue runner. +.It Cm stop +Stops both the MTA and the MSP queue runner. +.It Cm restart +Restarts both the MTA and the MSP queue runner. +.It Cm start-mta +Starts just the MTA. +.It Cm stop-mta +Stops just the MTA. +.It Cm restart-mta +Restarts just the MTA. +.It Cm start-mspq +Starts just the MSP queue runner. +.It Cm stop-mspq +Stops just the MSP queue runner. +.It Cm restart-mspq +Restarts just the MSP queue runner. +.El +.Pp +If no action is specified, +.Cm start +is assumed. +.Pp +The +.Nm +script is also used by +.Pa /etc/mail/Makefile +to enable the +.Pa Makefile Ns 's +.Cm start , stop , +and +.Cm restart +targets. +.Sh RC.CONF VARIABLES +The following variables affect the behavior of +.Nm . +They are defined in +.Pa /etc/defaults/rc.conf +and can be changed in +.Pa /etc/rc.conf . +.Bl -tag -width indent +.It Va sendmail_enable +.Pq Vt str +If set to +.Dq Li YES , +run the +.Xr sendmail 8 +daemon at system boot time. +If set to +.Dq Li NO , +do not run a +.Xr sendmail 8 +daemon to listen for incoming network mail. +This does not preclude a +.Xr sendmail 8 +daemon listening on the SMTP port of the loopback interface. +The +.Dq Li NONE +option is deprecated and should not be used. +It will be removed in a future release. +.It Va sendmail_flags +.Pq Vt str +If +.Va sendmail_enable +is set to +.Dq Li YES , +these are the flags to pass to the +.Xr sendmail 8 +daemon. +.It Va sendmail_submit_enable +.Pq Vt bool +If set to +.Dq Li YES +and +.Va sendmail_enable +is set to +.Dq Li NO , +run +.Xr sendmail 8 +using +.Va sendmail_submit_flags +instead of +.Va sendmail_flags . +This is intended to allow local mail submission via +a localhost-only listening SMTP service required for running +.Xr sendmail 8 +as a non-set-user-ID binary. +Note that this does not work inside +.Xr jail 2 +systems, as jails do not allow binding to just the localhost interface. +.It Va sendmail_submit_flags +.Pq Vt str +If +.Va sendmail_enable +is set to +.Dq Li NO +and +.Va sendmail_submit_enable +is set to +.Dq Li YES , +these are the flags to pass to the +.Xr sendmail 8 +daemon. +.It Va sendmail_outbound_enable +.Pq Vt bool +If set to +.Dq Li YES +and both +.Va sendmail_enable +and +.Va sendmail_submit_enable +are set to +.Dq Li NO , +run +.Xr sendmail 8 +using +.Va sendmail_outbound_flags +instead of +.Va sendmail_flags . +This is intended to allow local mail queue management +for systems that do not offer a listening SMTP service. +.It Va sendmail_outbound_flags +.Pq Vt str +If both +.Va sendmail_enable +and +.Va sendmail_submit_enable +are set to +.Dq Li NO +and +.Va sendmail_outbound_enable +is set to +.Dq Li YES , +these are the flags to pass to the +.Xr sendmail 8 +daemon. +.It Va sendmail_msp_queue_enable +.Pq Vt bool +If set to +.Dq Li YES , +start a client (MSP) queue runner +.Xr sendmail 8 +daemon at system boot time. +As of sendmail 8.12, a separate queue is used for command line +submissions. +The client queue runner ensures that nothing is +left behind in the submission queue. +.It Va sendmail_msp_queue_flags +.Pq Vt str +If +.Va sendmail_msp_queue_enable +is set to +.Dq Li YES , +these are the flags to pass to the +.Xr sendmail 8 +daemon. +.El +.Pp +These variables are used to determine how the +.Xr sendmail 8 +daemons are started: +.Pp +.Bd -literal -offset indent +# MTA +if (${sendmail_enable} == NONE) + # Do nothing +else if (${sendmail_enable} == YES) + start sendmail with ${sendmail_flags} +else if (${sendmail_submit_enable} == YES) + start sendmail with ${sendmail_submit_flags} +else if (${sendmail_outbound_enable} == YES) + start sendmail with ${sendmail_outbound_flags} +endif + +# MSP Queue Runner +if (${sendmail_enable} != NONE && + [ -r /etc/mail/submit.cf] && + ${sendmail_msp_queue_enable} == YES) + start sendmail with ${sendmail_msp_queue_flags} +endif +.Ed +.Pp +To completely prevent any +.Xr sendmail 8 +daemons from starting, you must +set the following variables in +.Pa /etc/rc.conf : +.Bd -literal -offset indent +sendmail_enable="NO" +sendmail_submit_enable="NO" +sendmail_outbound_enable="NO" +sendmail_msp_queue_enable="NO" +.Ed +.Sh SEE ALSO +.Xr rc.conf 5 , +.Xr rc 8 , +.Xr sendmail 8 +.Sh HISTORY +The +.Nm +file appeared in +.Fx 4.6 . diff --git a/share/man/man8/rc.subr.8 b/share/man/man8/rc.subr.8 new file mode 100644 index 0000000..9f6c7fa --- /dev/null +++ b/share/man/man8/rc.subr.8 @@ -0,0 +1,890 @@ +.\" $NetBSD: rc.subr.8,v 1.12 2004/01/06 00:52:24 lukem Exp $ +.\" +.\" Copyright (c) 2002-2004 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Luke Mewburn. +.\" +.\" 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. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``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 FOUNDATION OR CONTRIBUTORS +.\" 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. +.\" +.\" $FreeBSD$ +.\" +.Dd May 18, 2007 +.Dt RC.SUBR 8 +.Os +.Sh NAME +.Nm rc.subr +.Nd functions used by system shell scripts +.Sh SYNOPSIS +.Bl -item -compact +.It +.Ic .\& Pa /etc/rc.subr +.Pp +.It +.Ic backup_file Ar action Ar file Ar current Ar backup +.It +.Ic checkyesno Ar var +.It +.Ic check_pidfile Ar pidfile Ar procname Op Ar interpreter +.It +.Ic check_process Ar procname Op Ar interpreter +.It +.Ic debug Ar message +.It +.Ic err Ar exitval Ar message +.It +.Ic force_depend Ar name +.It +.Ic info Ar message +.It +.Ic load_kld Oo Fl e Ar regex Oc Oo Fl m Ar module Oc Ar file +.It +.Ic load_rc_config Ar name +.It +.Ic load_rc_config_var Ar name Ar var +.It +.Ic mount_critical_filesystems Ar type +.It +.Ic rc_usage Ar command ... +.It +.Ic reverse_list Ar item ... +.It +.Ic run_rc_command Ar argument +.It +.Ic run_rc_script Ar file Ar argument +.It +.Ic set_rcvar Op Ar base +.It +.Ic wait_for_pids Op Ar pid ... +.It +.Ic warn Ar message +.El +.Sh DESCRIPTION +The +.Nm +script +contains commonly used shell script functions and variable +definitions which are used by various scripts such as +.Xr rc 8 . +Scripts required by ports in +.Pa /usr/local/etc/rc.d +will also eventually +be rewritten to make use of it. +.Pp +The +.Nm +functions were mostly imported from +.Nx . +.Pp +They are accessed by sourcing +.Pa /etc/rc.subr +into the current shell. +.Pp +The following shell functions are available: +.Bl -tag -width 4n +.It Ic backup_file Ar action file current backup +Make a backup copy of +.Ar file +into +.Ar current . +If the +.Xr rc.conf 5 +variable +.Va backup_uses_rcs +is +.Dq Li YES , +use +.Xr rcs 1 +to archive the previous version of +.Ar current , +otherwise save the previous version of +.Ar current +as +.Ar backup . +.Pp +The +.Ar action +argument +may be one of the following: +.Bl -tag -width ".Cm remove" +.It Cm add +.Ar file +is now being backed up by or possibly re-entered into this backup mechanism. +.Ar current +is created, and if necessary, the +.Xr rcs 1 +files are created as well. +.It Cm update +.Ar file +has changed and needs to be backed up. +If +.Ar current +exists, it is copied to +.Ar backup +or checked into +.Xr rcs 1 +(if the repository file is old), +and then +.Ar file +is copied to +.Ar current . +.It Cm remove +.Ar file +is no longer being tracked by this backup mechanism. +If +.Xr rcs 1 +is being used, an empty file is checked in and +.Ar current +is removed, +otherwise +.Ar current +is moved to +.Ar backup . +.El +.It Ic checkyesno Ar var +Return 0 if +.Ar var +is defined to +.Dq Li YES , +.Dq Li TRUE , +.Dq Li ON , +or +.Ql 1 . +Return 1 if +.Ar var +is defined to +.Dq Li NO , +.Dq Li FALSE , +.Dq Li OFF , +or +.Ql 0 . +Otherwise, warn that +.Ar var +is not set correctly. +The values are case insensitive. +.Sy Note : +.Ar var +should be a variable name, not its value; +.Ic checkyesno +will expand the variable by itself. +.It Ic check_pidfile Ar pidfile procname Op Ar interpreter +Parses the first word of the first line of +.Ar pidfile +for a PID, and ensures that the process with that PID +is running and its first argument matches +.Ar procname . +Prints the matching PID if successful, otherwise nothing. +If +.Ar interpreter +is provided, parse the first line of +.Ar procname , +ensure that the line is of the form: +.Pp +.Dl "#! interpreter [...]" +.Pp +and use +.Ar interpreter +with its optional arguments and +.Ar procname +appended as the process string to search for. +.It Ic check_process Ar procname Op Ar interpreter +Prints the PIDs of any processes that are running with a first +argument that matches +.Ar procname . +.Ar interpreter +is handled as per +.Ic check_pidfile . +.It Ic debug Ar message +Display a debugging message to +.Va stderr , +log it to the system log using +.Xr logger 1 , +and +return to the caller. +The error message consists of the script name +(from +.Va $0 ) , +followed by +.Dq Li ": DEBUG: " , +and then +.Ar message . +This function is intended to be used by developers +as an aid to debugging scripts. +It can be turned on or off +by the +.Xr rc.conf 5 +variable +.Va rc_debug . +.It Ic err Ar exitval message +Display an error message to +.Va stderr , +log it to the system log +using +.Xr logger 1 , +and +.Ic exit +with an exit value of +.Ar exitval . +The error message consists of the script name +(from +.Va $0 ) , +followed by +.Dq Li ": ERROR: " , +and then +.Ar message . +.It Ic force_depend Ar name +Output an advisory message and force the +.Ar name +service to start. +The +.Ar name +argument is the +.Xr basename 1 +component of the path to the script, usually +.Pa /etc/rc.d/name . +If the script fails for any reason it will output a warning +and return with a return value of 1. +If it was successful +it will return 0. +.It Ic info Ar message +Display an informational message to +.Va stdout , +and log it to the system log using +.Xr logger 1 . +The message consists of the script name +(from +.Va $0 ) , +followed by +.Dq Li ": INFO: " , +and then +.Ar message . +The display of this informational output can be +turned on or off by the +.Xr rc.conf 5 +variable +.Va rc_info . +.It Ic load_kld Oo Fl e Ar regex Oc Oo Fl m Ar module Oc Ar file +Load +.Ar file +as a kernel module unless it is already loaded. +For the purpose of checking the module status, +either the exact module name can be specified using +.Fl m , +or an +.Xr egrep 1 +regular expression matching the module name can be supplied via +.Fl e . +By default, the module is assumed to have the same name as +.Ar file , +which is not always the case. +.It Ic load_rc_config Ar name +Source in the configuration files for +.Ar name . +First, +.Pa /etc/rc.conf +is sourced if it has not yet been read in. +Then, +.Pa /etc/rc.conf.d/ Ns Ar name +is sourced if it is an existing file. +The latter may also contain other variable assignments to override +.Ic run_rc_command +arguments defined by the calling script, to provide an easy +mechanism for an administrator to override the behaviour of a given +.Xr rc.d 8 +script without requiring the editing of that script. +.It Ic load_rc_config_var Ar name Ar var +Read the +.Xr rc.conf 5 +variable +.Ar var +for +.Ar name +and set in the current shell, using +.Ic load_rc_config +in a sub-shell to prevent unwanted side effects from other variable +assignments. +.It Ic mount_critical_filesystems Ar type +Go through a list of critical file systems, +as found in the +.Xr rc.conf 5 +variable +.Va critical_filesystems_ Ns Ar type , +mounting each one that +is not currently mounted. +.It Ic rc_usage Ar command ... +Print a usage message for +.Va $0 , +with +.Ar commands +being the list of valid arguments +prefixed by +.Sm off +.Dq Bq Li fast | force | one . +.Sm on +.It Ic reverse_list Ar item ... +Print the list of +.Ar items +in reverse order. +.It Ic run_rc_command Ar argument +Run the +.Ar argument +method for the current +.Xr rc.d 8 +script, based on the settings of various shell variables. +.Ic run_rc_command +is extremely flexible, and allows fully functional +.Xr rc.d 8 +scripts to be implemented in a small amount of shell code. +.Pp +.Ar argument +is searched for in the list of supported commands, which may be one +of: +.Bl -tag -width ".Cm restart" -offset indent +.It Cm start +Start the service. +This should check that the service is to be started as specified by +.Xr rc.conf 5 . +Also checks if the service is already running and refuses to start if +it is. +This latter check is not performed by standard +.Fx +scripts if the system is starting directly to multi-user mode, to +speed up the boot process. +.It Cm stop +If the service is to be started as specified by +.Xr rc.conf 5 , +stop the service. +This should check that the service is running and complain if it is not. +.It Cm restart +Perform a +.Cm stop +then a +.Cm start . +Defaults to displaying the process ID of the program (if running). +.It Cm rcvar +Display which +.Xr rc.conf 5 +variables are used to control the startup of the service (if any). +.El +.Pp +If +.Va pidfile +or +.Va procname +is set, also support: +.Bl -tag -width ".Cm restart" -offset indent +.It Cm poll +Wait for the command to exit. +.It Cm status +Show the status of the process. +.El +.Pp +Other supported commands are listed in the optional variable +.Va extra_commands . +.Pp +.Ar argument +may have one of the following prefixes which alters its operation: +.Bl -tag -width ".Li force" -offset indent +.It Li fast +Skip the check for an existing running process, +and sets +.Va rc_fast Ns = Ns Li YES . +.It Li force +Skip the checks for +.Va rcvar +being set to +.Dq Li YES , +and sets +.Va rc_force Ns = Ns Li YES . +This ignores +.Ar argument Ns Va _precmd +returning non-zero, and ignores any of the +.Va required_* +tests failing, and always returns a zero exit status. +.It Li one +Skip the checks for +.Va rcvar +being set to +.Dq Li YES , +but performs all the other prerequisite tests. +.El +.Pp +.Ic run_rc_command +uses the following shell variables to control its behaviour. +Unless otherwise stated, these are optional. +.Bl -tag -width ".Va procname" -offset indent +.It Va name +The name of this script. +This is not optional. +.It Va rcvar +The value of +.Va rcvar +is checked with +.Ic checkyesno +to determine if this method should be run. +.It Va command +Full path to the command. +Not required if +.Ar argument Ns Va _cmd +is defined for each supported keyword. +Can be overridden by +.Va ${name}_program . +.It Va command_args +Optional arguments and/or shell directives for +.Va command . +.It Va command_interpreter +.Va command +is started with: +.Pp +.Dl "#! command_interpreter [...]" +.Pp +which results in its +.Xr ps 1 +command being: +.Pp +.Dl "command_interpreter [...] command" +.Pp +so use that string to find the PID(s) of the running command +rather than +.Va command . +.It Va extra_commands +Extra commands/keywords/arguments supported. +.It Va pidfile +Path to PID file. +Used to determine the PID(s) of the running command. +If +.Va pidfile +is set, use: +.Pp +.Dl "check_pidfile $pidfile $procname" +.Pp +to find the PID. +Otherwise, if +.Va command +is set, use: +.Pp +.Dl "check_process $procname" +.Pp +to find the PID. +.It Va procname +Process name to check for. +Defaults to the value of +.Va command . +.It Va required_dirs +Check for the existence of the listed directories +before running the +.Cm start +method. +.It Va required_files +Check for the readability of the listed files +before running the +.Cm start +method. +.It Va required_modules +Ensure that the listed kernel modules are loaded +before running the +.Cm start +method. +This is done after invoking the commands from +.Va start_precmd +so that the missing modules are not loaded in vain +if the preliminary commands indicate a error condition. +A word in the list can have an optional +.Dq Li : Ns Ar modname +or +.Dq Li ~ Ns Ar pattern +suffix. +The +.Ar modname +or +.Ar pattern +parameter is passed to +.Ic load_kld +through a +.Fl m +or +.Fl e +option, respectively. +See the description of +.Ic load_kld +in this document for details. +.It Va required_vars +Perform +.Ic checkyesno +on each of the list variables +before running the +.Cm start +method. +.It Va ${name}_chdir +Directory to +.Ic cd +to before running +.Va command , +if +.Va ${name}_chroot +is not provided. +.It Va ${name}_chroot +Directory to +.Xr chroot 8 +to before running +.Va command . +Only supported after +.Pa /usr +is mounted. +.It Va ${name}_flags +Arguments to call +.Va command +with. +This is usually set in +.Xr rc.conf 5 , +and not in the +.Xr rc.d 8 +script. +The environment variable +.Sq Ev flags +can be used to override this. +.It Va ${name}_nice +.Xr nice 1 +level to run +.Va command +as. +Only supported after +.Pa /usr +is mounted. +.It Va ${name}_program +Full path to the command. +Overrides +.Va command +if both are set, but has no effect if +.Va command +is unset. +As a rule, +.Va command +should be set in the script while +.Va ${name}_program +should be set in +.Xr rc.conf 5 . +.It Va ${name}_user +User to run +.Va command +as, using +.Xr chroot 8 +if +.Va ${name}_chroot +is set, otherwise +uses +.Xr su 1 . +Only supported after +.Pa /usr +is mounted. +.It Va ${name}_group +Group to run the chrooted +.Va command +as. +.It Va ${name}_groups +Comma separated list of supplementary groups to run the chrooted +.Va command +with. +.It Ar argument Ns Va _cmd +Shell commands which override the default method for +.Ar argument . +.It Ar argument Ns Va _precmd +Shell commands to run just before running +.Ar argument Ns Va _cmd +or the default method for +.Ar argument . +If this returns a non-zero exit code, the main method is not performed. +If the default method is being executed, this check is performed after +the +.Va required_* +checks and process (non-)existence checks. +.It Ar argument Ns Va _postcmd +Shell commands to run if running +.Ar argument Ns Va _cmd +or the default method for +.Ar argument +returned a zero exit code. +.It Va sig_stop +Signal to send the processes to stop in the default +.Cm stop +method. +Defaults to +.Dv SIGTERM . +.It Va sig_reload +Signal to send the processes to reload in the default +.Cm reload +method. +Defaults to +.Dv SIGHUP . +.El +.Pp +For a given method +.Ar argument , +if +.Ar argument Ns Va _cmd +is not defined, then a default method is provided by +.Ic run_rc_command : +.Bl -tag -width ".Sy Argument" -offset indent +.It Sy Argument +.Sy Default method +.It Cm start +If +.Va command +is not running and +.Ic checkyesno Va rcvar +succeeds, start +.Va command . +.It Cm stop +Determine the PIDs of +.Va command +with +.Ic check_pidfile +or +.Ic check_process +(as appropriate), +.Ic kill Va sig_stop +those PIDs, and run +.Ic wait_for_pids +on those PIDs. +.It Cm reload +Similar to +.Cm stop , +except that it uses +.Va sig_reload +instead, and does not run +.Ic wait_for_pids . +Another difference from +.Cm stop +is that +.Cm reload +is not provided by default. +It can be enabled via +.Va extra_commands +if appropriate: +.Pp +.Dl "extra_commands=reload" +.It Cm restart +Runs the +.Cm stop +method, then the +.Cm start +method. +.It Cm status +Show the PID of +.Va command , +or some other script specific status operation. +.It Cm poll +Wait for +.Va command +to exit. +.It Cm rcvar +Display which +.Xr rc.conf 5 +variable is used (if any). +This method always works, even if the appropriate +.Xr rc.conf 5 +variable is set to +.Dq Li NO . +.El +.Pp +The following variables are available to the methods +(such as +.Ar argument Ns Va _cmd ) +as well as after +.Ic run_rc_command +has completed: +.Bl -tag -width ".Va rc_flags" -offset indent +.It Va rc_arg +Argument provided to +.Ic run_rc_command , +after fast and force processing has been performed. +.It Va rc_flags +Flags to start the default command with. +Defaults to +.Va ${name}_flags , +unless overridden by the environment variable +.Sq Ev flags . +This variable may be changed by the +.Ar argument Ns Va _precmd +method. +.It Va rc_pid +PID of +.Va command +(if appropriate). +.It Va rc_fast +Not empty if +.Dq Li fast +prefix was used. +.It Va rc_force +Not empty if +.Dq Li force +prefix was used. +.El +.It Ic run_rc_script Ar file argument +Start the script +.Ar file +with an argument of +.Ar argument , +and handle the return value from the script. +.Pp +Various shell variables are unset before +.Ar file +is started: +.Bd -ragged -offset indent +.Va name , +.Va command , +.Va command_args , +.Va command_interpreter , +.Va extra_commands , +.Va pidfile , +.Va rcvar , +.Va required_dirs , +.Va required_files , +.Va required_vars , +.Ar argument Ns Va _cmd , +.Ar argument Ns Va _precmd . +.Ar argument Ns Va _postcmd . +.Ed +.Pp +The startup behaviour of +.Ar file +depends upon the following checks: +.Bl -enum +.It +If +.Ar file +ends in +.Pa .sh , +it is sourced into the current shell. +.It +If +.Ar file +appears to be a backup or scratch file +(e.g., with a suffix of +.Pa ~ , # , .OLD , +or +.Pa .orig ) , +ignore it. +.It +If +.Ar file +is not executable, ignore it. +.It +If the +.Xr rc.conf 5 +variable +.Va rc_fast_and_loose +is empty, +source +.Ar file +in a sub shell, +otherwise source +.Ar file +into the current shell. +.El +.It Ic stop_boot Op Ar always +Prevent booting to multiuser mode. +If the +.Va autoboot +variable is set to +.Ql yes , +or +.Ic checkyesno Ar always +indicates a truth value, then a +.Dv SIGTERM +signal is sent to the parent +process, which is assumed to be +.Xr rc 8 . +Otherwise, the shell exits with a non-zero status. +.It Ic set_rcvar Op Ar base +Set the variable name required to start a service. +In +.Fx +a daemon is usually controlled by an +.Xr rc.conf 5 +variable consisting of a daemon's name postfixed by the string +.Dq Li "_enable" . +This is not the case in +.Nx . +When the following line is included in a script: +.Pp +.Dl "rcvar=`set_rcvar`" +.Pp +this function will use the value of the +.Va $name +variable, which should be defined by the calling script, +to construct the appropriate +.Xr rc.conf 5 +knob. +If the +.Ar base +argument is set it will use +.Ar base +instead of +.Va $name . +.It Ic wait_for_pids Op Ar pid ... +Wait until all of the provided +.Ar pids +do not exist any more, printing the list of outstanding +.Ar pids +every two seconds. +.It Ic warn Ar message +Display a warning message to +.Va stderr +and log it to the system log +using +.Xr logger 1 . +The warning message consists of the script name +(from +.Va $0 ) , +followed by +.Dq Li ": WARNING: " , +and then +.Ar message . +.El +.Sh FILES +.Bl -tag -width ".Pa /etc/rc.subr" -compact +.It Pa /etc/rc.subr +The +.Nm +file resides in +.Pa /etc . +.El +.Sh SEE ALSO +.Xr rc.conf 5 , +.Xr rc 8 +.Sh HISTORY +The +.Nm +script +appeared in +.Nx 1.3 . +The +.Xr rc.d 8 +support functions appeared in +.Nx 1.5 . +The +.Nm +script +first appeared in +.Fx 5.0 . diff --git a/share/man/man8/rescue.8 b/share/man/man8/rescue.8 new file mode 100644 index 0000000..2921887 --- /dev/null +++ b/share/man/man8/rescue.8 @@ -0,0 +1,184 @@ +.\" Copyright (c) 2003 Tim Kientzle <kientzle@acm.org> +.\" Copyright (c) 2003 Simon L. Nielsen <simon@FreeBSD.org> +.\" 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. +.\" +.\" 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. +.\" +.\" $FreeBSD$ +.\" +.Dd July 23, 2003 +.Dt RESCUE 8 +.Os +.Sh NAME +.Nm rescue +.Nd rescue utilities in +.Pa /rescue +.Sh DESCRIPTION +The +.Pa /rescue +directory contains a collection of common utilities intended for use +in recovering a badly damaged system. +With the transition to a dynamically-linked root beginning with +.Fx 5.2 , +there is a real possibility that the standard tools in +.Pa /bin +and +.Pa /sbin +may become non-functional due to a failed upgrade or a disk error. +The tools in +.Pa /rescue +are statically linked and should therefore be more resistant to +damage. +However, being statically linked, the tools in +.Pa /rescue +are also less functional than the standard utilities. +In particular, they do not have full use of the locale, +.Xr pam 3 , +and nsswitch libraries. +.Pp +If your system fails to boot, and it shows a prompt similar to: +.Pp +.Dl "Enter full pathname of shell or RETURN for /bin/sh: " +.Pp +the first thing to try running is the standard shell, +.Pa /bin/sh . +If that fails, try running +.Pa /rescue/sh , +which is the +.Nm +shell. +To repair the system, the root partition must first be remounted +read-write. +This can be done with the following +.Xr mount 8 +command: +.Pp +.Dl "/rescue/mount -uw /" +.Pp +The next step is to double-check the contents of +.Pa /bin , /sbin , +and +.Pa /usr/lib , +possibly mounting a +.Fx +rescue or +.Dq "live file system" +CD-ROM (e.g., +.Li disc2 +of the officially released +.Fx +ISO images) and copying files from there. +Once it is possible to successfully run +.Pa /bin/sh , /bin/ls , +and other standard utilities, try rebooting back into the standard +system. +.Pp +The +.Pa /rescue +tools are compiled using +.Xr crunchgen 1 , +which makes them considerably more compact than the standard +utilities. +To build a +.Fx +system where space is critical, +.Pa /rescue +can be used as a replacement for the standard +.Pa /bin +and +.Pa /sbin +directories; simply change +.Pa /bin +and +.Pa /sbin +to be symbolic links pointing to +.Pa /rescue . +Since +.Pa /rescue +is statically linked, it should also be possible to dispense with much +of +.Pa /usr/lib +in such an environment. +.Pp +In contrast to its predecessor +.Pa /stand , +.Pa /rescue +is updated during normal +.Fx +source and binary upgrades. +.Sh FILES +.Bl -tag -width ".Pa /rescue" -compact +.It Pa /rescue +Root of the +.Nm +hierarchy. +.El +.Sh SEE ALSO +.Xr crunchgen 1 , +.Xr crash 8 +.Sh HISTORY +The +.Nm +utilities first appeared in +.Fx 5.2 . +.Sh AUTHORS +.An -nosplit +The +.Nm +system was written by +.An Tim Kientzle Aq kientzle@FreeBSD.org , +based on ideas taken from +.Nx . +This manual page was written by +.An Simon L. Nielsen Aq simon@FreeBSD.org , +based on text by +.An Tim Kientzle Aq kientzle@FreeBSD.org . +.Sh BUGS +Most of the +.Nm +tools work even in a fairly crippled system. +The most egregious exception is the +.Nm +version of +.Xr vi 1 , +which currently requires that +.Pa /usr +be mounted so that it can access the +.Xr termcap 5 +files. +Hopefully, a failsafe +.Xr termcap 3 +entry will eventually be added into the +.Xr ncurses 3 +library, so that +.Pa /rescue/vi +can be used even in a system where +.Pa /usr +cannot immediately be mounted. +In the meantime, the +.Nm +version of the +.Xr ed 1 +editor can be used from +.Pa /rescue/ed +if you need to edit files, but cannot mount +.Pa /usr . diff --git a/share/man/man8/sticky.8 b/share/man/man8/sticky.8 new file mode 100644 index 0000000..aa94a11 --- /dev/null +++ b/share/man/man8/sticky.8 @@ -0,0 +1,82 @@ +.\" Copyright (c) 1980, 1991, 1993 +.\" The Regents of the University of California. 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. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``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 REGENTS OR CONTRIBUTORS 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. +.\" +.\" @(#)sticky.8 8.1 (Berkeley) 6/5/93 +.\" $FreeBSD$ +.\" +.Dd June 5, 1993 +.Dt STICKY 8 +.Os +.Sh NAME +.Nm sticky +.Nd sticky text and append-only directories +.Sh DESCRIPTION +A special file mode, called the +.Em sticky bit +(mode S_ISTXT), +is used to indicate special treatment +for directories. +It is ignored for regular files. +See +.Xr chmod 2 +or +the file +.In sys/stat.h +for an explanation of file modes. +.Sh STICKY DIRECTORIES +A directory whose `sticky bit' is set +becomes an append-only directory, or, more accurately, +a directory in which the deletion of files is restricted. +A file in a sticky directory may only be removed or renamed +by a user if the user has write permission for the directory and +the user is the owner of the file, the owner of the directory, +or the super-user. +This feature is usefully applied to directories such as +.Pa /tmp +which must be publicly writable but +should deny users the license to arbitrarily +delete or rename each others' files. +.Pp +Any user may create a sticky directory. +See +.Xr chmod 1 +for details about modifying file modes. +.Sh HISTORY +A +.Nm +command appeared in +.At 32v . +.Sh BUGS +Neither +.Xr open 2 +nor +.Xr mkdir 2 +will create a file with the sticky bit set. diff --git a/share/man/man8/yp.8 b/share/man/man8/yp.8 new file mode 100644 index 0000000..f57c8df --- /dev/null +++ b/share/man/man8/yp.8 @@ -0,0 +1,574 @@ +.\" Copyright (c) 1992/3 Theo de Raadt <deraadt@fsa.ca> +.\" 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. +.\" +.\" from: @(#)yp.8 1.0 (deraadt) 4/26/93 +.\" $FreeBSD$ +.\" +.Dd June 25, 2009 +.Dt YP 8 +.Os +.Sh NAME +.Nm yp +.Nd description of the YP/NIS system +.Sh SYNOPSIS +.Nm +.Sh DESCRIPTION +The +.Nm YP +subsystem allows network management of passwd, group, netgroup, hosts, +services, rpc, bootparams and ethers file +entries through the functions +.Xr getpwent 3 , +.Xr getgrent 3 , +.Xr getnetgrent 3 , +.Xr gethostent 3 , +.Xr getnetent 3 , +.Xr getrpcent 3 , +and +.Xr ethers 3 . +The +.Xr bootparamd 8 +daemon makes direct +.Tn NIS +library calls since there are no +functions in the standard C library for reading bootparams. +.Tn NIS +support is enabled in +.Xr nsswitch.conf 5 . +.Pp +The +.Nm YP +subsystem is started automatically in +.Pa /etc/rc +if it has been initialized in +.Pa /etc/rc.conf +and if the directory +.Pa /var/yp +exists (which it does in the default distribution). +The default +.Tn NIS +domain must also be set with the +.Xr domainname 1 +command, which will happen automatically at system startup if it is +specified in +.Pa /etc/rc.conf . +.Pp +.Tn NIS +is an +.Tn RPC Ns -based +client/server system that allows a group of +machines within an +.Tn NIS +domain to share a common set of configuration files. +This permits a system +administrator to set up +.Tn NIS +client systems with only minimal configuration +data and add, remove or modify configuration data from a single location. +.Pp +The canonical copies of all +.Tn NIS +information are stored on a single machine +called the +.Tn NIS +.Em "master server" . +The databases used to store the information are called +.Tn NIS +.Em maps . +In +.Fx , +these maps are stored in +.Pa /var/yp/ Ns Aq Ar domainname +where +.Aq Ar domainname +is the name of the +.Tn NIS +domain being served. +A single +.Tn NIS +server can +support several domains at once, therefore it is possible to have several +such directories, one for each supported domain. +Each domain will have +its own independent set of maps. +.Pp +In +.Fx , +the +.Tn NIS +maps are Berkeley DB hashed database files (the +same format used for the +.Xr passwd 5 +database files). +Other operating systems that support +.Tn NIS +use old-style +.Nm ndbm +databases instead (largely because Sun Microsystems originally based +their +.Tn NIS +implementation on +.Nm ndbm , +and other vendors have simply licensed +Sun's code rather than design their own implementation with a different +database format). +On these systems, the databases are generally split +into +.Pa .dir +and +.Pa .pag +files which the +.Nm ndbm +code uses to hold separate parts of the hash +database. +The Berkeley DB hash method instead uses a single file for +both pieces of information. +This means that while you may have +.Pa passwd.byname.dir +and +.Pa passwd.byname.pag +files on other operating systems (both of which are really parts of the +same map), +.Fx +will have only one file called +.Pa passwd.byname . +The difference in format is not significant: only the +.Tn NIS +server, +.Xr ypserv 8 , +and related tools need to know the database format of the +.Tn NIS +maps. +Client +.Tn NIS +systems receive all +.Tn NIS +data in +.Tn ASCII +form. +.Pp +There are three main types of +.Tn NIS +systems: +.Bl -enum +.It +.Tn NIS +clients, +which query +.Tn NIS +servers for information. +.It +.Tn NIS +master servers, +which maintain the canonical copies of all +.Tn NIS +maps. +.It +.Tn NIS +slave servers, +which maintain backup copies of +.Tn NIS +maps that are periodically +updated by the master. +.El +.Pp +A +.Tn NIS +client establishes what is called a +.Em binding +to a particular +.Tn NIS +server using the +.Xr ypbind 8 +daemon. +The +.Xr ypbind 8 +utility checks the system's default domain (as set by the +.Xr domainname 1 +command) and begins broadcasting +.Tn RPC +requests on the local network. +These requests specify the name of the domain for which +.Xr ypbind 8 +is attempting to establish a binding. +If a server that has been +configured to serve the requested domain receives one of the broadcasts, +it will respond to +.Xr ypbind 8 , +which will record the server's address. +If there are several servers +available (a master and several slaves, for example), +.Xr ypbind 8 +will use the address of the first one to respond. +From that point +on, the client system will direct all of its +.Tn NIS +requests to that server. +The +.Xr ypbind 8 +utility will occasionally +.Dq ping +the server to make sure it is still up +and running. +If it fails to receive a reply to one of its pings +within a reasonable amount of time, +.Xr ypbind 8 +will mark the domain as unbound and begin broadcasting again in the +hopes of locating another server. +.Pp +.Tn NIS +master and slave servers handle all +.Tn NIS +requests with the +.Xr ypserv 8 +daemon. +The +.Xr ypserv 8 +utility is responsible for receiving incoming requests from +.Tn NIS +clients, +translating the requested domain and map name to a path to the +corresponding database file and transmitting data from the database +back to the client. +There is a specific set of requests that +.Xr ypserv 8 +is designed to handle, most of which are implemented as functions +within the standard C library: +.Bl -tag -width ".Fn yp_master" +.It Fn yp_order +check the creation date of a particular map +.It Fn yp_master +obtain the name of the +.Tn NIS +master server for a given +map/domain +.It Fn yp_match +lookup the data corresponding to a given in key in a particular +map/domain +.It Fn yp_first +obtain the first key/data pair in a particular map/domain +.It Fn yp_next +pass +.Xr ypserv 8 +a key in a particular map/domain and have it return the +key/data pair immediately following it (the functions +.Fn yp_first +and +.Fn yp_next +can be used to do a sequential search of an +.Tn NIS +map) +.It Fn yp_all +retrieve the entire contents of a map +.El +.Pp +There are a few other requests which +.Xr ypserv 8 +is capable of handling (i.e., acknowledge whether or not you can handle +a particular domain +.Pq Dv YPPROC_DOMAIN , +or acknowledge only if you can handle the domain and be silent otherwise +.Pq Dv YPPROC_DOMAIN_NONACK ) +but +these requests are usually generated only by +.Xr ypbind 8 +and are not meant to be used by standard utilities. +.Pp +On networks with a large number of hosts, it is often a good idea to +use a master server and several slaves rather than just a single master +server. +A slave server provides the exact same information as a master +server: whenever the maps on the master server are updated, the new +data should be propagated to the slave systems using the +.Xr yppush 8 +command. +The +.Tn NIS +.Pa Makefile +.Pq Pa /var/yp/Makefile +will do this automatically if the administrator creates +.Pa /var/yp/Makefile.local +and empties the +.Va NOPUSH +variable: +.Bd -literal -offset four +.Li NOPUSH= +.Ed +.Pp +.Va ( NOPUSH +is set to true by default because the default configuration is +for a small network with only one +.Tn NIS +server). +The +.Xr yppush 8 +command will initiate a transaction between the master and slave +during which the slave will transfer the specified maps from the +master server using +.Xr ypxfr 8 . +(The slave server calls +.Xr ypxfr 8 +automatically from within +.Xr ypserv 8 ; +therefore it is not usually necessary for the administrator +to use it directly. +It can be run manually if +desired, however.) +Maintaining +slave servers helps improve +.Tn NIS +performance on large +networks by: +.Bl -bullet +.It +Providing backup services in the event that the +.Tn NIS +master crashes +or becomes unreachable +.It +Spreading the client load out over several machines instead of +causing the master to become overloaded +.It +Allowing a single +.Tn NIS +domain to extend beyond +a local network (the +.Xr ypbind 8 +daemon might not be able to locate a server automatically if it resides on +a network outside the reach of its broadcasts. +It is possible to force +.Xr ypbind 8 +to bind to a particular server with +.Xr ypset 8 +but this is sometimes inconvenient. +This problem can be avoided simply by +placing a slave server on the local network.) +.El +.Pp +The +.Fx +.Xr ypserv 8 +is specially designed to provide enhanced security (compared to +other +.Tn NIS +implementations) when used exclusively with +.Fx +client +systems. +The +.Fx +password database system (which is derived directly +from +.Bx 4.4 ) +includes support for +.Em "shadow passwords" . +The standard password database does not contain users' encrypted +passwords: these are instead stored (along with other information) +in a separate database which is accessible only by the super-user. +If the encrypted password database were made available as an +.Tn NIS +map, this security feature would be totally disabled, since any user +is allowed to retrieve +.Tn NIS +data. +.Pp +To help prevent this, +.Fx Ns 's +.Tn NIS +server handles the shadow password maps +.Pa ( master.passwd.byname , +.Pa master.passwd.byuid , +.Pa shadow.byname +and +.Pa shadow.byuid ) +in a special way: the server will only provide access to these +maps in response to requests that originate on privileged ports. +Since only the super-user is allowed to bind to a privileged port, +the server assumes that all such requests come from privileged +users. +All other requests are denied: requests from non-privileged +ports will receive only an error code from the server. +Additionally, +.Fx Ns 's +.Xr ypserv 8 +includes support for +.An Wietse Venema Ns 's +tcp wrapper package; with tcp +wrapper support enabled, the administrator can configure +.Xr ypserv 8 +to respond only to selected client machines. +.Pp +While these enhancements provide better security than stock +.Tn NIS , +they are by no means 100% effective. +It is still possible for +someone with access to your network to spoof the server into disclosing +the shadow password maps. +.Pp +On the client side, +.Fx Ns 's +.Xr getpwent 3 +functions will automatically search for the +.Pa master.passwd +maps and use them if they exist. +If they do, they will be used, and +all fields in these special maps (class, password age and account +expiration) will be decoded. +If they are not found, the standard +.Pa passwd +maps will be used instead. +.Sh COMPATIBILITY +When using a +.No non- Ns Fx +.Tn NIS +server for +.Xr passwd 5 +files, it is unlikely that the default MD5-based format that +.Fx +uses for passwords will be accepted by it. +If this is the case, the value of the +.Va passwd_format +setting in +.Xr login.conf 5 +should be changed to +.Qq Li des +for compatibility. +.Pp +Some systems, such as +.Tn SunOS +4.x, need +.Tn NIS +to be running in order +for their hostname resolution functions +.Fn ( gethostbyname , +.Fn gethostbyaddr , +etc.) to work properly. +On these systems, +.Xr ypserv 8 +performs +.Tn DNS +lookups when asked to return information about +a host that does not exist in its +.Pa hosts.byname +or +.Pa hosts.byaddr +maps. +.Fx Ns 's +resolver uses +.Tn DNS +by default (it can be made to use +.Tn NIS , +if desired), therefore its +.Tn NIS +server does not do +.Tn DNS +lookups +by default. +However, +.Xr ypserv 8 +can be made to perform +.Tn DNS +lookups if it is started with a special +flag. +It can also be made to register itself as an +.Tn NIS +v1 server +in order to placate certain systems that insist on the presence of +a v1 server +.No ( Fx +uses only +.Tn NIS +v2, but many other systems, +including +.Tn SunOS +4.x, search for both a v1 and v2 server when binding). +.Fx Ns 's +.Xr ypserv 8 +does not actually handle +.Tn NIS +v1 requests, but this +.Dq "kludge mode" +is useful for silencing stubborn systems that search for both +a v1 and v2 server. +.Pp +(Please see the +.Xr ypserv 8 +manual page for a detailed description of these special features +and flags.) +.Sh HISTORY +The +.Nm YP +subsystem was written from the ground up by +.An Theo de Raadt +to be compatible to Sun's implementation. +Bug fixes, improvements +and +.Tn NIS +server support were later added by +.An Bill Paul . +The server-side code was originally written by +.An Peter Eriksson +and +.An Tobias Reber +and is subject to the GNU Public License. +No Sun code was +referenced. +.Sh BUGS +While +.Fx +now has both +.Tn NIS +client and server capabilities, it does not yet have support for +.Xr ypupdated 8 +or the +.Fn yp_update +function. +Both of these require secure +.Tn RPC , +which +.Fx +does not +support yet either. +.Pp +The +.Xr getservent 3 +and +.Xr getprotoent 3 +functions do not yet have +.Tn NIS +support. +Fortunately, these files +do not need to be updated that often. +.Pp +Many more manual pages should be written, especially +.Xr ypclnt 3 . +For the time being, seek out a local Sun machine and read the +manuals for there. +.Pp +Neither Sun nor this author have found a clean way to handle +the problems that occur when ypbind cannot find its server +upon bootup. |
