• Reference
• /
• Components
• /
• cf-execd

cf-execd

cf-execd is the scheduling daemon forcf-agent. It runscf-agent locally according to a schedule specified in policy code (executorcontrol body). After acf-agent run is completed,cf-execd gathers outputfromcf-agent, and may be configured to email the output to a specifiedaddress. It may also be configured tosplay (randomize)the execution schedule to prevent synchronizedcf-agent runs across anetwork.

cf-execd keeps the promises made incommon bundles, and is affected bycommon andexecutor control bodies.

Notes:

• This daemon reloads it's config when the SIGHUP signal is received.
• cf-execd always considers the classexecutor to be defined.

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 cf-execd  --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  --ignore-preferred-augments           - Ignore def_preferred.json file in favor of def.json  --skip-db-check value - Do not run database integrity checks and repairs at startup  --with-runagent-socket value - Specify the directory for the socket for runagent requests or 'no' to disable the socket

Control promises

These body settings determine the behavior ofcf-execd,including schedulingtimes and output capture toWORKDIR/outputs and relay via email.

bodyexecutorcontrol{splaytime=>"5";mailto=>"cfengine@example.org";mailfrom=>"cfengine@$(host).example.org";smtpserver=>"localhost";schedule=>{"Min00","Min30"}}

agent_expireafter

Description: Maximum agent runtime (in minutes)

Sets a maximum time on any run of the command inexec_command. Ifno data is received from the pipe opened to the process createdwithexec_command after the time has elapsed, the process getskilled.

Note that if you have long-running jobs, they may get killed withthis setting. Therefore, you should ensure it is higher than anyrun ofcf-agent that you want to leave alone. Alternatively, youcan make your jobs output something to STDOUT at least as often asthis threshold. This will reset the timer.

Type:int

Allowed input range:0,10080

Default value: 120

Example:

bodyexecutorcontrol{agent_expireafter=>"120";}

Notes:The setting will effectively allow you to set a threshold on thenumber of simultaneous agents that are running. For example, if youset it to120 and you are using a 5-minute agent schedule, amaximum 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_USERLOG_DAEMONLOG_LOCAL0LOG_LOCAL1LOG_LOCAL2LOG_LOCAL3LOG_LOCAL4LOG_LOCAL5LOG_LOCAL6LOG_LOCAL7

See the syslog manual pages.

Default value:LOG_USER

Example:

bodyexecutorcontrol{executorfacility=>"LOG_USER";}

exec_command

Description: The full path and command to the executable run bydefault (overridingbuiltin)

The command is run in a shell encapsulation so pipes and shellsymbols may be used if desired.

Type:string

Allowed input range:"?(/.*)

Note: Ifexec_command is not definedcf-agent will be executed with thefailsafe.cf policy.

Example:

exec_command => "$(sys.workdir)/bin/cf-agent -f update.cf && $(sys.workdir)/bin/cf-agent";

mailfilter_exclude

Description: List ofanchored regular expressions that, ifmatched by a log entry, will cause that log entry to be excluded from agentexecution emails.

If no filter is set,cf-execd acts as if no log entry matches the excludepattern. If a log entry also matches a pattern inmailfilter_include, theexclude pattern takes precedence.

Type:slist

Allowed input range:.*

Note: Merely adding or removing a pattern that causes the number of matchinglog entries to change, does not guarantee that the next agent execution willgenerate an email from cf-execd. The actual output from cf-agent still has to bedifferent from the previous run for an email to be generated.

Example:

