SmartShield

The SmartShield is the protection Cosmos puts in front of your URLs. It watches how much each visitor consumes (requests, bandwidth, time, simultaneous connections) and slows down, then blocks, the ones that behave like an attack or a runaway script. Normal visitors never notice it.

It is enabled per URL (see URLs), and it is recommended to keep it enabled everywhere. This page explains how it decides to block someone, and how to use the Bans and Whitelist tabs of the URLs page to see what is going on and fix it when someone gets blocked by mistake.

How it works

For every URL, the SmartShield keeps a budget per visitor over the last hour: number of requests, amount of data, and number of simultaneous connections.

• A visitor going over a budget is first throttled: requests still go through, just slower.
• A visitor going far over a budget gets a strike: they are blocked for 1 hour.
• 3 strikes within 24 hours become a temporary ban. The first one blocks for 4 hours, the second for 24 hours, and the following ones for 72 hours.
• 3 temporary bans within 7 days become a permanent ban, which stays until you remove it.

With Cosmos Pro, the SmartShield never issues permanent bans: a repeat offender gets another 72 hours ban each time. Pro servers often see many people behind a single IP address (an office, a campus), and this avoids locking all of them out for good because of one.

How far is "far over" depends on the Policy Strictness of the URL: with Strict a strike is issued as soon as the budget is exceeded, with Normal at twice the budget, with Lenient at three times.

A blocked visitor receives a "Too many requests" error, and the block applies to all your URLs, not only the one where it happened. Strikes and temporary bans are forgotten after 7 days.

Who is a "visitor"

• Someone logged in to Cosmos is counted per user. Several people behind the same internet connection (an office, a family, a university) each get their own budget, and one of them misbehaving does not block the others.
• Anonymous visitors are counted per IP address.

With Constellation

If your servers are connected through Constellation, strikes and bans are shared: someone banned by one server is blocked by all of them, and the Bans tab shows the whole picture whichever server you open it from.

The Bans tab

Go to URLs, then the Bans tab.

The top of the page shows what Cosmos has been blocking. Use Latest, Hourly and Daily to change the time range.

• Blocked requests: how many requests were blocked over time.
• Blocked by reason: the same, split by what blocked them: bots, geolocation (blocked countries), referer, hostname (usually someone scanning your IP), IP whitelists (including URLs restricted to Constellation), and the SmartShield itself.

Below, Strikes and bans lists every visitor that has been struck or banned. You can search by visitor or by URL name.

• Client: the IP address, or user: followed by the nickname for a logged-in user.
• Status: Strike, Temporary ban, Permanent ban, or Clear when the visitor has a history but is not blocked at the moment.
• Blocked until: when the block ends. ∞ for a permanent ban.
• Last reason: which budget was exceeded, by how much and on which URL. For example requests 36012 of 36000 on jellyfin.
• History: the number of past strikes and bans. Hover it to see each of them with its date, its reason and the server that issued it.

Unblocking someone

Click Unban on the row (or Clear strikes if they are not banned yet) and confirm. This wipes the whole history of that visitor, on every server of your Constellation, and they can come back right away.

If the same visitor keeps getting blocked for legitimate reasons, either raise the budgets of the URL they use (see below) or add them to the whitelist.

The Whitelist tab

IP addresses in the whitelist are never throttled, struck or banned by the SmartShield, on any URL. This is the place to put your office, your home connection, or your monitoring service. The list is global, and applies to HTTP, TCP and UDP URLs.

Click Add IP:

• IP or CIDR: a single address (203.0.113.7) or a range (10.0.0.0/8). IPv6 works too.
• Label: a note for yourself, to remember what this address is.
• Bypass geo restrictions: also let this address through when its country is blocked.
• Bypass URL IP restrictions: also let this address reach URLs that are limited to a list of IPs, or restricted to Constellation.

Leave the two options unticked if all you want is to protect an address from bans. To change an entry, delete it and add it again.

Tuning the SmartShield of a URL

Open a URL from the URLs tab and go to its Security section. Under Smart Shield:

• Smart Shield Protection: turns the SmartShield on for this URL.
• Policy Strictness: Strict, Normal or Lenient, as explained above.
• Per User Request Limit: requests per hour.
• Per User Byte Limit: data per hour.
• Per User Time Budget: cumulated time spent serving the visitor per hour, in milliseconds.
• Per User Simultaneous Connections Limit: connections opened at the same time by one visitor.
• Max Global Simultaneous Connections Limit: connections opened at the same time by everyone. Above it, new visitors wait for a free slot.
• Privileged Groups: the people the SmartShield ignores on this URL. Admins only by default.

Leave a field on 0 (or Default) to use the default value:

| Setting | Default | Default with Cosmos Pro | |---|---|---| | Policy Strictness | Normal | Lenient | | Requests per user | 18 000 per hour | 200 000 per hour | | Data per user | 200 GB per hour | 1 TB per hour | | Time budget per user | Unlimited | Unlimited | | Simultaneous connections per user | 100 | 500 | | Global simultaneous connections | 2 000 | 20 000 |

The defaults are generous on purpose: they are meant to stop abuse, not to get in the way. Lower them on a URL that is expensive to serve, raise them on one that legitimately moves a lot of data (backups, media, a package registry).