Differential D22012 Diff 97323 contrib/dhcpcd/hooks/dhcpcd-run-hooks.8

Changeset View

Standalone View

View Options

contrib/dhcpcd/hooks/dhcpcd-run-hooks.8

This file was added.

.\"

.\" Redistribution and use in source and binary forms, with or without

.\" modification, are permitted provided that the following conditions

.\" are met:

.\" 1. Redistributions of source code must retain the above copyright

.\" notice, this list of conditions and the following disclaimer.

.\" 2. Redistributions in binary form must reproduce the above copyright

.\" notice, this list of conditions and the following disclaimer in the

.\" documentation and/or other materials provided with the distribution.

.\"

.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND

.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE

.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE

.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE

.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL

.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS

.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)

.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT

.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY

.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF

.\" SUCH DAMAGE.

.\"

.Dd December 27, 2020

.Dt DHCPCD-RUN-HOOKS 8

.Os

.Sh NAME

.Nm dhcpcd-run-hooks

.Nd DHCP client configuration script

.Sh DESCRIPTION

.Nm

is used by

.Xr dhcpcd 8

to run any system and user defined hook scripts.

System hook scripts are found in

.Pa /libexec/dhcpcd-hooks

and the user defined hooks are

.Pa /etc/dhcpcd.enter-hook .

and

.Pa /etc/dhcpcd.exit-hook .

The default install supplies hook scripts for configuring

.Pa /etc/resolv.conf

and the hostname.

Your distribution may have included other hook scripts to say configure

ntp or ypbind.

A test hook is also supplied that simply echos the dhcp variables to the

console from DISCOVER message.

.Pp

The hooks scripts are loaded into the current shell rather than executed

in their own process.

This allows each hook script, such as

.Pa /etc/dhcpcd.enter-hook

to customise environment variables or provide alternative functions to hooks

further down the chain.

As such, using the shell builtins

.Ic exit ,

.Ic exec

or similar will cause

.Nm

to exit at that point.

.Pp

Each time

.Nm

is invoked,

.Ev $interface

is set to the interface that

.Nm dhcpcd

is run on and

.Ev $reason

is to the reason why

pauamma_gundo.comUnsubmitted

Done

.Ev $reason

- is to the reason why

+ is set to the reason why

.Nm

was invoked.

pauamma_gundo.com:

.Nm

pauamma_gundo.comUnsubmitted

Done

Spurious line?

pauamma_gundo.com: Spurious line?

was invoked.

DHCP information to be configured is held in variables starting with the word

new_ and old DHCP information to be removed is held in variables starting with

the word old_.

.Nm dhcpcd

can display the full list of variables it knows how about by using the

.Fl V , -variables

pauamma_gundo.comUnsubmitted

Done

.Nm dhcpcd

- can display the full list of variables it knows how about by using the

+ can display the full list of variables it knows about by using the

.Fl V , -variables

pauamma_gundo.com:

argument.

.Pp

Here's a list of reasons why

.Nm

could be invoked:

.Bl -tag -width EXPIREXXXEXPIRE6

.It Dv PREINIT

dhcpcd is starting up and any pre-initialisation should be done.

.It Dv CARRIER

pauamma_gundo.comUnsubmitted

Done

.It Dv PREINIT

- dhcpcd is starting up and any pre-initialisation should be done.

+ dhcpcd is starting up and any pre-initialisation required should be performed now.

.It Dv CARRIER

Make clearer to non-native speakers it's "initialize now", not "initialization should already be complete".

pauamma_gundo.com: Make clearer to non-native speakers it's "initialize now", not "initialization should already…

dhcpcd has detected the carrier is up.

This is generally just a notification and no action need be taken.

.It Dv NOCARRIER

dhcpcd lost the carrier.

The cable may have been unplugged or association to the wireless point lost.

.It Dv NOCARRIER_ROAMING

dhcpcd lost the carrier but the interface configuration is persisted.

