INSTALLATION
April 6 2010

This is a brief outline of how to build and install dhcpd from scratch.
(If you have already built it, and are applying a Princeton patch,
instead see the instructions that accompany that patch.)

I suggest compiling this product with gcc.  If 'gcc' is in your
path, 'configure' will find it and use it by default.

1) Run './configure' to figure out system dependancies and create the
   Makefiles for you.

2) Examine the top-level Makefile, and edit if necessary; chances are you won't
   need to change anything.

   The dhcp server includes optional SNMP support; it is not included by
   default. If you include it, the dhcpd daemon will include an SNMP agent that
   will serve a custom DHCP MIB, listening for SNMP commands at a UDP port
   (port 161 by default); a DHCP management client ('dhcpcmd') will also be
   built. Documentation on neither of these is included. If you want the
   optional SNMP support, locate the appropriate section in the top-level
   Makefile and uncomment it.

   If you instead make your changes to Makefile.in before running './configure',
   they'll be reflected every time you re-run 'configure'; otherwise you'll have
   to re-do them in Makefile if you run './configure' again. If you do choose to
   edit Makefile.in, save a copy of it first, so you'll have a clean copy when
   it comes time to apply the next patch.

3) Examine defaults.h and edit it if necessary. If you do change it, save a
   copy first, so you'll have a clean copy when it comes time to apply the
   next patch.

   Definition you may want/need to change:

     * By default we log to syslog's 'LOG_DAEMON' facility. You may override
       it by redefining LOG_FACILITY.

     * If this is a first-time install, increase HASHTABLESIZE. 
       (On an upgrade, leave it alone unless you erase your existing bindings directory.)

     * If this is a first-time install, uncomment ALT_HASH_FN2.
       (On an upgrade, leave it alone unless you erase your existing bindings directory.)

4) Run 'make'. (If you have built before, and have since made any changes to the
   Makefile, run 'make clean' first.)

  If you get any compile-time errors, check the "COMMON COMPILER AND RUN-TIME 
  ERRORS" section below.

5) Run 'make install' to copy the dhcpd executable to /etc and to create the
   /etc/bindings directory. Or perform this step by hand if you prefer.

6) Optionally copy tools/dhcp-bindings-tool to wherever is appropriate on your
   system for local utilities (e.g. perhaps /usr/local/bin).

   This tool is not necessary to use dhcpd; it is a utility to allow you to
   manipulate the bindings directory created by dhcpd.

   The tool requires perl version 5.8.0 or later.  If your perl is not in
   /usr/local/bin, you may need to edit the tool's first line to specify
   your perl location.

   The tool requires CPAN modules Readonly and Statistics::Descriptive. 

7) Optionally, install the man pages from the man directory: dhcpd.8,
   bootptab.5, dhcpd.conf.5, and dhcp-bindings-tool.8 to whereever is appropriate 
   on your system.

8) Create a bootptab file for your clients. See the bootptab.5 man page, and the
   samples in the sample/ directory.

   To write a useful bootptab, you'll probably also need to review the dhcpd.8 
   man page at some point.

9) Create an dhcpd.conf file. See the dhcpd.conf.5 man page, and the sample in
   sample/dhcpd.conf.

   To write a useful dhcpd.conf, you'll probably also need to review 
   the dhcpd.8 man page at some point.

10) If you use NIS, make sure the following entries are in your services map and
   if not, add them:

     bootps          67/udp          bootp           # BOOTP Server
     bootpc          68/udp                          # BOOTP Client

   If you don't use NIS, then add these to /etc/services.

11) Edit your /etc/syslog.conf file to capture dhcpd messages of interest. If
    you didn't change the LOG_FACILITY compile-time definition, these messages
    are logged with the facility 'daemon', and range from DEBUG to ERR.

12) Start /etc/dhcpd; you must start this as root. If the bindings directory,
    dhcpd.conf file, or bootptab file are in locations other than their
    defaults, specify those locations on the commandline.

    If you haven't already reviewed the dhcpd.8 man page, now's a good time.

    You may wish to start with the -d option specified to increase the 
    debuglevel to more than the default level of '0'.

    If you get any run-time errors that prevent the server from functioning,
    check the "COMMON COMPILER AND RUN-TIME ERRORS" section below.

