Connect: A Connection Resource Manager

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

Connect is a generic connection manager designed to manage a heterogeneous mix of connection oriented resources. The initial motivation for connect was the need for a PPP dial-up connection manager for small local area networks. Connect's client/server architecture allows connections to be managed locally or remotely over a TCP/IP network. The package includes a FreeBSD/Linux client and server and a Windows 95/98/NT/XP client.

Overview

IMPORTANT: Read the Connect README first.

Connect is a TCP/IP based client/server application, the server (connectd) runs as a daemon process, the client (connect) is a user application.

Connect's design is generic and it can be used in situations requiring management of multiple heterogeneous connection oriented resources. Connect is designed to concurrently manage different types of connections.

The connect server translates connect client requests to a set of (configurable) link control and monitor commands. Connect does not know (or care) about the underlying implementation of the connections it manages, for all it knows it could be opening and closing garden gates.

Vocabulary

Server: A host computer running the connectd server daemon.
Link: A physical connection resource, for example a PPP dialup connection. Each link is identified by a link name. The set of link names associated with a server are unique.
Connection: Synonym for link when used as a noun.
Client: An application that sends connect commands to the server on behalf of a user or another application.
Session: A session is an instance of active link usage. Client applications request link access by opening a new session. Each link can have zero or more different sessions. Each session has a name which is unique to the associated link.
Connect Command: A request command defined by the connect client / server protocol.
Link Command: An executable command used by the server to open, close and monitor a link.

LAN Dialup Manager

A primary application for connect is as an Internet dial-up connection manager for a small local area network, this is connect's default configuration and it is the source of most of the examples.

The network typically consists of one or more client PCs (running Linux or Windows) connected over a LAN to a Linux server. The Linux server connects to the Internet using a PPP dialup connection. Connect manages concurrent Internet connection requests from multiple workstations and applications across the PPP dialup connection.

The server will normally be configured as a masquerading gateway so that multiple client PCs can simulaneously share a single Internet connection (see the Linux IP-Masquerade-HOWTO for setting up a masquerading gateway).

Typical dial-up gateway requirements are: - Automatic mail delivery from office server to/from ISP mailboxes at regular scheduled intervals. - On demand Web browsing by users from client PCs. - Scheduled server clock synchronisation from an Internet time server. - Scheduled FTP updates to ISP hosted Web site.

For for the vast majority of small businesses that's about it so far as Internet connectivity is concerned.

Why connect?

It's fairly straight-forward to configure a FreeBSD/Linux PPP dialup connection, the problems start when multiple clients want to use the connection as a shared gateway. We need to ensure that the connection is only closed after all clients have finished.

Programs implementing on-demand dialing, such as diald, would seem to be an obvious solution. This technique relies on second guessing the users intentions from network activity, user sessions and connections are not explicitly controlled or monitored. In practise I have found on-demand dialing:

Difficult to configure, especially when it came to ensuring link activation only occurs when required.
Connection termination must be left to link inactivity timeouts.

Connect's approach is fundamentally different. Instead of autonomously controlling the underlying link (based a on knowledge of the links internal implementation), connect implements a client/server protocol that allows users and applications to explicitly manage remote or local network connections.

Connection Management Criteria

Users should be able to independently open and close the dialup connection without affecting other users.
Client applications controling the connection should be simple to use.
It should be possible to minimize phone line usage.

The last requirement is important when: - The line is also being used for voice or fax (as is often the case in home office environments). - Phone and ISP charges are often based on connect time.

The problem with relying on pppd idle timeout to close the connection is that it if it's to short users will be frustrated (10 minutes is reasonable), but if it's to long then regularly scheduled short lived connections such as Email delivery will generate a lot of unnecessary connect time.

The most common cause of the link being left open is that the user forgets to close the session. This problem has been alleviated by the Windows connect client which has an option to launch another application automatically once the link is opened (typically the Web browser), it is also able to detect when that application closes and close the connect session automatically (see 'Connect Windows Client').

Installation

IMPORTANT: Read the Connect README first.

The connect client and server is distributed as a single tarball file connect-0.6.0.tar.gz that contains source code, documentation and example scripts and configuration files.

For the latest version of connect go to the connect home page at http://www.methods.co.nz/connect/

The Windows GUI client comes in a separate tarball file named winconnect-0.5.0.4.tar.gz. Documentation and installation instructions for the Windows client can be found in the winconnect-guide document.

Compiling and Installing

IMPORTANT: Before going any further read the preceding README section
for details of the current state of connect and the platforms on which
it has been run.

Unpack the distribution tarball and execute the A-A-P Makefile
targets.

- Unpack the distribution tarball, for example:

  $ mv connect-0.6.0.tar.gz ~/tmp
  $ cd ~/tmp
  $ tar -xzf connect-0.6.0.tar.gz

- Compile connect client and server, for example:

  $ cd connect-0.6.0
  $ aap

- Install connect (you need root permission to do this), for example:

  $ su
  # aap install

Uninstalling Connect

To uninstall connect cd to the unpacked distribution directory and execute the uninstall A-A-P target (you need root permission to do this), for example:

$ cd connect-0.6.0
$ su
# aap uninstall

Installed Files

The installation adds the following files to your system (the exact
locations may vary depending on your operating system (see the
connect A-A-P main.aap makefile for installed locations):

connectd, connect::
        The connect server and client executables.

connect.1, connect.5, connectd.8::
        Man pages.

connectd (Redhat Linux)::
connectd.sh.sample (FreeBSD)::
        The connectd start/stop script.

/etc/connect/ (Linux)::
/usr/local/etc/ (FreeBSD)::
        connectd(8) configuration files directory which includes
        example configuration files and scripts.

/usr/local/doc/connect-0.6.0/ (Linux)::
/usr/local/share/doc/connect-0.6.0/ (FreeBSD)::
        Connect documentation and example configurations.

Configuration
-------------
Configuring Connect to Manage a PPP Link

The default install creates an empty /etc/connect/ configuration file directory, you will need to create a connect.links file in the /etc/connect/ along with any necessary chat or pppd options files.

As as starting point for dial-up PPP link configuration checkout the connect.links file and the associated chat and pppd options files (for the example internet and anet links) in the examples directory (/usr/local/doc/connect-0.6.0/examples/). These example PPP links use the /etc/connect/status-command and you will need to modify your /etc/ppp/ip-up and /etc/ppp/ip-down scripts as per examples in /usr/local/doc/connect-0.6.0/examples/.

See the connectd(8) Man Page section for detailed server configuration information, see also the examples source directory for examples of configuration files.

Start the server using the connectd initialisation script /etc/rc.d/init.d/connectd (not be confused with the connectd server /usr/local/sbin/connectd).

# /etc/rc.d/init.d/connectd start

To test the server is running execute the connect links command from the connect client:

$ /usr/local/bin/connect links

Now try to open the PPP link using the connect client open command:

$ /usr/local/bin/connect open

Check the system log file (usually /var/log/messages) if you experience problems.

pppd(8) Notes

If you're running an RPM based distribution such as Redhat you can check pppd is installed by running the command rpm -q ppp.
Usually you want the PPP link to be the default route (set by the defaultroute option in /etc/connect/connnect.options), in which case you should check there is no other default route using the route(8) command. Pppd will be unable to start using the defaultroute option if another default route exists.
pppd should be run with the nodetach option which ensures the pppd open_command does not exit till pppd is terminated by an external event such as a SIGINT or SIGTERM signal (from connectd), an unrecoverable link error or an idle timeout.

Managing Multiple PPP Links

When a physical link is opened it is assigned the next unused PPP interface name (ppp0,ppp1…). There is no way to statically assign interface names so if you have multiple links you cannot rely on the interface name to identify the physical link.

This can lead to problems if PPP interface names are hardwired into scripts: - If connectd(8) is being used to dial-up PPP connections you must use the status_command option as described below. - The ipfwadm command used in the /etc/rc.d/init.d/ipfw script has a -W option that specifies the network interface (see 'Firewalling Multiple PPP Links below).

Status Commands for Multiple PPP Links

The default status_command is not suitable for multiple PPP links because the PPP network interface name is choosen dynamically at connect time. But it's not difficult to implement an alternate mechanism that can handle multiple PPP links.

The technique is to create a file named like

/var/run/connect-<link_name>.link

when the link opens and then delete, it when the link closes. A status_command can then be implemented as a program that simply tests for the existence of the link file.

To do this we rely on two properties of pppd(8), namely:

pppd calls a program called /etc/ppp/ip-up when the link comes up and a program called /etc/ppp/ip-down when the link closes.
The pppd ipparam option argument is passed as a command parameter to /etc/ppp/ip-up.

See the pppd(8) man page for details.

Here are example shell commands that implement the above scheme (note: the following examples can be found in the connect /usr/local/doc/connect-0.6.0/examples/ directory):

Insert into /etc/ppp/ip-up (/etc/ppp/ip-up.local for Redhat):

# If pppd has been passed an ipparam option ($6) create a file.
[ "$6" != "" ] && /bin/echo $* > /var/run/connect-$6.link

Insert into /etc/ppp/ip-down (/etc/ppp/ip-down.local for Redhat):

# Delete connect link file created by /etc/ppp/ip-up
[ "$6" != "" ] && /bin/rm -f /var/run/connect-$6.link

A shell script to implement the connectd status_command is:

#!/bin/sh
# /etc/connect/status-command
# Exit code of zero if link status file exists.
[ -e /var/run/connect-$1.link ]

This script must be passed the connect link_name as the first argument ($1).

You also need to to set the pppd ipparams option. A convenient place is in the open_command parameter in the /etc/connect/connect.links file. The following example from a /etc/connect/connect.links file defines a link called isp (the important thing here is that the link_name, in this case isp, is the same in link_name, open_command and status_command parameters):

[isp]
link_behavior   = hold_open
open_command    = /usr/sbin/pppd nodetach ipparam isp file
/etc/connect/isp.options
status_command  = /etc/connect/status-command isp
leave_open      = true

NOTE: - The open_command in the above example is a single unbroken line. - Be sure that at the most one PPP link is set as the default link (make sure the defaultroute option is not in a shared /etc/connnect/connect.options file).

Finally, you need to ensure that any /var/run/connect-<link_name>.link files are deleted at boot time. Typically you will put the following lines in /etc/rc.d/rc.local:

# Clean up connectd link status files.
rm -f /var/run/connect-*.link

Firewalling Multiple PPP Links

As the same PPP interface can be used to access different networks with differing security requirements you will need to install and delete firewall rules dynamically when the connections open and close. This technique uses the /etc/ppp/ip-up and /etc/ppp/ip-down scripts to install and delete routing table entries and firewall rules.

The following (incomplete) script is called ipfw-updown and is called from both /etc/ppp/ip-up and /etc/ppp/ip-down scripts:

#!/bin/sh
# /etc/rc.d/init.d/ipfw-updown
#
# Installs and deletes firewall rules for PPP interfaces
# and installs IP routes.
#
# This script is customised with parameters of connecting networks.
#
# Called from /etc/ppp/ip-up and /etc/ppp/ip-down.
#
# Usage: ipfw-updown up|down $*
#
# The $* argument are the parameters passed to /etc/ppp/ip-up and
# /etc/ppp/ip-down.
#

# Utility library.
. /usr/local/sbin/shell-lib

LOG_FILE="/var/log/ppp-updown.log"

case "$1" in
up)
    ACTION="up"
    COMMAND="append"
    ;;
down)
    ACTION="down"
    COMMAND="delete"
    ;;
*)
    echo "Illegal action parameter"
    exit 1
    ;;
esac

# Set positional parameters to as they would be passed to /etc/ppp/ip-up,
# /etc/ppp/ip-down.
shift

# Customise the network address entries in the following case
# statement. Be sure that the remote addresses labeling the case
# clauses are unique.  Apart from the default case each network that
# is administered assigns a unique local IP address to the
# administered end.
case "$5" in
    192.168.1.251)
        # Connected to Net1.
        logMsg "Connection to Net1: $ACTION ($*)"

        # Insert commands to install route (if $ACTION="up").
        # Insert commands to install or remove firewall rules.

        ;;
    *)
        # Assume we're connected to the internet.
        logMsg "Connection to Internet $ACTION ($*)"

        # Insert commands to install route (if $ACTION="up").
        # Insert commands to install or remove firewall rules.

        ;;
esac