..\" 3/5/95 man page updated by Jim Van Zandt <jrv@vanzandt.mv.com>
.TH DIP "8" "3/7/95" "Version 3.3.7n" "Reference"
.SH NAME
dip - handle dialup IP connections
.SH SYNOPSIS
\fBdip\fP [\fB-v\fP] [\fB-m\fP \fImtu\fP] [\fB-p\fP \fIproto\fP] \fIscriptfile\fP
.br
\fBdip -t\fP [\fB-v\fP]
.br
\fBdip -i\fP [\fB-a\fP] [\fB-v\fP]
.br
.BR diplogin
[\fIusername\fP]
.br
.BR diplogini
.br
\fBdip \fP[\fB-v\fP] \fB-k\fP [\fB-l\fP \fItty_line\fP]
.SH DESCRIPTION
\fBdip\fP 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. The outgoing connections
use the system's \fBdial\fP(3) library if available.
.PP
The first form interprets \fIscriptfile\fP to dial out and open an IP connection
(see \fBDIALOUT MODE\fP below).
.PP
The \fB-t\fP option runs \fBdip\fP interactively (see \fBCOMMAND MODE\fP below).
This is most useful while gathering data to set up a chat script.
.PP
\fBdip -i\fP handles incoming connections (see \fBDIALIN MODE\fP below).
\fBdiplogin\fP is equivalent to \fBdip -i\fP, and \fPdiplogini\fP
is equivalent to \fBdip -i -a\fP. These are mainly for use with
versions of \fBlogin\fP(1) that do not pass command line
parameters to the shell program.
.PP
\fBdip -k\fP kills an existing \fBdip\fP process, closing the connection.
.SH OPTIONS
.IP \fB-a\fP
Prompt for user name and password.
.IP \fB-i\fP
Act as a dialin server (see \fBDIALIN MODE\fP below).
.IP \fB-k\fP
Kill the \fBdip\fP process that runs (has locked) the specified tty device
(see \fB-l\fP option),
or else the most recent invocation of \fBdip\fP.
Note that \fBdip\fP
takes care not to kill a process started by somebody
else (unless it's root who demands the operation :-).
.IP "\fB-l\fP \fItty_line\fP"
Indicate the line to be killed. (Requires \fB-k\fP option.)
.IP "\fB-m\fP \fImtu\fP"
Set the Maximum Transfer Unit (MTU) (default 296).
.IP "\fB-p\fP \fIproto\fP"
Set the line protocol. \fIproto\fP must be one of: SLIP, CSLIP, PPP, or TERM.
.IP \fB-t\fP
Run in test mode (see \fBCOMMAND MODE\fP below).
.IP \fB-v\fP
Set verbose mode. This enables various debug printouts, including
an echo of each line of the chat script.
.SH "COMMAND MODE"
The first possible use of
.B dip
is as an interactive program to set up an outgoing IP connection.
This can be done by invoking
.B dip
with the
.B -t
option, which means
.B "enter TEST mode"
and, more precisely, dumps you in the
.B COMMAND-MODE
of the dip program. You are reminded of this by the
.B "DIP> "
prompt, or, if you also specified the
.B -v
debugging flag, the
.B "DIP [NNNN]> "
prompt. The latter prompt also displays the current value of the
global
.B $errlvl
variable, which is used mostly when dip runs in
.B script
mode. For the interactive mode, it can be used to determine if the
result of the previous command was OK or not.
.PP
The following is a sample taken from a live session:
.br
.sp 1
.nf
$dip -t
DIP: Dialup IP Protocol Driver version 3.3.7n-uri (7 Mar 95)
Written by Fred N. van Kempen, MicroWalt Corporation.
DIP> _
.fi
.sp 1
The possible commands are listed below (see \fBCOMMANDS\fP).
Note particularly the \fBhelp\fP command.
Each command displays a usage message if it is
invoked incorrectly. Just experiment a little
to get the feel of it, and have a look at the sample script
file, which also uses this command language (see \fBEXAMPLES\fP).
.SH "DIALOUT MODE"
The second way of using
.B dip
is to initiate outgoing connections.
To make life easier for the people who have to manage links of this type,
.B dip
uses a
.B "chat script"
to set up a link to a remote system. This gives the user an
enormous 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 \fBdip\fP. If \fIscriptfile\fP
has no file extension, \fBdip\fP will automatically add the extension \fB".dip"\fP.
This is just a way to group scripts together in a single directory.
.SH "DIALIN MODE"
The third possible way of using
.B dip
is as a login shell for incoming IP connections, as in dialup
SLIP and PPP connections. To make integration into the existing
UNIX system as easy as possible,
.B dip
can be installed by simply naming it as the login shell in \fI/etc/passwd\fP.
A sample entry looks like:
.sp 1
.nf
suunet:ij/SMxiTlGVCo:1004:10:UUNET:/tmp:/usr/sbin/diplogin
.fi
.sp 1
When user
.B suunet
logs in, the
.BR login (1)
program sets the home directory to \fI/tmp\fP and executes the
.B diplogin
program. \fBdiplogin\fP should be a symbolic link to
\fBdip\fP, which means that
.B dip
must run in
.B input
mode.
.B 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
.BR getuid (2)
system call) in its database file. An optional single argument
to the
.B dip
program in this mode can be the username that must be used in
this lookup, regardless the current user id.
.PP
.B dip
now scans \fI/etc/diphosts\fP for an entry for the given user name.
This file contains lines of text (much like the standard password file).
Any line starting with \fB#\fP is a comment.
Otherwise, each line has seven colon-separated items, in the format
.nf
user : password : remote host : local host : netmask :
comments : protocol,MTU
.fi
The first field of a line is the user name, which we must
match.
.PP
The second field can contain an encrypted password. If this
field is non-null,
.B dip
displays the prompt "\fBExternal security password:\fP", and the reply must
match the password in this field. If this field is
"s/key" (check the value of \fBSKEY_TOKEN\fP in \fIdip.h\fP) and \fBdip\fP
was compiled with S/Key enabled, then S/Key authentication
will take place (see \fIREADME.SKEY\fP in the \fBdip\fP source directory).
.PP
The third field
contains the name (or raw IP address) of the remote host.
If a host name is given, the usual
address resolving process is started, using either a name server or
a local hosts file.
.PP
The fourth field contains the name (or raw IP address) of the local host.
If a host name is given, it's resolved, just like the remote
host name in the third field.
.PP
The fifth field contains the netmask in decimal dotted notation
(like 255.255.255.0). If empty, 255.255.255.0 is used by default.
.PP
The sixth field may contain any text; it is not used by \fBdip\fP.
.PP
Finally, the seventh field of a line contains a mixture
of comma-separated flags. Possible flags are:
.sp 1
.ti +.2i
.B SLIP
to indicate we must use the SLIP protocol.
.br
.ti +.2i
.B CSLIP
to indicate Compressed SLIP protocol.
.br
.ti +.2i
.B PPP
to indicate we must use the PPP protocol.
.br
.ti +.2i
.B number
which gives the MTU parameter of this connection.
.sp 1
Please note: my experience shows smaller blocks (i.e. smaller MTU) work
better. You *can* define MTU 1500, but it won't vouch for your sanity.
.PP
After finding the correct line,
.B dip
puts the terminal line into
.B 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
.B routing
table to make the connection work.
.PP
.B dip
now goes into an endless loop of sleeping, which continues until
the connection is physically aborted (i.e. the line is dropped).
At that time,
.B 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.
.SH COMMANDS
The following may appear in a chat script. Most can also be used
in command mode:
.IP \fIlabel\fP\fB:\fP
Define a label.
.IP "\fBbeep\fP [\fItimes\fP]"
Beep on user's terminal [this many times].
.IP "\fBbootp\fP [\fIhowmany\fP [\fIhowlong\fP]]"
Use BOOTP protocol to fetch local and remote IP addresses.
.IP \fBbreak\fP
Send a BREAK.
.IP "\fBchatkey\fP \fIkeyword\fP [\fIcode\fP]"
Add to \fBdip\fP's collection of modem response words.
For example,
.br
.nf
\fBchatkey CONNECT 1\fP
.fi
would duplicate one of the existing entries.
.IP "\fBconfig\fP [\fBinterface\fP|\fBrouting\fP] [\fBpre\fP|\fBup\fP|\fBdown\fP|\fBpost\fP] {\fIarguments...\fP}"
Store interface configuration parameters.
(This may be disabled by the administrator.)
.IP "\fBdatabits 7\fP|\fB8\fP"
Set the number of data bits.
.IP "\fBdec\fP \fI$variable\fP [\fIdecrement-value\fP|\fI$variable\fP]"
Decrement a variable. The default \fIdecrement-value\fP is 1.
.IP \fBdefault\fP
Tells DIP to set up the default route to the remote host it made a connection
to. If this command isn't present in the command file, the default route
won't be set/changed.
.IP "\fBdial\fP \fIphonenumber\fP [\fItimeout\fP]"
Dials the indicated number. The default \fItimeout\fP is 60 sec.
\fBdip\fP parses the string returned by the modem, and sets \fB$errlvl\fP
accordingly. The standard codes are as follows:
.nf
0 OK
1 CONNECT
2 ERROR
3 BUSY
4 NO CARRIER
5 NO DIALTONE
.fi
You can change or add to these with the \fBchatkey\fP command.
.IP "\fBecho\fP \fBon\fP|\fBoff\fP"
Enables or disables the display of modem commands.
.IP "\fBexit\fP [\fIexit-status\fP]"
Exit script leaving established [C]SLIP connection intact and \fBdip\fP running.
.IP \fBflush\fP
Flush input on the terminal.
.IP "\fBget\fP \fI$variable\fP [\fIvalue\fP | \fBask\fP | \fBremote\fP [\fItimeout_value\fP | \fI$variable\fP]]
Get or ask for the value of a variable.
If the second parameter is \fBask\fP, a prompt is printed and the value
is read from standard input. If it is \fBremote\fP, it is read
from the remote machine. Otherwise, the second parameter is a constant
or another variable which supplies the value.
.IP "\fBgoto\fP \fIlabel\fP"
Transfer control to the indicated label in the chat script.
.IP \fBhelp\fP
Print list of commands, similar to this:
.sp 1
.nf
DIP> help
DIP knows about the following commands:
beep bootp break chatkey config databits
dec default dial echo flush get
goto help if inc init mode
modem netmask parity password proxyarp print
port quit reset securidf securid send
sleep speed stopbits term timeout wait
DIP> _
.sp 1
.fi
.IP "\fBif\fP \fIexpr\fP \fBgoto\fP \fIlabel\fP"
Test some result code. The \fIexpr\fP must have the form
.nf
\fI$variable op constant\fP
.fi
where \fIop\fP is one of: \fB== != < > <= >=\fP.
.IP "\fBinc\fP \fI$variable\fP [\fIincrement-value\fP|\fI$variable\fP]"
Increment a variable. The default \fIincrement-value\fP is 1.
.IP "\fBinit\fP \fIinit-string\fP"
Set the initialization string (sent to the modem before
dialing) to the indicated string (default ATE0 Q0 V1 X1).
\fIPlease\fP use it!
.IP "\fBmode SLIP\fP|\fBCSLIP\fP|\fBPPP\fP|\fBTERM\fP"
Set the line protocol (default SLIP).
.IP "\fBmodem\fP \fImodem-name\fP"
Set the type of modem.
(The default, and at present the only legal value, is HAYES).
.IP "\fBnetmask\fP \fIxxx.xxx.xxx.xxx\fP"
Indicate the netmask we will want to use.
.IP "\fBparity E\fP|\fBO\fP|\fBN\fP"
Set the type of parity.
.IP \fBpassword\fP
Prompt for a password and send it.
.IP \fBproxyarp\fP
Request Proxy ARP to be set.
.IP "\fBprint\fP \fI$variable\fP"
Print the contents of some variable.
.IP "\fBport\fP \fItty_name\fP"
Set the name of the terminal port to use. (The path \fI/dev/\fP is assumed.)
.IP \fBquit\fP
Exit with nonzero exit status.
.IP \fBreset\fP
Reset the modem. (Sends "+++" then "ATZ".)
.IP "\fBsecuridf\fP \fIfixedpart\fP"
Store the fixed part of the SecureID password.
.IP \fBsecurid\fP
Prompt for the variable part of the password generated
by the ACE System SecureID card.
The fixed part of the password must already have been stored
using a \fBsecureidf\fP command.
The two parts are concatenated and sent to the remote terminal server.
.IP "\fBsend\fP \fItext-string\fP"
Send a string to the serial driver.
.IP "\fBskey\fP [\fItimeout\fP | \fI$variable\fP]"
This tells \fBdip\fP to look for an S/Key challenge from the remote
terminal server. \fBdip\fP then prompts the user for the secret
password, generates the response, and sends it to the remote host. The
optional parameter \fItimeout\fP sets how long \fBdip\fP is to wait to
see the challenge. \fB$errlvl\fP is set to 1 if the \fBskey\fP command
times out. If \fBskey\fP successfully sends a response, \fB$errlvl\fP is
set to 0. Requires S/Key support to be compiled in.
.IP "\fBsleep\fP \fItime-in-secs\fP"
Wait some time.
.IP "\fBspeed\fP \fIbits-per-sec\fP"
Set port speed (default 38400).
Note that the actual speed associated with "38400" can be changed
using \fBsetserial\fP(8). Also, you should tell port's \fBreal\fP
speed here, as \fBdip\fP takes care of the \fIset_hi\fP and such
bits by itself. Also, don't be afraid, if you told the speed
"57600" and it reports back "38400" - everything's OK, the
proper flags were applied and the real port speed will be
what you told it to be, i.e. "57600".
.IP "\fBstopbits 1\fP|\fB2\fP"
Set the number of stop bits.
.IP \fBterm\fP
Enter a terminal mode.
.IP "\fBtimeout\fP \fItime-in-sec\fP"
Set timeout. This defines the period of inactivity on the line, after
which DIP will force the line down and break the connection (and exit).
.IP "\fBwait\fP \fItext \fP[\fItimeout_value\fP | \fI$variable\fP]"
Wait for some string to arrive.
.PP
.SS "SPECIAL VARIABLES"
.IP \fB$errlvl\fP
Holds the result of the previous command.
.IP \fB$locip\fP
IP number of local host in dotted quad notation (for example, 128.96.41.50).
.IP \fB$local\fP
Fully qualified local host name (for example, sunsite.unc.edu).
.IP \fB$rmtip\fP
IP number of remote host in dotted quad notation.
.IP \fB$remote\fP
Fully qualified remote host name.
.IP \fB$mtu\fP
Maximum Transfer Unit (maximum number of bytes transferred at once).
.IP \fB$modem\fP
Modem type (at present the only valid value is HAYES).
.IP \fB$port\fP
The name of the terminal port to use. (The path \fI/dev/\fP is assumed.)
.IP \fB$speed\fP
Transfer rate between the local host and the modem, in bits/sec.
.SH EXAMPLES
Here is a sample \fI/etc/diphosts\fP:
.sp 1
.ft B
.nf
#
# diphosts This file describes a number of name-to-address
# mappings for the DIP program. It is used to determine
# which host IP address to use for an incoming call of
# some user.
#
# Version: @(#)diphosts 1.20 05/31/94
#
# Author: Fred N. van Kempen, <waltje@uwalt.nl.mugnet.org>
# Modified: Uri Blumenthal <uri@watson.ibm.com>
#
# name : pwd : hostname : local server: netmask: comments : protocol,mtu
#==================================================
sbonjovi::bonjovi:server1:netmask:MicroWalt "bonjovi" SLIP:SLIP,296
sroxette::roxette:server2:netmask:MicroWalt "roxette" SLIP:CSLIP,296
stephen:s/key:tuin:server3:netmask:S/Key Authenticated login:CSLIP,296
# End of diphosts.
.ft P
.fi
.sp 1
A chat script should look something like this:
.sp 1
.ft B
.nf
#
# sample.dip Dialup IP connection support program.
#
# Version: @(#)sample.dip 1.40 07/20/93
#
# Author: Fred N. van Kempen, <waltje@uWalt.NL.Mugnet.ORG>
#
main:
# First of all, set up our name for this connection.
# I am called "uwalt.hacktic.nl" (== 193.78.33.238)
get $local uwalt.hacktic.nl
# Next, set up the other side's name and address.
# My dialin machine is called 'xs4all.hacktic.nl' (== 193.78.33.42)
get $remote xs4all.hacktic.nl
# Set netmask on sl0 to 255.255.255.0
netmask 255.255.255.0
# Set the desired serial port and speed.
port cua02
speed 38400
# Reset the modem and terminal line.
# This seems to cause trouble for some people!
reset
# Note! "Standard" pre-defined "errlvl" values:
# 0 - OK
# 1 - CONNECT
# 2 - ERROR
# 3 - BUSY
# 4 - NO CARRIER
# 5 - NO DIALTONE
#
# You can change these with the chatkey command
# Prepare for dialing.
send ATQ0V1E1X4\\r
wait OK 2
if $errlvl != 0 goto modem_trouble
dial 555-1234567
if $errlvl != 1 goto modem_trouble
# We are connected. Login to the system.
login:
sleep 2
wait ogin: 20
if $errlvl != 0 goto login_error
send MYLOGIN\\n
wait ord: 20
if $errlvl != 0 goto password_error
send MYPASSWD\\n
loggedin:
# We are now logged in.
wait SOMETEXT 15
if $errlvl != 0 goto prompt_error
# Set up the SLIP operating parameters.
get $mtu 296
# Ensure "route add -net default xs4all.hacktic.nl" will be done
default
# Say hello and fire up!
done:
print CONNECTED $locip ---> $rmtip
mode CSLIP
goto exit
prompt_error:
print TIME-OUT waiting for SLIPlogin to fire up...
goto error
login_trouble:
print Trouble waiting for the Login: prompt...
goto error
password_error:
print Trouble waiting for the Password: prompt...
goto error
modem_trouble:
print Trouble occurred with the modem...
error:
print CONNECT FAILED to $remote
quit 1
exit:
exit
.fi
.ft P
.sp 1
This script causes
.B dip
to dial up a host, log in, and get a
.B SLIP
interface channel going (in the same manner as with incoming
connections). When all is set up, it simply goes into the background
and waits for a hangup (or just a lethal signal), at which it hangs
up and exits.
.SH FILES
.nf
.ft I
/etc/passwd
/etc/diphosts
/etc/rc.dip \fR(for example)\fP
.ft R
.fi
.SH BUGS
Virtually none - what you see are
.B features
(:-).
.SH AUTHORS
.nf
Fred N. van Kempen <waltje@uwalt.nl.mugnet.org>,
.br
Uri Blumenthal <uri@watson.ibm.com>,
.br
Paul Cadach <paul@paul.east.alma-ata.su>,
.br
John Edwards <pje120@cs.usask.ca>,
.br
Olaf Kirch <okir@monad.sub.de>,
.br
Pauline Middelink <middelin@calvin.iaf.nl>,
.br
Paul Mossip <mossip@vizlab.rutgers.edu>,
.br
Bill Reynolds,
.br
Jim Seagrave <jes@grendel.demon.co.uk>,
.br
Stephen Shortland <stephen@cork.cig.mot.com>,
.br
Daniel Suman,
.br
Jeff Uphoff <juphoff@aoc.nrao.edu>
.fi
.SH "SEE ALSO"
.BR login (1),
.BR skey (1),
.BR getuid (2),
.BR dial (3),
.BR ifconfig (8),
.BR netstat (8),
.BR route (8),
.BR setserial (8)