Commit | Line | Data |
---|---|---|
182a2654 AC |
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 |