GoAdmio

white

Whitelist an IP address on this server and in Cloudflare's firewall for every hosted domain

On this page: Overview · Quick start · Syntax · Arguments · Output · Examples · Troubleshooting · Details · See also


Overview

/go/white makes sure a trusted IP address is never blocked. In one run it:

Run it with no argument to whitelist the server's own public IP. This is useful so the server can fetch its own pages with curl and read file content without being challenged by Cloudflare. Pass an IP to whitelist an office, a monitoring service, or your own connection.

Subdomains are skipped, because a Cloudflare rule on the root domain already covers them.


Quick start

# Whitelist this server's own public IP
/go/white

# Whitelist a specific IP
/go/white 203.0.113.10

Syntax

/go/white [ip]
Form Behavior
/go/white Uses the server's public IPv4 address, detected through checkip.amazonaws.com.
/go/white <ip> Uses the IP you pass.

Every call is appended to /var/log/go/white.log with a timestamp and the arguments used.


Arguments

Argument Required Default Notes
ip No This server's public IPv4 address Only the first argument is used. See IP handling.

There are no -- options.

Prerequisites

Requirement Where it comes from
Cloudflare account ID CloudflareAccountID in the Config table of /var/lib/sqlite/config.db
Cloudflare API token CloudflareAPIToken in the same table. It needs permission to read zones and edit firewall access rules.
Domains in Cloudflare Each domain's zone must exist in that Cloudflare account.
Internet access Needed to detect the server IP and to call the Cloudflare API.

Output

The command prints one progress line per domain, followed by the raw JSON that Cloudflare returns for the rule.

[1/3] Allow 203.0.113.10 for example.com...
{"result":{"id":"...","mode":"whitelist","configuration":{"target":"ip","value":"203.0.113.10"},"notes":"Allow Server IP",...},"success":true,...}

[2/3] blog.example.com (Subdomain)...
[3/3] Cannot Get Zone ID for example.net...
Message Meaning
[N/C] Allow <ip> for <domain>... The Cloudflare rule is being created. The JSON that follows shows whether it worked ("success": true).
[N/C] <domain> (Subdomain)... The domain was recognized as a subdomain and skipped.
[N/C] Cannot Get Zone ID for <domain>... Cloudflare returned no zone for this domain. See Troubleshooting.
IP <ip> found The IP is already in the whitelist file. The command exits with status 1 and does nothing else.

[!NOTE] C counts every folder in /home whose name contains a dot, but N only advances for root domains. The counter can therefore stop below C. This is cosmetic.


Examples

# Allow the server itself (so it can curl its own sites through Cloudflare)
/go/white
# Allow an office IP on all domains
/go/white 198.51.100.25
# Re-apply an IP that is already in the whitelist file:
# remove its line first, then run the command again
sed -i '/^203.0.113.10$/d' /var/go/etc/white
/go/white 203.0.113.10
# Check what was run and when
tail /var/log/go/white.log

Troubleshooting

Symptom Likely cause Fix
IP <ip> found and exit status 1 The IP is already in /var/go/etc/white, so the command stops before touching Cloudflare. If you only need it whitelisted, nothing to do. To push it to Cloudflare again (for example after adding a new domain), remove the line from the file and run again.
Cannot Get Zone ID for <domain> The domain isn't in the configured Cloudflare account, its nameservers aren't on Cloudflare, or the account ID or token is empty or wrong. Check the credentials with cloudflare or config, and confirm the domain exists in that account.
Cloudflare JSON shows "success": false Invalid IP value, token without enough permission, or a rule for this IP already exists. Read the errors field in the JSON and fix the token scope or the IP.
A new domain isn't covered The domain was added after the IP was whitelisted, and the early exit prevents a second run. Remove the IP from /var/go/etc/white, then run /go/white <ip> again.
Subdomain is not whitelisted By design. Subdomains are skipped. The rule on the root domain applies to them.
Domain with a country-style TLD (such as example.co.uk) is skipped as a subdomain The two-part TLD isn't in the script's list. Report it, or whitelist that zone manually in Cloudflare.

