cogd.conf - Clockwork Agent configuration file




cogd(1) reads its configuration from /etc/clockwork/cogd.conf (unless a different file is specified with the -c option).

Valid configuration directives, and their meanings, are as follows:

master.N - Master Servers

Master Servers are the fixed points in the Clockwork architecture. They maintain the global manifest and are solely responsible for handing out policy to managed hosts.

Each master server must be specified by its endpoint IP address and TCP port number. The standard Clockwork port for master servers is TCP/2314.

A single cogd can be configured with up to 8 master servers, master.1, master.2 ... master.8. It will round-robin between these master servers until it finds one it can connect to. This can be leveraged to provide more resiliency into core of your configuration management layer.

At least one master server (master.1) must be specified, or

cogd will exit with an error.

cert.N - Master Server Certificates

Each master server must be authenticated by providing the cogd clients with their public certificate (which contains only the public key).

mesh.control - Mesh Control Channel
mesh.broadcast - Mesh Broadcast Channel

Each cogd can register with a Clockwork Mesh server, to which it will subscribe for inbound orchestration and remote queries. There are two channels that must be set up for this to work.

The broadcast channel is what cogd listens to for inbound commands that are sent to all nodes simultaneously. It usually runs on port 2316.

The control channel is where cogd sends the results of any commands or queries it has executed, so that they can be related back to the original requester. This is usually port 2315.

security.cert - Client Certificate

Since all communication between cogd and clockd is encrypted, the client must have a public/private keypair, which is contained inside of its combined certificate.

timeout - Timeout for Master Server communication

When communicating with master server(s), there is a chance that the remote peer is not up or accepting connections. Due to the asynchronous nature of the Clockwork protocol, cogd must enforce timeouts on replies from each master that it talks to.

This configuration directive specifies that timeout, in seconds.

Defaults to 5.

interval - How often to run configuration management

Defaults to 300 (5 minutes).

gatherers - Path or shell glob to gatherer script(s)

Gatherers allow this host to collect as much information about itself as possible, and communicate that to the policy master. This data includes stuff like kernel version, number of interfaces, distribution name, etc., and allows the policy master to tailor a policy specific to this host.

To specify more than one script (the most common case), use a shell glob. For example, if you keep multiple gatherers in /opt/clockwork, set gatherers to "/opt/clockwork/*".

Only files with the executable bit set will be seen as valid gatherer scripts.

Defaults to /etc/clockwork/gather.d/*.

copydown - Root directory for copydown

When cogd starts up, the first thing it does after contacting a master server is perform a COPYDOWN. During the step, static files (usually gatherer scripts) will be copied down from the master to the local node. This ensures that the policy generated is correct, and that local fact gatherers are not tampered with.

This setting lets you choose where the copydown files are stored.

Defaults to /etc/clockwork/gather.d.

pidfile - PID file for storing the daemon process ID

Defaults to /var/run/cogd.conf.

lockdir - Where to store coordination locks

Certain actions that cogd performs should only be executed by a single process at any given point in time. To help coordinate this, and still enable one-off runs, cogd creates lock files that serve as advisory locks to other cogd processes.

This setting lets you relocate the directory where these lock files are created. Note that anyone wishing to run cogd must be allowed to write to this directory.

Defaults to /var/lock/cogd.

difftool - What tool to use for logging file change diffs

This command will be run, and its output logged to NOTICE, whenever cogd changes a local file from a remote source. It should print out the key differences between the two versions, to assist system owners in troubleshooting proper policy enforcement.

Whatever program you specify must be able to take two arguments, the first being the path to the original, local file, and the second being the literal string "-". It must also be able to read the new file from standard input.

This models the standard diff utility, which is what most people will probably use. You can specify command-line options to the tool if so desired.

Defaults to /usr/bin/diff -u.

syslog.ident - Syslog identity string

Defaults to cogd.

syslog.facility - Syslog facility for logging

Defaults to daemon.

syslog.level - Log level

Defaults to error.


This is the default configuration, plus a single master server at

security.cert  /etc/clockwork/certs/cogd

timeout    5
interval   300
gatherers  /etc/clockwork/gather.d/*
copydown   /etc/clockwork/gather.d

lockdir          /var/lock/cogd
pidfile          /var/run/

syslog.ident     cogd
syslog.facility  daemon
syslog.level     error

difftool  /usr/bin/diff -u

Here's a bare-bones configuration that can talk to three different master servers, in three different 10/8 subnets (certificates have been omitted for brevity):

master.1  # Chicago, IL
master.2  # New York, NY
master.3  # San Jose, CA
timeout 15


clockwork(7), clockd(1), clockd.conf(5) and cogd.conf(5)


Clockwork was designed and written by James Hunt.

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