User:Paul/sandbox/OpenBSD Basic Server

OpenBSD has earned its reputation as a BSD descendant focused on security. With the increased development of OpenBSD's httpd and OpenSMTPD, plus most of the components commonly used in a basic web server, OpenBSD provides a highly secure and efficient choice for building servers.

Finding online support for OpenBSD can be much more difficult when compared to Linux. While the OpenBSD project requires its man pages to be very complete, support beyond man pages such as tutorials or sample configurations can be much harder to find. This has largely been due to the project being targeted at use primarily by professional systems administrators.

This tutorial will establish a basic web server that includes a functioning mail server with local maildir accessed through mutt.

OpenBSD providers pre-compiled binary packages available by using the pkg_add. The pkg_info command can be used to provide information on a package. To search packages, navigate to the page for the installed version:

https://cdn.openbsd.org/pub/OpenBSD/6.8/packages/amd64/

For other versions of OpenBSD, navigate to the version's packages from https://cdn.openbsd.org/pub/OpenBSD/.

Initial configuration

The default configuration for OpenBSD is generally acceptable for the majority of users. However, some small changes are necessary to some configurations.

Run updates

On initial login, update OpenBSD and installed packages, then reboot:

servername# syspatch
Get/Verify syspatch66-020_vmm_pvc... 100% |*************|   178 KB    00:00    
Installing patch 020_vmm_pvclock
Get/Verify syspatch66-021_smtpd_e... 100% |*************|   317 KB    00:01    
Installing patch 021_smtpd_envelope
Relinking to create unique kernel... done; reboot to load the new kernel
Errata can be reviewed under /var/syspatch
servername# pkg_add -u
quirks-3.183 signed on 2020-03-08T21:21:46Z
pcre2-10.33->10.34: ok
Read shared items: ok
servername# reboot

Install nano

Log back into the server using the root account.

For users not familiar with vi or mg, it may be preferable to install a simple text editor, such as nano

servername# pkg_add nano
quirks-3.183 signed on 2020-03-08T21:21:46Z
nano-4.4: ok

Install curl

The curl command is used to transfer data to a server from almost any source, and is often very useful.

servername# pkg_add curl
quirks-3.440 signed on 2020-12-13T14:50:57Z
curl-7.72.0p0:nghttp2-1.41.0p1: ok
curl-7.72.0p0: ok

Install wget

The wget command is used to conveniently download files.

servername# pkg_add wget
quirks-3.440 signed on 2020-12-20T14:28:14Z
wget-1.20.3p3:libunistring-0.9.7: ok
wget-1.20.3p3:libidn2-2.3.0p0: ok
wget-1.20.3p3:bzip2-1.0.8: ok
wget-1.20.3p3:pcre2-10.35: ok
wget-1.20.3p3:libpsl-0.20.2p1: ok
wget-1.20.3p3: ok

Set up user account

servername# adduser

This will generate adduser.conf for default new user configuration by asking several questions, followed the option to set up a new user. Default options are presented within brackets [] (e.g, [default]). Pressing Enter without typing anything will select the default option.

Couldn't find /etc/adduser.conf: creating a new adduser configuration file
Reading /etc/shells
Enter your default shell: csh ksh nologin sh [ksh]: 
Your default shell is: ksh -> /bin/ksh
Default login class: authpf bgpd daemon default pbuild staff unbound 
[default]: 
Enter your default HOME partition: [/home]: 
Copy dotfiles from: /etc/skel no [/etc/skel]: 
Send welcome message?: /path/file default no [no]: yes
Really? Type the filepath, 'default' or 'no' [no]: default
Message file ``/etc/adduser.message'' created
Prompt for passwords by default (y/n) [y]: 
Default encryption method for passwords: auto blowfish [auto]: 
Use option ``-silent'' if you don't want to see all warnings and questions.

Reading /etc/shells
Check /etc/master.passwd
Check /etc/group

