Summary and Problem Description

  The DHCP client program (dhcpagent daemon; PSARC 1999/040)
  implements a state machine.  Customers may want to perform some
  actions when the state changes; for examples, fire up an application
  after lease request is honored and the specified interface is
  configured successfully, or perform cleanup before the interface is
  released from DHCP control.  It can be done through event
  notification by invoking a customer- installed action program.  The
  current dhcpagent implementation in Solaris does not provide such a
  mechanism.  This RFE addresses the shortcoming.  It provides basic
  functionality similar to that of the open source ISCDHCP
  implementation.

Release Binding

  Patch/micro

Event Names

  Events represent the state changes for the dhcpagent state machine.
  The following events are supported.  For each event, the text below
  describes when the event occurs and when the event program is
  invoked.

  (1) BOUND

  This event occurs when dhcpagent receives the ACK reply from the
  DHCP server for the lease request of an address.  The event program
  is invoked just after the interface is configured successfully.

  (2) EXTEND

  This event occurs when dhcpagent successfully extends a lease, or in
  response to DHCPACK from DHCPINFORM.  The event program is invoked
  just after dhcpagent receives the ACK reply from the DHCP server for
  the renew request.

  (3) EXPIRE

  This event occurs when a lease expires.  The event program is
  invoked just before the leased address is removed from the interface
  and the interface is marked as "down".

  (4) DROP

  This event occurs when the interface is removed from DHCP control.
  The event program is invoked just before the interface is removed
  from DHCP control.

  (5) RELEASE

  This event occurs when the leased address is relinquished on the
  interface.  The event program is invoked just before dhcpagent
  relinquish the address on the interface and sends the RELEASE packet
  to the DHCP server.

State Machine

  For any given interface, the hook script will see cycles consisting
  of:

	exactly one BOUND
	zero or more EXTENDs
	exactly one of either DROP, EXPIRE, or RELEASE

  in other words:

  The script will not see an EXTEND unless the previous event was
  either BOUND or a previous EXTEND

  The script will only see BOUND after another event since boot if the
  previous event was DROP, EXPIRE, or RELEASE

  The script will not see more than one of DROP, EXPIRE, or RELEASE
  for each BOUND.

Program Invocation

  Event programs can be any executable binary or script.  Dhcpagent
  looks at the fixed location /etc/dhcp/eventhook to see whether the
  event program exists and is executable.  The system doesn't provide
  a default event program.  The file /etc/dhcp/eventhook should be
  owned by the root and its mode should be 755, but the daemon does
  not enforce this.

  Upon the event program invocation, the interface name and the event
  name are passed to the program as command line arguments
  (i.e. /etc/dhcp/eventhook interface-name event-name).  The event
  program can use the dhcpinfo utility program to fetch more
  information about the interface.  The event program is invoked on
  every event defined in this document.  It can ignore those events in
  which it is not interested.  Like dhcpagent, event programs run with
  root privileges.  Program environments are inherited from dhcpagent.
  Stdin, stdout, and stderr are connected to /dev/null before
  invocation.

  Dhcpagent waits for the event program to exit on each event.  To
  avoid being blocked forever in case the event program hangs,
  dhcpagent waits at most 60 seconds; the event program is forcefully
  terminated if it doesn't exit after 60 seconds.  It first sends
  SIGTERM to the child and if it doesn't exit after another 3 seconds,
  it sends SIGKILL.

  Dhcpagent doesn't look at the program's exit status.  It is
  generally agreed by the I-team that a tunable is not justified for
  the wait time.

  If the script attempts to use ifconfig dhcp subcommands on the
  interface, it will fail like this:

	ifconfig: hme0: interface currently has a pending command (try later)

  This is existing behavior for the DHCP subsystem; if an event is in
  progress, you can't modify the interface state.  Because of this,
  it's not possible for BOUND, DROP, or RELEASE events while a script
  is still running.  EXTEND and EXPIRE events originate externally,
  and are queued.

  This mechanism doesn't use sysevents because they're asynchronous,
  and a synchronous interface was expected to be simpler to use.

  This project grants all of the permissions of dhcpagent to the
  script that is run.  That presently includes uid=0 and privs=all.  A
  future project that restricts dhcpagent to a subset of those
  privileges would also have to address how the privileges for user
  scripts are specified.

  Well-written user scripts should be written to ignore unknown
  events.


Interface Table

Interface               Stability       Description
-------------------     ---------       -----------------------------------
/etc/dhcp/eventhook     Evolving        Customer-supplied script/program
privileges		Evolving	Script's privileges; see text
interface-name event    Evolving        Command line arguments to eventhook
BOUND                   Evolving        Event keyword passed to eventhook
EXTEND                  Evolving        Event keyword passed to eventhook
EXPIRE                  Evolving        Event keyword passed to eventhook
DROP                    Evolving        Event keyword passed to eventhook
RELEASE                 Evolving        Event keyword passed to eventhook