
				README FOR DSLIP 2.03

(0)

    (c)Copyright 1994, Matthew Dillon, All rights reserved.  This code may
    be used in any project, commercial or otherwise, as long as I am given
    appropriate credit and as long as this copyright remains intact in all
    source and document files.

    MASTER DISTRIBUTION IS ON: apollo.west.oic.com in the directory
                               pub/linux/dillon_src

    NOTE!!! This relase is COMPLETELY DIFFERENT from dslip101.tgz

    Matthew Dillon		dillon@apollo.west.oic.com
    1005 Apollo Way		ham: KC6LVW (no mail drop)
    Incline Village, NV. 89451	Obvious Implementations Corporation
    USA 			Sandel-Avery Engineering
    [always include a portion of the original email in any response!]


(I) INSTALLATION

    You need to create a 'slip' user and two groups: 'slip' and 'slipown'.
    Also included below are sample dialin accounts "shuttle" and "voyager".
    These are not required if you are only doing dialout slip.

	--- example passwd entries ---
	slip:*:1088:1089::/etc/slip:*
	shuttle:*:1088:1089:Shuttle SLIP,,,:/:/etc/slip/dialin/slipin_mason
	voyager:*:1088:1089:Voyager SLIP,,,:/:/etc/slip/dialin/slipin_junkie

	--- example group entries ---
	slip::1088:slip
	slipown::1089:slip

    Those people who are allowed to turn on and off SLIP lines should be
    put in the slip group.  NOBODY except user slip should be allowed in
    the slipown group since it effectively allows root access (since the
    dialin/dialout scripts must be run as root).

    After you create the appropriate user and groups, cd into /etc/ and
    unpack the archive.  Before unpacking, be sure to:

    --> The archive must be unpacked as root.

    --> You must have setup the 'slip' passwd and 'slip' and 'slipown'
    --> group entries.  'shuttle' and 'voyager' passwd entries are examples
    --> and not required for installation.

    --> If you already have /etc/slip, rename it so your existing configuration
    --> files do not get overwritten.

	cd /etc
	gunzip <dslip203.tar.gz | tar xvfp -


    The following is a listing of the /etc/slip heirarchy for critical files.
    The permissions and ownership are VERY important.

    	(note: file sizes shown below will not necessarily match the 
    	actual distribution)

	slip:
	total 19
	drwxrwxr-x   7 root     slipown      1024 Aug  4 11:15 ./
	drwxrwxrwt   4 root     wheel        2048 Aug  4 11:15 ../
	drwxr-x---   2 root     slip         1024 Aug  4 11:15 bin/
	drwxr-x---   2 root     wheel        1024 Aug  4 11:15 dialin/
	drwx------   2 root     wheel        1024 Aug  4 11:15 dialout/
	-rwx------   1 root     wheel         322 Aug  4 11:01 rc.slip*
	-rw-rw----   1 root     slipown      2361 Aug  4 10:37 runslip.conf
	drwxr-xr-x   2 root     wheel        1024 Aug  4 11:15 sample/
	drwxr-xr-x   2 root     wheel        1024 Aug  4 11:15 src/

	slip/bin:
	total 500
	-rwsr-x---   1 root     slipown      9220 Aug  4 11:15 allocslip*
	-rwx------   1 root     wheel       13316 Aug  4 11:15 dudiscdev*
	-rwxr-xr-x   1 root     wheel      439780 Sep 27  1993 expect*
	-rwxr-xr-x   1 root     wheel       17412 Aug  4 11:15 notty*
	-rwx------   1 root     wheel       13316 Aug  4 11:15 runslip*
	-rwxr-sr-x   1 root     slipown      9220 Aug  4 11:15 slipctl*

	slip/dialin:
	total 3
	-rwxr-x---   1 root     slipown       878 Aug  4 09:49 slipin_mason*

	slip/dialout:
	total 4
	-rwx------   1 root     wheel        1665 Aug  4 10:39 gbasin.xp*

    Note that the permissions are important.  For example, /etc/slip/bin
    MUST be group 'slip' so only people in the slip group can execute
    the 'slipctl' family of programs, and slipctl itself must be sgid-slipown
    so it can write.  Also, the 'allocslip' program is suid-root, so it must
    be group slipown so nobody can execute it outside of the passwd entry.
    the runslip.conf file should be writable by the slipown group for future
    compatibility.

    Modify the rc.slip file as appropriate... you may need to change the
    location of the log file.

        vi rc.slip
        .. change location of logfile if necessary ..

    Then, cd into /etc/slip and 'make install' to install the slipctl
    executables in /usr/local/bin.

    	cd /etc/slip
    	make install

    To continue without rebooting, you should 'rehash' any /bin/csh or 
    /bin/tcsh shells you have open so the shells can find the newly installed
    binaries.

    	rehash

