This is the latest version of the options(4) man page I've been
working on, documenting machine independent kernel configuration
options.

Its still incomplete -- lots of sections are delimited by []s,
indicating that I don't know answers to questions I've raised.

Please send me comments on this man page soon. I intend to commit it
-- even if it is still incomplete -- within the next few days.

Perry

.\"	$NetBSD$
.\"
.\" Copyright (c) 1996 
.\" 	Perry E. Metzger.  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 withough specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
.\"
.\"
.Dd September 6, 1996
.Os NetBSD 1.2
.Dt OPTIONS 4
.Sh NAME
.Nm options
.Nd Miscellaneous kernel configuration options
.Sh SYNOPSIS
.Cd options ...
.Sh DESCRIPTION
This manual page describes a number of miscellaneous kernel
configuration options that may be specified in a kernel config
file. See
.Xr config 8
for details on configuring kernels.
.Ss Compatibility Options
.Bl -ohang
.It Cd options COMPAT_09
Enable binary compatibility with
.Nx 0.9 .
This enables support for
16-bit user, group, and process ids (following revisions support
32-bit identifiers),
It also allows the use of the deprecated getdomainname, setdomainname,
and uname syscalls.
This option also allows using numeric fileystem identifiers rather
than strings.  Post 0.9 versions use string identifiers.
.It Cd options COMPAT_10
Enable binary compatibility with
.Nx 1.0 .
This option allows the use of the filesystem name of "ufs" as an alias for "ffs".  The name "ffs" should be used post 1.0 in /etc/fstab and other files.
It also adds old syscalls for the SYSV shared memory interface.  This
was changed post 1.0 to work on 64-bit architectures.
.It Cd options COMPAT_11
Enable binary compatibility with
.Nx 1.1 .
This allows binaries running on the i386 port to gain direct access to
the io ports by opening /dev/io read/write.  This functionality was
replaced by i386_iopl() post 1.1.
It also modifies the location of the boot block magic number on the
atari port.
.It Cd options COMPAT_12
Enable binary compatibility with
.Nx 1.2 .
This allows the use of old syscalls for reboot.  The syscall number
was changed post 1.2 to add functionality to the reboot syscall.
.It Cd options COMPAT_43
Enables compatibility with
.Bx 4.3 .
This adds an old syscall for lseek.  It also adds the ioctls for
TIOCGETP and TIOCSETP.  The return values for getpid, getgid, and
getuid syscalls are modified as well, to return the parent's pid and
uid as well as the current process's.  It also enables the deprecated
NTTYDISC terminal line disipline.  [It also does something funky in
net/if.c, but I can't figure out exactly what...]  It also enables
support for some older pre BSD 4.4 socket calls.
.It Cd options COMPAT_SVR4
On those architectures that support it, this enables binary
compatibility with
.Ux
System V Release 4 applications built for the same architecture.
.El
.Ss Debugging Options
.Bl -ohang
.It Cd options DDB
Compiles in a kernel debugger for diagnosing kernel problems. See
.Xr ddb 4
for details. 
.Em NOTE:
not available on all architectures.
.It Cd makeoptions DEBUG="-g"
The -g flag causes
.Pa netbsd.gdb
to be built in addition to
.Pa netbsd .
.Pa netbsd.gdb
is useful for debugging kernel crash dumps with gdb.
The command
.Dl gdb -k
invokes gdb in kernel debugger mode.
See
.Xr gdb 1
for details.
.It Cd options DIAGNOSTIC
Adds code to the kernel that does internal consistency checks.  This
code will cause the kernel to panic if corruption of internal data
structures is detected.
.It Cd options KTRACE
Add hooks for the system call tracing facility, which allows users to
watch the system call invokation behavior of processes. See
.Xr ktrace 1
for details.
.El
.Ss File Systems and File System Options
.Bl -ohang
.It Cd options FFS
Includes code implementing the Berkeley Fast File System
.Em ( FFS ) .
Most machines need this if they are not running diskless.
.It Cd options LFS
Include the log structured file system
.Em ( LFS ) .
See
.Xr mount_lfs 8
and
.Xr newlfs 8
for details.
.It Cd options MFS
Include the memory file system
.Em ( MFS ) .
This file system stores files in swappable memory, and produces
notable performance improvements when it is used as the file store
for /tmp and similar file systems. See
.Xr mount_mfs 8
for details.
.It Cd options NFSCLIENT
.It Cd options NFSSERVER
Include code implementing the client and server sides of the
.Em NFS
(Network File System) remote file sharing protocol. Although the bulk
of the code implementing 
.Em NFS
is kernel based, several user level daemons are needed for it to
work. See 
.Xr mount_nfs 8 ,
.Xr mountd 8 ,
.Xr nfsd 8 , 
and
.Xr nfsiod 8
for details.
.It Cd options CD9660
Includes code for the ISO 9660 + Rock Ridge file system, which is the
standard file system on many CD-ROMs. Useful mostly if you have a CD
drive. See
.Xr mount_cd9660 8
for details.
.It Cd options MSDOSFS
Includes the MS-DOS FAT file system, which is reportedly still used
by people who have not heard of
NetBSD.
Also implements the Windows 95
extensions to the same, which permit the use of longer, mixed case
file names. see
.Xr mount_msdos 8
and
.Xr fsck_msdos 8
for details.
.It Cd options FDESC
Includes code for a file system, conventionally mounted on
.Pa /dev/fd ,
which permits access to the per-process file descriptor space via
special files in the file system. [Am I correct that this is redundant
with the stuff already mknod'ed in /dev via the fd(4) driver?]
See
.Xr mount_fdesc 8
for details.
.It Cd options FIFO
Augments the system to permit the use of System V style FIFOs. This
option is recommended. [I'm not particularly clear on this how this
works -- am I correct that its not a file system you mount but just an
ordinary option? If so, should it be moved near QUOTA below? Do I even
have the description right?]
.It Cd options KERNFS
Includes code which permits the mounting of a special file system
(normally mounted on
.Pa /kern )
in which files representing various kernel variables and parameters
may be found.
See
.Xr mount_kernfs 8
for details.
.It Cd options NULLFS
Includes code for a loopback file system. This permits portions of the file
hierarchy to be re-mounted in other places. The code really exists to
provide an example of a stackable file system layer. See
.Xr mount_null 8
for details.
.It Cd options PORTAL
Includes the (experimental) portal filesystem. This permits
interesting tricks like opening TCP sockets by opening files in the
file system. The portal file system is conventionally mounted on
.Pa /p
and is partially implemented by a special daemon. See
.Xr mount_portal 8
for details.
.It Cd options PROCFS
Includes code for a special file system (conventionally mounted on
.Pa /proc )
in which the process space becomes visible in the file system. Among
other things, the memory spaces of processes running on the system are
visible as files, and signals may be sent to processes by writing to
.Pa ctl
files in the procfs namespace. See
.Xr mount_procfs 8
for details.
.It Cd options UMAPFS
Includes a loopback file system in which user and group ids may be
remapped -- this can be useful when mounting alien file systems with
different uids and gids than the local system.
See
.Xr mount_umap 8
for details.
.It Cd options UNION
Includes code for the union file system, which permits directories to
be mounted on top of each other in such a way that both file systems
remain visible -- this permits tricks like allowing writing on a
read-only file systems like a CD-ROM by mounting a local writable file
system on top of the read-only file system. See
.Xr mount_union 8
for details.
.El
.Ss File System Options
.Bl -ohang
.It Cd options QUOTA
Enables kernel support for file system quotas. See
.Xr quotaon 8 ,
.Xr edquota 8 ,
and
.Xr quota 1
for details. [What file systems do quotas work on?]
.El
.Ss Miscellaneous Options
.Bl -ohang
.It Cd options GENERIC
Indicates, on some ports, that code permitting booting and mounting
root on any file system should be included.
This options also allows the "swap generic" configuration file option
to find the location of the swap file at boot time rather than having a
compiled in default.
Largely obsolete though
still in use on some architectures. [Do I have this right?]
.It Cd options LKM
Enable loadable kernel modules. See
.Xr lkm 4
for details.
.Em NOTE:
not available on all architectures.
.It Cd options NTP
Turns on support for kernel PLLs for
.Em NTP
(Network Time Protocol). [Anyone have more data on this?]
.It Cd option SETUIDSCRIPTS
Allows scripts with the setuid bit set to execute as the effective
user rather than the real user, just like binary executables.
NOTE: Using this option will also enable 
.Em option FDSCRIPTS
.It Cd option FDSCRIPTS
Allows execution of scripts with the execute bit set, but not the
read bit, by opening the file and passing the file descriptor to
the shell, rather than the filename.  NOTE: Execute only (non-readable)
scripts will have 
.Va argv[0]
set to
.Pa /dev/fd/* .
.It Cd options TIMEZONE=integer
.It Cd options DST=[0|1]
The kernel (and typically the hardware battery backed-up clock on
those machines that have one) keeps time in
.Em UTC
(Universal Coordinated Time, once known as
.Em GMT ,
or Greenwich Mean Time)
and not in the time of the local time zone.
The
.Em TIMEZONE
option is used to tell the kernel that the 
hardware clock is offset from
.Em UTC
by the specified number of minutes. This is typically used when a
machine boots several operating systems and one of them wants the
hardware clock to run in the local time zone and not in
.Em UTC ,
e.g.
.Em TIMEZONE=300
means
the hardware clock is running US Eastern Time (300 minutes behind 
.Em UTC ) ,
and not 
.Em UTC .
.Bd -filled -offset indent
.Em HISTORICAL NOTE:
The
.Em TIMEZONE
option at one time was used to set the kernel's idea of what time zone
the system was operating in -- this information was returned by
.Xr gettimeofday 2 .
Time zone information is now managed by user space software based
on the contents of the
.Pa /etc/localtime
file or the
.Ev TZ
environment variable.
(See
.Xr zic 8 ,
.Xr tzfile 5 ,
and
.Xr tzset 3
for details).
This usage of the
.Em TIMEZONE
option is now obsolete.
.Ed
.Pp
The
.Em DST
option indicates [something or other -- I'm really not clear on
this. Can someone help me fill this part in?]
.El
.Ss Networking Options
.Bl -ohang
.It Cd options GATEWAY
Enables IP routing behavior. With this option enabled, the machine will
forward IP datagrams between its interfaces that are destined for other
machines. (Note that
.Em GATEWAY
has no impact on protocols other than IP, such as CLNP or XNS). Note
that even without this option, the kernel will still forward some
packets (such as source routed packets) -- removing
.Em GATEWAY
is insufficient to stop all routing through a bastion host on a
firewall.
To turn off source-routing, use 
.Em options IPFORWSRCRT=0 .
.It Cd options INET
Includes support for the TCP/IP protocol stack. You almost certainly
want this. See
.Xr inet 4
for details.
[Is this option required, though? Can you save space on a
standalone machine by nuking it, or will the kernel compile croak?]
.It Cd options NS
Include support for the Xerox XNS protocol stack. See
.Xr ns 4
for details.
.It Cd options ISO,TPIP
Include support for the ubiquitous OSI protocol stack. See
.Xr iso 4
for details.
.It Cd options EON
Include support for OSI tunneling over IP. [Do we have any
documentation on this at all?]
.It Cd options CCITT,LLC,HDLC
Include support for the X.25 protocol stack. [Really? What is this
thing? Does anything actually drive it? Do we have any documentation?]
.It Cd options IPNOPRIVPORTS
Normally, only root can bind a socket descriptor to a so-called
.Dq privileged
TCP
port, that is, a port number in the range 0-1023.  This option
eliminates those checks from the kernel. This can be useful if there
is a desire to allow daemons without privileges to bind those ports,
e.g. on firewalls. The security tradeoffs in doing this are subtle.
This option should only be used by experts.
.It Cd options TCP_COMPAT_42
TCP bug compatibility with 4.2BSD.  In 4.2BSD, TCP sequence numbers
were 32-bit signed values.  Modern implementations of TCP use unsigned
values.  This option clamps the initial sequence number to start in
the range 2^31 rather than the full unsigned range of 2^32.  Also,
under 4.2BSD, keepalive packets must contain at least one byte or else
the remote end would not respond.
.El
.Ss System V IPC Options
.Bl -ohang
.It Cd options SYSVMSG
Includes support for System V style message queues.
See
.Xr msgctl 2 ,
.Xr msgget 2 ,
.Xr msgrcv 2 ,
.Xr msgsnd 2 .
.It Cd options SYSVSEM
Includes support for System V style semaphores.
See
.Xr semctl 2 ,
.Xr semget 2 ,
.Xr semop 2 .
.It Cd options SYSVSHM
Includes support for System V style shared memory.
See
.Xr shmat 2 ,
.Xr shmctl 2 ,
.Xr shmdt 2 ,
.Xr shmget 2 .
.It Cd options SHMPAXPGS=value
Sets the maximum number of System V style shared memory
pages. Default value is 1024.  [Better description, please?]
.El
.Ss VM Related Options
.Bl -ohang
.It Cd options SWAPPAGER
Turns on paging. [Better description, someone? Is this really optional
anyway? If not, why is it an option?]
.It Cd options VNODEPAGER
support for mmap()ing of files [Better description, please? What does
this do EXACTLY.]
.It Cd options DEVPAGER
support for mmap()ing of devices  [Better description, please? What does
this do EXACTLY.]
.It Cd options NMBCLUSTERS=value
number of slots in the kernel submap "mb_map".  [Better description,
please? What does this do EXACTLY. CGD had some explanatory text
that I didn't understand]  Default is 256 (512 with
GATEWAY).  Increase this value if you get "mb_map full" messages.
.It Cd options NKMEMCLUSTERS=value
number of slots in the kernel submap "kmem_map".  [Better description,
please? Chris CGD had some comments that I didn't understand.]
Default is <look this up>.  Increase this value if you get "out of
space in kmem_map" panics.
.El
.\" The following requests should be uncommented and used where appropriate.
.\" .Sh FILES
.\" .Sh EXAMPLES
.Sh SEE ALSO
.Xr config 8 ,
.Xr gettimeofday 2 ,
.Xr tzset 3 ,
.Xr zic 8 ,
.Xr tzfile 5 ,
.Xr msgctl 2 ,
.Xr msgget 2 ,
.Xr msgrcv 2 ,
.Xr msgsnd 2 ,
.Xr semctl 2 ,
.Xr semget 2 ,
.Xr semop 2 ,
.Xr shmat 2 ,
.Xr shmctl 2 ,
.Xr shmdt 2 ,
.Xr shmget 2 ,
.Xr ddb 4 ,
.Xr lkm 4 ,
.Xr inet 4 ,
.Xr ns 4 ,
.Xr iso 4 ,
.Xr mount_lfs 8 ,
.Xr newlfs 8 ,
.Xr mount_mfs 8 ,
.Xr mount_nfs 8 ,
.Xr mount_cd9660 8 ,
.Xr mount_msdos 8 ,
.Xr mount_fdesc 8 ,
.Xr mount_kernfs 8 ,
.Xr mount_null 8 ,
.Xr mount_portal 8 ,
.Xr mount_procfs 8 ,
.Xr mount_umap 8 ,
.Xr mount_union 8 ,
.Xr edquota 8 ,
.Xr quotaon 8 ,
.Xr quota 1 ,
.Xr ktrace 1 ,
.Xr gdb 1
.Sh HISTORY
The
.Nm
man page first appeared in
.Nx 1.3 .