OpenBSD FAQ - System Management [FAQ Index]



Security Updates

When a critical bug is found, the fix will be committed to the -current tree (and made available in snapshot builds) as soon as possible. It will then be backported to the two most recent OpenBSD releases in the form of errata and details will be sent to the announce mailing list.

Getting these fixes can be done in a few different ways:

Security fixes for third party software installed via packages are normally only backported to the most recent release. To obtain them, do one of the following: To be alerted of port updates, consider following the ports-changes mailing list.

System Daemons

System daemons (or "services") are started, stopped and controlled by the rc(8) script via rc.d(8).

Most daemons and services that come with OpenBSD are controlled on boot by variables defined in /etc/rc.conf. You'll see lines similar to this:

httpd_flags=NO
This shows that httpd(8) is not to be started from rc(8) at boot time. Each line has a comment showing you the flags for common usage of that daemon or service.

Do not alter rc.conf(8) directly. Instead, use the rcctl(8) utility to maintain the /etc/rc.conf.local file. This makes future upgrades easier as all the changes are in the one file that isn't touched during upgrade.

For example, to start the apmd(8) daemon for CPU scaling, one might do:

# rcctl enable apmd
# rcctl set apmd flags -A
# rcctl start apmd

Executing Commands as Another User

The doas(1) tool lets a system administrator permit certain users to run specific commands as another user. Regular users can run administrative commands, only being required to authenticate as themselves, without the need for the root password.

For example, if appropriately configured, the following command would display root's crontab(5) file:

$ doas -u root crontab -l
Commands invoked by doas(1) are logged to /var/log/secure by default. Check the doas.conf(5) manual for configuration examples.

Editing the Password File

OpenBSD's main password file is located at /etc/master.passwd and is only readable by root. The pwd_mkdb(8) tool generates the world-readable /etc/passwd and the password databases (/etc/pwd.db and /etc/spwd.db) from the main file. The format is described in passwd(5).

Always use vipw(8) to edit the password file. After you are done editing, it will first sanity check the changes, then recreate /etc/passwd and the password databases, and finally install the copy in place of the original /etc/master.passwd file.

Resetting the Root Password

If the root password was forgotten, the basic process to regain access is to boot into single user mode, mount the / and /usr partitions, and run passwd(1) to change the root password.

Clock Syncing

OpenNTPD is a safe and simple NTP-compatible way to have accurate time on your computer. The ntpd(8) daemon is enabled by default and will set the clock based on data received from NTP peers. Once the clock is accurately set, it will be held at a high degree of accuracy using the configured time servers specified in ntpd.conf(5). At boot, ntpd will only jump the clock forward. If your clock has to be moved backward, manually set the clock using date(1).

To use OpenNTPD as a server, add a listen on * line to ntpd.conf(5) file and restart the daemon. You can also instruct it to only listen on a specific address or interface.

When you have ntpd(8) listening, other machines may not be able to synchronize their clocks right away. This is because time information won't be served until the local clock is synced with a reasonable level of stability. Once this level is reached, a "clock is now synced" message will appear in /var/log/daemon.

Time Zones

By default OpenBSD assumes your hardware clock is set to Coordinated Universal Time (UTC) rather than local time. This can cause problems when multibooting. Many other operating systems can be configured to do the same, which avoids this problem altogether.

If having the hardware clock set to UTC is a problem, you can change the default behavior of OpenBSD via sysctl.conf(5). For example, put the following in /etc/sysctl.conf to configure OpenBSD to use a hardware clock set to US Eastern Standard Time (5 hours behind UTC, so minus 300 minutes):

kern.utc_offset=-300
See sysctl(2) for more information.

Note that the hardware clock must already be running at the desired offset before booting OpenBSD with the above configuration or the system time will be incorrectly adjusted at boot.

Normally, the time zone is set during install. If you have need to change the time zone, you can create a new symbolic link to the appropriate time zone file in /usr/share/zoneinfo. For example, to set the machine to use EST5EDT as the new local time zone:

# ln -fs /usr/share/zoneinfo/EST5EDT /etc/localtime
Also see the date(1) manual.

Character Sets and Localization

