(c) 1997, 1998 The Meme Factory, Inc.  http://www.meme.com

Distributed under the GNU copyright.

April 2, 1997

Karl O. Pinc <kop@meme.com>

Release 0.1  Added comment about /etc/hosts & default ips.

CONTENTS
  INTRODUCTION
  FILES
    Configuring A New Interface
    File Descriptions
      High level configuration files (shell variable assignment syntax)
      User programs
      RedHat's high level (shell variable assginment syntax) 
               configuration files and scripts
      Low level configuration files (standard diald directive syntax)
      Other files
      System files
    Advanced Configuration
  TIPS
  RELEASE VERSIONS
  CONFIGURATION VARIABLE REFERENCE
    Variables defined in /etc/sysconfig/network-scripts/ifcfg-<iface>
    Variables That Should Be In The PPP Configuration
    Required Variables
      Configuration for diald
    Optional Variables
      Compatability
      Routing
      Diald monitoring
      link control settings
      Authentication
      Customization support
      Dialing section
      Other stuff
      Traffic control timeouts

INTRODUCTION

The purpose of this package is to make it easy to setup a system so
that it automatically connects to the net whenever needed and
disconnects when not needed.  Because "needed" is a relative term, to
meet this goal it must be easy to make changes to the system
configuration.  To that end, this package provides a configuration
system supporting diald, a "demand dialing daemon".

Configuring diald is easy using diald-config's high level
configuration files.  The high level files have a syntax which looks
like variable assignment in shell -- set a variable to change a
behavior.  Most users will want configure diald using only the high
level configuration files.  To handle exceptional cases, the diald
configuration directives (described in the diald man page) can also be
used.  These should be placed in the low level configuration files.

Please let me know of any problems.

The diald-config-unmetered and diald-config-metered are companion
packages which contain sample configurations that can be used "out of
the box" to configure diald for management of ppp0.

If you use this package, I'd like to hear from you.


FILES

  Configuring A New Interface

The diald-config-unmetered or diald-config-unmetered packages can be
used "out of the box" to manage ppp0.  If you use these packages you
can stop reading now and need only use the redhat ppp configuration
tool to configure ppp0 and you are set to go on ppp0.  To tweak the
configuration see the "Tips" and "Configuration Variable Reference"
below.  The values most people may wish to change are the "Traffic
Control Timeouts" -- how long to wait before hanging up the phone when
there's no network traffic.

Before diald can control any interface you must establish the default
settings for all interfaces by creating the file:

/etc/sysconfig/dialdcfg

You must create the following files for each interface controlled by
diald:

/etc/sysconfig/network-scripts/dialdcfg-<iface>
/etc/diald/diald-<iface>.conf
/etc/diald/chat-<iface>.fifo
/etc/diald/diald-<iface>.ctl
/etc/sysconfig/network-scripts/chat-<iface>
/etc/sysconfig/network-scripts/ifcfg-<iface>

The last two are created by the the redhat ppp configuration utility.

And optionally create both of:

/etc/sysconfig/network-scripts/chat-<iface>-<clone>
/etc/sysconfig/network-scripts/ifcfg-<iface>-<clone>

These two are also created by the redhat ppp configuration utility.

The remainder of this document should give you enough information to
create these files from scratch.  You may also find helpful some,
possibly old, sample configuration files for the common non-empty
configuration files you will need that are found in
"/usr/doc/diald-config-*/".  And, of course, the diald-config-metered
and diald-config-unmetered packages contain the configuration files
already set up to manage the ppp0 interface.

