HXMD(5)                                                                HXMD(5)



NAME
       hxmd - file format for hxmd configuration files

SYNOPSIS
       # comment to end of line
       %key-macro [attributes]
       key-value1 [attribute-values]
       key-value2 [attribute-values]
       ...
       common-attribute=value or common-attribute=.

DESCRIPTION
       All  of  this  is  covered in the hxmd(8l) manual page under the CONFIG
       section.

       The rules for an hxmd (aech-ex-em-dee) configuration file  follow  some
       common UNIX convention:

       octothorp (#) to end-of-line comments
              Just  like  most shells hxmd ignored unquoted "hash" or "pounds-
              sign" comments.

       m4 quotes to quote white-space or comments
              Since hxmd uses m4(1) to process attributes it uses  those  same
              quoting rules for attributes in the configuration files.

       C quotes to quote things m4 can't
              Like  the  word "can't" is hard to quote in m4, but easy under C
              double-quote rules.

       Arbitrary white-space as a separator
              This is taken from awk(1).  If you want  white-space  to  matter
              you  have  to quote it in m4 or C quotes.  You can't make white-
              space work in the key macro (see hxmd(8l), under -k).

       Strange to hxmd is the idea that the  value  dot  (.)   represents  the
       undefined value.  But not so strange if you used distrib(8l).

       Unique to hxmd is the idea of a variable header.  Each item in the con-
       figuration is specified with a definition line.  That line should  pro-
       vide a value for each macro listed in the most recent header.

       A  header  starts  with  a  percent  sign (%) 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 per-
       cent sign markup with a new list.

       For example below says that each "HOST" should specify an "OWNER":
              %HOST OWNER
       The list under that might look like:
              imp.npcguild.org    ksb
              foo.movie.com  'Paul A. Smith'
              bar.example.com     .
       That list tells us that "imp" is owned by me, "foo" by Paul, and  "bar"
       doesn't have an owner.

       The key-macro 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  (%) to accept the specified command-line value (usually under the
       application's -k option).

       An attribute macro name of dot (.) specifies that the associated column
       should  be  discarded.  Use this to delete columns generated by automa-
       tion (under -o) via the header, never parse the quoted values yourself.
       Rather apply a tool like sed to substitute the percent header line.

       An  attribute macro value of double-dot (..) specifies that the associ-
       ated macro should have the current in-scope value.
              OWNER='ksb'
              %HOST             OWNER
              imp.npcguild.org    ..
              nostromo.npcguild.org    ..
              sulaco.npcguild.org agt
              aisequo.npcguild.org     ..
       This allows an explicit way to compress a common value for  many  hosts
       into a much more compact form.

CONVENTION
       To  use  hxmd  as the basis for the master source system we install two
       configuration files on every host, and some extra site policy files:

       msrc.cf or msrc.zf
              This file defines the default values  for  the  attributes  msrc
              needs  to  know that might be host specific: the path to ssh(1),
              rdist(1), rdistd(8), and the like.  It is usually  updated  from
              the distribution one by site policy.

       auto.cf
              This  file  should  hold  the information about the local host's
              attributes.  The file is used in the "pull" version of the  mas-
              ter  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.

       empty
              An  empty  file  which  can  be  used by clever coders to get an
              anonymous temporary file from hxmd for data collection purposes.

       class.m4
              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 CLASS.

       cronsup.m4, gnumake.m4, sendfile.m4
              Other files with example markup.

EXAMPLES
       ENTRY_LOGIN="source"
              Set the attribute "ENTRY_LOGIN" to "source" until it is  defined
              as a header macro, or reset by another assignment.

       PERIOD='.'
              Set the attribute macro "PERIOD" to a literal dot.

       PERIOD="."
              Same as the last example, but use C quotes.

       %HOST SHORTHOST HOSTTYPE HOSTOS HASSRC
              Set the distrib default headers.

       %HOST
              Set the hxmd default headers.

       % %
              Set the header to just the current key macro, as specified under
              -k.

       lv426.npcguild.org
       sulaco.npcguild.org
              Define two hosts using the header line above.

       %SHORTHOST HOST
              Set the headers to move the SHORTHOST to the first word, the key
              specified  on  the  command  line  (under -k) could be either of
              these.

       nostromo nostromo.example.com
              Define a  host  named  "nostromo.example.com",  using  the  last
              header definition.

       %ENDPT DIALME TUNNEAR TUNFAR DESTNET KEYFILE
              This  is a real example of the openvpn(8) header line I actually
              use.

       ENTRY_LOGIN=.
              Unset the ENTRY_LOGIN attribute for all hosts defined below this
              line.

BUGS
       This  is not really a bug in the code, more a bug in the design: when a
       configuration file is read under -Z any in-scope definitions are set as
       default  values  for hosts in subsequent files, unless they are part of
       the header markup (%).  So this example file does not set a default for
       "WHAM":
              %HOST     WHAM BIFF
              sulaco    no   yes
              nostromo  yes  yes
              # comment on the fact the next line doesn't work
              WHAM='always'

       To  make this work as intended just replace the lines from comment line
       on, with this text:
              # Reset column headers to set a defaults for subsequent hosts.
              %%
              WHAM='always'
       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  (%)  to  name  the  key
       macro is always safe, even if the command-line changed that macro name.

AUTHOR
       KS Braunsdorf
       hxmd at-not-spam ksb dot npcguild.org


SEE ALSO
       m4(1),  cc(1),  hxmd(8l),  msrc(8l),   mmsrc(8l),   efmd(8l),   sed(1),
       distrib(8l)



                                     LOCAL                             HXMD(5)

NAME | SYNOPSIS | DESCRIPTION | CONVENTION | EXAMPLES | BUGS | AUTHOR | SEE ALSO