path: root/man/2/dhcpclient

.TH DHCPCLIENT 2
.SH NAME
Dhcpclient: Bootconf, Lease, bootp, dhcp, applycfg, removecfg \- client's side of dynamic host configuration protocol
.SH SYNOPSIS
.EX
include "dhcp.m";   # sic
dhcpclient := load Dhcpclient Dhcpclient->PATH;
Bootconf, Lease: import dhcpclient;

Bootconf: adt {
    ip:      string;
    ipgw:    string;
    ipmask:  string;
    bootf:   string;
    bootip:  string;
    dhcpip:  string;
    siaddr:  string;
    serverid: string;
    sys:     string;
    dom:     string;
    lease:   int;
    options: array of array of byte;
    vendor:  array of array of byte;

    new:     fn(): ref Bootconf;
    get:     fn(c: self ref Bootconf, n: int): array of byte;
    getint:  fn(c: self ref Bootconf, n: int): int;
    getip:   fn(c: self ref Bootconf, n: int): string;
    getips:  fn(c: self ref Bootconf, n: int): list of string;
    gets:    fn(c: self ref Bootconf, n: int): string;
    put:     fn(c: self ref Bootconf, n: int, a: array of byte);
    putint:  fn(c: self ref Bootconf, n: int, v: int);
    putips:  fn(c: self ref Bootconf, n: int, ips: list of string);
    puts:    fn(c: self ref Bootconf, n: int, s: string);
};

Lease: adt {
    configs: chan of (ref Bootconf, string);

    release: fn(l: self ref Lease);
};

init:      fn();
tracing:   fn(debug: int);
bootp:     fn(net: string, ctlifc: ref Sys->FD, device: string,
               init: ref Bootconf): (ref Bootconf, string);
dhcp:      fn(net: string, ctlifc: ref Sys->FD, device: string,
               init: ref Bootconf, options: array of int):
               (ref Bootconf, ref Lease, string);

applycfg:  fn(net: string, ctlifc: ref Sys->FD,
               conf: ref Bootconf): string;
removecfg: fn(net: string, ctlifc: ref Sys->FD,
               conf: ref Bootconf): string;
