==========================================================================

                         Dial-in for Linux
                         -----------------

                        using getty_ps 2.0.7b

                                 plus

                               dim 1.03

                              Frank Brokken
                       e-mail: frank@icce.rug.nl

==========================================================================


1.1. Copyright
--------------

The GNU General Public Licence is used with this program. I assume it's
well known. If not, mail me for further details.

    Frank Brokken                   e-mail: frank@icce.rug.nl
    Westerhaven 16                  phone:  (+31) 50 63 36 88)
    9718 AW Groningen                       (mo-vr, 9:00-17:00 MET)
    The Netherlands
    
1.2. Obtaining the dim program
------------------------------

The dim package, which is described in this document, is available at 
beatrix.icce.rug.nl through anonymous ftp (directory pub/unix).  The program 
is contained in a zip called dim.X.YY.tar.gz, where X.YY is the version 
number.  This file is availabe as dim.txt and is also contained in the 
archive.  

Also, dim has been uploaded to tsx-11.mit.edu and sunsite.unc.edu



2. PREREQUISITES
----------------

There is a number of prerequisites before the dim scheme can be
implemented.

2.1. The modem
--------------

First of all, the Linux box must be equipped with a modem which is capable 
of answering the phone and of dialling out.  If you don't have a modem yet 
for your Linux system, but are considering buying one, go for a Hayes 
compatible modem.  The remainder of this document shows examples for this 
type of modem.  

Second, the modem must of course be connected to a telephone. Make sure that 
the modem functions properly: it may be a good idea to boot under DOS and 
try to talk to your modem via a communications package.  E.g., supposing 
that you have MSKERMIT (the MSDOS version of Kermit), try booting DOS, 
starting mskermit, and typing: 

    set port com<X>         {this sets the COM2 (external modem) or COM4
                             (internal modem) port}
                            {alternatively, use:
                             set port com<X> <port-address> <irq-nr>}
    set baud <speed>        {this sets the modem speed}
    c                       {this should connect to the modem}
    at                      {this sends an attention signal to the modem}
    OK                      {modem should respond: OK}
    atdt 1234567            {this instructs your modem to dial (atd) using
                             tones (t) the phone number 1234567,
                             your modem should start dialling,
                             use atdp for pulse dialling}
    NO RESPONSE or BUSY     {modem response if the phone number is
    or NO CARRIER            invalid or does not connect to a modem}
        or
    CONNECT <speed>         {modem response if the phone number leads to
                             a modem}

2.2. The modem under Linux
--------------------------

The modem must function properly under Linux. The suggested modem device 
names are: 

    /dev/ttyS1 and /dev/cua1        for an external modem, and
    /dev/ttyS3 and /dev/cua3        for an internal modem.

You may need to create these devices, if you don't have them yet. The 
details on this are in the SERIAL.FAQ.  In the remainder of this document, 
/dev/ttyS3 will be used in the examples; however, you may need to change 
this device name into /dev/ttyS1 when appropriate.  Also, you may need to 
recompile your kernel with serial IO support.  Furthermore, you will need 
the program setserial, version 2.02 or higher (ftp-able from 
tsx.11.mit.edu).  The setserial program takes many parameters; such as, the 
uart type of the modem.  E.g., I have the following line 

    /etc/setserial /dev/ttyS3 irq 5 uart 8250

in my boot-script /etc/rc.local. This defines the uart of the modem. I have 
set the irq line of the modem to 5 using a dipswitch; I chose that number 
because that's the only irq I have left (originally, it's the irq number of 
the second parallel port).  

After configuring the modem for Linux, making sure that your kernel supports 
serial IO, etc., try talking to it through kermit.  Use the above session 
example to test the working.  Try calling out to a `real' system and test 
the reliability of the connection.  

2.3 Dial-in under Linux
-----------------------

Before you attempt to construct the dim procedure, you must make sure 
that dialling in to your Linux system works.  For the dial-in you need the 
`new' getty or uugetty: getty_ps version 2.0.7b or higher.  The sources for 
getty_ps can be obtained at, e.g., tsx-11.mit.edu.  

2.3.1. getty_ps

When constructing the new getty program, follow the instructions closely.  
Make sure NOT do do a "make install" right away: first, do a "make" and test 
the new getty as suggested.  A "make install" with a non-working getty
will overwrite the previous (working) version, and you might not be able to
login again on your linux-box for a while...

Once you have the new getty working and installed as 
etc/getty, adapt the following files to get dial-in working:
/etc/inittab, /etc/gettydefs, /etc/default/getty.ttyS3 (the ttyS3 again 
referring to an internal modem; for an external modem, use ttyS1).  The 
modifications for these files are described in the getty_ps documentation 
and are illustrated below.  

