Clockwork

cw-mesh(1)

NAME

cw-mesh - Clockwork Mesh Client

SYNOPSIS

cw-mesh [OPTIONS] command [arg...]

DESCRIPTION

Clockwork is a system configuration management system designed to securely enforce policies on one or more host systems. It can ensure that files have the prescribed attributes (owner, group, permissions, etc.) and content. It can maintain a specific set of installed packages, and even make sure that system user accounts exist.

cw-mesh is the client utility for Clockwork Mesh. With it you can interact with remote Clockwork nodes, query them for resource state (what version of Clockwork are you running? Is package X installd?) start services, execute commands, etc.

You can read more about Mesh in the mesh(7) man page.

There are several alias commands to make using mesh more natural.

$ cw show [OPTIONS] version

is identical to

$ cw mesh [OPTIONS] show version

The former makes it more natural to speak mesh, especially if there are no options to be had.

OPTIONS

-t, --timeout seconds

How long to wait for responses from mesh nodes, in seconds. cw-mesh will always wait this long, since there is no reliable way to determine how many nodes will respond to the query.

Defaults to 40 seconds. Values of 0 or less will be treated as this default.

This option can be set in the global /etc/clockwork/cw.conf and overridden in ~/.cwrc, via the mesh.timeout directive. The command-line flag will override both of those values.

-s, --sleep milliseconds

How many milliseconds to sleep between checking for results.

Defaults to 250 milliseconds. The minimum value is 100 milliseconds.

This option can be set in the global /etc/clockwork/cw.conf and overridden in ~/.cwrc, via the mesh.sleep directive. The command-line flag will override both of those values.

-w, --where FILTER

The given command should only be run on nodes matching FILTER. Filters are specified as 'key op value'. Regex matching is supported.

Here are the valid forms for a filter:

fact.name =  literal   # match the value "literal"
fact.name != literal   # match any other value

fact.name =  /^web/    # match any value starting with "web"
fact.name != /^web/    # match any value not starting with "web"

Note that '=' and '!=' are used for both literal matches and regex matches; the magic is in the forward slashes that surround the regex pattern.

fact.name = "^web"     # match the literal value "^web"

Multiple filters can be givne by adding the -w flag multiple times. All filters are ANDed together (they all have to match).

-v, --verbose
-q, --quiet

How much should cw-mesh print out. This is primarily for diagnostics.

-n, --noop

Parse options and the command, to ensure they are all valid, but don't authenticate or submit the query.

-u, --username USERNAME

User to authenticate as. If cw-mesh can't figure out who the current user is, and this option is not specified, it will prompt for the username.

-k, --key /path/to/mesh.key

Use the specified user private key and do key-based authentication. No passwords will be prompted for, and password authentication will be skipped.

Defaults to ~/clockwork/mesh.key.

If the special value "0" is given (as in -k0), then public key authentication will be skipped, and you will be prompted for a password.

--cert /path/to/cert.pub

Path to the public certificate for validating the Mesh master server.

There is no default for this option, but it can (and should) be set by the global /etc/clockwork/cw.conf or ~/.cwrc via the mesh.cert directive.

-c, --config /path/to/cw.conf

Specify an alternate cw configuration file. If not given, cw-mesh will check the normal places, starting with the global /etc/clockwork/cw.conf file, followed by overrides in ~/.cwrc. If you do specify a config file, the normal files (including ~/.cwrc) will be summarily skipped.

--optouts

By default, cw-mesh will ignore all OPTOUT replies from nodes that received the command, but opted out due to filtering and applicability. For debugging and troubleshooting, it can be helpful to see these replies, to verify that a missing host is in fact not responding at all, rather than mistakenly (or unexpectedly) opting out.

-Y, --yaml

Output results in YAML format. See OUTPUT FORMATS for examples.

-J, --json

Output results in JSON format. See OUTPUT FORMATS for examples.

-X, --xml

Output results in XML format. See OUTPUT FORMATS for examples.

-T, --text

Output results in a simple, machine-readable text format. This format is intended to be easily parsed by simple shell scripts.

See OUTPUT FORMATS for examples.

-P, --pretty

Output results in a pretty, human-readable format. This is the default.

See OUTPUT FORMATS for examples.

OUTPUT FORMATS

YAML

---
fe8565d6-2c2b-43e6-9c84-58a57f7d33ee:
  fqdn: host1.example.com
  status: 0
  output: |-
    command output
aef5002e-9238-43fe-b280-3e197136bb53:
  fqdn: host2.example.com
  status: 3
  output: |-
    more output
    on multiple lines
d79835c2-7e0f-41c4-adb7-f87596229542:
  fqdn: optout.example.com
  status: ~
  output: ~

JSON (--json)

{
  "fe8565d6-2c2b-43e6-9c84-58a57f7d33ee": {
    "fqdn"   : "host1.example.com",
    "status" : 0,
    "output" : "command output\n"
  },
  "aef5002e-9238-43fe-b280-3e197136bb53": {
    "fqdn"   : "host2.example.com",
    "status" : 3,
    "output" : "more output\non multiple lines\n"
  },
  "d79835c2-7e0f-41c4-adb7-f87596229542": {
    "fqdn"   : "optout.example.com",
    "status" : null,
    "output" : null
  },
}

XML (--xml)

<?xml version="1.0" encoding="UTF-8"?>
<results>
  <result uuid="fe8565d6-2c2b-43e6-9c84-58a57f7d33ee">
    <fqdn>host1.example.com</fqdn>
    <status>0</status>
    <output><![CDATA[command output
</output>
  </result>
  <result uuid="aef5002e-9238-43fe-b280-3e197136bb53">
    <fqdn>host2.example.com</fqdn>
    <status>3</status>
    <output><![CDATA[more output
on multiple lines
]]></output>
  </result>
  <result uuid="d79835c2-7e0f-41c4-adb7-f87596229542">
    <fqdn>optout.example.com</fqdn>
    <optout/>
  </result>
</results>

Machine-parseable Text (--text)

fe8565d6-2c2b-43e6-9c84-58a57f7d33ee host1.example.com success 0
 command output
aef5002e-9238-43fe-b280-3e197136bb53 host2.example.com failed 3
 more output
 on multiple lines
d79835c2-7e0f-41c4-adb7-f87596229542 optout.example.com optout

Human-readable Text (--pretty)

host1.example.com succeeded
UUID fe8565d6-2c2b-43e6-9c84-58a57f7d33ee
------------------------------------------------------------
  command output


host2.example.com failed (rc=3)
UUID aef5002e-9238-43fe-b280-3e197136bb53
------------------------------------------------------------
 more output
 on multiple lines


optout.example.com opted out
UUID d79835c2-7e0f-41c4-adb7-f87596229542

AUTHOR

Clockwork was designed and written by James Hunt.

The Clockwork website is licensed under the Creative Commons Attribution-NoDerivs 3.0 United States License