GoAdmio

cloudflare

Configure Cloudflare DNS records, SSL, caching, and security settings for one or all hosted domains through the Cloudflare API

On this page: Overview · Quick start · Syntax · Options · Operations · Output · Examples · Troubleshooting · Details · Caveats · See also


Overview

/go/cloudflare is the single entry point GoAdmio uses to manage Cloudflare. Depending on the options you pass, it can:

Every operation works on one domain, or on every hosted domain at once with --domain all. Domains marked API Ignore in GoAdmio are always skipped.

[!WARNING] Several operations delete DNS records or entire zones. The default mode also deletes and recreates the @ and www records. Read Operations and Caveats before running anything with --domain all.


Quick start

# 1. Save your Cloudflare credentials once
/go/cloudflare --cloudflareaccountid <account-id> --cloudflareapitoken <token>

# 2. Point a domain at this server and apply the standard settings
/go/cloudflare --domain example.com

Syntax

# Save credentials (nothing else runs)
/go/cloudflare --cloudflareaccountid <id> --cloudflareapitoken <token>

# Default mode: DNS + standard Cloudflare settings
/go/cloudflare --domain <domain|all> [--proxy on] [--action google|zoho]

# An action
/go/cloudflare --domain <domain|all> --action <action> [--value <value>]

# A record type
/go/cloudflare --domain <domain|all> --type <type> [--name <name>] [--value <value>] [--priority <n>] [--proxy on]

At least one -- option is required. Running the command with no options prints Invalid Arguments. and exits.

Every call is appended to /var/log/go/cloudflare.log, including the arguments you passed. See Security.


Options

Option Required Default Notes
--domain Yes — A domain that exists in /home, or all for every hosted domain. See Which domains are processed.
--type No — Selects a record type or record operation. See Types.
--action No — Selects an action. See Actions.
--name No @ Record name for --type txt and --type cname.
--value No Depends on the operation Record content, IP, or TTL. See each operation.
--priority No 0 MX priority for --type mx.
--proxy No Off on, true, or 1 turns the Cloudflare proxy (orange cloud) on. Any other value, or no value, turns it off.
--cloudflareaccountid No — Saves the account ID, then exits.
--cloudflareapitoken No — Saves the API token, then exits.
--mode No respect Accepted but not used by the script.

An unrecognized option stops the command with MAIL: Unknown parameter: <option>. The MAIL: prefix is a label left over from another script. Nothing is changed.

Prerequisites

Requirement Details
Credentials Saved in the Config table of /var/lib/sqlite/config.db. Without them the command prints a "Cloudflare API Configuration Required" box and exits.
API token permissions Must cover the operations you use: reading zones, editing DNS, editing zone settings, firewall access rules, cache rules, page rules, bot management, and creating or deleting zones. Check Cloudflare's current permission names when you create the token.
Zones in Cloudflare Each domain must exist in the Cloudflare account, except when you use --action addsite.
Tools curl, sqlite3, and dig. jq is needed for the status messages of spf, dmarc, txt, cname, and mx. ping and gawk are needed when an external SMTP host is configured.
Internet access To api.cloudflare.com, checkip.amazonaws.com, and icanhazip.com.

Operations

The command picks what to do from --type and --action. Spelling and case matter. Only the variants listed are accepted.

Default mode

Run with --domain and no --type or --action, or with --action google or --action zoho and no --type.

