dhcpcd-run-hooks

QNX SDP8.0Utilities ReferenceUtilities

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.

Page updated: