joinc(8)joinc(8)NAMEjoinc - Daemon for DHCP client configuration
SYNOPSIS
/usr/sbin/joinc [-f] [-dn] [-ln]
OPTIONS
Sets debug level to n. If debug is turned on, log messages are also
enabled. Runs in the foreground instead of as a daemon process.
Enables warning (n > 0) and log (n > 1) messages. If n is not explic‐
itly given, the value one is assumed (warnings are turned on).
DESCRIPTION
The joinc daemon implements the client half of the Dynamic Host Config‐
uration Protocol (DHCP) with hardware extensions.
(JOIN is a trademark of Competitive Automation.)
The DHCP protocol, among other things, permits a client to establish an
endpoint for communication with a network by delivering an IP address
for each of the client's network interfaces, and a “lease” on that
address. The lease specifies the interval for which the address remains
valid: it may be infinite or of fixed duration. If it appears that the
client wishes to continue using the IP address after its expiration,
the DHCP protocol must negotiate an extension. For this reason the DHCP
client code must run as a daemon, only terminating when the client pow‐
ers down.
Communication with the joinc daemon is effected through the agency of
an auxiliary program called dhcpconf. The joinc daemon may be invoked
as a user process (requiring root privileges), but this is not neces‐
sary as the dhcpconf program will start it implicitly.
When started, joinc reads its startup file, /etc/join/client.pcy and
either proceeds to act on the instruction(s) passed to it by the dhcp‐
conf program, or enters a passive state while awaiting a new command.
When joinc receives a command to configure an interface the DHCP proto‐
col starts. If successful the interface is configured. The configura‐
tion received is stored in the interface.dhc file located (by default)
under the /etc/join directory. The client daemon sleeps until it needs
to renew the lease, which happens well before the lease expires. Upon
wakeup, if the interface is found to be down or has a different IP
address, joinc considers that the interface is no longer under its con‐
trol and drops it from future consideration, until an explicit request
arrives from dhcpconf. If the lease cannot be renewed, joinc takes down
the interface when it expires as required by the DHCP protocol. See
RFC 1541 for details.
The DHCP protocol also acts as a mechanism to configure other informa‐
tion needed by the client such as name domain and router addresses. The
joinc daemon does not configure this information but acts as a database
which may be interrogated by other programs, particularly by dhcpconf.
This approach is more flexible in that it allows third party software
access to the data through a published API, and allows system adminis‐
trators to control client configuration by customizing startup scripts
to permit various aspects of the client and its software to be custom‐
ized in a specific order. On clients with a single interface this is
straightforward; clients with multiple interfaces may present difficul‐
ties because some information arriving on different interfaces may need
to be merged, or may be inconsistent. Furthermore, the configuration of
the interfaces is asynchronous; requests may arrive while some or all
of the interfaces are still unconfigured. The joinc daemon resolves
these problems as follows. When a request for a global parameter
arrives, joinc searches all interfaces that were successfully config‐
ured, and returns to the requester the name of the first one it find to
contain the pertinent data. The client program may then access the data
by an API which reads the appropriate interface.dhc file. If no inter‐
faces are successfully configured when the request is received, or if
the none of those which are configured have the data, the request
fails. The dhcpconf program allows this behavior to be overridden by
insisting that the global data sought be associated with a particular
interface. See dhcpconf(8) for details.
The joinc daemon writes informational and error messages in four cate‐
gories: Errors are severe, usually unrecoverable, events due to
resource exhaustion and other unexpected failure of system calls. An
error is also generated if the client's lease on an IP address is in
danger of expiring. Warnings are less severe, and in most cases
describe unusual or incorrect datagrams received from clients, or
requests for service that cannot be provided. Informational messages
provide a readable transcription of (correct) actions performed by the
server on behalf of client hosts. Debug messages may be generated at
various levels of verbosity from zero (not at all) through nine, as
controlled by the -d option.
Warning, informational, and debug messages are discarded. Errors are
written to /dev/console and are sent to the system logger syslog(3) at
priority LOG_ERR and with a facility identifier LOG_DAEMON. If warnings
are enabled they also are written to the system console and syslog with
the same facility, but at priority LOG_WARNING. The creation and dispo‐
sition of messages is controlled by the -f, -d, and -l command line
options, and the JOINLOG environment variable. When present, JOINLOG
names a file to which messages are sent in preference to the system
console. Note that until the root file system is mounted read-write no
ordinary file can be used for this purpose.
RESTRICTIONS
A cluster member should never be a DHCP client. It should always use
static addressing.
If a cluster is to support a DHCP server, there can be only one DHCP
server for all the cluster members using a common database with
failover.
The joinc daemon can configure clients with two or more interfaces giv‐
ing each an IP address. However, each interface so configured must be
on a different physical network and subnet.
DIAGNOSTICS
Upon receipt of SIGUSR1 signals, the joinc daemon dumps the contents of
its scheduling table and the status of each interface under its con‐
trol.
FILES
By default, the joinc daemon expects to read its policy file and read
and write its configuration databases in the /etc/join directory. The
JOINCONFIG environment variable may be used to select a different
directory. Contains parameters that govern the behavior of joinc, and
general policies concerning network administration. Contains the con‐
figuration for interface. The existence of this file does not imply
that the configuration is correct, since the lease may have expired.
SEE ALSO
Commands: dhcpconf(8), dhcpparm(8), joind(8), showdhc(8), shleases(8)
Files: client.pcy(4)
RFC 1541
joinc(8)
