DNS Hooks

dns_create_post.sh

The dns_create_post.sh script runs after a DNS zone is created, triggered when the zone is added to the named.conf.

Environment variables

• domain: name of DNS zone
• signed_zone: 0|1 Will be 1 if the zone being added is domain.com.db.signed
• skip_template: 0|1 Will be 1 if the hook is called during a restore, else 0 for all other creations.
• zone_existed: 0|1 Will be 1 if the zone was already in the named.conf (not common)
• username: Set to the User who owns the zone, when applicable. For caller=create:raw_save, it will be the local Admin account.
• caller: The possible caller values are:
  • create:zone: create a zone at the Admin Level
  • create:domain: create a domain
  • create:pointer: create a domain pointer
  • create:swap: rename a domain name
  • create:raw_save: raw zone, saved to this box, triggered by remote multi-server
  • create:dnssec: add the new domain.com.db.signed zone
  • remove:dnssec: add the non-signed domain.com.db from unsigning.

Note: Restores that have a DNSSEC signed zone will trigger this hook twice, hence the need for a signed_zone=1 check. Both skip_template and zone_existed were added in 1.674.

---

dns_delete_post.sh

This script runs after a DNS zone is created deleted.

Environment variables

• domain: name of DNS zone
• USERNAME: User who owns the zone, if created with a Domain.
• CREATOR: Creator of the User who owns the zone
• PACKAGE: package of this User.

Note: Similar to dns_write_post, the USERNAME, CREATOR, and PACKAGE are only set if this zone is below a User-owned domain and allow_ttl_override is 1. Manually created zones via the Admin Level without a Domain/User won't have these variables set as there is no associated User. Note: Deleting a missing DNS record does not throw an error. The logic behind this is that the desire for it to be gone was already true. This is especially useful when deleting multiple records where only some are missing, we don't throw an error so they can confirm the requested records are all gone.

However, it may be useful to know that some records were indeed missing prior to the removal. This change will add a warning message for each missing record, eg:
www A 1.2.3.4 did not exist
after the successful text:
Records Deleted

Either way, no error will be thrown after all records are confirmed gone from the zone.

---

dns_raw_save_post.sh

This post script is for the Multi Server Setup API and used for saving a raw DNS zone (CMD_API_DNS_ADMIN) when action=rawsave&domain=domain.com.

The main reason for its existence is because dns_write_post.sh doesn't get triggered for DNS clustering saves. This would be the script to use if a clustered write is required.

Environment variables

• domain: domain for newly saved domain
• remote_username: user that owns the zone on the remote server, when applicable.
• remote_hostname: hostname of the remote server calling this request.
• filename: zone filename, usually /var/named/domain.com.db, or /etc/bind/domain.com.db for Debian.
• sign_zone: yes or no depending on if it was reqested by the client (sign_zone=yes in GET). yes will trigger a dns_write_post.sh after the dns_raw_save_post.sh. A DirectAdmin master will not set sign_zone=yes when sending the zone to this slave, but a 3rd party API call could request it.

The actual data will have to be retrieved directly from the db filename.

This script is called before the dns_create_post.sh hook.

The remote_username and remote_hostname are set by the client in their GET request (eg: master DA version).

3rd party calls might not set these, thus might be missing or blank.

remote_*, filename, sign_zone values were added to the script variables in DirectAdmin 1.676

---

dns_write_post.sh

The dns_write_post.sh script is called after DNS zone data is updated.

Environment variables

• DOMAIN: name of DNS zone
• DOMAIN_IP: IP assigned
• SERVER_IP: server IP
• WWW_IP: ip used for www. A records
• USERNAME: Name of the User which owns the Domain, if applicable.
• PACKAGE: Current User package, if applicable.
• CREATOR: The creator of the given User, if applicable.
• SERIAL: Serial used in the zone
• EMAIL: Authoritative email
• NS1: Authoritative ns zone
• INCLUDE_DNSSEC_KEYS: list of paths to DNSSEC keys, one per line... has $include at the beginning
• Url encoded list of ${resource name}=${Value} pairs of specific DNS record.
  • A
  • AAAA
  • CNAME
  • MX: This only shows the only the value of MX record (${MX server name}=${priority}). Left for backwards compatibility. It is better to user MX_FULL.
  • MX_FULL: List of full mx records (${resource name}=${MX server name} ${priority}
  • NS: This is the only list where the pair is flipped (${value}=${resource name})
  • PTR
  • DS
  • CAA
  • TLSA
  • TXT
  • SPF
  • SRV
• DEFAULT_TTL: Default TTL set in directadmin.conf
• [RECORD]_TIME: default TTL value for specific RECORD type, eg: A_TIME=3600
• caller: Name of the parent function/action that triggered the dns_write_post.sh hook call. Possible values:
  • Domain::createSubdomain
  • Domain::createSubdomain:pointers
  • Domain::deleteSubdomains:pointers
  • Domain::deleteSubdomains:domain
  • Domain::add_ip_to_domain_dns
  • Domain::delete_ips_from_domain_dns
  • Named::rewriteDomains
  • Named::swapIPs
  • Named::swap_domains
  • Named::raw_save: sign_zone=yes
  • Named::remove_IPs_from_zone
  • Named::merge_db_file
  • Named::resetZone
  • Named::remove_dnssec
  • Named::sign_zone
  • Named::sign_zone
  • Named::add_subdomain_ds_to_parent
  • Named::taskq_dns
  • Named::set_mx_template
  • There are about 20 other cases where the caller value is not set. If you need a specific case logged, just ask and we can add more caller flags.

Note: the USERNAME, CREATOR and PACKAGE variables are only set when:

• da config-get allow_ttl_override returns 1, whichis the default value.
• The domain for this zone is created by a User, and listed in the /etc/virtual/domainowners file (must be a Domain owned by User, not a raw zone added by Admin)

---

special_exit_code 42

There are some cases where you'd like to have your hook output shown in the result, even if there are no errors.
Most of the time, any output from a script that returned zero (0 == no error), is not displayed.

This feature will allows for the script output to be forced to the visible result, even if it's not normally shown.

Internal directadmin.conf default:

special_exit_code=42

where you can disable the feature by setting it to 0, eg:

./directadmin set special_exit_code 0
service directadmin restart

This is only available for dns_write_post.sh upon development, but this feature can be made available to more hooks upon request, assuming reasonable need.

named_action_post.sh

This script will be called anytime DA makes any call to the named service, including 'start', 'stop', 'restart', 'reload', etc.

This can be used in case you need to trigger something anytime a local change is done on the DA side where named is altered.

The exit code does not affect any code logic, but if you exit with a non-zero result, the output will be saved to /var/log/directadmin/errortaskq.log.

If the exit code is 0 AND there is something to output, then DA will log it to system.log. So if everything went well, do not output anything, as that would just add more data to the system.log.

Environment variables

• action : given action that was just performed (start, stop, restart, reload, etc.)
• immediate (0|1): variable indicates if it's a task.queue action, which is 0, or 1 for immediate reloads, mainly for Let's Encrypt wildcards

---

taskq_dns_post.sh

This script will be called (and all data that was passed to the task.queue) for the:

action=dns&do=add...
action=dns&do=delete...

style calls, will also be passed to this script.

For example, when deleting a zone via the task.queue:

echo "action=dns&do=delete_zone&domain=domain.com" >> /usr/local/directadmin/data/task.queue

the custom hook taskq_dns_post.sh will be called, similar to other action=dns calls.

Environment variables

Depends on dataskq command.