The simplest connection case occurs when you have a fixed IP address assigned to your local machine, and that machine is not connected to a local network. Generally PPP is simpler to setup correctly than SLIP. Suppose for this example that your machine is to be connected by PPP, that your machine has been assigned the IP address 137.130.1.14, and that the machine you are connecting to has the address 137.130.2.44. Also, suppose your modem is on the serial line /dev/ttyS1, and that you want to set the modem speed to 115200, since you have a fast modem. Then the following /etc/diald/diald.options file is a minimal configuration for this case:

mode ppp

connect /etc/diald/connect

device /dev/ttyS1

speed 115200

modem

lock

crtscts

local 137.130.1.14

remote 137.130.2.44

defaultroute

include /etc/diald/standard.filter

The mode option tells diald that it should use the PPP protocol. The connect option tells diald where to find the connect script. The device option tells diald that the modem is on the /dev/ttyS1 device, and the speed option tells diald that it should connect to the modem at a speed of 115000 bps. The modem option tells diald that there is a modem on the serial line. Without this option diald will assume that it is connected directly to the remote system by a serial cable. Unless this is really the case, you will want the modem option. The lock option tells diald that it should perform locking to prevent other programs from using the modem while it is doing so. The crtscts option tells diald that it should use the hardware flow control lines for the serial device. This is almost certainly necessary for any high speed serial connections.

The local option specifies the IP address for your machine. Similarly, the remote option specifies the IP address for the machine at the remote end of your link. The defaultroute option tells diald to install a default route in the routing table that goes through the link it is controlling. If the link that diald is controlling is your link to the rest of the Internet, then you will want this option.

Finally, the last line tells diald to load the options in the file "/etc/diald/standard.filter". These options specify a set of rules for diald to use to determine when to bring the link up or down. Modifications to these rules are discussed in the third part of this manual page.

Suppose that you needed to connect using the SLIP protocol rather than the PPP protocol? In this case the line that says "mode ppp" needs to be changed to read "mode slip" (if you are using compressed SLIP this should read "mode cslip" instead). Assuming that your connect script does the right thing to start SLIP on the remote machine this might be enough. However, it is usually necessary to also set the Maximum Transmission Unit (MTU) on a SLIP link, since this setting must be identical on both ends of a SLIP link, and the default value of 1500 may be incorrect. Supposing that your MTU setting should be 576, then the following modification of the above example is a minimal /etc/diald/diald.options file for this situation:

mode slip

connect /etc/diald/connect

device /dev/ttyS1

speed 115200

modem

lock

crtscts

local 137.130.1.14

remote 137.130.2.44

mtu 576

defaultroute

include /etc/diald/standard.filter

Assume now that when you dial your remote site you might be connected to any one of a number of terminal servers, each of which has a different remote address. What should you pick for the remote address to tell diald? Curiously enough, it doesn't matter. The remote address assigned to an interface is really only a local label that the route program uses to find the right interface. Once the routes have been established the number is never used again. Therefore, faced with the above situation you can choose the address of any one of the terminal servers that you can be connected to as the remote address.

Let us again complicate matters for ourselves. Assume now that not only do you not know the remote address you will get connected to, but that the remote site might assign you a different local address each time you connect. In this situation we must use the dynamic option. Note that you must still supply an initial local address, otherwise diald won't be able to fake the existence of a connection when none has yet been made. This initial local address should be picked from one of the unroutable subnets that have been set aside for use as private IP numbers. It is usually also convenient to choose a fake number for the remote IP address in this case. If you do not have a local IP network that is using one of these private addresses, then you can just use the IP addresses 192.168.0.1 and 192.168.0.2. If you are already using these addresses in your local network, then you should pick IP addresses that you have not assigned to a machine on your local network. The following is a minimal /etc/diald/diald.options file for this case:

mode ppp

connect /etc/diald/connect

device /dev/ttyS1

speed 115200

modem

lock

crtscts

local 192.168.0.1

remote 192.168.0.2

dynamic

defaultroute

include /etc/diald/standard.filter

If you are using SLIP with dynamic IP addresses, then things are slightly more complicated. This is because the SLIP protocol does not specify a way for the two machines to negotiate the addresses assigned to the endpoints. The standard way to get around this problem is to have the remote SLIP server output a string stating the addresses that have been assigned before it actually goes into SLIP mode. The local machine can then read these strings from the modem before it enters SLIP mode. Diald is capable of reading and interpreting these strings, but it needs a little help. In particular, diald can't know in advance which order the local and remote addresses will be output, or for that matter if both will even appear. The dslip-mode command allows you to specify what address should be expected to appear and what order they will appear in. For example, if your remote site prints out the remote address followed by the local address (possibly with some intervening text between the addresses), the you might use the following minimal /etc/diald/diald.options file:

