The ubiquitous LAMP (Linux / Apache / MySQL / PHP) Stack that runs on just about every private or SOHO, and even enterprise level, deployment has scores of guides available across the Internet. If you are establishing your own web server for the first time, you can google LAMP Stack $linux_distro and Google will return thousands of results; many of them up-to-date and accurate enough that you can reliably follow the steps provided to deploy a secure production environment where you can serve anything from your WordPress blog to private cloud storage with webmail and online calendar application. Attempting to do the same on OpenBSD, however, is not as fruitful; current, correct, and comprehensive guides are not as forthcoming from a Google search. To start, there is no comparable search pattern. For example, OAMP Stack (OpenBSD / Apache / MySQL / PHP) returns 23 results, most of which aren’t relevant, and less than a handful that are current and correct albeit short of comprehensive. Further, the base system web server included in an OpenBSD installation is named httpd, which presents more of a challenge in searching for quality content. There is, however, a silver lining for OpenBSD users: quality documentation and rock solid design. The official OpenBSD documentation is clear and concise; it's super easy to follow and always correct. And certainly much more reliable than the commonly praised and exhaustive, albeit garrulous, official documentation of its better known cousin, FreeBSD. Further, installation of OpenBSD ported packages provides additional system specific information in /usr/local/share/doc/pkg-readmes with step-by-step instructions that produce sane configuration and a working setup out of the box. OpenBSD developers have put in a lot of work to ensure users are met with a precision in documentation that is equal to the stability and security of the system. It is an example of quality trumping quantity and engineering brilliance!

With that in mind, you will find this guide—which assumes an OpenBSD 6.2 system—presenting information sourced from the official OpenBSD documentation, provided in the website FAQ, as well as official software documentation. Proper use of these two sources combined with ad hoc use of relevant man pages are more often than not all that is needed for successful installation, configuration, and deployment of all OpenBSD base tools and packages.

HTTP Daemon Setup

OpenBSD comes with its own web server: httpd. It is secure, lightweight and very simple to use.

In OpenBSD, rcctl is used to configure and control daemons and services, which we'll use to enable and start httpd.

# rcctl enable httpd
# rcctl start httpd

The enable command adds an entry to /etc/rc.conf.local, which is where all the scripts that control the system daemons and services are either set or unset to run during system startup. The start command, as you would suspect, starts the httpd daemon.

OpenBSD provides an example configuration file in /etc/examples/httpd.conf that you can peruse if not use for yourself. Creating your own, though, is really very simple and can be done in as little as a half dozen non-whitespace lines.

Create a new /etc/httpd.conf file with your editor of choice, and add the following (replacing domain.tld with your site particulars):

types {  include "/usr/share/misc/mime.types" }

