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