
                             XDM-External Greeter
                                       
  What is it?
  
   XDM-External Greeter is a patch to XDM that allows it to call an
   external program that prompts the user for their username and
   password. This external program communicates the username and password
   back to XDM, using a protocol defined below.
   
   This distribution also includes Gtkgreet, a program that implements
   this interface.
   
  Version
  
   This is version 1.00 of XDM-External Greeter
   
  Compiliation
  
   Since XDM-External Greeter is a patch to the original XDM source code,
   you'll need a copy of that source code to compile it. You can always
   grab this from the X distribution. however, For your convenience,
   however, links to the base XDM have been provided on the XDM-External
   Greeter web site at http://tr.ml.org/~tom/software/xdm/.
   
   Once you have the XDM source code, you'll need to place it underneath
   this directory. All of the XDM code should be in the directory xdm.
   Assuming took one of the distributions of XDM from the web site, you
   can simply do:

      $ tar -xvzf xdm.tar.gz

   If the file xdm/Imakefile exists, you're probably in pretty good
   shape.
   
   You can now run 'make' . This will patch the xdm source code, build
   XDM-External Greeter, and build Gtkgreet. Assuming that both XDM and
   Gtkgreet have built without any problems, you can go ahead and switch
   to root and run 'make install'.

      $ make

   With any luck, you'll have a sucessfully compiled XDM-External
   Greeter. Should you not have GTK installed, you can do a 'make xdm' to
   make only xdm. However, you will need to point XDM-EG at a different
   external program.
   
Installation

   To install the software, change to root and run the command
   
      # make install

   This will install the xdm binary as _XROOT_/bin/xdm, supporting files
   in _XROOT_/lib/X11/xdm, and Gtkgreet as /usr/local/bin/gtkgreet.
   _XROOT_ is system dependant, although on Linux it's usually
   /usr/X11R6.
   
   If you already have configuration files for XDM, this process will not
   overwrite them. As a result, you'll have to go in and edit the config
   file by hand. The config file is located at
   _XROOT_/lib/X11/xdm/xdm-config.
   
   You need to make sure the following line exists:
   
      DisplayManager.egp:       /usr/local/bin/gtkgreet

   This points to the location of the program that will be used to prompt
   the user for their name and password. (Make sure this program
   exists... Bad Things will happen if it doesn't.)
   
   After this, configure xdm as appropriate for your system.
   
  Running
  
   Assuming the configuration is correct, you should be able to run XDM
   normally.
   
  Known Bugs/Todo
  
   As of this version, no pinging of remote X servers occurs.
   
  Protocol
  
   The programs used to prompt the user for a username and password are
   called an open file descriptor 3, upon which they must speak a simple
   protocol.
   
   Data types used are:
   
   UC
          A UC is an unsigned char. It can contain a value between 0 and
          255.
          
   String
          A String consists of a UC denoting a length, followed by that
          many bytes of data. The length does not count the UC containing
          the length. The strings should not be assumed to be
          null-terminated.
          
   The protocol consists of one or more cycles, where each cycle consists
   of a login attempt. After enough data has been gathered to attempt a
   login, the prompting program should write the following information
   out to file descriptor 3. (Remember to disable buffering!)

       String:  username                    Required
       String:  password                    Required
       UC:      extension designator        Optional
       ????:    extension data                 "
       UC:      extension designator           "
       ????:    extension data                 "
                .                              "
                .                              "
                .                              "
       UC:      0                           Required

   After sending this information, the program should wait for one of two
   signals. If it receives SIGTERM, the program should indicate success
   and terminate. If it receives SIGUSR1, the login failed, and the
   program should proceed on fo another cycle.
   
   As of right now, there's only one extension.
   
    Extension Designator: 01
    Extension Data:       String

    This extension allows the specification of additional parameters to the
    command line of Xsession. For example, one can use this to specify
    "failsafe", which will usually cause Xsession  to start only a minimal
    session.

  License
  
   New code developed for this project is distributed under the Gnu
   Public License.
   
  Contact Information
  
   The author of these patches is Tom Rothamel <tom-xdm@tr.ml.org>.
   
   There's also an XDM-External Greet web site, located at
   http://tr.ml.org/~tom/software/xdm/. On it, you'll be able to find the
   latest version, as well as the XDM sources and user contributed
   greeter programs.
   
   In a related note, don't hesitate to send your own greeter modules to
   the address specified above.
   
  Thanks
  
   First, I'd like to thank all of those who worked on the original XDM
   code, without which there'd be nothing for me to patch. I'd also like
   to thank Brad Keryan for reviewing this code.