server "domain.tld" {
     alias "www.domain.tld"
     listen on * port 80
     root "/htdocs/site_name"
     directory index index.php

     location "/*.php*" { fastcgi socket "/run/php-fpm.sock" }

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

The meanings of each line can be ascertained from the httpd.conf(5) man page. In short, the above will serve regular HTTP (i.e., port 80) domain.tld and www.domain.tld requests from /var/www/htdocs/site_name, and process all PHP requests through a Unix socket connection to the FastCGI Process Manager. The second location directive handles acme challenges that will be received when generating a HTTPS certificate with acme-client(1), which is described in detail in this post.

Before moving onto MariaDB installation, check that the syntax is correct then load the new httpd.conf:

# httpd -vnf /etc/httpd.conf
configuration OK
# httpd -f /etc/httpd.conf

That concludes the rather simple setup of the OpenBSD HTTP daemon, httpd.

Database Installation

OpenBSD offers both PostgreSQL and MariaDB, the open source MySQL fork, as binary packages available through pkg_add. PostgreSQL is an excellent (and likely superior) alternative to MySQL, but its configuration is not as widely covered by the official documentation of many third-party applications. Plus, for most personal and SOHO environments it is arguably overkill, with any real advantage not being utilised. In contrast, MySQL/MariaDB installations share common syntax with most documentation from third-party apps. In short, MySQL/MariaDB is simpler than PostgreSQL and more than enough firepower for this use case so it will be installed with:

# pkg_add mariadb-server

Once downloaded, use the install script provided before enabling and starting the daemon:

# mysql_install_db
# rcctl enable mysqld
# rcctl start mysqld

MariaDB provides a post-install script to secure the daemon and create a root superuser account, which should be run with:

# mysql_secure_installation

A series of easily answered questions will follow; set the root password and answer yes to each question.

Once finished, before accessing the database, change the environment to delete MySQL input rather than have it logged in clear text by adding the following to /etc/rc.conf.local:
export MYSQL_HISTFILE=/dev/null

Now access MariaDB as the superuser to create a database for the upcoming WordPress installation; enter the root password when prompted.

# mysql -u root -p

Then enter the following SQL to create the wordpress database with admin wp-admin and the desired password:

GRANT ALL ON wordpress.* to 'wp-admin'@'localhost' IDENTIFIED BY 'password';

To ensure MariaDB can communicate with httpd through a unix socket, edit /etc/my.cnf and change the socket location under both the client and mysqld sections to the absolute path of the file located inside the chroot:

socket = /var/www/var/run/mysql/mysql.sock
socket = /var/www/var/run/mysql/mysql.sock

Restart the daemon to make changes take effect before moving onto the PHP installation:

# rcctl restart mysqld

PHP Configuration

In OpenBSD, like all applications provided via pkg, PHP is offered as a pre-compiled binary package in one configuration, and any desired extensions that aren't built in the default provision can be installed as additional packages. Given that not all commonly required extensions are available in the latest available version, at the time of this writing, it is best to select version 5.6.31 when prompted by the interactive pkg prompt. In addition to the MySQL PHP extensions needed for this deployment, we will install some additional extensions commonly used by other popular applications:

# pkg_add php php-gd php-mysql php-mysqli php-bz2 php-curl php-intl php-mcrypt php-zip php-pdo_dblib php-pdo_mysql

The web server is already configured to handle PHP requests so we can move straight onto PHP configuration by enabling all installed extensions:

# cp /etc/php-5.6.sample/* /etc/php-5.6/.

Some minor adjustments to the default PHP configuration will be made for runtime optimisation. Bring up /etc/php-fpm.conf in your chosen editor and search for the string pm = to make the following changes:

pm = ondemand
pm.max_children = 50
pm.max_requests = 500

Next, to cache compiled PHP files and improve performance, activate Zend OpCache by either uncommenting and editing, or simply appending, the following entries to /etc/php-5.6.ini:


Now enable and start php-fpm, and restart httpd:

# rcctl enable php56_fpm
# rcctl start php56_fpm
# rcctl restart httpd


At this point, httpd is up and serving out of /var/www/htdocs/site_name; MariaDB has been installed, WordPress database created, and is ready to create further databases required by different web applications; and PHP is configured with FastCGI Process Manager handling requests made through the httpd web server.

To test that the setup is working as intended, open the new file /var/www/htdocs/site_name/info.php in your favourite editor and add:


Now enter domain.tld/info.php in a browser and you should be greeted with the easily recognisable PHP info page.

Web Deployment

To standup a basic website and blog, download the latest WordPress tarball into the /var/www/htdocs/site_name directory and extract its contents:

# cd /var/www/htdocs/site_name
# ftp -S do
# tar -zxvf wordpress-4.9.4-en_AU.tar.gz

Now open /etc/httpd.conf to change the root of domain.tld to the relative path of the /wordpress directory inside the chroot to serve up domain.tld requests:

root "/htdocs/site_name/wordpress"

Now restart the daemon for changes to take effect:

# rcctl restart httpd

Point your browser to domain.tld/wp-admin/install.php where you will be greeted by the WordPress setup screen. Enter the previously created database name (wordpress), username (wp-admin), password entered when creating the database, and database host (localhost). Leave the table prefix as is and click Let's go! You should immediately be met by WordPress advising that it cannot create the wp-config.php file, but providing you with the contents of this file instead. Copy the provided text, open up /var/www/htdocs/site_name/wordpress/wp-config.php in your chosen editor, paste the text, then save and exit the file.0 Now point your browser again to domain.tld where you will be presented with your brand new WordPress site.

0Alternatively, before opening domain.tld/wp-admin/install.php for the first time, run chmod 775 /var/www/htdocs/site_name/wordpress; chown :www /var/www/htdocs/site_name/wordpress and the wp-config.php file will be configured by WordPress itself without the manual copypasta.

n.b. If you have any issues following this guide, don't hesitate to comment or email mark [at] jamsek [dot] com.


comments powered by Disqus