Ok, let's go.
Don't worry about mistakes. There will be a chance later to correct any input.
Enter username []: username
Enter full name []: Full Username
Enter shell csh ksh nologin sh [ksh]: 
Uid [1000]: 
Login group username [username]: 
Login group is ``username''. Invite username into other groups: guest no 
[no]: wheel
Login class authpf bgpd daemon default pbuild staff unbound 
[default]: staff
Enter password []: 
Enter password again []: 

Name:           username
Password:       ****
Fullname:       Full Username
Uid:            1000
Gid:            1000 (username)
Groups:         username wheel
Login Class:    staff
HOME:           /home/username
Shell:          /bin/ksh
OK? (y/n) [y]:
Added user ``username''
Copy files from /etc/skel to /home/username
Send welcome message to ``username'' (y/n) [y]: 

Full Username,

your account ``username'' was created.
Have fun!

See also chpass(1), finger(1), passwd(1)

Add anything to the message (y/n) [n]: 
Copy message to another user?: no root second_mail_address 
[no]: 
Mail sent!
Add another user? (y/n) [y]: n
Goodbye!

The above configured username account is intended to be an administrator account for the server. Adding the wheel group applies several administrator level privilege configurations, as well as editing or reading privileges of otherwise protected system files and directories. Configuration as staff grants the account greater resource availability within OpenBSD.

Configure and enable doas

The OpenBSD sudo equivalent command is doas (as of 2015 - earlier documentation may refer to using sudo in OpenBSD), but is not configured by default.

There are many example configuration files located in /etc/examples/:

servername# ls /etc/examples/                                                   
acme-client.conf    ifstated.conf       ospfd.conf          ripd.conf
bgpd.conf           iked.conf           pf.conf             sasyncd.conf
chio.conf           inetd.conf          printcap            sensorsd.conf
dhclient.conf       ipsec.conf          rad.conf            snmpd.conf
dhcpd.conf          ldapd.conf          radiusd.conf        sysctl.conf
doas.conf           ldpd.conf           rbootd.conf         unwind.conf
dvmrpd.conf         man.conf            rc.local            vm.conf
eigrpd.conf         mixerctl.conf       rc.securelevel      wsconsctl.conf
exports             mrouted.conf        rc.shutdown         ypldap.conf
hostapd.conf        ntpd.conf           relayd.conf
httpd.conf          ospf6d.conf         remote

Copy the example doas.conf file into /etc/

servername# cp /etc/examples/doas.conf /etc/

Edit the configuration file:

servername# nano /etc/doas.conf

Change:

permit persist keepenv :wheel

By adding the configuration to /etc/, doas can now be invoked. The configuration file permits members of wheel to use doas and permitting persist means that each time doas is successfully invoked, a password will not be required when invoked again within five minutes.

Configure sshd

Permitting login through ssh with the root account or using passwords to log in are considered bad practice. The sshd configuration is managed through the sshd_config configuration file:

servername# nano /etc/ssh/sshd_config

Edit the following keyword line configurations to match the following:

PermitRootLogin no

PubkeyAuthentication yes

PasswordAuthentication no 

Restart sshd:

servername# rcctl restart sshd
sshd(ok)
sshd(ok)

Most security experts are recommending moving away from RSA keys. As configured, OpenBSD will work with RSA and ed25519 keys. In OpenSSH installations in most Linux distributions, both will be installed by default and ed25519 public keys are in the /home/username/.ssh/id_ed25519.pub file.

Add a public key to the configured user account authorized_keys file:

servername# nano /home/username/.ssh/authorized_keys

Updates and upgrades

The OpenBSD Project makes system updates, package updates, and system version upgrades very easy, as they view it as an important part to security. After all, if an upgrade is difficult or laborious, how likely are admins to install them?

Package updates

Package updates are relatively easy to install:

servername /home/username
$ doas pkg_add -u

System updates

Most versions of OpendBSD will have a dozen or so updates over the life of the version.

servername /home/username
$ doas syspatch

Some updates require a reboot, so it is important to note the messages output during the update.

System upgrade

Prior to performing a system upgrade, it is important to make sure all package and OS updates have been installed as per the preceding steps.

