PSARC 2009/285 DHCP Client Updates

[James Carlson]

I'm sponsoring this fast-track request for myself.  The timer is set
to 05/13/2009, the interfaces described are all "Committed", and the
release binding is Patch/Micro.  This project includes five fairly
simple updates for dhcpagent (the DHCP client on OpenSolaris) for the
price of one.

The changes could reasonably go in a patch, but, for clarity, I have
no intention of backporting them at this time.  They're intended for
OpenSolaris.

1.  Waiting for commands other than "start."

    The ifconfig "dhcp" subcommand allows the insertion of an optional
    "wait <n>" (where <n> is in seconds) directive between the "dhcp"
    keyword and the keyword specifying a command.

    Currently, the only thing that this does is to include a timeout
    parameter in the command sent (via IPC) to the dhcpagent process,
    which then uses it as a timer for the "start" operation.  In all
    cases, the client blocks "forever" waiting for the results, and
    relies on the server for any timers.

    As described in CR 6823679, this behavior can be harmful if
    something bad has happened to the DHCP server, and thus to
    decouple clients from server behavior, we will now take the
    timeout into account on the client side as well.  To make things
    simple, the client will always wait two seconds longer than the
    timeout value sent to the server, so the server has a chance to
    report its own timeout in the "normal" failure case.

    This will allow clients (such as nwamd) to use:

	ifconfig <intf> dhcp wait <n> drop
	ifconfig <intf> dhcp wait <n> release

    No man page updates are needed; the new behavior is consistent
    with the existing documented behavior.

2.  dhcpinfo primary

    The dhcpinfo(1) command will fail if no "-i <intf>" option is
    provided and there's no "primary" DHCP interface.

    As described in CR 6553194, nwamd intentionally does not set
    "primary" on any interface, and thus /sbin/dhcpinfo will fail
    unless given the "-i" option.  While use of "-i" is clearly the
    preferred method in DHCP eventhook scripts, in order to be
    specific about the information desired, other scripts may invoke
    this command without knowing which interface is the "right" one.

    This project will change dhcpinfo behavior such that if "-i" is
    not specified, and no DHCP-controlled interface is marked primary,
    then the interface whose name sorts lexically first and that has
    information from a DHCP server will be treated as the "primary"
    interface for the requested parameter.  This behavior mirrors the
    historical behavior of the system boot-time automatic "primary"
    interface selection.

    If a primary interface is selected, then this new feature has no
    effect; omitting the "-i" option causes dhcpinfo to return DHCP
    parameters from only that one interface.

    This new behavior will be documented on the dhcpinfo(1) man page.

3.  Ignore unwanted options

    As documented in CR 6667011, it's frequently necessary to exercise
    discretion in the DHCP client's operation by ignoring some
    parameters provided by the server.  For example, one may wish to
    ignore the "Hostname" parameter to avoid using one assigned by a
    hostile administrator (such as an ISP), or ignore an untrusted
    source of "DNSserv" addresses.  The existing PARAM_REQUEST_LIST
    does not do this; it only sets the list of parameters we request
    from the server and does not constrain the results the server may
    supply.

    In order to allow for this discretion, a new "PARAM_IGNORE_LIST"
    parameter will be added to /etc/default/dhcpagent.  This parameter
    is a string representing the DHCP Standard and Site options that
    should be ignored, and operates in exactly the same manner as the
    existing "PARAM_REQUEST_LIST" parameter.  If the server supplies
    one of these parameters, we will behave as though it wasn't
    supplied.

    (Note that Vendor options cannot be ignored.  They can't be
    requested, either.)

    The dhcpagent(1M) man page (which documents this file) will be
    updated to describe this new parameter.

4.  Symbolic parameter names

    As described in 4783123, it would be easier for administrators to
    add entries to the PARAM_REQUEST_LIST if they could use the
    symbolic names from /etc/dhcp/inittab (and /etc/dhcp/inittab6 for
    v6.PARAM_REQUEST_LIST), in much the same way that symbolic option
    names are allowed for the dhcpinfo(1) command.

    This project will update the agent to parse out symbolic Standard
    and Site options for PARAM_REQUEST_LIST and the new
    PARAM_IGNORE_LIST.

    The dhcpagent(1M) man page (which documents this file) will be
    updated to describe the new behavior.

5.  Lease validation refinement

    Currently, the dhcpagent daemon will "drop" releases on shutdown,
    which means that the lease is stored in local stable storage
    (disk) and the DHCP server is not informed that the client is
    shutting down.  It then attempts to get the lease back at
    start-up.  The /etc/default/dhcpagent file has a
    RELEASE_ON_SIGTERM option that will make the daemon "release"
    leases at shutdown instead, so that the lease isn't stored on
    disk, and the server is told that we're finished with the lease.

    This latter behavior is more desirable for nomadic clients, but as
    CR 6835298 documents, it sometimes isn't enough.

    In particular, the daemon will attempt to reverify leases on a
    link down/up transition and on a SIGTHAW (due to suspend/resume).
    If the server fails to respond at all (which is quite likely if
    you've moved your laptop to a new network and the server doesn't
    recognize you), you'll drive on with your old and now-invalid
    lease, and RELEASE_ON_SIGTERM won't help.

    To fix this problem, a new VERIFIED_LEASE_ONLY flag will be
    introduced.  When this flag is set (the flag has the same on/off
    sense and default as the previous flag), the DHCP client will
    discard the lease if it's unable to verify rather than continuing
    with the remaining lease, and will return to a normal lease
    acquisition attempt, in addition to not caching the lease at
    shutdown time and releasing it at the server, just like
    RELEASE_ON_SIGTERM.

    Due to the way parameters in this file are parsed, the simplest
    change is to allow RELEASE_ON_SIGTERM to continue to have its old
    meaning and not affect link-up/SIGTHAW, so that the new parameter
    is a superset of the old behavior.  We will remove
    RELEASE_ON_SIGTERM from the template /etc/default/dhcpagent file
    and the man page, and replace with VERIFIED_LEASE_ONLY.
    RELEASE_ON_SIGTERM becomes "Obsolete Committed."

Upgrade notes:

    On upgrade from a previous release, SysV packaging will edit the
    existing /etc/default/dhcpagent file to conform with the new
    features, but only if it contains the old text.  In all but one
    case, this is merely comment changes.

    If the user has set RELEASE_ON_SIGTERM set and upgrades with SysV
    packaging, we will convert this to VERIFIED_LEASE_ONLY.  The
    greatest likelihood is that users will need the new behavior and
    not the old.

    If this were released as a patch (no plans to do so), we would
    make the patch scripts leave RELEASE_ON_SIGTERM alone, so that the
    existing behavior is not changed, and the user must explicitly add
    the new variable if desired.

    The implications for IPS are not known at this time.  IPS does not
    have a facility similar to the i.dhcpagent class-action script in
    SUNWcnetr.  However, users will be notified via mailing lists
    about the new feature.