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