/go/cloudflare --domain example.com [--proxy on]
Step What happens
Redirect setting Sets the domain's GoAdmio SSLRedirect to 0 when --proxy on, otherwise 1. This prevents redirect loops behind Cloudflare. With all, it applies to every site.
Delete Removes existing A and AAAA records for @, the www A record, and the www, webmail, and go CNAME records.
Create A and AAAA for @ (this server's IPv4 and IPv6), and CNAMEs www, m, and * pointing to the domain (proxy follows --proxy). CNAMEs go and ftp are created with the proxy off.
Mail records See Mail handling in default mode.
Zone settings See Settings applied.
Firewall Adds a Cloudflare IP Access Rule that allows this server's IPv4, with the note Allow Server IP.

For a subdomain whose parent domain has a zone, only the subdomain's A record is replaced, in the parent's zone.

Actions

--action Also needs What it does all supported
google — Default mode, then replaces all MX records with Google Workspace MX records (ASPMX.L.GOOGLE.COM priority 1, ALT1 and ALT2 priority 5, ALT3 and ALT4 priority 10). SPF, DKIM, and DMARC are not added. Yes
zoho — Default mode, then replaces all MX records with mx.zoho.com (10), mx2.zoho.com (20), and mx3.zoho.com (50). SPF, DKIM, and DMARC are not added. Yes
addsite — Creates the domain as a zone in your Cloudflare account. Silent. Yes
removesite, deletesite — Deletes the whole zone from Cloudflare, with all its DNS records. Yes
cache, Cache — Creates a "Cache everything (Respect Origin)" cache rule and sets the browser cache TTL from the site's saved value. Yes
nocache, NoCache — Deletes a ruleset in the zone. See Caveats. Yes
nameservers, nameserver, dns, DNS — Prints the zone's two Cloudflare nameservers and pushes them to any configured registrar. Root domains only. Yes
full, strict, flexible, off --type with the same value Sets the Cloudflare SSL mode. The value sent comes from --type. Yes
browser, browsercache, browsercachettl --value <seconds> Saves the browser cache TTL in GoAdmio and sets it in Cloudflare. Yes
deletea, deletearecord, DeleteARecord — Deletes the first A record found in the zone. --value is not used to filter. Yes
deleteallarecord, DeleteAllARecord — Deletes up to five A records in the zone, whatever their names. Yes
deletetxtrecord, DeleteTXTRecord --value <content> Deletes the first unproxied TXT record on the domain name whose content matches. Yes
deletealltxtrecord, DeleteAllTXTRecord — Deletes up to five rounds of the SPF, DKIM (dkim._domainkey), and DMARC TXT records. Yes
delete with --type a or --type cname Switches those types from add to delete. Single domain only. No

Types

--type Also needs What it does all supported
a, A --value <ip> (optional) Adds an A record for @ pointing to the IP in --value, or to this server's IPv4 if the value is empty or has no dot. Subdomains get an A record under their parent zone. With --action delete, deletes instead. Yes
www, webmail, go, ftp, m — Adds a CNAME with that name pointing to the domain. The proxy follows --proxy. Subdomains are skipped. Yes
spf --value (optional) Adds an SPF TXT record. Default: v=spf1 +a +mx +ip4:<server IPv4> [+ip4:<SMTP host IP>] <additional SPF records> ~all. Yes
dmarc --value (optional) Replaces the _dmarc TXT record. Default: v=DMARC1; p=quarantine; rua=mailto:info@<domain>; ruf=mailto:info@<domain>; adkim=r; aspf=r; fo=1; sp=quarantine;. Yes
dkim — Replaces the DKIM TXT record with the key from /etc/opendkim/<domain>/dkim.txt (host dkim._domainkey). On cPanel servers it uses the cPanel key and host default._domainkey. Root domains only. Yes
txt --name, --value Adds an unproxied TXT record. Yes
cname --name, --value Adds a CNAME. With --action delete, deletes the first CNAME matching --name. Add only
mx --value, --priority Adds an MX record on the domain. Default value: imap.<domain>. See Caveats about --action delete. Yes
deletemainarecord, DeleteMainARecord, deletemaina — Deletes the A record for the domain's own name. Yes
deletecname, DeleteCNAME, deletec, deletecnamerecord --value <label> Deletes the CNAME named <label>.<domain>. Yes
deletemailrecord, deletemailrecords, DeleteMailRecord, DeleteMailRecords — Deletes the CNAMEs mail.<domain> and webmail.<domain>, and the MX record pointing to mail.<domain>. Yes
resellerclubmail, ResellerClubMail — Switches mail to ResellerClub (Mailhostbox): MX us2.mx1, mx2, mx3.mailhostbox.com (priority 100), CNAMEs pop, imap, smtp, webmail, an SPF redirect=_spf.mailhostbox.com, and DMARC. Yes
deleterull, DeleteRull — Deletes the first active Cloudflare Page Rule. Run again to remove more. (The spelling is intentional in the script.) Yes

Output

There is no single output format. Typical lines:

[1/12] Configuring DNS for example.com...
[2/12] Skipping DNS Configuration for example.net | API Ignore Domains
[3/12] Adding A Record 203.0.113.10 (example.org) | Success.
Adding SPF Record for example.com | Success
Adding DMARC Record for example.com | Zone does not exist
Output Meaning
[N/C] Configuring DNS for <domain>... Default mode is running for this domain.
Skipping DNS Configuration for <domain> | API Ignore Domains The domain is flagged API Ignore in GoAdmio (the --apiignore option of create).
Record already exists. / Success. / Failed. Result of adding a single record, where the command checks it.
Adding <type> Record for <domain> | Success or | <message> Result for spf, dmarc, txt, cname, and mx. The message is Cloudflare's own error text.
Raw JSON Some delete operations print Cloudflare's full response.
Nothing Default mode, addsite, cache, full/strict/flexible/off, and several others print no result. Check the domain in Cloudflare to confirm.

[!NOTE] The exit status is 1 for most paths, including successful ones. Do not use it to detect failure in scripts.

Security

[!WARNING] The whole command line is written to /var/log/go/cloudflare.log. If you save credentials with --cloudflareapitoken, the token is stored in that log in plain text, and it is also visible in your shell history and the process list. Remove the entry from the log after saving credentials, or save them from the GoAdmio dashboard instead (Cloudflare API).

The token is stored unencrypted in config.db. Dynadot and ResellerClub nameserver updates send their API keys in the URL over plain http (port 2020) to the helper server configured in GoAdmio.


Examples

# Save credentials
/go/cloudflare --cloudflareaccountid <account-id> --cloudflareapitoken <token>
# Point one domain at this server (DNS only, no proxy)
/go/cloudflare --domain example.com
# Point every hosted domain at this server with the Cloudflare proxy on
/go/cloudflare --domain all --proxy on
# Switch a domain to Google Workspace mail
/go/cloudflare --domain example.com --action google
# Add a verification TXT record
/go/cloudflare --domain example.com --type txt --name _verify --value "abc123"
# Add a proxied CNAME
/go/cloudflare --domain example.com --type cname --name blog --value example.com --proxy on
# Add an MX record
/go/cloudflare --domain example.com --type mx --value mail.example.net --priority 10
# Refresh the SPF record
/go/cloudflare --domain example.com --type spf
# Show Cloudflare nameservers (and update the registrar if configured)
/go/cloudflare --domain example.com --action nameservers
# Set SSL mode to strict: pass the value in both options
/go/cloudflare --domain example.com --action strict --type strict
# Enable edge caching, then set a 4-hour browser cache
/go/cloudflare --domain example.com --action cache
/go/cloudflare --domain example.com --action browser --value 14400
# Add a new site to Cloudflare, then fetch its nameservers
/go/cloudflare --domain example.com --action addsite
/go/cloudflare --domain example.com --action nameservers

Troubleshooting

Symptom Likely cause Fix
Invalid Arguments. No -- option was passed. Use the --option value form.
MAIL: Unknown parameter: <option> Misspelled or unsupported option. --override and --skip are not accepted. Check Options.
Please Enter Domain. --domain is missing. Pass --domain <domain> or --domain all.
Domain "<domain>" does not exist /home/<domain> is missing. new is also rejected. Create the account first with create, or check the spelling.
"Cloudflare API Configuration Required" box Account ID or token is empty. Save both. See Quick start.
Credentials command prints nothing Expected. It saves the values and exits. Run a domain command to test them.
No output and no change Most operations are silent, and API errors are hidden. Check the zone and token permissions in Cloudflare.
Zone not found, or Zone does not exist The domain isn't in the account, or the account ID is wrong. Run --action addsite, then point the registrar to the nameservers.
--action strict does nothing The SSL value is read from --type. Pass --action strict --type strict.
AAAA record missing The server has no IPv6 address, so the record has empty content. Expected. Ignore, or enable IPv6 on the server.
Two SPF records on a domain Old SPF records are not deleted by --type spf. Delete the old one in Cloudflare, or use --action deletetxtrecord --value "<old SPF>".
--action deletea removed the wrong record It deletes the first A record in the zone. Delete the exact record in the Cloudflare dashboard.
Messages missing after spf, dmarc, txt, cname, mx jq is not installed. Install jq.
Redirect loop after enabling the proxy SSLRedirect is still on in GoAdmio. Re-run /go/cloudflare --domain <domain> --proxy on.

Details

Which domains are processed

With --domain all, the command loops over every folder in /home and applies the operation when all of these are true:

Check Rule
Name Contains a dot (default mode) or doesn't start with m. (most other operations).
Site content /home/<domain>/www exists, or the server has a /scripts directory.
API Ignore The site's APIIgnore value in GoAdmio is not 1.

Root domains and subdomains are told apart by stripping known two-part TLDs (such as .co.uk and .com.au) and counting the remaining dots, as in white. A subdomain is handled through its parent's zone, unless it has a zone of its own.

Mail handling in default mode

Default mode only creates mail records when the domain does not already use external mail. The command runs dig for MX records and skips mail setup when there are two or more MX records, or when any MX points to Google, Zoho, or Outlook.

Condition Records added
Mail setup applies SPF (server IPv4, plus the active external SMTP host's IP if one is configured, plus any additional SPF records), DKIM (dkim._domainkey), DMARC (_dmarc), CNAMEs smtp, imap, webmail (proxy off), and MX imap.<domain> priority 0.
--action google or --action zoho The provider's MX records only.

Settings applied

Default mode ends by setting these on the zone:

Setting Value
SSL mode strict (the origin needs a valid certificate)
Auto Minify CSS, HTML, JS on (Cloudflare has retired this feature, so the call may have no effect)
Always Use HTTPS On
Cache level Basic
Browser cache TTL The site's saved BrowserCacheTTL
Always Online On
Crawler Hints On
Bot Fight Mode On, with AI bots blocked
Security level Medium

How the command picks what to run

The checks run one after another, not as exclusive branches, so combining unrelated --type and --action values can trigger more than one operation.

flowchart TD
    A["cloudflare --options"] --> B{"Any -- options?"}
    B -- "No" --> X1["Invalid Arguments, exit"]
    B -- "Yes" --> C{"Credentials passed?"}
    C -- "Yes" --> C2["Save to config.db, exit"]
    C -- "No" --> D{"Domain valid?"}
    D -- "No" --> X2["Error, exit"]
    D -- "Yes" --> E{"Credentials saved?"}
    E -- "No" --> X3["Configuration box, exit"]
    E -- "Yes" --> F{"No type, and action empty/google/zoho?"}
    F -- "Yes" --> G["Default mode, exit"]
    F -- "No" --> H["Run each matching --action / --type block in order"]

Order of the blocks

When more than one block matches, they run in this order: addsite, removesite, a, deletea, spf, dmarc, deletetxtrecord, cache, nocache, deleterull, deletemailrecord, resellerclubmail, deletecname, nameservers, deleteallarecord, deletealltxtrecord, SSL mode, browser cache, deletemainarecord, www/webmail/go/ftp/m, dkim, txt, cname, mx. The spf, dmarc, txt, cname, mx, removesite, and credentials blocks exit when done.


Caveats

These are behaviors of the current script. They are listed so you can avoid surprises. Several are likely candidates for fixes.

Area Behavior
Logging The token passed with --cloudflareapitoken is written to the command log.
Exit status Most paths exit with 1, including successful runs.
--override, --skip mail, --mode --override and --skip are rejected as unknown options, and the script's later checks for them can never match. --mode is read but unused. As a result, edge cache is always "respect origin" and mail records can't be skipped.
SSL mode The value comes from --type, not --action.
--type mx --action delete The delete branch tests a variable that is never set, so this call adds an MX record. There is currently no working MX delete, except through --action google or --action zoho.
--domain all with --type mx or --type dmarc and no --value The default is built before the loop, so every domain gets imap.all or info@all. Pass --value, or run per domain.
--type spf Existing SPF records are not found (the lookup output is discarded), so a changed SPF is added next to the old one. Multiple SPF records are invalid.
deletea and --type a --action delete Delete the first A record in the zone (root domains). --value and the domain name are not used as filters.
deleteallarecord Removes up to five A records of any name, including subdomains.
nocache and cache Both pick the last ruleset ID in the zone. If the zone has other rulesets, the wrong one can be updated or deleted.
--type a with all A subdomain's result always prints Failed., even when it worked.
--type cname --action delete with all Ignores delete and adds a CNAME. Delete works for a single domain only.
--type cname --action delete Never prints Success. The --name lookup is an exact match, so use the full hostname.
--domain new with addsite Rejected by the domain check, so the "new sites only" path can't run. Use a domain name or all.
--proxy in single-record types www, webmail, go, ftp, m follow --proxy, unlike default mode, which always creates go and ftp unproxied.
TXT and CNAME values Values are inserted into JSON unescaped. Quotes or backslashes in --value break the request.
Browser cache TTL An empty or missing TTL sends invalid JSON. Cloudflare ignores it silently.
Messages Several messages contain a stray `
Progress counters [N/C] can be wrong or empty in single-domain mode. This is cosmetic.

See also

Command Description
white Add an IP to the whitelist
dns Add your domain to Cloudflare and edit the DNS zone
cname Add a CNAME record to a domain through Cloudflare
mx Add an MX record to a domain through Cloudflare
txt Add a TXT record to a domain through Cloudflare
spf Add or refresh the SPF TXT record via Cloudflare
dkim Add a DKIM TXT record in Cloudflare
dmarc Add a DMARC TXT record in Cloudflare
google Add Google verification and Workspace DNS records via Cloudflare
zoho Configure Zoho mail integration (MX, SPF, DKIM)
proxy Change Cloudflare's proxy setting
purge Delete the Cloudflare edge cache (purge everything)
securitylevel Set the Cloudflare security level
waf Block IPs via Cloudflare WAF
nameservers Change the nameservers for a GoAdmio server
dynadot Manage DNS records using Dynadot's API