Document entry and exit hooks, plus make_resolv_conf function.

diff --git a/client/dhclient-script.8 b/client/dhclient-script.8
index fd4533d98ebf2b15f32597d8d0d8c0a8cd4d33c9..940aaa16a79885e2a1ba4db235edbb7b3437b348 100644 (file)
--- a/client/dhclient-script.8
+++ b/client/dhclient-script.8
@@ -15,7 +15,7 @@
 .\"
 .\" Support and other services are available for ISC products - see
 .\" http://www.isc.org for more information.
-.TH dhclient 8
+.TH dhclient-script 8
 .SH NAME
 dhclient-script - DHCP client network configuration script
 .SH DESCRIPTION
@@ -27,15 +27,49 @@ interface's final configuration once a lease has been acquired.  If no
 lease is acquired, the script is used to test predefined leases, if
 any, and also called once if no valid lease can be identified.
 .PP
-This script is not meant to be customized by the end user.  However,
-the script may not work on particular versions of particular operating
-systems (indeed, no standard script exists for some operating
-systems), so a pioneering user may well need to create a new script or
-modify an existing one.  In general, customizations specific to a
-particular computer should be done in the
+This script is not meant to be customized by the end user.  If local
+customizations are needed, they should be possible using the enter and
+exit hooks provided (see HOOKS for details).   These hooks will allow the
+user to override the default behaviour of the client in creating a
+.B /etc/resolv.conf
+file.
+.PP
+No standard client script exists for some operating systems, even though
+the actual client may work, so a pioneering user may well need to create
+a new script or modify an existing one.  In general, customizations specific
+to a particular computer should be done in the
+.B ETCDIR/dhclient.conf
+file.   If you find that you can't make such a customization without
+customizing
 .B ETCDIR/dhclient.conf
-script.   If you find that you can't make such a customization without
-customizing dhclient.conf, please submit a bug report.
+or using the enter and exit hooks, please submit a bug report.
+.SH HOOKS
+When it starts, the client script first defines a shell function,
+.B make_resolv_conf ,
+which is later used to create the
+.B /etc/resolv.conf
+file.   To override the default behaviour, redefine this function in
+the enter hook script.
+.PP
+On after defining the make_resolv_conf function, the client script checks
+for the presence of an executable
+.B ETCDIR/dhclient-enter-hooks
+script, and if present, it invokes the script inline, using the Bourne
+shell '.' command.   The entire environment documented under OPERATION
+is available to this script, which may modify the environment if needed
+to change the behaviour of the script.   If an error occurs during the
+execution of the script, it can set the exit_status variable to a nonzero
+value, and
+.B ETCDIR/dhclient-script
+will exit with that error code immediately after the client script exits.
+.PP
+After all processing has completed,
+.B ETCDIR/dhclient-script
+checks for the presence of an executable
+.B ETCDIR/dhclient-exit-hooks
+script, which if present is invoked using the '.' command.   The exit status
+is passed in the exit_status shell variable, and will always be zero if the
+script succeeded at the task for which it was invoked.
 .SH OPERATION
 When dhclient needs to invoke the client configuration script, it
 writes a shell script into /tmp which defines a variety of variables.