Sysctl(8)

Sysctl(8)

The OpenBSD kernel, like every BSD-based kernel, includes a variety of tunable parameters. These parameters are known as system controls, or sysctls. Some sysctls are static and can be viewed but not changed. Others can be changed by the sysadmin. Sysctls are a powerful feature; they will allow a systems administrator to solve problems or change system behavior without reconfiguring applications or recompiling the kernel. Developers like sysctls, as they allow programs to easily grab current information out of a running kernel. Changing the way a system behaves can impair programs or annoy users, however, so you need to know what you're doing before changing sysctls.

You can view sysctl values, and change those values that can be changed, with the sysctl(8) program. Throughout this book, I'll be mentioning sysctl values and how they affect system behavior. You should have a good general understanding of what sysctls are before changing them, however.

Sysctl Values

Sysctls are arranged in a Management Information Base, or MIB, tree. An MIB tree organizes information into categories and then divides each category into sub-categories. For example, the main categories in the OpenBSD sysctl MIB tree include categories such as kern (kernel), vm (virtual memory), net (networking), and so on. The net category includes sub-categories such as inet (IPv4 networking) and inet6 (IPv6 networking). The inet category includes subbranches for TCP and UDP, and so on. Each "last" category includes a variety of individual values that can be read or, possibly, tweaked. So, a typical single MIB might be something like this.

net.inet.tcp.rfc1323

This MIB is part of the network stack. It represents the IPv4 section of the network stack and specifically the TCP section. It represents support for RFC1323, or a certain type of TCP extensions. How do I know this? Well, understanding these off the top of your head requires a certain amount of UNIX and/ or networking experience. OpenBSD expects that you'll be able to figure out the meaning of some sysctl values, such as this one, by reading them. Others are much more obtuse, but are well documented in man pages.

So, if you want to explore sysctls, the next step is to get a list of them from your computer.

Viewing Available Sysctls

Before trying to change any sysctl options, take a look at the sysctls available on your system. The sysctls in a kernel depend on that kernel's configuration. We're going to assume here that you're using the GENERIC kernel shipped with your release of OpenBSD. You don't need to be root to view sysctls.

Some sysctls contain information that's coded in a particular format that isn't particularly easy to view. For the moment, we'll set those sysctls aside and only consider the ones that are most easily read. The following command will print all the readable sysctls available in your kernel and save the output to the file sysctl.out for easy viewing later:

# sysctl -a > sysctl.out

Take a look at the resulting sysctl.out file. Some sysctl values at the top of the list have pretty obvious meanings. Here are the first four from an OpenBSD 3.1 system:

kern.ostype = OpenBSD
kern.osrelease = 3.1
kern.osrevision = 200206
kern.version = OpenBSD 3.1 (GENERIC) #59: Sat Apr 13 15:28:52 MDT 2002
    deraadt@i386.openbsd.org:/usr/src/sys/arch/i386/compile/GENERIC

kern.* sysctls concern the kernel itself. Here we see some basic information about the kernel. The kern.ostype and kern.osrelease sysctls are fairly obvious. Why would an OpenBSD system have a sysctl to report the operating system, though? Shouldn't you know that already? Well, the sysctl interface can be found on any BSD-based operating system, and checking the value of this sysctl is a good way for programs to identify the operating system that they're running on. Kern.osrevision might make you wonder for a moment, but it's actually just the date when this particular version was released — June of 2002. Finally, the kern.version sysctl gives the exact version of the booted kernel and its compile date and location. Pretty darn easy, no? So, let's look at the next few.

kern.maxvnodes = 1310
kern.maxproc = 532
kern.maxfiles = 1772
kern.argmax = 262144
kern.securelevel = 1

Yuck! What the heck is all this? If you're an experienced sysadmin, you could make a real good guess about what something like "maxvnodes" means. New users probably have no clue. If you run "apropos vnode" you'll get a whole list of possible matches, however, and vnode(9) will look like a good place to start. Similarly, a bit of web and manual page searching as discussed in Chapter 1 will lead you to the definitions of the others.

When you know the name of a sysctl and you simply want to view the current value of that sysctl, give the sysctl name as an argument to sysctl(8). For example, to view the system's current securelevel (see Chapter 10), check the value of the kern.securelevel sysctl.

# sysctl kern.securelevel
kern.securelevel = 1
#

The current value of kern.securelevel is 1.

You can go somewhere in between the two and view all the portions of the sysctl tree under a certain category. For example, the net category covers all network-related sysctls, net.inet covers all IPv4 networking sysctls, and net.inet.udp covers the sysctls specific to UDP networking. To view everything in that section of the sysctl tree, just give the category name as an argument to sysctl.

# sysctl net.inet.udp
net.inet.udp.checksum = 1
net.inet.udp.baddynamic = 587,749
net.inet.udp.recvspace = 41600
net.inet.udp.sendspace = 9216
#

OpenBSD provides four sysctls for UDP networking. You can view any portion of the sysctl tree in this way, going as many categories deep as you like.

Changing Sysctl Values

Some sysctls are read-only. For example, the hw.ncpu sysctl shows how many processors are in the computer.

# sysctl hw.ncpu
hw.ncpu = 1
#

This system has one CPU. (Because OpenBSD currently only addresses one processor on multi-processor systems, this isn't such a great surprise.) Programs can use these sysctls to get operational information to make decisions on how they should run.

On the other hand, a system kernel can decide whether or not to forward packets. Packet forwarding is when a computer receives network packets on one network card and sends them out on another. Firewalls (Chapter 17) and routers typically forward packets. The net.inet.ip.forwarding sysctl controls this feature in OpenBSD. If this sysctl is set to 0, packets are not forwarded. If you set this to 1, packets can be routed through the system.

# sysctl net.inet.ip.forwarding
net.inet.ip.forwarding = 0
#

To change this, use sysctl's "-w" flag and the desired value.

# sysctl -w net.inet.ip.forwarding=1
net.inet.ip.forwarding: 0 -> 1
#

If you wanted to perform some network maintenance and stop forwarding packets temporarily, you could turn this back to 0 to turn off packet forwarding. This will annoy your users to no end, but if you're running the firewall I hope you know that already.

Note�

In simple on-off (or boolean) sysctls, 0 means "off" and 1 means "on." Many sysctls are not of the on/off variety, instead having a range of valid numeric values, so you cannot assume that a sysctl with a value of 1 or 0 is boolean!

Setting Sysctls at Boot

Sysctl changes revert to their defaults when you reboot your computer. This probably isn't desired, in most cases. You can set sysctls at boot in two different ways: in /etc/sysctl.conf and /etc/rc.local.

Changes specified in /etc/sysctl.conf take place early in the booting process. This is when most kernel customizations should occur. If you customize your network stack, for example, you want changes to take place before the system opens any network connections! You can list any sysctls you want to change, an equal sign, and their desired value, in /etc/sysctl.conf.

By default, the /etc/sysctl.conf file contains a variety of commonly used sysctls. Each is commented out with a pound sign and is set to the most common non-default setting. If you want to change the particular behavior, all you do is uncomment the particular entry. Let's look at some of the particular entries in /etc/sysctl.conf. (You may well have different entries in your system, depending on the version of OpenBSD you are running.)

net.inet.ip.forwarding

This controls forwarding of IPv4 packets through the system. If this is set to 1, packets will be forwarded according to the internal routing table (see more about this in Chapter 8). If it is set to 0, packets will not be forwarded.

net.inet6.ip6.forwarding

This controls forwarding of IPv6 packets, much as net.inet.ip.forwarding does for IPv4 packets. While we won't go into IPv6 in this book, you should be aware that it's available and that it's managed separately.

net.inet.tcp.rfc1323

This controls use of RFC1323 TCP congestion control. It's enabled by default, as almost everything on the Internet uses RFC1323 congestion control today. RFC1323-compliant network devices can have slow network connections to non-RFC1323 devices. You might want to set this to 0 if you're having trouble communicating with older TCP/IP devices.

ddb.panic

OpenBSD uses the ddb kernel debugger. On those rare occasions when an OpenBSD system panics, it automatically drops the console into the debugger. If you just want the system to reboot upon a panic, set this to 0.

ddb.console

If set to 1, this sysctl allows you to enter the kernel debugger while at the console by hitting CTRL-ALT-ESCAPE. This option is mostly only of interest to developers and others actively debugging the kernel.

vm.swapencrypt.enable

This tells OpenBSD to encrypt all data written to the swap file. It's possible for malicious users or intruders to pull data out of a swap file. While this data is usually scrambled well by normal system activity, a persistent user might eventually learn something from it. If your system tends to swap, and if you have shell users who you don't trust, you might want to set this. Note that you'll need to unmount and remount your various swap partitions for this to take effect. The simplest way to do this is to reboot.

machdep.allowaperture

This allows programs to access the video driver. If you're running XFree86 version 3, the X server needs access to the standard VGA framebuffer and BIOS. You can get that by setting mach.allowaperture to 1. If you're running XFree86 version 4, you'll need access to the whole first megabyte of physical memory, which may cause a few security problems. You can get that access by setting machdep.allowaperture to 2.

machdep.kbdreset

When it is set, you can shut down the computer correctly by pressing CTRL-ALT-DELETE. If you leave this unset (the default), pressing CTRL-ALT-DELETE will have no effect on the system.

Table Sysctls

So far, all of the sysctl values we've looked at have been fairly normal alphanumeric values. Not all sysctls have such friendly values, however. Many are tables, meaning that they can only be viewed with a special tool. (OpenBSD includes these tools, of course.) The sysctl program will allow you to view all sysctls, including the tabular ones, by using the "-A" flag. (There is no flag to specify just the tabular sysctls, but that would not be useful anywhere except for this example right now.)

# sysctl -A > sysctl-A.out

Look through this file, and you'll see an occasional line with additional information or instructions. For example, in the section of hardware sysctls we see the following snippet.

sysctl: use vmstat to view hw.diskstats information

There's a sysctl hw.diskstats, containing information only visible via vmstat(8). Each tabular sysctl in the output will give similar instructions, telling you how to access the information.

As you can probably guess, tabular sysctls are read-only (at least via sysctl(8)).