Readme for Xlogin-1Beta1

	Note: At the moment all sessions run with access controls disabled, even those
	started with xdmcp, the readme describes how it *should* work, not how it currently
	works. 
	This is beta quality software, its stable and feature complete but parts of it 
	simply refuse to work as designed. Currently the biggest problem is that xauthority
	creates a cookie for the user (see RAWX11 desktop script) - snag is it doesn't seem
	to work..... 
	



Whats this for:
xlogin is a login manager similar in function to xdm, gdm, kdm etc.
It does not use any xdm code and has very few dependencies. 

   Features :

   * Everything is available on the command line, great for use with init
   * Supports simple shell scripts for starting each desktop environment 
   * Use command line switches to enforce policy (desktops, wallpapers etc)
   * all settings stored in /etc/ - no hunting for settings or hastles with backups
   * automatic logins available with -autologin command line switch and xlogin-makeidentity utility
   * Persistant connection attempts to X servers, configure displays and turn it on/off at will
   * xdmcp server with MIT-COOKIE-1 authentication


Motivation:
I am not a fan of the way xdm is administered and I like gdm even less.
The idea behind xlogin is to write a small fast login dialog thats easy to administer,
its not the most attractive login in the world. xlogin is crude, requires very little 
to build and install hence is suitable for small or embedded systems.  Its use of X 
server retries for XOpen makes it suitable for running from init and tolerant of displays
that are not always on/available.
Personally I dont like "click on user" logins, this does not try to look like 
Windows XP ! Its closer to a text console login, a feeling enforced by the use of a 
fixed font.



Security:
You can chose between using xdmcp with MIT-COOKIE-1 (poor security) or running with 
access controls dissabled (no security). This is not a defect of this package but simply 
the design of X,  if you want secure X then you need to add encryption to it, ssh is the 
most common way. 



XDMCP:
X Display Management Control Protocol.  Basically this is pretty simple protocol and 
xlogins implementation is even simpler.  The idea is that an X display requests a 
session using the -query <hostname> argument. 

For example:
		X -query myserver :1

The XDMCP server takes that REQUEST and replies an ACCEPT responce, that accept 
response contains the cookie (random number that will be used to identify clients 
in all subsequent X transactions) and a sessionID (another unique number).
Having done that xdmcp-server lanunches an xlogin to satisfy the request.
In most implementations the xdmcp server and the login code are rolled into one 
executable (xdm/gdm/kdm). In this system they are seperate executables.  
This is simpler for the user to understand and makes life easy to see whats going on, 
the down side is that the proper implimentation of xdmcp requires the login code and 
the xdcp server to share some information. xlogin passes the MIT cookie to the xlogin 
code through the environment (environment variables).  This is clean ish as any hacker 
would be hard pushed to extract the environment from a process they dont own. 
At the moment xlogin-xdmcpserver does not support indirect queries (chooser), 
but this may be added later. xlogin-xdmcpserver is hard coded to use UDP port 177, 
the default for this protocol.  If you need to change it a #define is at the top of 
the source file.



Hows it works:
xlogin is designed to be started from init, when started it will connect to the 
display named in the command line -display argument or :0 if omitted. It tries to 
connect repeatedly incase the display is down or unreachable. The desktop names 
offered to the users are the shell script names from the /etx/xlogin/desktops directory.  
Each one of these scripts is used to start a desktop environment. The user can 
select the desired desktop by clicking on it (at any point) as well as enter a 
username/password. If the username/password pair authenticates correctly then the 
xlogin process swpans a bash session by setting the user id and group id to that of 
the user, modifying its environment to include the new HOME and DISPLAY variables
then launching the selected shell (desktop) from files in /etc/xlogin.  
The script starts the X session, this shell waits for all its child processes (the 
desktop itself) to  terminate before exiting itself.  If run from init this shell exit 
causes init to spawn another login for the terminal.


Dependency:
xlogin requires a working bash (not sh!) - it uses shadow passwords and is probably 
only suitable for linux without modification. It uses the "hostname" utility to read 
the systems hostname as well as the "ls" utility.  Requires gcc with a working xlib,
libcrypt (-lcrypt)  for background images libjpeg.
People wishing to contribute code should have in mind that one of my main goals was 
to have the minimum number of dependencies in the code, so dont bother to pull in your 
favorite toolkit and then sending me a patch ! At the moment the keyboard code looks 
crappy, the encryption of identities could be improved.



Desktops:
The files /etc/xlogin/desktops are shell scripts used to start a desktop.  You can 
customize them simply or add new ones.

The FIREFOX script tries to give a Kiosk type firefox session with no window manager !  
The snag is that the firefox command line options seem to be broken so the X server 
resolutions needs to be bodged into the firefox configuration file.  This may BREAK 
firefox for that user, you have been warned.  I recommend creating a special user to test.
After install remove any unwanted desktop files from the directory.  Some more files are 
in the desktops directory of the source package, not all are copied in as default - feel 
free to write new ones and submit them.


Arguments:
xlogin can use the following arguments.  The most useful is the -display argument, an IP 
or hostname can be used together with a display number.  Here are some example display 
names  "mypc:1" "192.168.1.231:1" "127.0.0.1:1" 


xlogin: <option list>
-display <name>		 IP or Hostname of X server to attach to, defulat is localhost:0
-allowroot		 As default for displays other than localhost:0 root logins are not permitted
-once			 Without this xlogin will keep trying to attach to a display indefinatly
-fontsize <S/M/L>	 Specify S or M or L for small medium or large fonts
-desktop <name>		 Limit this login to one desktop environment only, no selection menu
-default <name>		 Start with this desktop selected from the list
-pos XXX,YYY		 Position the login window here instead of centered on display
-v			 Be verbose with messages on stdout, default is silent
-help or --help		 This text




