The OpenBSD nginx/MySQL/PHP stack

This page has been deprecated, and only applies to OpenBSD versions that shipped nginx in the base distribution (5.2 - 5.6)

See our new guide: PHP/MySQL with nginx on OpenBSD


Starting with OpenBSD 5.2, OpenBSD ships with nginx with the intent that it will be the default web server, completely replacing Apache in the base distribution. It's pretty easy to get most PHP/MySQL applications working with nginx, but this requires a FastCGI implementation of PHP, and I've chosen PHP-FPM for this walk-through. As of November 1, 2014, these instructions have been tested to work for OpenBSD 5.5 and 5.6 on the i386 architecture.


First, install OpenBSD. Be sure to create a user-level account for yourself during the installation process, and I'd recommend disabling remote root logins while you're at it. This user account will be added to the wheel group. On BSD systems, wheel group is comparable to an administrator group, granting access to use the su command, etc.  You can add other trusted users to this group later on.

As an extension to this privilege, we usually add the wheel group to /etc/sudoers with the ability to run any command. Once you've got OpenBSD installed, log in and su to root (with "su -") or log in as root and edit the sudoers file with the "visudo" command. Uncomment (or add) the line below. Optionally, there's a similar line that does not prompt the user for a password. We do not recommend using that option on a production system.


Now, set up the package manager by adding an installpath line in /etc/pkg.conf. For best results, you should pick an OpenBSD mirror that is near you both physically and network-wise. Try pinging and tracerouting different mirrors in your country and seeing which ones have the best response times or the fewest hops. Once you've picked a mirror, you can create /etc/pkg.conf with this quick one-liner that takes your OpenBSD version and architecture into account. I'm using ftp5.usa in this example. Put it all on one line.

echo installpath=$(uname -r)/packages/$(uname -m) | sudo tee /etc/pkg.conf
If you bought the OpenBSD media and have packages on CD you'd like to use, you can add them to the installpath instead of the FTP mirror, or in addition to it.

Installing Packages
OpenBSD includes the Suhosin Hardened PHP patches in their default PHP package, which is nice. Nginx will require the use of PHP with FastCGI, and the package repository contains both php-fastcgi and php-fpm. We'll be using php-fpm for this. Since OpenBSD's package manager automatically installs dependencies, you can get away with this command, which should install everything else we need to get PHP up and running with the MySQL Client extension and MySQL server:

sudo pkg_add php-fpm php-mysql mysql-server

You'll likely be asked which version of certain packages you wish to install. Unless you know you require a specific version of PHP, your best bet is to go for the one with the highest version number. As of OpenBSD 5.6, that's PHP 5.5.14. Do not install any packages that end in "-ap2" as these are built against the apache2 package. After completion, you'll be asked to create symbolic links for PHP's configuration files. If you do not plan to use Apache (and why should you, if you're going with nginx?) you do not need to link to the modules directory. You will, however, have to perform the following to get PHP-MySQL working properly. Mind the version numbers below, as php-5.2, php-5.3 and php-5.4 have different paths.

sudo ln -sf /etc/php-5.4.sample/mysql.ini /etc/php-5.5/mysql.ini

Configure MySQL:

sudo /usr/local/bin/mysql_install_db
sudo /etc/rc.d/mysqld start
sudo /usr/local/bin/mysql_secure_installation

Follow the prompts to lock down MySQL. Set a good password. The rest of the defaults are probably okay.

Set daemons to start up by adding the following lines to /etc/rc.conf.local. You'll probably need to create the file manually.

pkg_scripts="mysqld php_fpm"

Of course, you can specify any additional options you need in nginx_flags instead of leaving it empty.

Edit /etc/nginx/nginx.conf and add "index.php" to the line that has the other index files. The config block should look like this, but you can alter the order if you wish.

        location / {
            root   /htdocs;
            index  index.html index.htm index.php;
Uncomment the following block of configuration to enable nginx to forward PHP requests to php-fpm. On OpenBSD 5.5, the fastcgi_pass line used TCP instead of a socket. The block of code in nginx.conf is correct and can be uncommented as-is in both OpenBSD 5.5 and 5.6.

        location ~ \.php$ {
            try_files      $uri $uri/ =404;
            fastcgi_pass   unix:run/php-fpm.sock;
            fastcgi_index  index.php;
            fastcgi_param  SCRIPT_FILENAME $document_root$fastcgi_script_name;
            include        fastcgi_params;
Nginx makes it relatively easy to set up multiple virtual hosts, but that's beyond the scope of this article. We'll install everything to /var/www/htdocs as the default web root.

Go ahead and reboot at this point to make sure the daemons start automatically.

There is no default index page provided with nginx. Browsing to your OpenBSD 5.6 web server will probably display an nginx error page.

Test PHP by adding the following lines to /var/www/htdocs/phpinfo.php

Then load http://your.server.ip/phpinfo.php. As you can see below, the Server API is FPM/FastCGI.

PHP-MySQL works just as it always has. Since nginx and php-fpm are configured for a chroot environment on /var/www, the easiest way to make sure you web applications work with MySQL is to set up the user accounts to work from (instead of "localhost" which is a socket connection, with the socket located outside the chroot environment). This forces MySQL to use a TCP connection to localhost. It may be a little slower, but should work for most users. Advanced users may wish to create a solution that hard-links the socket to a location in /var/www, and configure php to use that instead. This is beyond the scope of this getting-started guide, but would involve editing the MySQL startup scripts and php-fpm configuration.

blog comments powered by Disqus