.EE
.SH DESCRIPTION
.B Dhcpclient
implements the client side of the Dynamic Host Configuration Protocol (DHCP) of Internet RFC2131.
In the interface, Internet addresses are represented as strings, in forms that
.IR ip (2)
can parse, and that can be written directly to control files in
.IR ip (3).
.PP
.B Init
must be called before invoking any other operation of the module.
.PP
.B Bootp
reserves the UDP port on
.I net
for use by BOOTP/DHCP clients, and sends a BOOTP request (ie, one without a DHCP operation code).
.I Net
is the name of the network directory (if nil, the default is
.BR /net ).
If
.B bootp
is to configure the interface according to the results received,
.I ctlifc
should be open on the control file of the
.IB net /ipifc
directory for the interface to be configured; otherwise it should be nil.
.B Bootp
repeats the request periodically until it either receives a reply or has made 5 attempts.
It returns a tuple
.BI ( conf,\ err ).
If it has received a reply,
.I conf
refers to a
.B Bootconf
value that contains the values received, and
.I err
is nil.
If
.I ctlifc
is not nil, the interface will also have been configured appropriately.
If a valid reply has not been received, or some other error occurred,
.I conf
is nil, and
.I err
is a diagnostic.
.PP
.B Dhcp
has a similar interface, but runs the full DHCP protocol.
The
.I options
array has integers representing possible DHCP options;
.B dhcp
asks the server to provide values for them.
If
.I options
is nil, a few option values are requested that might be useful for Inferno
(eg, subnet mask, gateway, DNS server, authentication and file servers, and so on).
If the server does supply them, they can be retrieved either from
specific fields of
.BR Bootconf ,
or using its
.I get
operations.
.I Init
is also usually nil, but can refer to a
.B Bootconf
that provides some values to suggest to the server, for instance if the client
knows a previously-assigned address stored in non-volatile memory.
.B Dhcp
returns a tuple
.BI ( conf,\ lease,\ err ),
where
.I conf
and
.I err
are just as for
.BR bootp ,
and the new component
.I lease
is a reference to a
.B Lease
value that gives access to the state of the client's address assignment.
.PP
DHCP allows a server to assign a client an address permanently, or to lease it for a specified time.
In the latter case,
.B Bootconf.lease
will have a non-zero value, and
the client must periodically renew the lease to retain the address, and
.B dhcp
creates a process to do so.
The
.B Lease
value provides a way for that process to communicate changes (if any) to the network configuration.
Each time the configuration changes, the process will send a message on the channel
.BR configs .
(The channel is buffered, and
.B dhcp
first discards any previous notifications not yet received, so there are no ill effects
if no process ever receives from the channel.)
Each message is a tuple
.BI ( conf,\ diag ).
If a new state change has been made successfully,
.I conf
refers to a
.B Bootconf
value with the details.
Otherwise,
.I conf
is nil and
.I diag
explains what went wrong.
In any case, the watchdog process continues to try to extend the lease, or failing that,
obtain a new network configuration, perhaps from another server.
.B Lease.release
may be called to release the leased address and stop the watchdog.
.PP
.B Bootconf
has the following operations:
.TP
.B new()
Return a reference to a
.B Bootconf
with values initialised to nil or 0.
.TP
.IB bc .get( n )
Return the value of DHCP option
.I n
as a raw array of bytes.
Return nil if the option is not set.
.TP
.IB bc .getint( n )
Return the value of option
.I n
interpreted as an integer.
Return zero if the option is not set.
.TP
.IB bc .getip( n )
Return the first Internet address provided for option
.IR n .
.TP
.IB bc .getips( n )
Return a list of all the Internet addresses provided for option
.IR n .
.TP
.IB bc .gets( n )
Return the value of option
.I n
as a string.
.TP
.IB bc .put( n,\ a )
Set the value of DHCP option
.I n
to the bytes of byte array
.IR a .
If
.I a
is nil,
.B put
removes any existing value for the option.
.TP
.IB bc .putint( n,\ v)
Set option
.I n
to the integer value
.IR v .
.TP
.IB bc .putips( n,\ ips )
Set option
.I n
to the list of Internet addresses
.IR ips .
.TP
.IB bc .puts( n,\ s )
Set option
.I n
to the string
.IR n .
.PP
.B Dhcpclient
names a few constants representing commonly-used configuration options (attributes).
They are suitable parameters for the option selector
.I n
of
.BR Bootconf 's
.I get
and
.I put
functions.
The first set of constants name options for both BOOTP and DHCP:
.PP
.PD 0
.TP 25
.B Odnsserver
Internet address(es) of Domain Name Servers
.TP
.B Odomainname
Current domain (see
.BR Bootconf.dom )
.TP
.B Ohostname
Host name (see
.BR Bootconf.sys )
.TP
.B Omask
Network mask (IPv4).
Also see
.BR Bootconf.ipmask .
.TP
.B Onetbiosns
NetBIOS servers
.TP
.B Ontpserver
Network Time Protocol servers
.TP
.B Opop3server
POP3 mail servers
.TP
.B Orouter
Default router for subnet (see
.BR Bootconf.ipgw )
.TP
.B Osmtpserver
SMTP mail delivery servers
.TP
.B Ovendorinfo
Vendor-specific data (see below)
.TP
.B Owwwserver
HTTP proxy
.PD
.PP
The second set has DHCP options:
.PP
.PD 0
.TP 25
.B Obootfile
Name of the file containing a kernel for the client  to load (eg, by TFTP); see
.BR Bootconf.bootf .
.TP
.B Olease
Lease time for IP address, in seconds (also see
.BR Bootconf.lease )
.TP
.B Omaxmsg
Maximum DHCP size the client is willing to accept (minimum 576 bytes).
.TP
.B Orebindingtime
Time interval in seconds from address assignment to the time address must be rebound.
.TP
.B Orenewaltime
Time interval in seconds from address assignment to first attempt to renew the address.
.TP
.B Otftpserver
TFTP server from which to fetch kernel and parameter files; see
.BR Bootconf.bootip .
.TP
.B Ovendorclass
Identify vendor type and configuration of client. Inferno sets
this to
.B plan9_386
(sic) to encourage Plan 9 DHCP servers to respond; other servers will ignore it.
.PD
.PP
The final set give vendor-specific options that Inferno shares with Plan 9:
.PP
.PD 0
.TP 25
.B Ovendor
Flag OR'd in to an option number to mark it as destined for the `vendor information' section.
.TP
.B OP9auth
Authentication server
.RB ( Ovendor|129 )
.TP
.B OP9fs
File server
.RB ( Ovendor|128 )
.PD
.PP
Given a network configuration in
.IR conf ,
and a valid file descriptor for a network interface's control file,
in the network
.IR net ,
.B applycfg
sets the basic interface parameters (address, network mask, default gateway),
and writes other parameters to
.IR net /ndb ;
conversely,
.B removecfg
removes from the interface just those parameters set by
.IR conf .
Normally these functions are called automatically, as required, by
.B dhcp
and its watchdog process.
.SH SOURCE
.B /appl/lib/dhcpclient.b
.SH SEE ALSO
.IR bootpd (8),
.IR dhcp (8)