DIP(8)

NAME
dip - dialup IP connection handler.

SYNOPSIS
dip -i [-v]
diplogin [-v]
dip [h]
dip -k [-v] [-f file]
dip -t [-v] [-c count] [-f file]
dip [-v] [-d] [-c count] [-f file] [-m mtu] [-p proto] [-s /setup] script.dip

DESCRIPTION
Dip handles the connections needed for dialup IP links, like SLIP or PPP. It can handle both incoming and outgoing connections, using password security for incoming connections. If the modem detects a lost carrier it has the ability to build up a new connection.

Only the super-user may use dip.

OPTIONS
-c count
    Invokes the program with a master timer. If a protocol connection has not been made within approximately count seconds, dip will terminate with status code 5.

Note:
    When using this option, the timeout counts on the dialing script get and wait command will not be honored.

-d  Turn on debugging output. This includes verbose mode! So nearly all actions are logged to stdout and errors to stderr. And some messages will be written to syslog. Handle with care! See also the section below entitled DIAGNOSTICS.

-f file
    Specifies the file which will contain the pid of the dip process to be started soon or killed. Dip will add a prefix of "/var/run/dip." and a suffix of ".pid" to the file specified. So, if you say -f sunnet the pid file will be named "/var/run/dip.sunnet.pid". "/var/run/dip.pid" is default. Existing files will be overwritten.

-h  Prints a message listing and briefly describing all the command line options dip knows.

-i  Invoke the program in host mode. Same as diplogin.

-k  Invokes the program to kill a previously started session. See also option -f file.

-m mtu
    Default mtu to use.

Note:
    On (Net)BSD systems I wasn't able to change the SLIP interface MTU (see section BSD NOTES below at the end of the document). Dip default is therefore equal to the system default MTU 296.

-p proto
    Default protocol to use. At the moment SLIP and CSLIP are supported.

-s /setup
    Invokes the program with setup shell script /setup. Specify a complete (absolute) path, beginning with "/". This shell script takes the place of the automated ifconfig(8) and route(8) commands which are normally executed once the protocol is established. Handle with care. See sample file "setup.sample" for an example. See section below entitled SETUP SCRIPT.

-t  Invokes the program in interactive (command) mode. t means Test-Mode.

-v  Turn on verbose mode. Nearly all actions are logged to stdout and errors to stderr.

script.dip
    Starts the program in dialout mode and invokes the specified dialing script file. The suffix ".dip" will be automatically added to the path specified.

STATUS RETURNED
The following values are returned at the termination of dip:

-1  An error occurred or one (or more) command line parameters was wrong.

0   Normal exit.

2   A SIGHUP (tty line disconnect) was intercepted before protocol startup.

3   A SIGINT (user interrupt) was intercepted before protocol startup.

4   A SIGTERM (terminate process) was intercepted before protocol startup.

5   The -c count (timeout) option was used and count seconds expired before protocol startup.

6   A SIGHUP occurred while the protocol connection was running and dip has been started with option -i and runs in dialin mode. In dialout mode, dip tries to build up a new connection using the command lines following the mode command and so does not exit with an errorlevel.

7   A SIGINT occurred while the protocol connection was running.

8   A SIGTERM occurred while the protocol connection was running.

Note 1:
    I don't know, if it is really possible to receive the return codes 6 to 8 at the shell, because dip then runs as a daemon.

Note 2:
    All these latter signals are only caught after the port and the mode commands have been executed.

SETUP SCRIPT
When the option -s /setup is specified, /setup is the complete path string for a file containing a shell script to be executed in place of the normal ifconfig(8) and route(8) commands. See sample file "setup.sample".

Make sure your script exits with a return code of zero to indicate success, although dip at the moment doesn't matter the return code. You may specify #!shellname at the beginning of your script to get the shell of your choice. The script is called with the following arguments:

    /setup UP|DOWN if pro mtu local locip remote rmtip gw gwip nmsk
           rt rtip dft tmot

UP|DOWN
    On startup, the parameter will be UP (in upper case). On SLIP shutdown the parameter will be DOWN. Easy, eh?

if  the interface name

pro the protocol name

mtu the MTU value

local
    the value of the $local variable

locip
    the value of the $locip variable

remote
    the value of the $remote variable

rmtip
    the value of the $rmtip variable

gw  the gateway string

gwip
    the gateway IP string

nmsk
    the netmask string

rt  the route string

rtip
    the route IP string

dft set to 1 if the default command was used in this script; otherwise it is set to 0

tmot
    set to the value specified in the -c count (timeout) option.

