DIP(8)                      Reference                      DIP(8)

NAME
       dip - handle dialup IP connections

SYNOPSIS
       dip [-v] [-m mtu] [-p proto]  scriptfile
       dip -t [-v]
       dip -i [-a] [-v]
       diplogin [username]
       diplogini
       dip [-v] -k [-l tty_line]

DESCRIPTION
       dip  handles  the  connections needed for dialup IP links,
       like SLIP or PPP.  It can handle both incoming and  outgo-
       ing connections, using password security for incoming con-
       nections.   The  outgoing  connections  use  the  system's
       dial(3) library if available.

       The  first form interprets scriptfile to dial out and open
       an IP connection (see DIALOUT MODE below).

       The -t option runs dip  interactively  (see  COMMAND  MODE
       below).   This  is most useful while gathering data to set
       up a chat script.

       dip -i  handles  incoming  connections  (see  DIALIN  MODE
       below).   diplogin  is equivalent to dip -i, and diplogini
       is equivalent to dip -i -a.  These are mainly for use with
       versions of login(1) that do not pass command line parame-
       ters to the shell program.

       dip -k kills an existing dip process, closing the  connec-
       tion.

OPTIONS
       -a     Prompt for user name and password.

       -i     Act as a dialin server (see DIALIN MODE below).

       -k     Kill  the  dip  process  that runs (has locked) the
              specified tty device (see -l option), or  else  the
              most recent invocation of dip.  Note that dip takes
              care not to kill a process started by somebody else
              (unless it's root who demands the operation :-).

       -l tty_line
              Indicate  the  line  to  be  killed.   (Requires -k
              option.)

       -m mtu Set the Maximum Transfer Unit (MTU) (default  296).

       -p proto
              Set the line protocol.  proto must be one of: SLIP,
              CSLIP, PPP, or TERM.

       -t     Run in test mode (see COMMAND MODE below).

       -v     Set  verbose  mode.   This  enables  various  debug
              printouts,  including  an  echo of each line of the
              chat script.

COMMAND MODE
       The first possible use of dip is as an interactive 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 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  inter-
       active  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 version 3.3.7n-uri (7 Mar 95)
       Written by Fred N. van Kempen, MicroWalt Corporation.

       DIP> _

       The possible commands are  listed  below  (see  COMMANDS).
       Note particularly the help command.  Each command displays
       a usage message if it is invoked incorrectly.  Just exper-
       iment  a  little to get the feel of it, and have a look at
       the sample script file, which also uses this command  lan-
       guage (see EXAMPLES).

DIALOUT MODE
       The  second  way of using dip is to initiate outgoing con-
       nections.  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
       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 dip.  If scriptfile has no file  exten-
       sion,  dip  will  automatically  add the extension ".dip".
       This is just a way to group scripts together in  a  single
       directory.

DIALIN MODE
       The  third  possible  way of using 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, dip can be installed by simply
       naming  it  as  the  login shell in /etc/passwd.  A sample
       entry looks like:

       suunet:ij/SMxiTlGVCo:1004:10:UUNET:/tmp:/usr/sbin/diplogin

       When user suunet logs in, the login(1)  program  sets  the
       home  directory to /tmp and executes the diplogin program.
       diplogin should be a symbolic link  to  dip,  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  correspond-
       ing  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 user-
       name that must be used in this lookup, regardless the cur-
       rent user id.

       dip  now  scans  /etc/diphosts  for an entry for the given
       user name.  This file contains lines of  text  (much  like
       the  standard password file).  Any line starting with # is
       a comment.  Otherwise, each line has seven colon-separated
       items, in the format

       user : password : remote host : local host : netmask :
             comments : protocol,MTU

       The  first field of a line is the user name, which we must
       match.

       The second field can contain an  encrypted  password.   If
       this  field is non-null, dip displays the prompt "External
       security password:", and the reply must match the password
       in  this field.  If this field is "s/key" (check the value
       of SKEY_TOKEN in dip.h) and dip was  compiled  with  S/Key
       enabled,  then  S/Key  authentication will take place (see
       README.SKEY in the dip source directory).

       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.

       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.

       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.

       The  sixth  field  may contain any text; it is not used by
       dip.

       Finally, the seventh field of a line contains a mixture of
       comma-separated flags.  Possible flags are:

         SLIP to indicate we must use the SLIP protocol.
         CSLIP to indicate Compressed SLIP protocol.
         PPP to indicate we must use the PPP protocol.
         number which gives the MTU parameter of this connection.

       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.

       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  con-
       tinues  until  the  connection is physically aborted (i.e.
       the line is dropped).  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.

COMMANDS
       The  following may appear in a chat script.  Most can also
       be used in command mode:

       label: Define a label.

       beep [times]
              Beep on user's terminal [this many times].

       bootp [howmany [howlong]]
              Use BOOTP protocol to fetch  local  and  remote  IP
              addresses.

       break  Send a BREAK.

       chatkey keyword [code]
              Add  to  dip's  collection of modem response words.
              For example,
              chatkey CONNECT 1
              would duplicate one of the existing entries.

       config [interface|routing] [pre|up|down|post] {argu-
              ments...}
              Store  interface  configuration  parameters.  (This
              may be disabled by the administrator.)

       databits 7|8
              Set the number of data bits.

       dec $variable [decrement-value|$variable]
              Decrement a variable.  The default  decrement-value
              is 1.

       default
              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.

       dial phonenumber [timeout]
              Dials the indicated number.  The default timeout is
              60  sec.   dip  parses  the  string returned by the
              modem, and sets $errlvl accordingly.  The  standard
              codes are as follows:
                   0    OK
                   1    CONNECT
                   2    ERROR
                   3    BUSY
                   4    NO CARRIER
                   5    NO DIALTONE
              You  can  change  or  add to these with the chatkey
              command.

       echo on|off
              Enables or disables the display of modem  commands.

       exit [exit-status]
              Exit  script leaving established [C]SLIP connection
              intact and dip running.

       flush  Flush input on the terminal.

       get $variable [value | ask | remote [timeout_value |
              $variable]]
              Get  or  ask  for  the value of a variable.  If the
              second parameter is ask, a prompt  is  printed  and
              the  value  is  read from standard input.  If it is
              remote, it is read from the remote machine.  Other-
              wise, the second parameter is a constant or another
              variable which supplies the value.

       goto label
              Transfer control to the indicated label in the chat
              script.

       help   Print list of commands, similar to this:

              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  onexit   parity   password proxyarp
                      print    port     quit     reset    securidf securid
                      send     shell    sleep    speed    stopbits term
                      timeout  wait

              DIP> _

       if expr goto label
              Test some result code.  The expr must have the form
              $variable op constant
              where op is one of: == != < > <= >=.

       inc $variable [increment-value|$variable]
              Increment a variable.  The default  increment-value
              is 1.

       init init-string
              Set  the  initialization  string (sent to the modem
              before dialing) to the  indicated  string  (default
              ATE0 Q0 V1 X1).  Please use it!

       mode SLIP|CSLIP|PPP|TERM
              Set the line protocol (default SLIP).

       modem modem-name
              Set  the  type of modem.  (The default, and at pre-
              sent the only legal value, is HAYES).

       netmask xxx.xxx.xxx.xxx
              Indicate the netmask we will want to use.

       onexit .......
              Description is missing - look through the source in
              command.c.   Or  ask <inaky@@peloncho.fis.ucm.es> -
              he wrote it (:-).

       parity E|O|N
              Set the type of parity.

       password
              Prompt for a password and send it.

       proxyarp
              Request Proxy ARP to be set.

       print $variable
              Print the contents of some variable.

       psend command [arguments]
              Send the output of command to  the  serial  driver,
              optionally passing arguments to command. The UID is
              reset to the real UID before running command.

       port tty_name
              Set the name of the terminal  port  to  use.   (The
              path /dev/ is assumed.)

       quit   Exit with nonzero exit status.

       reset  Reset the modem.  (Sends "+++" then "ATZ".)

       securidf fixedpart
              Store the fixed part of the SecureID password.

       securid
              Prompt for the variable part of the password gener-
              ated by the ACE System SecureID  card.   The  fixed
              part  of the password must already have been stored
              using a secureidf command.  The two parts are  con-
              catenated and sent to the remote terminal server.

       send text-string
              Send a string to the serial driver.

       shell command [parameters]
              Executes   command   through   the   default  shell
              (obtained from the SHELL variable) with  parameters
              as  the  command-line arguments.  Dip variable sub-
              stitution is performed before  executing  the  com-
              mand.  If you don't want a parameter beginning with
              a $ to be interpreted as a dip variable, precede it
              with a \.

       skey [timeout | $variable]
              This  tells dip to look for an S/Key challenge from
              the remote terminal server.  dip then  prompts  the
              user   for   the  secret  password,  generates  the
              response, and sends it to  the  remote  host.   The
              optional  parameter timeout sets how long dip is to
              wait to see the challenge.  $errlvl is set to 1  if
              the  skey  command  times out. If skey successfully
              sends a response, $errlvl is set  to  0.   Requires
              S/Key support to be compiled in.

       sleep time-in-secs
              Wait some time.

       speed bits-per-sec
              Set  port  speed  (default  38400).   Note that the
              actual speed associated with "38400" can be changed
              using  setserial(8).  Also,  you should tell port's
              real speed here, as dip takes care  of  the  set_hi
              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".

       stopbits 1|2
              Set the number of stop bits.

       term   Enter a terminal mode.

       timeout time-in-sec
              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).

       wait text [timeout_value | $variable]
              Wait for some string to arrive.

   SPECIAL VARIABLES
       $errlvl
              Holds the result of the previous command.

       $locip IP  number  of  local  host in dotted quad notation
              (for example, 128.96.41.50).

       $local Fully qualified local host name (for example,  sun-
              site.unc.edu).

       $rmtip IP number of remote host in dotted quad notation.

       $remote
              Fully qualified remote host name.

       $mtu   Maximum  Transfer  Unit  (maximum  number  of bytes
              transferred at once).

       $modem Modem type (at present  the  only  valid  value  is
              HAYES).

       $port  The  name  of  the terminal port to use.  (The path
              /dev/ is assumed.)

       $speed Transfer rate between the local host and the modem,
              in bits/sec.

