
GETTY-PS 2.1.0 for Linux 1.0 and higher
----------------------------------------


OVERVIEW

It never fails - as soon as you release something, you find some problems
that *really* need fixing!  My second release of getty-ps is *also* mostly
fixes. (As soon as I fixed one thing, I found yet another that was broken!)
The only showstoppers in this release involved how the login timer was
handled - now, if you provide a login name, you have TIMEOUT seconds to
successfully provide a password. (This is *much* more secure.)  And, that
this program was *not* compatible with "modern" libraries.  It now is (it
compiles up thru kernel 2.4.5), however I have left all the old library
stuff in here, *just* in case someone out there needs it (see the LIBRARIES
define)... <smile>  It should still compile cleanly on kernels back to
0.99.15 - but no promises further back than that!

I have also added a *few* new things to getty, and done a pretty complete
overhaul of the man pages - but there is still more to do there!  Notice
all the nice, new Prompt Substitutions.  They work with both the issue
file (if used), and the login prompt.  This should provide enough
flexibility for anyone wishing a custom login prompt....(I hope!)

This release is intended as a maintenance release only.  I'm not sure what
will be in the next release of this package, as I have not had any
feedback, yet.  I may just do another maintenance release; or I may
continue along the path that Kris mapped out (as documented in the
ChangeLog), in which case the next release will be quite a bit different in
most aspects.

All compilation and lnstallation instructions have been moved to the
file "INSTALL".

For an details of the changes in this release (and historically), please
see "ChangeLog".

If you have any problems setting up the package, questions about mod-
ifications, or suggestions for additional features, feel free to e-mail me.
I am more than happy to help out.  When you e-mail me with problem reports,
please be sure to include full debugging output from getty that illustrates
the problem; I am pretty much helpless without it.

Of course, since all the bugs are now gone <smirk>, I don't expect to get
any bug reports.  But, I always like hearing from users of the package.
And lastly, my appologies to Kris Gleason, from whom I have plagurized most
of this.  But, since Kris is not responding to e-mail, I'm assuming a lack of
concern, from that corner <grin>.

Christine Jamison
getty-info@nwmagic.net


CONTENTS

1.  Brief explination of serial drivers under Linux (0.99.15 and up)
2.  Setting up the configuration files
3.  Troubleshooting
4.  Credits, Thanks, Etc...


1.  SERIAL DRIVERS

    The serial drivers have changed again as of 0.99.15.  If you are
    not too interested in knowing how the serial ports work, you can
    probably skim over this section.

    The basic idea behind Linux serial drivers is that callin and
    callout devices should not try to use the same line at the same 
    time.  In the past, this was accomplished by juggling lockfiles.
    The new scheme takes care of the problem in the kernel.  Instead 
    of one modem device, there are now two: a callin device, named 
    /dev/ttyS# (where # is the port number), and a callout device, 
    named /dev/cua# (again, # = port number).  The callin devices are 
    used by programs like getty; the callout devices are used by 
    programs like Seyon and Kermit.  If you don't have the callout 
    devices in /dev, you create them with the mknod command.  They 
    are character devices, major number 5, minor number same as the 
    corresponding callin device.  Consult the Linux Device List for
    more information about creating the /dev entries.

    So how does it work?  Simple...

    Suppose that kermit wants to open /dev/cua1 for a callout session.
    The kernel allows the line to be open if and only if no other
    program currently has the corresponding /dev/ttyS1 line open; if
    it does, the error EBUSY is returned in errno.  

    The /dev/ttyS1 line is a bit more complicated.  By default, the device
    'blocks' on open.  This means that the program will be stopped until
    the device is clear to open.  For the device to be clear, two things
    must be true:  no process can be using the corresponding /dev/cua1
    line, and the carrier detect line of the serial port must be high.
    While the device is blocking, it is not busy, so callout devices can
    use the line.  In other words, if getty is running on /dev/ttyS1, as
    long as no incoming calls open the line (causing the carrier to go
    high), other programs are free to use the line.  Blocking can be dis-
    abled by setting the O_NDELAY flag to the open system call.  In this 
    case, carrier detect is not needed to open the line; however, if 
    /dev/ttyS1 is busy, EBUSY is still returned in errno and the open fails.
    Finally, a blocking open will return EAGAIN in errno if another process
    closes the corresponding callout device.  This allows getty to easily
    monitor the serial line, and reinitialize if another program might
    have changed serial port parameters (or modem parameters).


