NAME
honk
—
honk administration
DESCRIPTION
The honk
daemon processes messages from
other federated servers. This is the admin manual. For user operation, see
honk(1).
Setup
Set up a TLS reverse proxy. honk
can
listen on TCP or unix sockets, but will not terminate TLS. https is a
required component for federation. Also, http signature verification
requires accurate time keeping.
Make sure to pass the Host header, if necessary (as for nginx).
proxy_set_header Host $http_host;
FastCGI can be used by prefixing the listen address with "fcgi:".
Build
Building honk
requires a go compiler 1.18
and libsqlite. On OpenBSD this is the go and sqlite3
packages. Other platforms may require additional development libraries or
headers to be installed. Run make. Please be patient. Even on fast machines,
building from source can take several seconds.
Options
The following options control where honk
looks for data.
-datadir
dir- The root data directory, where the database and other user data are stored. This directory contains all user data that persists across upgrades. Requires write access. Defaults to ".".
-viewdir
dir- The root view directory, where html and other templates are stored. The contents of this directory are generally replaced with each release. Read only. Defaults to ".".
The following options control log output. Acceptable values include "stderr" (the default), "stdout", "null", "syslog", or a file name. syslog messages will be sent to the UUCP facility.
Init
Run the init
command. This will create the
database and ask four questions, as well as creating the initial user. See
below about importing existing data.
Operation
Run honk.
Customization
The funzone contains fun flair that users may add to posts and profiles. Add custom memes (stickers) to the memes data directory. Image and video files are supported. Add custom emus (emoji) to the emus data directory. PNG and GIF files are supported.
Site CSS may be overridden by creating a views/local.css file in the data directory. Site JS may similarly be included by creating views/local.js. A restart is required after changes. A site icon.png and favicon.ico will be served from the views directory in the data directory, if present.
Custom HTML messages may be added to select pages by using the
admin
command. This interface is a little rough. A
restart is required after changes.
- server
- Displayed on the home page.
- about
- Displayed on the about page.
- login
- Displayed on the login form.
- avatar colors
- Four 32-bit hex colors (RGBA).
User Admin
New users can be added with the adduser
command. This is discouraged.
Passwords may be reset with the chpass
username command.
Users may be deleted with the deluser
username command.
Follow and unfollow requests can be sent via command line with
follow
username
url and unfollow
username url.
Maintenance
The database may grow large over time. The
cleanup
[days] command exists
to purge old external data, by default 30 days. This removes unreferenced,
unsaved posts and attachments. It does not remove any original content. This
will not immediately reduce the size of the database, but frees space for
future use. A vacuum may be performed manually if necessary, but will
require more time and additional disk space.
Backups may be performed by running backup
dirname
. Backups only include the minimal necessary information, such
as user posts and follower information, but not external posts.
Sometimes servers simply disappear, resulting in many errors
trying to deliver undeliverable messages. Running
unplug
hostname will delete
all subscriptions and pending deliveries.
Upgrade
Stop the old honk process. Backup the database. Perform the
upgrade with the upgrade
command. Restart.
The current version of the honk binary may be printed with the
version
command.
Security
honk
is not currently hardened against
SSRF, server side request forgery. Be mindful of what other services may be
exposed via localhost or the local network.
Development
Development mode may be enabled or disabled by running
devel
on|off. In devel mode,
secure cookies are disabled, TLS certs are not verified, and templates are
reloaded every request.
Import
Data may be imported and converted from other services using the
import
command. Currently supports Honk, Mastodon,
Twitter, and Instagram exported data. Posts are imported and backdated to
appear as old honks. The Mastodon following list is imported, but must be
refollowed.
To prepare a Honk data archive, extract the export.zip file.
./honk import username honk
source-directory
To prepare a Mastodon data archive, extract the archive-longhash.tar.gz file.
./honk import username mastodon
source-directory
To prepare a Twitter data archive, extract the twitter-longhash.zip file. After unzipping the data archive, navigate to the tweet_media directory and unzip any zip files contained within.
./honk import username twitter
source-directory
To prepare an Instagram data archive, extract the igusername.zip file.
./honk import username instagram
source-directory
Export
User data may be exported to a zip archive using the
export
command. This will export the user's outbox
and inbox in ActivityPub json format, along with associated media.
./honk export username
zipname
Advanced Options
Advanced configuration values may be set by running the
setconfig
key value command.
For example, to increase the fast timeout value from 5 seconds to 10:
./honk setconfig fasttimeout
10
To support separate mentions without a subdomain, e.g. @user@example.com and https://honk.example.com/u/user, set config key 'masqname' to 'example.com'. Route /.well-known/webfinger from the top domain to honk.
Custom URL seperators (not "u" and "h") may be specified by adding "usersep" and "honksep" options to the config table. e.g. example.com/users/username/honk/somehonk instead of example.com/u/username/h/somehonk.
FILES
honk
files are split between the data
directory and the view directory. Both default to "." but may be
specified by command line options.
The data directory contains:
- honk.db
- The main database.
- blob.db
- Media and attachment storage.
- emus
- Custom emoji.
- memes
- Stickers and such.
- views/local.js
- Locally customized JS.
- views/local.css
- Locally customized CSS.
The view directory contains:
- views
- HTML templates and CSS files.
EXAMPLES
This series of commands creates a new database, sets a friendly welcome message, and runs honk.
honk-v98> make honk-v98> ./honk -datadir ../honkdata init username: puffy password: OxychromaticBlowfishSwatDynamite listen address: /var/www/honk.sock server name: honk.example.com honk-v98> ./honk -datadir ../honkdata admin honk-v98> date; ./honk -log honk.log -datadir ../honkdata
The views directory includes a sample mastodon.css to change color scheme.
honk-v98> mkdir ../honkdata/views honk-v98> cp views/mastodon.css ../honkdata/views/local.css
Upgrade to the next version. Clean things up a bit.
datadir> cp honk.db backup.db datadir> cd ../honk-v99 honk-v99> make honk-v99> ./honk -datadir ../honkdata upgrade honk-v99> ./honk -datadir ../honkdata cleanup honk-v99> date; ./honk -log honk.log -datadir ../honkdata
ENVIRONMENT
Image processing and scaling requires considerable memory. It is recommended to adjust the datasize ulimit to at least 1GB.
SEE ALSO
CAVEATS
There's no online upgrade capability. Upgrades may result in minutes of downtime.