13) See the "SUGGESTED FILE LAYOUT AND OPTIONS" section below for ways to better
    organize the dhcp files and recommended startup options; some of the default
    file locations and filenames are historical, rather than convenient.


-----------------------------------------------------------

COMMON COMPILER AND RUN-TIME ERRORS

---

If you need to start from scratch, in addition to the 'make clean' target,
there's also a 'make distclean' target, which will also remove the information
cached by the 'configure' program and the makefiles it creates; this is most
useful when you are copying the source tree to another platform and need to be
sure you are configuring for the new platform.

---

If you've just applied a patch, remember to follow it with a 'make distclean'
and a './configure' before you 'make'. That ensures you build with the latest
makefiles and config.h; patches often include changes to the makefile templates
or the configure program.
 
---

If you receive a compile-time error message about `__builtin_va_alist' being
undeclared (used in report.c):

    report.c: In function `report':
    report.c:109: `__builtin_va_alist' undeclared (first use this function)

and/or you receive a compile-time error about LOG_PID being undefined, then
fix your installation of gcc.  Chances are the fixed include files that gcc 
needs were not installed.

For more details, search the Solaris FAQ for 'builtin_va_alist':

  http://www.fwi.uva.nl/pub/solaris/solaris2.html

---

If you receive a runtime error at startup about ioctls; e.g.:

    ioctl(SIOCGIFCONF): not supported

then chances are the fixed include files that gcc needs were not installed.

For more details, search the Solaris FAQ for 'builtin_va_alist':

  http://www.fwi.uva.nl/pub/solaris/solaris2.html

---

If you get the following messages from dhcpd:

     ioctl SIOCSARP: Network is unreachable

...then make sure you are compiling with gcc, not cc.

And make sure the fixed include files that gcc needs were installed.

---

If you get the following message at startup:

 bind: Address already in use

...first be sure you don't already have another copy of dhcpd running (or an
older dhcp or bootp server binding to udp port 67).

The other possibility is that you compiled-in the SNMP support, and your host is
already running an SNMP daemon bound to the standard udp port 161. The SNMP
agent you get in dhcpd when you compile-in SNMP support will try to bind to port
UDP port 161 by default. If that port's already in-use, it will issue the
warning message above, then will locate another port and bind to that. Assuming
you want to keep your pre-existing SNMP agent on port 161 (you probably do!),
and you don't want to be bothered by the warning from dhcpd on each startup,
just select a new unused port for dhcp's snmp listener, and specify it with
dhcpd's -p option. If you don't need dhcpd's built-in SNMP agent, disable it at
run-time with the '-p 0' option, or exclude it at compile-time by editing the
top-level Makefile.

---

If you receive compile-time errors like:

   main.c: In function `main':
   main.c:949: structure has no member named `rt_dst'

or

   main.c:955: `SIOCADDRT' undeclared (first use in this function)

or you receive a run-time error like:

   Could not add route 255.255.255.255: No such device

then you're encountering the "broadcast route" portability bug in the code;
see the TODO document for more about it.

To workaround this problem, locate the NOBROADCAST definition in defaults.h, and
uncomment it. That will exclude the code that causes the daemon to add a host
route for destination 255.255.255.255.

If your host is able to broadcast UDP packets destined to
255.255.255.255 without having a host route to that destination, then
you'll be fine; the code that's just been excluded from main.c was
unecessary for your host.

If your host is unable to broadcast UDP packets destined to
255.255.255.255, the dhcp server will not work right.  Before starting
the dhcp server, you will need to take whatever steps are necessary to
configure your host so that it can broadcast UDP packets destined to
255.255.255.255 (which is what the code we've just excluded from main.c
was trying to ).  On most hosts, the following command will do the
trick:

   route add host 255.255.255.255 my_ip_addr 0

where 'my_ip_addr' is your host's own IP address.

---

