Redirects, basic auth and security rules

Route rules are checks the edge (OpenResty on ports 80 and 443) runs on every request before it reaches your app. Because the edge turns a request away itself, a blocked or rate-limited visitor costs your app nothing, and you don't have to change or redeploy any code. Saving a rule pushes it to the edge immediately.

A rule can do any mix of:

• redirect a path or a pattern to another path or URL (301, 302, 307 or 308);
• basic auth: ask for a username and password;
• rate limit each client IP;
• allow only some HTTP methods or countries, deny IP ranges, ban IPs, countries or user agents;
• hotlink protection: only serve requests whose Referer is one of your sites.

Add a rule

Redirects

Under Redirect:

How they behave:

• Path prefix matches on whole path segments: /old matches /old and /old/post, but not /older. The rest of the path is appended, so /old-blog → /blog sends /old-blog/2024/hello to /blog/2024/hello.
• Regex matches the path (without the query string). Use $1 to $9 in To for capture groups: ^/posts/(\d+)$ → /blog/$1.
• The query string is kept, unless To already contains a ?.
• The redirect is answered at the edge before the request reaches your app.

Examples:

Limits: a rule holds at most 50 redirects (the panel adds one per rule). A prefix redirect whose relative destination lies inside its own source (for example /a → /a/b) is refused because it would loop, and so is a $1 in a prefix redirect. 303 isn't offered, because it changes the request method.

To send a whole domain to another one (for example www to the bare domain), use the domain's Redirect setting instead; see Redirect one domain to another.

Basic auth

Under Basic auth on the Security page, enter a Username and a Password. Visitors then get the browser's sign-in prompt, and requests without the right credentials receive 401.

• Put /admin in Path prefix to protect only that part of the site, or leave it empty to protect everything.
• The username can be 1 to 64 characters without :; the password up to 128 characters.
• The password is hashed by the API and never shown again ("The password is stored hashed and can't be shown again."). To change it, add a new rule and remove the old one.
• Enter both fields or neither: the form says "Enter both a username and a password" otherwise.
• Basic auth also applies to API calls and webhooks sent to the protected paths. Leave those paths out, or your integrations will get 401.

Rate limits and access control

The remaining Security fields:

Examples:

• Slow down brute force on a login page: Path prefix /login, Requests / sec 5, Burst 5.
• Private staging site: no path prefix, Allow only countries DE, plus basic auth.
• Keep scrapers off an API: Path prefix /api, Ban user-agents python-requests, scrapy, Block empty user-agent on.

How rules combine

For each request the edge picks one rule for access control: the enabled rule whose Path prefix is the longest match for the request path (a rule without a prefix is the fallback for everything else). That rule's checks run in this order: allowed methods, denied and allowed ranges, allowed countries, bans, hotlink, rate limit. The first check that fails blocks the request.

Basic auth and redirects are different: they look at every rule whose prefix matches. The most specific basic auth applies, and the first matching redirect of the most specific rule wins. So a site-wide password still covers /api even if /api has its own rate-limit rule.

This means a rule for /api replaces a site-wide rate limit or ban for requests under /api. Repeat the settings you want to keep in the more specific rule.

Known limits

• Rules added in the panel apply to all hostnames of the project. To scope a rule to one domain, use the CLI's --domain option or the API. The panel still labels such a rule All hostnames.
• Rule path prefixes (for rate limits, access lists, bans and basic auth) match as plain text: /api also covers /api-docs. A trailing slash (/api/) keeps a rule inside one folder, but then no longer covers /api itself. Redirect sources are different: they match whole path segments.
• Both Ban countries and Allow only countries block visitors whose country can't be determined. Countries come from the GeoLite2 database built into the edge; if the project's Monitoring tab says "Country data unavailable on this edge", either rule blocks everyone.
• Rules need the Synq edge in front of the app. Projects on Synq Cloud don't have them.
• IP-based checks use the visitor's real address only if the edge can see it. Behind Cloudflare's proxy this works automatically (the edge trusts Cloudflare's published ranges and reads CF-Connecting-IP). Behind another proxy or a load balancer, every visitor looks like the proxy and shares one rate-limit bucket. SYNQ_EDGE_TRUSTED_PROXIES and SYNQ_EDGE_REAL_IP_HEADER only apply to an edge installed directly on a server; the edge container of a standard (Docker Compose) install has its real-IP settings built in and ignores them. See Real visitor IPs.

From the CLI

synq edge rules manages the same rules. The CLI covers rate limits, bans and access lists; redirects and basic auth are set in the panel or through the API.

# 20 requests/second per client IP on the login path, allowing bursts
synq edge rules add -p <projectId> --path /login --rate-limit 20 --burst 40

# Block two countries and one IP, answering 403
synq edge rules add -p <projectId> --ban-country RU,CN --ban-ip 203.0.113.7 --block-status 403

# Only let an office network in (everyone else is denied)
synq edge rules add -p <projectId> --allow-cidr 198.51.100.0/24

# Scope a rule to one domain of the project
synq edge rules add -p <projectId> --domain <domainId> --rate-limit 50

synq edge rules list -p <projectId>
synq edge rules rm <ruleId> -p <projectId>

See the synq edge rules reference for every option.

Related