💾 Archived View for envs.net › ~tildebeast › technology › mollybrown-freebsd.gmi captured on 2023-11-14 at 08:35:13. Gemini links have been rewritten to link to archived content
⬅️ Previous capture (2020-10-31)
-=-=-=-=-=-=-
Caveat: these notes are exactly that. They embody the 'Well, it worked for me' ethos. Please don't expect a full set of instructions, and do not expect everything here to work first time on your own host. That said, if I remember something or spot an error I will update this page. Contact details are given at the bottom of the page.
The Unsinkable Molly Brown (also referred to here in short form or as 'molly_brown' after the executable name) is a server for the Gemini internet protocol. It was created by Solderpunk.
The repository README includes detailed write-ups for other operating systems, including Linux and OpenBSD. Please refer to it for details on server configuration options, redirects, the handling of certificates, shared hosting and much more. Please consider the Molly Brown README as definitive, and the document you are reading as merely a set of notes.
Create the special user and group 'gemini', with a home path of '/nonexistent' and a shell of '/usr/sbin/nologin'
Create a server root directory of '/usr/local/gemini/', with the default ownership of 'root:wheel'.
Inside that server root directory, create a site directory('<sitename>' for these notes). Assign ownership to 'gemini:gemini' using the 'chown' command.
Inside your home directory, create a directory called 'gemini'.
Add a line to /etc/fstab (editing as root):
/usr/local/gemini/<sitename> /home/<myusername>/gemini nullfs rw,uid=<my-uid>,gid=<my-gid> 0 0
Replace the variables <sitename>, <myusername>, <my-uid> and <my-gid> as appropriate for your system.
This sets up a nullfs connection between your gemini site directory and a convenient, user-editable directory in your home.
As root, run:
mount -a
As your own user, change directories to '~/gemini', then enter:
touch index.gmi
If there is a 'permission denied' error, check the permissions on '~/gemini', and use the 'mount' command to check that the folder is properly mounted
If you have not installed the 'go' langauge, either use the package manager as root, which may install a slightly older version of the go language:
pkg install go
Alternatively, you can install go manually. Here's a tutorial:
How to install Golang in FreeBSD in 5 minutes
I strongly recommend following the developer's instructions here:
Pay attention to the developer's notes on setting up the $GOPATH variable before fetching and building.
Note that Molly Brown has one external dependency, which must be installed:
TOML parser and encoder for Go with reflection
After a successful build, I copied the 'molly-brown' executable to '/usr/local/bin/' (as root) to make it available to other users, and checked that it had execution permissions. Other system-wide directories are possible, but this guide will assume that you do the same.
The world -- particularly the LetsEncrypt certificate service and Gemini clients, will need to find your site.
Ensure that the DNS records for your desired site (for example, 'gemini.mylovelydomain.net') point to the server on which you are setting up Molly Brown. It cannot be stressed enough that this is really quite important.
You may be in control of your DNS records, or you may need to ask for assistance from your hosting provider.
NB: it may take a while (up to several days in some cases) for the new record to be recognised by DNS nameservers everywhere.
Gemini requires TLS certificates. You can roll your own:
FreeBSD manual page on OpenSSL certificates
It is preferable to use a service such as LetsEncrypt to create certificates that can be renewed on demand.
The official guide to installing and using certbot for FreeBSD is here:
Installing Certbot for 'FreeBSD Other'
Pay special attention to the section on setting up a crontab entry to automate the renewal of your certificates.
I used the following crontab entry (in /etc/crontab):
0 0 * * * date >> /var/log/letsencrypt.log && certbot renew >> /var/log/letsencrypt.log
Note that you might want to adjust the time of execution away from '0 0' (midnight).
NB: certbot does not -- and will not -- install certificates to a custom path, which is a pain for those of us running servers as non-root users. You will need to copy the certificates from where they are installed by certbot to a path useful to your Molly Brown server.
- As root, create the directory '/usr/local/gemcerts'.
- Within this, create a subdirectory for your site, such as 'gemini.mylovelydomain.net'. Use chown to change the ownership of this subdirectory to gemini:gemini
- Manually copy the files from ls /usr/local/etc/letsencrypt/live/gemini.mylovelydomain.net/ to /usr/local/gemcerts/gemini.mylovelydomain.net (taking care to change the final part of each path to reflect the URL you've chosen for your site.
- Use chown to change ownership of the files in /usr/local/gemcerts/gemini.mylovelydomain.net to gemini:gemini
This copy process can be automated. Here is an example script:
#!/bin/sh
echo "Copying over new gemini certs if requried..."
find /usr/local/etc/letsencrypt/live/gemini.mylovelydomain.net -mtime -6 -name "*.pem" -exec cp {} /usr/local/gemcerts/gemini.mylovelydomain.net/ \;
chown gemini:gemini /usr/local/gemcerts/gemini.mylovelydomain.net/*.pem
echo "Done."
exit 0
The script will copy any '.pem' (certificate) files created in the last 6 days to your gemini certificates path, and will reassign ownership so that your molly_brown server can read them.
Place it in your weekly 'periodic' folder in a file such as '/usr/local/etc/periodic/weekly/501.copy_gemini_certs', and ensure the script file is executable using 'chmod'.
As root, create /usr/local/etc/molly_brown.conf. These are the rather basic settings that I used:
Port = 1965 Hostname = "gemini.mylovelydomain.net" CertPath = "/usr/local/gemcerts/gemini.mylovelydomain.net/fullchain.pem" KeyPath = "/usr/local/gemcerts/gemini.mylovelydomain.net/privkey.pem" DocBase = "/usr/local/gemini/gemini.mylovelydomain.net" AccessLog = "/var/log/gemini/access.log" ErrorLog = "/var/log/gemini/error.log"
Change 'gemini.mylovelydomain.net' to the site specified in your DNS records. I am assuming you use the same name for all relevant subdirectories.
Note that the settings above require logs in '/var/log/gemini'. As root, create this subdirectory and set ownership to root:gemini. You may want to create the log files themselves using 'touch' and assign them the same ownership.
Log files should not grow uncontrollably, as this can fill up your storage space. Consider using the newsyslog service to rotate files above a certain size.
To do this, save the following as root to '/etc/newsyslog.conf.d/molly_brown_syslog.conf':
# Log rotation settings for the molly_brown gemini server. # Adjust according to the paths and names specified in your molly_brown.conf file. # # These defaults will rotate to a new log file when the current one exceeds 100K, # and will store seven files. # # logfilename [owner:group] mode count size when flags [/pid_file] [sig_num] /var/log/gemini/access.log root:gemini 644 7 100 * JN /var/log/gemini/error.log root:gemini 644 7 100 * JN
You can learn more about the settings from these man pages:
By default, Molly Brown runs as a regular process. You will probably want to ensure that it starts at bootup at least.
As root, save the following to the file /usr/local/etc/rc.d/molly_brown:
#!/bin/sh
#
# $FreeBSD$
#
# PROVIDE: molly_brown
# REQUIRE: NETWORKING SYSLOG
# KEYWORD: shutdown
#
# Add the following lines to /etc/rc.conf to enable molly_brown:
#
# molly_brown_enable="YES"
#
# The prefix var is a total fudge. It should depend on a makefile value %%PREFIX%%
. /etc/rc.subr
name="molly_brown"
rcvar="molly_brown_enable"
load_rc_config $name
: ${molly_brown_prefix:="/usr/local"}
: ${molly_brown_user:="gemini"}
: ${molly_brown_enable:="NO"}
: ${molly_brown_facility:="daemon"}
: ${molly_brown_config:="molly_brown.conf"}
command="${molly_brown_prefix}/bin/${name} -c ${molly_brown_prefix}/etc/${molly_brown_config}"
pidfile="/var/run/${name}.pid"
start_cmd="${name}_start"
molly_brown_start() {
/usr/sbin/daemon -u ${molly_brown_user} -p ${pidfile} \
/usr/bin/env -i \
"PATH=${molly_brown_prefix}/bin:${PATH}" \
"USER=${molly_brown_user}" \
$command
}
run_rc_command "$1"
The file above is horribly basic. If you are good at writing and debugging rc files, please write a better one, test it, and email it to me for inclusion here with full acknowledgement.
Once you have saved the file, please add the following line to your /etc/rc.conf file:
molly_brown_enable="YES"
As root, you can then start the server using:
/usr/local/etc/rc.d/molly_brown
Use the 'ps' command to see if molly_brown started correctly.
Fire up your favourite gemini client and try to load your site, for example 'gemini://gemini.mylovelydomain.net'.
If all is well, your 'index.gmi' file (as created earlier) should be loaded.
This is a working draft.
I am neither a professional sysadmin nor developer. If you have comments and suggestions for improving this document, please email me at: