CONNECTD(8)

by Stuart Rackham
<srackham@methods.co.nz>
v0.6.2, January 2004

NAME

connectd - connection manager server

SYNOPSIS

connectd [-l link_name] [-b link_behavior] [-p server_port] [-o open_command] [-c close_command] [-s status_command] [-r maxretries] [-i poll_interval] [-m maxsessions] [-f links_file] [-h]

DESCRIPTION

The connectd daemon responds to connection management commands from connect clients. connectd opens and closes links by running configurable link specific commands. The default link commands are designed to manage a PPP connection using pppd(8).

connectd is assumed to have exclusive control of the links it manages, without exclusive control link management will probably be unreliable.

OPTIONS

All options apart from the -p server_port option are link specific and if specified are applied to the default link (the first link in the links configuration file or the only link if no links configuration file exists).

The default option values will configure a fairly typical PPP connection using pppd(8).

Commandline options take precedence over link configuration file options.

-l link_name

The name of the default link. link_name is the name used by connectd(8) to identify the link and is unrelated to the network interface name. Default is value is ppp0. Must not contain embedded spaces.

-b link_behavior

This option takes one of three values (hold_open or initiate_open or wait_open) and specifies the behavior of the default link's open_command. The default is hold_open. See LINK CONTROL below.

-o open_command

The program that opens the default link. The default "/usr/sbin/pppd nodetach file /etc/connect/connect.options" starts the PPP dialer daemon. The open_command must conform to one of the Link Behaviors.

-c close_command

The program that closes the default link. The default is no close command, in which case connectd closes the link by terminating the open_command process with a SIGTERM signal (see -o option). In contrast to the open command the close command will always succeed.

-s status_command

This command is run every poll_interval seconds while the default link is not closed. The command exits with a status of 0 if the link is open or 1 if the link is not open.

-i poll_interval

The interval in seconds to use when polling the link status. Minimum value 1 second, default value 1 second.

-m maxsessions

Maximum number of clients that can connect at one time. Default 5.

-p server_port

Server listens on this socket number. Default 8235. Minimum value 1024, maximum value 49151.

-r maxretries

The maximum number of times to retry to make a connection after the initial attempt fails (zero means try once). Default 5.

-f links_file

Specify a path name for the links configuration file. Default /etc/connect/connect.links (see FILES).

-h

Enables the leave_open option for the default link. When this option is set the connectd does not close the physical connection when it receives a close command. It is up to the link open_command to close the link autonomously (for example, using the idle time-out mechanism in pppd(8)). Link closure can still be forced using the forceclose and forcelock commands. This option can be set to true or false (the default is false) in the links configuration file /etc/connect/connect. The option was motivated by the need to have a PPP link held open continuously during the day, where is is kept alive by regular scheduled mail retrieval, and to close automatically at night once traffic stops and the PPP idle timeout expires. This option is only available for links that implement the hold_open behavior.

CONNECT PROTOCOL

Connect employs a simple client request / server response protocol.

Client Request 

The client request message is formatted like:

  session_name link_name command [command_argument]

- The session_name and link_name items are described in the OPTIONS
  section of the connect(1) man page.
- The command item can take the following values: open, close,
  sessions, links, status, forceclose, forcelock, lock, unlock,
  version. These commands are described in the CONNECT COMMANDS
  section of the connect(1) man page.
- All requests must be terminated by a newline character.
- All items are separated by white space characters and must not
  contain white space characters.
- The first three items (session_name, link_name, command) are
  mandatory.
- The command_argument is optional.
- A reserved link_name of '<default>' instructs the server to use the
  default link.
- Client requests are case sensitive.

Server Response

The server response messages are formatted like: 

response_code [response_data]

Note: The newline character is the line feed character (\n, 0x0a).

Response Codes 

If the command was accepted or accepted and executed without errors
the reponse_code begins with a '+', if the command was not accepted or
an execution error occured the response_code begins with a '-'
character. Response codes are categorised by the first digit as
follows:

        -100    Request syntax error.
        -200    Request execution error.
        +0xy    Status command response code (see below).
        +100    Request accepted but execution not yet completed.
        +200    Request accepted and executed successfully.

The second digit (x) of the the status command response code is the
link lock state which is encoded as follows:

        0 link unlocked
        1 link locked
        2 link locking

The third digit (y) of the the status command response code is the
link state which is encoded as follows:

        0 link closed
        1 link open
        2 link closing
        3 link opening
        4 link dropped
        5 link failed
        6 link idle

Example commands:

  Request:      srackham@neutrino internet open
  Response:     +100

  Request:      srackham@neutrino internet status
  Response:     +001
                internet  open  1  4  00:00:25  01:25:23  unlocked

  Request:      srackham@neutrino internwt close
  Response:     -200
                Unknown link internwt


LINK COMMANDS
-------------
Links are controlled by three executable link commands. Link commands
are executed by connectd to open, close and monitor connections. The
link commands are set by the open_command, close_command and
status_command options. Commands are (in order of increasing
precedence) default values or specified in the links configuration
file or specified on the commandline.

- Link activation is always initiated by a link open_command.
- An optional link_status command periodically monitors the link
  open/closed status.
- An optional link_close command closes the link.

Link commands are run by the execv() system call and are subject to
the following restrictions:
- All file names should be specified by there full path names. No
  tilde expansion is performed.
- Since the commands are not run via a shell no input/output
  redirection, pipes or other shell features can be used.
