You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Automate [Werc](http://werc.cat-v.org/) setup on [OpenBSD](https://www.openbsd.org/).
4
5
5
6
## Useful info
6
7
7
-
<!--
8
-
Both the `setup.sh` and `unsetup.sh` scripts, in their latest available version ([v1.3](https://github.com/EdoardoLaGreca/werc-on-openbsd/releases/tag/v1.3)), have been successfully tested on the latest available OpenBSD stable release (7.6). Prior or later versions of OpenBSD may not work.
9
-
-->
8
+
Both the `setup.sh` and `unsetup.sh` scripts, in their latest available version ([v2.0](https://github.com/EdoardoLaGreca/werc-on-openbsd/releases/tag/v2.0)), have been successfully tested on the latest available OpenBSD stable release (7.6). Prior or later versions of OpenBSD may not work.
10
9
11
-
**Performing an OpenBSD release upgrade (e.g. by using [sysupgrade(8)](https://man.openbsd.org/sysupgrade.8)) or updating the `plan9port` package may break the current Werc installation.** It is advised to always test your Werc installation after performing either a system upgradeor a `plan9port` update. If it stops working, head to [Troubleshooting](#troubleshooting).
10
+
**Performing an OpenBSD release upgrade (e.g. by using [sysupgrade(8)](https://man.openbsd.org/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](#troubleshooting).
12
11
13
12
### Limitations
14
13
15
-
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. The URL-based rules in `/etc/httpd.conf` may need a different configuration to support other HTTP requests as well.
14
+
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`.
16
15
17
16
### Other info
18
17
@@ -35,9 +34,9 @@ Since the testing process is manual I may overlook some edge cases, sometimes on
35
34
36
35
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`.
37
36
38
-
-**Do the files `/etc/httpd.conf.bk` and `/etc/fstab.bk` already exist in your machine's file system?** If so, `setup.sh` will overwrite them, consider renaming or removing them.
39
-
-**Did you add or change files in `$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` or placing them in directories which will not be removed.
40
-
-**Did you make a backup of your machine?** The setup script may fail to complete, for example due to a network error. This leads to an incomplete installation and neither running `setup.sh` again, nor running `unsetup.sh`, is going to repair it. 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's discouraged.
37
+
-**Do the files `/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.
38
+
-**Did you add or change files in `$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`.
39
+
-**Did you make a backup of your machine?** The setup script may fail to complete, for example due to a network error. This leads to an incomplete installation and neither running `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.
41
40
42
41
### Actual usage
43
42
@@ -48,52 +47,70 @@ The following procedure refers to the setup script (`setup.sh`). For the un-setu
48
47
The procedure is as follows, written both in human-readable steps and as commands:
49
48
50
49
1. Download the script from the latest tag.
51
-
2. Verify the script's checksum (see [Checksums](#checksums)).
50
+
2. Verify the script's checksum (see [checksums](#sha-256-checksums-v20)).
52
51
3. Change the `domain` variable (and `webdir`, if necessary) at will.
53
52
4. Set the execution permission bit of the script.
The `setup.sh` 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 and secondly you may have to reboot your system before starting the webserver if `/etc/fstab` has been changed by the script. 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. This does not apply to `unsetup.sh`.
63
+
The 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`.
65
64
66
-
### Running parts
65
+
####Running parts
67
66
68
-
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 function names to the script as arguments. An example is shown below.
67
+
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.
69
68
70
69
```sh
71
70
./setup.sh preinst inst
72
71
```
73
72
74
-
Although the example above uses `setup.sh`, `unsetup.sh` also behaves in this way.
73
+
Although the line above uses `setup.sh`, `unsetup.sh` also behaves in this way.
75
74
76
-
##Troubleshooting
75
+
### Maintenance
77
76
78
-
### Werc stops working after upgrading OpenBSD or updating plan9port
77
+
It is good practice to keep software up to date, both to receive new features and to patch existing vulnerabilities.
79
78
80
-
It may happen that, after upgrading OpenBSD or updating the `plan9port` package, your website stops working and only shows "500 internal server error".
79
+
When using Werc, 4 pieces of software need to be kept up to date:
81
80
82
-
I don't know the reason, if I'm being honest. However, I found out that removing all the contents of the `plan9port` package from the webserver's directory and then placing them there again solves the error. Uninstalling and re-installing everything would work, although this solution is a waste of time, especially on slower machines, and could potentially have some side effects (it is not guaranteed not to have them).
81
+
- OpenBSD's own HTTP and SlowCGI daemons (a.k.a. `httpd` and `slowcgi`)
82
+
- Werc
83
+
- plan9port
83
84
84
-
The proper way to solve this issue is by using the following commands.
85
+
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.
85
86
87
+
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.
88
+
89
+
```sh
90
+
doas ./unsetup.sh uninst rm9env
91
+
doas ./setup.sh inst mk9env
86
92
```
87
-
doas ./unsetup.sh rm9env
88
-
doas ./setup.sh mk9env
89
-
```
90
93
91
-
## Checksums (v1.3)
94
+
## Troubleshooting
95
+
96
+
### Werc stops working after upgrading OpenBSD
97
+
98
+
It may happen that, after upgrading OpenBSD, your website stops working and only shows "500 internal server error".
92
99
93
-
`setup.sh` SHA-256: ``
100
+
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.
Starting from [v1.3](https://github.com/EdoardoLaGreca/werc-on-openbsd/releases/tag/v1.3) 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.
116
+
Starting from [v2.0](https://github.com/EdoardoLaGreca/werc-on-openbsd/releases/tag/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.
Copy file name to clipboardExpand all lines: rat.md
+1-1Lines changed: 1 addition & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -16,4 +16,4 @@ Another thing I really cared about, back when I started writing this script, is
16
16
17
17
In addition to all I said before, and this was by far the hardest goal to achieve, all this had to comply with OpenBSD's [httpd](https://man.openbsd.org/httpd) way of doing things. That is, the hosted website is served from a `chroot`'ed directory, `/var/www`. By doing so, potential breaches are only limited to that portion of the file system. At first, since [symlinks](https://en.wikipedia.org/wiki/Symbolic_link) cannot be accessed from a `chroot`'ed environment, I solved it the naïve way: I just copied all the Plan 9 utilities, together with their shared objects, into `/var/www`. This was not the best solution, not even close, but it worked for a while. Then, I switched to [hard links](https://en.wikipedia.org/wiki/Hard_link). In theory, hard links consume way less data on disk. In practice, most of the times they are not possible because even OpenBSD's default installation splits the filesystem into many partitions and hard links cannot be created from one disk/partition to the other. At that time I wrote the setup script to only hard link files when possible and to copy them otherwise. Given the probabilities of finding an OpenBSD installation with all files on the same partition, this latter solution was basically the same as the former, naïve solution.
18
18
19
-
The final solution, introduced in [v1.3](https://github.com/EdoardoLaGreca/werc-on-openbsd/releases/tag/v1.3), is to clone plan9port's git repository into the `chroot`'ed filesystem and install it there, with its hard-coded paths adjusted through the `-r` option. Not only this improves the system's security, since patches can be applied immedately, but it also eliminates the need of work-arounds to make hard-coded paths work.
19
+
The final solution, introduced in [v2.0](https://github.com/EdoardoLaGreca/werc-on-openbsd/releases/tag/v2.0), is to clone plan9port's git repository into the `chroot`'ed filesystem and install it there, with its hard-coded paths adjusted through the `-r` option. Not only this improves the system's security, since patches can be applied immedately, but it also eliminates the need of work-arounds to make hard-coded paths work.
0 commit comments