Note:
    Some parameters may not presently be used and some may be replaced by placeholder null strings).

COMMAND MODE
The first possible use of dip is as a standalone program to set up an outgoing IP connection. This can be done by invoking dip with the -t option, which means "enter TEST mode" and, more precisely, dumps you in the command mode of the dip program. You are reminded of this by the DIP> prompt, or, if you also specified the -v or even -d debugging flag, the DIP [nnnn]> prompt. The latter prompt also displays the current value of the global $errlvl variable, which is used mostly when dip runs in script mode. For the interactive mode, it can be used to determine if the result of the previous command was OK or not.

The following is a sample taken from a live session:

# dip -t

    DIP: Dialup IP Protocol Driver
    Original idea & source:  Fred N. van Kempen, MicroWalt Corporation
    NetBSD implementation :  Joachim Bartz  v1.02  (1. July 1995)

DIP> _

The most helpful command in this mode is, of course, the help command, which should produce an output similar to this:

DIP> help

DIP knows about the following commands:

    databits  default   dec       dial      echo
    exit      flush     get       goto      help
    if        inc       init      mode      modem
    parity    print     port      reset     send
    sleep     speed     stopbits  term      wait

DIP> _

All commands display how they should be used when invoking them with no or invalid arguments. Just experiment a little to get the feel of it, and have a look at the sample script files, which also use this command language.

DIALING SCRIPTS
Any of the commands which can be used in command mode can pretty much be used in a dialing script as well. Help is available for each command in command mode and there is a detailed description of every command below (see section COMMANDS below). As an aid to writing scripts, the following C-like escape sequences may be added to strings passed to the wait (wait for a string to be received from the remote system) and send (send a string to the remote system) commands. The escape sequences consist of the following:

\a  alert (bell) character

\b  backspace

\f  formfeed

\n  newline character

\s  space (blank)

\t  horizontal tab

\v  vertical tab

\\  backslash

\'  single quote

\"  double quote

\?  question mark

COMMANDS
There are several known commands. But in normal circumstances only a few will be used by 'normal' scripts.

Error levels:

-2  Testing for a string in the actual buffer was not successful. The buffer will be cleared.

-1  While execution an error occured. This could be a simple syntax error or a failure accessing the terminal or ... Sometimes there will be other negative error levels, but the mean all the same: Error!

0   Execution was OK.

1-10
    One of these error levels is returned after execution of a wait command. See wait for details.

The commands:

databits bits
    Number of databits to use. Although there are four possible values 5,6,7 and 8, the correct value must be 8, which is program default, too.

dec $counter [value]
    Decrease the internal counter variable by one (default, if no third parameter given) or by the value.

default
    Make the new route the default route using the external command "route add default remoteIP".

dial telephone-number
    Dial the given telephone number. The string may contain a 'T' or 'P' to indicate touchtone or pulse dialing, but should not contain a 'AT'-command. Before the dial string is send to the modem, the init string is send.

echo on|off
    Set echo mode on or off. If set to on, output read from the modem is printed to stdout.

flush
    Flush all buffers.

exit [error-code|$counter]
    Leave command mode immediate. May also be used in a dip command script. 0 is returned, if the error-code is ommited. Otherwise the value or the content of the $counter variable.

Note:
    CTRL-D will also work.

get $variable [value|ask|remote [timeout-value]]
    Set an internal variable. The new variable value can be given as a concrete value, the user can be asked to enter the value per stdin or the value can be read from remote. Only in latter case the timeout value will be used (see -c count option).

Note 1:
    A timeout value of -1 means "wait until something valid is read". A timeout value of 0 stays for "test the actual buffer contents and return immediate". Other values mean a timeout given in seconds.

Note 2:
    To keep the program simple and small, there is no comprehensive error checking. In certain casees the program may die if the input is fatally incorrect.

Note 3:
    Only IP numbers but no address strings are parsed when reading input from remote.

Note 4:
    Setting the $mtu variable to any other value than 296 is senseless, since dip is not able to tell the kernel (better: the SLIP interface) the new value.

goto label
    Goto the label in the active command script. If the label is not found, the error level will be set to -1 and execution continues at the next line. In test mode goto returns always -1.

help
    Prints all available commands.

if expr goto label
    Conditional command execution. An expression must look like this: "$variable relop value". The variable may be one of these: $errlvl, $locip, $rmtip or $counter. Relop may be: ==, !=, <, >, >= or <=, and value is an integer.

Note:
    The executions of the if-test does not change the error level from previous commands, so there is the chance to a few comparisons depending on one wait. If the goto is executed, the error level changes to zero for successful execution.

