295 lines
14 KiB
HTML
295 lines
14 KiB
HTML
<!DOCTYPE html>
|
|
<html>
|
|
<!-- This is an automatically generated file. Do not edit.
|
|
Copyright (c) 2019 Ted Unangst
|
|
|
|
Permission to use, copy, modify, and distribute this software for any
|
|
purpose with or without fee is hereby granted, provided that the above
|
|
copyright notice and this permission notice appear in all copies.
|
|
|
|
THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
|
|
WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
|
|
MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
|
|
ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
|
|
WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
|
|
ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
|
|
OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
|
|
-->
|
|
<head>
|
|
<meta charset="utf-8"/>
|
|
<meta name="viewport" content="width=device-width, initial-scale=1.0"/>
|
|
<link rel="stylesheet" href="mandoc.css" type="text/css" media="all"/>
|
|
<title>HONK(8)</title>
|
|
</head>
|
|
<body>
|
|
<table class="head">
|
|
<tr>
|
|
<td class="head-ltitle">HONK(8)</td>
|
|
<td class="head-vol">System Manager's Manual</td>
|
|
<td class="head-rtitle">HONK(8)</td>
|
|
</tr>
|
|
</table>
|
|
<div class="manual-text">
|
|
<section class="Sh">
|
|
<h1 class="Sh" id="NAME"><a class="permalink" href="#NAME">NAME</a></h1>
|
|
<p class="Pp"><code class="Nm">honk</code> — <span class="Nd">honk
|
|
administration</span></p>
|
|
</section>
|
|
<section class="Sh">
|
|
<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1>
|
|
<p class="Pp">The <code class="Nm">honk</code> daemon processes messages from
|
|
other federated servers. This is the admin manual. For user operation, see
|
|
<a class="Xr" href="honk.1.html">honk(1)</a>.</p>
|
|
<section class="Ss">
|
|
<h2 class="Ss" id="Setup"><a class="permalink" href="#Setup">Setup</a></h2>
|
|
<p class="Pp">Set up a TLS reverse proxy. <code class="Nm">honk</code> can
|
|
listen on TCP or unix sockets, but will not terminate TLS. https is a
|
|
required component for federation. Also, http signature verification
|
|
requires accurate time keeping.</p>
|
|
<p class="Pp">Make sure to pass the Host header, if necessary (as for
|
|
nginx).</p>
|
|
<div class="Bd Pp Bd-indent Li">
|
|
<pre>proxy_set_header Host $http_host;</pre>
|
|
</div>
|
|
</section>
|
|
<section class="Ss">
|
|
<h2 class="Ss" id="Build"><a class="permalink" href="#Build">Build</a></h2>
|
|
<p class="Pp">Building <code class="Nm">honk</code> requires a go compiler 1.13
|
|
and libsqlite. On <span class="Ux">OpenBSD</span> this is the go and sqlite3
|
|
packages. Other platforms may require additional development libraries or
|
|
headers to be installed. Run make. Please be patient. Even on fast machines,
|
|
building from source can take several seconds.</p>
|
|
</section>
|
|
<section class="Ss">
|
|
<h2 class="Ss" id="Options"><a class="permalink" href="#Options">Options</a></h2>
|
|
<p class="Pp">The following options control where <code class="Nm">honk</code>
|
|
looks for data.</p>
|
|
<dl class="Bl-tag">
|
|
<dt id="datadir"><a class="permalink" href="#datadir"><code class="Fl">-datadir</code></a>
|
|
<var class="Ar">dir</var></dt>
|
|
<dd>The root data directory, where the database and other user data are
|
|
stored. This directory contains all user data that persists across
|
|
upgrades. Requires write access. Defaults to ".".</dd>
|
|
<dt id="viewdir"><a class="permalink" href="#viewdir"><code class="Fl">-viewdir</code></a>
|
|
<var class="Ar">dir</var></dt>
|
|
<dd>The root view directory, where html and other templates are stored. The
|
|
contents of this directory are generally replaced with each release. Read
|
|
only. Defaults to ".".</dd>
|
|
</dl>
|
|
<p class="Pp">The following options control log output. Acceptable values
|
|
include "stderr" (the default), "stdout",
|
|
"null", "syslog", or a file name. syslog messages will
|
|
be sent to the UUCP facility.</p>
|
|
<dl class="Bl-tag">
|
|
<dt id="errorlog"><a class="permalink" href="#errorlog"><code class="Fl">-errorlog</code></a>
|
|
<var class="Ar">log</var></dt>
|
|
<dd>The error log. Something bad has happened.</dd>
|
|
<dt id="infolog"><a class="permalink" href="#infolog"><code class="Fl">-infolog</code></a>
|
|
<var class="Ar">log</var></dt>
|
|
<dd>The informative messages log. Something has happened, but probably not too
|
|
bad.</dd>
|
|
<dt id="debuglog"><a class="permalink" href="#debuglog"><code class="Fl">-debuglog</code></a>
|
|
<var class="Ar">log</var></dt>
|
|
<dd>The debug log. There's probably no reason to care.</dd>
|
|
<dt id="log"><a class="permalink" href="#log"><code class="Fl">-log</code></a>
|
|
<var class="Ar">log</var></dt>
|
|
<dd>Set all three logs.</dd>
|
|
</dl>
|
|
</section>
|
|
<section class="Ss">
|
|
<h2 class="Ss" id="Init"><a class="permalink" href="#Init">Init</a></h2>
|
|
<p class="Pp">Run the <code class="Ic">init</code> command. This will create the
|
|
database and ask four questions, as well as creating the initial user. See
|
|
below about importing existing data.</p>
|
|
</section>
|
|
<section class="Ss">
|
|
<h2 class="Ss" id="Operation"><a class="permalink" href="#Operation">Operation</a></h2>
|
|
<p class="Pp">Run honk.</p>
|
|
</section>
|
|
<section class="Ss">
|
|
<h2 class="Ss" id="Customization"><a class="permalink" href="#Customization">Customization</a></h2>
|
|
<p class="Pp">The funzone contains fun flair that users may add to posts and
|
|
profiles. Add custom memes (stickers) to the <span class="Pa">memes</span>
|
|
data directory. Image and video files are supported. Add custom emus (emoji)
|
|
to the <span class="Pa">emus</span> data directory. PNG and GIF files are
|
|
supported.</p>
|
|
<p class="Pp">Site CSS may be overridden by creating a
|
|
<span class="Pa">views/local.css</span> file in the data directory. Site JS
|
|
may similarly be included by creating
|
|
<span class="Pa">views/local.js</span>. A restart is required after changes.
|
|
A site icon.png and favicon.ico will be served from the views directory in
|
|
the data directory, if present.</p>
|
|
<p class="Pp">Custom HTML messages may be added to select pages by using the
|
|
<code class="Ic">admin</code> command. This interface is a little rough. A
|
|
restart is required after changes.</p>
|
|
<dl class="Bl-tag">
|
|
<dt>server</dt>
|
|
<dd>Displayed on the home page.</dd>
|
|
<dt>about</dt>
|
|
<dd>Displayed on the about page.</dd>
|
|
<dt>login</dt>
|
|
<dd>Displayed on the login form.</dd>
|
|
<dt>avatar colors</dt>
|
|
<dd>Four 32-bit hex colors (RGBA).</dd>
|
|
</dl>
|
|
</section>
|
|
<section class="Ss">
|
|
<h2 class="Ss" id="User_Admin"><a class="permalink" href="#User_Admin">User
|
|
Admin</a></h2>
|
|
<p class="Pp">New users can be added with the <code class="Ic">adduser</code>
|
|
command. This is discouraged.</p>
|
|
<p class="Pp">Passwords may be reset with the <code class="Ic">chpass</code>
|
|
<var class="Ar">username</var> command.</p>
|
|
<p class="Pp">Users may be deleted with the <code class="Ic">deluser</code>
|
|
<var class="Ar">username</var> command.</p>
|
|
</section>
|
|
<section class="Ss">
|
|
<h2 class="Ss" id="Maintenance"><a class="permalink" href="#Maintenance">Maintenance</a></h2>
|
|
<p class="Pp">The database may grow large over time. The
|
|
<code class="Ic">cleanup</code> [<var class="Ar">days</var>] command exists
|
|
to purge old external data, by default 30 days. This removes unreferenced,
|
|
unsaved posts and attachments. It does not remove any original content.</p>
|
|
<p class="Pp">Backups may be performed by running <code class="Ic">backup
|
|
dirname</code>. Backups only include the minimal necessary information, such
|
|
as user posts and follower information, but not external posts.</p>
|
|
<p class="Pp">Sometimes servers simply disappear, resulting in many errors
|
|
trying to deliver undeliverable messages. Running
|
|
<code class="Ic">unplug</code> <var class="Ar">hostname</var> will delete
|
|
all subscriptions and pending deliveries.</p>
|
|
</section>
|
|
<section class="Ss">
|
|
<h2 class="Ss" id="Upgrade"><a class="permalink" href="#Upgrade">Upgrade</a></h2>
|
|
<p class="Pp">Stop the old honk process. Backup the database. Perform the
|
|
upgrade with the <code class="Ic">upgrade</code> command. Restart.</p>
|
|
<p class="Pp">The current version of the honk binary may be printed with the
|
|
<code class="Ic">version</code> command.</p>
|
|
</section>
|
|
<section class="Ss">
|
|
<h2 class="Ss" id="Security"><a class="permalink" href="#Security">Security</a></h2>
|
|
<p class="Pp"><code class="Nm">honk</code> is not currently hardened against
|
|
SSRF, server side request forgery. Be mindful of what other services may be
|
|
exposed via localhost or the local network.</p>
|
|
</section>
|
|
<section class="Ss">
|
|
<h2 class="Ss" id="Development"><a class="permalink" href="#Development">Development</a></h2>
|
|
<p class="Pp">Development mode may be enabled or disabled by running
|
|
<code class="Ic">devel</code> <var class="Ar">on|off</var>. In devel mode,
|
|
secure cookies are disabled, TLS certs are not verified, and templates are
|
|
reloaded every request.</p>
|
|
</section>
|
|
<section class="Ss">
|
|
<h2 class="Ss" id="Import"><a class="permalink" href="#Import">Import</a></h2>
|
|
<p class="Pp">Data may be imported and converted from other services using the
|
|
<code class="Ic">import</code> command. Currently supports Mastodon and
|
|
Twitter exported data. Posts are imported and backdated to appear as old
|
|
honks. The Mastodon following list is imported, but must be refollowed.</p>
|
|
<p class="Pp">To prepare a Mastodon data archive, extract the
|
|
archive-longhash.tar.gz file.</p>
|
|
<div class="Bd Bd-indent"><code class="Li">./honk import username mastodon
|
|
source-directory</code></div>
|
|
<p class="Pp">To prepare a Twitter data archive, extract the
|
|
twitter-longhash.zip file. After unzipping the data archive, navigate to the
|
|
tweet_media directory and unzip any zip files contained within.</p>
|
|
<div class="Bd Bd-indent"><code class="Li">./honk import username twitter
|
|
source-directory</code></div>
|
|
</section>
|
|
<section class="Ss">
|
|
<h2 class="Ss" id="Advanced_Options"><a class="permalink" href="#Advanced_Options">Advanced
|
|
Options</a></h2>
|
|
<p class="Pp">Advanced configuration values may be set by running the
|
|
<code class="Ic">setconfig</code> <var class="Ar">key value</var> command.
|
|
For example, to increase the fast timeout value from 5 seconds to 10:</p>
|
|
<div class="Bd Bd-indent"><code class="Li">./honk setconfig fasttimeout
|
|
10</code></div>
|
|
<p class="Pp">To support separate mentions without a subdomain, e.g.
|
|
@user@example.com and https://honk.example.com/u/user, set config key
|
|
'masqname' to 'example.com'. Route
|
|
<span class="Pa">/.well-known/webfinger</span> from the top domain to
|
|
honk.</p>
|
|
<p class="Pp">Custom URL seperators (not "u" and "h") may be
|
|
specified by adding "usersep" and "honksep" options to
|
|
the config table. e.g. example.com/users/username/honk/somehonk instead of
|
|
example.com/u/username/h/somehonk.</p>
|
|
</section>
|
|
</section>
|
|
<section class="Sh">
|
|
<h1 class="Sh" id="FILES"><a class="permalink" href="#FILES">FILES</a></h1>
|
|
<p class="Pp"><code class="Nm">honk</code> files are split between the data
|
|
directory and the view directory. Both default to "." but may be
|
|
specified by command line options.</p>
|
|
<p class="Pp">The data directory contains:</p>
|
|
<dl class="Bl-tag">
|
|
<dt><span class="Pa">honk.db</span></dt>
|
|
<dd>The main database.</dd>
|
|
<dt><span class="Pa">blob.db</span></dt>
|
|
<dd>Media and attachment storage.</dd>
|
|
<dt><span class="Pa">emus</span></dt>
|
|
<dd>Custom emoji.</dd>
|
|
<dt><span class="Pa">memes</span></dt>
|
|
<dd>Stickers and such.</dd>
|
|
<dt><span class="Pa">views/local.js</span></dt>
|
|
<dd>Locally customized JS.</dd>
|
|
<dt><span class="Pa">views/local.css</span></dt>
|
|
<dd>Locally customized CSS.</dd>
|
|
</dl>
|
|
<p class="Pp">The view directory contains:</p>
|
|
<dl class="Bl-tag">
|
|
<dt><span class="Pa">views</span></dt>
|
|
<dd>HTML templates and CSS files.</dd>
|
|
</dl>
|
|
</section>
|
|
<section class="Sh">
|
|
<h1 class="Sh" id="EXAMPLES"><a class="permalink" href="#EXAMPLES">EXAMPLES</a></h1>
|
|
<p class="Pp">This series of commands creates a new database, sets a friendly
|
|
welcome message, and runs honk.</p>
|
|
<div class="Bd Pp Bd-indent Li">
|
|
<pre>honk-v98> make
|
|
honk-v98> ./honk -datadir ../honkdata init
|
|
username: puffy
|
|
password: OxychromaticBlowfishSwatDynamite
|
|
listen address: /var/www/honk.sock
|
|
server name: honk.example.com
|
|
honk-v98> ./honk -datadir ../honkdata admin
|
|
honk-v98> date; ./honk -datadir ../honkdata >> log 2>&1</pre>
|
|
</div>
|
|
<p class="Pp">The views directory includes a sample pleroma.css to change color
|
|
scheme.</p>
|
|
<div class="Bd Pp Bd-indent Li">
|
|
<pre>honk-v98> mkdir ../honkdata/views
|
|
honk-v98> cp views/pleroma.css ../honkdata/views/local.css</pre>
|
|
</div>
|
|
<p class="Pp">Upgrade to the next version. Clean things up a bit.</p>
|
|
<div class="Bd Pp Bd-indent Li">
|
|
<pre>datadir> cp honk.db backup.db
|
|
datadir> cd ../honk-v99
|
|
honk-v99> make
|
|
honk-v99> ./honk -datadir ../honkdata upgrade
|
|
honk-v99> ./honk -datadir ../honkdata cleanup
|
|
honk-v99> date; ./honk -datadir ../honkdata >> log 2>&1</pre>
|
|
</div>
|
|
</section>
|
|
<section class="Sh">
|
|
<h1 class="Sh" id="ENVIRONMENT"><a class="permalink" href="#ENVIRONMENT">ENVIRONMENT</a></h1>
|
|
<p class="Pp">Image processing and scaling requires considerable memory. It is
|
|
recommended to adjust the datasize ulimit to at least 1GB.</p>
|
|
</section>
|
|
<section class="Sh">
|
|
<h1 class="Sh" id="SEE_ALSO"><a class="permalink" href="#SEE_ALSO">SEE
|
|
ALSO</a></h1>
|
|
<p class="Pp"><a class="Xr" href="intro.1.html">intro(1)</a>,
|
|
<a class="Xr" href="honk.1.html">honk(1)</a></p>
|
|
</section>
|
|
<section class="Sh">
|
|
<h1 class="Sh" id="CAVEATS"><a class="permalink" href="#CAVEATS">CAVEATS</a></h1>
|
|
<p class="Pp">There's no online upgrade capability. Upgrades may result in
|
|
minutes of downtime.</p>
|
|
</section>
|
|
</div>
|
|
<table class="foot">
|
|
<tr>
|
|
<td class="foot-date">May 31, 2022</td>
|
|
<td class="foot-os">OpenBSD 7.1</td>
|
|
</tr>
|
|
</table>
|
|
</body>
|
|
</html>
|