NETCONFIG(1) NETCONFIG(1)
2 Aug 1993
NAME
netconfig - configure network kernel options
SYNOPSIS
netconfig [ <variable-name> [value] ] ...
DESCRIPTION
Netconfig is a tool for managing network configuration variables.
Kernel network software includes a number of configurable variables
inside the running kernel. Netconfig allows one to change those
variables' values. With no options, netconfig prints out values of all
the network options that it knows about and can find in the kernel.
Netconfig interprets its command line as a series of requests to set
or get a variable's contents. A request to set a variable consists of
the name of a kernel variable followed by a value for that variable.
A request to get a variable's value consists only of the name of the
variable. It is possible to request both a get and a set of a
variable; writes are performed before reads, so that would amount to
confirmation that a write really has been performed. Netconfig
implements variable typing. Each variable is treated as either
numeric or boolean. Numeric variables (such as TCP output buffer
size) expect numeric values upon being set. Boolean variables expect
either 'on', 'off', or a number as a value; a nonzero numeric value is
the same as the 'on' value, and a numeric value of zero is the same as
the 'off' value. Netconfig ignores underscores for purposes of
matching variable names on the command line with actual variable
names. For example, 'tcpsendspace' would succeed in matching
'tcp_sendspace'. The kernel memory special device /dev/kmem, which
netconfig relies upon to read and write its values, is usually
installed with extremely restrictive permissions. Thus, it is
suggested that one install netconfig setgid kmem, or setuid root if
there is no group kmem. If netconfig is installed setuid or setgid,
it only uses the special access to allow anybody to run netconfig and
find out what the values of kernel variables are. In order to change
kernel variables, the user running the program must already have
permission to write to /dev/kmem; normally, one must either be root or
in group kmem.
OUTPUT FORMAT
Netconfig prints out its variables grouped by protocol. The format of
each line is as follows:
Input Buffer Size (tcp_sendspace): 28672
"Output Buffer Size" is a description of what the variable controls.
"tcp_sendspace" is a the actual name of the variable that one would
use in configuration. 28672 is the value tcp_sendspace is currently
set to in kernel memory.
USAGE NOTES
One can find out what kernel variables may be set in one's kernel by
looking at the output of netconfig run without options. The variable
names are the lowercase names in parenthesis. Many vendors ship
- 1 - Formatted: January 15, 2025
NETCONFIG(1) NETCONFIG(1)
2 Aug 1993
machines with values of network configuration variables that track
current network technology and memory prices slowly. Some values made
sense when a 2 megabyte VAX was pretty impressive. Netconfig can be
used to automatically set network variable values upon boot. We place
the following invocation in our /etc/rc.local to do this:
if [ -f /usr/local/bin/netconfig ]; then
/usr/local/bin/netconfig `cat /etc/netconfig.conf` 2>/dev/null
fi
The effect of this is that network variable settings are read from
/etc/netconfig.conf upon boot. Three sample 'netconfig.conf's are
provided with the netconfig distribution: netconfig.conf contains
values consistent with highest performance without a danger of loss of
safety or interoperability. netconfig.conf.hiperf contains values
that give highest performance, at a small risk of loss of
interoperability. netconfig.conf.bigwin contains values that give
highest performance on machines supporting big windows (this will also
activate the big windows implementation) WARNING: don't use
netconfig.conf.bigwin on machines not supporting big windows - check
by running netconfig and looking for the presence of tcp_dont_winscale
- packets may silently stop being received.
EXAMPLES
To set tcp_recvspace (TCP input buffer size) to 28672:
netconfig tcp_recvspace 28672
Another way to set tcp_recvspace to 28672, making use of the
underscore-ignoring feature:
netconfig tcprecvspace 28672
To show the value of tcp_recvspace:
netconfig tcp_recvspace
VARIABLE MEANINGS AND SUGGESTED SETTINGS
This section provides description of and suggested settings for some
of the variables. These suggestions are only meant as starting
points; you should consider your environment and application carefully
before deciding what appropriate settings are. I have attempted to be
conservative in my suggestions, but neither I nor the University of
California will be responsible if these settings result in explosions
or other disasters. TCP MAX WINDOW SIZES - TCP_SENDSPACE AND
TCP_RECVSPACE Tcp_sendspace and tcp_sendspace control TCP maximum
window size. For a TCP connection to operate at maximum speed over a
given connection, the TCP maximum window must be at least as large as
the product of the round-trip delay of the connection and the max
bandwidth of the connection. For full speed TCP over local Ethernet,
that comes out to around 5k, but it goes up for FDDI and remote
connections. The maximum window size also potentially controls the
maximum time it could take a TCP window to drain over a slow SLIP
link. Memory prices suggest that a machine on a LAN should have as
large a TCP window size as possible. Unfortunately, limitations on
some implementations of TCP and assorted performance quirks reduce the
optimal conservative value to <32k - mbuf cluster length>. Mbuf
cluster length varies by OS, but is so far never over 8k in size,
- 2 - Formatted: January 15, 2025
NETCONFIG(1) NETCONFIG(1)
2 Aug 1993
yielding a safe value for everyone of:
tcp_sendspace 24576
tcp_recvspace 24576
Getting Gutsy: Raising Max Window Size: If you are feeling slightly
gutsy or have a need for a larger window size, you could raise these
values to 48k (49152) each. Environments in which I have heard of
trouble with such values are ones in which machines are present that
process TCP window sizes using 16-bit signed variables - some PC
TCP/IPs. Note that, depending upon your machine, one can go as high
as somewhere between 52428 and (64k - 1). I do NOT recommend pushing
above 52428 unless you know what you're doing (see sbreserve source
code in uipc_socket2.c) (but see the discussion of TCP Big Windows and
tcp_dont_winscale, below). Even pushing above 48k can be a bad idea
because most TCP/IP implementations exhibit slightly inefficient
behavior when faced with windows that are not even multiples of the
cluster mbuf size - and worse still, the inefficiency will affect even
connections that do not need a large TCP window size, which is most
TCP connections. TCP BIG WINDOWS - TCP_DONT_WINSCALE Even raising the
TCP window size to its usual maximum of 64k is sometimes not enough.
Over high-bandwidth WAN links, the window size may need to go higher
to not act as a limit on bandwidth. For example, if one were able to
move data at the theoretical maximum speed of the NSFNET backbone all
the way across the country (forget it, unless both you and the thing
you're connecting to have a dedicated T3 link or work on the same
campus as an NSF backbone node), one might need as much as 3/4 of a
megabyte of window size. Most of the time it doesn't matter, because
one rarely gets that sort of bandwidth across the NSFNET, not because
of the backbone but because of the much slower regional networks and
hookups to the regionals and the contention for those links. However,
if you are privileged to work with a high-bandwidth (>= T3) WAN or be
on the same campus as an NSF backbone link, you may find it useful to
raise window size. Some hosts support a TCP extension to do exactly
this. Tcp_dont_winscale controls this extension. If it's off, then
window scaling is on. Unfortunately, while vendors do often ship with
TCP window scaling on, they usually neglect various other necessary
adjustments. One must raise tcp_recvspace and tcp_sendspace to take
advantage of this. Additionally, one cannot raise tcp_recvspace and
tcp_sendspace to above 64k without raising another parameter, called
sb_max (see just below). Note that this has no effect on performance
on most current hosts - it generally is not needed for LAN
communication, and is usually only really needed across links with
extraordinary bandwidth (T3 or higher) or latency (high-bandwidth
satellite link). 256k seems to me to be a usefully high starting
point for setting all three variables if you need TCP big windows -
it's enough to fill a T3 network running the length of the US East or
West Coast or a 2 Mbit satellite channel at geosynch. However, this
is the sort of thing that can get pretty application-specific, so I
recommend calculating it yourself (see above on how to calculate TCP
max window size). Note that even if you do have access to a high-
bandwidth WAN link, big windows may still not help you if your machine
doesn't have the horsepower to pump out packets faster than it's
- 3 - Formatted: January 15, 2025
NETCONFIG(1) NETCONFIG(1)
2 Aug 1993
already doing. SYSTEM OVERALL SOCKET BUFFER LIMIT - SB_MAX Sb_max
controls how large a socket buffer limit can get. Normally this is
statically limited to 64k, but machines shipped with support for TCP
big windows often have an option to raise that limit so that it is
possible to specify a bigger window. You must appropriately set all
of sb_max, tcp_dont_winscale, tcp_sendspace, and tcp_recvspace to use
TCP big windows. UDP MAX QUEUE LENGTH - UDP_SENDSPACE AND
UDP_RECVSPACE Udp_sendspace and udp_recvspace control how large a UDP
packet your machine is able to send or receive. In addition,
udp_recvspace controls how much UDP data is allowed to enqueue on a
given socket awaiting user process reception. I have never seen any
reason to limit these in general for most modern workstations (user
processes requiring latency limits can override these values on a
per-socket basis):
udp_sendspace 49152
udp_recvspace 49152
ROUTING ON/OFF - IPFORWARDING, IPSENDREDIRECTS Ipforwarding controls
whether a host is willing to route packets if it has at least two
network interfaces. If you do not intend a machine to be used as a
router, you can avoid the unexpected by setting ipforwarding on that
machine to 0. It must be 1 for routers. On suns only, ipforwarding
has an additional valid value: -1 means that no matter how many
interfaces the machine has, no routing will be done (the presence of
this additional value is why ipforwarding is not considered to be a
boolean). A value of 0 means that the value should be set to 1 if a
second network interface is ifconfig'ed up. For the purposes of this
program, unless you run netconfig before ifconfig, either in your
/etc/rc.* files or by hand, the meaning is that a value of 1 indicates
routing is on, and anything else indicates routing is off. This is
subtly different, but enough to force me to stop calling ipforwarding
a boolean. Ipsendredirects controls whether a host should send an
ICMP redirect when it receives a datagram that it forwarded to a
different router on the same subnet as the subnet it came in on; in
effect the redirect tells the host that sent the datagram to update
its routing table to send directly to the router to which the datagram
was forwarded in the future. This can act, in effect, as a kind of
cheap routing protocol, and usually at worst acts to reduce the
severity of certain kinds of mistakes made by network administrators.
It should probably be set Ipgateway's functionality depends upon the
host operating system. Under OSF/1, it acts as an alternative to
ipforwarding, with the addition that statistics on traffic between
interfaces are kept, and arp tables are enlarged if this is set at
boot time. Under Ultrix, it determines whether a non-routing host
should send an ICMP Network Unreachable message when it receives an IP
packet not destined for itself (e.g., to be routed). It is unclear
what ipgateway is supposed to do. CHECKSUMMING ON/OFF - UDP_CKSUM,
TCP_CKSUM, AND NOCKSUM Udp_cksum controls whether UDP packets sent by
the host checksum their data or not. Some vendors ship machines with
udp_cksum turned off. That is because the checksumming data is
extremely time-consuming and one can improve NFS performance
noticeably by doing so. Turning off checksums results in a risk - if
- 4 - Formatted: January 15, 2025
NETCONFIG(1) NETCONFIG(1)
2 Aug 1993
packets are corrupted, one can end up with corrupted data. Since
almost all NFS is done over LANs with hardware checksum protection,
the risk is often worth the benefit. However, any NFS across a long
distance (mounting from a remote site, mounting an Internet archive
such as wuarchive, mounting across a SLIP link) carries a much larger
risk of data corruption. A host that participates as either client or
server in such transactions should probably have udp_cksum turned on.
If you are uncertain of whether your hosts often send "long-distance"
UDP packets, you should set udp_cksum 'on.' Tcp_cksum decides if a
host should checksum TCP packets that it receives. Many TCP
connections are over long distances, so by the reasoning of the last
paragraph this should almost always be 'on'. Nocksum decides if a
host should do any TCP/IP checksumming routine at all, for all
protocols. When this is set, the TCP/IP checksum routine returns zero
without actually examining any data. USE WITH CAUTION. Turning this
on has the effect of disabling networking with any machine that does
not also have this flag set. It also removes ALL of the checksum
protection described above, plus some not described in this document.
REDUNDANT CHECKSUM AVOIDANCE CONTROL - TCPLCLSUM AND UDPLCLSUM
Tcplclsum and udplclsum control whether checksum redundancy avoidance
it is used, if it is available in your kernel. Checksum redundancy
avoidance is software that avoids the need for the udp_cksum flag
above - it detects whether packet transmissions are local or remote
and avoids performing data checksums only on packets that cross a
single LAN. One can tell if one has checksum redundancy avoidance by
checking to see if tcplclsum and udplclsum appear in the list of
variables that appears when one runs netconfig with no arguments. For
most environments, they should be 'off', which turns checksum
redundancy avoidance on. If your application requires reliability
higher than is normally found in a workstation environment, you should
set them to 'on'. KEEPALIVES - TCP_KEEPIDLE, TCP_KEEPLEN,
TCP_KEEPINTVL Tcp_keepidle, tcp_keeplen, and tcp_keepintvl control the
TCP keepalive option. The keepalive mechanism times out connections
on which keepalives are on and no packet has been seen for some time.
A connection with keepalives on that has not seen any packets for
tcp_keepidle half-seconds starts sending a packet every tcp_keepidle
half-seconds. That has the effect of telling the remote TCP that the
connection is still alive. In addition, the remote TCP must send an
acknowledgement, telling the local host that the connection is still
alive. If the sender sends eight keepalive packets without a
response, TCP will conclude that the remote host is either unreachable
or crashed and close the connection. Tcp_keeplen controls how much
data to include in a keepalive. Data sent in a keepalive is carefully
chosen so that the receiving TCP must throw out the data but still
acknowledge the packet, so that no extraneous data appears to user
programs. A single byte of data is usual, because it suffices and
some implementations ignore zero-length packets. I recommend the
following (usual) settings:
tcp_keepidle 14400
tcp_keepintvl 150
tcp_keeplen 1
- 5 - Formatted: January 15, 2025
NETCONFIG(1) NETCONFIG(1)
2 Aug 1993
TIME TO LIVE - UDP_TTL, TCP_TTL, MAXTTL The internet time to live
(TTL) governs how many IP routers a packet travels through before
being discarded. If this value is set low, packets may not be
able to travel from your host to all areas of the Internet. The
IETF currently recommends a value of 64 for this. In general
operational experience, 20 intermediate routers seems to be
typical for crossing the US, 30 a current upper limit on numbers
of hops needed to reach remote international locations, so 64
permits continued growth for a while. It is unclear to me why
this parameter is not just set to its potential max of 255 - the
only drawback to setting the parameter high is that it takes
longer to discard packets caught in router loops. The difference
is unlikely to be annoying, much less a problem, unless the
router loop is made up of SLIP links. Each of the *_ttl
parameters determines the default max ttl for a different kind of
packet. Tcp_ttl determines the default TTL for TCP packets,
udp_ttl determines the default TTL for UDP packets, and maxttl,
despite its name, only determines the TTL for ICMP packets.
SEE ALSO
adb(1), dbx(1), (DECstation and SGI only) kvar(8), traceroute(1) R.
Stevens, TCP/IP Illustrated, Volume 1. J. Postel, "Transmission
Control Protocol," Internet Request for Comments 793. R. Braden, J.
Postel, "Requirements for Internet Gateways," Internet Request for
Comments 1009. R. Braden, "Requirements for Internet Hosts --
Communication Layers," Internet Request for Comments 1122. D. Borman,
R. Braden, V. Jacobson, "TCP Extensions for High Performance,"
Internet Request for Comments 1323. S. J. Leffler, M. K. Mckusick, M.
J. Karels, J. S. Quarterman, "Interprocess Communication," The Design
and Implementation of the 4.3BSD UNIX Operating System, Addison-
Wesley, Nov. 1989. Compressed SLIP distribution, available from
ftp.ee.lbl.gov. Fastnet (incl. checksum redundancy avoidance)
distribution, available from ucsd.edu:pub/csl/fastnet.
AUTHOR
Jon Kay (jkay@ucsd.edu) of the Computer Systems Lab at the University
of California, San Diego.
ACKNOWLEDGEMENTS
I gratefully acknowledge help from Kim Claffy, of the University of
California, San Diego Computer Systems Lab (kc@cs.ucsd.edu) with the
documentation.
BUGS
It doesn't work on Solaris 2.3 or Linux. I can't do anything about
Linux because it doesn't have appropriate variables - every such thing
MUST be configured at kernel build time. Solaris is a different
matter - the problems there are that the variables are stored in
loadable kernel modules which netconfig doesn't know how to deal with,
and that the variable names are different from BSD. The netconfig
software distribution should be a distribution of a general kernel
- 6 - Formatted: January 15, 2025
NETCONFIG(1) NETCONFIG(1)
2 Aug 1993
variable access program. Netconfig's functionality would be
implemented as a script on top of the more general program. Though
it'd have be be VERY talented to also work on Solaris. Netconfig
attempts to track a moving target, and the author will probably
require external assistance to track new network configuration kernel
variables (hint!).
- 7 - Formatted: January 15, 2025