servername /home/username
$ doas sysupgrade

After the upgrade has completed and the server has rebooted, log in and perform the following:

servername /home/username
$ doas pkg_add -Uu
$ doas pkg_delete -a
$ doas sysmerge

Adding the -U option when running package update will update the dependencies, which can otherwise be a problem after system upgrades.

Running pkg_delete -a will delete unused dependencies, which are often present after upgrades.

The sysmerge command is used to update configuration files after an upgrade.

Customizations

OpenBSD uses the KornShell (ksh) and a few changes can be made to create custom command line entries, some of which borrow from other projects, such defaults found in Unbuntu, which uses GNU Bash (BASH).

ll (ls -alhF)

Ubuntu has a convenient command, ll, for viewing directory contents that is a shortcut for ls -alF.

To add ll to the OpenBSD command line:

$ nano .profile

Add the following line:

alias ll="ls -alhF"

The h option prints file sizes in human readable form (e.g., 1.2G).

Default editor

The default text editor in OpenBSD is vi. To change to a different default text editor, such as nano:

$ nano .profile

Add the following lines:

export EDITOR="$VISUAL"
export VISUAL=/usr/local/bin/nano

Do the same for root:

$ doas nano /root/.profile

Add the following lines:

export EDITOR="$VISUAL"
export VISUAL=/usr/local/bin/nano

Command prompt

The standard command prompt is somewhat intrusive when operating from nested and long directory names or using long commands while being sparse on information. A still easy to read but more informative prompt can be created with a small change to .profile:

$ nano .profile

Add the following:

PS1='servername $PWD\n$ '

At next login for the user, the command prompt should look like:

servername /home/username
$

Web server

OpenBSD has two components for serving websites: relayd and httpd.

Web server with relayd and httpd

Using relayd provides greater flexibility while adding only a little extra work in the initial setup.

Web server with only httpd

Most of the instructions in this article require root:

$ doas su

OpenBSD comes with httpd, the project's own web server, installed by default though disabled. The httpd configuration is managed in its configuration file, /etc/httpd.conf, which has to be created:

# nano /etc/httpd.conf

Add to the file:

# Main Configuration
server "example.com" {
    listen on * port 80
    root "/htdocs/example.com"
    location "/.well-known/acme-challenge/*" {
        root "/acme"
        request strip 2
    }
    location * {
        block return 302 "https://$HTTP_HOST$REQUEST_URI"
    }
}

Test the configuration:

# httpd -n
configuration OK

Start httpd.

# rcctl -f start httpd
httpd(ok)

Add a Let's Encrypt certificate to the server:

# cp /etc/examples/acme-client.conf /etc/acme-client.conf
# nano /etc/acme-client.conf

Change example.com to the desired domain and remove, change, or add subdomains to the alternative line.

# acme-client -v example.com

After successful registration, create a cron job:

# crontab -e

Add:

0	*	*	*	*	sleep $((RANDOM \% 2048)) && \
	acme-client example.com && rcctl reload httpd

Now add the SSL/TLS and redirect options httpd.conf

# nano /etc/httpd.conf

Add:

# This is a redirect to the Main Configuration
server "www.example.com" {
    listen on * port 80
    listen on * tls port 443
    tls {
        certificate "/etc/ssl/example.com.fullchain.pem"
        key "/etc/ssl/private/example.com.key"
    }
    block return 301 "http://example.com$REQUEST_URI"
}
 
server "example.com" {
    listen on * tls port 443
    root "/htdocs/example.com"
    tls {
        certificate "/etc/ssl/example.com.fullchain.pem"
        key "/etc/ssl/private/example.com.key"
    }

    location "/.well-known/acme-challenge/*" {
        root "/acme"
        request strip 2
    }
}

Test and restart httpd

# httpd -n
Configuration OK
# rcctl reload httpd
httpd(ok)

Enable DNS resolution and local time

If a package requires local time or DNS resolution, the following configuration will support this within the chroot:

