System Configuration

Synopsis #

System configuration in OpenBSD relies on a small set of well-defined utilities and text files located in /etc. Settings can be applied at runtime using tools like sysctl, wsconsctl, and rcctl, or persisted across reboots in files such as /etc/sysctl.conf, /etc/wsconsctl.conf, and /etc/rc.conf.local. In addition, system maintenance includes managing service behavior, login environment limits, bootloader parameters, root mail notifications, and scheduled updates.

Kernel Parameters with sysctl #

The sysctl utility displays and modifies kernel state variables. These variables control aspects such as networking, security, hardware behavior, memory limits, and process constraints.

To display all values:

sysctl

To read or set a single value:

sysctl hw.smt
doas sysctl hw.smt=0

Save only the settings the host needs in /etc/sysctl.conf. These are examples, not a list to apply in full; enable forwarding only on a router:

hw.smt=0
net.inet.ip.forwarding=1
kern.maxfiles=16384
net.inet.tcp.recvspace=65536
net.inet.tcp.sendspace=65536
kern.nosuidcoredump=1
vm.swapencrypt.enable=1

Common Examples #

  • hw.smt=0 — Disable hyperthreading (SMT), often recommended for security.
  • net.inet.ip.forwarding=1 — Enable IP packet forwarding for routing.
  • kern.maxfiles — Increase the number of open file descriptors.
  • vm.swapencrypt.enable=1 — Encrypt data swapped to disk.
  • kern.nosuidcoredump=1 — Prevent core dumps for set-user-ID binaries.

Changes to /etc/sysctl.conf are applied at boot by the system startup scripts.

Console Input and Display with wsconsctl #

The wsconsctl utility modifies the behavior of the console keyboard and display. Settings can be applied at runtime or saved in /etc/wsconsctl.conf for persistence.

Keyboard Layout and Behavior #

To adjust the keyboard layout:

doas wsconsctl keyboard.layout=us

Other settings include:

doas wsconsctl keyboard.bell.volume=0
doas wsconsctl keyboard.repeat.del1=400
doas wsconsctl keyboard.repeat.deln=40

To keep keyboard settings after reboot, add them to /etc/wsconsctl.conf:

keyboard.layout=us
keyboard.bell.volume=0
keyboard.repeat.del1=400
keyboard.repeat.deln=40

Console Font Configuration #

wsfontload(8) loads bitmap fonts when the display driver supports it. List available loaded fonts with:

doas wsfontload -l

The manual’s VGA example loads an 8-pixel-high IBM-encoded font:

doas wsfontload -N myname -h 8 -e ibm /usr/share/misc/pcvtfonts/vt220l.808

Select a supported font through wsconsctl display.font. Font availability and usable dimensions depend on the console driver. wsfontload -f selects a control device, not a font file; the font filename is the final operand. Test console changes before adding them to /etc/rc.local.

Managing Services with rcctl #

OpenBSD uses rcctl to enable, disable, and control services. These services are defined under /etc/rc.d/.

To enable a service at boot:

doas rcctl enable ntpd

To start a service immediately:

doas rcctl start ntpd

To check its status:

doas rcctl check ntpd

To disable a service:

doas rcctl disable ntpd

To restart a service:

doas rcctl restart ntpd

To set runtime flags for a service:

doas rcctl enable ntpd
doas rcctl set ntpd flags -v

These settings are saved in /etc/rc.conf.local and used on the next service start or restart. The example enables verbose logging; inspect existing flags before replacing them.

Persistent System Configuration Files #

System behavior is primarily defined by configuration files in /etc. Below is a summary of key files:

  • /etc/rc.conf — Default system settings (do not edit)
  • /etc/rc.conf.local — Local overrides for services and variables
  • /etc/hostname.if — Interface configuration (e.g., hostname.em0)
  • /etc/myname — System hostname
  • /etc/mygate — Default route (gateway)
  • /etc/resolv.conf — DNS resolver configuration
  • /etc/fstab — Filesystem mounting configuration
  • /etc/doas.conf — Permissions for privilege elevation
  • /etc/login.conf — User login classes and limits
  • /etc/sysctl.conf — Kernel parameters
  • /etc/wsconsctl.conf — Console and keyboard settings
  • /etc/ttys — Terminal and console definitions
  • /etc/mail/aliases — Email aliasing, including for root
  • /etc/rc.local — Startup commands

Editing User and Group Databases #

To safely edit the password and user database:

doas vipw

This ensures updates are atomic and that related shadow files are kept in sync. For group modifications, edit /etc/group directly with a text editor.

Using /etc/examples #

When installing or enabling new components, configuration templates are often found in /etc/examples. For example:

doas cp /etc/examples/ntpd.conf /etc/ntpd.conf

These defaults are maintained by the system and are safe to copy and customize.

Login Classes and Resource Limits #

The /etc/login.conf file defines environment and resource limits for user classes. Each user is associated with a class (e.g., default, staff, daemon).

Example definition:

staff:\
  :openfiles-cur=1024:\
  :stacksize-cur=8M:\
  :tc=default:

After editing the file, rebuild the capability database:

doas cap_mkdb /etc/login.conf

Changes take effect at the next login.

Bootloader Configuration #

Bootloader behavior is controlled through /etc/boot.conf. This file can contain commands that are automatically passed to the bootloader during early system startup.

Example configuration:

set timeout 5
set image /bsd

This sets a 5-second delay and instructs the loader to boot /bsd. At boot time, users may interrupt the countdown and issue commands manually. Refer to boot(8) for boot prompt syntax.

Root Mail and Internal Notifications #

OpenBSD uses local mail delivery to notify administrators about system events. Sources of mail include:

  • cron(8) job output
  • daily(8), weekly(8), and monthly(8) reports
  • Errors or messages from system daemons

To view root’s mail:

doas mail

To forward root’s mail to an external address, edit /etc/mail/aliases:

root: admin@example.com

Then run:

doas newaliases

Mail is stored in /var/mail/root.

Alternate Root Partition (/altroot) #

The daily maintenance script can copy the root partition to a designated /altroot partition. It requires ROOTBACKUP=1 in /etc/daily.local, an existing /altroot directory, and an fstab entry with type ffs and options xx. The destination remains unmounted during the copy and must be large enough for the source.

This is a partition-image copy, not a directory in which to store a dump archive. Follow Back Up and Restore an OpenBSD System for setup and independent backups.

Scheduling Automatic Updates #

Periodic checks can report available security patches without installing them. One way to do this is to add commands to /etc/daily.local, which is run by the daily script.

Example:

File: /etc/daily.local

#!/bin/sh
syspatch -c

The daily script sources this file; an exit command would terminate the remaining daily maintenance. Keep it owned by root and not writable by other users. Execute permissions are not required. This example checks for patches; installation remains a separate maintenance action.

System scripts also generate logs in /var/log/:

  • /var/log/daily.out
  • /var/log/weekly.out
  • /var/log/monthly.out

These logs are emailed to root. Ensure they are reviewed regularly or redirected.

Report a bug