(II) OPERATION

    Modify your /etc/rc.local or /etc/rc.net file, depending on how you
    have it organized, to add the following.  Note that slip should be
    started up AFTER you configure the lo interface and AFTER you configure
    any ethernet boards.  This is for consistancy and future compatibility.

	if [ -x /etc/slip/rc.slip ]; then
	    echo -n "slip "
	    /etc/slip/rc.slip
	fi

    You do not have to reboot, running /etc/slip/rc.slip manually is
    acceptable.  However, only run it once!  Note that /etc/slip/rc.slip 
    expects /usr/bin/killall to exist (kill processes by name).  Well,
    ok, if you have killall installed properly then you can re-run rc.slip
    as many times as you like :-)

    At this point, you can copy your old dslip scripts back and modify them
    as necessary, or modify the existing samples.  edit the "runslip.conf" 
    file.  The file contains two examples and a description of the 
    configuration variables.  You can setup as many slip connections as 
    you like.  The most confusing aspect of this file is the "ducmd" 
    entry, which might look like this:

	# runslip.conf file
	#
	# 
	name		fubar
	...
	ducmd		-e dialout/gbasin.xp -t 9

    The ducmd line specifies options to the dudiscdev program.  The dudiscdev
    program is responsible for managing a dialout connection.  The -e option
    specifies an expect script (/etc/slip/bin/expect) that is to perform the
    actual dialout command.  The -t option specifies the SLIP encapsulation
    to be used:

    	-t 0	SLIP
    	-t 1	CSLIP
    	-t 9	AUTO SLIP/CSLIP

    If you are not sure, try -t 0 first, then -t 9.

    The expect program script example, /etc/slip/dialout/gbasin.xp, should
    contain enough example code to allow you to create your own tcl based 
    expect scripts without having to download the expect or tcl distributions.

    If you do not want to use expect, you can use something else, simply
    change the shell script's #! line at the top to the appropriate program.
    The program will get the device on stdin and stdout and is expected
    to generate call-progress messages to stderr.  The program must return
    an exit code of 2 to indicate success, at which point dudiscdev will
    attach the slip interface.

(III) ENABLING AND DISABLING SLIP CONTROLS

    slipctl reload

    	Causes runslip to reload the runslip.conf file.  Any non-trivial
    	modifications made to runslip.conf will cause the effected
    	interface(s) to be reset.

    slipon <slipid> [<device>]

    	Enable a slip connection, optionally changing the dialout device in 
    	the runslip.conf configuration file.  If the connection is already
    	enabled and you specify a device different from the one currently
    	being used, this will cause a hangup and redial (roughly equivalent
    	to the slipreset command).

    	NOTE: for security reasons, if you specify a new device here the
    	device must already be referenced somewhere in the runslip.conf
    	file.

    slipoff <slipid>

    	Disable a slip connection.  <slipid> can be a symbolic name OR
    	a device name (such as /dev/cua0).

    slipreset <slipid> [<device>]

    	Reset a slip connection.  If the connection is currently enabled,
    	this will cause it to hangup and redial.  If the connection is
    	not currently enabled, nothing happens.  You may optionally specify
    	a new dialout device (which is remembered even if the connection is not
    	currently enabled).

    	<slipid> may be a symbolic name OR a device name such as /dev/cua0.

    	NOTE: for security reasons, if you specify a new device here the
    	device must already be referenced somewhere in the runslip.conf
    	file. 

    Once you believe you have your configuration and dialout scripts setup
    correctly, do:

    	slipctl reload

    If you have them diabled in runslip.conf by default, then enable one
    of them (say you called it 'test') with:

    	slipon test

    --> if the shell cannot find slipctl, slipon, or other executables,
    --> be sure you have 'rehash'd it and that /usr/local/bin is in your
    --> execution path.

    --> You can do these slip* commands as root.  Any user in the 'slip'
    --> group can also execute the slip* commands.

    You can enable or disable a SLIP connection at any time.  Furthermore, you
    can have a number of named configurations that use the same serial port.
    If you enable, say, 'test2' on /dev/cua0 and 'test1' on /dev/cua0 is
    already running, the slip control system will automatically disable
    'test1' before trying to connect test2.

    Whenever you make a modification to /etc/slip/runslip.conf you must
    run 'slipctl reload' to cause the running runslip to reload its
    configuration file.  When reloading a configuration file, runslip
    will IGNORE the 'enabled' and 'disabled' entries under the assumption
    that you do not want it to suddenly throw away any slipon/slipoff 
    commands you had already done.  It will also ignore any device changes
    for currently enabled connections, again presuming that you might have
    overriden it and not want the device to get changed out from under
    the active connection.  Apart from that, any changes to the configuration
    for active connections will automatically reset the connection (cause
    it to hangup and redial).  This feature may change in the future.

