# PAM_VIRTUAL
#  Pam_virtual's sole function is to allow a server on one machine to look and
#	behave like that one server, duplicated over several machines, with
#	separate resource areas and user name spaces.
#		
#  To that end, it can be told about several virtual hosts, their settings,
#	their users; and those users' permitted facilities and resources.
#	It uses this information, along with the IP address used to connect
#	to the machine, to insinuate separate username spaces into the
#	authorisation procedures (by prepending a vhost-unique identifier to
#	PAM_USER), and also to provide facilities for setting per-user server
#	access (permission to use the server at all) and environment variables,
#	including most notably USER, UID, GID, HOME, and SHELL, as appropriate.
#	(Note that USER would not have anything prepended to it.)
#
#  Pam_virtual is only a major part of the overall virtual system, which
#	includes programs to reconfigure the live computer to a new configuration 
#	(by constructing other programs' configuration files from the central
#	configuration file, then using rc.d or other methods to bring servers
#	into line) and a web-browser way of editing the configuration file
#	(which is text-based, and hence amenable to traditional Unix editors).

# Servers.
#  Servers which use pam_virtual are considered to be `virtual', regardless
#	of what they actually do. :)
#
#  The extent to which a server is virtual depends primarily upon what
#	virtuality would mean for that server: POP is a very sensible candidate
#	for virtual users - indeed qmail+qmail-POP seem designed for that very
#	purpose; FTP could be made virtual, with a root for each machine; Samba
#	could too, for similar reasons to FTP. Webservers fit easily into the
#	virtual system, and can even have users via .htaccess.
#
#  Even shell-type accounts could be made vaguely virtual in principle,
#	but anticipated use is merely that the configuration file should set up
#	USER+UID+GID+GECOS+HOME+SHELL in a useful way, probably mirrored by
#	/etc/passwd for backwards compatibility, and then whichever server
#	was about to fork a shell would just fork the shell: not virtual
#	insofar as they don't chroot(), but one still needs to telnet to the
#	appropriate host in order to log on at all. And, of course, have been
#	permitted telnet-based access.

# Passwords.
#  All virtual servers are authenticated thusly:
#	The IP address to which connection was made (or the default IP address
#	in the case of console connections) is used to determine whether a user
#	exists for that host. If it does, a vhost-unique code is prepended to
#	the usercode given to the Login:-type challenge, effectively forming
#	a set of separate namespaces in whatever underlying authentication
#	mechanism is in force. At this stage, environment variables are also
#	set up, as read from the configuration file.
#	The server would have to decide whether to sgid($GID) suid($UID) or
#	not, later: this may be pam_virtual's job.
#
#  Changing password can be done during the authentication process, when
#	PAM_USER would have been changed to include the vhost. If a networked
#	password-changer (poppasswd) is used, it will suffer whatever fate
#	the POP server suffers (see Other Hosts, below).  If a non-networked
#	password-changer (passwd) is used, some way will need to be found
#	to supply the vhost information, and this is a problem.
#
#  Non-virtual servers, ones not using this module, may use a partially
#	intersecting namespace within whichever authentication module was in
#	use. If these servers need to change passwords or whatever, it may
#	be necessary to provide both virtual and non-virtual password-changing
#	servers.

# Other hosts.
#  In addition to authentication on one host, pam_virtual's configuration
#	file can be used by other hosts (over NFS or via mirroring).
#	The way PAM is configured on any given host can change the way
#	it's influenced by virtual.conf: the machine with all the virtual addresses
#	may not run a POP server, but since IP packets are sent to Ethernet
#	addresses based purely on IP destination (and not on a combination of
#	destination IP and target TCP port), some kludgery may prove necessary.
#
#  For example, a web host actually needs the IP addresses, because webservers
#	work that way, but a separate POP server on the same network can usefully
#	utilise the webhost's configuration file by insisting that pop users
#	log in (to its single IP address) with ready-munged versions of their
#	usernames (effecting a virtual virtual login :). Since the POP host has
#	no munge string of its own, PAM_USER will be left alone, and authentication
#	will proceed as expected. (ie, using some chicanery to find the host in
#	virtual.conf with the appropriate munge-prefix, so as to be able to
#	determine the settings for that particular virtual user.)

# ##### File starts here

# Default UID/GID for authenticated virtual users of each given server

:SERVER:
	config		UID=nofiles	GID=nofiles
	ftp			UID=anonftp	GID=anonftp
	qmail-pop3d	UID=pop		GID=pop
	samba		UID=samba	GID=samba
::SERVER

# PAM_USER is changed only for the rest of PAM. pam_virtual keeps its
#	own idea of the username in virtual_user (or just USER?)

# ALL_UPPERCASE variables are environment variables
# All_MixedCase variables are configuration variables
# all_lowercase variables are pam variables and PAM_* psuedovariables

# Need to resolve how configuration knows how to create/destroy
#	maildirs etc, and how/when to complain (eg non-empty directories)

:HOST:
	# Note, expressions for a given parameter are gathered without evaluation
	# until all possible expressions have been acquired (and more general ones
	# knocked out by more specific ones), when they're all evaluated with
	# with each other. Simply: forward references are okay.

	pam_user=$hostkey-$USER
	Base_Interface=eth:00:00:1B:20:57:92

	Pop_Okay=yes HOME=/home/$hostkey/$USER Dot_Qmail=$HOME/Maildir/

	194.200.167.17, some
	:virtual:
		:host:
			Aname=www.some.co.uk
			Cname=mailgate.some.co.uk:secure.some.co.uk
		::host
		
		:USER:
			news
				Dot_Qmail=warwick-$USER@some.co.uk
				HOME=/var/spool/news
				UID=9 GID=13
		::USER
		:USER:
				HOME=/home/$USER
				SHELL=/bin/bash
	
			root	UID=0 GID=0 HOME=/root
			warwick	UID=100 GID=80,100,81
			john	UID=101	GID=80,100
		::USER
		:USER:
			jason
			lisa
			carole
		::USER
		:USER:
			Pop_Okay=no
			
			default	Dot_Qmail=warwick@some.co.uk
			sales	Dot_Qmail=jaybee@some.co.uk
			localfocus
					Dot_Qmail=jaybee@some.co.uk:carole@some.co.uk:dave@some.co.uk
			auto	Dot_Qmail=/var/local/spool/mailbot/kolinski/$ANAME/
		::USER
	::virtual

	194.200.167.52, bbtmc
	:virtual:
		:host:
			Aname=www.boltonburytmc.co.uk
			Httpd_Root=/http:/$Aname
		::host
		:USER:
			lindsey.mercer
			kiyoko.hay	Dot_Qmail=ki29823@bolton.ac.uk
			margaret.moir
		::USER
		:USER:
			Pop_Okay=no
			sales	Dot_Qmail=margaret.moir
			info	Dot_Qmail=margaret.moir
			default	Dot_Qmail=$2HOST-lindsey.mercer
			auto	Dot_Qmail=/var/local/spool/mailbot/kolinski/$Aname/
		::USER
	::virtual
::HOST