# mkdir /var/www/etc
# cp /etc/{hosts,localtime,resolve.conf} /var/www/etc/

Install PHP

Boot multiple PHP versions

The pkg_add tool permits the installation of multiple PHP versions which can be configured to load at boot.

Create a new php-fpm configuration for each PHP version.

$ doas cp /etc/php-fpm.conf /etc/php73-fpm.conf
$ doas cp /etc/php-fpm.conf /etc/php74-fpm.conf
$ doas nano /etc/php73-fpm.conf

Change the listen directive in each file to match the new FPM configuration file:

listen = /var/www/run/php73-fpm.sock

$ doas nano /etc/php74-fpm.conf

Change:

listen = /var/www/run/php74-fpm.sock

Edit rc.conf.local to load each PHP version with the new FPM configuration file on startup:

$ doas nano /etc/rc.conf.local

Add:

pkg_scripts=php73_fpm php74_fpm
php73_fpm_flags="-y /etc/php73-fpm.conf"
php74_fpm_flags="-y /etc/php74-fpm.conf"

The separate FPM configurations are convenient for servers hosting multiple PHP packages that may require different PHP versions. It is a little extra to configure initially, but packages failing due to incorrect PHP versions do not always announce this to be the cause of their failure, generating what at times can be a time-consuming diagnosis. A server dedicated to a single PHP package requiring a specific PHP version, such as PHP 7.3, can do away with the above procedure and configure rc.conf.local with a single command:

$ doas rcctl enable php73_fpm

This will use the automatically configured php-fpm.conf file, so there is no need to use a _flags option to specify a different configuration file.

Email

OpenBSD in its default configuration comes with opensmtpd in a very secure configuration that supports outgoing mail. This is primarily useful for transactional email, most especially administrative messages.

Administrative message recipients can be configured in the aliases file and are default configured to be sent to the local root user local mailbox. To configure additional recipients:

# nano /etc/mail/aliases

Change and add:

# Basic system aliases -- these MUST be present
MAILER-DAEMON: postmaster
postmaster: root
root: username@example.com,anotherusername@example.net

Update the configuration:

# newaliases

Transactional mail configuration

This configuration is for sending transactional mail and supporting DKIM for a single domain that can be used in DNS records for multiple domains.

$ doas pkg_add opensmtpd-filter-dkimsign

Note that the man page for dkimsign is located at man filter-dkimsign.

$ doas openssl genrsa -out /etc/mail/dkim/selector.key 1024
$ doas chmod 0640 /etc/mail/dkim/selector.key
$ doas openssl rsa -in /etc/mail/dkim/selector.key -pubout -out /etc/mail/dkim/selector.pub
$ doas chown -R _dkimsign:_dkimsign /etc/mail/dkim

The selector can be left as is in the sample text or changed to a different character string, such as a date, a domain, airspeed of an unladen swallow, etc.

$ doas nano /etc/mail/smtpd.conf

Change to:

# This is the smtpd server system-wide configuration file.
# See smtpd.conf(5) for more information.

table aliases file:/etc/mail/aliases

filter "dkimsign" proc-exec "filter-dkimsign \
    -d example.com -s selector -t \
    -k /etc/mail/dkim/selector.key" user _dkimsign group _dkimsign

listen on socket filter "dkimsign"
listen on lo0 filter "dkimsign"

action "local_mail" mbox alias <aliases>
action "outbound" relay

# Uncomment the following to accept external mail for domain "example.org"
#
# match from any for domain "example.org" action "local_mail"

match for local action "local_mail"
match for any action "outbound"

Mail server configuration

Create DKIM key and directory:

# mkdir /etc/mail/dkim
# openssl genrsa -out /etc/mail/dkim/example.com.key 1024
# chmod 640 /etc/mail/dkim/example.com.key
# openssl rsa -in /etc/mail/dkim/example.com.key -pubout -out /etc/mail/dkim/example.com.pub
# cat /etc/mail/dkim/example.com.pub

Install and configure antispam packages