inc $counter [value]
    Increase the internal counter variable by one (default, if no third parameter given) or by the value.

init init-string
    Set the internal modem init string to the given value. There must not be any white spaces in the string! Dip default is the string "ATE0Q0V1X1". Newline and carriage return codes are appended automatically.

mode protocol-name
    Set the desired protocol (at the moment only SLIP and CLIP are implemented), register routing and interface usage (using route(8) and ifconfig(8) or execute the shell script given via option -s /setup on the command line). Then become a daemon and wait for an external signal. So, in normal cases, the script should never reach the following command lines. The only way to reach these command lines following a mode command is due to a lost carrier or an error while creating the desired pid file (see option -f file ). A lost carrier results in an errorlevel of +1, the pid file error in a -1. Have a look at the sample dip scripts how to handle these two cases.

modem modem-type
    Chose modem type to use. At the moment there is only one type: HAYES. And because of that, this is default and there is no chance to change the type. It is better to forget this command at once... :-)

parity E|O|N
    Set the parity to Even, Odd or None. Default is None and there is no need to change this for normal [C]SLIP usage.

print [text]
    Print out the given text which may contain white spaces. Maximum length is about 1000 Bytes. Print without parameters results in an empty line. Allowed to print are also variables: $errlvl, $local, $locip, $remote, $rmtip, $netmask, $modem, $port, $speed, $mtu and $counter.

port dev-name
    Set dev-name as the active port. Dev-name may contain the prefix "/dev/".

reset
    Reset the modem if it is defined via modem and port. For HAYES modems the reset sequence consists of: Wait one second, send "+++" and wait another second. Then send "ATZ". To check whether the modem is operational, try the command wait 2 OK. It must set the error level to 1 in maximal 2 seconds (see also wait command).

send text
    Sends the given text to the modem or even to the remote site if connected to an other system. The text may contain white spaces and the special C-like characters (see above).

sleep time
    Wait for time seconds.

speed value
    Set terminal speed. Possible values are: 50, 75, 110, 134, 150, 200, 300, 600, 1200, 1800, 2400, 4800, 7200, 9600, 14400, 19200, 28800, 38400, 57600, 76800, 115200 and 230400, but not all of them are supported by most modems! And there is another pit: Very high baud rates (> 57600 baud) require a very fast computer and a minimum of processor load! Otherwise there will be lost IP packets and/or syslog messages like "comX: N silo overflows".

stopbits 1|2
    Set the number of stopbits to use. Possible values are 1 and 2. Default is 1.

term
    Enter terminal mode. This is only possible, if modem and port are properly set. In this mode normal modem commands may be given.

