.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 respect hard link counts. 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 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 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. For example, for enhanced XSS security, you can set the "Content-Security-Policy" header to "script-src ;" to be totally sure that no JavaScript is executed. .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 short_description A textual short description about the instance (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. .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 compatilibity 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. If you don't know about regular expressions, don't use this option (or learn about them in 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. .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, on input. .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. I will describe the process to do it from .Nm to Mastodon; on other software implementations, it will surely be very 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 current 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, in our example, @origin@snac.example.org). According to the link above, you must wait at least five 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, notifying all of them that they must 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. I recommend you to read the document I linked above to know how heartbreaking it can be. .Ss Migrating from Mastodon to snac 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 .Nm account. .Pp To do this, download the user's list of accounts being followed (in CSV format) from the Mastodon web interface and execute this: .Bd -literal -offset indent awk -F, 'NR > 1 { print $1 }' /path/to/following_accounts.csv | \\ xargs -n 1 snac follow $SNAC_BASEDIR $SNAC_USER .Ed .Ss Instance blocking Full instances can be blocked. This operation must be done from the command-line tool. See .Xr snac 1 . .Ss Other Considerations .Nm 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 .Nm data storage into. .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; } # 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; } # optional (needed by some Mastodon API clients) location /.well-known/host-meta { proxy_pass http://localhost:8001; proxy_set_header Host $http_host; } .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 ProxyPass http://127.0.0.1:8001/social # WebFinger ProxyPass http://127.0.0.1:8001/.well-known/webfinger # Mastodon API (entry points) ProxyPass http://127.0.0.1:8001/api/v1/ ProxyPass http://127.0.0.1:8001/api/v2/ # Mastodon API (OAuth support) ProxyPass http://127.0.0.1:8001/oauth # NodeInfo (optional) ProxyPass http://127.0.0.1:8001/.well-known/nodeinfo # host-meta (optional, needed for some Mastodon API clients) ProxyPass http://127.0.0.1:8001/.well-known/host-meta .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 } .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.