Mastodon Instance Federation Mode: How to Set Allowlist vs Denylist

Mastodon instance administrators must decide how their server talks to other servers across the fediverse. The default mode, often called open federation, lets your instance communicate with any other instance unless it is explicitly blocked. However, some administrators need stricter control to protect their community or comply with internal policies. This article explains the difference between allowlist and denylist federation modes and provides step-by-step instructions to configure each mode on your Mastodon instance.

What Are Allowlist and Denylist Federation Modes?

Federation in Mastodon is the mechanism by which different instances exchange posts, profiles, and other data. By default, a Mastodon instance operates in open federation mode: it accepts communication from any other instance unless that instance is manually added to a blocklist. This open model is the foundation of the fediverse, but it also exposes your community to spam, harassment, or content that violates your instance rules.

Two alternative federation modes give administrators more granular control:

Allowlist Mode

In allowlist mode, your instance only communicates with instances you have explicitly approved. All other instances are blocked by default. This mode is sometimes called “whitelist” federation. It is the most restrictive option and is typically used by private or enterprise instances that need to limit interactions to a known set of trusted servers. For example, a company might run a Mastodon instance for internal communication and only allow federation with the company’s other regional instances.

Denylist Mode

In denylist mode, your instance communicates with all other instances except those you have specifically blocked. This is the standard behavior for most public instances. Administrators add instances to the denylist when they receive reports of spam, harassment, or policy violations. Denylist mode gives you the flexibility to reactively block problematic servers without limiting the openness of your instance.

Steps to Configure Allowlist or Denylist Federation Mode

Before you begin, ensure you have administrator access to your Mastodon instance. You will need to edit environment variables in the .env.production file and use the web administration interface. The process differs slightly depending on whether you run a single-user instance or a multi-user instance.

Method 1: Enable Allowlist Mode Using Environment Variables

The most reliable way to enable allowlist mode is to set the ALLOWED_DOMAINS environment variable. This variable tells Mastodon to only accept federation from the listed domains. All other domains are automatically denied.

1. Open the .env.production file
   SSH into your Mastodon server and navigate to the Mastodon installation directory. Open the .env.production file with a text editor such as nano or vim.
2. Add the ALLOWED_DOMAINS variable
   Add a new line: ALLOWED_DOMAINS=example.com,another-instance.social. Separate multiple domains with commas. Do not include spaces between domains.
3. Save the file and restart Mastodon services
   Run systemctl restart mastodon-web mastodon-sidekiq mastodon-streaming to apply the changes.
4. Verify the setting in the admin panel
   Log into your Mastodon instance as an administrator. Go to Administration > Server Settings > Federation. The page will display the allowlist status and list the approved domains.

Method 2: Use the Denylist Mode via the Admin Interface

Denylist mode does not require an environment variable change because it is the default behavior. You add domains to the deny list through the web interface.

1. Open the Federation settings
   Log into your Mastodon instance as an administrator. Navigate to Administration > Server Settings > Federation.
2. Add a domain to the denylist
   In the “Blocked domains” section, enter the domain of the instance you want to block. Click the “Add domain” button.
3. Choose the severity level
   Mastodon offers three levels of blocking: “Reject media files,” “Reject all incoming posts,” and “Silence the domain.” Select the appropriate level for your needs. “Reject all incoming posts” is the strictest denial option.
4. Save your changes
   Click “Save changes” to apply the block. The blocked domain will appear in the list.

Common Mistakes and Limitations When Configuring Federation Modes

Allowlist Mode Blocks All Unlisted Domains, Including Your Own

When you set ALLOWED_DOMAINS, you must include your own instance’s domain in the list. If you forget to add your own domain, your instance will not be able to federate with itself, which breaks user profiles and post visibility. Always test the configuration by visiting your instance’s public timeline after applying the change.

Denylist Mode Does Not Prevent Future Federation Attempts

Adding a domain to the denylist stops current federation with that instance. However, if the blocked instance changes its domain name or uses a different subdomain, it may still be able to reach your server. For complete control, consider using allowlist mode instead.

Environment Variables Override Admin Panel Settings

If you set ALLOWED_DOMAINS in .env.production, the admin panel’s allowlist settings will be ignored. Mastodon reads the environment variable first. If you want to manage the allowlist solely through the admin interface, remove the ALLOWED_DOMAINS variable from the environment file.

Allowlist vs Denylist Federation Mode Comparison

Item	Allowlist Mode	Denylist Mode
Default behavior	Block all instances by default	Allow all instances by default
Configuration method	ALLOWED_DOMAINS env variable	Admin panel > Server Settings > Federation
Best use case	Private or enterprise instances	Public or community instances
Maintenance overhead	High (must manually approve each new instance)	Low (only block problematic instances)
Risk of unwanted content	Very low	Moderate

Allowlist mode provides the highest security but requires constant maintenance as new instances appear. Denylist mode is easier to manage but leaves your instance exposed to unwanted content until you manually block the offending server.

After configuring your federation mode, monitor the instance logs and user reports for the first few days. If you chose allowlist mode, check that all desired instances are included. If you chose denylist mode, review the blocked domains list weekly to ensure no new problematic servers have appeared. For advanced control, combine federation mode with the Authorized Fetch setting in Administration > Server Settings > Federation to require authenticated requests from other instances.