werc on openbsd
v2.1
Automate Werc setup on OpenBSD.
Both the setup.sh and unsetup.sh scripts, in their latest available version (v2.1), have been successfully tested on the latest available OpenBSD stable release (7.6). Prior or later versions of OpenBSD may not work.
Performing an OpenBSD release upgrade (e.g. by using sysupgrade(8)) may break the current Werc installation. It is advised to always test your Werc installation after performing either a system upgrade, a Werc update, or a plan9port update. If it stops working, head to Troubleshooting.
For now, the installation resulting from setup.sh has only been tested with GET requests, which it supports for sure. Other types of HTTP requests may or may not work (e.g. the "user login" feature). The URL-based rules in /etc/httpd.conf (location ...) may need a different configuration to support HTTP requests other than GET.
A tagged commit with tag name of the form vN.M (where N and M are integers), is a commit whose working tree has the following characteristics:
setup.sh and unsetup.sh, tested against the latest OpenBSD stable version (available at that point in time) with positive outcome and no known side effect on the system.Since the testing process is manual I may overlook some edge cases, sometimes on purpose and sometimes not. I care about the quality of my software but testing every single line against all its possible edge cases is really time consuming and unsustainable.
(Moved to rat.md.)
Note: To preserve the original config files that are going to be modified, the setup script backs them up by adding .bk to the end of their name. For example, the original content of /etc/httpd.conf is copied to /etc/httpd.conf.bk. To restore the original files, the unsetup script renames the backup files with their original name, replacing the changed version.
In the following list, $webdir and $p9pdir respectively refer to httpd's web content directory, by default /var/www, and plan9port's installation directory with $webdir as root, by default /plan9.
/etc/httpd.conf.bk and /etc/fstab.bk already exist in your machine's file system? If so, setup.sh will probably overwrite them, consider renaming or removing them.$webdir which cannot be lost? The setup script creates new files in $webdir which may overwrite existing ones while the unsetup script removes some directories which may delete those files. Consider moving important files out of $webdir.setup.sh again, nor running unsetup.sh, is going to repair it. (If it did, you're just lucky.) Depending on which command(s) failed and the type of error, you may be able to manually repair the installation by yourself. However, this is not always the case and it's an error-prone procedure, so it is not advised at all.The following procedure downloads scripts using the latest release tag. The latest tag shown in the URL below is manually updated, please check that it matches the actual latest release before proceeding. It is not recommended (at all) to run scripts from the main branch.
The following procedure refers to the setup script (setup.sh). For the un-setup script (unsetup.sh), the procedure is the same except for the script name.
The procedure is as follows, written both in human-readable steps and as commands:
domain variable (and webdir, if necessary) at will.ftp https://raw.githubusercontent.com/EdoardoLaGreca/werc-on-openbsd/v2.1/setup.sh
sha256 -q setup.sh
vi setup.sh # change domain and webdir
chmod 744 setup.sh
doas ./setup.shThe setup script does not automatically start httpd and slowcgi. It behaves like that for two reasons: firstly, you might want to make some final changes to your website before displaying it publicly; secondly, if /etc/fstab has been changed by the script, you need to reboot your system before starting the webserver. The script should display a log message if you need to reboot (and/or /etc/fstab has been changed). The absence of such message in the log means that rebooting is not necessary. All this does not apply to unsetup.sh.
Instead of running the entire script, one might want to run just one or some parts to, for example, debug the script or run again a part which could not terminate successfully. To do so is as simple as passing the part names to the script as arguments. An example is shown below.
./setup.sh preinst instAlthough the line above uses setup.sh, unsetup.sh also behaves in this way.
It is good practice to keep software up to date, both to receive new features and to patch existing vulnerabilities.
When using Werc, 4 pieces of software need to be kept up to date:
httpd and slowcgi)Unless you're using OpenBSD's -current branch, httpd and slowcgi are usually updated on every system upgrade. They are pretty secure and minimalist so keeping them up to date is not essential. These programs are part of OpenBSD's source tree which contains the whole operating system, including its kernel, essential libraries, and all preinstalled utilities. All software in that source tree undergoes severe security audits, that's why they are so secure.
On the other hand, it's important to keep Werc and plan9port up to date. To do so, run the following lines in the shell. They remove the existing Werc and plan9port installations, download their updated version, and install them again.
doas ./unsetup.sh uninst rm9env
doas ./setup.sh inst mk9envUnless you'd like to contribute to the development, skip this section.
A test script, namely test.sh, automates the testing of the setup and unsetup scripts. The test script contains three main functions:
init, which performs all the preliminary taskssetup, which runs the setup script and collects information about changes in the filesystemunsetup, which is the same as setup but with the unsetup scriptThe behavior of the test script is similar to that of the setup and unsetup scripts: functions can be called by specifying them as command line arguments. However, there is one little difference, which is that running the script without arguments is no different from not running the script at all. This behavior is a choice which, in theory, should reduce careless testing.
It may happen that, after upgrading OpenBSD, your website stops working and only shows "500 internal server error".
While the exact reason behind this behavior should be carefully analyzed and understood, you might try uninstalling and re-installing Werc and plan9port. The procedure is the same as if you were to update them.
doas ./unsetup.sh uninst rm9env
doas ./setup.sh inst mk9envThese checksums are calculated on the working tree of the latest release.
setup.sh:
7a08ee3a8e824f9a54b9a471ef0ebc6fb7ee2a848f13a33264b42a3e9d8817da
unsetup.sh:
18f74da2537dc4dcc97c3fc6d4439faf6340f068309d9110a5dc098b899c3e50
Starting from v2.0 the project is now licensed under the ISC license, instead of Creative Commons Zero. Most things don't change, except for giving users and contributors more rights.
