Provided by: snac2_2.75-2_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 keeps hard links, like
tar(1) or rsync(1) with the -H switch. 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.
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).
You can launch the snac process by running
snac httpd $HOME/snac-data
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, FreeBSD or NetBSD, 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, 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 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. If it starts with /, it's assumed to be a UNIX-like socket
instead.
port The listen network port (unused if address is a UNIX socket).
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 multiplied by the number of retries already done.
queue_timeout
The maximum number of seconds to wait when sending a message from the queue.
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).
def_timeline_entries
This is the default timeline entries shown in the web interface.
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).
short_description_raw
Whether to interpret short_descript as raw string or convert to HTML (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.
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.
protocol This string value contains the protocol (schema) to be used in URLs. If not set, it defaults
to "https". If you run snac 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.
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.
disable_block_notifications
If set to true, notifications about 'Block' activities are never sent.
strict_public_timelines
If set to true, public timelines only show posts and boosts originating from an account (no
conversation trees).
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 snac. 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.
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).
badlogin_expire
The number of seconds a blocked IP address is ignored in login attempts (default: 300
seconds).
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.
max_public_entries
The maximum number of entries (posts) to be returned in user RSS feeds and outboxes (default:
20).
max_attachments
The maximum number of attachments per post (default: 4).
enable_svg Since version 2.73, SVG image attachments are hidden by default; you can enable them by
setting this value to true.
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.
Custom Emojis
From version 2.51, support for customized Emojis in posts is available (previously, they were hardcoded).
Emojis are read from the 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).
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 compatilibity with other ActivityPub implementations,
like e.g. :happydoggo:). These images can be served from an external source or from the static directory
of the instance admin.
If you want to disable any Emoji substitution, change the file to contain just an empty JSON object ({}).
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. snac includes some (not very
strong) tools for trying to survive the SPAM flood that will eventually happen.
The 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.
From version 2.50, post content can be filtered out by regular expressions. These weapons of mass
destruction can be written into the 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.
ActivityPub Support
These are the following activities and objects that snac supports:
Follow Complete support, on input and output.
Undo For Follow, Like and Announce objects, on input and output.
Create For Note, Question, Page, Article, Event and Video objects on input, and for Note and
Question on output.
Accept For Follow objects, on input and output.
Like For Note objects, on input and output.
EmojiReact For Note objects, on input.
Announce For Note objects, on input and output.
Update For Note, Question, Page, Article, Event and Video objects on input, and for Note on output.
Delete Supported for Note and Tomsbtone objects on input, and for Note objects on output.
Move For actor-like objects, for input and 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 snac to Mastodon
Since version 2.60, you can migrate your snac account to other ActivityPub instances. What is described
here is the process to do it from snac to Mastodon; on other software implementations, it will surely be
somewhat different. All the steps regarding your snac 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:
https://fedi.tips/transferring-your-mastodon-account-to-another-server/
1. On your snac server, first export your data to CSV by running:
snac export_csv $SNAC_BASEDIR origin
You'll find the following CSV files in the export/ subdirectory inside the user directory: bookmarks.csv,
blocked_accounts.csv, lists.csv, and following_accounts.csv.
2. In the web interface of your new Mastodon account, click on Preferences > Import and Export > Import
and upload the CSV files one at a time. You must specify the type of file you are uploading.
3. Still in the web interface of your new Mastodon account, click on Preferences > Account > Moving From
a Different Account, then click on 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.
4. Meanwhile, you must tell snac about your new account by creating an alias from your current one. So,
on your snac server, run
snac alias $SNAC_BASEDIR origin "@destination@mastodon.example.com"
5. Finally, you must order snac to start the migration process, that will consist in iterating all the
people that follows your account and sending them a Move message, that acts as a suggestion to unfollow
your old account and follow the new one. The command is
snac migrate $SNAC_BASEDIR origin
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.
Also, please take note that the snac 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.
Migrating from Mastodon to snac
Since version 2.61, you can migrate accounts on other ActivityPub instances to your snac 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 snac 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:
https://fedi.tips/transferring-your-mastodon-account-to-another-server/
1. On the web interface of your origin Mastodon account, click on Preferences > Import and Export >
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: bookmarks.csv,
blocked_accounts.csv, lists.csv, and following_accounts.csv.
2. Copy all those files to the import/ subdirectory of the user's directory inside the server base
directory, and run
snac import_csv $SNAC_BASEDIR destination
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 snac complains that it can't find any of these files, please check that they are really
stored in the 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.
3. Again on your snac server, run
snac alias $SNAC_BASEDIR destination "@origin@mastodon.example.com"
Check that no errors were shown. If they do, the origin Mastodon server may be busy or down; try again
later.
4. Move back to the web interface of the origin Mastodon account, go to Preferences > Account > Move To A
Different Account, and follow the instructions there. Set the handle of the new account to your snac 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 Move message to every one of your followers. Eventually,
you will start receiving follow notifications to your snac 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.
Instance blocking
Full instances can be blocked. This operation must be done from the command-line tool. See snac(1).
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 server.json file by setting the badlogin_retries variable, and the number of seconds
the IP address unlock timer expires, in 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 X-Forwarded-For HTTP
header (unless you use the FastCGI interface; if that's the case, you don't have to do anything).
Subscribing to Fediverse Relays
Since version 2.69, a snac 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 snac 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.
Example:
snac adduser $SNAC_BASEDIR relay # only needed once
snac follow $SNAC_BASEDIR relay https://relay.example.com/actor
Users on your instance do NOT need to follow the local relay user to benefit from following hashtags.
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).
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).
No language file is installed by default; the administrator must copy any desired .po files to the lang/
subdirectory in the base directory. Once the server is restarted, users can select the new language from
the user settings. The snac source distribution may include .po files in the po/ subdirectory. You don't
need to copy the English language one, as it's the default.
To create new language files, create a copy of po/en.po, rename it to a reasonable value like pl.po or
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 snac distribution, please send me a link to it via
the Fediverse to @grunfink@comam.es or make a PR via the Git repository.
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;
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;
}
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 /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>
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 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
}
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
}
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.
Debian $Mdocdate$ SNAC(8)