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