Routing must also be established for each interface managed by diald.
When there's only one interface and that's used to connect to the
internet, routing is easy.  Just check the box in the redhat ppp
control panel (or set the DEFROUTE variable in one of the high level
configuration files -- see below) to configure so that the interface
has the default route.  The method used to establish routes for the
non-default-route interface is configurable.  The suggested method is
to create routes to diald's proxy slip interface and the corresponding
ppp interface with the redhat network control panel.  diald requires
two routes be created for each interface, one for the interface itself
and one for the corresponding proxy slip interface which diald uses
internally.  Setting the ADDROUTE variable to the redhat route
establishment script will cause the route to the slip interface to be
established when diald is brought up for the interface, and redhat's
script that brings up ppp will also establish the route to the ppp
interface.  Unfortunately, the redhat control panel does not allow the
maintenance of route metrics so a ppp ip-up.local script should be
used to raise the metric of the route to the proxy interface so that
packets with go straight through the ppp interface once it is
established.  A ppp ip-down script should do the reverse.  You may
also wish to gateway the proxy slip interface through the ppp
interface so that if it is a tcp socket which triggered diald's
establishment of the ppp interface the socket will open successfully,
although packets routed through this socket will impose additional
overhead.

  File Descriptions

High level configuration files (shell variable assignment syntax):

/etc/sysconfig/dialdcfg 
Default diald configuration file.  Any changes to this file apply to
all diald daemons.

/etc/sysconfig/network-scripts/dialdcfg-<iface> 
Configuration file for a specific interface.  There must be a
/etc/sysconfig/network-scripts/dialdcfg-<iface> for every interface
who's establishment is controlled by diald.  This file may contain any
or all of the variables allowed in /etc/sysconfig/dialdcfg, and vice
versa.  The interface specific variable values override the default
values.

User programs:

/usr/local/bin/start-dctrl
Use this to start the diald monitor, dctrl.  By default, this will
start a dctrl program for each configured diald daemon.  Interfaces
may be passed as arguments to start separate dctrl processes for
specific diald daemons.

Note that dctrl (use start-dctrl) must be started independently of
diald with links in /etc/rc.d/rc*.d/, if you always want it up.  dctrl
should be started after diald, and stopped before diald.  (Seems that
way with diald v 0.16 anyhow.)

RedHat's high level (shell variable assignment syntax) configuration
files and scripts (you don't need to know these details if you're
using the redhat config tools):

/etc/sysconfig/network-scripts/chat-<iface>
Interface configuration files (for ppp interfaces in particular)
established by the redhat configuration toolkit.  It is a chat script
that takes the interface from it's down state (usually phone hung up,
etc.) to a state where the remote end of the link has started running
the ppp protocol.

/etc/sysconfig/network-scripts/ifcfg-<iface>
Interface configuration files (for ppp interfaces in particular)
established by the redhat configuration toolkit.  A shell script that
assigns values to the high level, per interface, configuration
variables used by both the redhat ppp connection scripts and this
package's.  So, it contains variables used to configure specific ppp
interfaces.

/etc/sysconfig/network-scripts/chat-<iface>-<clone>
/etc/sysconfig/network-scripts/ifcfg-<iface>-<clone>
These correspond directly to the same files without the "-<clone>" and
may contain all the same variables.  To quote Michael K. Johnson
<johnsonm@redhat.com> "Clone devices are alternative configurations
for the same device.  A Clone devices inherits the settings of the
parent device except where they differ."  The clone chat script must
be a complete chat script.  No further mention will be made of clone
devices, except for how to set one as a diald device, because they are
just like regular devices.

/etc/sysconfig/network-scripts/network-functions
Optional file.  Part of the RedHat network interface management
system.  If it doesn't exist then clone devices won't work.  If it
does exist it should: be a shell script file that can be source-d by
the diald system programs; should define a function named
source_config which takes no arguments.  Executing source_config
should: reference a variable -- CONFIG -- to contain the full name of
the file in /etc/sysconfig/network-scripts/ which holds the name of
the per interface configuration -- "ifcfg-<iface>" or
"ifcfg-<iface>-<clone>"; source the ifcfg-<iface> and
ifcfg-<iface>-<clone> files (as appropriate).  *whew*

/etc/sysconfig/network-scripts/ifup-routes
/etc/sysconfig/network-scripts/static-routes
Script and configuration file maintained by the redhat network
configuration utilities to establish routes to interfaces.
ifup-routes is the suggested script to use to bring up routes to the
interfaces managed by diald.

Low level configuration files (standard diald directive syntax):

/usr/lib/diald/diald.defs
Default protocol rules and variable definitions applicable to all
diald daemons, straight from the diald distribution.  See the diald
man page.

/etc/diald.conf
Default diald configuration file.  Any changes to this configuration
file apply to all diald daemons.

/etc/diald/diald-<iface>.conf
Configuration file specific to a particular interface's diald daemon.

/etc/diald/diald.conf.m4
m4 file to generate custom diald configuration directives which apply
to all diald daemons.  If this file exists, it is processed by m4 and
included in the diald directives.  All the variables given values in
the section titled "Traffic Control Timeouts" below, as well as the
STARTUP_TIMEOUT variable, are defined m4 macros and may be used in the
file.

/etc/diald/diald-<iface>.conf.m4
m4 file to generate custom diald configuration directives specific to
a particular interface's diald daemon.  If this file exists, it is
processed by m4 and included in the diald directives.  All the
variables given values in the section titled "Traffic Control
Timeouts" below, as well as the STARTUP_TIMEOUT variable, are defined
m4 macros and may be used in the file.


Other files:

/usr/lib/diald/standard.filter
Part of the standard diald distribution.  Not used.

/var/lock/LCK..*  
See the diald man page.

/var/run/diald-<iface>.pid
Logging of the process ids of running diald daemons.  One for each
interface's daemon.

/etc/diald/chat-<iface>.fifo
/etc/diald/diald-<iface>.ctl
These files are named pipes.  In order to control a diald daemon
managing an interface with dctrl a user requires read access to
/etc/diald/chat-<iface>.fifo and read and write access to
/etc/diald/diald-<iface>.ctl for that interface.  The names and
locations of these fifos is configurable.

System Files:

/etc/rc.d/init.d/diald
/etc/sysconfig/network-scripts/diald-up
/etc/sysconfig/network-scripts/diald-down
/etc/sysconfig/network-scripts/diald-connect
The programs that run the system.

/usr/local/lib/diald/standard.filter.m4
Used to generate diald configuration directives from the high level
diald configuration files.

/tmp/diald-<iface>.conf
/tmp/diald-<iface>.filter
/tmp/diald-<iface>.connect
Temporary files used to hold the diald configuration directives
generated from the high level configuration.


  Advanced Configuration

To customize your configuration with low level diald configuration
directives, you need to know the order in which the configuration
files are processed by diald.

Diald configuration directives are processed by the diald daemons in
this order:

/usr/lib/diald/diald.defs

/etc/diald.conf

Directives generated by /etc/diald/diald.conf.m4.

Directives generated from /etc/sysconfig/dialdcfg and
/etc/sysconfig/dialdcfg-<iface> files, except for the default timeouts
(OTHER_UDP_TIMEOUT, OTHER_TCP_TIMEOUT, DEFAULT_TIMEOUT) that catch
any packets not caught by any other rules.

Directives generated by /etc/diald/diald-<iface>.conf.m4.

/etc/diald/diald-<iface>.conf

Default timeout directives generated from /etc/sysconfig/dialdcfg and
/etc/sysconfig/dialdcfg-<iface> files (OTHER_UDP_TIMEOUT,
OTHER_TCP_TIMEOUT, DEFAULT_TIMEOUT) that catch any packets not
caught by any other rules.


TIPS

You will get better performance over a phone line if you run a caching
nameserver.  (But see the BUGS file regarding the failure to open the
first tcp socket.)

It helps to be able to resolve locally the names of the IP numbers you
use for the local and remote ends of the link, at least the IP numbers
that are not dynamically assigned by your ISP.  So, either add them to
your nameserver configuration, or add them to /etc/hosts.

Your hosts fully qualified domain name (FQDN), and just the hostname
part, should be able to be resolved locally.  If this is not the case,
then just starting programs like sendmail or emacs can cause diald to
try to connect to the net in an attempt to associate an IP number with
your machine's hostname.  The solution is to run a nameserver locally,
or define your hostname/FQDN in /etc/hosts -- if nothing else they can
be defined as aliases of localhost by adding these names to the back
of the line that defines localhost.

As an alternate method for duplicating the original diald
distribution, use the diald configuration directives distributed in
the diald package.  Do not define any network traffic related
variables in the high level configuration files.  Instead, place the
directive "include /usr/lib/diald/standard.filter" at the end of
/etc/diald.conf.

To generate a complete custom diald configuration using diald
configuration directives, do not define any network traffic related
variables in the high level configuration files.  Instead, place your
diald config directives in the /etc/diald.conf and/or
/etc/diald/diald-<iface>.conf files.

You may wish to add dctrl to the Start menu of fvwm95.  To do this on
an out-of-the-box Redhat (4.0) system, edit
"/etc/X11/TheNextLevel/.fvwm2rc.programs" and have the menu item run
/usr/local/bin/start-dctrl.

RELEASE VERSIONS

Release numbers are structured as follows:
<major>.<minor>.<bug>

A release is a major release if it introduces very significant new
functionality.  A major release may not be compatible with prior
releases.

Minor releases introduce new functionalty.  They will be compatible
with prior releases.

A bug release introduces no new functionalty.  Bug fixes and/or
documentation upgrades.

This release system starts with version 1.2.1, prior versions are:

0.0 Initial alpha release
0.1 Bug fixes
1.0 Major release -- not entirely upwardly compatable.
1.1 Minor release & bug fixes
1.2 Bug fixes

-------------------------------------------------------------
CONFIGURATION VARIABLE REFERENCE

All the variables used to configure diald, and which files they
come from.

Variables either contain the appropriate values, or "yes" or "no".
(The code only ever tests for "yes".)  Typical values are listed here.

Note that the standard chat script,
/etc/sysconfig/network-scripts/chat-<iface>, for the interface is
used.  This document does not include the variables used by that
script.

# These values are good for a personal machine on a U.S. residential
# phone line.  YMMV


  Variables defined in /etc/sysconfig/network-scripts/ifcfg-<iface>

These are maintained by the redhat network control panel.

# Use the ppp connection as the default route.
DEFROUTE=yes

# Which serial line is connected to the modem?  (required)
# Note, this should be a "ttyS<n>" device when using mgetty.
# Further, _every_ program should use the same path to the device
# so if you use /dev/modem, check that /etc/inittab getty entries
# for the port also use /dev/modem.  (Rtfm for mgetty.)
MODEMPORT=/dev/modem

# Speed of the serial line connected to the modem.  (required)
# See man setserial for why 38400 isn't.
LINESPEED=38400

# Whether or not to escape control characters on the link.
# Note that the current (Redhat 4.0) /etc/sysconfig/network-scripts/ifup-ppp
# script does the opposite of what it should.
ESCAPECHARS=no

# The modem is configured and wired to use hardware flow control.
HARDFLOWCTL=yes

# IP number the remote end of the ppp link _must_ use.
REMIP=

# IP number the local end of the ppp link _must_ use.
IPADDR=

# IP MRU to use on the link.
MRU=

# Name of the local system to use to for PAP authentication.
PAPNAME=

# Have pppd log control packets.  (See pppd debug option.)
DEBUG=

  Configuration maintained in /etc/sysconfig/dialdcfg and/or
     /etc/sysconfig/network-scripts/dialdcfg-<iface>

Variables That Should Be In The PPP Configuration:

Must be maintained by hand at present.

# Kill ppp link if no lcp response from the other end (ppp startup fails.)
# These are optional, but recommended.
# How many checks can fail before we give up?
LCP_ECHO_FAILURE=3
# How often should we check?
LCP_ECHO_INTERVAL=7

# The local ppp daemon will not supply any ip numbers for the link.
# Turning this on, you've no control over the ip's used for ppp.
# If you can't seem to get a ppp link to work, try adding "debug" to
# /etc/pppoptions, and  have /etc/syslog.conf route daemon.debug messages
# somewhere.  If the messages show failure after the local end starts
# IPCP, then try turning this on.
# NOIPDEFAULT=yes


Required Variables:

# Configuration for diald

ADDROUTE, START_STATE, LINK_DOWN_IPADDR, LINK_DOWN_REMIP, FIFO,
CHAT_FIFO, and CLONE are typically found in the interface specific
config file.

# As soon as diald starts, tell it to:    ;# required
#   Note: The dctrl program's control menu does not reflect the use
#   these flags
# Bring the link up and keep it that way until told to unforce.
# START_STATE="up"
# Bring the link down and keep it that way until told to unblock.
# START_STATE="down"
# Start with the link down and bring it up and down as needed.
START_STATE="demand"

You may find it convenient to add LINK_DOWN_IPADDR and LINK_DOWN_REMIP
to /etc/hosts and set /etc/host.conf to "order hosts,bind" so that you
don't get long delays when attempting to come up with names for these
ips.

# Local ip number used (and required) when IPADDR is not defined.  1)
# used when the link is down, 2) suggested to be used when the link is
# up subject to the restrictions of NOIPDEFAULT.
LINK_DOWN_IPADDR=192.168.0.1

# Remote ip number used (and required) when REMIP is not defined. 1)
# used when the link is down, 2) suggested to be used when the link is
# up subject to the restrictions of NOIPDEFAULT.
LINK_DOWN_REMIP=192.168.0.2


Optional Variables:

#
# Compatibility.
#

# The configuration program used to generate some of these config files.
# Unless configured otherwise, make diald work like the ppp system
# we're replacing.
#
# Legal values are:
# REDHAT  For the RedHat ppp network configuration utility.
# the empty string (or undefined)  For no particular GUI config utility.
CONFPROG="REDHAT"

# Version of the configuration program.
# With Redhat this is the redhat distribution release number.
CONFPROGVER="4.2"

# Name of the RedHat "clone" device to be used with diald.
# "home" would be the proper clone name to use the RedHat
# ifcfg-<iface>-home clone.  Undefined or empty for the usual
# case, no clone.
# CLONE=

#
# Routing
#
# See also DEFROUTE.

# Executable which diald runs to bring routes up for the interface.
# This should probably not be used together with DEFROUTE.  See the
# diald documentation for the "addroute" configuration directive for
# more information on the executable and when it is run.
# ADDROUTE=/etc/sysconfig/network-scripts/ifup-routes

#
# Diald monitoring
#

# FIFO and CHAT_FIFO are required if dctrl is used & for "up" & "down"
# values of START_STATE & for MON_CONNECT=yes

# Path to the fifo used with dctrl or other control mechanism.
FIFO=/etc/diald/diald-<iface>.ctl

# Path to the fifo through which chat's log messages are passed to dctrl.
CHAT_FIFO=/etc/diald/chat-<iface>.fifo

# Animate the dctrl icon (when the window is iconified.)
ANIMATE_DCTRL=

# Start dctrl as an icon.
ICONIFY_DCTRL=

# Start dctrl with dialing log displayed.
DLOG_DCTRL=yes

# Start dctrl with packet queue displayed.
PQUEUE_DCTRL=

# Start dctrl with alarm timeouts and numeric load detail displayed.
TLOAD_DCTRL=

# Start dctrl with graphical load monitor displayed.
GLOAD_DCTRL=

# Send log messages regarding the connect script to the FIFO.
# (Usually dctrl, which displays them in it's dialing log.)
MON_CONNECT=yes

# Log exchange used to connect.
# Note that if this is on, the password will be logged unless it is
# prefixed in the chat script with "\q", which is _not_ done automatically
# by the Redhat (4.0) network control panel.
VERBOSE_LOGGING="yes"

#
# link control settings
#

See LCP_ECHO_FAILURE & LCP_ECHO_INTERVAL settings above.

LCP_ECHO_FAILURE & LCP_ECHO_INTERVAL are preferred over
STARTUP_TIMEOUT.  If the link stays up and you can send data when
LCP_ECHO_FAILURE and LCP_ECHO_INTERVAL are not defined, but when they
are defined the link will not go up/stay up, then the ppp
implementation on the remote end is not properly responding to lcp
packets and you should try defining STARTUP_TIMEOUT.  STARTUP_TIMEOUT
will not detect remote ppp failure or line down, but will at least
detect that the link has not come up.

# Force diald retry on failed ppp establishment.  (When lcp is not used to
# detect dead link bring the line down.)
# Should be set longer on slow networks.
#STARTUP_TIMEOUT=15

#
# Authentication
#

# Username to use when checking to see that remote end is who they say
# they are.  (See pppd remotename option.)  When Redhat compatible, empty
# picks up the value Redhat uses.
# REMOTENAME=

#
# Customization support.
#

# Extra parameters to pass to scripts ppp calls when link goes up/down.
# (See pppd ipparam option and other doc.)  When Redhat compatible,
# empty picks up the value Redhat uses.
# IPPARAM=

#
# Dialing section.
#
# These correspond directly to diald options.
#

See START_STATE above.

# How many times should I try to dial the phone?
# DIAL_FAIL_LIMIT=

# How long should I wait between dialing tries?
REDIAL_TIMEOUT=1

# Delay between dialing attempts when no free modem is available, in 
# seconds.
# NODEV_RETRY_TIMEOUT=1

# Maximum dial attempts on initial connection.
# RETRY_COUNT=0

# Connection failures allowed before doubling delay between dial attempts.
# REDIAL_BACKOFF_START=

# Maximum delay between failed calls, in seconds.
# REDIAL_BACKOFF_LIMIT=600

#
# Other stuff.
#

# Throw away packets older that this that are sitting waiting to be sent.
BUFFER_TIMEOUT=600

#
# Traffic control timeouts
#
# Each of these variables that is given a value is defined as a m4 macro
# and may be used in site specific m4 macro files to generate diald
# configuration directives.  Variables assigned no value are not
# defined as macros.
#


# Keep "typical network maintenance traffic" from controlling the link.
STANDARD_IGNORES="yes"

# Default for http, nntp, and ftp traffic
WEB_BROWSING_TIMEOUT=1800  ;# 30 minutes 

# ftp traffic, if not defined, WEB_BROWSING_TIMEOUT will be used
# FTP_TIMEOUT=1800      ;# 30 minutes 

# http (web) traffic, if not defined, WEB_BROWSING_TIMEOUT will be used
# HTTP_TIMEOUT=1800     ;# 30 minutes

# nntp (news) traffic, if not defined, WEB_BROWSING_TIMEOUT will be used
# NNTP_TIMEOUT=1800     ;# 30 minutes

# Mail timeouts should correspond to the timeouts in the applications
# that get/send mail, plus a little slack as experience dictates.
#
# imap and pop-2 and pop-3 traffic
# FETCH_MAIL_TIMEOUT=240          ;#  4 minutes 
#
# smtp traffic
# SEND_MAIL_TIMEOUT=240          ;#  4 minutes 

# domain name services.
# As this is what usually brings the link up, it must be longer than the
# time taken to start the link and get the first dns reply!  (At least with
# those resolvers/configurations where no more packets will be sent until the
# dns reply comes back.)  I believe that the standard resolver timeout is
# 30 seconds, so, in absence of other traffic, 
# when nameservices requests the net, just when diald
# is about to give up and hang up the phone, the resolver sends out another
# packet if it wants to try again.  What a co-inky-dink!
DOMAIN_TIMEOUT=30  ;# in seconds, standard value from diald distribution

# Ugly microsoft netbios name services.
NETBIOS_NS_TIMEOUT=

# Drop the connection quickly when tcp sessions finish.
# Overrides timeouts for all tcp connections but http.
# QUICK_DROP=yes

# Do not bring link up or keep link up for dns requests.  
# The only time I can imagine you want this option is a) to emulate
# the configuration distributed with diald, or b) when you are
# supplying a dialup site with internet access and that site is acting
# as a primary nameserver for which you are a secondary.
# IGNORE_NAMESERVER=yes

# Generic defaults
OTHER_TCP_TIMEOUT=600     ;# 10 minutes 
OTHER_UDP_TIMEOUT=120     ;#  2 minutes 

# How long should the link remain idle before we hang up the phone?
# Catches any packets for which there are no other timeouts defined.
DEFAULT_TIMEOUT=30	;# In seconds.