2.3.2. /etc/inittab

Here is a sample from my file inittab (see also the directory examples):

    s3:6:respawn:/etc/getty ttyS3 modem vt100

This line instructs init, the first program which is run under Linux, to 
execute /etc/getty upon startup.  That program, getty, will then
watch /dev/ttyS3 for activity.  When eventually the modem accepts a call,
getty will try to establish a connection according to two files: 
/etc/gettydefs and /etc/default/getty.ttyS3.  The specification "respawn" in 
this line causes init to restart the getty process when it dies or when its 
subprocesses die.  

2.3.3. /etc/gettydefs

The file /etc/gettydefs defines the type of connection to establish. Here is 
a part of my /etc/gettydefs: 

    #label  # connection definitions                # prompt    #next
    #-----------------------------------------------------------------
    modem   # B2400 CS8     # B2400 SANE -ISTRIP    #login:     # modem

Once getty detects activity on the specified input line, it will search 
for the label "modem" (as mentioned in /etc/inittab) in its definition file 
/etc/gettydefs.  That label occurs here, and instructs getty to try to 
establish a 2400 baud connection. In my case, this is a fixed baud rate,
you might want to change that if you want to use an adaptable baud rate
setting. See the SERIAL-FAQ for details.

2.3.4. /etc/default/getty.ttyS3

The file /etc/default/getty.ttyS3 is needed for the `new' getty program.  
The previous getty, often still distributed with SLS, does not use this 
file.  The file therefore has to be created.  Here is a sample of the file 
/etc/default/getty.ttyS3: 

    SYSTEM=<name-of-your-linux-box>
    VERSION=/proc/version
    LOGIN=/bin/login
    ISSUE=/etc/issue
    CLEAR=NO
    HANGUP=YES
    INIT="" ATH\r OK ATZ\r OK ATS0=1&C1&D3&W\r OK
    TIMEOUT=60
    CONNECT="" CONNECT

This file defines the following actions:

    (a) The first four lines define text information, to be displayed during 
    the login process.  Refer to the getty_ps information for the meaning of 
    these lines; e.g., the line LOGIN=/bin/login defines the program which 
    is used to log in a user.  

    (b) The lines CLEAR=NO and HANGUP=YES define the way that getty 
    handles the modem.  

    (c) The line

        INIT="" ATH\r OK ATZ\r OK ATS0=1&C1&D3&W\r OK

    consists of strings, which are in turn either expected by getty to be read
	from the modem line, or which are sent to the modem.  The INIT label 
	tells getty to execute this sequence upon startup. 	

    The sequence can be read as follows:

        - Getty should wait for no special string on the modem line ("").
        - Getty should then send the string "ATH", followed by a
          carriage-return, to the modem. This hangs up the phone line.
        - Getty should then wait for the string OK to appear on the modem
          line; that is the modem's response.
        - Getty should then send "ATZ", followed by a carriage-return. This
          re-initializes the modem.
        - Getty should then wait for an OK.
	- Getty will then send "ATS0=1", followed by a carriage-return. This
	  will instruct the modem to answer the phone on the first incoming
	  ring.
          &C1 sets the carrier detect signal only when the remote carrier is
          present.
	  &D3 forces a hangup of the line, and resets the modem, after an
          ON-to-OFF Data Terminal Ready transition.  
	  &W writes the active configuration in the profile to be used by
          default. (&W0&W1 would store the active profile in both
          nonvolatile profile memories, that would be ok too).

	  The &C1&D3 were added after experiencing problems with the modem
          configuration after switching off the computer (in my case: the
          modem too, as it's an internal one).  Apparently the &C1&D3
          settings weren't kept, causing the modem to spawn login
          constantly. The &C1&D3 addition cured the problem.

	- Getty should again wait for an OK from the modem. 

    Please note that the AT commands, which are sent to the modem, apply to 
    my `Hayes-compatible' modem. Be sure to check your modem 
    documentation for the exact syntax applying to your modem when using 
    these commands for your own setup.  

    (d) The TIMEOUT specification instructs getty to break the connection 
    when the user waits longer than 60 seconds before logging in.  

    (f) The line

        CONNECT="" CONNECT

    defines a chat-sequence to be performed after the modem has auto-answered
	the phone. The sequence can be read as follows: 

        - Getty is instructed not to wait for specific information ("").
        - Then getty waits for the string CONNECT, whereupon the login
		  process starts.

2.3.5. The modem-setup itself
-----------------------------

The modem itself should be configured as follows:

(profile 1 is identical to profile 0: I left it out. No phone-numbers are
configured, also left out).

