.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 You can launch the .Nm process by running .Bd -literal -offset indent snac httpd $HOME/snac-data .Ed .Pp Use a web browser to connect to the specified address and port. You should see a greeting page. .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 or OpenBSD, 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, 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 .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. .It Ic port The listen network port. .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 multipled by the number of retries already done. .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 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 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. .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 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. .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 objects, on input and output. .It Vt Create For .Vt Note , .Vt Question and .Vt Page objects, on input and 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 Announce For .Vt Note objects, on input and output. .It Vt Update For .Vt Person , .Vt Note and .Vt Question objects, on input and output. .It Vt Delete Supported for .Vt Note and .Vt Tomsbtone objects on input, and for .Vt Note objects on 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 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 .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 # 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; } .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 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 size 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 # 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 } .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.