snac2-glamour-mirror/doc/snac.8

.Dd $Mdocdate$
.Dt SNAC 8
.Os
.Sh NAME
.Nm snac
.Nd snac administration
.Sh DESCRIPTION
The
.Nm
daemon processes messages from other servers in the Fediverse
using the ActivityPub protocol.
.Pp
This is the admin manual. For user operation, see
.Xr snac 1 .
For file and data formats, see
.Xr snac 5 .
.Ss Special cares about your snac you must know beforehand
.Nm
makes heavy use of hard links and link reference counts for its work, so
don't even think of using it on a filesystem that doesn't support this
feature. Most UNIX-like operating systems (Linux, the BSDs, the old DEC
Ultrix machine in your grandfather basement, probably MacOS) support hard
links on their native filesystems. Don't do fancy things like moving the
subdirectories to different filesystems. Also, if you move your
.Nm
installation to another server, do it with a tool that keeps hard
links, like
.Xr tar 1
or
.Xr rsync 1
with the -H switch. Remember:
.Nm
is a very UNIXy program that loves hard links.
.Ss Building and Installation
A C compiler must be installed in the system, as well as the development
headers and libraries for OpenSSL (or compatible) and curl. To build
.Nm ,
run
.Bd -literal -offset indent
make
.Ed
.Pp
And, after that, run as root
.Bd -literal -offset indent
make install
.Ed
.Ss Data storage Initialization
Once
.Nm
is properly installed on the system, designate a directory where
the server and user data are to be stored. This directory
must not exist yet.
.Nm
must always be run as a regular user; you can create one for
it or use your own. To initialize the data storage, execute
.Bd -literal -offset indent
snac init $HOME/snac-data
.Ed
.Pp
A small set of questions will be asked regarding the installation,
specially the host name it will run under, the local network address
and port
.Nm
will listen to, the optional path prefix and possibly other things.
.Pp
Since version 2.57, if the 'network address' starts with /, it's
assumed to be a UNIX-like socket (please take note that the http proxy
must have full read and write access to this socket; this is a common
pitfall. Permissions will break your heart).
.Pp
You can launch the
.Nm
process by running
.Bd -literal -offset indent
snac httpd $HOME/snac-data
.Ed
.Pp
Log messages are sent to the standard error stream. By default, only
relevant information is written there. You can increase the debugging
level by editing the 'dbglevel' field in the
.Pa server.json
file or by setting a numeric value between 0 and 3 to the DEBUG
environment variable, see below.
.Pp
If you operate a Linux systemd-enabled system, OpenBSD, FreeBSD or NetBSD, there are
startup scripts and configuration data in the
.Pa examples
directory.
For other operating systems, please read the appropriate documentation
on how to install a daemon as a non-root service.
.Ss Upgrading to a new version
Sometimes, the data storage disk layout changes between versions. If there
is such a change,
.Nm
will refuse to run and require an upgrade. Do this by running
.Bd -literal -offset indent
snac upgrade $HOME/snac-data
.Ed
.Pp
Take special care to execute this upgrade operation without any
.Nm
processes serving on the same folder. You can break everything. I know
this because Tyler knows this.
.Pp
.Ss Server Setup
.Pp
An http server with TLS and proxying support must already be
installed and configured.
.Nm
runs as a daemon and listens on a TCP/IP socket, preferably
on a local interface. It can serve the full domain or only
a directory. The http server must be configured to route to the
.Nm
socket all related traffic and also the webfinger standard
address. The Host header must be propagated.
See the examples below.
.Ss Adding Users
.Pp
Users must be created from the command line.
You can do it by running
.Bd -literal -offset indent
snac adduser $HOME/snac-data
.Ed
.Pp
All needed data will be prompted for. There is no artificial limit
on the number of users that can be created.
.Ss Customization
The
.Pa server.json
configuration file allows some behaviour tuning:
.Bl -tag -width tenletters
.It Ic host
The host name.
.It Ic prefix
The URL path prefix.
.It Ic address
The listen network address. If it starts with /, it's assumed to be
a UNIX-like socket instead.
.It Ic port
The listen network port (unused if address is a UNIX socket).
.It Ic dbglevel
The debug level. An integer value, being 0 the less verbose (the default).
.It Ic layout
The disk storage layout version. Never touch this.
.It Ic queue_retry_max
Messages sent out are stored in a queue. If the posting of a messages fails,
it's re-enqueued for later. This integer configures the maximum count of
times the sending will be retried.
.It Ic queue_retry_minutes
The number of minutes to wait before the failed posting of a message is
retried. This is not linear, but multiplied by the number of retries
already done.
.It Ic queue_timeout
The maximum number of seconds to wait when sending a message from the queue.
.It Ic queue_timeout_2
The maximum number of seconds to wait when sending a message from the queue
to those servers that went timeout in the previous retry. If you want to
give slow servers a chance to receive your messages, you can increase this
value (but also take into account that processing the queue will take longer
while waiting for these molasses to respond).
.It Ic def_timeline_entries
This is the default timeline entries shown in the web interface.
.It Ic max_timeline_entries
This is the maximum timeline entries shown in the web interface.
.It Ic timeline_purge_days
Entries in the timeline older that this number of days are purged.
If you don't want any timeline purging and enjoy your data drives
fill up with old crap and finally burst in flames, you can disable
purging by setting this to 0.
.It Ic local_purge_days
Same as before, but for the user-generated entries in the local timeline.
.It Ic propagate_local_purge
If this value is set to true, a Delete activity is generated for every
purged local post and sent everywhere.
.It Ic cssurls
This is a list of URLs to CSS files that will be inserted, in this order,
in the HTML before the user CSS. Use these files to configure the global
site layout.
.It Ic disable_cache
If set to true, timeline caching is not done. This is only useful for
debugging purposes; don't enable it unless you know what do you want, as
it makes everything slower.
.It Ic disable_openbsd_security
If running under OpenBSD,
.Nm
makes use of the enhanced security functions
.Xr unveil 2
and
.Xr pledge 2 .
Setting this to true disables their usage. These functions limit severely
what an intruder can do in case of a security vulnerability, so only enable
this option if something is very broken.
.It Ic num_threads
By setting this value, you can specify the exact number of threads
.Nm
will use when processing connections. Values lesser than 4 will be ignored.
.It Ic disable_email_notifications
By setting this to true, no email notification will be sent for any user.
.It Ic disable_inbox_collection
By setting this to true, no inbox collection is done. Inbox collection helps
being discovered from remote instances, but also increases network traffic.
.It Ic http_headers
If you need to add more HTTP response headers for whatever reason, you can
fill this object with the required header/value pairs.
.It Ic show_instance_timeline
If this is set to true, the instance base URL will show a timeline with the latest
user posts instead of the default greeting static page. If other information
fields are set (see below), they are also shown.
.It Ic admin_email
The email address of the instance administrator (optional).
.It Ic admin_account
The user name of the instance administrator (optional).
.It Ic title
The name of the instance (optional).
.It Ic short_description
A textual short description about the instance (optional).
.It Ic short_description_raw
Whether to interpret short_descript as raw string or convert to HTML (optional).
.It Ic fastcgi
If set to true,
.Nm
will use the FastCGI interface to communicate with the upper level
http server, that must be configured accordingly.
.It Ic disable_history
If set to true, history monthly snapshots are not served nor their links shown.
.It Ic shared_inboxes
This boolean value selects if shared inboxes are announced or not. Enabling
shared inboxes helps (somewhat) in optimizing incoming traffic for instances
with a large number of users.
.It Ic min_account_age
If this numeric value (in seconds) is set, any activity coming from an account
that was created more recently than that will be rejected. This may be used
to mitigate spam from automatically created accounts.
.It Ic protocol
This string value contains the protocol (schema) to be used in URLs. If not
set, it defaults to "https". If you run
.Nm
as part of a hidden network like Tor or I2P that doesn't have a TLS /
Certificate infrastructure, you need to set it to "http". Don't change it
unless you know what you are doing.
.It Ic hide_delete_post_button
If set to true, the button to delete a post is not shown. It's not very
useful and somewhat clutters the already crowded button space.
.It Ic disable_block_notifications
If set to true, notifications about 'Block' activities are never sent.
.It Ic strict_public_timelines
If set to true, public timelines only show posts and boosts originating
from an account (no conversation trees).
.It Ic proxy_media
If set to true, links to all image, audio or video media from other accounts'
posts will not be direct ones, but proxied by
.Nm .
This way, remote media servers will not see the user's IP, but the server one,
improving privacy. Please take note that this will increase the server's incoming
and outgoing traffic.
.It Ic badlogin_retries
If incorrect logins from a given IP address reach this count, subsequent attempts
from it are rejected until the lock expires (default: 5 retries).
.It Ic badlogin_expire
The number of seconds a blocked IP address is ignored in login attempts
(default: 300 seconds).
.It Ic disable_sandbox
This boolean toggle allows disabling Linux Landlock sandboxing. Confining a
program in a sandbox limits the directories and resources it can use, so it's
recommended for security. Support for Linux sandboxing must be compiled in, and you
need at least a Linux kernel version 5.13.0.
.It Ic max_public_entries
The maximum number of entries (posts) to be returned in user RSS feeds and outboxes
(default: 20).
.It Ic max_attachments
The maximum number of attachments per post (default: 4).
.It Ic max_poll_options
The maximum number of poll options in a poll (default: 8).
.It Ic max_poll_option_length
The maximum length of a single poll option (default: 60).
.It Ic enable_svg
Since version 2.73, SVG image attachments are hidden by default; you can enable
them by setting this value to true.
.It Ic smtp_url
Since version 2.76, email notifications can be sent via direct connection to an
SMTP server instead of the traditional behaviour of piping the message to
.Pa /usr/sbin/sendmail .
Set this value to the SMTP url to be used for sending email notifications
(for example, smtp://localhost). It may include a port number if it's not running on
the usual one, like in smtp://mail.example.com:587.
.It Ic smtp_user
.It Ic smtp_password
To be filled if the SMTP server defined by the previous directive needs credentials.
.It Ic rss_hashtag_poll_hours
The periodic number of hours hashtag RSS are polled (default: 4). It has a minimum
value of 1 to avoid hammering servers.
.It Ic disable_notify_webhook
Since version 2.78, users can set a webhook URL to receive notifications. Set this
to true if you don't want your users to have this privilege.
.It Ic favicon_url
The URL to a favicon. If it's not set, the default one is used instead.
.It Ic max_failing_days
The maximum number of days an instance is considered down after continuous failed
outgoing messages (default: 15). Anyway, whenever any incoming activity from a
failed instance is detected, this counter is reset for it.
.It Ic vkey
Public vapid key. Used for notification on some client.
.It Ic disable_emojireact
If set to true, all EmojiReact support (for input and output) is disabled.
.It Ic strip_exif
If set to true, EXIF and other metadata will be stripped from uploaded images (jpg, png, webp, heic, avif, tiff, gif, bmp) and videos (mp4, m4v, mov, webm, mkv, avi). This requires the
.Nm mogrify
(from ImageMagick) and
.Nm ffmpeg
tools to be installed. If
.Nm snac
cannot find or execute these tools at startup, it will refuse to run.
.Pp
When enabled, registered users might pass arbitrary files to
.Nm mogrify
or
.Nm ffmpeg .
These commands are being executed outside the sandbox and have a huge
attack surface. Exploits would be run as the
.Nm
system user. Reconsider enabling this on
.Nm
instances with unknown or untrusted users.
.It Ic mogrify_path
Overrides the default "mogrify" command name or path. Use this if the tool is not in the system PATH or has a different name.
.It Ic ffmpeg_path
Overrides the default "ffmpeg" command name or path. Use this if the tool is not in the system PATH or has a different name.
.It Ic purge_static
If set to true, user static directories are purged; any file stored in these subdirectories (usually images or other media) that is not attached to any post, not used as avatar, header or favicon, and not served as an emoji, is deleted from the filesystem. Don't enable this option if any of your users are serving other files (like, e.g., CSS assets) this way.
.El
.Pp
You must restart the server to make effective these changes.
.Pp
If a file named
.Pa greeting.html
is present in the server base directory, it will be returned whenever
the base URL of the server is requested. Fill it with whatever
information about the instance you want to supply to people
visiting the server, like sign up requirements, site policies
and such. The special %userlist% mark in the file will cause
the list of users in this instance to be inserted.
.Pp
Users can change a bit of information about themselves from the
web interface. See
.Xr snac 1
for details. Further, every user can have a private CSS file in their
.Pa static/style.css
that will be served instead of the server-wide one.
It's not modifiable from the web interface to avoid users
shooting themselves in the foot by destroying everything.
.Ss Custom Emojis
From version 2.51, support for customized Emojis in posts is available
(previously, they were hardcoded). Emojis are read from the
.Pa emojis.json
file in the instance base directory, as a JSON object of key / value
pairs (if this file does not exist, it will be created with
the predefined set). Each key in the object contains the text to be found (e.g.,
the :-) for a smiling face), and its associated value, the text string that
will replace it (in this example case, the HTML entity for the Unicode codepoint
for the smiley or the Emoji itself as text).
.Pp
Emoji values can also be URLs to image files; in this case, they will not be
substituted in the post content, but added to the 'tag' array as an ActivityPub
standard 'Emoji' object (it's recommendable that the Emoji key be enclosed in
colons for maximum compatibility with other ActivityPub implementations, like
e.g. :happydoggo:). These images can be served from an external source or from the
.Pa static
directory of the instance admin.
.Pp
If you want to disable any Emoji substitution, change the file to contain
just an empty JSON object ({}).
.Ss SPAM Mitigation
There have been some SPAM attacks on the Fediverse and, as too many
instances and server implementations out there still allow automatic
account creation, it will only get worse.
.Nm
includes some (not very strong) tools for trying to survive the SPAM
flood that will eventually happen.
.Pp
The 
.Ic min_account_age
field in the main configuration file allows setting a minimum age (in
seconds) to consider too recently created accounts suspicious of being
a potential source of SPAM. This is a naïve assumption, because spammers
can create accounts, let them dormant for a while and then start to use
them. Also, some ActivityPub implementations don't even bother to return
a creation date for their accounts, so this is not very useful.
.Pp
From version 2.50, post content can be filtered out by regular expressions.
These weapons of mass destruction can be written into the
.Ic filter_reject.txt
file in the server base directory, one per line; if this file exists,
all posts' content will be matched (after being stripped of HTML tags)
against these regexes, one by one, and any match will make the post to
be rejected. Use lower case, the regex will be case insensitive by default. 
If you don't know about regular expressions, don't use this
option (or learn about them inw some tutorial, there are gazillions of
them out there), as you and your users may start missing posts. Also,
given that every regular expression implementation supports a different
set of features, consider reading the documentation about the one
implemented in your system.
.Ss ActivityPub Support
These are the following activities and objects that
.Nm
supports:
.Bl -tag -width tenletters
.It Vt Follow
Complete support, on input and output.
.It Vt Undo
For
.Vt Follow ,
.Vt Like
and
.Vt Announce
objects, on input and output.
.It Vt Create
For
.Vt Note ,
.Vt Question ,
.Vt Page ,
.Vt Article ,
.Vt Event
and
.Vt Video
objects on input, and for
.Vt Note
and
.Vt Question
on output.
.It Vt Accept
For
.Vt Follow
objects, on input and output.
.It Vt Like
For
.Vt Note
objects, on input and output.
.It Vt EmojiReact
For
.Vt Note
objects, on input and output.
.It Vt Announce
For
.Vt Note
objects, on input and output.
.It Vt Update
For
.Vt Note ,
.Vt Question ,
.Vt Page ,
.Vt Article ,
.Vt Event
and
.Vt Video
objects on input, and for
.Vt Note
on output.
.It Vt Delete
Supported for
.Vt Note
and
.Vt Tomsbtone
objects on input, and for
.Vt Note
objects on output.
.It Vt Move
For actor-like objects, for input and output.
.El
.Pp
The rest of activities and objects are dropped on input.
.Pp
There is partial support for
.Vt OrderedCollection
objects in the
.Pa /outbox 
(with the last 20 entries of the local timeline shown). No pagination
is supported. Intentionally, the
.Pa /followers
and
.Pa /following
paths return empty lists.
.Ss Migrating from snac to Mastodon
Since version 2.60, you can migrate your
.Nm
account to other ActivityPub instances. What is described here is the process to do it from
.Nm
to Mastodon; on other software implementations, it will surely be somewhat different. All
the steps regarding your
.Nm
account must be done from the command line. For the sake of the example, let's
say that you want to migrate from an account named @origin@snac.example.org to
another one named @destination@mastodon.example.com and that both of them
already exist. I've used this very informative page as a guideline:
.Pp
.Lk https://fedi.tips/transferring-your-mastodon-account-to-another-server/
.Pp
1. On your
.Nm
server, first export your data to CSV by running:
.Bd -literal -offset indent
snac export_csv $SNAC_BASEDIR origin
.Ed
.Pp
You'll find the following CSV files in the
.Pa export/
subdirectory inside the user directory:
.Pa bookmarks.csv ,
.Pa blocked_accounts.csv ,
.Pa lists.csv , and
.Pa following_accounts.csv .
.Pp
2. In the web interface of your new Mastodon account, click on
.Vt Preferences
>
.Vt Import and Export
>
.Vt Import
and upload the CSV files one at a time. You must specify the type of
file you are uploading.
.Pp
3. Still in the web interface of your new Mastodon account, click on
.Vt Preferences
>
.Vt Account
>
.Vt Moving From a Different Account ,
then click on
.Vt Create an account alias
and follow the instructions. (When it asks you to
write your old account’s handle, it needs to include the @ at the start
as well as the @ in the middle; as of our example, @origin@snac.example.org).
It seems this step is not performed immediately, you must wait an unspecified
number of minutes for this to be effective.
.Pp
4. Meanwhile, you must tell
.Nm
about your new account by creating an alias from your current one.
So, on your
.Nm
server, run
.Bd -literal -offset indent
snac alias $SNAC_BASEDIR origin "@destination@mastodon.example.com"
.Ed
.Pp
5. Finally, you must order
.Nm
to start the migration process, that will consist in iterating all the
people that follows your account and sending them a
.Vt Move
message, that acts as a suggestion to unfollow your old account
and follow the new one. The command is
.Bd -literal -offset indent
snac migrate $SNAC_BASEDIR origin
.Ed
.Pp
This process can be very long and unreliable; any destination server may be down,
too busy, disconnected or gone. I recommend you to read the document I linked
above to know about all the sorrows awaiting. 
.Pp
Also, please take note that the
.Nm
account you migrated from is not disabled nor changed in any way, so can still
use it as it no migration was done. This behaviour may or may not match what other
ActivityPub implementations do.
.Pp
.Ss Migrating from Mastodon to snac
Since version 2.61, you can migrate accounts on other ActivityPub instances to your
.Nm
one. What is described here is the process to do it from
Mastodon; on other software implementations, it will surely be somewhat different. All
the steps regarding your
.Nm
account must be done from the command line. For the sake of the example, let's
say that you want to migrate from an account named @origin@mastodon.example.com to
another one named @destination@snac.example.org and that both of them
already exist. I've used this very informative page as a guideline:
.Pp
.Lk https://fedi.tips/transferring-your-mastodon-account-to-another-server/
.Pp
1. On the web interface of your origin Mastodon account, click on
.Vt Preferences
>
.Vt Import and Export
>
.Vt Export
and download the CSV files under the "Follows", "Lists", "You Block" and "Bookmarks"
labels. After being downloaded, you should find the following files on your download
directory:
.Pa bookmarks.csv ,
.Pa blocked_accounts.csv ,
.Pa lists.csv , and
.Pa following_accounts.csv .
.Pp
2. Copy all those files to the
.Pa import/
subdirectory of the user's directory inside the server base directory, and run
.Bd -literal -offset indent
snac import_csv $SNAC_BASEDIR destination
.Ed
.Pp
This process may take some time because it depends on the availability / responsiveness
of all the ActivityPub servers involved (webfinger, accounts, posts, etc.). Some errors
may be transient and retried later. Also, if
.Nm
complains that it can't find any of these files, please check that they are really
stored in the
.Pa import/
subdirectory and that their names match exactly. Some of them may be
empty (for example, if you didn't create any list) and that's fine.
.Pp
3. Again on your
.Nm
server, run
.Bd -literal -offset indent
snac alias $SNAC_BASEDIR destination "@origin@mastodon.example.com"
.Ed
.Pp
Check that no errors were shown. If they do, the origin Mastodon server may be
busy or down; try again later.
.Pp
4. Move back to the web interface of the origin Mastodon account, go to
.Vt Preferences
>
.Vt Account
>
.Vt Move To A Different Account ,
and follow the instructions there. Set the handle of the new account to your
.Nm
one; as of our example, @destination@snac.example.org. This will start the migration
process: it's the duty of your old Mastodon instance to send an automatic
.Vt Move
message to every one of your followers. Eventually, you will start receiving follow notifications to your
.Nm
account from all accounts that followed the Mastodon one. According to the great document
I linked above, this process may or may not start immediately, and its success may depend
heavily on how all the servers involved behave. Just cross your fingers and hope for the best.
.Pp
.Ss Instance blocking
Full instances can be blocked. This operation must be done from
the command-line tool. See
.Xr snac 1 .
.Pp
.Ss Bad login throttling
Since version 2.67, a simple logic to avoid brute force attacks against user passwords
has been implemented: if, from a given IP address, the number of failed logins reaches
a given threshold, further tries from that IP address are never successful until a timer
expires. The maximum number of retries can be configured in the 
.Pa server.json
file by setting the
.Ic badlogin_retries
variable, and the number of seconds the IP address unlock timer expires, in
.Ic badlogin_expire .
Please take note that, for this system to work, you must setup your web server proxy
to pass the remote connection address in the
.Ic X-Forwarded-For
HTTP header (unless you use the FastCGI interface; if that's the case, you don't have
to do anything).
.Pp
.Ss Subscribing to Fediverse Relays
Since version 2.69, a
.Nm
instance can subscribe to LitePub (Pleroma-style) Fediverse Relays. Doing this improves
visibility and allows following hashtags. To do this, you must create a special user named
relay and, from it, follow the relay actor(s) like you do with regular actor URLs. This
special user will start receiving boosts from the relay server of posts from other instances
also following it. If any other user of the same
.Nm
instance follows any of the hashtags included in these boosted posts coming from the relay,
they will be received as if they were for them.
.Pp
Example:
.Bd -literal -offset indent
snac adduser $SNAC_BASEDIR relay # only needed once
snac follow $SNAC_BASEDIR relay https://relay.example.com/actor
.Ed
.Pp
Users on your instance do NOT need to follow the local relay user to benefit from following
hashtags.
.Pp
Please take note that subscribing to relays can increase the traffic towards your instance
significantly. In any case, lowering the "Maximum days to keep posts" value for the relay
special user is recommended (e.g. setting to just 1 day).
.Ss Web interface language
Since version 2.73, the web UI can be localized via simple .po files (they are directly
parsed, no support for gettext is needed).
.Pp
No language file is installed by default; the administrator must copy any desired .po files
to the
.Pa lang/
subdirectory in the base directory. Once the server is restarted, users can select the
new language from the user settings. The
.Nm
source distribution may include .po files in the
.Pa po/
subdirectory. You don't need to copy the English language one, as it's the default.
.Pp
To create new language files, create a copy of
.Pa po/en.po ,
rename it to a reasonable value like
.Pa pl.po
or
.Pa pt_BR.po ,
change the translator in the header to yourself and fill the msgstr strings with your
translation. If you have any doubt on how to modify .po files, there are many tutorials
out there. If you want your language file to be included in the standard
.Nm
distribution, please send me a link to it via the Fediverse to @grunfink@comam.es
or make a PR via the Git repository.
.Ss Number of open files on OpenBSD and login classes
Being a file intensive application, even a small
.Nm
instance might open lots of files, especially when forwarding a new post to
other instances.
.Pp
OpenBSD's daemon login class comes with a very low
.Pa openfiles
value, usually restricting the amount of open files to 128 (cur), 1024 (max).
This can result in
.Nm
to stop working due to too many open files.
.Pp
To continue operation, a new
.Pa snac
login class can be created. Please consult
.Xr login.conf 5
and afterwards create a new login class as follows.
.Bd -literal -offset indent
snac:\\
    :openfiles=4096:\\
    :tc=daemon:
.Ed
.Pp
After rebuilding the
.Pa /etc/login.conf.db ,
ensure that your snac user's login class is set to
.Pa snac :
.Bd -literal -offset indent
# cap_mkdb /etc/login.conf
# usermod -L snac SNACUSER
.Ed
.Pp
One restart later, the daemon should run with increased
.Pa openfiles .
.Sh ENVIRONMENT
.Bl -tag -width Ds
.It Ev DEBUG
Overrides the debugging level from the server 'dbglevel' configuration
variable. Set it to an integer value. The higher, the deeper in meaningless
verbiage you'll find yourself into.
.El
.Sh EXAMPLES
You want to install the
.Nm
Fediverse daemon in the host example.com, that is correctly configured
with a valid TLS certificate and running the nginx httpd server.
The service will be installed under the
.Pa fedi
location. Two users, walter and jessie, will be hosted in the system.
Their Fediverse presence addresses will be
.Lk https://example.com/fedi/walter
and
.Lk https://example.com/fedi/jesse ,
respectively. They will be known
in the Fediverse as @walter@example.com and @jesse@example.com. The
.Nm
daemon will run as the user snacusr in the system and listen to the
localhost:8001 network socket. All data will be stored in the
.Pa /home/snacusr/fedidata
directory.
.Pp
Log into the system as snacusr and execute:
.Bd -literal -offset indent
snac init /home/snacusr/fedidata
.Ed
.Pp
Answer "example.com" to the host name question, "/fedi" to the path
prefix question, "localhost" to the address and "8001" to the port.
.Pp
Create the users
.Bd -literal -offset indent
snac adduser /home/snacusr/fedidata walter
snac adduser /home/snacusr/fedidata jesse
.Ed
.Pp
Answer the questions with reasonable values.
.Pp
Execute the server:
.Bd -literal -offset indent
snac httpd /home/snacusr/fedidata
.Ed
.Pp
Edit the nginx configuration and add the following snippet to the
example.com server section:
.Bd -literal -offset indent
# nginx configuration example

# main web access point
location /fedi {
    proxy_pass http://localhost:8001;
    proxy_set_header Host $http_host;
    proxy_set_header X-Forwarded-For $remote_addr;
}
# webfinger
location /.well-known/webfinger {
    proxy_pass http://localhost:8001;
    proxy_set_header Host $http_host;
    proxy_set_header X-Forwarded-For $remote_addr;
}
# Mastodon API (entry points)
location /api/v1/ {
    proxy_pass http://localhost:8001;
    proxy_set_header Host $http_host;
    proxy_set_header X-Forwarded-For $remote_addr;
}
location /api/v2/ {
    proxy_pass http://localhost:8001;
    proxy_set_header Host $http_host;
    proxy_set_header X-Forwarded-For $remote_addr;
}
# Mastodon API (OAuth support)
location /oauth {
    proxy_pass http://localhost:8001;
    proxy_set_header Host $http_host;
    proxy_set_header X-Forwarded-For $remote_addr;
}
# optional
location /.well-known/nodeinfo {
    proxy_pass http://localhost:8001;
    proxy_set_header Host $http_host;
    proxy_set_header X-Forwarded-For $remote_addr;
}
# optional (needed by some Mastodon API clients)
location /.well-known/host-meta {
    proxy_pass http://localhost:8001;
    proxy_set_header Host $http_host;
    proxy_set_header X-Forwarded-For $remote_addr;
}
# optional (Mastodon-like link share entrypoint)
location /share {
    proxy_pass http://localhost:8001;
    proxy_set_header Host $http_host;
    proxy_set_header X-Forwarded-For $remote_addr;
}
# optional (Mastodon-like "authorize interaction" entrypoint)
location /authorize_interaction {
    proxy_pass http://localhost:8001;
    proxy_set_header Host $http_host;
    proxy_set_header X-Forwarded-For $remote_addr;
}
.Ed
.Pp
Restart the nginx daemon and connect to
.Lk https://example.com/fedi/walter .
The empty, default screen will be shown. Enter the admin section with the
credentials defined for this user. Search people, start following
them, engage in arid discussions and generally enjoy the frustrating
experience of Social Media.
.Pp
This is an example of a similar configuration for the Apache2 web server:
.Bd -literal -offset indent
# apache2 configuration example

ProxyPreserveHost On

# Main web access point
<Location /fedi>
    ProxyPass http://127.0.0.1:8001/social
</Location>

# WebFinger
<Location /.well-known/webfinger>
    ProxyPass http://127.0.0.1:8001/.well-known/webfinger
</Location>

# Mastodon API (entry points)
<Location /api/v1/>
    ProxyPass http://127.0.0.1:8001/api/v1/
</Location>

<Location /api/v2/>
    ProxyPass http://127.0.0.1:8001/api/v2/
</Location>

# Mastodon API (OAuth support)
<Location /oauth>
    ProxyPass http://127.0.0.1:8001/oauth
</Location>

# NodeInfo (optional)
<Location /.well-known/nodeinfo>
    ProxyPass http://127.0.0.1:8001/.well-known/nodeinfo
</Location>

# host-meta (optional, needed for some Mastodon API clients)
<Location /.well-known/host-meta>
    ProxyPass http://127.0.0.1:8001/.well-known/host-meta
</Location>

# optional (Mastodon-like link share entrypoint)
<Location /share>
    ProxyPass http://127.0.0.1:8001/share
</Location>

# optional (Mastodon-like "authorize interaction" entrypoint)
<Location /authorize_interaction>
    ProxyPass http://127.0.0.1:8001/share
</Location>
.Ed
.Pp
Since version 2.43,
.Nm
supports communicating from / to the front end http server using the FastCGI
protocol. There is no special advantage in using this, only that some servers
allow for simpler configuration. For example, in the case of nginx, you can
replace the two 'proxy_pass' and 'proxy_set_header' lines in the example
above with just
.Bd -literal -offset indent
fastcgi_pass localhost:8001;
.Ed
.Pp
The only thing to change on
.Nm
is to the set 'fastcgi' value to true in
.Pa server.json .
.Pp
Further, using the FastCGI interface allows a much simpler configuration
under OpenBSD's native httpd, given that it's natively implemented there
and you no longer need to configure the complicated relayd server. This is
an example:
.Bd -literal -offset indent
# OpenBSD httpd configuration example

# other server configuration
[...]

location "/fedi/*" {
    fastcgi socket tcp "127.0.0.1" 8001
}

location "/.well-known/webfinger" {
    fastcgi socket tcp "127.0.0.1" 8001
}

location "/oauth/*" {
    fastcgi socket tcp "127.0.0.1" 8001
}

location "/api/v1/*" {
    fastcgi socket tcp "127.0.0.1" 8001
}

location "/api/v2/*" {
    fastcgi socket tcp "127.0.0.1" 8001
}

location "/.well-known/nodeinfo" {
    fastcgi socket tcp "127.0.0.1" 8001
}

location "/.well-known/host-meta" {
    fastcgi socket tcp "127.0.0.1" 8001
}

location "/share" {
    fastcgi socket tcp "127.0.0.1" 8001
}

location "/authorize_interaction" {
    fastcgi socket tcp "127.0.0.1" 8001
}
.Ed
.Sh SEE ALSO
.Xr snac 1 ,
.Xr snac 5
.Sh AUTHORS
.An grunfink Lk https://comam.es/snac/grunfink @grunfink@comam.es
.Sh LICENSE
See the LICENSE file for details.
.Sh CAVEATS
JSON files are fragile when modified by hand. Take care.