The OS has to support wireless roaming or IP Persistance for this to happen.

.It Dv INFORM | Dv INFORM6

dhcpcd informed a DHCP server about its address and obtained other

configuration details.

.It Dv BOUND | Dv BOUND6

dhcpcd obtained a new lease from a DHCP server.

.It Dv RENEW | Dv RENEW6

dhcpcd renewed it's lease.

.It Dv REBIND | Dv REBIND6

pauamma_gundo.comUnsubmitted

Done

.It Dv RENEW | Dv RENEW6

- dhcpcd renewed it's lease.

+ dhcpcd renewed its lease.

.It Dv REBIND | Dv REBIND6

pauamma_gundo.com:

dhcpcd has rebound to a new DHCP server.

.It Dv REBOOT | Dv REBOOT6

dhcpcd successfully requested a lease from a DHCP server.

.It Dv DELEGATED6

pauamma_gundo.comUnsubmitted

Not Done

Is "REBOOT" correct? I can't connect the dots between rebooting and getting a leased address for the first time.

pauamma_gundo.com: Is "REBOOT" correct? I can't connect the dots between rebooting and getting a leased address…

roy_marples.nameUnsubmitted

Not Done

REBOOT is when a previously aquired lease is acked by the server but not yet on the interface.
Such as when the host initially starts up or when the carrier goes down or comes back up again.

If there is no previouisly acquired lease, or it has expired then the BOUND event is raised instead.

Realistically there is no difference between the two and mainly exists as to be compatible with dhclient-script(8)

roy_marples.name: REBOOT is when a previously aquired lease is acked by the server but not yet on the interface.

dhcpcd assigned a delegated prefix to the interface.

.It Dv IPV4LL

dhcpcd obtained an IPV4LL address, or one was removed.

.It Dv STATIC

dhcpcd has been configured with a static configuration which has not been

obtained from a DHCP server.

.It Dv 3RDPARTY

dhcpcd is monitoring the interface for a 3rd party to give it an IP address.

.It Dv TIMEOUT

dhcpcd failed to contact any DHCP servers but was able to use an old lease.

.It Dv EXPIRE | EXPIRE6

dhcpcd's lease or state expired and it failed to obtain a new one.

.It Dv NAK

dhcpcd received a NAK from the DHCP server.

This should be treated as EXPIRE.

.It Dv RECONFIGURE

dhcpcd has been instructed to reconfigure an interface.

.It Dv ROUTERADVERT

dhcpcd has received an IPv6 Router Advertisement, or one has expired.

.It Dv STOP | Dv STOP6

dhcpcd stopped running on the interface.

.It Dv STOPPED

dhcpcd has stopped entirely.

.It Dv DEPARTED

The interface has been removed.

.It Dv FAIL

dhcpcd 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.

.It Dv TEST

dhcpcd received an OFFER from a DHCP server but will not configure the

interface.

This is primarily used to test the variables are filled correctly for the

script to process them.

.El

.Sh ENVIRONMENT

.Nm dhcpcd

will clear the environment variables aside from

pauamma_gundo.comUnsubmitted

Not Done

For consistency, either remove .Nm here or add it to all list items above.

pauamma_gundo.com: For consistency, either remove .Nm here or add it to all list items above.

.Ev $PATH .

The following variables will then be set, along with any protocol supplied

ones.

.Bl -tag -width xnew_delegated_dhcp6_prefix

.It Ev $interface

the name of the interface.

.It Ev $protocol

the protocol that triggered the event.

.It Ev $reason

as described above.

.It Ev $pid

the pid of

.Nm dhcpcd .

.It Ev $ifcarrier

the link status of

.Ev $interface :

.Dv unknown ,

.Dv up

.Dv down .

.It Ev $ifmetric

.Ev $interface

preference, lower is better.

.It Ev $ifwireless

.Dv 1 if

.Ev $interface

is wireless, otherwise

.Dv 0 .

.It Ev $ifflags