mode slip

connect /etc/diald/connect

device /dev/ttyS1

speed 115200

modem

lock

crtscts

local 192.168.0.1

remote 192.168.0.2

dynamic

dslip-mode remote-local

mtu 576

defaultroute

include /etc/diald/standard.filter

We now consider a more complex example. This example illustrates several more advanced options that you might need to be aware of.

Suppose that you have a small network that has been assigned the IP addresses in the network 137.130.1.0/255.255.255.0 that must be connected to corporate headquarters via a PPP server that has the IP address 137.130.2.44. Also, suppose that your main connection to the Internet is via some other connection, and that you only want to route addresses on the network 137.130.2.0/255.255.255.0 through the link maintained by diald.

Let us further suppose that the server at headquarters depends on you to specify the address of your local machine in the PPP negotiation phase, since you may need to change it in the event of a breakdown, and headquarters doesn't want to be bothered with reconfiguring their server when this happens. In this case, pppd must be passed an address parameter of the form "137.130.1.14:".

Finally, suppose that there is a pool of modems on the devices /dev/ttyS1 through /dev/ttyS5, and that outgoing calls should use any of these modems that is not busy already.

The following /etc/diald/diald.options file can be used in this case. The options that have not been used in previous examples are discussed below.

# General options

mode ppp

accounting-log /var/log/diald.log

fifo /var/run/diald.fifo

pppd-options 137.130.1.14:

# Device configuration

connect /etc/diald/connect

device /dev/ttyS1

device /dev/ttyS2

device /dev/ttyS3

device /dev/ttyS4

device /dev/ttyS5

rotate-devices

speed 115200

modem

lock

crtscts

# Network configuration

local 137.130.1.14

remote 137.130.2.44

netmask 255.255.255.0

mtu 576

mru 576

window 2048

addroute /etc/diald/addroute

ip-up /etc/diald/shipmail

# Timeouts

redial-backoff-start 4

redial-backoff-limit 300

dial-fail-limit 15 # Get the standard filter policy

include /etc/diald/standard.filter

The accounting-log option specifies a file in which diald should record a log of the phone calls it makes. If you don't need this log, then you can just omit this option.

The fifo option tells diald to make a control fifo named /var/run/diald/diald.fifo that can be used to control diald once it is running. The programs dcntl and diald-top make use of this control fifo, and it is easy to write new programs that also make use of it. Note that although the fifo need not exist when diald is started, the directory that it is located in (/etc/diald in the example) must exist.

The pppd-options option specifies a list of one or more options that should be passed to pppd when diald starts it. In this case the option "137.130.1.14:" is passed so that pppd can negotiate the correct local IP address.

Note that there is more than one device option. Each specifies one of the possible modem devices. The rotate-devices option tells diald to start with a different device every time it tries to make a call. This ensures that if one of the modems gets broken diald won't get stuck trying to use the same broken modem every time.

The netmask option sets the network mask for the local side of the PPP interface. In this case we want the mask to be 255.255.255.0. Often the correct netmask can be deduced by diald knowing the IP address, but if this is not the case you can specify it with this option.

Unlike previous examples using the PPP mode, this example includes an MTU setting. The default setting for the MTU in PPP mode is 1500. To get better interactive response you might want to negotiate a smaller value. In this example we are trying to get both sides of the link to set their MTU to 576. The mtu option sets the MTU on this side of the link. The mru option forces diald to ask the other side of the link to set its MTU to 576.

The window option is also present for performance tuning reasons. In particular, the TCP protocol can normally send quite large amounts of data (30-40k) at a time. This much data can take quite a while to pass through a modem. This option tells diald to set the window size in its entries in the routing table. This restricts the amount of data that TCP will send in a single burst. This can improve interactive performance quite a bit. See the diald manual page for a discussion of appropriate window settings.

The addroute option asks diald to run a script named /etc/diald/addroute when it is ready to add entries to the routing table. We do this so that we can add the routes to the network 137.130.2.0/255.255.255.0 as we discussed in the description leading up to this example. An appropriate /etc/diald/addroute script for this purpose would be:

#!/bin/sh

/sbin/route add -net 137.130.2.0 \

netmask 255.255.255.0 gw $4 \

window 2048 metric $5 dev $1

The ip-up option asks diald to run a script named /etc/diald/shipmail whenever the IP layer is brought up. In this case we might suppose that this script sends out any mail that is destine for addresses at headquarters. You can use an ip-up script to do any processing that you need to do every time the link comes up.

