-6 --dhcp-script=<path>
Whenever a new DHCP lease is created, or an old one destroyed, or a TFTP file transfer completes, the executable specified by this option is run. <path> must be an absolute pathname, no PATH search occurs. The arguments to the process are "add", "old" or "del", the MAC address of the host (or DUID for IPv6) , the IP address, and the hostname, if known. "add" means a lease has been created, "del" means it has been destroyed, "old" is a notification of an existing lease when dnsmasq starts or a change to MAC address or hostname of an existing lease (also, lease length or expiry and client-id, if --leasefile-ro is set and lease expiry if --script-on-renewal is set). If the MAC address is from a network type other than ethernet, it will have the network type prepended, eg "06-01:23:45:67:89:ab" for token ring. The process is run as root (assuming that dnsmasq was originally run as root) even if dnsmasq is configured to change UID to an unprivileged user.

The environment is inherited from the invoker of dnsmasq, with some or all of the following variables added

For both IPv4 and IPv6:

DNSMASQ_DOMAIN if the fully-qualified domain name of the host is known, this is set to the domain part. (Note that the hostname passed to the script as an argument is never fully-qualified.)

If the client provides a hostname, DNSMASQ_SUPPLIED_HOSTNAME

If the client provides user-classes, DNSMASQ_USER_CLASS0..DNSMASQ_USER_CLASSn

If dnsmasq was compiled with HAVE_BROKEN_RTC, then the length of the lease (in seconds) is stored in DNSMASQ_LEASE_LENGTH, otherwise the time of lease expiry is stored in DNSMASQ_LEASE_EXPIRES. The number of seconds until lease expiry is always stored in DNSMASQ_TIME_REMAINING.

DNSMASQ_DATA_MISSING is set to "1" during "old" events for existing leases generated at startup to indicate that data not stored in the persistent lease database will not be present. This comprises everything other than IP address, hostname, MAC address, DUID, IAID and lease length or expiry time.

If a lease used to have a hostname, which is removed, an "old" event is generated with the new state of the lease, ie no name, and the former name is provided in the environment variable DNSMASQ_OLD_HOSTNAME.

DNSMASQ_INTERFACE stores the name of the interface on which the request arrived; this is not set for "old" actions when dnsmasq restarts.

DNSMASQ_RELAY_ADDRESS is set if the client used a DHCP relay to contact dnsmasq and the IP address of the relay is known.

DNSMASQ_TAGS contains all the tags set during the DHCP transaction, separated by spaces.

DNSMASQ_LOG_DHCP is set if --log-dhcp is in effect.

DNSMASQ_REQUESTED_OPTIONS a string containing the decimal values in the Parameter Request List option, comma separated, if the parameter request list option is provided by the client.

DNSMASQ_MUD_URL the Manufacturer Usage Description URL if provided by the client. (See RFC8520 for details.)

For IPv4 only:

DNSMASQ_CLIENT_ID if the host provided a client-id.

DNSMASQ_CIRCUIT_ID, DNSMASQ_SUBSCRIBER_ID, DNSMASQ_REMOTE_ID if a DHCP relay-agent added any of these options.
  If the client provides vendor-class, DNSMASQ_VENDOR_CLASS.

For IPv6 only:

If the client provides vendor-class, DNSMASQ_VENDOR_CLASS_ID, containing the IANA enterprise id for the class, and DNSMASQ_VENDOR_CLASS0..DNSMASQ_VENDOR_CLASSn for the data.

DNSMASQ_SERVER_DUID containing the DUID of the server: this is the same for every call to the script.

DNSMASQ_IAID containing the IAID for the lease. If the lease is a temporary allocation, this is prefixed to 'T'.

DNSMASQ_MAC containing the MAC address of the client, if known.

Note that the supplied hostname, vendorclass and userclass data is only supplied for "add" actions or "old" actions when a host resumes an existing lease, since these data are not held in dnsmasq's lease database.

All file descriptors are closed except stdin, which is open to /dev/null, and stdout and stderr which capture output for logging by dnsmasq. (In debug mode, stdio, stdout and stderr file are left as those inherited from the invoker of dnsmasq).

The script is not invoked concurrently: at most one instance of the script is ever running (dnsmasq waits for an instance of script to exit before running the next). Changes to the lease database are which require the script to be invoked are queued awaiting exit of a running instance. If this queueing allows multiple state changes occur to a single lease before the script can be run then earlier states are discarded and the current state of that lease is reflected when the script finally runs.

At dnsmasq startup, the script will be invoked for all existing leases as they are read from the lease file. Expired leases will be called with "del" and others with "old". When dnsmasq receives a HUP signal, the script will be invoked for existing leases with an "old" event.

There are five further actions which may appear as the first argument to the script, "init", "arp-add", "arp-del", "relay-snoop" and "tftp". More may be added in the future, so scripts should be written to ignore unknown actions. "init" is described below in --leasefile-ro

The "tftp" action is invoked when a TFTP file transfer completes: the arguments are the file size in bytes, the address to which the file was sent, and the complete pathname of the file.

The "relay-snoop" action is invoked when dnsmasq is configured as a DHCP relay for DHCPv6 and it relays a prefx delegation to a client. The arguments are the name of the interface where the client is connected, its (link-local) address on that interface and the delegated prefix. This information is sufficient to install routes to the delegated prefix of a router. See --dhcp-relay for more details on configuring DHCP relay.

The "arp-add" and "arp-del" actions are only called if enabled with --script-arp They are are supplied with a MAC address and IP address as arguments. "arp-add" indicates the arrival of a new entry in the ARP or neighbour table, and "arp-del" indicates the deletion of same.