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