# pkg_add redis rspamd opensmtpd-filter-rspamd opensmtpd-filter-senderscore

Configure DKIM signing:

# chown root:_rspamd /etc/mail/dkim/example.com.key
# mkdir /etc/rspamd/local.d
# nano /etc/rspamd/local.d/dkim_signing.conf
allow_username_mismatch = true;

domain {
    example.com {
        path = "/etc/mail/dkim/example.com.key";
        selector = "20200221";
    }
}

Enable and start redis and rspamd:

# rcctl enable redis
# rcctl enable rspamd
# rcctl start redis
redis(ok)
# rcctl start rspamd
rspamd(ok)

Update the OpenSMTPD configuration:

# mv /etc/mail/smtpd.conf /etc/mail/smtpd.conf.original
# nano /etc/mail/smtpd.conf

pki mail.hypno.cat cert "/etc/ssl/mail.hypno.cat.fullchain.pem"
pki mail.hypno.cat key "/etc/ssl/private/mail.hypno.cat.key"

filter check_dyndns phase connect match rdns regex { '.*\.dyn\..*', '.*\.dsl\..*' } \
    disconnect "550 no residential connections"

filter check_rdns phase connect match !rdns \
    disconnect "550 no rDNS is so 80s"

filter check_fcrdns phase connect match !fcrdns \
    disconnect "550 no FCrDNS is so 80s"

filter senderscore \
    proc-exec "filter-senderscore -blockBelow 10 -junkBelow 70 -slowFactor 5000"

filter rspamd proc-exec "filter-rspamd"

table aliases file:/etc/mail/aliases

listen on all tls pki example.com \
    filter { check_dyndns, check_rdns, check_fcrdns, senderscore, rspamd }

listen on all port submission tls-require pki example.com auth filter rspamd

action "local_mail" maildir junk alias <aliases>
action "outbound" relay helo example.com

match from any for domain "example.com" action "local_mail"
match for local action "local_mail"

match from any auth for any action "outbound"
match for any action "outbound"

Reinstallation on Vultr

To run OpenBSD as configured by the OpenBSD project, which makes use of multiple partitions, it is currently necessary to create a Vultr instance running OpenBSD, then reinstall OpenBSD using the console in the Vultr dashboard.

Open the console

From the Vultr dashboard, open the OpenBSD instance and click the console icon at the top of the page. Note that when using the console interface, it will not be possible to use a mouse, access the local clipboard, or otherwise interact with the interface other than through the keyboard.

Load installer through bsd.rd

Log in using root with the password from the Vultr dashboard.

vultr# reboot

Note the above step may be performed through SSH, which may be easier to enter password and access the shell using the local clipboard.

After the system boots there will be a boot prompt:

boot> bsd.rd

Followed by a question:

Welcome to the OpenBSD/amd64 6.6 installation program.
(I)nstall, (U)pgrade, (A)utoinstall or (S)hell? I

Install OpenBSD with partitions

Most of the install questions can be answered using the default, which is shown in brackets.

Note the following non-default answers:

Create the root user using the password provided for the instance by Vultr, taking care to correctly enter ambiguous characters.

Enter the domain of the hostname (example.com).

Do you expect to run the X Window System? [yes] no

There is a warning about not allowing root to ssh log in using password. This is will be reconfigured later in the setup process.

Allow root ssh login? (yes, no, prohibit-password) [no] yes

Location of sets? (cd0 disk http nfs or 'done') [cd0] http

For selecting the download location, enter ? then note a desired download location and enter the number:

HTTP Server? (hostname, list#, 'done' or '?') ?
...
HTTP Server? (hostname, list#, 'done' or '?') 47

Configure the partitions

The automatically generated partition table for a 25GB server instance will look something like below and should be edited:

#                 size          offset  fstype [fsize   bsize  cpg]
 a:            890.7M              64  4.2BSD    2048  16384    1 # /
 b:           1263.9M         1824160    swap
 c:          25600.0M               0  unused
 d:            1305.M         4412544  4.2BSD    2048  16384    1 # /tmp
 e:           2005.8M         7085376  4.2BSD    2048  16384    1 # /var
 f:           2240.7M        11193184  4.2BSD    2048  16384    1 # /usr
 g:            828.4M        15782080  4.2BSD    2048  16384    1 # /usr/X11R6
 h:           3246.0M        17478656  4.2BSD    2048  16384    1 # /usr/local
 i:           1596.3M        24126560  4.2BSD    2048  16384    1 # /usr/src
 j:           5712.5M        27395712  4.2BSD    2048  16384    1 # /usr/obj
 k:           6506.4M        39095008  4.2BSD    2048  16384    1 # /home
Use (A)uto layout, (E)dit auto layout, or create (C)ustom layout? [a] e

For available commands from the prompt, enter ? or see the disklable(8) man page

The /usr/src and /usr/obj partitions are used when updating or upgrading OpenBSD from source, but this is not planned for usage of this installation so will not be created.

If an error is made when making a change, u will undo the last change, and u a second time will restore the change, while U will undo all changes.

Delete and create partitions. To see the current partition table with changes, use p *.

sd0> z
sd0*> a a
offset: [64]
size: [52420031] 1793024
FS type: [4.2BSD]
mount point: [none] /
sd0*> a b
offset: [1793088]
size [50627007] 3073771
FS type: [swap]
sd0*> a d
offset: [4866859]
size: [47553236] 2663840
FS type: [4.2BSD]
mount point: [none] /tmp
sd0*> a e
offset: [7530720] 
size: [44889375] 20491776
FS type: [4.2BSD]
mount point: [/var]
sd0*> a f
offset: [28022496]
size: [24397599] 6147520
FS type: [4.2BSD]
mount point: [none] /usr
sd0*> a g
offset: [37858560]
size: [14561535] 1991776
FS type: [4.2BSD]
mount point: [none] /usr/X11R6
sd0*> a h
offset: [39850336]
size: [12569759] 3434400
FS type: [4.2BSD]
mount point: [none] /usr/local
sd0*> a k
offset: [43284736]
size: [9135359]
FS type: [4.2BSD]
mount point: [none] /home
sd0*> p *
OpenBSD area: 64-52410098; size: 25595.7; free: 0.0M
 #                 size          offset  fstype [fsize   bsize  cpg]
 a:            875.5M              64  4.2BSD    2048  16384    1 # /
 b:           1500.9M         1793088    swap
 c:          25600.0M               0  unused
 d:           1300.7M         4866880  4.2BSD    2048  16384    1 # /tmp
 e:          10005.8M         7530720  4.2BSD    2048  16384    1 # /var
 f:           4802.8M        28022496  4.2BSD    2048  16384    1 # /usr
 g:            972.5M        37858560  4.2BSD    2048  16384    1 # /usr/X11R6
 h:           1677.0M        39850336  4.2BSD    2048  16384    1 # /usr/local
 k:           4460.6M        43284736  4.2BSD    2048  16384    1 # /home
sd0*> w
sd0> q

A sector is 512 bytes and the offset is the sector the partition begins at. If Vultr changes the number of sectors, simply determine the free sectors using the r command and modify the partitions, moving them in similar fashion to above steps (e.g., starting with partition k:).

While the above configuration should be acceptable for most small server needs, it does have some weaknesses. On a busier server, there should likely be separate partitions created for /var/log/, /var/db/, /var/www/, and /var/www/logs/. This is to prevent applications from filling the partition and crashing the server.

Now the partitions will be created and the installer will ask:

Let's install the sets!
Location of sets? (cd0 disk http nfs or 'done') [http}
HTTP proxy URL? (e.g. 'http://proxy:8080', or 'none') [note]
HTTP Server? (hostname, list#, 'done' or '?') [mirrors.sonic.net]
Server directory? [pub/OpenBSD/6.6/amd64]

For the software selection, leave all selected and at [done] press enter.

When given the option to reboot, press enter.

Install MariaDB

servername$ doas pkg_add -v mariadb-server