To understand this document

This is a base document. You mostly just need to read it and try to understand the ideas. Later you can come back to understand how this impacts other aspects of the configuration structure at your site..

Having it your way

It is really cool and groovy how the whole msrc building an hxmd, instancing an xapply machine, wrapped in xclates above and below, to collate output works. But it doesn't do much for you until you build a local configuration.

The local configuration consists of some hxmd data files that describe your host populations (you can have as many of these as you need) and a zero configuration file to set the default attribute macros for msrc for transport options. You can even build multiple default attribute macro files.

There is a remote configuration too, which we'll get to below.

The key attributes in a zero configuration file

We need to tell hxmd what default attribute macros to set when msrc uses it to visit hosts. I'm sure you've already read the hxmd HTML document and the msrc HTML document, so we don't have to review all that material. In this context you need to remember which of the attribute macros are used by the application as hooks, and which are used by the structure itself.

These three attributes are almost always used by any "Msrc.hxmd" files to hook back to the make recipe file, so avoid setting them: INIT_CMD, PRE_CMD, and POST_CMD.

The HOST macro and the other four distrib used (SHORTHOST HOSTTYPE, HOSTOS, and HASSRC) would not be global preferences. So don't set those here.

That leaves the attributes that describe how to get the each machine (RSH_PATH and SSH) and who to become there (ENTRY_LOGIN), what to source to get a clean environment (ENTRY_DEFS), and which transport programs to use (RDISTD_PATH, RDIST_PATH and SDIST). Of those you needn't set any. The structure should work if you can ssh over to each host with the default ssh program, and if rdist is installed in the default search path on both ends.

I usually do change RDIST_PATH to suppress rdist's chatty nature. One could add the -q option to rdist or include shell markup to redirect the stdout stream to the bit-bucket.

The other tune I include, in the default hxmd file for msrc, is an ENTRY_DEFS that is backwards compatible with the old master source system: the old system always sourced a shell file named "/usr/local/lib/distrib/local.defs". You could spell the filename anyway local policy requires in the new system, and even put the file in a different place for different groups of hosts.

Here is an example msrc.cf from my site policy:

# $Id: msrc.cf,v ...
# Hxmd configuration (designed for the -Z option) which sets all the	(ksb)
# macro definitions that msrc needs to set to locally significant values.
ENTRY_DEFS=`/usr/local/lib/distrib/local.defs'
RDIST_PATH=`rdist >/dev/null'

which looks a lot like the default one shipped in this directory, but forces the local.defs path.

The list of hosts

After we've told msrc "how", "who", "what" and "which" we need to tell hxmd where (a list of hosts) and why (other attributes about those hosts).

I break my hosts into realms. For example the "dmz" realm holds the hosts that run our Internet face. The "sac" realm holds the workstations and test hosts for the system administration group. One large file with all your hosts in it is also a workable solution.

Since hxmd reads as many configuration files as you like (under -C) you can build one file per host, if you feel that's a good solution to your local issues. I'm pretty sure that doesn't scale to thousands of hosts.

Pick a name (like mysite.cf) build the file here. I used sac.cf, and it starts out like:

# $Id: ...
%HOST
w01.sac.fedex.com
w02.sac.fedex.com
adm0.sac.fedex.com....

Add the file name to the Makefile in the SOURCE macro, and in Makefile.host to the DATA macro. After that, when you run mmsrc (or msrc) to install this directory the new "mysite.cf" file should become available via hxmd under -C without a full pathname. We'll add a shell script (called "dmz.sh" in msrc's source directory) later so we don't have to type that option over and over.

Keep that list of hosts up-to-date. Put an revision control spell over it (subversion, RCS, SCCS, CVS, or what ever you like) and keep track of the current revision. Break it up later into realms, only if you need to.

Now you must prime the pump for ssh. If you don't give it a chance to record the host keys for each host ssh is going to go interactive on you at the worst time to ask if the host key matches for each of your hosts. To prevent this make sure you have an active ssh-agent loaded with your keys, then run a command like:

hxmd -xP1 -C mysite.cf 'ssh -o "Batchmode=yes" -n HOST date'

which asks hxmd to verify the file is syntactically correct, the trace the launch of an ssh to each host sequentially to run date.

Remove the "Batchmode" option to verify host keys then fix any errors you see in that output: misspelled hosts, mismatched host keys, incorrect dates, and the like. Later the -P1 can be made wider, but the secure shell client sometimes steps on the known_hosts file with large numbers of parallel updates.

Now you must add some additional facts about each host. For the base tools to work you must add "HOSTTYPE" and "HOSTOS" to the file. If all your hosts are the same, you may add them as macro=value lines before the host list:

# $Id:...
HOSTTYPE="value"
HOSTOS="value"
%HOST
host1
host2...

If they are a mixed set you should use the column-style for each host.

# $Id:...
%HOST	HOSTTYPE	HOSTOS"
host1	type1		os1
host2	type2		os2

I use the columns for attributes like a serial number: all hosts have one and they are all different. I use the "set it an forget it" style for attributes that are common to a large section of the file, or to all hosts in the file.

If you use the set-it-here style you might need to "unset it" after the end of the hosts that have that attribute, this can be hard to remember, so write a sanity checker if you need one.

The triggers

The when part of the system is broken in to two parts: different files for different populations, and different triggers to start the processes.

We might break the list of hosts up on a few criteria: the mechanism to gain access, the political span of administrative control, or the class of support (viz. test, development, beta, production). That partitioning is largely up to you.

A crontab, at, or batch command can trigger a shell action to start the process to touch a list of hosts. My kicker batch-file injector, the op or sudo rule-base may include scripts to run hxmd on a list of hosts. Any task management service (even a web CGI) could start the ball rolling.

Other attribute lists

The example above of the serial number of the hosts is not a fiction. But the group that keeps track of asset management might not be the group that does the software provisioning for the site. These two groups only have to agree on the key field (usually the "HOST" attribute macro).

Then the Hardware guys can keep "hardware.cf" up to date with 3 columns:

# $Id: hardware.cf,v ...
%HOST			SNUMBER		LOCATION
host1.example.com	5271010		E101:97:1
host2.example.com	1964215		E101:97:2
...

The Software guys can merge that file in with "-X hardware.cf" when they need to use the location or serial number to select a host or report on a host's status.

Classes of hosts

By a class we mean hosts with similar application stacks, a common set of logins and groups, and maybe a common set of privilege escalation rules. I use a common basename for hosts of the same "class". For example the "cache" class might have members "cache1", "cache2", ... up to "cache32" (today) and some preproduction members "cachetest1" and "cachetest2".

The file "class.m4" always (in my implementations) contains a macro CLASSOF which converts a given HOST into the name of the parent class. It should hide any local macros behind the local political domain. The example in this directory uses the domain "my", and is actually not the one I use in my group.

The shorthand macro CLASS just expands to CLASSOF(HOST), which is what you want most of the time. Sometimes you need to find the class of a host you found by a macro like NFS_SERVER or HIS_NAME.

You should edit that file so it turns your local hostnames into classes, if you are going to use that (for op's rule-base) later on. See the HTML documentation.

Remote configuration in `auto.cf`

The configuration file auto.cf is generated by some detailed m4 markup in auto.cf.host. This includes macros which describe some of the macro values needed to push or pull updates to the local host.

These should include at least some of the lines below. Other additions to this file would be local site policy.

DATE_STAMP="date when file created"

A comment that lets an admin know when the update was built, the time on the file tell when it was installed. It may have been packaged in an RPM or tar archive for quite some time.

ENTRY_DEFS="absolute path to local.defs"

RDISTD_PATH="path to rdistd on this host"

#RDIST_PATH="path to rdist on msrc host"

There may be useful for local self-updates. The RDIST_PATH is a comment because there is no proof that the source host has the same location as the client (which may have different everything from each other) for rdist.

# preserved pull update information

If this line is in the file then the update was a pull, rather than a push.

Only if this line is present should the next three lines be included.

MSRCMUX="tcmpmux name for msrcmux"

MSRCMUX_MPS="msrc pull service CNAME"

MSRCMUX_CFG=" config given to mmsrc for target host"

All the information required to connect to the pull service to ask for another update: the RFC1078 service name, the host to connect to, and the configuration file which contains our definition.

For example:

muxcat MSRCMUX_MPS MSRCMUX local/bin/flock MSRCMUX_CFG > /tmp/$TFILE.tar

%HOST SHORTHOST HOSTTYPE HOSTOS HASSRC

FQDN short-name hosttype base10-OS-version ..

localhostdomain.site.tld localhost hosttype base10-OS-version ..

localhost localhost hosttype base10-OS-version ..

I always use localhost, but other site policy calls for the hostname. If you don't specify one you may update the host three times. If you specify a common name for the host you might match none of the lines.

None of these sets HASSRC because we really do not know if this host should have a full platform source.

Other nits

If your version of ssh is not up to snuff you might need to specify a path to another for some group of hosts, or build a script that adds command-line options to the vanilla ssh to diddle options. You might also want to apply the high performance network patches to ssh.