The redial-backoff-start, rediald-backoff-limit, and dial-fail-limit options all help limit how often diald will attempt to make consecutive failing calls. The rediald-backoff-start option tells diald to start doubling the time between successive calls after 4 consecutive failures. The rediald-backoff-limit option tells diald not to wait more than 300 seconds after a failed call. Finally, the dial-fail-limit option tells diald not to make more than 15 consecutive failed calls. If diald should make 15 consecutive calls that failed, then it would stop attempting to dial out, issue a report of the error condition to the system logs, and wait for an operator to issue it an instruction to restart dialing. The manual page for diald describes these options in more detail.

Accept, bringup, keepup and ignore rules control the addition of new connection identities to the connection set. Each accept, bringup or keepup rule specifies a set of conditions that a packet must match, a method to generate a connection identity from a packet, and a timeout. Ignore rules specify only a set of conditions that a packet must match. When a packet arrives that matches a given accept rule, then a connection identity, say <id>, is generated from the packet, and <id> is added to the connection set with the timeout specified by the filter rule. If <id> was already in the set, then the new timeout will replace the old timeout. Note that the new timeout may be less than the old timeout.

Each accept, bringup, keepup or ignore statement must specify the name of a protocol rule. Protocol rules specify how to build connection identifiers. The distributed /etc/diald/diald.defs file contains the following four definitions:

prule tcp tcp 9:12:13:14:15:16:17:18:19:+0:+1:+2:+3:9:9:9

prule udp udp 9:12:13:14:15:16:17:18:19:+0:+1:+2:+3:9:9:9

prule icmp icmp 9:12:13:14:15:16:17:18:19:9:9:9:9:9:9:9

prule any any 9:12:13:14:15:16:17:18:19:9:9:9:9:9:9:9

The tcp and udp rules respectively match tcp and udp packets, and build connection identifiers consisting of the packet protocol, the source and destination IP addresses, and the source and destination port numbers. The icmp and any rules construct identifiers consisting only of the packet protocol and source and destination IP addresses. It is important to note that diald does not build connection identifiers directly from the matched packet. Before generating the connection identifier diald may swap the source and destination addresses, so that the numerically smaller address is always in the source field before generating the connection identifier. This is done so that the same connection identifier is generated regardless of the direction the packet is going across the interface.

As well, each accept, bringup, keepup or ignore statement must specify some set of conditions on the contents of the packet. Variable definitions allow access to the contents of the packet in accept and reject statements. The distributed /etc/diald/diald.defs file defines variables for all the fields in the ip packet header and for all the fields in the tcp, udp and icmp packet headers. The names match those used in the include files found in /usr/include/linux.

The IP packet header variables are: ip.ihl header length

ip.version format version

ip.tos type of service

ip.tot_len length of ip packet in words

ip.id packet id

ip.frag_off fragment offset

ip.ttl time to live

ip.protocol ip protocol

ip.check ip header checksum

ip.saddr ip source address

ip.daddr ip destination address

The TCP packet header variables are: tcp.source tcp source port

tcp.dest tcp destination port

tcp.seq tcp sequence number

tcp.ack_seq tcp ack sequence number

tcp.doff tcp data offset in words

tcp.fin tcp finish flag

tcp.syn tcp synchronize flag

tcp.rst tcp reset flag

tcp.psh tcp push flag

tcp.ack tcp acknowledge flag

tcp.urg tcp urgent flag

tcp.live tcp connection state

The final variable (tcp.live) is a pseudo variable provided by diald. It is true if and only if the TCP connection has not been shut down.

The UDP packet header variables are: udp.source udp source port

udp.dest udp destination port

udp.len udp header length

udp.check udp packet checksum

The ICMP packet header variables are: icmp.type icmp packet type

icmp.code icmp packet code

icmp.checksum icmp packet checksum

icmp.echo.id icmp echo id

icmp.echo.sequence icmp echo sequence

icmp.gateway icmp gateway

It may help to consider some examples. The rule

accept tcp 10 any

says to match any tcp packet and assign the generated connection identity a timeout of 10 seconds. The method used to generate a connection identity is specific to tcp packets. The identity of a tcp packet consists of the protocol, the source and destination ip address, and the source and destination port associated with the tcp packet.

Similarly, the rule

accept any 10 any

says to match any packet and assign the generated connection identity a timeout of 10 seconds.

The more complex rule

accept tcp 60 tcp.dest=tcp.www,ip.daddr&255.255.0.0=149.100.0.0

matches any tcp packet with a destination matching the tcp www port number specified in /etc/services, and an ip destination address on the 149.100.0.0 subnet.

