lib/common.cf

Suggest changes

Table of contents

Seethecommon promise attributesdocumentation for a comprehensive reference on the body types and attributesused here.

action bodies

if_elapsed

Prototype:if_elapsed(x)

Description: Evaluate the promise everyx minutes

Arguments:

x: The time in minutes between promise evaluations

Implementation:

code

bodyactionif_elapsed(x){ifelapsed=>"$(x)";expireafter=>"$(x)";}

if_elapsed_day

Prototype:if_elapsed_day

Description: Evalute the promise once every 24 hours

Implementation:

code

bodyactionif_elapsed_day{ifelapsed=>"1440";# 60 x 24expireafter=>"1400";}

measure_performance

Prototype:measure_performance(x)

Description: Measure repairs of the promiser everyx minutes

Repair-attempts are cancelled afterx minutes.

Arguments:

x: The time in minutes between promise evaluations.

Implementation:

code

bodyactionmeasure_performance(x){measurement_class=>"Detect changes in$(this.promiser)";ifelapsed=>"$(x)";expireafter=>"$(x)";}

measure_promise_time

Prototype:measure_promise_time(identifier)

Description: Performance will be measured and recorded under identifier

Arguments:

identifier: Measurement name.

Implementation:

code

bodyactionmeasure_promise_time(identifier){measurement_class=>"$(identifier)";}

warn_only

Prototype:warn_only

Description: Warn once an hour if the promise needs to be repaired

The promise does not get repaired.

Implementation:

code

bodyactionwarn_only{action_policy=>"warn";ifelapsed=>"60";}

bg

Prototype:bg(elapsed, expire)

Description: Evaluate the promise in the background everyelapsed minutes, for at mostexpire minutes

Arguments:

elapsed: The time in minutes between promise evaluations
expire: The time in minutes after which a repair-attempt gets cancelled

Implementation:

code

bodyactionbg(elapsed,expire){ifelapsed=>"$(elapsed)";expireafter=>"$(expire)";background=>"true";}

ifwin_bg

Prototype:ifwin_bg

Description: Evaluate the promise in the background when running on Windows

Implementation:

code

bodyactionifwin_bg{windows::background=>"true";}

immediate

Prototype:immediate

Description: Evaluate the promise at everycf-agent execution.

Implementation:

code

bodyactionimmediate{ifelapsed=>"0";}

policy

Prototype:policy(p)

Description: Set theaction_policy top

Arguments:

p: The action policy

Implementation:

code

bodyactionpolicy(p){action_policy=>"$(p)";}

log_repaired

Prototype:log_repaired(log, message)

Description: Logmessage to a filelog=[/file|stdout]

Arguments:

log: The log file for repaired messages
message: The log message

Implementation:

code

bodyactionlog_repaired(log,message){log_string=>"$(sys.date),$(message)";log_repaired=>"$(log)";}

log_verbose

Prototype:log_verbose

Description: Sets thelog_level attribute to "verbose"

Implementation:

code

bodyactionlog_verbose{log_level=>"verbose";}

sample_rate

Prototype:sample_rate(x)

Description: Evaluate the promise everyx minutes,A repair-attempt is cancelled after 10 minutes

Arguments:

x: The time in minutes between promise evaluation

Implementation:

code

bodyactionsample_rate(x){ifelapsed=>"$(x)";expireafter=>"10";}

classes bodies

if_repaired

Prototype:if_repaired(x)

Description: Define classx if the promise has been repaired

Arguments:

x: The name of the class

Implementation:

code

bodyclassesif_repaired(x){promise_repaired=>{"$(x)"};}

if_else

Prototype:if_else(yes, no)

Description: Define the classesyes orno depending on promise outcome

Arguments:

yes: The name of the class that should be defined if the promise is kept or repaired
no: The name of the class that should be defined if the promise could not be repaired

Implementation:

code

bodyclassesif_else(yes,no){promise_kept=>{"$(yes)"};promise_repaired=>{"$(yes)"};repair_failed=>{"$(no)"};repair_denied=>{"$(no)"};repair_timeout=>{"$(no)"};}

cf2_if_else

Prototype:cf2_if_else(yes, no)

Description: Define the classesyes orno, depending on promise outcome

A version ofif_else that matches CFEngine2 semantics. Neither class is set if the promisedoes not require any repair.

Arguments:

yes: The name of the class that should be defined if the promise is repaired
no: The name of the class that should be defined if the promise could not be repaired

Implementation:

code

bodyclassescf2_if_else(yes,no){promise_repaired=>{"$(yes)"};repair_failed=>{"$(no)"};repair_denied=>{"$(no)"};repair_timeout=>{"$(no)"};}

if_notkept

Prototype:if_notkept(x)

Description: Define the classx if the promise is not kept and cannot be repaired.

Arguments:

x: The name of the class that should be defined

Implementation:

code

bodyclassesif_notkept(x){repair_failed=>{"$(x)"};repair_denied=>{"$(x)"};repair_timeout=>{"$(x)"};}

if_ok

Prototype:if_ok(x)

Description: Define the classx if the promise is kept or repaired

Arguments:

x: The name of the class that should be defined

Implementation:

code

bodyclassesif_ok(x){promise_repaired=>{"$(x)"};promise_kept=>{"$(x)"};}

if_ok_cancel

Prototype:if_ok_cancel(x)

Description: Cancel the classx if the promise is kept or repaired

Arguments:

x: The name of the class that should be cancelled

Implementation:

code

bodyclassesif_ok_cancel(x){cancel_repaired=>{"$(x)"};cancel_kept=>{"$(x)"};}

cmd_repair

Prototype:cmd_repair(code, cl)

Description: Define the classcl if an external command in acommands,file orpackagespromise is executed with return codecode

Arguments:

code: The return codes that indicate a successful repair
cl: The name of the class that should be defined

See also:repaired_returncodes

Implementation:

code

bodyclassescmd_repair(code,cl){repaired_returncodes=>{"$(code)"};promise_repaired=>{"$(cl)"};}

classes_generic

Prototype:classes_generic(x)

Description: Definex prefixed/suffixed with promise outcome

Arguments:

x: The unique part of the classes to be defined

Implementation:

code

bodyclassesclasses_generic(x){promise_repaired=>{"promise_repaired_$(x)","$(x)_repaired","$(x)_ok","$(x)_reached"};repair_failed=>{"repair_failed_$(x)","$(x)_failed","$(x)_not_ok","$(x)_error","$(x)_not_kept","$(x)_reached"};repair_denied=>{"repair_denied_$(x)","$(x)_denied","$(x)_not_ok","$(x)_error","$(x)_not_kept","$(x)_reached"};repair_timeout=>{"repair_timeout_$(x)","$(x)_timeout","$(x)_not_ok","$(x)_error","$(x)_not_kept","$(x)_reached"};promise_kept=>{"promise_kept_$(x)","$(x)_kept","$(x)_ok","$(x)_reached"};}

results

Prototype:results(scope, class_prefix)

Description: Define classes prefixed withclass_prefix and suffixed withappropriate outcomes: _kept, _repaired, _not_kept, _error, _failed,_denied, _timeout, _reached

Arguments:

scope: The scope in which the class should be defined (bundle ornamespace)
class_prefix: The prefix for the classes defined

This body can be applied to any promise and sets global(namespace) or local (bundle) classes based on its outcome. Forinstance, withclass_prefix set toabc:

if the promise is to change a file's owner tonick and the filewas already owned bynick, the classesabc_reached andabc_kept will be set.
if the promise is to change a file's owner tonick and the filewas owned byadam and the change succeeded, the classesabc_reached andabc_repaired will be set.

This body is a simpler, more consistent version of the bodyscoped_classes_generic, which see. The key difference is thatfewer classes are defined, and only for outcomes that we can know.For example this body does not define "OK/not OK" outcome classes,since a promise can be both kept and failed at the same time.

It's important to understand that promises may do multiple things,so a promise is not simply "OK" or "not OK." The best way tounderstand what will happen when your specific promises get thisbody is to test it in all the possible combinations.

Suffix Notes:

_reached indicates the promise was tried. Any outcome will resultin a class with this suffix being defined.
_kept indicates some aspect of the promise was kept
_repaired indicates some aspect of the promise was repaired
_not_kept indicates some aspect of the promise was not kept.error, failed, denied and timeout outcomes will result in a classwith this suffix being defined
_error indicates the promise repair encountered an error
_failed indicates the promise failed
_denied indicates the promise repair was denied
_timeout indicates the promise timed out

Example:

code

bundleagentexample{commands:"/bin/true"classes=>results("bundle","my_class_prefix");reports:my_class_prefix_kept::"My promise was kept";my_class_prefix_repaired::"My promise was repaired";}

See also:scope,scoped_classes_generic,classes_generic

Implementation:

code

bodyclassesresults(scope,class_prefix){scope=>"$(scope)";promise_kept=>{"$(class_prefix)_reached","$(class_prefix)_kept"};promise_repaired=>{"$(class_prefix)_reached","$(class_prefix)_repaired"};repair_failed=>{"$(class_prefix)_reached","$(class_prefix)_error","$(class_prefix)_not_kept","$(class_prefix)_failed"};repair_denied=>{"$(class_prefix)_reached","$(class_prefix)_error","$(class_prefix)_not_kept","$(class_prefix)_denied"};repair_timeout=>{"$(class_prefix)_reached","$(class_prefix)_error","$(class_prefix)_not_kept","$(class_prefix)_timeout"};}

diff_results

Prototype:diff_results(scope, x)

Description: Definex prefixed/suffixed with promise outcome with command return codes adjusted to align withdiff.

Arguments:

scope: The scope the class should be defined with [bundle|namespace].
x: The unique part of the classes to be defined.

From man diff:Exit status is 0 if inputs are the same, 1 ifdifferent, 2 if trouble.

Example:

code

bundleagentexample{commands:"/usr/bin/diff"args=>"/tmp/file1 /tmp/file2",classes=>diff_results("diff");vars:"c"slist=>classesmatching("diff_.*");reports:"Found class '$(c)'";"Files Differ!"if=>"diff_failed|diff_error|diff_not_kept";"Files are the same."if=>"diff_kept";}

Implementation:

code

bodyclassesdiff_results(scope,x){inherit_from=>results($(scope),$(x));kept_returncodes=>{"0"};failed_returncodes=>{"1","2"};}

scoped_classes_generic

Prototype:scoped_classes_generic(scope, x)

Description: Definex prefixed/suffixed with promise outcomeSee also:scope

Arguments:

scope: The scope in which the class should be defined
x: The unique part of the classes to be defined

Implementation:

code

bodyclassesscoped_classes_generic(scope,x){scope=>"$(scope)";promise_repaired=>{"promise_repaired_$(x)","$(x)_repaired","$(x)_ok","$(x)_reached"};repair_failed=>{"repair_failed_$(x)","$(x)_failed","$(x)_not_ok","$(x)_error","$(x)_not_kept","$(x)_reached"};repair_denied=>{"repair_denied_$(x)","$(x)_denied","$(x)_not_ok","$(x)_error","$(x)_not_kept","$(x)_reached"};repair_timeout=>{"repair_timeout_$(x)","$(x)_timeout","$(x)_not_ok","$(x)_error","$(x)_not_kept","$(x)_reached"};promise_kept=>{"promise_kept_$(x)","$(x)_kept","$(x)_ok","$(x)_reached"};}

state_repaired

Prototype:state_repaired(x)

Description: Definex for 10 minutes if the promise was repaired

Arguments:

x: The name of the class that should be defined

Implementation:

code

bodyclassesstate_repaired(x){promise_repaired=>{"$(x)"};persist_time=>"10";scope=>"namespace";}

enumerate

Prototype:enumerate(x)

Description: Definex for 15 minutes if the promise is either kept or repairedThis is used by commercial editions to count instances of jobs in a cluster

Arguments:

x: The unique part of the class that should be definedThe class defined is prefixed withmXC_

Implementation:

code

bodyclassesenumerate(x){promise_repaired=>{"mXC_$(x)"};promise_kept=>{"mXC_$(x)"};persist_time=>"15";scope=>"namespace";}

always

Prototype:always(x)

Description: Define classx no matter what the outcome of the promise is

Arguments:

x: The name of the class to be defined

Implementation:

code

bodyclassesalways(x){promise_repaired=>{"$(x)"};promise_kept=>{"$(x)"};repair_failed=>{"$(x)"};repair_denied=>{"$(x)"};repair_timeout=>{"$(x)"};}

kept_successful_command

Prototype:kept_successful_command

Description: Set command to "kept" instead of "repaired" if it returns 0

Implementation:

code

bodyclasseskept_successful_command{kept_returncodes=>{"0"};}

Still need help?

Chat

Ask a question on Github

Mailing list

Version

master 3.24 (LTS)3.21 (LTS)view all versions

Movatterモバイル変換

lib/common.cf

action bodies

if_elapsed

if_elapsed_day

measure_performance

measure_promise_time

warn_only

bg

ifwin_bg

immediate

policy

log_repaired

log_verbose

sample_rate

classes bodies

if_repaired

if_else

cf2_if_else

if_notkept

if_ok

if_ok_cancel

cmd_repair

classes_generic

results

diff_results

scoped_classes_generic

state_repaired

enumerate

always

kept_successful_command

Still need help?