----------------------------------------------------------------------
ACTIVE PROFILE:
B1 E1 L3 M3 Q0 V1 X4 Y1 &C1 &D3 &G0 &J1 &L0 &P1 &Q0 &R1 &S1 &X0 &Y0
S00:000 S01:000 S02:043 S03:013 S04:010 S05:008 S06:002 S07:030
S08:002 S09:006 S10:014 S12:050 S14:AAH S16:00H S18:000 S21:FFH
S22:FFH S23:17H S25:005 S26:001 S27:40H

STORED PROFILE 0:
B1 E1 L3 M3 Q0 V1 X4 Y1 &C1 &D3 &G0 &J1 &L0 &P1 &Q0 &R1 &S1 &X0
S00:000 S14:AAH S18:000 S21:FFH S22:FFH S23:17H S25:005 S26:001
S27:40H
----------------------------------------------------------------------

Several things are worth noting:

1. Contrary to the SERIAL-FAQ, the modem is *not* shut up at all: command
   echoing is on (E1), and the modem sends responses (Q0). In fact, by shutting
   up the modem I had a completely failing INIT chat-sequence in the original
   setup, as getty never got anything back from the modem.

2. &C1: Carrier Detect Signal is only ON when a remote carrier signal is
   present. This is in line with the SERIAL-FAQ.

3. &D3: Once the connection is broken (On to Off Data Terminal Ready
   transition), the modem will hangup the line, reset, and return to
   command-mode. Again, in line with the SERIAL-FAQ.




After installing getty_ps and modifying all necessary files, you should have 
the dial-in protocol established.  Test the dialling in before attempting 
the next step: installing dim.


4. GETTY DEFINITION FILES
-------------------------

Dim uses two getty definition files. These files 
are /conf/callback/getty.ttyS3.org and /conf/callback/getty.ttyS3.dim.

(The directory specification 'conf/callback' is a leftover from Karel
Kubat's callback system. His directory slection has been accepted unaltered
by dim. It can of course be changed to another name of your liking).

The first of these files, with the extension .org, is the file which causes 
getty to accept incoming calls.  This file is used in dim's -reset command,
and has already been described before:

    SYSTEM=<name-of-your-linux-box>
    VERSION=/proc/version
    LOGIN=/bin/login
    ISSUE=/etc/issue
    CLEAR=NO
    HANGUP=YES
    INIT="" ATH\r OK ATZ\r OK ATS0=1&C1&D3&W\r OK
    TIMEOUT=60
    CONNECT="" CONNECT


The file /conf/callback/getty.ttyS3.dis will diable the autoanswering
facility of the modem. It contains but one line:

    INIT="" ATH\r OK ATZ\r OK ATS0=0&C1&D3&W\r OK

Via this initialization the modem is instructed not to react to incoming calls.
The command ATS0=0 disables the auto-answering.

5. INSTALLING DIM
-----------------

Before unpacking the zip containing the sources, create an appropriate 
directory (e.g., /usr/local/src/dim).  Move the archive to this 
directory and unpack it.  Archives in the form .zip can be unpacked using 
"unzip <archive>".

5.1. The file src/config.h
--------------------------

The pathnames used by the dim program use the directory /conf/callback.
If you dislike this name, edit src/config.h and substitute your favorite 
name.  Note however that it may be a good idea to place all configuration 
files into a directory which is only readable by root.  In the following 
discussion it is assumed that the default name /conf/callback is used.  

dim assumes that you are using an internal modem, pointed to by the 
device /dev/ttyS3.  If you are using an external modem, change all 
occurrences of "ttyS3" into "ttyS1" in the file src/config.h.  

Furthermore, you may want or need to change the following strings or defines
in src/config.h:

    TMPGETTY - this filename is used as a temporary file. dim deletes 
    this file after operation.  Default: /tmp/getty.ttyS3.tmp.  

    LOGIN - the original login program. Default: /bin/login.

    ERRLOG - the logfile where cblogin logs fatal errors. Default:
    /usr/adm/dim.log.

    PANICLOG - the file where cblogin writes fatal errors, when ERRLOG 
    cannot be written.  Default: /dev/console.  

    EMAIL - e-mail address which is displayed to the dialling in user when 
    cblogin cannot proceed.  You can leave this string undefined if you do 
    not wish any e-mail address shown.  The default is my e-mail address; 
    please change the string or undefine it, or my name will appear in your 
    modem's login screen.

    DISABLEGETTY - Define this filename if you want the system 
    administrator's tool cbstat to be able to disable the modem. This file 
    must then contain a getty definition which disables the modem.
    
5.2. Building dim
-----------------

First, create the directory for the configuration files of dim. E.g., 
if this directory should be the default conf/callback, do a: 

    mkdir -p /conf/callback
    (cd /conf; chmod 700 dim)

This will make the directory readable by root only.

