HCoop Git - hcoop/zz_old/domtool.git/blame_incremental

... / ...

Commit	Line	Data
	1	TOOLS FOR COOPERATIVE INTERNET HOSTING
	2	http://hcoop.sf.net/
	3
	4
	5	Introduction
	6	------------
	7
	8	This package collects tools that have been found useful in running
	9	Internet servers cooperatively for the Internet Hosting Cooperative
	10	(http://hcoop.net/). The inclusion of all of them in this package
	11	isn't always particularly well motivated. However, everything here
	12	should be of potential interest to the general sysadminning public.
	13
	14	The basic goal here is to provide Internet hosting services that meet
	15	the following criteria:
	16	* A group of people share the resources of a server.
	17	* People should be prevented from breaking other people's services.
	18	* It should be easy to administer your own services.
	19	* The base interface should be attractive to expert users, which
	20	includes making it relatively easy to manipulate with scripts.
	21
	22
	23	Domtool basics
	24	--------------
	25
	26	The central organizing principle of the tools here is to represent all
	27	domains hosted on a machine as parts of a directory tree mirroring the
	28	structure of Internet domain names. Configuration files relevant to
	29	daemons that have per-domain/hostname configuration live in the
	30	directories for the domains whose settings they control. Standard UNIX
	31	filesystem permissions control who is allowed to change the settings
	32	for which domains.
	33
	34	There are also additional controls related to which users, groups, and
	35	paths may be used in configuration files. Each directory in the domain
	36	tree may contain a .users file which lists UNIX usernames on separate
	37	lines. The union of the users specified in a domain's directory and
	38	all its parent directories in the domain tree specifies which users
	39	administrators of that domain are allowed to delegate for processes to
	40	run as. .groups files are treated analogously for UNIX groups. .paths
	41	files work in the same way for specifying filesystem paths that users
	42	are permitted to use in daemon configuration. Any recursive
	43	subdirectory of a path in .paths is also allowed.
	44
	45	Obviously this system is useless if domain administrators are
	46	permitted to edit these files themselves. The tools that read config
	47	files will check that such files are owned by a set UNIX user, which
	48	will probably be a special user you create for domtool.
	49
	50	For convenience, there is also a mechanism for defining
	51	variables. .vars files are treated in the same inheriting fashion, but
	52	they contain lines of variable names separated from their values by
	53	whitespace. Variables are currently intended to be used to give
	54	shorthand names for the IP addresses of particular machines that will
	55	often come up in configuration while avoiding the potential
	56	chicken-and-egg problem of looking up hostnames while configuring DNS.
	57
	58
	59	Software organization
	60	---------------------
	61
	62	First things first: All of the software here is written in Standard
	63	ML. You can find compilers and educational material on it starting at
	64	http://www.standardml.org/. One of the domtool authors has also
	65	written an SML advocacy page that you can find at
	66	http://www.hprog.org/fhp/MlLanguage. We quite realize that SML is far
	67	from being popular with the general development community, but we hope
	68	you'll see why it's such a great language to use if you give it a try.
	69
	70	The code in src/ handles the basic structure described above. Actual
	71	interaction with particular daemons is handled by
	72	modules. src/domtool.sig gives the interface that they may use to hook
	73	into the main tool. This transfer of control is based on configuration
	74	file names. Modules register particular configuration file names that
	75	they handle when such files are found in domain directories. There may
	76	also be one default handler registered, which is called for otherwise
	77	unmatched files that are valid Internet hostnames. Currently this is
	78	assumed to be a handler for Web virtual hosts, but it would be easy to
	79	do something else with these files.
	80
	81	Tweakable configuration options are controlled throughout by SML
	82	source files. Everything is designed to be compiled with the MLton
	83	compiler (http://www.mlton.org/). MLton is a whole-program compiler
	84	and will integrate the settings in the various config files into the
	85	compiled code. If you have a current version of MLton installed, you
	86	should be able to run 'make' in this directory and build everything
	87	fine after you copy all config.sample.sml files to config.sml files
	88	and configure local settings.
	89
	90	In the subdirectories of src/, you'll find various modules and
	91	additional command line programs. Each of these will typically have a
	92	config.sample.sml file that you should copy to config.sml and modify
	93	to set local options. Each should also contain a README file
	94	explaining the basics of the module or tool.
	95
	96
	97	Usage of the command-line tool
	98	------------------------------
	99
	100	Running the program that builds in bin/domtool with no parameters will
	101	crawl over the domain tree reading configuration files. As it goes, it
	102	writes temporary versions of the new system configuration files in a
	103	location configured by the scratchDir variable in
	104	src/config.sml. After everything is read, a quick switch-over to the
	105	new files is performed, along with poking any daemons that need to
	106	reload configuration or restart. This change-over is done by running
	107	bin/domtool with the single argument 'publish'. It shouldn't be
	108	necessary to run this manually. Domtool itself will re-run itself with
	109	elevated permissions using sudo, or whatever other means you
	110	configure. (See below)
	111
	112	The final way to use domtool is as follows:
	113	domtool mkdom domain.name user
	114	This creates the appropriate directory in the domain tree, setting it
	115	up to be administered by the specified UNIX user. It is not necessary
	116	to set up new domains this way. Just creating a directory in the right
	117	place will work fine. Mkdom just does some helpful things like
	118	automatically generating the access control files and chown'ing them
	119	to the right user.
	120
	121
	122	Handling permissions
	123	--------------------
	124
	125	At hcoop, we make extensive use of sudo
	126	(http://www.courtesan.com/sudo/) to give our members access to
	127	modify system configuration files in safe ways. Here's the basic
	128	setup, which you may or may not want to emulate:
	129
	130	We have a user 'domains.'
	131
	132	We have the program that builds in bin/domtool in
	133	/usr/local/bin/domtool.real.
	134
	135	We have a script in /usr/local/bin/domtool that runs:
	136	sudo -u domains /usr/local/bin/domtool.real
	137
	138
	139	In /etc/sudoers, we have:
	140
	141	A group of users allowed to run domtool:
	142	User_Alias DOMTOOL_USERS = user1,user2,user3
	143
	144	Authorization for these users to run domtool as user domains:
	145	DOMTOOL_USERS ALL = (domains) NOPASSWD:
	146	/usr/local/bin/domtool.real
	147
	148	Authorization for user domains to run domtool publish:
	149	domains ALL = (root) NOPASSWD:
	150	/usr/local/bin/domtool.real publish