TOOLS FOR COOPERATIVE INTERNET HOSTING http://hcoop.sf.net/ Introduction ------------ This package collects tools that have been found useful in running Internet servers cooperatively for the Internet Hosting Cooperative (http://hcoop.net/). The inclusion of all of them in this package isn't always particularly well motivated. However, everything here should be of potential interest to the general sysadminning public. The basic goal here is to provide Internet hosting services that meet the following criteria: * A group of people share the resources of a server. * People should be prevented from breaking other people's services. * It should be easy to administer your own services. * The base interface should be attractive to expert users, which includes making it relatively easy to manipulate with scripts. Domtool basics -------------- The central organizing principle of the tools here is to represent all domains hosted on a machine as parts of a directory tree mirroring the structure of Internet domain names. Configuration files relevant to daemons that have per-domain/hostname configuration live in the directories for the domains whose settings they control. Standard UNIX filesystem permissions control who is allowed to change the settings for which domains. There are also additional controls related to which users, groups, and paths may be used in configuration files. Each directory in the domain tree may contain a .users file which lists UNIX usernames on separate lines. The union of the users specified in a domain's directory and all its parent directories in the domain tree specifies which users administrators of that domain are allowed to delegate for processes to run as. .groups files are treated analogously for UNIX groups. .paths files work in the same way for specifying filesystem paths that users are permitted to use in daemon configuration. Any recursive subdirectory of a path in .paths is also allowed. Obviously this system is useless if domain administrators are permitted to edit these files themselves. The tools that read config files will check that such files are owned by a set UNIX user, which will probably be a special user you create for domtool. For convenience, there is also a mechanism for defining variables. .vars files are treated in the same inheriting fashion, but they contain lines of variable names separated from their values by whitespace. Variables are currently intended to be used to give shorthand names for the IP addresses of particular machines that will often come up in configuration while avoiding the potential chicken-and-egg problem of looking up hostnames while configuring DNS. Software organization --------------------- First things first: All of the software here is written in Standard ML. You can find compilers and educational material on it starting at http://www.standardml.org/. One of the domtool authors has also written an SML advocacy page that you can find at http://www.hprog.org/fhp/MlLanguage. We quite realize that SML is far from being popular with the general development community, but we hope you'll see why it's such a great language to use if you give it a try. The code in src/ handles the basic structure described above. Actual interaction with particular daemons is handled by modules. src/domtool.sig gives the interface that they may use to hook into the main tool. This transfer of control is based on configuration file names. Modules register particular configuration file names that they handle when such files are found in domain directories. There may also be one default handler registered, which is called for otherwise unmatched files that are valid Internet hostnames. Currently this is assumed to be a handler for Web virtual hosts, but it would be easy to do something else with these files. Tweakable configuration options are controlled throughout by SML source files. Everything is designed to be compiled with the MLton compiler (http://www.mlton.org/). MLton is a whole-program compiler and will integrate the settings in the various config files into the compiled code. If you have a current version of MLton installed, you should be able to run 'make' in this directory and build everything fine after you copy all config.sample.sml files to config.sml files and configure local settings. In the subdirectories of src/, you'll find various modules and additional command line programs. Each of these will typically have a config.sample.sml file that you should copy to config.sml and modify to set local options. Each should also contain a README file explaining the basics of the module or tool. Usage of the command-line tool ------------------------------ Running the program that builds in bin/domtool with no parameters will crawl over the domain tree reading configuration files. As it goes, it writes temporary versions of the new system configuration files in a location configured by the scratchDir variable in src/config.sml. After everything is read, a quick switch-over to the new files is performed, along with poking any daemons that need to reload configuration or restart. This change-over is done by running bin/domtool with the single argument 'publish'. It shouldn't be necessary to run this manually. Domtool itself will re-run itself with elevated permissions using sudo, or whatever other means you configure. (See below) The final way to use domtool is as follows: domtool mkdom domain.name user This creates the appropriate directory in the domain tree, setting it up to be administered by the specified UNIX user. It is not necessary to set up new domains this way. Just creating a directory in the right place will work fine. Mkdom just does some helpful things like automatically generating the access control files and chown'ing them to the right user. Handling permissions -------------------- At hcoop, we make extensive use of sudo (http://www.courtesan.com/sudo/) to give our members access to modify system configuration files in safe ways. Here's the basic setup, which you may or may not want to emulate: We have a user 'domains.' We have the program that builds in bin/domtool in /usr/local/bin/domtool.real. We have a script in /usr/local/bin/domtool that runs: sudo -u domains /usr/local/bin/domtool.real In /etc/sudoers, we have: A group of users allowed to run domtool: User_Alias DOMTOOL_USERS = user1,user2,user3 Authorization for these users to run domtool as user domains: DOMTOOL_USERS ALL = (domains) NOPASSWD: /usr/local/bin/domtool.real Authorization for user domains to run domtool publish: domains ALL = (root) NOPASSWD: /usr/local/bin/domtool.real publish