If you have Icmake, look at the file "build". Modify the define dimDIR 
(default: /conf/callback) if you do not want to use this name as the basic 
dim directory.  Modify the define BINDIR if you wish an 
installation of this program into an other directory.  After modifying the 
file "build", do a "./build install".

If you do not have Icmake, get it. Icmake is a powerful program maintenance 
tool and a script language, and is available at tsx-11.mit.edu (directory 
pub/linux/sources/usr.bin) or at beatrix.icce.rug.nl (directory pub/unix).  
The file icmake.doc explains how to install Icmake.  If you cannot get 
Icmake, chdir to the directory src and do: 

    (cd dim ; gcc -c *.c)
    gcc -o dim/dim dim/*.o
    mv dim/dim /usr/local/bin
    chmod 700 /usr/local/bin/dim

Note that dim is only readable and executable by root.

5.3. The program dim
--------------------

The program dim, which is installed by default to /usr/local/bin, is a 
small tool to either see what the dim setup is doing, or to force 
the modem into auto answering mode or not.  
The program should be readable and executable by root 
only, since it is only an administrator's tool.  When dim is invoked
without arguments, usage information is shown on the screen.  

The actions of dim are further discussed below:

    dim -disable: This option can only be used when the define 
    DISABLEGETTY is used during the compilation and installation of the 
    package. The file /conf/callback/getty.ttyS3.dis is copied to 
    /etc/default/getty.ttyS3: the disable-file should contain commands
    to disable the modem. Having copied this file, getty (for the
    modem-line) is killed, and is immediately restarted again by init,
	using the new getty.ttyS3 file.
    
    dim -enable: This forces the modem into its auto-answer state.
    The getty definition file which allows only dial-in, 
    /conf/callback/getty.ttyS3.org, is copied to 
    /etc/default/getty.ttyS3. Then getty is killed, immediately to be
	restarted again, using the new getty.ttyS3, by init.
    
    dim -file: This shows the current getty definition file 
    /etc/default/getty.ttyS3, stripped of comment lines etc.  

    dim -wake: This tries to wake up init by sending a SIGHUP. This will
	also generate a kernel message: '/etc/initrunlvl not found', which
	may safely be ignored. The message is logged on the file
	/usr/adm/syslog (i.e., on my linux-box)

6. DIM AND CALLBACK
-------------------

Karel Kubat's callback program and dim resemble each other in many ways.

Questions regarding callback should be sent to karel@icce.rug.nl. 
Questions regarding dim can be sent to me: frank@icce.rug.nl

7. INCOMING CALLS
-----------------

At some point in time, when dim is installed, you might want to answer an
incoming call via the modem, rather than via getty. I had some problems 
initially in getting that part of the story running smoothly. 
Here's how I do it now:

       - When you know an incoming call is about to arrive, start kermit.
       - Then, if the call arrives, kermit rather than getty will catch
         the call.
       - The modem beeps and shreeks and falls silent. *THAT* is the 
         time to enter:
       - c
       - Now you're connected to the incoming call via kermit, and you
         can, e.g., login.
	 
However, if you know there may be incoming calls but you don't want to
accept them, then you will probably have given the command

                dim -disable

Why would you do that? Well, I have my linux-box at the office call my
linux-box at home every evening between 18:00 and 20:00, every 15". 
Usually within that time-block I want to login at the office's linux-box.
Not every 15", so I don't want the modem to accept the call at that time.

But, if the modem has been switched off (dim -disable) I can start kermit
allright, but it won't take the call since the modem was switched off. This 
is cured by the following 'modem.kermrc' file which I pass to kermit when
kermit is started, i.e., I give the command

                kermit modem.kermrc

The modem.kermrc file contains:

        ----------------------------------------
        set line /dev/ttyS3
        set speed 2400
        set modem hayes
        set dial dial-command ATDT%s\{13}

        set prompt [modem] kermit> 
        
        set file type bin
        set file name lit

        output ats0=1\13
        ----------------------------------------
	
The last line here is the interesting one: it enables auto-answering
when kermit is started. So, if dim -disable has been given, I can start
kermit and the modem will now accept incoming calls, due to the enabling
of the auto-answering. Note that when kermit is done, it resets the modem 
again, which may or may not what you want. 

At some point you might want to do an explicit dim -enable after the kermit 
session.

	 
8. HISTORY
----------

1.00: Initial release. One program, dim, documentation, and example files.
1.01: Appending &C1&D3&W to the INIT chat-sequences to prevent constantly
      respawning of login.
1.02: Change in the description only. A section on answering incoming calls
1.03: Changes in the description and file organization, related to 
      sunsite and tsx-11 uploads. Icmake binaries are part of the
      distribution.

