welcome: please sign in

Diff for "DomTool/UserGuide"

Differences between revisions 1 and 2
Revision 1 as of 2006-12-17 18:38:30
Size: 1829
Editor: AdamChlipala
Comment: Overview
Revision 2 as of 2006-12-17 19:05:05
Size: 5594
Editor: AdamChlipala
Comment: Configuration files
Deletions are marked like this. Additions are marked like this.
Line 16: Line 16:

= Configuration files =

In this example, we'll assume that you've requested and been granted privileges to some Internet domain name (like `you.com`) via our [https://members.hcoop.net/portal/domain web portal]. If you ''don't'' want to configure a domain that you own, then you don't need to be using DomTool!

You will edit a text file with the configuration directives you want applied your domain. Where `$USER` is your HCoop username and `$DOMAIN` is your domain name, you should write configuration into a file `/afs/hcoop.net/usr/$USER/domtool/$DOMAIN`. If you're logged into one of our servers, `cd ~/domtool` should get you to the proper directory.

We leave it up to you to choose how to edit the source file. You might run something like `emacs $DOMAIN` over SSH, or you might open it locally if you have our AFS cell mounted in your local filesystem.

In this file `$DOMAIN`, you can write:
{{{dom "$DOMAIN" with
end;}}}

You should replace `$DOMAIN` with the actual domain name. This example introduces the simplest useful configuration, based on the `dom` directive. What does this source file accomplish? It:
 * Declares our nameservers as authoritative for your domain.
 * Declares that Exim should handle e-mail for your domain.
 * Directs Exim to send all mail to your domain to your mailbox.
 * Adds a DNS mapping from `www.yourdomain.com` to our web server's IP address.
 * Creates an Apache virtual host at that hostname serving `~$USER/public_html/`.

There are more primitive configuration directives to set up each of these features individually. `dom` packages all of the functionality together in an easy-to-use package. One of the main principles behind DomTool and our use of it is to '''avoid configuration repetition wherever possible'''. The DomTool language contains several abstraction features familiar from high-level programming languages, as well as some new ones, all in support of abstracting common code patterns into programming language entities that can be called multiple times. In general, if you find yourself writing the same code over and over again, let us know, and we'll try to add a new abstraction to our standard library! You could even write such an abstraction yourself, but that's beyond the scope of this intro document.

Now, enough talk; let's execute our source file! Assuming that you're in your `domtool` directory, run{{{
domtool $DOMAIN}}}

This contacts our central dispatcher server over an SSL connection. Once the server verifies that you are who you say you are, it will publish your configuration to the affected daemons, and you should be able to start using your domain.

You could also simply run{{{
domtool}}}
which calls the dispatcher with '''all''' configuration files in your `domtool` directory, regardless of what your current working directory is. This can be a helpful shortcut sometimes, though it can be noticeably less efficient than calling `domtool` with the single domain that you know you've changed.

In fact, the names of the source files in your `domtool` directory don't matter. We recommend storing the configuration for each of your domains in a separate file named after that domain, but you might want to make different choices. For instance, you might want to use an abstraction that configures multiple domains at once. However, it '''is''' important that you keep all your permanent configuration files in your `domtool` directory. Sometimes we need to reprocess all configuration from scratch, and in such cases our dispatcher will only look for source files in your `domtool` directory. For temporary experimentation, though, you can feel free to store source files elsewhere and run them explicitly with `domtool $FILENAME`.

TableOfContents()

Overview

HCoop is almost unique in the history of the Internet. We are trying to provide highly configurable Internet hosting to the general public while maintaining a high level of security, so that your services keep running and your data stays safe and private. You can probably see that these goals conflict in a number of ways! Since our organization's birth in 2002, we've been evolving tools to help us reconcile these different goals. This document introduces the primary element of our current solution.

This solution is called DomTool, and here's the one-line summary of what it's all about:

  • DomTool enables HCoop members to use a domain-specific programming language to describe how to configure daemons spread across our servers.

Some other cogent properties of DomTool:

  • The language is a [http://en.wikipedia.org/wiki/Statically_typed statically-typed], [http://en.wikipedia.org/wiki/Purely_functional purely functional] programming language. Other functional programming languages that you might have heard of include Lisp, Scheme, ML, and Haskell. Haskell and ML are statically-typed, and Haskell is purely functional.

  • The language has a rich and extensible type system that can enforce complicated security policies through type-checking.

  • Configuration works via a distributed client/server architecture, so, with the right software installed, you can configure your domains from anywhere.

Some readers may be scared off by this level of technical jargon. We apologize, but we just couldn't help showing it off. ;-) The rest of this document will be aimed at the average member, assuming only a solid understanding of the basics of Linux and the Internet. In particular, we assume no experience with particular kinds of programming.

Configuration files

In this example, we'll assume that you've requested and been granted privileges to some Internet domain name (like you.com) via our [https://members.hcoop.net/portal/domain web portal]. If you don't want to configure a domain that you own, then you don't need to be using DomTool!

You will edit a text file with the configuration directives you want applied your domain. Where $USER is your HCoop username and $DOMAIN is your domain name, you should write configuration into a file /afs/hcoop.net/usr/$USER/domtool/$DOMAIN. If you're logged into one of our servers, cd ~/domtool should get you to the proper directory.

We leave it up to you to choose how to edit the source file. You might run something like emacs $DOMAIN over SSH, or you might open it locally if you have our AFS cell mounted in your local filesystem.

In this file $DOMAIN, you can write: {{{dom "$DOMAIN" with end;}}}

You should replace $DOMAIN with the actual domain name. This example introduces the simplest useful configuration, based on the dom directive. What does this source file accomplish? It:

  • Declares our nameservers as authoritative for your domain.
  • Declares that Exim should handle e-mail for your domain.
  • Directs Exim to send all mail to your domain to your mailbox.
  • Adds a DNS mapping from www.yourdomain.com to our web server's IP address.

  • Creates an Apache virtual host at that hostname serving ~$USER/public_html/.

There are more primitive configuration directives to set up each of these features individually. dom packages all of the functionality together in an easy-to-use package. One of the main principles behind DomTool and our use of it is to avoid configuration repetition wherever possible. The DomTool language contains several abstraction features familiar from high-level programming languages, as well as some new ones, all in support of abstracting common code patterns into programming language entities that can be called multiple times. In general, if you find yourself writing the same code over and over again, let us know, and we'll try to add a new abstraction to our standard library! You could even write such an abstraction yourself, but that's beyond the scope of this intro document.

Now, enough talk; let's execute our source file! Assuming that you're in your domtool directory, run

domtool $DOMAIN

This contacts our central dispatcher server over an SSL connection. Once the server verifies that you are who you say you are, it will publish your configuration to the affected daemons, and you should be able to start using your domain.

You could also simply run

domtool

which calls the dispatcher with all configuration files in your domtool directory, regardless of what your current working directory is. This can be a helpful shortcut sometimes, though it can be noticeably less efficient than calling domtool with the single domain that you know you've changed.

In fact, the names of the source files in your domtool directory don't matter. We recommend storing the configuration for each of your domains in a separate file named after that domain, but you might want to make different choices. For instance, you might want to use an abstraction that configures multiple domains at once. However, it is important that you keep all your permanent configuration files in your domtool directory. Sometimes we need to reprocess all configuration from scratch, and in such cases our dispatcher will only look for source files in your domtool directory. For temporary experimentation, though, you can feel free to store source files elsewhere and run them explicitly with domtool $FILENAME.

DomTool/UserGuide (last edited 2021-02-24 02:49:10 by ClintonEbadi)