We now describe the construction of much of the rule set found in the file "/etc/diald/standard.filter". Rather than listing the contents of this file in one piece, we will discuss small groups of rules in the order they appear in the file. Be warned that some knowledge of the internal workings of the Internet protocols may be required to completely understand some of these examples. Also be warned that the description here is intended to help understand how to write filter rules. Some rules that occur in the actual file at the time of this writing have been left out, and the distributed file may have evolved since this was written. This should not affect the usefulness of the discussion.

Note that the order in which filter rules occur is critical. Each time a packet arrives diald will apply the first filter rule that matches the packet.

The rules in the standard filter file are divided into three sections: TCP rules, UDP rules, and a general catch all set of rules.

TCP Rules

Before proceeding to describe the rules, it will be helpful to make some general remarks about the reasoning behind these rules.

In general, we would like to treat only data on a TCP link as significant for timeouts. Therefore, we try to ignore packets with no data. Since the shortest possible set of headers in a TCP/IP packet is 40 bytes. Any packet with length 40 must have no data riding in it. We may miss some empty packets this way (optional routing information and other extras may be present in the IP header), but we should get most of them. Note that we don't want to filter out packets with tcp.live clear, since we use them later to speedup disconnects on some TCP links.

We also want to make sure WWW packets live even if the TCP socket is shut down. We do this because WWW doesn't keep connections open once the data has been transfered, and it would be annoying to have the link keep bouncing up and down every time you get a document.

Outside of WWW the most common use of TCP is for long lived connections, that once they are gone mean we no longer need the network connection. We don't necessarily want to wait 10 minutes for the connection to go down when we don't have any telnet's or rlogin's running, so we want to speed up the timeout on TCP connections that have shutdown. We do this by catching packets that do not have the live flag set.

The first rule is designed to give the link 15 seconds up time when we are initiating a TCP connection. The idea here is to deal with possibility that the network on the opposite end of the connection is unreachable. In this case you don't really want to give the link 10 minutes up time. With the rule below we only give the link 15 seconds initially. If the network is reachable then we will normally get a response that actually contains some data within 15 seconds. If this causes problems because you have a slow response time at some site you want to regularly access, you can either increase the timeout or remove this rule.

accept tcp 15 tcp.syn

If you are running named, then it will send data across the link periodically to synchronize against other domain name servers. Since this can happen at any time, it is undesirable to keep the link up for it. Therefore, we ignore any traffic from or to a domain name server.

ignore tcp tcp.dest=tcp.domain

ignore tcp tcp.source=tcp.domain

Normally the packet that starts a connection is longer that 40 bytes, since it normally contains TCP options to specify the MSS. However, some TCP implementations don't include these options. Therefore, we must be careful not to ignore SYN packets that are only 40 bytes long.

accept tcp 5 ip.tot_len=40,tcp.syn

Otherwise, we want to ignore any TCP packet that is only 40 bytes long, since it is not carrying any data. However, we don't want to ignore 40 byte packets that mark the closing of a connection, since we use those to cut short the timeout on connections that have died. Therefore we must test the tcp.live flag here. If it is not set we might want to see this packet later on in the rules.

ignore tcp ip.tot_len=40,tcp.live

Make sure http transfers hold the link for 2 minutes, even after they end. This prevents web browsers from bouncing the connection too much. You may find the 2 minutes is a bit short for your taste.

accept tcp 120 tcp.dest=tcp.www

accept tcp 120 tcp.source=tcp.www

Once the link is no longer live, we try to shut down the connection quickly. Note that if the link is already down, the closing of the a connection (which will generate traffic) will not bring it back up.

keepup tcp 5 !tcp.live

ignore tcp !tcp.live

An ftp-data or ftp connection can be expected to show reasonably frequent traffic, so we can use a short timeout for this kind of traffic.

accept tcp 120 tcp.dest=tcp.ftp

accept tcp 120 tcp.source=tcp.ftp

Finally, if we don't match the TCP packet somewhere above, then we give the link 10 minutes up time. Most TCP packets match this rule.

accept tcp 600 any

UDP Rules

Not many programs communicate via UDP packets, and many of those that do are programs that we don't want to hold the link up, since they broadcast UDP packets every few minutes. However, the normal sequence of events when the link is down is for the user to initiate a network program that needs to perform a domain name query before it can make a TCP connection. Therefore, we want to bring up the link when we see a domain name packet cross the link. We explicitly ignore may other kinds of UDP packets.

Don't bring the link up for rwho.

ignore udp udp.dest=udp.who

ignore udp udp.source=udp.who

Don't bring the link up for routing packets.

ignore udp udp.dest=udp.route

