SNAC(8)

📦

version 2.94 · 6 versions

🎀 SNAC(8) 🎀

okay bestie, welcome to the admin manual for snac 💖 this is the System Manager's Manual page SNAC(8), and it's literally everything you need to run your own lil corner of the Fediverse. buckle up, it's giving sysadmin era 👑

✨ NAME ✨

snac — snac administration

🌸 DESCRIPTION 🌸

The snac daemon processes messages from other servers in the Fediverse using the ActivityPub protocol. no cap, that's the whole vibe 🦋

This one right here is the admin manual. If you're looking for how to use it like a normal person, go read snac(1). And if you're here for file and data formats, that's snac(5). different books, different chapters, iykyk 📚

💅 Special cares about your snac you must know beforehand 💅

okay so before you even think about touching this, listen: snac makes heavy use of hard links and link reference counts for its work. so do NOT — i repeat, do not — even think of using it on a filesystem that doesn't support this feature. like, at all. 🙈

The good news? Most UNIX-like operating systems support hard links on their native filesystems — that's Linux, the BSDs, the old DEC Ultrix machine in your grandfather's basement, and probably MacOS. iconic lineage honestly 👑

What you also should NOT do: fancy things like moving the subdirectories to different filesystems. nope. don't.

And if you're moving your snac installation to another server? use a tool that keeps hard links, like tar(1) or rsync(1) with the -H switch. Remember, bestie: snac is a very UNIXy program that loves hard links. fr fr, it's a personality trait at this point 💖

🛠️ Building and Installation 🛠️

First things first, you need a C compiler installed on the system, plus the development headers and libraries for OpenSSL (or something compatible) and curl. no compiler, no snac, that's the deal 🍓

To build snac, run:

make

And after that, run as root:

make install

slay. you built a daemon 💅

🗂️ Data storage Initialization 🗂️

Once snac is properly installed on the system, you gotta designate a directory where the server and user data are to be stored. 👑 heads up: this directory must not exist yet.

Also super important: snac must always be run as a regular user. you can create one for it, or just use your own, whatever vibes fit you best.

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. just answer honestly bestie, it's a vibe check 🦋

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 💔 i'm so serious.)

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. If you want more tea, 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 — great news, 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. do your homework, bestie 📖

🧚 Upgrading to a new version 🧚

Sometimes, the data storage disk layout changes between versions. if that happens, snac will refuse to run and require an upgrade. dramatic? yes. necessary? also yes. 💀

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. 😭

so like... seriously. close the doors first, then upgrade. periodt.

🌐 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 — your call, main character energy either way.

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. and ngl there is no artificial limit on the number of users that can be created. go forth and populate your instance, queen 👑✨