2.  SETTING UP CONFIGURATION FILES

    After you install the binaries AND BEFORE YOU LOGOUT/SHUTDOWN you must 
    edit the file /etc/inittab.  The argument format for getty_ps is:
    
      getty tty speed [terminal-type]
      uugetty tty speed [terminal-type]

    'Tty' is the line to run on (without the /dev).  Speed is the line speed
    as defined in /etc/gettydefs.  This argument must match the first field
    of one of the lines in /etc/gettydefs (see gettydefs(4) man page). The
    optional terminal-type is the expected type of terminal to be found at the
    other end.  I set this to console for vt's and vt100 for serial lines.
    Here is the relevant portion of my /etc/inittab file:

	1:123:respawn:/etc/getty tty1 VC console
	...
	s2:23:respawn:/etc/uugetty ttys2 2400 vt100

    Be sure the format of the inittab entries you create are consistent
    with the version of init you are using.  This example works with a
    SYS-V compatible init program.  If you are using simpleinit, the
    format is different.  You will want to change one of the lines to 
    use your OLD WORKING getty (named getty- if you used make install) 
    until everything is stable.

    Next, you want to create the configuration files.  The file
    /etc/gettydefs must exist for proper operation.  See the man page
    for gettydefs(5) for the format of this file.  There is an example
    under the examples directory that you can use to get started.
    (Actually, the examples are from a full-blown, working system.  Most
    installations should not have to change anything.)

    You will also want to set up /etc/syslog.conf to properly log 
    getty error and debug output.  By default, getty logs to facility
    LOG_AUTH.  Errors are sent with priority LOG_ERR, and debugging
    output is sent with priority LOG_DEBUG.  If you don't like syslog,
    make the proper adjustments to tune.h.  Here are the relevant lines 
    from my /etc/syslog.conf:

	auth.warning;		/usr/adm/auth.log
	auth.debug;		/usr/adm/getty.debug.log

    Finally, you want to create configuration files for the individual
    lines.  These are kept in /etc/default.  If you are running getty on
    tty2, the configuration file is /etc/default/getty.tty2; for uugetty
    on ttyS0, /etc/default/uugetty.ttyS0.  Also, if you want the same file
    for all instances of getty or uugetty, you can make the file
    /etc/default/getty or /etc/default/uugetty.  Example configuration
    files are under the examples directory.  

    See the getty(1) manual page for more information on this file.  These 
    configuration files are optional, so your system won't crash if you 
    don't have them, and no configuration files are needed to run getty 
    on a virtual console or dumb terminal (though you can still have them 
    if you want).  The main purpose of the configuration files is to 
    configure your modem correctly.

    If you think you have everything right, 
reboot your system (you do have
    a *working* bootable floppy, right?  I thought so).  If you can log into
    your system on the consoles you set to use the new getty, everything is
    working fine (at least on the consoles).  


    If you think you have everything right, reboot your system (you do have
    a *working* bootable floppy, right?  I thought so).  If you can log into
    your system on the consoles you set to use the new getty, everything is
    working fine (at least on the consoles).  

    Next, after you have edited the configuration file for your modem's tty
    line, go over to a friend's house and try to call up.  If you have a
    14400 baud Hayes modem, the files I have included should drop right in
    and work; otherwise they might need some editing.

3.  TROUBLESHOOTING

    So, what could possibly go wrong?

    In my experience, the major source of confusion with getty_ps has
    been setting up the chat sequences correctly.  Failing chat 
    sequences will cause init to produce errors like 'respawning too 
    fast'.

    If your modem is not responding as expected to the INIT/OFF/CONNECT 
    chat sequences, getty will be continuously respawning.  Check your
    log files; if you have have lots of lines that say INIT sequence 
    failed, this is the problem.  Check your /etc/default/* files.  You 
    can turn on	debugging of the init sequence by adding the following line
    to your defaults file:

	DEBUG=010

    or, alternatly, add the -D010 flag to the entry in /etc/inittab.
	
    This will log some helpful information to syslog.  Read this for clues 
    as to what might be going wrong.

    If you get CONNECT sequence failed, then the CONNECT line is to blame.  
    Debug this line the same way.

    If you have other problems, try turning on full debugging:
    
	DEBUG=777
	
    and read the debugging log.  If you can't make heads or tails of it,
    e-mail it to me and I'll see what I can do with it (after all... it may
    be a bug <shocked look!>).  I have experience with *lots* of modems
    over the years, so if you have modem specific questions, I *may* be
    able to help.


4.  CREDITS, ETC...

Special thanks to all of these people:
	Paul Sutcliffe     ... original author
	Steve Robbins      ... former maintanier of getty_ps
	Kris Gleason	   ... former maintanier of getty_ps

	Michael Haardt     ... SYSV init support
	Theodore Tso       ... for a valuable discussion of the
	                       new serial drivers
	Shane Alderton     ... for the ringback patches
	Julian Cowley      ... for helping with the transition to the
                               0.99.15 serial drivers
	Dr. G.W. Wettstein ... for syslog patches
	Eugene Crosser     ... fidonet patches

I have included all of the original documentation from this package under
the OLD directory.  You might find it useful.  If you find that this file
is missing something, please let me know.  I've tried to be as complete as
possible without writing a book, but this *can* be a complicated issue,
and I've tried to be as helpful as possible.

Good Luck.

Christine Jamison
