dhcpcd-run-hooks
DHCP client configuration script
Name:
dhcpcd-run-hooks
Description:
The dhcpcd utility uses dhcpcd-run-hooks to run any system and user-defined hook scripts. System hook scripts are found in /usr/lib/dhcpcd/dhcpcd-hooks and the user-defined hooks are /etc/dhcpcd.enter-hook and /etc/dhcpcd.exit-hook. The default install supplies hook scripts for configuring /etc/resolv.conf and the hostname. To use additional scripts, copy them to /sbin/dhcpcd-run-hooks.
The hooks scripts are loaded into the current shell rather than executed in their own process. This behavior allows each hook script, such as /etc/dhcpcd.enter-hook, to customise environment variables or provide alternative functions to hooks further down the chain. Therefore, using shell builtins like exit or exec cause dhcpcd-run-hooks to exit at that point.
Each time dhcpcd-run-hooks is invoked, $interface is set to the interface that dhcpcd is run on, and $reason is set to the reason why dhcpcd-run-hooks was invoked. DHCP information to be configured is held in variables prefixed with new_, and old DHCP information to be removed is held in variables prefixed with old_. The dhcpcd utility can use -V or --variables argument to display the full list of variables it knows.
Here's a list of reasons why dhcp-run-hooks could be invoked:
- PREINIT
- The dhcpcd utility is starting up and any pre-initialization should be done.
- CARRIER
- The dhcpcd utility detected that the carrier is up. This is generally just a notification and no action needs to be taken.
- NOCARRIER
- Not supported by the io-sock networking stack.
- NOCARRIER_ROAMING
- The dhcpcd utility lost the carrier but the interface configuration persisted.The OS has to support wireless roaming or IP Persistence for this to happen.
- INFORM | INFORM6
- The dhcpcd utility informed a DHCP server about its address, and obtained other configuration details.
- BOUND | BOUND6
- The dhcpcd utility obtained a new lease from a DHCP server.
- RENEW | RENEW6
- The dhcpcd utility renewed its lease.
- REBIND | REBIND6
- The dhcpcd utility has rebound to a new DHCP server.
- REBOOT | REBOOT6
- The dhcpcd utility successfully requested a lease from a DHCP server.
- DELEGATED6
- The dhcpcd utility assigned a delegated prefix to the interface.
- IPV4LL
- The dhcpcd utility obtained an IPV4LL address, or one was removed.
- STATIC
- The dhcpcd utility has been configured with a static configuration which hasn't been obtained from a DHCP server.
- 3RDPARTY
- The dhcpcd utility is monitoring the interface for a third party to give it an IP address.
- TIMEOUT
- The dhcpcd utility failed to contact any DHCP servers but was able to use an old lease.
- EXPIRE | EXPIRE6
- The dhcpcd utility's lease or state expired and it failed to obtain a new one.
- NAK
- The dhcpcd utility received a NAK from the DHCP server. This should be treated as EXPIRE.
- RECONFIGURE
- The dhcpcd utility was instructed to reconfigure an interface.
- ROUTERADVERT
- The dhcpcd utility received an IPv6 Router Advertisement, or one has expired.
- STOP | STOP6
- The dhcpcd utility stopped running on the interface.
- STOPPED
- The dhcpcd utility stopped entirely.
- DEPARTED
- The interface was removed.
- FAIL
- The dhcpcd utility failed to operate on the interface. This normally happens when dhcpcd does not support the raw interface, which means it cannot work as a DHCP or ZeroConf client. Static configuration and DHCP INFORM is still allowed.
- TEST
- The dhcpcd utility received an OFFER from a DHCP server but does not configure the interface. This is primarily used to test if the variables are filled correctly for the script to process them.
Environment:
The dhcpcd utility clears the environment variables except for $PATH. The following variables are then set, along with any protocol-supplied ones:
- $interface
- The name of the interface.
- $protocol
- The protocol that triggered the event.
- $reason
- The reason dhcpcd-run-hooks was invoked.
- $pid
- The pid of dhcpcd.
- $ifcarrier
- The link status of $interface: unknown, up or down.
- $ifmetric
- The $interface preference (lower is better).
- $ifwireless
- 1 if $interface is wireless, otherwise 0.
- $ifflags
- $interface flags.
- $ifmtu
- The MTU (Maximum Transmission Unit) of $interface.
- $ifssid
- The name of the SSID the interface is connected to.
- $interface_order
- A list of interfaces (in order of preference).
- $if_up
- True if the interface is up, otherwise false. This is more than IFF_UP and may not be equal.
- $if_down
- True if the interface is down, otherwise false. This is more than IFF_UP and may not be equal.
- $af_waiting
- Address family waiting for, as defined in dhcpcd.conf.
- $profile
- The name of the profile selected from dhcpcd.conf.
- $new_delegated_dhcp6_prefix
- Space-separated list of delegated prefixes.
Files:
When dhcpcd-run-hooks runs, it loads /etc/dhcpcd.enter-hook and any scripts found in /sbin/dhcpcd-hooks in lexical order. It then loads /etc/dhcpcd.exit-hook.
Contributing author:
Roy Marples roy@marples.name
Security Considerations:
The dhcpcd utility validates the content of each option against its encoding. For string, ASCII, raw or binhex encoding, it's up to the user to validate it for the intended purpose.
When used in a shell script, each variable must be quoted correctly.