.\" $Id: hxmd.man,v 1.93 2012/02/03 21:06:24 ksb Exp $
.\" $Compile: Display%h
.\" $Display: ${groff:-groff} -Tascii -man %f | ${PAGER:-less}
.\" $Display(*): ${groff:-groff} -T%s -man %f
.\" $Install: %b -mDeinstall %o %f && cp %f $DESTDIR/usr/local/man/man5/hxmd.5
.\" $Deinstall: ${rm-rm} -f $DESTDIR/usr/local/man/[cm]a[nt]5/hxmd.5*
.TH HXMD 5L LOCAL
.SH NAME
hxmd \- file format for hxmd configuration files
.SH DESCRIPTION
.nf
\fB#\fP \fIcomment to end of line\fP
\fB%\fP\fIkey-macro\fP [\fIattributes\fP]
\fIkey-value1\fP [\fIattribute-values\fP]
\fIkey-value2\fP [\fIattribute-values\fP]
\fI...\fP
.fi
\fIcommon-attribute\fP\fB=\fP\fIvalue\fP
or
\fIcommon-attribute\fP\fB=.\fP

.P
All of this is covered in the \fBhxmd\fP(8l) manual page under the
\fBCONFIG\fP section.

.P
The rules for an \fBhxmd\fP (aech-ex-em-dee) configuration file follow some
common UNIX convention:
.TP
octothorp (\fB#\fP) to end-of-line comments
Just like most shells \fBhxmd\fP ignored unquoted "hash" or "pounds-sign"
comments.
.TP
\fBm4\fP quotes to quote white-space or comments
Since \fBhxmd\fP uses \fBm4\fP(1) to process attributes it uses
those same quoting rules for attributes in the configuration files.
.TP
\fBC\fP quotes to quote things \fBm4\fP can't
Like the word "can't" is hard to quote in \fBm4\fP, but easy under
\fBC\fP double-quote rules.
.TP
Arbitrary white-space as a separator
This is taken from \fBawk\fP(1).  If you want white-space to matter
you have to quote it in \fBm4\fP or \fBC\fP quotes.  You can't make
white-space work in the \fIkey\fP macro (see \fBhxmd\fP(8l), under \fB\-k\fP).

.P
Strange to \fBhxmd\fP is the idea that the value dot (\fB.\fP)
represents the undefined value.  But not so strange if you used
\fBdistrib\fP(8l).
.P
Unique to \fBhxmd\fP is the idea of a variable header.  Each item in
the configuration is specified with a definition line.  That line
should provide a value for each macro listed in the most recent header.
.P
A header starts with a percent sign (\fB%\fP) and defines a list of
the attribute macros that define elements by a list of the require
attributes.  It can be changed later in the file by
repeating the percent sign markup with a new list.
.P
For example below says that each "HOST" should specify an "OWNER":
.RS
.nf
\fB%\fPHOST OWNER
.fi
.RE
The list under that might look like:
.RS
.nf
imp.npcguild.org	ksb
foo.movie.com	`Paul A. Smith'
bar.example.com	.
.fi
.RE
That list tells us that "imp" is owned by me, "foo" by Paul,
and "bar" doesn't have an owner.
.P
The \fIkey-macro\fP may actually be included anywhere in the list
(it doesn't have to be the first macro) and may be specified as a
single percent sign (\fB%\fP) to accept the specified command-line value
(usually under the application's \fB\-k\fP option).
.P
An \fIattribute\fP macro name of dot (\fB.\fP) specifies that the
associated column should be discarded.  Use this to delete columns
generated by automation (under \fB\-o\fP) via the header, never parse
the quoted values yourself.  Rather apply a tool like \fBsed\fP
to substitute the percent header line.
.P
An \fIattribute\fP macro value of double-dot (\fB..\fP) specifies that the
associated macro should have the current in-scope value.
.RS
.nf
OWNER=`ksb'
\fB%\fPHOST             OWNER
imp.npcguild.org	..
nostromo.npcguild.org	..
sulaco.npcguild.org	agt
aisequo.npcguild.org	..
.fi
.RE
This allows an explicit way to compress a common value for many
hosts into a much more compact form.


.SH CONVENTION

To use \fBhxmd\fP as the basis for the master source system we
install two configuration files on every host, and some extra
site policy files:
.TP
\fBmsrc.cf\fP or \fBmsrc.zf\fP
This file defines the default values for the attributes \fBmsrc\fP
needs to know that might be host specific: the path to ssh(1),
rdist(1), rdistd, and the like.  It is usually updated from the
distribution one by site policy.
.TP
\fBauto.cf\fP
This should hold the information about the local host's attributes.
The file is used in the "pull" version of the master source to
tell us all the attributes we need to build for the host we are
currently on.  Some effort is made to make a sane version when
we build a RPM, but it doesn't always work.
.TP
\fBempty\fP
An empty file which can be used by clever coders to get an
anonymous temporary file from \fBhxmd\fP for data collection
purposes.
.TP
\fBclass.m4\fP
This is an example site policy macro that converts a hostname to a "class"
based on the spelling of the name.  It should be viewed as
an example only, not a suggested implementation.  Hosts can force
a class with a definition of \fBCLASS\fP.
.TP
\fBcronsup.m4\fP, \fBgnumake.m4\fP, \fPsendfile.m4\fP
Other files with example markup.

.SH EXAMPLES
.TP
.nf
ENTRY_LOGIN="source"
.fi
Set the attribute "ENTRY_LOGIN" to "source" until it is defined
as a header macro, or reset by another assignment.
.TP
.nf
PERIOD=`.'
.fi
Set the attribute macro "PERIOD" to a literal dot.
.TP
.nf
PERIOD="."
.fi
Same as the last example, but use \fBC\fP quotes.
.TP
.nf
%HOST SHORTHOST HOSTTYPE HOSTOS HASSRC
.fi
Set the \fBdistrib\fP default headers.
.TP
.nf
%HOST
.fi
Set the \fBhxmd\fP default headers.
.TP
.nf
% %
.fi
Set the header to just the current key macro.
.TP
.nf
lv426.npcguild.org
sulaco.npcguild.org
.fi
Define two hosts using the header line above.
.TP
.nf
%SHORTHOST HOST
.fi
Set the headers to move the SHORTHOST to the first word, the key specified
on the command line (under \fB\-k\fP) could be either of these.
.TP
.nf
nostromo nostromo.example.com
.fi
Define a host named "nostromo.example.com", using the last header definition.
.TP
.nf
%ENDPT DIALME TUNNEAR TUNFAR DESTNET KEYFILE
.fi
This is a real example of the \fBopenvpn\fP header line I actually use.
.TP
.nf
ENTRY_LOGIN=.
.fi
Unset the ENTRY_LOGIN attribute for all hosts defined below this line.

.SH BUGS
This is not really a bug in the code, more a bug in the design: when
a configuration file is read under \fB\-Z\fP any in-scope
definitions are set as default values for hosts in subsequent files,
\fBunless\fP they are part of the header markup (\fB%\fP).  So
this example file does \fBnot\fP set a default for "WHAM":
.RS
.nf
%HOST	\fBWHAM\fP	BIFF
sulaco	no	yes
nostromo	yes	yes
# comment on the fact the next line doesn't work
WHAM=`always'
.fi
.RE
.P
To make this work as intended just replace the lines from comment line on, with
this text:
.RS
.nf
# Reset column headers to set a defaults for subsequent hosts.
%%
WHAM=`always'
.fi
.RE
This is mandatory because all of the column header macros are withdrawn at
the end of the file, if "WHAM" is one it will be undefined at the end of file.
The use of the shorthand percent (\fB%\fP) to name the key macro is always
safe, even if the command-line changed that macro name.

.SH AUTHOR
KS Braunsdorf
.br
hxmd at-not-spam ksb dot npcguild.org
.PP
.SH "SEE ALSO"
.hlm 0
m4(1), cc(1), hxmd(8l), msrc(8l), mmsrc(8l), efmd(8l), sed(1), distrib(8l)