Initial revision
[hcoop/zz_old/domtool.git] / README
5 Introduction
6 ------------
8 This package collects tools that have been found useful in running
9 Internet servers cooperatively for the Internet Hosting Cooperative
10 ( 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.
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.
23 Domtool basics
24 --------------
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.
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.
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.
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.
59 Software organization
60 ---------------------
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 One of the domtool authors has also
65 written an SML advocacy page that you can find at
66 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.
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.
81 Tweakable configuration options are controlled throughout by SML
82 source files. Everything is designed to be compiled with the MLton
83 compiler ( 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.
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.
97 Usage of the command-line tool
98 ------------------------------
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)
112 The final way to use domtool is as follows:
113 domtool mkdom 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.
122 Handling permissions
123 --------------------
125 At hcoop, we make extensive use of sudo
126 ( 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:
130 We have a user 'domains.'
132 We have the program that builds in bin/domtool in
133 /usr/local/bin/domtool.real.
135 We have a script in /usr/local/bin/domtool that runs:
136 sudo -u domains /usr/local/bin/domtool.real
139 In /etc/sudoers, we have:
141 A group of users allowed to run domtool:
142 User_Alias DOMTOOL_USERS = user1,user2,user3
144 Authorization for these users to run domtool as user domains:
146 /usr/local/bin/domtool.real
148 Authorization for user domains to run domtool publish:
149 domains ALL = (root) NOPASSWD:
150 /usr/local/bin/domtool.real publish