1.\"
  2.\" Copyright (c) 2019 Ted Unangst
  3.\"
  4.\" Permission to use, copy, modify, and distribute this software for any
  5.\" purpose with or without fee is hereby granted, provided that the above
  6.\" copyright notice and this permission notice appear in all copies.
  7.\"
  8.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
  9.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
 10.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
 11.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
 12.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
 13.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
 14.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 15.\"
 16.Dd $Mdocdate$
 17.Dt HONK 8
 18.Os
 19.Sh NAME
 20.Nm honk
 21.Nd honk administration
 22.Sh DESCRIPTION
 23The
 24.Nm
 25daemon processes messages from other federated servers.
 26This is the admin manual.
 27For user operation, see
 28.Xr honk 1 .
 29.Ss Setup
 30.Pp
 31Set up a TLS reverse proxy.
 32.Nm
 33can listen on TCP or unix sockets, but will not terminate TLS.
 34https is a required component for federation.
 35Also, http signature verification requires accurate time keeping.
 36.Pp
 37Make sure to pass the Host header, if necessary (as for nginx).
 38.Bd -literal -offset indent
 39proxy_set_header Host $http_host;
 40.Ed
 41.Ss Build
 42Building
 43.Nm
 44requires a go compiler 1.18 and libsqlite.
 45On
 46.Ox
 47this is the go and sqlite3 packages.
 48Other platforms may require additional development libraries or headers
 49to be installed.
 50Run make.
 51Please be patient.
 52Even on fast machines, building from source can take several seconds.
 53.Ss Options
 54The following options control where
 55.Nm
 56looks for data.
 57.Bl -tag -width datadirxdirx
 58.It Fl datadir Ar dir
 59The root data directory, where the database and other user data are stored.
 60This directory contains all user data that persists across upgrades.
 61Requires write access.
 62Defaults to ".".
 63.It Fl viewdir Ar dir
 64The root view directory, where html and other templates are stored.
 65The contents of this directory are generally replaced with each release.
 66Read only.
 67Defaults to ".".
 68.El
 69.Pp
 70The following options control log output.
 71Acceptable values include "stderr" (the default), "stdout", "null", "syslog",
 72or a file name.
 73syslog messages will be sent to the UUCP facility.
 74.Bl -tag -width errorlogxlogx
 75.It Fl errorlog Ar log
 76The error log.
 77Something bad has happened.
 78.It Fl infolog Ar log
 79The informative messages log.
 80Something has happened, but probably not too bad.
 81.It Fl debuglog Ar log
 82The debug log.
 83There's probably no reason to care.
 84.It Fl log Ar log
 85Set all three logs.
 86.El
 87.Ss Init
 88Run the
 89.Ic init
 90command.
 91This will create the database and ask four questions, as well as creating
 92the initial user.
 93See below about importing existing data.
 94.Ss Operation
 95Run honk.
 96.Ss Customization
 97The funzone contains fun flair that users may add to posts and profiles.
 98Add custom memes (stickers) to the
 99.Pa memes