.Ev $interface

flags.

.It Ev $ifmtu

.Ev $interface

MTU.

.It Ev $ifssid

the name of the SSID the

.Ev interface

pauamma_gundo.comUnsubmitted

Done

.It Ev $ifssid

- the name of the SSID the

+ the SSID the

.Ev interface

A SSID *is* a name.

pauamma_gundo.com: A SSID *is* a name.

is connected to.

.It Ev $interface_order

A list of interfaces, in order of preference.

.It Ev $if_up

.Dv true

if the

.Ev interface

is up, otherwise

.Dv false .

This is more than IFF_UP and may not be equal.

.It Ev $if_down

pauamma_gundo.comUnsubmitted

Not Done

What does that mean?

pauamma_gundo.com: What does that mean?

roy_marples.nameUnsubmitted

Not Done

For example the link could be down or could be in some other transitive state.
I'm deliberately being vague because it's highly dependent on the interface state, what the OS supports and the state of various protocols running on it.

I think I'm trying to say that even if the interface is marked as up, dhcpcd might mark it as not up.

roy_marples.name: For example the link could be down or could be in some other transitive state. I'm deliberately…

.Dv true

if the

.Ev interface

is down, otherwise

.Dv false .

This is more than IFF_UP and may not be equal.

.It Ev $af_waiting

pauamma_gundo.comUnsubmitted

Not Done

Same question as above.

pauamma_gundo.com: Same question as above.

roy_marples.nameUnsubmitted

Not Done

Same answer as above, but note that if_down is seperate from if_up - it's not possible both would be true, but it is possible for both to be false.

roy_marples.name: Same answer as above, but note that if_down is seperate from if_up - it's not possible both…

Address family waiting for, as defined in

.Xr dhcpcd.conf 5 .

.It Ev $profile

the name of the profile selected from

.Xr dhcpcd.conf 5 .

.It Ev $new_delegated_dhcp6_prefix

space separated list of delegated prefixes.

.El

pauamma_gundo.comUnsubmitted

Done

.It Ev $new_delegated_dhcp6_prefix

- space separated list of delegated prefixes.

+ space-separated list of delegated prefixes.

.El

.Sh FILES

pauamma_gundo.com:

.Sh FILES

When

.Nm

runs, it loads

.Pa /etc/dhcpcd.enter-hook

and any scripts found in

.Pa /libexec/dhcpcd-hooks

in a lexical order and then finally

.Pa /etc/dhcpcd.exit-hook

.Sh SEE ALSO

pauamma_gundo.comUnsubmitted

Done

runs, it loads

- .Pa /etc/dhcpcd.enter-hook

- and any scripts found in

+ .Pa /etc/dhcpcd.enter-hook ,

+ any scripts found in

.Pa /libexec/dhcpcd-hooks

- in a lexical order and then finally

- .Pa /etc/dhcpcd.exit-hook

+ in lexical order, then finally

+ .Pa /etc/dhcpcd.exit-hook .

.Sh SEE ALSO

Commafy list to make it clearer that "lexical order" applies to /libexec/dhcpcd-hooks/* only.

pauamma_gundo.com: Commafy list to make it clearer that "lexical order" applies to /libexec/dhcpcd-hooks/* only.

.Xr dhcpcd 8

.Sh AUTHORS

.An Roy Marples Aq Mt roy@marples.name

.Sh BUGS

Please report them to

.Lk http://roy.marples.name/projects/dhcpcd

.Sh SECURITY CONSIDERATIONS

pauamma_gundo.comUnsubmitted

Done

Please report them to

- .Lk http://roy.marples.name/projects/dhcpcd

+ .Lk https://roy.marples.name/projects/dhcpcd

.Sh SECURITY CONSIDERATIONS

Since the https version works.

pauamma_gundo.com: Since the https version works.

.Nm dhcpcd

will validate 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.

.Pp

When used in a shell script, each variable must be quoted correctly.