(IV) INCOMING SLIP CALLS

    Incoming slip is handled by getty.  You need to create a special
    account... for example, the 'shuttle' account in the example password
    file.  This passwd entry should run the script file 
    /etc/slip/dialin/<dialin_script_file>.

    This script file will execute the allocslip command with appropriate
    arguments.  allocslip takes one option, -t, which specifies the type
    of SLIP interface:

    	-t 0	SLIP
    	-t 1	CSLIP
    	-t 9	AUTO SLIP/CSLIP

    Plus two arguments which specify shell commands to run on interface
    attachment and detachment.  The example script, dialin/slipin_mason
    simply has allocslip run slipin_mason again with different arguments
    so it can detect which state to handle.

    Incoming calls are left up to the user to implement.  It is not entirely
    trivial and there are many variations.  Please do not email me asking
    questions about how to deal with incoming calls!  Instead, use the
    newsgroups!

(V) LOG FILE MONITORING AND MAINTENANCE

    rc.slip creates a log file "/var/log/slip.log".  Simply change rc.slip
    to change the location of the log file (before running rc.slip, of
    course!).

    In order to monitor the log, do a 'tail -f /var/log/slip.log' in a
    shell window.

    In order to enable session debugging for an expect script, there
    should be a 'debug 9' line near the beginning of the script.  To
    turn off session debugging for an expect script, remove the debug
    line.  You do not have to reload the configuration when modifying
    expect scripts.

    You should clean your slip log once a day.  The most common way of
    doing this is as follows:

    	cat /var/log/slip.log >/var/log/old/slip.log
    	echo >/var/log/slip.log

    Note that you MUST NOT REMOVE THE LOG FILE.  The runslip program maintains
    an open descriptor to the file.  Simply removing it will result in runslip
    now logging to an unlinked file and you having no way whatsoever to
    access that log information.

(VI) TROUBLESHOOTING

    * is ifconfig in root's path during rc startup ?

    * is route and other networking commands in root's path during rc startup ?

    * are the directory permissions for the /etc/slip heirarchy correct ?

    * if you intalled new links in /usr/local/bin, 'rehash' must be run in
      shells started before to the installation so they can find the new
      commands

    * is /usr/local/bin in your path?

    * is runslip running? (do a ps)

    * was a log file created, try tail -f'ing it so you can follow the log
      messages.

    * if you use a device override in the slipon or slipreset commands,
      the device must already exist somewhere in the configuration file.
      Create dummy entries if necessary to accomodate the possible serial
      devices you may use.

    * if runslip is interfering with [m]getty, check for a possible
      lock file conflict... runslip puts its lock files in /usr/spool/uucp

(VII) CHANGELOG

    V2.03	Added ability to disable/reset connected interfaces by 
    		device name rather then by symbolic name.  This makes
    		'slip shutdown' scripts trivial when multiple destinations
    		are being managed.

    		A user found a bug in the pointtopoint specification...
    		runslip was calling ifconfig with 'pointtopoint' instead
    		of 'pointopoint'.  runslip.conf should still use pointtopoint.

    		Fixed a few problems in example scripts that were referencing
    		programs from the wrong location.

    		Added UUCP style lock files.  If /usr/spool/uucp exists
    		runslip will user LCK..<dev> style lock files to lock the
    		line.

    V2.02	Added ability to override tty device in runslip.conf when
    		enabling or resetting a slip connection.

    		Fixed minor typos in documentation

    		'notty' binary was missing in V2.01, now included (notty
    		source WAS in V2.01 so no big deal).

    		when you killed an interface in the midst of dialing,
    		the dial script would not necessarily be killed.

    		now does mgetty+sendfax compatible locking

    V2.01	Complete rewrite

    V1.01	Original release, was a mess

    						-Matt

    Matthew Dillon		dillon@moonshot.west.oic.com
    1005 Apollo Way		dillon@overload.berkeley.ca.us
    Incline Village, NV. 89451	ham: KC6LVW (no mail drop)
    USA 			Sandel-Avery Engineering
    [always include a portion of the original email in any response!]