Examples:

	Start a login on the second X server of this machine
	xlogin -display localhost:1

	Start a login on the second desktop of the machine with KDE selected for the user, but the user can still change it
	xlogin -display localhost:1 -default KDE

	Start a login on the second desltop of the machine, the user has no choice but to use GNOME
	xlogin -display localhost:1 -desktop GNOME

	Start a login on a X11 server on the network that may or may not exist yet
	xlogin -display 192.168.1.11:0

	Start a login on a X11 server on the network that may or may not exist yet, but dont keep trying to connect
	xlogin -display 192.168.1.11:0 -once

	Start a login on display 1, make the main window background black, black is a special word not a filename
	xlogin -display localhost:1 -background black

	Start a login with some wallpaper on display 1 of my local machine "X -ac :1"
	For a display with dimensions of 800x600 this will infact use the image /etc/xlogin/backgrounds/example_800x600.jpg
	xlogin -display localhost:1 -background example

	Start a login with some wallpaper on display 1, position the login on the top left of the screen
	xlogin -display localhost:1 -background example -pos 10,10

	Make an identity for use with xlogin
	xlogin-makeidentity -user myuser

	Start a login using the identity myuser for a GNOME desktop
	xlogin -display localhost:1 -identity myuser -desktop GNOME

	# start an xdmcp server for X terminals using the "-query <hostname>" option
	xlogin-xdmcpserver -display localhost:1 -background example -pos 10,10



/etc/inittab examples:
	The following examples are based around a Redhat/Fedora system. Other distributions will work but you may
	need to play with what runlevel you specify. Redhat distros use runlevel 5 to indicate X is running. You dont
	need X running locally at all, so 35: is also ok. Debian would be runlevl 23:

	Example1: Simple examples, a single Xvnc session
	vnc1:5:respawn:/usr/bin/Xvnc -once -ac -rfbport 5903 -geometry 1024x768 -PasswordFile /root/.vnc/passwd -query localhost :7
	xlg1:5:respawn:/usr/bin/xlogin/xlogin -display jonspcb:1

	Example2: xdmcp server 
	xdmc:5:respawn:/usr/bin/xlogin-xdmcpserver -background example -pos 10,10



	Exmaple3: For this example to work the X servers need to be start with access controls dissabled. Without xdmcp its impossible
		  to push a security key at the X server before the session. See -ac option for X server.
	
		  4 Fixed displays each with a permanent desktop,  dont log the same user in multiple times it upsets KDE/GNOME which
		  holds a lot of user state in the $HOME/.Hidden files.   Best to create one user per desktop and hard wire them with
		  the -display argument in xlogin rather than try and use xdmcp-server, this is even true for the FIREFOX desktop !
		  Create 4 users "workstation1" "workstation2" etc with "adduser" and passwd <username>, then make 4 identity files 
		  with xlogin-makeidentity.
		  Transcript of root terminal session :
			# adduser workstation1
			# passwd workstation1
			password: ********
			# adduser workstation2
			# passwd workstation2
			password: ********
			# adduser workstation3
			# passwd workstation3
			password: ********
			# adduser workstation4
			# passwd workstation4
			password: ********
			# xlogin-makeidentity -user workstation1 -password password1
			# xlogin-makeidentity -user workstation2 -password password2
			# xlogin-makeidentity -user workstation3 -password password3
			# xlogin-makeidentity -user workstation4 -password password4
			

	# /etc/inittab ........
	ws1:5:respawn:/usr/bin/xlogin -display workstation1 -identity workstation1 -desktop FIREFOX
	ws2:5:respawn:/usr/bin/xlogin -display workstation2 -identity workstation2 -desktop FIREFOX
	ws3:5:respawn:/usr/bin/xlogin -display workstation3 -identity workstation3 -desktop GNOME
	ws4:5:respawn:/usr/bin/xlogin -display workstation4 -identity workstation4 -desktop KDE



Buidling/Installing:

	# gunzip xlogin.tar.gz
	# tar xvf xlogin.tar
	# cd xlogin
	# <youeditor> key.h, change the key string
	# ./compile
	# ./install



The utilities:
	All these programs must run as root.

	xlogin				-	Connects to the X server and presents the login box, 
						authenticates and starts session

	xlogin-xdmcpserver		-	Server component for xdmcp managed systems. Everything on the command
						line is passed as arguments to the individual xlogin sessions it spwans.

	xlogin-makeidentity		-	Create an identity file for a given user.


Directories:
	/etc/xlogin			-	Base of operations
	/etx/xlogin/backgrounds		-	Jpeg images of varying sizes for backgrounds
	/etc/xlogin/desktops		-	Scripts for starting sessions, the filenames become the menu xlogin
						offers to its users


Distribution notes:
	On all distributions you need the X11 libs and headers, as well as libcrypt and headers plus libjpeg and headers.
	On my Debian box everything built first time, same for Fedfora core 6. I've not tested many others but this should
	build on almost anything with a working build environment. I've installed the package on machine with no local X
	server at all, and embedded sytems where only RAWX11 is possible.

	I've tested against Xfree86 and X.org servers, all seems to work ok - even for pretty early ones.  If your X server
	does not support MIT cookies then your going to be out of luck with xdmcp unless you use -ac as well, it does seem
	to work with both.


Removing:
	# rm -rf /etc/xlogin
	# rm /usr/bin/xlogin*



Bugs/Todo:
	Im disabling all access controls, why cany I make MIT cookie work with rootjpeg and the xauth in scripts ?
	initial caps lock state needs to be set to leds off
	Fix password echoback on xlogin-makeidentity ?
	Keyboard handling is poor and assumes a US style layout, not a problem unless you like a lot of punctuation
	in your username/passwords.