Details

IP handling

Input Behavior
No argument The server's public IPv4 address is used.
Starts with a digit Treated as an IP: saved to /var/go/etc/white and sent to Cloudflare.
Doesn't start with a digit Not saved to the whitelist file, but still sent to Cloudflare as the rule value. Cloudflare will reject an invalid value.
Already in the file (exact line match) Prints IP <ip> found and exits with status 1.

Before the IP is appended, any line in the file that starts with the same text is deleted. Because this is a prefix match, an entry such as 203.0.113.1 could also remove lines like 203.0.113.10 if the exact line didn't exist. The . characters also act as regex wildcards. Keep this in mind if you add comments or neighboring addresses to the file.

Which domains are processed

A folder in /home is processed when all of these are true:

Check Rule
Name Contains a dot.
Site content /home/<domain>/www exists, or the server has a /scripts directory.
Root domain Not a subdomain. Subdomains are detected by stripping known two-part TLDs (such as .co.uk, .com.au, .org.uk, .in.net, .com.museum) and counting the remaining dots.

The Cloudflare rule

For each root domain the command looks up the zone ID, then sends this request to the Cloudflare firewall access rules endpoint:

{
  "mode": "whitelist",
  "configuration": { "target": "ip", "value": "<ip>" },
  "notes": "Allow Server IP"
}

The note is always Allow Server IP, even when the IP is not the server's own. Filter by that note in the Cloudflare dashboard to find the rules this command created.

What it does

flowchart TD
    A["white [ip]"] --> B{"Running as root?"}
    B -- "No" --> B2["Re-run with sudo"]
    B -- "Yes" --> C["Log the call"]
    B2 --> C
    C --> D["Read Cloudflare account ID and token"]
    D --> E{"IP given?"}
    E -- "No" --> E2["Use server public IP"]
    E -- "Yes" --> F
    E2 --> F{"IP already in /var/go/etc/white?"}
    F -- "Yes" --> X["Print 'IP found', exit 1"]
    F -- "No" --> G["Save IP to /var/go/etc/white"]
    G --> H["For each root domain in /home"]
    H --> I{"Zone ID found?"}
    I -- "No" --> I2["Print 'Cannot Get Zone ID'"]
    I -- "Yes" --> J["Create Cloudflare whitelist rule"]
    I2 --> K
    J --> K["Next domain"]
    K --> L["Run /go/fail2ban"]
  1. If the user isn't root, runs itself again through sudo.
  2. Appends a timestamped line to /var/log/go/white.log.
  3. Reads CloudflareAccountID and CloudflareAPIToken from /var/lib/sqlite/config.db.
  4. Detects the server's public IPv4 address with checkip.amazonaws.com.
  5. Uses the server IP if no argument was passed.
  6. If /var/go/etc/white exists and already has the exact IP, prints IP <ip> found and exits with status 1.
  7. Otherwise removes lines starting with the IP, then appends the IP to the file (only if it starts with a digit).
  8. Counts folders in /home that contain a dot.
  9. For each folder with a www directory (or when /scripts exists) that is a root domain, gets the Cloudflare zone ID.
  10. Creates the whitelist IP Access Rule in that zone and prints Cloudflare's response.
  11. Runs fail2ban.

[!NOTE] The IP is saved to the whitelist file before any Cloudflare call. If the Cloudflare step fails, the IP stays in the file, and the next run will exit early with IP <ip> found. See Troubleshooting.


See also

Command Description
block Block an IP address on a GoAdmio server
unblock Unblock an IP address on a GoAdmio server
fail2ban Install and configure Fail2ban to ban brute-force sources
waf Block IPs via Cloudflare WAF
cloudflare Manage DNS records using Cloudflare's API
blacklist Block blacklisted IPs (bad bots and SSH brute-force attacks)
allow Open a port in your server's firewall