Last Change: 2018-09-07, 16:50
powered by manpag.es
diald − demand dialing daemon for IP links over phone lines
/usr/sbin/diald [device1 ...] [options...] [-- [pppd options...]]
External IP network connections that go over phone lines, either via SLIP or PPP on a serial modem, or via PPP on an ISDN line, are normally explicitly turned on or off by operator intervention. Diald can be used to automatically bring a link up when there are Internet packets to be sent to another site, and to close the link down when it is idle.
Diald operates by starting a SLIP link on a pseudo tty and setting up a route to the resulting interface. This interface is called the proxy. Diald monitors the proxy to determine when to bring up a real communications link. When a real link is up diald routes packets from the proxy to the real link and monitors the real link to decide if it needs to be shut down. As well, if the link goes down unexpectedly diald will attempt to reestablish the link. The rules for controlling these operations are extensively configurable in run time startup files.
This manual page is the reference manual for diald. It documents all of the configuration options that diald can be given. Reading this manual page may not be the easiest way to get started with diald. The diald-examples manual page provides a serials of worked configuration examples to help you get started using diald. The dctrl manual page should be consulted for a program that will help you control a running copy of diald using a graphical interface. In addition the diald-control and diald-monitor manual pages should be consulted for details of the commands that dctrl can send to diald, and the data that diald can return to dctrl.
Diald is normally configured by the use of configuration files. For historical reasons almost everything that can be placed into a configuration file can appear on the command line. However, with the exception of passing diald an option to tell it which file to load its configuration from, passing arguments on the command line is never necessary. The use of command line arguments is depreciated.
On startup diald reads options first from /usr/lib/diald/diald.defs, then from /etc/diald.conf and then from the command line. Additional files to be read may be specified on the command line, or within the options files themselves. The initial portion of the command line is a list of zero or more serial devices. Note that diald supports the use of ISDN devices that appear as Ethernet devices, but these cannot be specified in this initial portion of the command line. This feature is strictly for backward compatibility with existing installations. It is preferable to specify devices using the "device" option, documented in the configuration section of this manual.
The first argument to the command line that is not a serial device marks the start of a sequence of 0 or more diald configuration options. All of the diald configuration options documented below, except the "pppd-options" option, can appear on the command line. Each of these options takes a fixed number of arguments, which must immediately follow the option on the command line. For example, the "-f" command takes a single argument that is a file name. On the command line this might appear as:
diald -f /etc/diald/config.18
This command line tells diald to get additional configuration options from the file /etc/diald/config.18. In fact, this is the only configuration option that ever need appear on the command line. Furthermore, unless you are running multiple diald processes, diald can be run without any command line arguments. This is done by placing the configuration options into the file /etc/diald.conf, which is always read by diald.
Any options after a "--" are options for pppd and are passed on to pppd whenever it is executed by diald. These options can also be placed into the /etc/ppp/options file or specified in a configuration file using the "pppd-options" command. If you make use of this ability you should read the important warning note in the section below that documents the "pppd-options" command.
As mentioned before, on startup diald reads options first from /usr/lib/diald/diald.defs, then from /etc/diald.conf and then from the command line. Additional files to be read may be specified on the command line, or within the options files themselves.
Note that the file /usr/lib/diald/diald.defs is intended to contain only var and prule options. This is not enforced, but it should never be necessary to violate this convention. Furthermore, in all but the most extreme cases the distributed diald.defs file will not need to be changed. In fact, changing the rules specified in this file changes the language recognized by diald in later configuration files. The need to do this should be carefully considered before proceeding.
Within configuration files commands must appear one to a line. Each line is parsed into a series of words delimited by whitespace (space and tab characters). Words can be quoted with (") or (’) to include whitespace in them. Within a quoted word the sequences (\") and (\’) can be used to enter a (") or (’) character. Other escape sequences are interpreted as in the language C. Blank lines are ignored, as are lines where the first non whitespace character is the (#) character.
General Configuration
The following commands control the general behavior of diald. This includes the files it reads its configuration options from, the path names to important files or programs, and a few other commands that are less easily categorized.
|
-f <f> |
Read the file <f> for additional commands. |
-file <f>
This is a synonym for the -f command.
include <f>
This is another synonym for the -f command. Note that these commands can be used within a file to include another file.
linkname <name>
Specifies a name to be used for this link.
linkdesc <description>
Specifies a description to be used for this link. The description will be sent to monitors that connect as an aid in identifying the link in question.
authsimple <file>
Specifies the name of a file to be used for simple authentication (very simple...) for TCP monitor connections.
authpam <file>
Specifies the name of a file to be used for PAM authentication (not so simple...) for TCP monitor connections.
scheduler <class>
Set diald’s scheduling class. Valid choices for systems that support POSIX scheduling classes are:
fifo Real time, first come, first served.
rr Real time, round robin
other Normal process scheduling
For systems that do not support POSIX scheduling classes the only valid option is other.
If the scheduler option is used the priority option is usually used as well.
Because diald needs to snoop the traffic on the managed link and distribute information to any monitors in a timely fashion it is often useful to run diald with a higher priority, perhaps even in one of the real time scheduling classes. This is especially true when the managed link is running at ISDN speeds or faster.
priority <n>
Set the scheduling priority to <n>. The meaning of the value depends on the chosen scheduling class. For the scheduling class other the value is the absolute nice value to use (as compared to the nice(1) command which specifies an increment to the current nice value). Nice values lie in the range -20 (highest priority) to 19 (lowest priority). For the real time scheduling classes the value is the static priority, the range of which should be determined from system documentation such as sched_setscheduler(2).
mode <m>
Set the operation mode to <m>. Valid choices are:
slip SLIP mode.
cslip Compressed SLIP mode.
slip6 6 BIT SLIP mode.
cslip6 Compressed 6 bit SLIP mode.
aslip Adaptive SLIP mode.
ppp PPP mode.
dev Ethernet device mode.
All but the last of these modes operate over a serial device. The last mode is for use with ISDN adaptors that appear to be Ethernet devices. These adaptors will dial out on demand, but do so for all packets without and policy decisions being made. This option mode allows diald to act as a front end for these devices and provide a more sophisticated control mechanism.
The directory "contrib/isdn4linux" in the diald distribution should be consulted for example configuration files that use this mode. Note that most of the modem control configuration options do not make sense in this mode, and are simply ignored.
|
-m <m> |
This is a synonym for the mode command. |
keepalive <t>
This option tells diald to set the SLIP keepalive timer to <t> seconds. This will only work if your kernel has been compiled with the SLIP keepalive option enabled. With this option turned on the kernel will hang up any SLIP line that does not see a packet arrive within <t> seconds. If the remote slip can do outfilling, then this can be used to test for lines that are having hardware problems. Alternatively, if you can arrange that whenever you are connected the remote side will regularly try to send packets, you can get the same effect. One way to do this is to configure diald to ignore ping packets and send ping packets to your gateway machine once a second. If it stops responding the keepalive option will cause a hangup after <t> seconds. Note that <t> must be in the range 0-255.
outfill <t>
This option tells diald to set the SLIP outfill timer to <t> seconds. This will only work if your kernel has been compiled with the SLIP outfill option enabled. With this option turned on the kernel will send an empty SLIP packet every <t> seconds if no other traffic has been sent within <t> seconds. This can be used in conjunction with the keepalive option to have both ends of a SLIP connection test to be sure that the link is still active, even if there is currently no IP traffic.
accounting-log <f>
Name the file that diald should append accounting information to. This command allows diald to log connection start and end times and the amount of data transferred during each connection. This is intended to be used to aid company accounting departments track phone usage. Note that <t> must be in the range 0-255.
pidfile <f>
Changes the name of the file that diald uses to store its own PID from diald.pid to the given file. This file is normally put into the directory /var/run, although on some systems it will be found in /etc.
fifo <f>
Turns on the FIFO command channel. Diald will attempt to open a named pipe with the pathname <f>. External programs can write commands to the pipe and diald will react. See the section on signals and FIFO commands below for the commands that can be issued to a running diald. If the named pipe already exists diald will simply attempt to open it. If it does not exist it will be created. Diald will create it as owned by the user running diald (usually root) and with permission modes "0600". Note that it is generally a bad idea to allow too many users access to the control FIFO for diald. Also, the best security is probably obtained by creating the FIFO’s ahead of time and choosing appropriate owners and permissions rather than letting diald create them.
tcpport <port>
Turns on the TCP command channel. Diald will listen on the given port. Remote systems may connect to the port in order to issue commands to the running diald and monitor its state.
If diald has been compiled with tcp wrappers support connections are accepted or rejected on the TCP port under control of rules for diald in /etc/hosts.allow and /etc/hosts.deny. If diald has not been compiled with tcp wrappers support cconnections are accepted from anybody unless blocked by external firewalling.
It is not wise to use a tcpport option unless you are certain that unauthorized users will not be able to access it. In particular you almost certainly do not want the port to be publically accessible via the link that diald is controlling!
blocked
Start diald in blocked mode. While the link is blocked diald will accept incoming connections but will not attempt to make an outgoing call either on demand or manually requested.
-blocked
Start diald in unblocked mode. Outgoing calls will be attempted when necessary. This is the default.
|
demand |
Start diald in demand mode. Outgoing calls will be made as necessary in order to send packets through the link. This is the default. |
-demand
Start diald in manual mode. Outgoing calls will not be made whenever packets wish to cross it but will be made in response to manual requests using "up".
debug <mask>
Set the debugging mask. The mask is the binary OR of the following hex value flags:
0x0001 FILTER_MATCH
0x0004 PROXYARP
0x0008 VERBOSE
0x0010 STATE_CONTROL
0x0020 TICK
0x0040 CONNECTION_QUEUE
The FILTER_MATCH flag tells diald to dump information showing which packets are matched by which filtering rule. The PROXYARP flag tells diald to dump information on the proxyarp setup. The VERBOSE flag tells diald to dump details on various normal operations. The STATE_CONTROL flag tells diald to output changes in the finite state control for the link status. The TICK flag tells diald to dump a heartbeat message every second. The CONNECTION_QUEUE flag tells diald to dump information detailing every change to the connection queue. A value of 0 turns off debugging output. Debugging is off by default.
-daemon
Don’t run in daemon mode. This means that the the standard input, standard output, and standard error output are not closed, that all messages are logged to the standard error as well as the syslog facility, and that the diald program does not fork itself into the background. This is mostly useful when you are running the debugging mode and you want to see what is happening.
pppd-options <arg1> ...
When diald is being used in PPP mode extra commands can be passed on to pppd by specifying them after a pppd-options command, or after "--" on the command line. This should not normally be necessary as default commands can be placed into the /etc/ppp/options file. But, if you need to run multiple instances of diald with different pppd options, then you will have to make use of this ability. WARNING: Note that some pppd commands should not be specified, not even in the /etc/ppp/options file, because they will interfere with the proper operation of diald. In particular you should not specify the tty device, the baud rate, nor any of the options crtscts, xonxoff, -crtscts, defaultroute, lock, netmask, -detach, modem, local, mtu and proxyarp. Use the equivalent diald commands to control these pppd settings.
lock-prefix <path>
Set the pathname prefix to use for modem device lock files. By default this is "/var/lock/LCK..".
pidstring
Write lock files as an ASCII string representing the process identifier of the locking program. This is the default.
-pidstring
Write lock files in binary format.
run-prefix <path>
Set the directory where diald writes out its PID file. By default this is "/var/run".
path-ip <path>
Set the path to the ip command. There is no default for this as this command may not be installed on all systems yet. If this is specified diald will use ip in preference to the route command.
path-route <path>
Set the path to the route command. By default this is "/sbin/route". Diald must have the correct setting for this path in order to function.
path-ifconfig <path>
Set the path to the ifconfig command. By default this is "/sbin/ifconfig". Diald must have the correct setting for this path in order to function.
path-pppd <path>
Set the path to the pppd command. By default this is "/usr/sbin/pppd". Diald must have the correct setting for this path in order to function in PPP mode.
path-bootpc <path>
Set the path to the bootpc command. By default this is "/usr/sbin/bootpc". Diald must have the correct setting for this path in order to use the "bootp" setting for the "dslip-mode" option.
buffer-packets
Tells diald to buffer packets while waiting for a link to come up. This is the default.
-buffer-packets
Tells diald not to buffer packets while waiting for a link to come up.
buffer_size <n>
Sets the size of the buffer for saving packets while waiting for a link to come up. This defaults to 65536 bytes.
buffer-fifo-dispose
Tells diald to dispose of packets in a first in first out order if it runs out of room on the packet buffer while waiting for a link to come up. This is the default.
-buffer-fifo-dispose
Tells diald not to dispose of old packets when the buffer becomes full. I can’t imagine why you would want to do this, but I’ve put the option in here anyway.
buffer-timeout <n>
Set the timeout for throwing away packets in the buffer. This defaults to 600 seconds (10 minutes). This is a good idea, since you don’t want packets that are a few hours old to get sent out when diald comes up for some other reason.
Device Configuration
The commands in the following section control the device(s) that diald uses for the external IP link.
device <f>
Add the device <f> to the list of devices that can be used for the outgoing connection. For SLIP and PPP modes these should be serial devices. For the "dev" mode this should be the name of an Ethernet device.
If you specify more than one device then when attempting to establish an outside connection diald will try each device in turn until it finds one that is not locked. It will then attempt to dial out on that device. If it fails to dial out it will relinquish its lock and go through the device list again the next time it tries to establish the connection.
rotate-devices
In normal operation diald attempts to open each of the possible devices listed on its command line in the order they are given. If the first device on this fails in such a way that it can still be opened, but it will not be able to connect (e.g. someone tripped over the modem cable), then diald will not be able to make a connection until the problem is corrected. This command forces diald to rotate the list of devices each time a device is opened. Thus, in the above scenario diald would fail to make the connection on the damaged device, but would then try the second device first on the next attempt.
initializer <p>
Use the executable or shell script <p> to perform once only initialization of this link when diald first starts up or when it reloads its configuration. This may be used, for instance, to set up an ISDN interface ready to accept incoming connections.
deinitializer <p>
Use the executable or shell script <p> to clean up this link before diald exits or before reloading the configuration. This may be used, for instance, to delete an ISDN interface when we have finished managing it.
connect <p>
Use the executable or shell script <p> to set up the serial line. This normally dials the modem, starts up the remote SLIP or PPP session. It should not start SLIP or PPP locally - diald will do this itself once the connect script returns a success (zero) exit status. The command <p> is started with the standard output and input directed at the modem device. In addition the environment variables MODEM and FIFO are set. The MODEM environment variable will contain the name of the device. This is useful in those cases where the script might have to behave differently depending on the device it is operating. The FIFO environment variable will contain the name of the command fifo used by diald. This allows connect scripts to pass information back to diald over the command fifo. Note that the FIFO environment variable will not be set if diald is not configured to use a command fifo.
The chat program that comes with pppd is generally used to perform the task of the connect script. For purposes where chat is insufficient, an sh, csh, perl or expect script might meet your needs. This command is not optional unless the mode option is set to "dev", in which case any connect option will be ignored.
disconnect <p>
Use the executable or shell script <p> to shut down serial line. This could be used to hang up the modem on systems that don’t do hardware hang-ups. As with the connect script, the script is run with the standard input and output redirected to the modem, and the environment variable MODEM set to the name of the device that the script is connected to.
|
lock |
Perform UUCP style locking of the serial line. |
speed <baud-rate>
Set the baud rate to use on the serial line. The default value is 38400.
|
modem |
Treat the serial device as a modem. This command will also be passed on to pppd in PPP mode. |
crtscts
Use the hardware flow control lines (RTS and CTS) to control the serial line. This command will also be passed on to pppd in PPP mode. You almost certainly want to use this command.
Network Configuration
The following commands specify how diald should configure its network interfaces and what entries it places into the routing table.
local <a>
Sets the local IP address for the link established by diald. If you are not using the dynamic option then this address must match the local IP address assigned to you by your provider.
remote <a>
Sets the remote IP address for the link established by diald. If you are not using the dynamic option then this address should match the remote IP address of your provider. (Note that due to the nature of IP routing this is not actually necessary, but your routing tables will appear confusing to you if the addresses don’t match).
dynamic
Dynamically change the local and remote IP addresses to match those obtained when an actual connection (either SLIP or PPP) is made. Note that in dynamic mode initial local and remote IP addresses must still be specified, but it is not necessary that either address be correct. Normally this means that you should use address from the range of IP numbers reserved for private networks that cannot be routed onto the Internet at large. These include addresses in the networks 10.0.0.0/255.0.0.0, 172.16.0.0/255.240.0.0, and 192.168.0.0/255.255.0.0. If you are not already using them, the addresses 192.168.0.1 and 192.168.0.2 are convenient lies for your local and remote address. Note that it is possible that you will know one of either the local or the remote address, even though you do not know the other. In this case you might as well specify the one that you do know.
|
sticky |
As dynamic but the actual addresses discovered from an actual connection will continue to be used for the proxy interface after the link is dropped in preference to the originally configured local and remote addresses. This may be useful if your provider uses dynamic addresses but only expires an address allocation after a relatively long period of inactivity. |
dslip-mode <mode>
Set the interpretation of dynamic address information for SLIP mode. The possible settings are: bootp, remote, local, remote-local, and local-remote. If the mode is bootp, then the BOOTP protocol is used to determine the dynamic slip address. Otherwise dynamic slip addresses are determined by reading a banner string that is produced by the remote SLIP server when it starts. The string produced might be something like:
Annex address is 137.130.1.14. Your local address is 137.130.2.44.
The dslip-mode specifies which IP addresses should be read from the servers initial output, and in which order they will appear. The default mode is remote-local.
netmask <a>
Set the netmask to be used for the interface.
broadcast <a>
Set the broadcast IP address to be used for the interface.
mtu <m>
Set the MTU (Maximum Transmission Unit) to <m>. The default is 1500. This is the maximum size packet that the networking layer will send over your physical link. Useful values are between 296 and 3000. If you choose a small value you will get better interactive response, larger values will get better throughput, at the expense of interactive response. Note that pppd may negotiate a value other than that you ask for. If you are using SLIP mode then this setting exactly the same as the MTU setting required by your SLIP provider. If the MTU settings do not match on both ends of the SLIP link you will experience severe performance problems.
If you are using pppd, and pppd negotiates a value smaller than that you asked for, then diald will attempt to adjust the MTU to the setting negotiated by pppd. This is not guaranteed to work without causing errors, since adjusting the MTU of an interface that is already up is not supported by the kernel. Hopefully a future version of the kernel will support this. If a readjustment is necessary diald will issue a warning in the system logs. To be sure that no problems will occur you should probably restart diald with an MTU setting matching that reported by diald in the system logs.
mru <m>
Set the MRU (Maximum Receive Unit) to <m>. This only makes sense in PPP mode. This sets the size that pppd will ask the remote size to choose for its MTU. This may be useful to help obtain matching MTU settings on both ends of the PPP link.
metric <n>
Sets the metric for routes associated with this link to <n>. The default is 0. This is useful if you want diald to run as a backup for another network connection. Note that this value is for the actual link. Routes through the proxy will have a metric one greater.
window <s>
This option specifies a TCP window size to place in routing table entries. Choosing a window size limits the number of bytes that a TCP connection will place into the send queue at any one time. This can make a substantial difference to interactive performance. In theory, the window size should be not much more than the bandwidth-delay product, and larger window sizes can negatively impact performance. For a 33.2 kbps modem with a round trip time 120ms, the bandwidth delay product is only 576 bytes! This is a bit too small for practical purposes, but a window size between 2048 and 4096 is not out of line with an MTU between 296 and 1500. You should also keep the window size to a multiple of the MTU, otherwise there will always be a portion of the window that cannot be used.
defaultroute
Tell diald to set up a default route to the SLIP link.
proxyarp
Tell diald to add an entry to this system’s ARP [Address Resolution Protocol] table with the IP address of the remote system, and the Ethernet address of this system.
demasq (Linux only)
Tell diald that packets across this link may be being masqueraded by the kernel. If diald sees a packet whose port is in the range normally used by the kernel masquerading (61000 - 61000+4096) diald will attempt to look up the real source in /proc/net/ip_masquerade and show this as the source in the connection queue shown to monitors.
addroute <script-name>
The designated script or executable is called by diald once it has established the proxy device. The script is passed five arguments: <iface> <netmask> <local-ip> <remote-ip> <metric>. The <iface> argument designates the interface that the proxy device is using, and the next three arguments give the current netmask, local ip address and remote ip address of that interface. The <metric> argument gives the route metric that diald would like the routes to have. Diald will set this parameter to 1 for routes on the proxy link, and 0 for routes on a physical link. Some care should be taken in setting up routes for these two cases. Routes for the proxy link should have "0.0.0.0" as the gateway. Routes for the physical link should have <remote-ip> as the gateway. If you do not do this you will open a window during which there will be no network route during the transition between the proxy and physical links. This can cause TCP connections to be reset when using Linux 1.3.X or greater kernels.
Note that the routing parameters may get changed between the time that your addroute script is first called, and the time diald manages to establish dynamic connection. This will result in the addroute script being called again.
delroute <script-name>
The designated script or executable is called by diald just before it deletes the proxy device (when diald is about to terminate). The script receives the same arguments as the addroute script. This command is here for symmetry, it is unlikely you will need to use it, since the kernel will delete routes that go through an interface that has been taken down.
ip-up <script-name>
The designated script or executable is called by diald whenever the IP layer is brought up. The script receives the same arguments as the addroute script. Diald does not wait for this script to terminate before proceeding with other actions. This means that it is possible to have more than one copy of the script running at the same time. You should consider this when writing your script.
ip-goingdown <script-name>
The designated script or executable is called by diald just before the IP layer is brought down. The script receives the same arguments as the addroute script. Diald waits for this script to terminate before proceeding with other actions. Note that this script is only run if diald is going to terminate the link. If the remote terminates the link this script is not and cannot be run.
ip-down <script-name>
The designated script or executable is called by diald whenever the IP layer is brought down. The script receives the same arguments as the addroute script. Diald does not wait for this script to terminate before proceeding with other actions. This means that it is possible to have more than one copy of the script running at the same time. You should consider this when writing your script.
Timeout Commands
The following options configure how long diald will wait for a variety of events, and to some extent what actions it will take when a timeout occurs.
connect-timeout <t>
Set the maximum amount of time to wait for the connect script to complete to <t> seconds. The default is 60 seconds.
disconnect-timeout <t>
Set the maximum amount of time to wait for the disconnect script to complete to <t> seconds. The default is 60 seconds.
redial-timeout <t>
Set the delay between dialing attempts to <t> seconds. The default is 30 seconds.
nodev-retry-timeout <t>
Set the delay between dialing attempts when no free modem device is available to <t> seconds. The default is 1 second.
stop-dial-timeout <t>
Set the maximum amount of time to wait for connect to die after sending a SIGINT to <t> seconds. The default is 60 seconds.
kill-timeout <t>
Set the maximum amount of time to wait for a subprocess to die after sending a SIGKILL to <t> seconds. After this diald will assume there is something permanently wedge and terminate. (This should never happen). The default is 60 seconds.
start-pppd-timeout <t>
Set the maximum amount of time to wait for pppd to choose a PPP device to <t> seconds. The default is 60 seconds.
stop-pppd-timeout <t>
Set the maximum amount of time to wait for pppd to die after sending it SIGINT to <t> seconds. The default is 60 seconds.
first-packet-timeout <t>
Set the first packet timeout to <t> seconds. After the link has been established there may be some delay before the first packet is actually sent, for example while pppd negotiates the link parameters. If no packets have crossed the link after <t> seconds then diald will assume something went wrong and shut the link down. The default timeout is 120 seconds.
retry-count <n>
Set the maximum number of times diald should attempt to make the initial connection without falling back and waiting for more network traffic. The default is 0.
died-retry-count <n>
Set the maximum number of times diald should attempt to restore a connection that was severed before it should fall back and wait for more network traffic. The default is 1.
redial-backoff-start
Specifies the number of consecutive failures to connect allowed before diald starts doubling the delay between dialing attempts after each attempt. This command can be used to prevent diald from overwhelming the phone lines when the remote side is extremely busy. If this command is not specified redial-backoff-start is taken to be infinity, which effectively turns off the backoff algorithm. When redial-backoff-start is set, diald will use redial-timeout as the delay between each of the first redial-backoff-start unsuccessful calls. After this diald will double the timeout after each failure, up to a limit of redial-backoff-limit seconds. A successful connection resets the backoff algorithm.
redial-backoff-limit
Set the maximum number of seconds diald will delay between failed calls when it invokes the backoff algorithm. The default value is 600 seconds (10 minutes).
dial-fail-limit
Sets the maximum number of consecutive failed connection attempts diald will allow. If this limit is exceeded diald will block further connections until an "unblock" command is issued on the command FIFO. If this is set to 0 diald will not enforce any limit. The default value is 0. When this condition occurs diald will issue the following message to the system logs:
"Too many dialing failures in a row. Blocking connection."
This command is intended for use at sites that need to avoid the possibility of diald attempting a large number of long distance phone calls to a machine that is not operating correctly. Once diald blocks the connection an operator can investigate the cause, correct the problem, and then issue the "unblock" command to allow diald to continue. The link may be manually opened while blocked but will not open on demand until it has been unblocked.
route-wait
On some badly configured PPP servers, traffic will not flow until a routing daemon notices that the PPP link has come up, at which time a routing packet will cross the link from the server to the local side. This option tells diald that it is interoperating with server that is broken in this way, and that it should not consider the IP layer to have come up until it sees at least one packet come from the remote side. Hopefully almost no-one will need this option.
two-way
Normally if the connection is broken by the other end hanging up diald will immediately re-dial the other end. This command forces diald to re-dial only if there is some outgoing traffic. This is intended to be used when the other end of the link is also running some sort of demand dialer (possibly even diald).
give-way
Normally if a FIFO connect request comes in while a connection script is running, the FIFO connect request shell is terminated. This command reverses this behavior so the connect script will be terminated and the FIFO request honoured. This is intended to be used at one (or even both) ends of a two-way link, to avoid problems with both ends attempting to connect simultaneously.
Packet Filter Policy Commands
Diald maintains a virtual link to the remote site at all times. This link is in one of two modes. Either the corresponding physical link is expected to be up, or it is expected to be down. When the physical link is expected to be up diald will attempt to maintain the physical link, dialing and re-dialing if necessary. It will also monitor any packets passing over the virtual link to determine if the physical link should be brought down. When the physical link is expected to be down diald will monitor packets that are sent to the virtual link to determine if the physical link should be brought up. The general approach used by diald to determine when to change between these two modes is to keep a connection set of connection identities, each with an associated timeout. When a timeout associated with a connection identity expires, it is removed from the set. When the connection set is empty diald expects the physical link to be down, otherwise diald expects the physical link to be up.
This section describes the configuration options that control how diald constructs entries for the connection set. The diald-examples manual page gives some examples of how these options can be used.
prule <name> <protocol> <spec>
Define a new protocol rule called <name> to be used in filter statements. The <protocol> field must either be the name of a protocol defined in /etc/protocols, the special keyword "any", or an integer between 0 and 254 inclusive. The <spec> field is a list of 16 colon separated offset codes that specify the bytes to be extracted from a packet to build a connection identifier. Each offset code is an integer, possibly prefixed with a ’+’. Values that are not prefixed are offsets into the ip header, values with the ’+’ prefix are offsets into the data segment of the ip packet.
var <name> <spec>
Define a new variable called <name> to be used in filter statements. The <spec> portion of the definition defines how to construct the value of the variable from a packet. It consists of a byte offset to a 4 byte word, possibly prefixed with a ’+’, optionally followed by a right shift value in brackets, optionally followed by a ’&’ character and a bit mask value. Offsets prefixed with ’+’ are offsets into the data segment of the ip packet, otherwise they are offsets into the ip header of the packet. For example, the ip source address of a packet is defined by
var ip.saddr 12
which means to get the four bytes located starting at an offset of 12 into the packet header. Similarly, the ip protocol of a packet is defined by
var ip.protocol 9(24)&0xff
which means to get the four bytes located starting at an offset of 9 bytes into the header, right shift the obtained value by 24 bits, and mask it with 0xff. As a final example, the source port in a tcp header is defined as
var tcp.source +0(16)&0xffff
which says to obtain the four bytes starting at the beginning of the ip data segment, shift the value right by 16 bits, and mask it with 0xffff.
accept <protocol-rule> <timeout> <packet-rule>
Define a packet matching rule to control the link. Packets that match an accept rule will cause the link to come up and stay up for at least <timeout> seconds. The <protocol-rule> must refer to a protocol rule defined by a previous prule statement. The value <timeout> must be a non negative integer. A <timeout> of zero means the connection associated with the packet will be killed immediately.
The <packet-rule> parameter is a list of one or more conditions that the packet must meet. As a special case the rule "any" matches all packets. Otherwise, a rule is written as a list of terms, separated by commas and no white space. Each term specifies either a test on some field of the packet. Basic terms are written as
<variable-name><op><value>
or
<variable-name>&<bitmask><op><value>
Where the <bitmask> is an optional binary bitmask to logical and with the variable value before the comparison and <op> is one of "=", "!=", "<=" or ">=". As well there are two short forms: "<variable-name>" and "!<variable-name>", which are short for "<variable-name>!=0" and "<variable-name>=0".
Only variable names defined by previous var statements may be used in packet rules. Comparison values and bitmask values can be specified as decimal numbers, octal numbers, hex numbers, dots and numbers style ip addresses, or by symbolic names. The symbolic names of the form "tcp.<service>", "udp.<service>" match the values defined in /etc/services. Symbolic names can also match any protocol defined in /etc/protocols.
See the discussion on controlling link uptime below for further explanation of how accept rules are applied.
bringup <protocol-rule> <timeout> <packet-rule>
Define a packet matching rule to control the link. Packets that match a bringup rule will cause attempts to bring the link up for at least <timeout> seconds. These rules are ignored if the link is currently up. The parameters are exactly as described for the accept command.
See the discussion on controlling link uptime below for further explanation of how bringup rules are applied.
keepup <protocol-rule> <timeout> <packet-rule>
Define a packet matching rule to control the link. Packets that match a keepup rule will cause the link to stay up, if it is already up, for at least <timeout> seconds. These rules are ignored if the link is currently down. The parameters are exactly as described for the accept command.
See the discussion on controlling link uptime below for further explanation of how keepup rules are applied.
ignore <protocol-rule> <packet-rule>
Define a packet matching rule to control the link. Packets that match an ignore rule will be ignored and will not match any later rules. Except for the lack of a <timeout> parameter, the parameters are exactly as described for the accept command.
See the discussion on controlling link uptime below for further explanation of how ignore rules are applied.
restrict <start> <end> <weekdays> <monthdays> <months>
or-restrict <start> <end> <weekdays> <monthdays> <months>
Normally filter rules apply at all times. The restrict statement makes all filter rules following the restrict statement, up to the next restrict statement, apply only at the times indicated by the restrict statement. A restrict statement provides five numeric fields. The first two fields indicate a starting time and an ending time, given in the form "HH:MM:SS". If "*" is given for the start time it is taken as meaning "00:00:00". Similarly if "*" is given for the end time it is taken as meaning "23:59:59". For the remaining three fields, each field is either "*", to indicate all possible values, or a comma separated list of numbers and number ranges. The <weekdays> field specifies the days of the week Acceptable numbers are in the range 0-6, where the number 0 is Sunday, the number 1 is Monday, and so forth. The <monthdays> field specifies the days of the month. Acceptable numbers are in the range 1-31. The <months> field specifies the months of the year. Acceptable numbers are in the range 1-12. A restrict command specifies an range of times. The or-restrict command expands the immediately preceding restrict to include the range of times specified by the or-restrict command. As an example, to restrict the following filter rules to be applicable from 2-3 AM and 5-6 PM every Sunday one would use the statements:
restrict 2:00:00 3:00:00 0 * *
or-restrict 17:00:00 18:00:00 0 * *
WARNING: this interface is experimental and the syntax may change in future versions of diald.
|
up |
The up rule forces the link to be up at all times, regardless of the packet filtering that is in force. The application of this rule can be limited by the use of a restrict statement. For example, the sequence of commands |
restrict 12:00:00 13:00:00 * * *
up
would force the link to be up from 12:00-1:00 PM every day.
|
down |
The down rule forces the link to be down at all times, regardless of the packet filtering that is in force. The application of this rule can be limited by the use of a restrict statement. For example, the sequence of commands |
restrict 12:00:00 13:00:00 * * *
down
would force the link to be down from 12:00-1:00 PM every day.
NOTE: Up and down rules with overlapping restrictions are applied in the order they are given. For example, The sequence
restrict 12:30:00 12:39:00 * * *
down
restrict 12:00:00 13:00:00 * * *
up
would bring the link up at 12:00 PM, bring it back down at 12:30, back up at 12:40, and let the line float up or down depending upon traffic after 1:00 PM.
impulse <duration>,<fuzz>
impulse <initial-duration>,<secondary-duration>,<fuzz>
The impulse command is used to control the link up time in units larger than a single second. This is intended to be used in areas where phone connections are charged in impulses. In the two argument form, the <duration> parameter indicates the number of seconds that diald will keep the line up before checking to see if it is idle. The <fuzz> parameter is the number of seconds that diald will continue to monitor the idle state before waiting for <duration> seconds again. In the three argument form, the <initial-duration> parameter indicates the minimum number of seconds diald will keep the line up once a call has been initiated. After this timer expires diald will proceed as for the two argument case using the <secondary-duration> parameter in place of the <duration> parameter. Zero values for <duration> and <fuzz> turn off the impulses feature.
For example, if on Sundays your phone connections are charged in units of $1 per 1 hour chunk, and no matter how much of each chunk you use you pay the full $1, then you might as well keep the connection up for 1 hour once you’ve made it. To accomplish this you might use the following commands.
restrict * * 0 * *
impulse 3570,30
This will keep the link up for 3570 seconds at a time, with a 30 second leeway to account for the time required to make and break the connection. Note that the <fuzz> factor should not be made to small, since otherwise diald may not be able to hang up the connection before your call is being billed in the next impulse.
Similarly, if you’re calls are billed by the second, but there is a minimum charge for the first 10 minutes, then you might use the following command.
impulse 600,0,0
flushfilters
Remove all existing filter rule definitions.
flushprules
Remove all existing protocol rule definitions.
flushvars
Remove all existing variable definitions.
Exits with status 1 if something causes diald to terminate abnormally. Error and information messages are logged to the syslog daemon under the LOCAL2 facility. If diald is not running in daemon mode, then they are also printed on stderr. Setting the debugging mask flags can greatly increase the amount of this output. If you turn debugging on watch your log files!
/etc/diald.conf
Default configuration file.
/etc/diald.defs
Default protocol rules and variable definitions.
/var/lock/LCK..*
UUCP style lock files for serial devices.
/var/run/*
Logging for the pid of a running diald. By default the file diald.pid is used. This can be changed with the pidfile command.
dctrl(1), diald-examples(5), diald-control(5), diald-monitor(5), pppd(8), chat(8), expect(1)
Mike Jagdis (jaggy AT purplet DOT demon DOT co DOT uk) Eric Schenk (Eric DOT Schenk AT dna DOT lth DOT se)
There are some known problems and limitations.
Lines in configuration files can contain at most 1024 characters. Longer lines are silently truncated.
If there are no filter rules specified then no packets will be matched and the daemon won’t do anything. It should probably match all packets by default in this case.
Diald attempts to automatically adjust the MTU of the proxy to match the MTU of the actual connection negotiated by ppp, but this is not guaranteed to work, since changing the MTU on an active interface is not supported by the kernel. It is possible that an auto adjusted MTU will cause some long packets to get dropped on the floor. If you are having problems you should match these values manually. Diald will report the negotiated MTU in the system logs and warn you that you should adjust the settings.
The monitor command represents a security risk as anyone who has access to a diald control FIFO can ask diald to write to any named pipe in the system. Be careful with the permissions on your FIFO’s.