README

   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