- Environment variables are inherited from the parent (connectd)
  process (usually the exported root environment).

Link command security implications are discussed under SECURITY.

For flexibility link open_commands are acceptable if they conform to
one of three link control behaviors. These behaviours are outlined
below in the context of the link control commands.

Link open_command

The link open command implements one of three link control behaviors:

hold_open behavior - - - - - - - - - The open_command continues running until: - The link fails to open. - The link is closed by connectd in reponse to a client command. - An external event closes the link.

The link is assumed closed once the open_command has exited. The open_command must detect link closure by an external event in which case it should exit immediately. If no link close_command is specified he open_command must respond to the SIGTERM signal by closing the link and exiting.

No assumptions are made regards the open_command exit codes.

This is the behavior of the default -o "/usr/sbin/pppd nodetach file /etc/connect/connect.options" open_command option.

initiate_open behavior - - - - - - - - - - - The open_command initiates link activation then exits with a zero exit code. A link close_command must be specified. If link initiation fails an exit code of 1 should be returned, in this case the link has failed and no retries are attempted.

If there is no status_command the link is assumed to have opened once the open_command returns with a zero exit code.

wait_open behavior - - - - - - - - - This is the same as the link initiate_open behavior except that it does not exit till either the link has opened or fails to open.

The open_command should respond to the SIGTERM signal by closing the link (if it is open or opening) and exiting.

Link status_command 

The status_command is used to detect whether the link is currently
open or closed.

The default mechanism is a built-in command that checks for an
open PPP network interface by searching the /proc/net/route
file for a line starting with ppp0 followed by a tab
character. For this mechanism to work connectd should only
manage one PPP link.

The default status_command is suitable for one PPP link per
server because the network interface name is choosen
dynamically when pppd(8) connects (starting with the name
ppp0). To manage multiple PPP links a status_command must be
implemented.

If no status_command is available then the pseudo command
n/a (not applicable) should be specified.

If status_command is unavailable then the open_command must
return a 0 status when the link opens (or 1 if it fails to
open) and a close_command must exist to close the link. If
there is no status_command then the links is assumed to be
reliable in that once the link has been opened connectd
assumes it will remain open until the close_command is
executed.

The server blocks while running the status_command and it must
therefore complete quickly.

The status_command exit code is zero if the link is open and one if
the link is closed, any other exit code is logged as an error.

The status_command always exits normally unless a catastrophic error
occurs.

The link_status command is optional but very useful in the following
situations:

hold_open, initiate_open behaviors
- - - - - - - - - - - - - - - - -
After the open_command has been started the link_status
command is used to detect when the link has opened or failed
to open. Without the status command the link is assumed open
as soon as the open_command has started.

initiate_open, wait_open behavior
- - - - - - - - - - - - - - - - -
After the link has opened (link_open) the link_status command
is used to detect when the link is closed by an external event
(link_dropped).  Without the status command there is no way to
detect a dropped link.

Link close_command

This link command closes the link if it is open, if the link is already closed it returns immediately.

If hold_open behavior is implemented then the close_command can be omitted, in which case connectd closes the link by sending the SIGTERM signal to the running open_command which responds by closing the link then exiting.

The link is assumed closed once the close_command exits.

If the close_command is successful it's exit code will be zero, if non-zero then an error is logged.

SECURITY

Assign root ownership to the /etc/connect/connect.links configuration file and set access permissions to rw-r--r-- (mode 644). This prevents unauthorized (non-root) users configuring connectd to run unauthorised link commands with root permission.

To stop non-root users executing connectd assign it root ownership and set the access permissions to rwxr--r-- (mode 744).

SIGNALS

SIGINT, SIGTERM

These signals cause connectd to close all open links and exit.

SIGHUP

This signal causes connectd to re-read the links configuration file. New link definitions in the link configuration file are added. Existing links that are not in the configuration file are deleted if they are currently closed. Existing links that are in the configuration file are updated if they are currently closed. You can ensure link updates and deletions by locking the links closed before the SIGHUP signal is sent (see the connect(1) forcelock and forceclose commands). Any command line parameters that modified the default link will be overriden if they are defined in the links configuration file.

FILES

/etc/connect/connect.links

This is the default name of the optional connectd configuration file.

/var/run/connectd.pid

Process ID file created at startup, deleted at exit.

CONFIGURATION FILE

The connectd connect.links configuration file is located in the connectd configuration directory (/etc/connect or /usr/local/etc/connect).

connect.links is a text file and is divided into sections containing link parameters. A section begins with a line containing the link_name enclosed in square brackets, the link parameters follow on subsequent lines. Each link parameter occupies a separate line and is formatted like <parameter_name>=<value>. Blank lines and lines beginning with a # character are ignored. Parameters are trimmed of leading and trailing white spaces. If a parameter is missing the default value is used. Valid parameter names are:

link_behavior, open_command, close_command, status_command, maxretries, poll_interval, maxsessions, leave_open.

These parameters correspond to the option arguments with the same names discussed in the previous OPTIONS section.

The file is read when connectd begins execution or when connectd receives a SIGHUP signal, the first defined link is the default client link. connectd command line options take precedence over options for the default link in the configuration file.

See SECURITY for security implications of this file.

SEE ALSO

connect(1), pppd(8), chat(8)

BUGS

Other bugs almost certainly exist. Send comments and bug reports to Stuart Rackham <srackham@methods.co.nz>

AUTHOR

Stuart Rackham <srackham@methods.co.nz>