🎨 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. do not. do not the layout. 💀
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. math is happening bestie 🧠
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.
propagate_local_purge — If this value is set to true, a Delete activity is generated for every purged local post and sent everywhere.
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).
title — The name of the instance (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 — how many seconds a blocked IP address gets ignored for login attempts (default: 300 seconds).
disable_sandbox — a boolean toggle that lets you turn Linux Landlock sandboxing off. Bestie, sandboxing keeps a program confined to only the directories and resources it actually needs, so it's recommended for security. Heads up tho: support for Linux sandboxing has to be compiled in, and you need at least a Linux kernel version 5.13.0.
max_public_entries — the max number of entries (posts) returned in user RSS feeds and outboxes (default: 20).
max_attachments — the max number of attachments per post (default: 4).
max_poll_options — the max number of poll options in a poll (default: 8).
max_poll_option_length — the max length of a single poll option (default: 60).
enable_svg — ok so since version 2.73, SVG image attachments are hidden by default 🙈 (not me being safe or whatever). You can turn them back on by setting this value to true.
smtp_url — since version 2.76, email notifications can be sent via a direct connection to an SMTP server instead of the traditional behaviour of piping the message to /usr/sbin/sendmail. Set this value to the SMTP url you wanna use for sending those 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.
smtp_user, smtp_password — fill these in if the SMTP server defined by the previous directive needs credentials.
rss_hashtag_poll_hours — the periodic number of hours hashtag RSS gets polled (default: 4). It has a minimum value of 1 to avoid hammering servers 💀.
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.
favicon_url — the URL to a favicon. If it's not set, the default one is used instead.
max_failing_days — the max 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 gets reset for it.
vkey — public vapid key. Used for notification on some client.
disable_emojireact — if set to true, all EmojiReact support (for input and output) is disabled.
strip_exif — if set to true, EXIF and other metadata gets stripped from uploaded images (jpg, png, webp, heic, avif, tiff, gif, bmp) and videos (mp4, m4v, mov, webm, mkv, avi). This requires the mogrify (from ImageMagick) and ffmpeg tools to be installed. And if snac cannot find or execute these tools at startup, it will refuse to run. 🛑

⚠️ major caution: when this is enabled, registered users might pass arbitrary files to mogrify or ffmpeg. These commands are being executed outside the sandbox and have a huge attack surface. Exploits would be run as the snac system user. Reconsider enabling this on snac instances with unknown or untrusted users, fr fr.

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.
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.
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, gets deleted from the filesystem. Don't enable this option if any of your users are serving other files this way (like, e.g., CSS assets).
keep_replied_posts — if set to true, when you reply to a remote post, the parent remote post will be added to the local public timeline.
keep_replied_me — if set to true, when a remote user replies to one of your local posts, the remote reply will be added to the local public timeline.

You must restart the server to make these changes effective 🔁 (no cap, they won't apply until you do).

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 info 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. Iconic, honestly.

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 is 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 compatibility 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 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 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.

🛰️ 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 and output.
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's 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/

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.

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.
Still in the web interface of your shiny new Mastodon account, click Preferences > Account > Moving From a Different Account, then click Create an account alias and follow the instructions. (When it asks you for your old account's handle, it genuinely needs the @ at the start and the @ in the middle — as of our example, @origin@snac.example.org.) Heads up bestie, this step does not seem to happen immediately, you have to wait an unspecified number of minutes for it to actually be effective. 🙈
Meanwhile, you have to 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"

And finally, you have to order snac to start the migration process, which consists of iterating all the people that follow 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 just gone. I recommend you 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 you can still use it as if 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's 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 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 used this very informative page as a guideline:

https://fedi.tips/transferring-your-mastodon-account-to-another-server/

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 in your download directory: bookmarks.csv, blocked_accounts.csv, lists.csv, and following_accounts.csv.
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're 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. 💅

Again on your snac server, run

snac alias $SNAC_BASEDIR destination "@origin@mastodon.example.com"

Check that no errors were shown. If they do show up, the origin Mastodon server may be busy or down; try again later.

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).

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 set up 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. 🫶

Being a file intensive application, even a small snac instance might open lots of files, especially when forwarding a new post to other instances. 😵

OpenBSD's daemon login class comes with a very low openfiles value, usually restricting the amount of open files to 128 (cur), 1024 (max). This can result in snac to stop working due to too many open files.

To continue operation, a new snac login class can be created. Please consult login.conf(5) and afterwards create a new login class as follows.

snac:\
    :openfiles=4096:\
    :tc=daemon:

After rebuilding the /etc/login.conf.db, ensure that your snac user's login class is set to snac:

# cap_mkdb /etc/login.conf
# usermod -L snac SNACUSER

One restart later, the daemon should run with increased openfiles. ✨

🌸 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 🌸

Okay bestie, story time — here's a whole real-life scenario, and it ate. 💅

So picture this: you wanna install the snac Fediverse daemon on the host example.com, which is already living its best life with a valid TLS certificate and running the nginx httpd server. The service is gonna be installed under the fedi location. Two users, walter and jessie, will be hosted in the system. Their Fediverse presence addresses are gonna be:

respectively ✨. And they'll be known in the Fediverse as @walter@example.com and @jesse@example.com. The snac daemon itself will run as the user snacusr on the system, listening on the localhost:8001 network socket. All the data lives in /home/snacusr/fedidata. 🗂️

🦋 Step 1 — log in and init that thing

Log into the system as snacusr and execute:

snac init /home/snacusr/fedidata

Then answer the questions like the icon you are:

"example.com" to the host name question
"/fedi" to the path prefix question
"localhost" to the address
"8001" to the port

Heads up bestie: yes, the users are named walter and jessie, but the adduser commands below literally say jesse — that's exactly how it's written, so just copy it character for character, no cap. 🙈

🎀 Step 2 — create the users

snac adduser /home/snacusr/fedidata walter
snac adduser /home/snacusr/fedidata jesse

Answer the questions with reasonable values. (You got this, you're the main character. 👑)

💖 Step 3 — run the server

snac httpd /home/snacusr/fedidata

🌈 Step 4 — nginx said "let me handle this"

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. 😭 fr fr.

🧚 Apache2? Say less, we got you

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>

Not to be that girl, but notice the /social up in the main web access point and the /share on that last /authorize_interaction block? That's literally what the page says, so keep it exactly like that. 🙈

🫶 FastCGI girlies, this one's for you

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 — the only thing is 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. 🌟

🍓 OpenBSD httpd? lowkey iconic

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. Here's the 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)

Go read your sisters, they're serving too. 💜

👑 AUTHORS 👑

grunfink @grunfink@comam.es: https://comam.es/snac/grunfink

That's the legend. Respect. 🫡

🎀 LICENSE 🎀

See the LICENSE file for details.

💀 CAVEATS 💀

JSON files are fragile when modified by hand. Take care. 😭

Like, do NOT be out here hand-editing JSON with reckless abandon, bestie. It WILL break and it WILL not warn you first. Be gentle. 🌸

and that's a wrap on SNAC(8) 💅✨ this one ships as the Debian build (version placeholder $Mdocdate$ doing its thing, dated $Mdocdate$) — so go forth, install your little Fediverse corner, and slay responsibly. periodt. 🦋💖🌈

📦 where this page comes from

ubuntu stonking: snac2 2.94-1 · MIT
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-11-03: a language model's rewrite of the original, under its terms