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