Prototype: peers(filename, regex, groupsize)

Return type: slist

Description: Returns the current host's partition peers (excluding it).

So given groupsize 3 and the file

code
a
b
c
# this is a comment d
e

The peers of host b will be a and c.

Given a list of host names in filename, one per line, and excluding comment lines starting with the unanchored regular expression regex, CFEngine partitions the host list into groups of up to groupsize. Each group's peer leader is the first host in the group.

The comment field is a multiline regular expression and will strip out unwanted patterns from the file being read, leaving unstripped characters to be split into fields. Using the empty string ("") indicates no comments.

The current host (unqualified or fully qualified) should belong to this file if it is expected to interact with the others. The function returns an empty list otherwise.

Arguments:

  • filename: string - File name of host list - in the range: "?(/.*)
  • regex: regular expression - Comment regex pattern - in the range: .*
  • groupsize: int - Peer group size - in the range: 2,64

groupsize must be between 2 and 64 to avoid nonsensical promises.

Example:

Prepare:

code
echo alpha > /tmp/cfe_hostlist
echo beta >> /tmp/cfe_hostlist
echo gamma >> /tmp/cfe_hostlist
echo "Set HOSTNAME appropriately beforehand"
echo "$(hostname -f)" | tr 'A-Z' 'a-z' >> /tmp/cfe_hostlist
echo "Delta Delta Delta may I help ya help ya help ya"
echo delta1 >> /tmp/cfe_hostlist
echo delta2 >> /tmp/cfe_hostlist
echo delta3 >> /tmp/cfe_hostlist
echo may1.I.help.ya >> /tmp/cfe_hostlist
echo may2.I.help.ya >> /tmp/cfe_hostlist
echo may3.I.help.ya >> /tmp/cfe_hostlist

Run:

code
body common control
{
      bundlesequence => { "peers" };
}

bundle agent peers
{
  vars:

      "mygroup" slist => peers("/tmp/cfe_hostlist","#.*",4);

      "myleader" string => peerleader("/tmp/cfe_hostlist","#.*",4);

      "all_leaders" slist => peerleaders("/tmp/cfe_hostlist","#.*",4);

  reports:

      # note that the current host name is fourth in the host list, so
      # its peer group is the first 4-host group, minus the host itself.
      "/tmp/cfe_hostlist mypeer $(mygroup)";
      # note that the current host name is fourth in the host list, so
      # the peer leader is "alpha"
      "/tmp/cfe_hostlist myleader $(myleader)";
      "/tmp/cfe_hostlist another leader $(all_leaders)";
      "Unable to find my fully qualified hostname $(sys.fqhost) in /tmp/cfe_hostlist. Can't determine peers."
        if => not( regline( $(sys.fqhost), "/tmp/cfe_hostlist" ) );
}

Output:

code
R: /tmp/cfe_hostlist mypeer alpha
R: /tmp/cfe_hostlist mypeer beta
R: /tmp/cfe_hostlist mypeer gamma
R: /tmp/cfe_hostlist myleader alpha
R: /tmp/cfe_hostlist another leader alpha
R: /tmp/cfe_hostlist another leader delta1
R: /tmp/cfe_hostlist another leader may2.I.help.ya