cf-execd
cf-execd
is the scheduling daemon for cf-agent
. It runs
cf-agent
locally according to a schedule specified in policy code (executor
control body). After a cf-agent
run is completed, cf-execd
gathers output
from cf-agent
, and may be configured to email the output to a specified
address. It may also be configured to splay (randomize)
the execution schedule to prevent synchronized cf-agent
runs across a
network.
cf-execd
keeps the promises made in common
bundles, and is affected by
common
and executor
control bodies.
Note: This daemon reloads it's config when the SIGHUP signal is received.
History:
- SIGHUP behavior added in 3.7.0
Command reference
--help , -h - Print the help message
--debug , -d - Enable debugging output
--verbose , -v - Output verbose information about the behaviour of the agent
--dry-run , -n - All talk and no action mode - make no changes, only inform of promises not kept
--version , -V - Output the version of the software
--file , -f value - Specify an alternative input file than the default. This option is overridden by FILE if supplied as argument.
--define , -D value - Define a list of comma separated classes to be defined at the start of execution
--negate , -N value - Define a list of comma separated classes to be undefined at the start of execution
--no-lock , -K - Ignore locking constraints during execution (ifelapsed/expireafter) if "too soon" to run
--inform , -I - Print basic information about changes made to the system, i.e. promises repaired
--diagnostic , -x - Activate internal diagnostics (developers only)
--log-level , -g value - Specify how detailed logs should be. Possible values: 'error', 'warning', 'notice', 'info', 'verbose', 'debug'
--no-fork , -F - Run as a foreground processes (do not fork)
--once , -O - Run once and then exit (implies no-fork)
--no-winsrv , -W - Do not run as a service on windows - use this when running from a command shell (CFEngine Nova only)
--ld-library-path, -L value - Set the internal value of LD_LIBRARY_PATH for child processes
--color , -C value - Enable colorized output. Possible values: 'always', 'auto', 'never'. If option is used, the default value is 'auto'
--timestamp , -l - Log timestamps on each line of log output
--skip-db-check, - value - Do not run database integrity checks and repairs at startup
Control Promises
These body settings determine the behavior of cf-execd
,including scheduling
times and output capture to WORKDIR/outputs
and relay via email.
body executor control
{
splaytime => "5";
mailto => "cfengine@example.org";
mailfrom => "cfengine@$(host).example.org";
smtpserver => "localhost";
schedule => { "Min00_05", "Min30_35" }
}
agent_expireafter
Description: Maximum agent runtime (in minutes)
Sets a maximum time on any run of the command in exec_command
. If
no data is received from the pipe opened to the process created
with exec_command
after the time has elapsed, the process gets
killed.
Note that if you have long-running jobs, they may get killed with
this setting. Therefore, you should ensure it is higher than any
run of cf-agent
that you want to leave alone. Alternatively, you
can make your jobs output something to STDOUT at least as often as
this threshold. This will reset the timer.
Type: int
Allowed input range: 0,10080
Default value: 120
Example:
body executor control
{
agent_expireafter => "120";
}
Notes:
The setting will effectively allow you to set a threshold on the
number of simultaneous agents that are running. For example, if you
set it to 120
and you are using a 5-minute agent schedule, a
maximum of 120 / 5 = 24 agents should be enforced.
See Also: body action expireafter
, body contain exec_timeout
, body agent control expireafter
executorfacility
Description: Menu option for syslog facility level
Type: (menu option)
Allowed input range:
LOG_USER
LOG_DAEMON
LOG_LOCAL0
LOG_LOCAL1
LOG_LOCAL2
LOG_LOCAL3
LOG_LOCAL4
LOG_LOCAL5
LOG_LOCAL6
LOG_LOCAL7
See the syslog manual pages.
Default value: LOG_USER
Example:
body executor control
{
executorfacility => "LOG_USER";
}
exec_command
Description: The full path and command to the executable run by
default (overriding builtin
)
The command is run in a shell encapsulation so pipes and shell symbols may be used if desired.
Type: string
Allowed input range: "?(/.*)
Note: If exec_command
is not defined cf-agent
will be executed with the failsafe.cf
policy.
Example:
exec_command => "$(sys.workdir)/bin/cf-agent -f update.cf && $(sys.workdir)/bin/cf-agent";
mailfilter_exclude
Description: List of anchored regular expressions that, if matched by a log entry, will cause that log entry to be excluded from agent execution emails.
If no filter is set, cf-execd
acts as if no log entry matches the exclude
pattern. If a log entry also matches a pattern in mailfilter_include
, the
exclude pattern takes precedence.
Type: slist
Allowed input range: .*
Note: Merely adding or removing a pattern that causes the number of matching log entries to change, does not guarantee that the next agent execution will generate an email from cf-execd. The actual output from cf-agent still has to be different from the previous run for an email to be generated.
Example:
body executor control
{
# Ignore agent execution emails about permission errors.
mailfilter_exclude => { ".*Permission denied.*" };
}
History: Introduced in CFEngine 3.9.
mailfilter_include
Description: List of anchored regular expressions that must match a log entry in order for it to be included in agent execution emails.
If no filter is set, cf-execd
acts as if every log entry matches the include
pattern. If a log entry also matches a pattern in mailfilter_exclude
, the
exclude pattern takes precedence.
Type: slist
Allowed input range: .*
Note: Merely adding or removing a pattern that causes the number of matching log entries to change, does not guarantee that the next agent execution will generate an email from cf-execd. The actual output from cf-agent still has to be different from the previous run for an email to be generated.
Example:
body executor control
{
# Only include reports in agent execution emails.
mailfilter_include => { "R:.*" };
}
History: Introduced in CFEngine 3.9.
mailfrom
Description: Email-address cfengine mail appears to come from
Type: string
Allowed input range: .*@.*
Example:
body executor control
{
mailfrom => "mrcfengine@example.org";
}
mailmaxlines
Description: Maximum number of lines of output to send by email
This limit prevents anomalously large outputs from clogging up a system
administrator's mailbox. The output is truncated in the email report, but the
complete original transcript is stored in WORKDIR/outputs/*
where it can be
viewed on demand. A reference to the appropriate file is given.
Type: int
Allowed input range: 0,1000
Default value: 30
Example:
body executor control
{
mailmaxlines => "100";
}
mailsubject
Description: The subject in the mail sent by CFEngine.
The subject can contain system variables, like for example IP address or architecture.
Type: string
Allowed input range: .*
Example:
body executor control
{
mailsubject => "CFEngine report ($(sys.fqhost))";
}
mailto
Description: Email-address cfengine mail is sent to
The address to whom email is sent if an smtp host is configured.
Type: string
Allowed input range: .*@.*
Example:
body executor control
{
mailto => "cfengine_alias@example.org";
}
schedule
Description: The class schedule used by cf-execd for activating cf-agent
The list should contain class expressions comprised of classes
which are visible to the cf-execd
daemon. In principle, any
defined class expression will cause the daemon to wake up and
schedule the execution of the cf-agent
. In practice, the classes
listed in the list are usually date- and time-based.
The actual execution of cf-agent
may be delayed by splaytime
,
and may be deferred by promise caching and the value of
ifelapsed
. Note also that the effectiveness of the splayclass
function may be affected by changing the schedule
.
Type: slist
Allowed input range: (arbitrary string)
Default value:
schedule => { "Min00", "Min05", "Min10", "Min15", "Min20", "Min25",
"Min30", "Min35", "Min40", "Min45", "Min50", "Min55" };
Example:
body executor control
{
schedule => { "Min00", "(Evening|Night).Min15_20", "Min30", "(Evening|Night).Min45_50" };
}
smtpserver
Description: Name or IP of a willing smtp server for sending email
This should point to a standard port 25 server without encryption. If you are running secured or encrypted email then you should run a mail relay on localhost and point this to localhost.
Type: string
Allowed input range: .*
Example:
body executor control
{
smtpserver => "smtp.example.org";
}
splaytime
Description: Time in minutes to splay this host based on its name hash
Whenever any class listed in the schedule
attribute is present,
cf-execd
can schedule an execution of cf-agent
. The actual
execution will be delayed an integer number of seconds between
0-splaytime
minutes. The specific amount of delay for "this" host
is based on a hash of the hostname. Thus a collection of hosts will
all execute at different times, and surges in network traffic can
be avoided.
A general rule for scaling of small updates is to set the splay time to
runinterval-1 minutes for up a few thousand hosts. For example, the default
schedule executes once every 5 minutes, so the splay time should be set to no
more than 4 minutes. The splaytime
should be set to a value less than the
cf-execd
scheduling interval, else multiple clients might contend for data.
In other words, splaytime
+ cf-agent
run time should be less than the
scheduling interval.
Type: int
Allowed input range: 0,99999999999
Default value: 0
The CFEngine default policy sets splaytime
to 1.
Example:
body executor control
{
splaytime => "2";
}
See also: The splayclass()
function for a task-specific
means for setting splay times.