Configuring Wigwam Services
Configuring the services comes in several parts:
- Determine the Role for each Playpen.
Each playpen you run Wigwam on has a role. The role of a playpen is found in a file etc/role. This file should not be checked into CVS.
Role files on clusters are made by pubtool.
- Configuring the Roles
The roles are arranged in directories, etc/roles/$role_name/. Currently there is only one file: a sh-script named config that is sourced before starting or stopping the services.
From a sh-script you may load these environment variables by sourcing the ext/bin/load-config script.
- Service-Specific Configuration
[TODO: re write some of this info and put it in the how wigwam is organized section]
The configuration files used by the service are generally substituted using the sub-conf program. These means that they can be configured by environment variables, and it means that the package provides a configuration file in ext/etc which can be overridden a copy in etc. This allows you to make a project-specific version of that file.
If the environment variable applies across an entire cluster, you should put that variable in etc/clusters/$CLUSTER/config. If it applies to a role generally, you should put that variable in in etc/roles/$ROLE/config.
All such services' actual configuration files should put in ext. There are a few paths which are in standard locations relative to the installed config file. We will give examples, assuming the config file is in ext/foo/dummy.
Sometimes, even with substitution, the distributed configuration file is not flexible enough. In that case you may provide an equivalent configuration file as just foo/dummy (that is, the same path, but with ext cut off the front). Such a modified file should be checked into CVS and is global to the project.
Sometimes, for testing, you may wish to change the conf file without affecting the version in the CVS repository. For this purpose, if foo/dummy.local is available, it will be substituted instead.
The Playpen config File
Each playpen has a role specified by etc/role. Each role has a config file in etc/roles/$PLAYPEN_ROLE, which may set certain shell variables:
- playpen_services
List of services which are run in this role by default.
Wigwam Cluster Configuration
A cluster is a group of machines that you can publish to. They have identical content, but they often run different services. We classify the machines into roles, which are nothing more than configuration variables and a list of services to run.
Clusters are configured in directories etc/clusters/$CLUSTER. Each directory contains a file hosts. Each line in that file starts with a comma-separated list of hosts, then a few key-value pairs. For example:
host1,host2,host3 role=webserver playpen_root=/tmp username=daveb |
- role
The role the machine is supposed to play. There should be a directory checked into CVS, etc/roles/$PLAYPEN_ROLE/, that contains configuration for the role, including what services should be run.
- playpen_root
The PLAYPEN_ROOT of this project on the host. Please note that it is extremely important that $PLAYPEN_ROOT point to different paths on different hosts. This won't work if playpen_root points to a shared drive.
- username
The username to use when connecting to this host; if not specified, no username will be given to ssh.
- ssh_identity
ssh identity file to use when performing commands in parallel on the cluster. If not specified, no identity file will be used.
- ssh_flags
Extra options for ssh when performing commands in parallel on the cluster.
- rsync_flags
Extra options for rsync when copying the project to the cluster.
A common option is -t, which will cause rsync to preserve the timestamps on the files it transfers. This can speed up publication significantly, especially if your project has a lengthy compilation phase. However, you must make sure the clocks on all the machines in your cluster are synchronized (e.g., using ntpd) for it to be safe. If you specify rsync_flags=-t and the machines' clocks are not synchronized, make and its ilk are likely to get confused and build the project incorrectly.
- disconnected
This host or hosts is not attached to the same network as one of the package archives.
Wigwam will automatically run an http-proxy, tinyproxy, and use ssh-port-forwarding (the -R option) to download all the packages, so that only the machine from which you are publishing needs to be attached to the net.
You can specify default values for any of the keys by including a line with the special hostname _default. The default values only apply to hosts listed after the _default line. For example:
_default playpen_root=/web/myproject |
Clusters, like roles, may also have a config file which will be sourced by ext/bin/load-config. It should set variables for the cluster that override variables in project.conf.
There can also be a file default-tag-prefix in etc/clusters/$CLUSTER to control the default prefix to use when making CVS tags for publishing to the cluster. If this file is not present, the default tag prefix will be live.
Finally, on some clusters, services which are normally in Wigwam are available outside of Wigwam. For example, on some clusters, all projects may use a common database. To indicate that, make a file, etc/clusters/$CLUSTER/foreign-services which contains a list of services which are available globally on this cluster.
Using clusterctl
- Table of Contents
- clusterctl -- run something on all the hosts in a cluster