100data directory.
101Image and video files are supported.
102Add custom emus (emoji) to the
103.Pa emus
104data directory.
105PNG and GIF files are supported.
106.Pp
107Site CSS may be overridden by creating a
108.Pa views/local.css
109file in the data directory.
110Site JS may similarly be included by creating
111.Pa views/local.js .
112A restart is required after changes.
113A site icon.png and favicon.ico will be served from the views directory
114in the data directory, if present.
115.Pp
116Custom HTML messages may be added to select pages by using the
117.Ic admin
118command.
119This interface is a little rough.
120A restart is required after changes.
121.Bl -tag -width tenletters
122.It server
123Displayed on the home page.
124.It about
125Displayed on the about page.
126.It login
127Displayed on the login form.
128.It avatar colors
129Four 32-bit hex colors (RGBA).
130.El
131.Pp
132.Ss User Admin
133New users can be added with the
134.Ic adduser
135command.
136This is discouraged.
137.Pp
138Passwords may be reset with the
139.Ic chpass Ar username
140command.
141.Pp
142Users may be deleted with the
143.Ic deluser Ar username
144command.
145.Pp
146Follow and unfollow requests can be sent via command line with
147.Ic follow Ar username Ar url
148and
149.Ic unfollow Ar username Ar url .
150.Ss Maintenance
151The database may grow large over time.
152The
153.Ic cleanup Op Ar days
154command exists to purge old external data, by default 30 days.
155This removes unreferenced, unsaved posts and attachments.
156It does not remove any original content.
157This will not immediately reduce the size of the database, but frees space
158for future use.
159A vacuum may be performed manually if necessary, but will require more time
160and additional disk space.
161.Pp
162Backups may be performed by running
163.Ic backup dirname .
164Backups only include the minimal necessary information, such as user posts
165and follower information, but not external posts.
166.Pp
167Sometimes servers simply disappear, resulting in many errors trying to deliver
168undeliverable messages.
169Running
170.Ic unplug Ar hostname
171will delete all subscriptions and pending deliveries.
172.Ss Upgrade
173Stop the old honk process.
174Backup the database.
175Perform the upgrade with the
176.Ic upgrade
177command.
178Restart.
179.Pp
180The current version of the honk binary may be printed with the
181.Ic version
182command.
183.Ss Security
184.Nm
185is not currently hardened against SSRF, server side request forgery.
186Be mindful of what other services may be exposed via localhost or the
187local network.
188.Ss Development
189Development mode may be enabled or disabled by running
190.Ic devel Ar on|off .
191In devel mode, secure cookies are disabled, TLS certs are not verified,
192and templates are reloaded every request.
193.Ss Import
194Data may be imported and converted from other services using the
195.Ic import
196command.
197Currently supports Honk, Mastodon, Twitter, and Instagram exported data.
198Posts are imported and backdated to appear as old honks.
199The Mastodon following list is imported, but must be refollowed.
200.Pp
201To prepare a Honk data archive, extract the export.zip file.
202.Dl ./honk import username honk source-directory
203.Pp
204To prepare a Mastodon data archive, extract the archive-longhash.tar.gz file.
205.Dl ./honk import username mastodon source-directory
206.Pp
207To prepare a Twitter data archive, extract the twitter-longhash.zip file.
208After unzipping the data archive, navigate to the tweet_media directory
209and unzip any zip files contained within.
210.Dl ./honk import username twitter source-directory
211.Pp
212To prepare an Instagram data archive, extract the igusername.zip file.
213.Dl ./honk import username instagram source-directory
214.Ss Export
215User data may be exported to a zip archive using the
216.Ic export
217command.
218This will export the user's outbox and inbox in ActvityPub json format,
219along with associated media.
220.Dl ./honk export username zipname
221.Ss Advanced Options
222Advanced configuration values may be set by running the
223.Ic setconfig Ar key value
224command.
225For example, to increase the fast timeout value from 5 seconds to 10:
226.Dl ./honk setconfig fasttimeout 10
227.Pp
228To support separate mentions without a subdomain,
229e.g. @user@example.com and https://honk.example.com/u/user,
230set config key 'masqname' to 'example.com'.
231Route
232.Pa /.well-known/webfinger
233from the top domain to honk.
234.Pp
235Custom URL seperators (not "u" and "h") may be specified by adding
236"usersep" and "honksep" options to the config table.
237e.g. example.com/users/username/honk/somehonk instead of
238example.com/u/username/h/somehonk.
239.Sh FILES
240.Nm
241files are split between the data directory and the view directory.
242Both default to "." but may be specified by command line options.
243.Pp
244The data directory contains:
245.Bl -tag -width views/local.css
246.It Pa honk.db
247The main database.
248.It Pa blob.db
249Media and attachment storage.
250.It Pa emus
251Custom emoji.
252.It Pa memes
253Stickers and such.
254.It Pa views/local.js
255Locally customized JS.
256.It Pa views/local.css
257Locally customized CSS.
258.El
259.Pp
260The view directory contains:
261.Bl -tag -width views
262.It Pa views
263HTML templates and CSS files.
264.El
265.Sh EXAMPLES
266This series of commands creates a new database, sets a friendly
267welcome message, and runs honk.
268.Bd -literal -offset indent
269honk-v98> make
270honk-v98> ./honk -datadir ../honkdata init
271username: puffy
272password: OxychromaticBlowfishSwatDynamite
273listen address: /var/www/honk.sock
274server name: honk.example.com
275honk-v98> ./honk -datadir ../honkdata admin
276honk-v98> date; ./honk -log honk.log -datadir ../honkdata
277.Ed
278.Pp
279The views directory includes a sample mastodon.css to change color scheme.
280.Bd -literal -offset indent
281honk-v98> mkdir ../honkdata/views
282honk-v98> cp views/mastodon.css ../honkdata/views/local.css
283.Ed
284.Pp
285Upgrade to the next version.
286Clean things up a bit.
287.Bd -literal -offset indent
288datadir> cp honk.db backup.db
289datadir> cd ../honk-v99
290honk-v99> make
291honk-v99> ./honk -datadir ../honkdata upgrade
292honk-v99> ./honk -datadir ../honkdata cleanup
293honk-v99> date; ./honk -log honk.log -datadir ../honkdata
294.Ed
295.Sh ENVIRONMENT
296Image processing and scaling requires considerable memory.
297It is recommended to adjust the datasize ulimit to at least 1GB.
298.Sh SEE ALSO
299.Xr intro 1 ,
300.Xr honk 1
301.Sh CAVEATS
302There's no online upgrade capability.
303Upgrades may result in minutes of downtime.