HONK(8) | System Manager's Manual | HONK(8)

# 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;

## Build

Building `honk` requires a go compiler 1.13 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`
  The root data directory, where the database and other user data are stored. Requires write access. Defaults to ".".
`-viewdir`
  The root view directory, where html and other templates are stored. Read only. Defaults to ".".

## 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. Log messages are sent to stderr and should probably be redirected to a file.

## Customization

Add custom memes (stickers) to the memes data directory. Image and video files are supported.

Add custom emus (emoji) to the emus data directory. Image files are supported.

Site CSS may be overridden by creating a views/local.css file in the data directory. A restart is required after changes.

Custom HTML messages may be added to select pages by using the `admin` command. A restart is required after changes.

server
  Displayed on the home page.
about
  Displayed on the about page.
login
  Displayed about 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.

## Maintenance

The database may grow large over time. The `cleanup` [days] command exists to purge old data, by default 30 days. This removes unreferenced, unsaved posts and attachments. It does not remove any original content.

Backups may be performed by running `backup dirname`. Backups only include the minimal necessary information.

## 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.

## unplug

Sometimes servers simply disappear, resulting in many errors trying to deliver undeliverable messages. Running `unplug` hostname will delete all subscriptions and pending deliveries.

## 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.

## Debug

Debug mode may be enabled or disabled by running `debug` on|off. In debug mode, secure cookies are disabled and templates are reloaded every request. Debug mode is really more useful for development, not debugging production.

## Import

Data may be imported and converted from other services using the `import` command. Posts are imported and backdated to appear as old honks. No other information is imported. Currently supports Mastodon and Twitter exported data.

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`

## Advanced Options

To support separate mentions without a subdomain, e.g. @user@example.com and https://honk.example.com/u/user, add a ('masqname', 'example.com') row to the config table of the database. 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.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 -datadir ../honkdata >> log 2>&1

The views directory includes a sample pleroma.css to change color scheme.

    honk-v98> mkdir ../honkdata/views
    honk-v98> cp views/pleroma.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 -datadir ../honkdata >> log 2>&1

# ENVIRONMENT

Image processing and scaling requires considerable memory. It is recommended to adjust the datasize ulimit to at least 1GB.

# SEE ALSO

intro(1), honk(1)

# CAVEATS

There's no online upgrade capability. Upgrades may result in minutes of downtime.

December 10, 2020 | OpenBSD 6.7