ignore udp udp.source=udp.route

Don't bring the link up for NTP or timed.

ignore udp udp.dest=udp.ntp

ignore udp udp.source=udp.ntp

ignore udp udp.dest=udp.timed

ignore udp udp.source=udp.timed

Don't bring up on domain name requests between two running copies of named.

ignore udp udp.dest=udp.domain,udp.source=udp.domain

Bring up the network whenever we make a domain request from someplace other than named. We time out domain requests quite quickly. We just want them to bring the link up, not keep it around for very long. This is because the network will usually come up on a call from the resolver library, but once it is up we will get a response and make TCP connection. If that fails we don't want the link to stay up because of the prior domain name query. Note that you should not make the timeout shorter than the time you might expect your DNS server to take to respond. Otherwise when the initial link gets established there might be a delay greater than this between the time the initial series of packets goes across the link and the time that any response packets cross the link, in which case you will loose the link.

accept udp 30 udp.dest=udp.domain

accept udp 30 udp.source=udp.domain

We treat netbios-ns broadcasts the same as domain name queries.

ignore udp udp.source=udp.netbios-ns,udp.dest=udp.netbios-ns

accept udp 30 udp.dest=udp.netbios-ns

accept udp 30 udp.source=udp.netbios-ns

Any other UDP packets keep the link up for 2 minutes. If you are having trouble because various UDP protocols are keeping your link up when you don't want them to, you might try changing this rule to ignore any UDP packets that were not caught above. Of course this may break something else.

accept udp 120 any

Catch All Rules

Catch any packets that we didn't catch above and give the connection 30 seconds of live time. Most often this just catches ICMP ping packets.

accept any 30 any

Often it will be the case that you do not want to use the same set of filter rules at all times. This can be accomplished by the use of the restrict and or-restrict statements. For example, suppose that you wanted diald to keep the line up at all times from 08:00 to 18:00 Monday to Friday, and from 08:00 to 14:00 on Saturday, but you wanted the line to stay down at all other times. This could be accomplished by the following filter rules:

restrict 08:00:00 18:00:00 1-5 * *

or-restrict 08:00:00 14:00:00 6 * *

up

restrict * * * * *

down

Note that the statement "restrict * * * * *" means that the "down" rule is applicable at all times. The reason this set of rules works as intended is that diald looks for the first rule that is applicable to each packet. During the hours that the "up" rule is applicable, the down rule will never be examined. Outside of those hours the down rule will be the only matching rule.

As a slightly more complicated example, suppose that we wanted the line to be up "on demand" outside of normal working hours, rather than forced down. In addition suppose that we must force the line down 15 minutes after the end of normal business hours for 15 minutes to clear the modem to accept an incoming call from a branch site that will update the sales database. This can be accomplished by the following filter rules:

restrict 08:00:00 18:00:00 1-5 * *

or-restrict 08:00:00 14:00:00 6 * *

up

restrict 18:15:00 18:30:00 1-5 * *

restrict 14:15:00 14:30:00 6 * *

down

restrict * * * * *

include /etc/diald/standard.filter

In many countries phone calls are charged in fixed size quanta, called impulses. Once an impulse has started, you are charged for the entire impulse. This means that there is no money to be saved by hanging up the phone just after the start of an impulse. Diald has a facility that allows you to specify the impulse charging mechanism in use, and arrange to try and hang up near the end of impulses.

As an example, suppose that on Monday to Friday, from 08:00 to 15:00 phone calls are charged in impulses of 3 minutes, but outside of these hours they are charged in impulses of 9 minutes. In addition suppose that the first impulse of any phone call is always 3 minutes, regardless of when the call is made.

The following rules, placed before your filtering rules in /etc/diald/diald.options, will tell diald about this impulse system.

restrict 08:00:00 15:00:00 1-5 * *

impulse 150,510,30

restrict * * * * *

impulse 150,30

The diald man page should be consulted for the precise semantics of the impulse command.

There are some problems that you might be tempted to solve using time restrictions, that are better solved in a different way.

For example, suppose you wanted to bring the phone line up every 30 minutes for 5 minutes to check your mail. You might be tempted have the mail collection started in your ip-up script, and to write a long series of rules like:

restrict 00:00:00 00:05:00 * * *

or-restrict 00:30:00 00:35:00 * * *

.

.

.

up

This will work, but requires writing a rather long series of rules. Furthermore, the problem can better be solved by having cron run a job every 30 minutes that issues diald an "up" command via the fifo control, or sends it a SIGUSR1, which has the same effect. This would cause diald to make a single attempt to dial out, and if it succeeds in making the connection the ip-up script will be run, collecting your mail.