EXAMPLES
       Here is a sample /etc/diphosts:

       #
       # 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.

       A chat script should look something like this:

       #
       # 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

       This  script causes dip to dial up a host, log in, and get
       a 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.

FILES
       /etc/passwd
       /etc/diphosts
       /etc/rc.dip (for example)

BUGS
       Virtually none - what you see are features (:-).

AUTHORS
       Fred N. van Kempen <waltje@uwalt.nl.mugnet.org>,
       Uri Blumenthal <uri@watson.ibm.com>,
       Paul Cadach <paul@paul.east.alma-ata.su>,
       John Edwards <pje120@cs.usask.ca>,
       Olaf Kirch <okir@monad.sub.de>,
       Pauline Middelink <middelin@calvin.iaf.nl>,
       Paul Mossip <mossip@vizlab.rutgers.edu>,
       Bill Reynolds,
       Jim Seagrave <jes@grendel.demon.co.uk>,
       Stephen Shortland <stephen@cork.cig.mot.com>,
       Daniel Suman,
       Jeff Uphoff <juphoff@aoc.nrao.edu>

SEE ALSO
       login(1),  skey(1),  getuid(2), dial(3), ifconfig(8), net-
       stat(8), route(8), setserial(8)

Version 3.3.7o                3/7/95                            1