bodyexecutorcontrol{# Ignore agent execution emails about permission errors.mailfilter_exclude=>{".*Permission denied.*"};}

History: Introduced in CFEngine 3.9.

mailfilter_include

Description: List ofanchored regular expressions that mustmatch 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 includepattern. If a log entry also matches a pattern inmailfilter_exclude, theexclude pattern takes precedence.

Type:slist

Allowed input range:.*

Note: Merely adding or removing a pattern that causes the number of matchinglog entries to change, does not guarantee that the next agent execution willgenerate an email from cf-execd. The actual output from cf-agent still has to bedifferent from the previous run for an email to be generated.

Example:

bodyexecutorcontrol{# 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:

bodyexecutorcontrol{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 systemadministrator's mailbox. The output is truncated in the email report, but thecomplete original transcript is stored inWORKDIR/outputs/* where it can beviewed on demand. A reference to the appropriate file is given.

Type:int

Allowed input range:0,1000

Default value: 30

Example:

bodyexecutorcontrol{mailmaxlines=>"100";}

mailsubject

Description: The subject in the mail sent by CFEngine.

The subject can contain system variables, like for example IP address orarchitecture.

Type:string

Allowed input range:.*

Example:

bodyexecutorcontrol{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:

bodyexecutorcontrol{mailto=>"cfengine_alias@example.org";}

schedule

Description: The class schedule used by cf-execd for activatingcf-agent

The list should contain class expressions comprised of classeswhich are visible to thecf-execd daemon. In principle, anydefined class expression will cause the daemon to wake up andschedule the execution of thecf-agent. In practice, the classeslisted in the list are usually date- and time-based.

The actual execution ofcf-agent may be delayed bysplaytime,and may be deferred by promise caching and the value ofifelapsed. Note also that the effectiveness of thesplayclassfunction may be affected by changing theschedule.

Type:slist

Allowed input range: (arbitrary string)

Default value:

schedule => { "Min00", "Min05", "Min10", "Min15", "Min20", "Min25",          "Min30", "Min35", "Min40", "Min45", "Min50", "Min55" };

Example:

bodyexecutorcontrol{schedule=>{"Min00","(Evening|Night).Min15","Min30","(Evening|Night).Min45"};}

smtpserver

Description: Name or IP of a willing smtp server for sendingemail

This should point to a standard port 25 server without encryption. If you arerunning secured or encrypted email then you should run a mail relay onlocalhost and point this to localhost.

Type:string

Allowed input range:.*

Example:

bodyexecutorcontrol{smtpserver=>"smtp.example.org";}

splaytime

Description: Time in minutes to splay this host based on its namehash

Whenever any class listed in theschedule attribute is present,cf-execd can schedule an execution ofcf-agent. The actualexecution will be delayed an integer number of seconds between0-splaytime minutes. The specific amount of delay for "this" hostis based on a hash of the hostname. Thus a collection of hosts willall execute at different times, and surges in network traffic canbe avoided.

A general rule for scaling of small updates is to set the splay time toruninterval-1 minutes for up a few thousand hosts. For example, the defaultschedule executes once every 5 minutes, so the splay time should be set to nomore than 4 minutes. Thesplaytime should be set to a value less than thecf-execd scheduling interval, else multiple clients might contend for data.In other words,splaytime +cf-agent run time should be less than thescheduling interval.

Type:int

Allowed input range:0,99999999999

Default value: 0

The CFEngine default policy setssplaytime to 1.

Example:

bodyexecutorcontrol{splaytime=>"2";}

See also: Thesplayclass() function for a task-specificmeans for setting splay times.

runagent_socket_allow_users

Description: Users who are allowed access the socket (STATEDIR/cf-execd.sockets/runagent.socket).

Type:slist

Allowed input range:.*

Default value: none

Notes:

• By default, in the Masterfiles Policy Framework,cfapache is allowed to access the socket on Enterprise Hubs.

Example:

bodyexecutorcontrol{runagent_socket_allow_users=>{"yoda","obi-wan"};}

See also:cf-runagent

History:

• 3.18.0 Addedrunagent_socket_allow_users attribute

Sockets

cf-execd createsSTATEDIR/cf-execd.sockets/runagent.socket (/var/cfengine/state/cf-execd.sockets/runagent.socket).

Thebody executor control attributerunagent_socket_allow_users controls the list of users that should be allowed to access (**RW**) the socket via ACLs.

Notes:

• Unlike execution triggered with thecf-runagent binary, there is currently no capability to define additional options like defining additional classes, or the remote bundlesequence.

Example:

Write the name or IP into the socket to request unscheduled execution on that host:

echo 'host001' > /var/cfengine/state/cf-execd.sockets/cf-runagent.socket

See also:cf-runagent,runagent_socket_allow_users

History:

• 3.18.0 Added socket for triggeringcf-runagent by hostname or IP.

Still need help?

Chat

Ask a question on Github

Mailing list