diff --git a/.cvsignore b/.cvsignore index d5917f3..38577ea 100644 --- a/.cvsignore +++ b/.cvsignore @@ -1 +1 @@ -dhcp-4.0.0.tar.gz +dhcp-3.1.0.tar.gz diff --git a/Makefile.libdhcp4client b/Makefile.libdhcp4client new file mode 100644 index 0000000..624d746 --- /dev/null +++ b/Makefile.libdhcp4client @@ -0,0 +1,150 @@ +# +# Makefile.dist for libdhcp4client +# +# We get the libdhcp4client library from the patched ISC source code. We +# rebuild key C files with -DLIBDHCP to turn on the library features we +# need. Normal build results in standard ISC code (i.e., not LIBDHCP +# stuff enabled). We then link together a static library and a shared +# library with the new resulting objects. +# +# Copyright (C) 2006, 2007 Red Hat, Inc. All rights reserved. +# +# This copyrighted material is made available to anyone wishing to use, +# modify, copy, or redistribute it subject to the terms and conditions of +# the GNU General Public License v.2, or (at your option) any later version. +# This program is distributed in the hope that it will be useful, but WITHOUT +# ANY WARRANTY expressed or implied, including the implied warranties of +# MERCHANTABILITY or FITNESS FOR A * PARTICULAR PURPOSE. See the GNU General +# Public License for more details. You should have received a copy of the +# GNU General Public License along with this program; if not, write to the +# Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA +# 02110-1301, USA. Any Red Hat trademarks that are incorporated in the +# source code or documentation are not subject to the GNU General Public +# License and may only be used or replicated with the express permission of +# Red Hat, Inc. +# +# Red Hat Author(s): Jason Vas Dias +# David Cantrell +# + +# What version of ISC DHCP is this? +VER = $(shell grep DHCP_VERSION ../../includes/version.h | head -1 | cut -d '"' -f 2 | cut -d 'V' -f 2 | cut -d '-' -f 1) + +PROGS = libdhcp4client.a libdhcp4client-$(VER).so.0 + +# NOTE: The ordering of these file lists is important! We are using the +# whole program optimization features of gcc, so the order matters here. + +# Source files shared by all objects +COMMON_SRCS = client_clparse.c client_dhclient.c common_alloc.c common_bpf.c \ + common_comapi.c common_conflex.c common_discover.c \ + common_dispatch.c common_dns.c common_ethernet.c \ + common_execute.c common_inet.c common_lpf.c common_memory.c \ + common_options.c common_packet.c common_parse.c common_print.c \ + common_socket.c common_tables.c common_tr.c common_tree.c \ + dst_dst_api.c dst_base64.c dst_hmac_link.c dst_md5_dgst.c \ + omapip_alloc.c omapip_array.c omapip_auth.c omapip_buffer.c \ + omapip_connection.c omapip_convert.c omapip_dispatch.c \ + omapip_errwarn.c omapip_handle.c omapip_hash.c \ + omapip_listener.c omapip_mrtrace.c omapip_result.c \ + omapip_support.c omapip_toisc.c omapip_trace.c + +# Source files for libdhcp4client.o +CLIENT_SRCS = common_ctrace.c common_dlpi.c common_nit.c common_upf.c \ + dst_dst_support.c dst_prandom.c omapip_generic.c \ + omapip_message.c omapip_protocol.c + +# Source files for libres.o (minires) +MINIRES_SRCS = minires_ns_date.c minires_ns_name.c minires_ns_parse.c \ + minires_ns_samedomain.c minires_ns_sign.c minires_ns_verify.c \ + minires_res_comp.c minires_res_findzonecut.c \ + minires_res_init.c minires_res_mkquery.c \ + minires_res_mkupdate.c minires_res_query.c minires_res_send.c \ + minires_res_sendsigned.c minires_res_update.c + +# ISC dhcp headers we need to copy to /usr/include/dhcp4client +DHCP_HEADERS = dhcpd.h cdefs.h osdep.h arpa/nameser.h minires/minires.h \ + site.h cf/linux.h dhcp.h statement.h tree.h inet.h dhctoken.h \ + omapip/omapip_p.h failover.h ctrace.h minires/resolv.h \ + minires/res_update.h omapip/convert.h omapip/hash.h \ + omapip/trace.h + +HDRS = dhcp4client.h +SRCS = $(COMMON_SRCS) $(CLIENT_SRCS) +OBJS = $(SRCS:.c=.o) + +INCLUDES = -I$(TOP) -I$(TOP)/includes -I$(TOP)/dst -I. +CFLAGS = $(DEBUG) $(PREDEFINES) $(INCLUDES) $(COPTS) \ + -DCLIENT_PATH=${CLIENT_PATH} -DLIBDHCP -DUSE_MD5 + +all: $(PROGS) + +install: all + install -p -m 0755 -D libdhcp4client-$(VER).so.0 $(DESTDIR)$(LIBDIR)/libdhcp4client-$(VER).so.0 + ln -sf libdhcp4client-$(VER).so.0 $(DESTDIR)/$(LIBDIR)/libdhcp4client.so + install -p -m 0644 -D libdhcp4client.a $(DESTDIR)$(LIBDIR)/libdhcp4client.a + install -p -m 0644 -D dhcp4client.h $(DESTDIR)$(INCDIR)/dhcp4client/dhcp4client.h + for hdr in $(DHCP_HEADERS) ; do \ + install -p -m 0644 -D $(TOP)/includes/$${hdr} $(DESTDIR)$(INCDIR)/dhcp4client/$${hdr} ; \ + done + +depend: + $(MKDEP) $(INCLUDES) $(PREDEFINES) $(SRCS) + +clean: + -rm -f $(OBJS) + +realclean: clean + -rm -f $(PROG) *~ #* + +distclean: realclean + -rm -f Makefile + +# This isn't the cleanest way to set up links, but I prefer this so I don't +# need object targets for each subdirectory. The idea is simple. Since +# libdhcp4client is a linked together wad of objects from across the source +# tree, we change / to _ when linking source files here. Follow this example: +# +# We need to use client/dhclient.c, so we make this link: +# rm -f client_dhclient.c +# ln -s $(TOP)/client/dhclient.c client_dhclient.c +# +# Simple. Given the way the ISC build system works, this is the easiest to +# maintain and least invasive. +# +# David Cantrell +links: + @for target in $(SRCS); do \ + source="`echo $$target | sed -e 's|_|/|'`"; \ + if [ ! -b $$target ]; then \ + rm -f $$target; \ + fi; \ + ln -s $(TOP)/$$source $$target; \ + done; \ + for hdr in $(HDRS); do \ + if [ ! -b $$hdr ]; then \ + rm -f $$hdr; \ + fi; \ + ln -s $(TOP)/libdhcp4client/$$hdr $$hdr; \ + done + +# minires is difficult to build because it overrides things in common and dst, +# so we just link with the already built libres.a since we need it all anyway +libres.a: + if [ ! -f ../minires/$@ ]; then \ + $(MAKE) -C ../minires; \ + fi; \ + ln ../minires/libres.a .; \ + $(AR) x libres.a + +# Create the libraries +# minires/res_query.o contains an undefined symbol __h_errno_set, is not +# used by any dhcp code, and is optimized out by the linker when producing +# the dhclient executable or a shared library +libdhcp4client.a: $(OBJS) libres.a + $(AR) crus $@ $(OBJS) `$(AR) t libres.a | grep -v res_query.o` + +libdhcp4client-$(VER).so.0: $(OBJS) libres.a + $(CC) -shared -o $@ -Wl,-soname,$@ $(OBJS) `$(AR) t libres.a | grep -v res_query.o` + +# Dependencies (semi-automatically-generated) diff --git a/README.ldap b/README.ldap new file mode 100644 index 0000000..2263050 --- /dev/null +++ b/README.ldap @@ -0,0 +1,192 @@ +LDAP Support in DHCP +Brian Masney +Last updated 3/23/2003 + +This document describes setting up the DHCP server to read it's configuration +from LDAP. This work is based on the IETF document +draft-ietf-dhc-ldap-schema-01.txt included in the doc directory. For the +latest version of this document, please see http://home.ntelos.net/~masneyb. + +First question on most people's mind is "Why do I want to store my +configuration in LDAP?" If you run a small DHCP server, and the configuration +on it rarely changes, then you won't need to store your configuration in LDAP. +But, if you have several DHCP servers, and you want an easy way to manage your +configuration, this can be a solution. + +The first step will be to setup your LDAP server. I am using OpenLDAP from +www.openldap.org. Building and installing OpenLDAP is beyond the scope of +this document. There is plenty of documentation out there about this. Once +you have OpenLDAP installed, you will have to edit your slapd.conf file. I +added the following 2 lines to my configuration file: + +include /etc/ldap/schema/dhcp.schema +index dhcpHWAddress eq +index dhcpClassData eq + +The first line tells it to include the dhcp schema file. You will find this +file under the contrib directory in this distribution. You will need to copy +this file to where your other schema files are (maybe +/usr/local/openldap/etc/openldap/schema/). The second line sets up an index +for the dhcpHWAddress parameter. The third parameter is for reading subclasses +from LDAP every time a DHCP request comes in. Make sure you run the slapindex +command and restart slapd to have these changes to into effect. + +Now that you have LDAP setup, you should be able to use gq +(http://biot.com/gq/) to verify that the dhcp schema file is loaded into LDAP. +Pull up gq, and click on the Schema tab. Go under objectClasses, and you +should see at least the following object classes listed: dhcpClass, dhcpGroup, +dhcpHost, dhcpOptions, dhcpPool, dhcpServer, dhcpService, dhcpSharedNetwork, +dhcpSubClass, and dhcpSubnet. If you do not see these, you need to check over +your LDAP configuration before you go any further. + +You should now be ready to build DHCP. If you would like to enable LDAP over +SSL, you will need to perform the following steps: + + * Edit the includes/site.h file and uncomment the USE_SSL line + or specify "-DUSE_SSL" via CFLAGS. + * Edit the dst/Makefile.dist file and remove md5_dgst.c and md5_dgst.o + from the SRC= and OBJ= lines (around line 24) + * Now run configure in the base source directory. If you chose to enable + LDAP over SSL, you must append -lcrypto -lssl to the LIBS= line in the + file work.os/server/Makefile (replace os with your operating system, + linux-2.2 on my machine). You should now be able to type make to build + your DHCP server. + +If you choose to not enable LDAP over SSL, then you only need to run configure +and make in the toplevel source directory. + +Once you have DHCP installed, you will need to setup your initial plaintext +config file. In my /etc/dhcpd.conf file, I have: + +ldap-server "localhost"; +ldap-port 389; +ldap-username "cn=DHCP User, dc=ntelos, dc=net"; +ldap-password "blah"; +ldap-base-dn "dc=ntelos, dc=net"; +ldap-method dynamic; +ldap-debug-file "/var/log/dhcp-ldap-startup.log"; + +If SSL has been enabled at compile time using the USE_SSL flag, the dhcp +server trys to use TLS if possible, but continues without TLS if not. + +You can modify this behaviour using following option in /etc/dhcpd.conf: + +ldap-ssl + off: disables TLS/LDAPS. + ldaps: enables LDAPS -- don't forget to set ldap-port to 636. + start_tls: enables TLS using START_TLS command + on: enables LDAPS if ldap-port is set to 636 or TLS in + other cases. + +See also "man 5 ldap.conf" for description the following TLS related +options: + ldap-tls-reqcert, ldap-tls-ca-file, ldap-tls-ca-dir, ldap-tls-cert + ldap-tls-key, ldap-tls-crlcheck, ldap-tls-ciphers, ldap-tls-randfile + +All of these parameters should be self explanatory except for the ldap-method. +You can set this to static or dynamic. If you set it to static, the +configuration is read once on startup, and LDAP isn't used anymore. But, if +you set this to dynamic, the configuration is read once on startup, and the +hosts that are stored in LDAP are looked up every time a DHCP request comes +in. + +When the optional statement ldap-debug-file is specified, on startup the DHCP +server will write out the configuration that it generated from LDAP. If you +are getting errors about your LDAP configuration, this is a good place to +start looking. + +The next step is to set up your LDAP tree. Here is an example config that will +give a 10.100.0.x address to machines that have a host entry in LDAP. +Otherwise, it will give a 10.200.0.x address to them. (NOTE: replace +dc=ntelos, dc=net with your base dn). If you would like to convert your +existing dhcpd.conf file to LDIF format, there is a script +contrib/dhcpd-conf-to-ldap.pl that will convert it for you. Type +dhcpd-conf-to-ldap.pl --help to see the usage information for this script. + +# You must specify the server's host name in LDAP that you are going to run +# DHCP on and point it to which config tree you want to use. Whenever DHCP +# first starts up, it will do a search for this entry to find out which +# config to use +dn: cn=brian.ntelos.net, dc=ntelos, dc=net +objectClass: top +objectClass: dhcpServer +cn: brian.ntelos.net +dhcpServiceDN: cn=DHCP Service Config, dc=ntelos, dc=net + +# Here is the config tree that brian.ntelos.net points to. +dn: cn=DHCP Service Config, dc=ntelos, dc=net +cn: DHCP Service Config +objectClass: top +objectClass: dhcpService +dhcpPrimaryDN: dc=ntelos, dc=net +dhcpStatements: ddns-update-style none +dhcpStatements: default-lease-time 600 +dhcpStatements: max-lease-time 7200 + +# Set up a shared network segment +dn: cn=WV Test, cn=DHCP Service Config, dc=ntelos, dc=net +cn: WV +objectClass: top +objectClass: dhcpSharedNetwork + +# Set up a subnet declaration with a pool statement. Also note that we have +# a dhcpOptions object with this entry +dn: cn=10.100.0.0, cn=WV Test, cn=DHCP Service Config, dc=ntelos, dc=net +cn: 10.100.0.0 +objectClass: top +objectClass: dhcpSubnet +objectClass: dhcpOptions +dhcpOption: domain-name-servers 10.100.0.2 +dhcpOption: routers 10.100.0.1 +dhcpOption: subnet-mask 255.255.255.0 +dhcpOption: broadcast-address 10.100.0.255 +dhcpNetMask: 24 + +# Set up a pool for this subnet. Only known hosts will get these IPs +dn: cn=Known Pool, cn=10.100.0.0, cn=WV Test, cn=DHCP Service Config, dc=ntelos, dc=net +cn: Known Pool +objectClass: top +objectClass: dhcpPool +dhcpRange: 10.100.0.3 10.100.0.254 +dhcpPermitList: deny unknown-clients + +# Set up another subnet declaration with a pool statement +dn: cn=10.200.0.0, cn=WV Test, cn=DHCP Service Config, dc=ntelos, dc=net +cn: 10.200.0.0 +objectClass: top +objectClass: dhcpSubnet +objectClass: dhcpOptions +dhcpOption: domain-name-servers 10.200.0.2 +dhcpOption: routers 10.200.0.1 +dhcpOption: subnet-mask 255.255.255.0 +dhcpOption: broadcast-address 10.200.0.255 +dhcpNetMask: 24 + +# Set up a pool for this subnet. Only unknown hosts will get these IPs +dn: cn=Known Pool, cn=10.200.0.0, cn=WV Test, cn=DHCP Service Config, dc=ntelos, dc=net +cn: Known Pool +objectClass: top +objectClass: dhcpPool +dhcpRange: 10.200.0.3 10.200.0.254 +dhcpPermitList: deny known clients + +# Set aside a group for all of our known MAC addresses +dn: cn=Customers, cn=DHCP Service Config, dc=ntelos, dc=net +objectClass: top +objectClass: dhcpGroup +cn: Customers + +# Host entry for my laptop +dn: cn=brianlaptop, cn=Customers, cn=DHCP Service Config, dc=ntelos, dc=net +objectClass: top +objectClass: dhcpHost +cn: brianlaptop +dhcpHWAddress: ethernet 00:00:00:00:00:00 + +You can use the command slapadd to load all of these entries into your LDAP +server. After you load this, you should be able to start up DHCP. If you run +into problems reading the configuration, try running dhcpd with the -d flag. +If you still have problems, edit the site.conf file in the DHCP source and +add the line: COPTS= -DDEBUG_LDAP and recompile DHCP. (make sure you run make +clean and rerun configure before you rebuild). + diff --git a/dhclient-script.8 b/dhclient-script.8 new file mode 100644 index 0000000..727f258 --- /dev/null +++ b/dhclient-script.8 @@ -0,0 +1,255 @@ +.\" dhclient-script.8 +.\" +.\" Copyright (c) 2004-2005 by Internet Systems Consortium, Inc. ("ISC") +.\" Copyright (c) 1996-2003 by Internet Software Consortium +.\" +.\" Permission to use, copy, modify, and distribute this software for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES +.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR +.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN +.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT +.\" OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.\" Internet Systems Consortium, Inc. +.\" 950 Charter Street +.\" Redwood City, CA 94063 +.\" +.\" http://www.isc.org/ +.\" +.\" This software has been written for Internet Systems Consortium +.\" by Ted Lemon in cooperation with Vixie Enterprises and Nominum, Inc. +.\" To learn more about Internet Systems Consortium, see +.\" ``http://www.isc.org/''. To learn more about Vixie Enterprises, +.\" see ``http://www.vix.com''. To learn more about Nominum, Inc., see +.\" ``http://www.nominum.com''. +.\" +.\" $Id: dhclient-script.8,v 1.1 2007/11/12 23:16:08 dcantrel Exp $ +.\" +.TH dhclient-script 8 +.SH NAME +dhclient-script - DHCP client network configuration script +.SH DESCRIPTION +The DHCP client network configuration script is invoked from time to +time by \fBdhclient(8)\fR. This script is used by the dhcp client to +set each interface's initial configuration prior to requesting an +address, to test the address once it has been offered, and to set the +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. 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, and to handle DHCP options not handled by default. +.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 +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 CLIENTBINDIR/dhclient-script +will exit with that error code immediately after the client script exits. +.PP +After all processing has completed, +.B CLIENTBINDIR/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 of dhclient-script will be passed to dhclient-exit-hooks in the +exit_status shell variable, and will always be zero if the script +succeeded at the task for which it was invoked. The rest of the +environment as described previously for dhclient-enter-hooks is also +present. The +.B ETCDIR/dhclient-exit-hooks +script can modify the valid of exit_status to change the exit status +of dhclient-script. +.PP +Immediately after dhclient brings an interface UP with a new IP address, +subnet mask, and routes, in the REBOOT/BOUND states, it will check for the +existence of an executable +.B ETCDIR/dhclient-up-hooks +script, and source it if found. This script can handle DHCP options in +the environment that are not handled by default. A per-interface. +.B ETCDIR/dhclient-${IF}-up-hooks +script will override the generic script and be sourced when interface +$IF has been brought up. +.PP +Immediately before dhclient brings an interface DOWN, removing its IP +address, subnet mask, and routes, in the STOP/RELEASE states, it will +check for the existence of an executable +.B ETCDIR/dhclient-down-hooks +script, and source it if found. This script can handle DHCP options in +the environment that are not handled by default. A per-interface +.B ETCDIR/dhclient-${IF}-down-hooks +script will override the generic script and be sourced when interface +$IF is about to be brought down. + +.SH OPERATION +When dhclient needs to invoke the client configuration script, it +defines a set of variables in the environment, and then invokes +.B CLIENTBINDIR/dhclient-script. +In all cases, $reason is set to the name of the reason why the script +has been invoked. The following reasons are currently defined: +MEDIUM, PREINIT, BOUND, RENEW, REBIND, REBOOT, EXPIRE, FAIL, STOP, RELEASE, +NBI and TIMEOUT. +.PP +.SH MEDIUM +The DHCP client is requesting that an interface's media type +be set. The interface name is passed in $interface, and the media +type is passed in $medium. +.SH PREINIT +The DHCP client is requesting that an interface be configured as +required in order to send packets prior to receiving an actual +address. For clients which use the BSD socket library, this means +configuring the interface with an IP address of 0.0.0.0 and a +broadcast address of 255.255.255.255. For other clients, it may be +possible to simply configure the interface up without actually giving +it an IP address at all. The interface name is passed in $interface, +and the media type in $medium. +.PP +If an IP alias has been declared in dhclient.conf, its address will be +passed in $alias_ip_address, and that ip alias should be deleted from +the interface, along with any routes to it. +.SH BOUND +The DHCP client has done an initial binding to a new address. The +new ip address is passed in $new_ip_address, and the interface name is +passed in $interface. The media type is passed in $medium. Any +options acquired from the server are passed using the option name +described in \fBdhcp-options\fR, except that dashes ('-') are replaced +by underscores ('_') in order to make valid shell variables, and the +variable names start with new_. So for example, the new subnet mask +would be passed in $new_subnet_mask. +.PP +Before actually configuring the address, dhclient-script should +somehow ARP for it and exit with a nonzero status if it receives a +reply. In this case, the client will send a DHCPDECLINE message to +the server and acquire a different address. This may also be done in +the RENEW, REBIND, or REBOOT states, but is not required, and indeed +may not be desirable. +.PP +When a binding has been completed, a lot of network parameters are +likely to need to be set up. A new /etc/resolv.conf needs to be +created, using the values of $new_domain_name and +$new_domain_name_servers (which may list more than one server, +separated by spaces). A default route should be set using +$new_routers, and static routes may need to be set up using +$new_static_routes. +.PP +If an IP alias has been declared, it must be set up here. The alias +IP address will be written as $alias_ip_address, and other DHCP +options that are set for the alias (e.g., subnet mask) will be passed +in variables named as described previously except starting with +$alias_ instead of $new_. Care should be taken that the alias IP +address not be used if it is identical to the bound IP address +($new_ip_address), since the other alias parameters may be incorrect +in this case. +.SH RENEW +When a binding has been renewed, the script is called as in BOUND, +except that in addition to all the variables starting with $new_, +there is another set of variables starting with $old_. Persistent +settings that may have changed need to be deleted - for example, if a +local route to the bound address is being configured, the old local +route should be deleted. If the default route has changed, the old default +route should be deleted. If the static routes have changed, the old +ones should be deleted. Otherwise, processing can be done as with +BOUND. +.SH REBIND +The DHCP client has rebound to a new DHCP server. This can be handled +as with RENEW, except that if the IP address has changed, the ARP +table should be cleared. +.SH REBOOT +The DHCP client has successfully reacquired its old address after a +reboot. This can be processed as with BOUND. +.SH EXPIRE +The DHCP client has failed to renew its lease or acquire a new one, +and the lease has expired. The IP address must be relinquished, and +all related parameters should be deleted, as in RENEW and REBIND. +.SH FAIL +The DHCP client has been unable to contact any DHCP servers, and any +leases that have been tested have not proved to be valid. The +parameters from the last lease tested should be deconfigured. This +can be handled in the same way as EXPIRE. +.SH STOP +The dhclient has been informed to shut down gracefully, the +dhclient-script should unconfigure or shutdown the interface as +appropriate. +.SH RELEASE +The dhclient has been executed using the -r flag, indicating that the +administrator wishes it to release its lease(s). dhclient-script should +unconfigure or shutdown the interface. +.SH NBI +No-Broadcast-Interfaces...dhclient was unable to find any interfaces +upon which it believed it should commence DHCP. What dhclient-script +should do in this situation is entirely up to the implementor. +.SH TIMEOUT +The DHCP client has been unable to contact any DHCP servers. +However, an old lease has been identified, and its parameters have +been passed in as with BOUND. The client configuration script should +test these parameters and, if it has reason to believe they are valid, +should exit with a value of zero. If not, it should exit with a +nonzero value. +.PP +The usual way to test a lease is to set up the network as with REBIND +(since this may be called to test more than one lease) and then ping +the first router defined in $routers. If a response is received, the +lease must be valid for the network to which the interface is +currently connected. It would be more complete to try to ping all of +the routers listed in $new_routers, as well as those listed in +$new_static_routes, but current scripts do not do this. +.SH FILES +Each operating system should generally have its own script file, +although the script files for similar operating systems may be similar +or even identical. The script files included in Internet +Systems Consortium DHCP distribution appear in the distribution tree +under client/scripts, and bear the names of the operating systems on +which they are intended to work. +.SH BUGS +If more than one interface is being used, there's no obvious way to +avoid clashes between server-supplied configuration parameters - for +example, the stock dhclient-script rewrites /etc/resolv.conf. If +more than one interface is being configured, /etc/resolv.conf will be +repeatedly initialized to the values provided by one server, and then +the other. Assuming the information provided by both servers is +valid, this shouldn't cause any real problems, but it could be +confusing. +.SH SEE ALSO +dhclient(8), dhcpd(8), dhcrelay(8), dhclient.conf(5) and +dhclient.leases(5). +.SH AUTHOR +.B dhclient-script(8) +has been written for Internet Systems Consortium +by Ted Lemon in cooperation with Vixie +Enterprises. To learn more about Internet Systems Consortium, +see +.B http://www.isc.org. +To learn more about Vixie +Enterprises, see +.B http://www.vix.com. diff --git a/dhclient.8 b/dhclient.8 new file mode 100644 index 0000000..4bba06b --- /dev/null +++ b/dhclient.8 @@ -0,0 +1,428 @@ +.\" dhclient.8 +.\" +.\" Copyright (c) 2004,2007 by Internet Systems Consortium, Inc. ("ISC") +.\" Copyright (c) 1996-2003 by Internet Software Consortium +.\" +.\" Permission to use, copy, modify, and distribute this software for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES +.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR +.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN +.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT +.\" OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.\" Internet Systems Consortium, Inc. +.\" 950 Charter Street +.\" Redwood City, CA 94063 +.\" +.\" http://www.isc.org/ +.\" +.\" Support and other services are available for ISC products - see +.\" http://www.isc.org for more information. +.\" +.\" $Id: dhclient.8,v 1.1 2007/11/12 23:16:08 dcantrel Exp $ +.\" +.TH dhclient 8 +.SH NAME +dhclient - Dynamic Host Configuration Protocol Client +.SH SYNOPSIS +.B dhclient +[ +.B -p +.I port +] +[ +.B -d +] +[ +.B -e +.I VAR=value +] +[ +.B -q +] +[ +.B -1 +] +[ +.B -r +] +[ +.B -x +] +[ +.B -lf +.I lease-file +] +[ +.B -pf +.I pid-file +] +[ +.B -cf +.I config-file +] +[ +.B -sf +.I script-file +] +[ +.B -s +server +] +[ +.B -g +relay +] +[ +.B -n +] +[ +.B -nw +] +[ +.B -w +] +[ +.B -B +] +[ +.B -I +.I dhcp-client-identifier +] +[ +.B -H +.I host-name +.R | +.B -F fqdn.fqdn +] +[ +.B -V +.I vendor-class-identifier +] +[ +.B -R +.I request option list +] +[ +.B -T +.I timeout +] +[ +.I if0 +[ +.I ...ifN +] +] +.SH DESCRIPTION +The Internet Systems Consortium DHCP Client, dhclient, provides a +means for configuring one or more network interfaces using the Dynamic +Host Configuration Protocol, BOOTP protocol, or if these protocols +fail, by statically assigning an address. +.SH OPERATION +.PP +The DHCP protocol allows a host to contact a central server which +maintains a list of IP addresses which may be assigned on one or more +subnets. A DHCP client may request an address from this pool, and +then use it on a temporary basis for communication on network. The +DHCP protocol also provides a mechanism whereby a client can learn +important details about the network to which it is attached, such as +the location of a default router, the location of a name server, and +so on. +.PP +On startup, dhclient reads the +.IR dhclient.conf +for configuration instructions. It then gets a list of all the +network interfaces that are configured in the current system. For +each interface, it attempts to configure the interface using the DHCP +protocol. +.PP +In order to keep track of leases across system reboots and server +restarts, dhclient keeps a list of leases it has been assigned in the +dhclient.leases(5) file. On startup, after reading the dhclient.conf +file, dhclient reads the dhclient.leases file to refresh its memory +about what leases it has been assigned. +.PP +When a new lease is acquired, it is appended to the end of the +dhclient.leases file. In order to prevent the file from becoming +arbitrarily large, from time to time dhclient creates a new +dhclient.leases file from its in-core lease database. The old version +of the dhclient.leases file is retained under the name +.IR dhclient.leases~ +until the next time dhclient rewrites the database. +.PP +Old leases are kept around in case the DHCP server is unavailable when +dhclient is first invoked (generally during the initial system boot +process). In that event, old leases from the dhclient.leases file +which have not yet expired are tested, and if they are determined to +be valid, they are used until either they expire or the DHCP server +becomes available. +.PP +A mobile host which may sometimes need to access a network on which no +DHCP server exists may be preloaded with a lease for a fixed +address on that network. When all attempts to contact a DHCP server +have failed, dhclient will try to validate the static lease, and if it +succeeds, will use that lease until it is restarted. +.PP +A mobile host may also travel to some networks on which DHCP is not +available but BOOTP is. In that case, it may be advantageous to +arrange with the network administrator for an entry on the BOOTP +database, so that the host can boot quickly on that network rather +than cycling through the list of old leases. +.PP +The names of the network interfaces that dhclient should attempt to +configure may be specified on the command line. If no interface names +are specified on the command line dhclient will normally identify all +network interfaces, eliminating non-broadcast interfaces if +possible, and attempt to configure each interface. +.PP +It is also possible to specify interfaces by name in the +.B dhclient.conf(5) +file. If interfaces are specified in this way, then the client will +only configure interfaces that are either specified in the +configuration file or on the command line, and will ignore all other +interfaces. +.SH OPTIONS +.TP +.BI \-p\ +The UDP port number the DHCP client should listen and transmit on. If +unspecified, +.B dhclient +uses the default port 68. This option is mostly useful for debugging +purposes. If a different port is specified for the client to listen and +transmit on, the client will also use a different destination port - one +greater than the specified destination port. + +.TP +.BI \-d +Force +.B dhclient +to run as a foreground process. This is useful when running the client +under a debugger, or when running it out of inittab on System V systems. + +.TP +.BI \-e\ VAR=value +Define additional environment variables for the environment where +dhclient-script executes. You may specify multiple +.B \-e +options on the command line. + +.TP +.BI \-q +Suppress all terminal and log output except error messages. + +.TP +.BI \-1 +Try one to get a lease. On failure, exit with code 2. + +.TP +.BI \-r +Tell +.B dhclient +to release the current lease it has from the server. This is not required +by the DHCP protocol, but some ISPs require their clients to notify the +server if they wish to release an assigned IP address. + +.TP +.BI \-lf\ +Path to the lease database file. If unspecified, the default +.B DBDIR/dhclient.leases +is used. + +.TP +.BI \-pf\ +Path to the process ID file. If unspecified, the default +.B RUNDIR/dhclient.pid +is used. + +.TP +.BI \-cf\ +Path to the client configuration file. If unspecified, the default +.B ETCDIR/dhclient.conf +is used. + +.TP +.BI \-sf\ +Path to the network configuration script invoked by +.B dhclient +when it gets a lease. If unspecified, the default +.B CLIENTBINDIR/dhclient-script +is used. + +.TP +.BI \-s\ +Specifiy the server IP address or fully qualified domain name to transmit +DHCP protocol messages to. Normally, +.B dhclient +transmits these messages to 255.255.255.255 (the IP limited broadcast +address). Overriding this is mostly useful for debugging purposes. + +.TP +.BI \-g\ +Only for debugging. Set the giaddr field of all packets the client +sends to the IP address specified. This should not be expected to work +in any consistent or useful way. + +.TP +.BI \-n +Do not configure any interfaces. Most useful combined with the +.B -w +option. + +.TP +.BI \-nw +Become a daemon process immediately (nowait) rather than waiting until an IP +address has been acquired. + +.TP +.BI \-w +Keep running even if no network interfaces are found. The +.B omshell +program can be used to notify the client when a network interface has been +added or removed so it can attempt to configure an IP address on that +interface. + +.TP +.BI \-B +Set the BOOTP broadcast flag in request packets so servers will always +broadcast replies. + +.TP +.BI \-I\ +Specify the dhcp-client-identifier option to send to the DHCP server. + +.TP +.BI \-H\ +Specify the host-name option to send to the DHCP server. The host-name +string only contains the client's hostname prefix, to which the server will +append the ddns-domainname or domain-name options, if any, to derive the +fully qualified domain name of the client. The +.B -H +option cannot be used with the +.B -F +option. + +.TP +.BI \-F\ +Specify the fqdn.fqdn option to send to the DHCP server. This option cannot +be used with the +.B -H +option. The fqdn.fqdn option must specify the complete domain name of the +client host, which the server may use for dynamic DNS updates. + +.TP +.BI \-V\ +Specify the vendor-class-identifier option to send to the DHCP server. + +.TP +.BI \-R\