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.13 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 files are supported.
106.Pp
107Site CSS may be overridden by creating a
108.Pa views/local.css
109file in the data directory.
110A restart is required after changes.
111.Pp
112Custom HTML messages may be added to select pages by using the
113.Ic admin
114command.
115This interface is a little rough.
116A restart is required after changes.
117.Bl -tag -width tenletters
118.It server
119Displayed on the home page.
120.It about
121Displayed on the about page.
122.It login
123Displayed on the login form.
124.It avatar colors
125Four 32-bit hex colors (RGBA).
126.El
127.Pp
128.Ss User Admin
129New users can be added with the
130.Ic adduser
131command.
132This is discouraged.
133.Pp
134Passwords may be reset with the
135.Ic chpass Ar username
136command.
137.Pp
138Users may be deleted with the
139.Ic deluser Ar username
140command.
141.Ss Maintenance
142The database may grow large over time.
143The
144.Ic cleanup Op Ar days
145command exists to purge old external data, by default 30 days.
146This removes unreferenced, unsaved posts and attachments.
147It does not remove any original content.
148.Pp
149Backups may be performed by running
150.Ic backup dirname .
151Backups only include the minimal necessary information, such as user posts
152and follower information, but not external posts.
153.Ss Upgrade
154Stop the old honk process.
155Backup the database.
156Perform the upgrade with the
157.Ic upgrade
158command.
159Restart.
160.Pp
161The current version of the honk binary may be printed with the
162.Ic version
163command.
164.Ss unplug
165Sometimes servers simply disappear, resulting in many errors trying to deliver
166undeliverable messages.
167Running
168.Ic unplug Ar hostname
169will delete all subscriptions and pending deliveries.
170.Ss Security
171.Nm
172is not currently hardened against SSRF, server side request forgery.
173Be mindful of what other services may be exposed via localhost or the
174local network.
175.Ss Debug
176Debug mode may be enabled or disabled by running
177.Ic debug Ar on|off .
178In debug mode, secure cookies are disabled and templates are reloaded
179every request.
180Debug mode is really more useful for development, not debugging production.
181.Ss Import
182Data may be imported and converted from other services using the
183.Ic import
184command.
185Posts are imported and backdated to appear as old honks.
186No other information is imported.
187Currently supports Mastodon and Twitter exported data.
188.Pp
189To prepare a Mastodon data archive, extract the archive-longhash.tar.gz file.
190.Dl ./honk import username mastodon source-directory
191.Pp
192To prepare a Twitter data archive, extract the twitter-longhash.zip file.
193After unzipping the data archive, navigate to the tweet_media directory
194and unzip any zip files contained within.
195.Dl ./honk import username twitter source-directory
196.Ss Advanced Options
197To support separate mentions without a subdomain,
198e.g. @user@example.com and https://honk.example.com/u/user,
199add a ('masqname', 'example.com') row to the config table of the database.
200Route
201.Pa /.well-known/webfinger
202from the top domain to honk.
203.Pp
204Custom URL seperators (not "u" and "h") may be specified by adding
205"usersep" and "honksep" options to the config table.
206e.g. example.com/users/username/honk/somehonk instead of
207example.com/u/username/h/somehonk.
208.Sh FILES
209.Nm
210files are split between the data directory and the view directory.
211Both default to "." but may be specified by command line options.
212.Pp
213The data directory contains:
214.Bl -tag -width views/local.css
215.It Pa honk.db
216The main database.
217.It Pa blob.db
218Media and attachment storage.
219.It Pa emus
220Custom emoji.
221.It Pa memes
222Stickers and such.
223.It Pa views/local.css
224Locally customized CSS.
225.El
226.Pp
227The view directory contains:
228.Bl -tag -width views
229.It Pa views
230HTML templates and CSS files.
231.El
232.Sh EXAMPLES
233This series of commands creates a new database, sets a friendly
234welcome message, and runs honk.
235.Bd -literal -offset indent
236honk-v98> make
237honk-v98> ./honk -datadir ../honkdata init
238username: puffy
239password: OxychromaticBlowfishSwatDynamite
240listen address: /var/www/honk.sock
241server name: honk.example.com
242honk-v98> ./honk -datadir ../honkdata admin
243honk-v98> date; ./honk -datadir ../honkdata >> log 2>&1
244.Ed
245.Pp
246The views directory includes a sample pleroma.css to change color scheme.
247.Bd -literal -offset indent
248honk-v98> mkdir ../honkdata/views
249honk-v98> cp views/pleroma.css ../honkdata/views/local.css
250.Ed
251.Pp
252Upgrade to the next version.
253Clean things up a bit.
254.Bd -literal -offset indent
255datadir> cp honk.db backup.db
256datadir> cd ../honk-v99
257honk-v99> make
258honk-v99> ./honk -datadir ../honkdata upgrade
259honk-v99> ./honk -datadir ../honkdata cleanup
260honk-v99> date; ./honk -datadir ../honkdata >> log 2>&1
261.Ed
262.Sh ENVIRONMENT
263Image processing and scaling requires considerable memory.
264It is recommended to adjust the datasize ulimit to at least 1GB.
265.Sh SEE ALSO
266.Xr intro 1 ,
267.Xr honk 1
268.Sh CAVEATS
269There's no online upgrade capability.
270Upgrades may result in minutes of downtime.