If you receive compile-time errors in snmp.c, snmpd/*.c, snmplib/*.c, or
dhcpcmd/dhcpcmd.c, you may be encountering portability problems we have in our
SNMP support. If you don't need the SNMP support, edit the top-level Makefile to
exclude it. (It is excluded by default.)

---

mark at zang dot com (mark dot metalab dot unc dot edu) has made compiled versions 
of dhcpd with the Princeton patches for Solaris available on Sunsite; you may want 
to retrieve that if you have difficulty compiling. Visit:

http://sunsite.unc.edu/pub/packages/solaris/sparc
 ftp://sunsite.unc.edu/pub/packages/solaris/sparc

(Look for a filename that starts with 'dhcp' and check to see what version
number (patchlevel) it includes.)

---

Howard Harvey (howard <dot> harvey <at> myrealbox <dot> com) has offered to act
as a contact for "those venturesome souls who want to make it run under the BSDs
or any other operating system."

-----------------------------------------------------------

SUGGESTED FILE LAYOUT AND OPTIONS

Although the server defaults to locating its bootptab, dhcpd.conf, pidfile,
and bindings in /etc, and its dump files in /tmp, I suggest creating someplace
unique to hold them, to avoid any possible confusion with OS-supplied files.
For example:

   /usr/local/etc/dhcpd            executable
   /usr/local/dhcp/                directory for all dhcp operating files
   /usr/local/dhcp/dhcpd.conf      conf file
   /usr/local/dhcp/bootptab        bootptab file
   /usr/local/dhcp/bindings/       directory for all bindings files
   /usr/local/dhcp/dumps/          directory for dump files


Even better, create a local user 'dhcp' and a local group 'dhcp', make these the
owner/group of these directories and files, and run dhcp with the "-U dhcp -G
dhcp" options. (Remember that dhcpd needs to be able to read its conf file and
bootptab, and write to the bindings directory and dump files.)

So you might startup with:

/usr/local/etc/dhcpd -U dhcp -G dhcp -c /usr/tmp -b /usr/local/dhcp/bindings \
        -B /usr/local/dhcp/dumps/bindings.dump  -x /usr/local/dhcp/dhcpd.conf \
        /usr/local/dhcp/bootptab /usr/local/dhcp/dumps/bootptab.dump

Other options you'll probably want to consider including are: -A (disable the
'Check File Access' feature), -a (log a parseable message on each assignment),
-e (log a message whenever a lease is expired or removed), -I (ignore Client
Identifier options), -u (enable the 'Renew Unbound Statics' feature), -dN (set
debuglevel N).

The -f option is useful to specify when you first are testing the server
interactively, to keep the process in the foreground and log its messages to
stderr. (Don't use this option in production.)

You'll probably want to start with a fairly high debuglevel (e.g. -d12), so you
can see enough information about the incoming packets and the server's
decision-making to know if you've got it all configured right. Once you're sure
the server is configured right, you'll probably find it useful to normally run
with a debuglevel of 3 or perhaps 4.

You'll probably want to configure your host to start the dhcpd server when the
host boots. Don't neglect to arrange for the server to be terminated cleanly
(e.g. with a SIGINT or SIGTERM) when your host shuts down cleanly; that ensures
any bindings not yet flushed to disk get written. For a sample SysV-style
startup/shutdown script, see sample/startup-script.

As a security measure, you may wish to ensure no one from outside your site can
send packets to the dhcp server. If you have a firewall router, block incoming
UDP packets destined to the server's port 67 (the bootp/dhcp server port). (This
may not be feasible if the same router functions as a bootp relay agent.)

-----------------------------------------------------------

PLATFORMS

* Platforms known to work

        Solaris 10 on SPARC
        gcc 4.2.4

Previous releases of the program have been successfully built and used
on the following platforms:

        Solaris 2.5.1 on SPARC
        gcc 2.8.1

        Solaris 2.5.1 on SPARC
        gcc 2.95.1

        Solaris 2.6 on SPARC
        gcc 2.8.1

        Solaris 2.6 on SPARC
        gcc 2.95.1

        Solaris 2.7 on SPARC
        gcc 2.95.1

        Solaris 8 on SPARC
        gcc 2.95.2

        Solaris 8 on SPARC
        gcc 2.95.3

        Solaris 8 on SPARC
        gcc 3.0.4

        Solaris 9 on SPARC
        gcc 3.3.6

        FreeBSD 4.5 on i386
        gcc

        Solaris 9 on SPARC
        gcc 4.1.2