Note:
    No character will be interpreted, for example, there will be no delete key etc.! To leave the terminal mode, type Ctrl+A or Ctrl+] (latter key sequence isn't available on some [german] keyboard layouts).

wait timeout text1 [text2 ... text10]
    Wait is a complex command like get. Here a timeout parameter must be given. Setting up to ten text string parameters, there are also ten error levels (1-10) depending on the number of parameters given. Separation of parameters is done by white spaces, so no real spaces are allowed in the text strings. If desired, use '\s' instead.

Note 1:
    There are three possibilities for the timeout value (like the one given at the get command). The value -1 means "wait until one of the desired strings is received", this can lead in an indefinit loop!. A 0 stays for "just test the actual buffer against the strings but do not wait for characters to arraive". The third way is the normally used: "read the input a check for the maximal then strings and return, if they do not arrived within the number of seconds".

Note 2:
    It's often enough to use values between 2 and 60 seconds. An error level of -1 stays for timeout or usage error. -2 occurs, if the timeout value was 0 and no desired string could be found in the buffer.

The above command descriptions are absolutely not complete! There are some more features (esp. error levels and return codes), but it does not make much sense to tell all about them. Interested people should take a look at the sources.

DIALIN MODE
The second possible way of using dip is as a login shell for incoming IP connections, as in dialup SLIP and PPP connections.

Note:
    I have no chance and possibility to test this mode. So I believe the original sources and the man page, that dip will do it well. I will give no warranty!!!

To make integration into the existing UNIX system as easy as possible, dip can be installed as simply as using it as a login shell in the system's password file. A sample entry looks like:

suunet:ij/SMxiTlGVCo:1004:10:UUNET:/tmp:/sbin/dip -i

When user suunet logs in, the login(1) program sets the home directory to "/tmp" , and executes the dip program with the -i option, which means that dip must run in input mode. Dip then tries to locate the name of the logged in user (i.e. the name corresponding to its current user id, as returned by the getuid(2) system call) in its database file. An optional single argument to the dip program in this mode can be the username that must be used in this lookup, regardless the current user id.

Dip now scans the /etc/diphosts file for an entry for the given user name. This file contains lines of text (much like the standard password file). The format looks like:

    #
    # diphosts	This file describes a number of name-to-
    #		address mappings for the DIP program. It
    #		is used to determine which IP address to
    #		use for an incoming call of some user.
    #
    suunet::uunet.uu.net:UUNET SLIP:SLIP,296
    # End of diphosts.

The first field of a line identifies the user name, which we must match. The second field can contain an encrypted password. If this field is non-null, the dip program asks for an external security password , which must match the password in this field. The third field contains the name (or raw IP address) of the host that is connecting to the system with this link. If a host name is given, the usual address resolving process is started, using either a name server or a local hosts file.

The fourth field may contain any text, it is not (yet) used by the dip program. In future releases, this info may be used in the system log files. Finally, the fifth field of a line contains a mixture of comma-separated flags. Possible flags are:

[C]SLIP
    to indicate we must use the SLIP [CSLIP] protocol.

,number
    which gives the MTU parameter of this connection. The comma is required to separate the flags.

After finding the correct line, dip puts the terminal line into raw mode, and asks the system networking layer to allocate a channel of the desired protocol. Finally, if the channel is activated, it adds an entry to the system's routing table to make the connection work.

Dip now goes into an endless loop of sleeping, which continues until the connection is physically aborted (i.e. the line is dropped or dip has been killed). At that time, dip removes the entry it made in the system's routing table, and releases the protocol channel for re-use. It then exits, making room for another session.

DIALOUT MODE
The last way of using dip is as a program that initiates outgoing connections. To make life easier for the people who have to manage links of this type, dip uses a chat script to set up a link to a remote system. This gives the user an enourmous amount of flexibility when making the connection, which otherwise could require many command-line options.

The path name of the script to be run is then given as the single argument to dip; the program will automatically check if the file has a file name ending in a ".dip" part. This is not mandatory, just a tool to group scripts together in a single directory.

EXAMPLES

dip -i

diplogin
    Use the dip program in host mode.

dip -k -f sunnet
    Kill the running dip daemon using the pid stored in the file /var/run/dip.sunnet.pid.

dip -t -v
    Invoke dip in test mode and be verbose.

dip -v sunnet.dip
    Invoke the dip program in dialout mode and be verbose. Then execute the command file "sunnet.dip" line by line.

DIAGNOSTICS
Look for error messages on stderr and in /var/log/messages ( dip can behave as a daemon). Messages indicating the specified interface does not exist, the requested address is unknown, the user is not privileged and tried to alter an interface's configuration are logged. Dip also logs failure to set the controlling terminal or failure to install signal handlers.

FILES
/etc/hosts
/etc/passwd
/etc/master.passwd
    Get necessary information about the accessing user and networks.

/etc/diphosts
    This file describes a number of names to address mappings for the dip program. It is used to determine which IP address to use for an incoming call of some user.

/var/run/dip.<file>.pid
    with <file> replaced by a given -f file name paramter. The file contains the numerical process ID of the dip process and can be examined by scripts in order to send a signal to the attached dip. The file is only then created, when dip is about to get a daemon.

/var/spool/uucp/LCK..<tty>
    with <tty> replaced by the used tty port. Filelength should be zero, owner the user uucp.

SEE ALSO
netstat(1), netintro(4), ifconfig(8), route(8), syslogd(8)

AUTHORS
BSD version:
    Joachim Bartz, injb@sun.rz.tu-clausthal.de

Linux versions:
    Fred N. van Kempen, waltje@uwalt.nl.mugnet.org
    Paul Mossip, <mossip@vizlab.rutgers.edu>
    Jeff Uphoff, <juphoff@aoc.nrao.edu>
    Jim Seagrave, <jes@grendel.demon.co.uk>
    Olaf Kirch, <okir@monad.sub.de>

Note:
    Please do not ask the latter concerning this BSD dip version. They are not responsible for this version.

    If you have any question or bug report or ... please feel free to write me (Joachim Bartz) an email and I'll try to help.

BSD NOTES
The BSD port was adapted (and slightly improved) by Joachim Bartz from the original dip written by Fred N. van Kempen for Linux.

As I mentioned before, under BSD systems it seems to be, that changing the SLIP MTU is impossible! I spend a lot of time looking for a system call and found SIOCSIFMTU, but it does not work on SLIP interfaces!