HONK(8)

💖 HONK(8) — honk administration 💖

okay so this is the HONK(8) page, aka the System Manager's Manual entry for honk administration. bestie, it's giving "everything you need to run the thing" energy, and we're gonna go through it together. 💅✨

🎀 NAME 🎀

honk — honk administration. that's the vibe. 🫶

🌸 DESCRIPTION 🌸

The honk daemon processes messages from other federated servers. This is the admin manual. For user operation, see honk(1). lowkey important distinction, iykyk.

🛠️ 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. no cap. ⏰

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.22+ and libsqlite 3.34.0+. 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. fr fr, give it a sec. 🧚

✨ 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 ".". Also set by HONK_DATADIR.
• -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 ".". Also set by HONK_VIEWDIR.

The following options control log output.

• -log logfile — Log to file logfile. The special name "syslog" logs to the UUCP facility. The special names "stdout" and "-" log to standard output. The default is stderr.
• -debug — Enable absurdly verbose debug logging. not me using this and drowning in output 😭

🌱 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. that's it. main character energy. 👑

🎨 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. obsessed. 🍓

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.

🗄️ Storage 🗄️

By default, honk will store attachments in a file system directory structure, attachments. Previous versions stored files in a database, blob.db. Related commands:

• storefiles — Switch to storing attachments in the file system.
• storeblobs — Switch to storing attachments in the blob.db.
• extractblobs — Copy blobs from the blob.db into the file system. Running cleanup first will reduce the time and space required.

🧹 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. bestie, vacuuming is not a quick lil refresh, okay? 😭

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 ⬆️

Safe and slow: Stop the old honk process. Backup the database. Perform the upgrade with the upgrade command. Restart.

Web scale alternative: Send SIGHUP.

pkill -HUP honk

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. this is a real warning, not a vibe check to ignore. 💀

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

• convertavif — If libavif can be loaded, convert JPEG images to AVIF. May reduce bandwidth requirements.
• acceptavif — If libavif can be loaded, also accept AVIF images. If libheif can be loaded, also accept HEIC images.
• fasttimeout — Short timeout for fetching activities. (Default: 5)
• slowtimeout — Long timeout for posting actvities. (Default: 30)
• honkwindow — How many days to display in a timeline. (Default: 7)
• collectforwards — Fetch reply actvities forwarded from other servers. (Default: true)
• usersep — (Default: u)
• honksep — (Default: h)

📁 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.
• attachments — Media and attachment storage.
• blob.db — Old location for 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. bestie, your images need room to breathe. 🌈

honk will respond to SIGHUP by restarting a new process.

🫶 SEE ALSO 🫶

• intro(1)
• honk(1)

---

that's the whole page, bestie — source/version/date vibes: Debian, $Mdocdate$, HONK(8). slay. 💅✨