Provided by: snac2_2.45-1build3_amd64 
NAME
snac — snac administration
DESCRIPTION
The snac daemon processes messages from other servers in the Fediverse using the ActivityPub
protocol.
This is the admin manual. For user operation, see snac(1). For file and data formats, see
snac(5).
Special cares about your snac you must know beforehand
snac 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 snac installation
to another server, do it with a tool that respect hard link counts. Remember: snac is a very
UNIXy program that loves hard links.
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 snac, run
make
And, after that, run as root
make install
Data storage Initialization
Once snac 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. snac must always be run as a
regular user; you can create one for it or use your own. To initialize the data storage,
execute
snac init $HOME/snac-data
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 snac will listen to, the optional path
prefix and possibly other things.
You can launch the snac process by running
snac httpd $HOME/snac-data
Use a web browser to connect to the specified address and port. You should see a greeting
page.
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
server.json file or by setting a numeric value between 0 and 3 to the DEBUG environment
variable, see below.
If you operate a Linux systemd-enabled system, OpenBSD or FreeBSD, there are startup scripts
and configuration data in the examples directory. For other operating systems, please read
the appropriate documentation on how to install a daemon as a non-root service.
Upgrading to a new version
Sometimes, the data storage disk layout changes between versions. If there is such a change,
snac will refuse to run and require an upgrade. Do this by running
snac upgrade $HOME/snac-data
Take special care to execute this upgrade operation without any snac processes serving on
the same folder. You can break everything. I know this because Tyler knows this.
Server Setup
An http server with TLS and proxying support must already be installed and configured. snac
runs as a daemon and listens on a TCP/IP socket, preferrably on a local interface. It can
serve the full domain or only a directory. The http server must be configured to route to
the snac socket all related traffic and also the webfinger standard address. The Host header
must be propagated. See the examples below.
Adding Users
Users must be created from the command line. You can do it by running
snac adduser $HOME/snac-data
All needed data will be prompted for. There is no artificial limit on the number of users
that can be created.
Customization
The server.json configuration file allows some behaviour tuning:
host The host name.
prefix The URL path prefix.
address The listen network address.
port The listen network port.
dbglevel The debug level. An integer value, being 0 the less verbose (the default).
layout The disk storage layout version. Never touch this.
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.
queue_retry_minutes
The number of minutes to wait before the failed posting of a message is retried.
This is not linear, but multipled by the number of retries already done.
max_timeline_entries
This is the maximum timeline entries shown in the web interface.
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.
local_purge_days
Same as before, but for the user-generated entries in the local timeline.
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.
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.
disable_openbsd_security
If running under OpenBSD, snac makes use of the enhanced security functions
unveil(2) and 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.
num_threads
By setting this value, you can specify the exact number of threads snac will use
when processing connections. Values lesser than 4 will be ignored.
disable_email_notifications
By setting this to true, no email notification will be sent for any user.
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.
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.
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.
admin_email
The email address of the instance administrator (optional).
admin_account
The user name of the instance administrator (optional).
short_description
A textual short description about the instance (optional).
fastcgi If set to true, snac will use the FastCGI interface to communicate with the
upper level http server, that must be configured accordingly.
disable_history
If set to true, history monthly snapshots are not served nor their links shown.
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.
You must restart the server to make effective these changes.
If a file named 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.
Users can change a bit of information about themselves from the web interface. See snac(1)
for details. Further, every user can have a private CSS file in their 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.
Old Data Purging
From version 2.06, there is no longer a need to add a special cron job for purging old data,
as this is managed internally.
ActivityPub Support
These are the following activities and objects that snac supports:
Follow Complete support, on input and output.
Undo For Follow objects, on input and output.
Create For Note, Question and Page objects, on input and output.
Accept For Follow objects, on input and output.
Like For Note objects, on input and output.
Announce For Note objects, on input and output.
Update For Person, Note and Question objects, on input and output.
Delete Supported for Note and Tomsbtone objects on input, and for Note objects on
output.
The rest of activities and objects are dropped on input.
There is partial support for OrderedCollection objects in the /outbox (with the last 20
entries of the local timeline shown). No pagination is supported. Intentionally, the
/followers and /following paths return empty lists.
Migrating from Mastodon
User migration from different Fediverse instances is a pain in the ass that has been
implemented everywhere as a kludgy afterthought. There is not much that can be done, other
than importing the list of people you follow to your new snac account.
To do this, download the user's list of accounts being followed (in CSV format) from the
Mastodon web interface and execute this:
awk -F, 'NR > 1 { print $1 }' /path/to/following_accounts.csv | \
xargs -n 1 snac follow $SNAC_BASEDIR $SNAC_USER
Instance blocking
Full instances can be blocked. This operation must be done from the command-line tool. See
snac(1).
Other Considerations
snac stores all the messages it receives as JSON files, which are usually bloated and filled
with redundant information. Using a filesystem with file compression enabled (like btrfs or
zfs) will probably be a good choice to store the snac data storage into.
ENVIRONMENT
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.
EXAMPLES
You want to install the snac 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 fedi location. Two users, walter and jessie, will be hosted in
the system. Their Fediverse presence addresses will be https://example.com/fedi/walter and
https://example.com/fedi/jesse, respectively. They will be known in the Fediverse as
@walter@example.com and @jesse@example.com. The snac 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
/home/snacusr/fedidata directory.
Log into the system as snacusr and execute:
snac init /home/snacusr/fedidata
Answer "example.com" to the host name question, "/fedi" to the path prefix question,
"localhost" to the address and "8001" to the port.
Create the users
snac adduser /home/snacusr/fedidata walter
snac adduser /home/snacusr/fedidata jesse
Answer the questions with reasonable values.
Execute the server:
snac httpd /home/snacusr/fedidata
Edit the nginx configuration and add the following snippet to the example.com server
section:
# nginx configuration example
# main web access point
location /fedi {
proxy_pass http://localhost:8001;
proxy_set_header Host $http_host;
}
# webfinger
location /.well-known/webfinger {
proxy_pass http://localhost:8001;
proxy_set_header Host $http_host;
}
# Mastodon API (entry points)
location /api/v1/ {
proxy_pass http://localhost:8001;
proxy_set_header Host $http_host;
}
location /api/v2/ {
proxy_pass http://localhost:8001;
proxy_set_header Host $http_host;
}
# Mastodon API (OAuth support)
location /oauth {
proxy_pass http://localhost:8001;
proxy_set_header Host $http_host;
}
# optional
location /.well-known/nodeinfo {
proxy_pass http://localhost:8001;
proxy_set_header Host $http_host;
}
Restart the nginx daemon and connect to 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.
This is an example of a similar configuration for the Apache2 web server:
# apache2 configuration example
ProxyPreserveHost On
# Main web access point
<Location /social>
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>
# NodeInfo (optional)
<Location /.well-known/nodeinfo>
ProxyPass http://127.0.0.1:8001/.well-known/nodeinfo
</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>
Since version 2.43, snac 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
fastcgi_pass localhost:8001;
The only thing to change on snac size is to the set 'fastcgi' value to true in server.json.
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:
# 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
}
SEE ALSO
snac(1), snac(5)
AUTHORS
grunfink @grunfink@comam.es: https://comam.es/snac/grunfink
LICENSE
See the LICENSE file for details.
CAVEATS
JSON files are fragile when modified by hand. Take care.