Blocklists and rule groups

A blocklist subscription is a list of hosts Outbound downloads and turns into rules. Pick a list from the library of popular blocklists or add any HTTPS address, and Outbound keeps the rules current: it re-downloads the list on a schedule and replaces its rules in one step. Manage subscriptions in Settings › Blocklists (see the Blocklists settings) or with outboundctl blocklist (see outboundctl).

Example data.

During setup, Block ads and trackers can subscribe to one starter list: “Peter Lowe’s list · about 3,500 ad and tracking servers, refreshed daily”. The subscription name is “Ads and trackers (Peter Lowe’s list)”.

Subscribing

Popular Blocklists… in the main window’s Blocklists pane, or Add from Catalog… in Settings › Blocklists, opens a library of 60 well-known lists. It shows Featured lists, All Categories, or one category, and has a search field. Each row names the list, its publisher and its licence, and its details give a description, the download address, the format (domains and hosts, or IP addresses and networks) and the size measured when the library was prepared. A list that is over Outbound’s per-list limit says so and cannot be loaded. Select several and choose Add N Blocklists. These lists are made and updated by their publishers.

To add a list that is not in the library, Add Blocklist… asks for:

• Name, with the prompt “optional”. Empty means the server’s host name is used, or the full address when the URL has no host.
• Address: an https URL. The prompt is https://example.com/hosts.txt. An address that is not https is refused. A redirect away from https stops the download.
• Rules: Block these hosts or Allow these hosts.
• SHA-256, prompt “optional”. The line under it: “With a SHA-256, Outbound refuses the list when its content is not exactly the one you pinned. Leave it empty if the list changes.” You can write sha256: at the front. Surrounding spaces and capital letters are ignored. The value has to be 64 hexadecimal digits, or the field says “A SHA-256 is 64 hexadecimal digits.”

You cannot subscribe to the same address twice. The message is “You are already subscribed to url.”

What a list rule looks like

Each entry acts as one rule: the subscription’s action, outgoing, any app, any port, any protocol, forever. The destination is a domain (which covers its subdomains), an exact host, an address or a network, depending on the line. The Rules pane labels these Blocklist: name, or Blocklist when the name is not on hand.

Formats Outbound accepts

A list is plain text. Domains from any of these syntaxes become a domain rule, so they also cover subdomains. A *.example.com wildcard is reduced to that domain.

• A hosts-file entry, such as 0.0.0.0 ads.example.com. Several names after the address are all taken.
• A plain domain on its own line. A single-label name is not a domain, so a line that is only printer is skipped.
• An adblock-style ||example.com^ entry.
• A CIDR network or a single IP address.

Comments (# and !), blank lines, adblock exceptions (@@) and cosmetic filters (##) are skipped. Names are lowercased and duplicates are removed. Localhost and broadcast names are skipped: localhost, localhost.localdomain, local, broadcasthost, and the ip6- names a hosts file uses for them.

A list may also be a rule group in the .lsrules JSON format. Outbound takes deny entries for any program, outgoing, with no port, protocol or other condition. Exact hosts come from that file’s host lists (a single label such as printer is allowed there). Domains come from its domain lists. An allow-list subscription pointed at a .lsrules body installs nothing.

Refreshing

A subscription refreshes every 24 hours by default. To change that, select the list in Settings › Blocklists and choose a Refresh Interval: every hour, 6 hours, 12 hours, day or week. The same details show Last Fetched, Next Refresh and the number of entries, and Refresh Now fetches it at once. Outbound checks about once a minute for lists that are due, and tries a failed list again after 15 minutes. A manual refresh does not wait. Downloads send If-None-Match when they have an ETag, so an unchanged list can come back as not modified and leave the installed rules alone.

Limits:

• A download is capped at 64 MB and the request times out after 60 seconds.
• A block or ask list can hold up to 2,000,000 entries. An allow list can hold up to 200,000. A list over its limit is refused whole.
• A refresh that returns no usable entries keeps the previous rules in force.

Success and failure can notify you. “Blocklist updated” (or “Rule group updated” for an allow list) is off by default. Failure is on. The switches are in Settings › Notifications.

Entries you control

• Turn a list off: switch Enabled off in the list’s details. Its entries stop deciding connections, but they are kept and the list still refreshes on schedule, ready to turn back on.
• Browse entries: Browse Entries… in a list’s details, or All Entries in the main window’s sidebar for every list together. Search the entries and filter them by Used, Enabled, Disabled or Unapproved. Each entry shows its kind (host, domain, address or network), how many times it decided a connection and when it last did.
• Switch one entry off: Disable Entry… turns that entry off for every app, after you confirm. Other lists that hold the same entry still apply. The entry stays off when the list refreshes, and Edit › Undo brings it back.
• Review new entries: with Mark new blocklist entries for review on in Settings › Advanced, entries a refresh adds are marked. Review New Entries… in the list’s details shows them, with Approve and Approve All.

From Terminal, outboundctl blocklists entries, blocklist entry enable|disable, blocklists new and blocklists approve do the same. See outboundctl blocklist.

When a list blocks something you need

Select the blocked connection in the Network Monitor. In the inspector, the blocklist badge names the list and the exact entry, for example “Blocked by Example list · ads.example.com”, and its menu shows when the list was last fetched. From there:

• Allow for app Only makes an exception for that app alone.
• Allow for Every App… asks you to confirm separately. It saves a priority rule, “Allow destination for every app, with priority, on ports”, and lists which of your rules it would override.
• Show Entry in list, Disable Entry… and Turn Off list… change the list instead.

Exceptions that earlier versions of Outbound made for every app are listed at the top of Review under Review Existing Blocklist Exceptions, so you can choose the app each one is for. They keep working as before until you change them.

When a list suddenly shrinks

A refresh that would leave fewer than a tenth of the list’s largest size is refused, and the previous rules stay. The largest size is the larger of the number installed now and the most entries this subscription has had. Exactly a tenth is accepted. Below that, it is not. If a list really did get smaller, remove it and add it again.

Allow lists

An allow list stages its entries as a review group instead of installing rules at once:

• New entries wait as pending and match nothing until you accept them.
• Entries you accepted become allow rules in a rule group. You can edit them like your own rules.
• An entry the list drops is removed if it is still an allow. One you turned into a block or an ask becomes yours (source You) and stays.

The shrink check for an allow list uses the number of entries the group already has.

Rule groups

A rule group is a set of rules Outbound installs together. Three kinds show up in the Rules pane:

• Trusted by default (see Trusted apps). While one of those groups stays on, a rule you switch off inside it stays off. Turning the group off removes its rules.
• Known telemetry, built from the tracker database.
• The groups a downloaded allow list produces, described above.

outboundctl update-rule-groups asks Outbound to refresh list content from outside the app, the same request as outboundctl blocklist update.

Managed rule feeds

An administrator can distribute rules from an https address set with managed preferences. Outbound fetches the feed at launch and about every six hours. A SHA-256 pin is optional. The feed is capped at 50,000 rules and 32 MB. A feed rule may last forever, until a date, or on a schedule. A lifetime tied to a process, a login session or a startup is refused. See Managed rule feed.