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