The OpenBSD base system fully supports the ASCII character set and encoding, and partially supports the UTF-8 encoding of the Unicode character set. No other encodings or character sets are supported by the base system, but ports can be used to handle them. The level of UTF-8 support and the default encoding configuration vary greatly with the program or library.

To use the Unicode character set in UTF-8 encoding wherever supported, set the LC_CTYPE environment variable to the value en_US.UTF-8:

When logging into remote systems with ssh(1), the LC_CTYPE environment variable is not propagated, and you have to make sure that the local terminal is set to the character encoding used by the remote server before connecting. If that encoding is unknown or unsupported by OpenBSD, make sure you use the default xterm(1) configuration and set LC_CTYPE=en_US.UTF-8 in the remote shell after connecting.

The OpenBSD base system completely ignores all locale-related environment variables except LC_CTYPE; even LC_ALL and LANG only affect the character encoding. Some ports may respect other LC_* variables, but using them or setting LC_CTYPE to any value other than C, POSIX or en_US.UTF-8 is not recommended.

Symmetric Multithreading, or "Why are only half of my CPUs used?"

Some CPUs use Symmetric Multithreading (SMT; Intel's implementation is known as "Hyper-Threading"). In this case, one physical processor presents an extra logical processor to the OS - shown as a separate CPU in dmesg(8) and tools like top(1). These do not have full CPU resources but are there to allow sharing part of a single core's resources with more than one concurrent process.

This feature can improve performance for some workloads but reduces it for others.

SMT has been involved in various CPU vulnerabilities, in particular relating to speculative execution. This can result in processes learning information about other processes which they should not have access to. To mitigate this, OpenBSD disables running code on detected SMT "virtual" cores by default.

They can be reenabled by setting the sysctl hw.smt to 1, however doing so is generally not recommended.

Using S/Key

S/Key is a "one-time password" authentication system. It generates a sequence of one-time (single use) passwords from a user's secret passphrase along with a challenge received from the server, by means of a hash function: md5, sha1 or rmd160.
WARNING: One-time password systems only protect authentication information. They do not prevent network eavesdroppers from gaining access to private information. Furthermore, if you are accessing a secure system A, it is recommended that you do this from another trusted system B, to ensure nobody is gaining access to system A by logging your keystrokes or by capturing and/or forging input and output on your terminal devices.

Setting Up S/Key

To start off, the directory /etc/skey must exist. If this directory doesn't exist, have the superuser create it by doing:
# skeyinit -E
Then use skeyinit(1) to initialize your S/Key. You will first be prompted for your login password, then you will be asked for your S/Key secret passphrase, which must be at least 10 characters long:
$ skeyinit
Password:
[Adding ericj with md5]
Enter new secret passphrase:
Again secret passphrase:

ID ericj skey is otp-md5 100 oshi45820
Next login password: HAUL BUS JAKE DING HOT HOG
Notice the information in the last two lines. The program used to create your S/Key password is otp-md5(1), the sequence number is 100 and the secret key is oshi45820. The six small words HAUL BUS JAKE DING HOT HOG constitute the S/Key password with sequence number 100.

Generating S/Key Passwords

To generate the S/Key password for the next login, use skeyinfo(1) to find out what command to run:
$ skeyinfo -v
otp-md5 95 oshi45820
$ otp-md5 95 oshi45820
Enter secret passphrase:
NOOK CHUB HOYT SAC DOLE FUME
In order to generate a list of S/Key passwords, do:
$ otp-md5 -n 5 95 oshi45820
Enter secret passphrase:
91: SHIM SET LEST HANS SMUG BOOT
92: SUE ARTY YAW SEED KURD BAND
93: JOEY SOOT PHI KYLE CURT REEK
94: WIRE BOGY MESS JUDE RUNT ADD
95: NOOK CHUB HOYT SAC DOLE FUME

Using S/Key to Log In

Here is an example session using S/Key to log in to an ftp server on localhost. To perform an S/Key login, you append :skey to your login name.
$ ftp localhost
Connected to localhost.
220 oshibana.shin.ms FTP server (Version 6.5/OpenBSD) ready.
Name (localhost:ericj): ericj:skey
331- otp-md5 93 oshi45820
331 S/Key Password: JOEY SOOT PHI KYLE CURT REEK
[...]
230 User ericj logged in.
Remote system type is UNIX.
Using binary mode to transfer files.
ftp> quit
221 Goodbye.
Similarly, for ssh(1):
$ ssh -l ericj:skey localhost
otp-md5 91 oshi45821
S/Key Password: SHIM SET LEST HANS SMUG BOOT
Last login: Thu Apr  7 12:21:48 on ttyp1 from 156.63.248.77
$

Directory Services

OpenBSD can be used for both servers and clients of databases containing user credentials, group information and other network-related data.

Of course, you could use various directory services on OpenBSD. But YP is the only one that can be accessed directly using standard C-library functions like getpwent(3), getgrent(3), gethostbyname(3) and so on. Thus, if you keep your data in a YP database, you do not need to copy it to local configuration files like master.passwd(5) before you can use it, for example to authenticate system users.

YP is a directory service compatible with Sun Microsystems NIS (Network Information System). See yp(8) for an overview of the available manual pages. Be careful, some operating systems contain directory services bearing similar names but all the same being incompatible, for example NIS+.

To use directory services other than YP, you either need to populate local configuration files from the directory, or you need a YP frontend to the directory. For example, you can use the sysutils/login_ldap port when you choose the former, while the ypldap(8) daemon provides the latter.

For some applications, simply synchronizing a small number of configuration files among a group of machines using tools like rdist(1), cron(8), scp(1) or rsync (available from ports) constitutes an easy and robust alternative to a full-blown directory service.

YP Security Considerations

For compatibility reasons, all security features built into the OpenBSD implementation of YP are switched off by default. Even when they are all switched on, the NIS protocol is still inherently insecure for two reasons: All data, including sensitive data like password hashes, is transmitted unencrypted across the network, and neither the client nor the server can reliably verify each other's identity.

Thus, before setting up any YP server, you should consider whether these inherent security flaws are acceptable in your context. In particular, YP is inadequate if potential attackers have physical access to your network. Anybody gaining root access to any computer connected to your network segments carrying YP traffic can bind your YP domain and retrieve its data. In some cases, passing YP traffic through SSL or IPsec tunnels might be an option.

Setting Up a YP Server

A YP server serves a group of clients called a "domain." You should first select a domain name; it can be an arbitrary string and need not be related in any way to DNS domain names. Choosing a random name like "Eepoo5vi" can marginally improve security, though the effect is mostly in security by obscurity. In case you need to maintain several distinct YP domains, it's probably better to choose descriptive names like "sales," "marketing" and "research" in order to forestall system administration errors caused by obscurity. Also note that some versions of SunOS require using the host's DNS domain name, so your choice might be restricted in a network including such hosts.

Use the domainname(1) utility to set the domain name, and put it into the defaultdomain(5) file to have it automatically set at system startup time.

# echo "puffynet" > /etc/defaultdomain
# domainname `cat /etc/defaultdomain`
Initialize the YP server using the interactive command:
# ypinit -m
At this point, it is not necessary to specify slave servers yet. To add slave servers, you can rerun ypinit(8) later, using the -u option. Setting up at least one slave server for each domain is useful to avoid service interruptions. For example, should the master server ever go down or lose network connectivity, client processes trying to access YP maps block indefinitely until they receive the requested information. Thus, YP service interruptions typically render the client hosts completely unusable until YP is back to service.

Decide where to store the source files to generate your YP maps from. Keeping the server configuration separate from the served configuration helps to control which information will be served and which won't, so the default /etc often isn't the best choice.

The only inconvenience caused by changing the source directory is that you will not be able to add, remove and modify users and groups in the YP domain using utilities like user(8) and group(8). Instead, you will have to edit the configuration files with a text editor.

To define the source directory, edit the file /var/yp/`domainname`/Makefile and change the DIR variable, e.g.

DIR=/etc/yp/src/puffynet
Consider customizing other variables in /var/yp/`domainname`/Makefile. See Makefile.yp(8) for details.

For example, even in case you use the default source directory /etc, you do not usually need all accounts and groups existing on the server on all your client hosts. In particular, not serving the root account and thus keeping root's password hash confidential is often beneficial to security. Review the values of MINUID, MAXUID, MINGID and MAXGID and adjust them to you needs.

If all your YP clients run OpenBSD or FreeBSD, exclude the encrypted passwords from the passwd maps by setting UNSECURE="" in /var/yp/`domainname`/Makefile.

The former practice of editing the template file /var/yp/Makefile.yp is no longer recommended. Changes to that file affect all domains initialized after the change, but do not affect domains initialized before the change, so this is error-prone either way: You both risk that the intended changes do not take effect, and you risk to forget about them and have them affect other domains later which they were never intended for.

Create the source directory and populate it with the configuration files you need. See Makefile.yp(8) to learn which YP maps require which source files. For the format of the individual configuration files, refer to passwd(5), group(5), hosts(5) and so on, and look at the examples in /etc.

Create the initial version of your YP maps using the commands

# cd /var/yp
# make
Do not worry about error messages from yppush(8) right now. The YP server is not yet running.

YP uses rpc(3) (remote procedure calls) to communicate with clients, so it is necessary to enable portmap(8). To do so, use rcctl(8).

# rcctl enable portmap
# rcctl start portmap
Consider using either the securenet(5) or the ypserv.acl(5) security feature of the YP server daemon. But be aware that both of these only provide IP based access control. Thus, they only help as long as potential attackers have neither physical access to the hardware of the network segments carrying your YP traffic nor root access to any host connected to those network segments.

Finally, start the YP server daemon:

# rcctl enable ypserv
# rcctl start ypserv
To test the new server, consider making it its own client, following the instructions in the first part of the next section. In case you don't want the server to use its own maps, you can disable the client part after the test with the following commands:
# rcctl stop ypbind
# rcctl disable ypbind
Remember that each time you change a file sourced by a YP map, you must regenerate your YP maps.
# cd /var/yp
# make
This updates all database files in /var/yp/`domainname`, with one exception: The file ypservers.db, listing all YP master and slave servers associated with the domain, is created directly from ypinit -m and modified exclusively by ypinit -u. In case you accidentally delete it, run ypinit -u to recreate it from scratch.

Setting Up a YP Client

Setting up a YP client involves two distinct parts. First, you must get the YP client daemon running, binding your client host to a YP server. Completing the following steps will allow you to retrieve data from the YP server, but that data will not yet be used by the system:

Like on the server, you must set the domain name and enable the portmapper:

# echo "puffynet" > /etc/defaultdomain
# domainname `cat /etc/defaultdomain`
# rcctl enable portmap
# rcctl start portmap
It is recommended to provide a list of YP servers in the configuration file /etc/yp/`domainname`. Otherwise, the YP client daemon will use network broadcasts to find YP servers for its domain. Explicitly specifying the servers is both more robust and marginally less open to attack. If you have not set up any slave servers, just put the host name of the master server into /etc/yp/`domainname`.

Enable and start the YP client daemon, ypbind(8).

# rcctl enable ypbind
# rcctl start ypbind
If all went well you should be able to query the YP server using ypcat(1) and see your passwd map returned.
# ypcat passwd
bob:*:5001:5000:Bob Nuggets:/home/bob:/usr/local/bin/zsh
...
Another useful tool for debugging your YP setup is ypmatch(1).

The second part of configuring a YP client involves editing local configuration files such that certain YP maps get used by various system facilities. Not all servers serve all standard maps supported by the operating system, some servers serve additional non-standard maps, and you are by no means compelled to use all those maps. Which of the available maps shall or shall not be used, and for which purposes they shall be used, is fully at the discretion of the client host's system administrator.

For a list of standard YP maps and their standard usage, see Makefile.yp(8).

If you want to include all user accounts from the YP domain, append the default YP marker to the master password file and rebuild the password database:

# echo '+:*::::::::' >> /etc/master.passwd
# pwd_mkdb -p /etc/master.passwd
For details on selective inclusion and exclusion of user accounts, see passwd(5). To test whether inclusion actually works, use the id(1) utility.

If you want to include all groups from the YP domain, append the default YP marker to the group file:

# echo '+:*::' >> /etc/group
For details on selective group inclusion, see group(5).