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