cf-serverd

Table of contents

cf-serverd is a socket listening daemon providing two services: it acts as afile server for remote file copying and it allows an authorizedcf-runagent to start acf-agent run.cf-agenttypically connects to acf-serverd instance to request updated policy code,but may also request additional files for download.cf-serverd employsrole based access control (defined in policy code) to authorizerequests.

cf-serverd keeps the promises made incommon andserver bundles, and isaffected bycommon andserver control bodies.

Notes:

This daemon reloads it's config when the SIGHUP signal is received.
Ifenable_report_dumps exists inWORKDIR (/var/cfengine/enable_report_dumps)cf-serverd will log reports provided tocf-hub toWORKDIR/diagnostics/report_dump (/var/cfengine/diagnostics/report_dumps). This data is useful when troubleshooting reporting issues with CFEngine Enterprise.
cf-serverd always considers the classserver to be defined.
SIGUSR1 sets the log level to debug.
SIGUSR2 sets the log level to notice.

History:

SIGHUP behavior added in 3.7.0
enable_report_dumps added in 3.16.0

Command reference

code

  --help        , -h       - Print the help message  --log-level   , -g value - Specify how detailed logs should be. Possible values: 'error', 'warning', 'notice', 'info', 'verbose', 'debug'  --debug       , -d       - Enable debugging output  --verbose     , -v       - Output verbose information about the behaviour of the agent  --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)  --no-fork     , -F       - Run as a foreground processes (do not fork)  --ld-library-path, -L value - Set the internal value of LD_LIBRARY_PATH for child processes  --generate-avahi-conf, -A       - Generates avahi configuration file to enable policy server to be discovered in the network  --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  --graceful-detach, -t value - Terminate gracefully on SIGHUP by detaching from systemd and waiting n seconds before terminating  --ignore-preferred-augments           - Ignore def_preferred.json file in favor of def.json

Control promises

Settings describing the details of the fixed behavioral promises made bycf-serverd. Server controls are mainly about determining access policy forthe connection protocol: i.e. access to the server itself. Access to specificfiles must be granted in addition.

code

bodyservercontrol{allowconnects=>{"127.0.0.1","::1"};allowallconnects=>{"127.0.0.1","::1"};# Uncomment me under controlled circumstances#trustkeysfrom         => { "127.0.0.1" , "::1" };}

allowconnects

Description: List of IP addresses that may connect to theserver port. They are denoted in either IP or subnet form. Forcompatibility reasons, regular expressions are also accepted.

This is the first line of defence; clients who are notin this list may not connect or send any data to the server.

See also the warning about regular expressions inallowallconnects.

Type:slist

Allowed input range: (arbitrary string)

Examples:

code

allowconnects=>{"127.0.0.1","::1","200.1.10.0/24","200\.1\.10\..*",};

allowallconnects

Description: List of IP addresses that may have more than oneconnection to the server port. They are denoted in either IP or subnetform. For compatibility reasons, regular expressions are also accepted.

The clients that are not listed here may have only one open connectionat the time with the server.

Note that127.0.0.1 is a regular expression (i.e., "127 anycharacter 0 any character 0 any character 1"), but this will onlymatch the IP address127.0.0.1. Take care with IP addresses anddomain names, as the hostname regular expressionwww.domain.comwill potentially match more than one hostname (e.g.,wwwxdomain.com, in addition to the desired hostnamewww.domain.com).

Type:slist

Allowed input range: (arbitrary string)

Examples:

code

allowallconnects=>{"127.0.0.1","::1","200.1.10.0/24","200\.1\.10\..*",};

allowlegacyconnects

Description: List of hosts from which the server accepts connectionsthat are not using the latest protocol.

To define subnets or address ranges, use CIDR notation:

code

allowlegacyconnects=>{"192.168.1.0/24","192.168.2.123"}

In CFEngine <= 3.8, absence of this attribute means that connections from all hosts are accepted,for compatibility with pre-3.6 CFEngine versions.

Set this attribute to an empty list to not allow any incoming connectionsusing legacy protocol versions:

code

allowlegacyconnects=>{}

In CFEngine >= 3.9, legacy protocol is disallowed by default, and you have tospecify a list of hosts allowed to use the legacy protocol.

Type:slist

Allowed input range: (arbitrary string)

See also:protocol_version

allowciphers

Description: List of TLS ciphers the server accepts bothincoming andoutgoing (in the case of client initiated reporting with CFEngine Enterprise) connections usingcf-serverd.For a list of possible ciphers, see man page for "openssl ciphers".

Type:string

Allowed input range: (arbitrary string)

Default value: AES256-GCM-SHA384:AES256-SHA

Example:

code

bodyservercontrol{# Only this non-default cipher is to be acceptedallowciphers=>"RC4-MD5";}

Note: When used withprotocol_version 1 (classic protocol),this does not do anything as the classic protocol does not support TLS ciphers.

History: Introduced in CFEngine 3.6.0

allowtlsversion

Description: Minimum TLS version allowed for bothincoming andoutgoing (in the case of client initiated reporting with CFEngine Enterprise) connections usingcf-serverd.

Type:string

Allowed input range: (arbitrary string)

Default value: 1.0

Example:

code

bodyservercontrol{# Allow only TLSv1.1 or higherallowtlsversion=>"1.1";}

Note: When used withprotocol_version 1 (classic protocol),this attribute does not do anything.

History: Introduced in CFEngine 3.7.0

allowusers

Description: List of usernames who may execute requests from thisserver

The usernames listed in this list are those asserted as public keyidentities during client-server connections. These may or may notcorrespond to system identities on the server-side system.

Type:slist

Allowed input range: (arbitrary string)

Example:

code

allowusers=>{"cfengine","root"};

bindtointerface

Description: IP of the interface to which the server should bindon multi-homed hosts

On multi-homed hosts, the server and client can bind to a specificinterface for server traffic. The IP address of the interface mustbe given as the argument, not the device name.

Type:string

Allowed input range: (arbitrary string)

code

bindtointerface=>"192.168.1.1";

To bind to all interfaces, including IPV6:

code

bindtointerface=>"::";

Note that a bug in netstat will not correctly report that cf-serverd islistening on both IPV4 and IPV6 interfaces. A test with netcat (nc) willconfirm.

code

# nc -v -4 172.16.100.1 5308Connectionto172.16.100.15308port[tcp/cfengine]succeeded!^C# nc -v -6 fe80:470:1d:a2f::2 5308Connectiontofe80:470:1d:a2f::25308port[tcp/cfengine]succeeded!^C

cfruncommand

Description: Path to the cf-agent command or cf-execd wrapper forremote execution

It is normal for this to point to the location ofcf-agent but itcould also point to thecf-execd, or even another program orshell command at your own risk.

Type:string

Allowed input range:.+

code

bodyservercontrol{cfruncommand=>"/var/cfengine/bin/cf-agent";}

call_collect_interval

CFEngine Enterprise only.

Description: The interval in minutes in between collect calls tothe CFEngine Server offering a tunnel for report collection.

If option time is set, it causes the server daemon to peer with apolicy hub by attempting a connection at regular intervals of thevalue of the parameter in minutes.

This feature is designed to allow Enterprise report collection fromhosts that are not directly addressable from a hub data-aggregationprocess. For example, if some of the clients of a policy hub arebehind NAT or firewall then the hub possibly is not able toopen a connection to port 5308 of the client. The solution is toenablecall_collect_interval on the client's cf-serverd.Note: also remember to admit the client's IP on the hub'scollect_calls ACL (seeresource_type inbundle serveraccess_rules).

If this option is set, the client'scf-serverd will "peer" withthe server daemon on a policy hub. This means that,cf-serverd onan unreachable (e.g. NATed) host will attempt to report in to thecf-serverd on its assigned policy hub and offer it a short timewindow in which to download reports over the establishedconnection. The effect is to establish a temporary secure tunnelbetween hosts, initiated from the satellite host end. Theconnection is made in such a way that host autonomy is notcompromised. Either hub may refuse or decline to play their role atany time, in the usual way (avoiding DOS attacks). Normal accesscontrols must be set for communication in both directions.

Collect calling cannot be as efficient as data collection by thecf-hub, as the hub is not able to load balance. Hosts that use thisapproach should exclude themselves from the cf-hub datacollection.

The sequence of events is this:

The host'scf-serverd connects to its registered CFEngine Server
The host identifies itself to authentication and accesscontrol and sends a collect-call pull-request to the server
The server might honor this, if the access control grants access.
If access is granted, the server hascollect_window seconds toinitiate a query to the host for its reports.
The server identifies itself to authentication and accesscontrol and sends a query request to the host to collect thereports.
When finished, the host closes the tunnel.

Type:int

Allowed input range:0,99999999999

Example:

code

call_collect_interval => "5";

The full configuration to enable client initiated reporting would look something like this:

code

########################################################## Server config#########################################################bodyservercontrol{allowconnects=>{"10.10.10.0/24","::1"};allowallconnects=>{"10.10.10.0/24","::1"};trustkeysfrom=>{"10.10.10.0/24","::1"};call_collect_interval=>"5";}#########################################################bundleservermy_access_rules(){access:policy_server::"collect_calls"resource_type=>"query",admit=>{"10.10.10.10"},comment=>"The policy server must admit queries for collect_calls (client initated reporting).";satellite_hosts::"delta"comment=>"Grant access to cfengine hub to collect report deltas",resource_type=>"query",admit=>{"policy_hub"};"full"comment=>"Grant access to cfengine hub to collect full report dump",resource_type=>"query",admit=>{"policy_hub"};}

Note: In theMasterfiles Policy Framework,body server control and default access rules are found incontrols/cf_serverd.cf.

History: Was introduced in Enterprise 3.0.0 (2012)

collect_window

CFEngine Enterprise only.

Description: A time in seconds that a collect-call tunnel remainsopen to a hub to attempt a report transfer before it is closed

Type:int

Allowed input range:0,99999999999

code

collect_window => "15";

Default value: 30.

History: Was introduced in Enterprise 3.0.0 (2012)

denybadclocks

Description: true/false accept connections from hosts with clocksthat are out of sync

A possible form of attack on the fileserver is to request filesbased on time by setting the clocks incorrectly. This optionprevents connections from clients whose clocks are drifting too farfrom the server clock (where "too far" is currently defined as"more than an hour off"). This serves as a warning about clockasynchronization and also a protection against Denial of Serviceattempts based on clock corruption.

Type:boolean

Default value: true

Example:

code

bodyservercontrol{denybadclocks=>"true";}

denyconnects

Description: List of IPs that may NOT connect to theserver port

Hosts or IP addresses that are explicitly denied access. Thisshould only be used in special circumstances. One should nevergrant generic access to everything and then deny special cases.Since the default server behavior is to grant no access toanything, this list is unnecessary unless you have already grantedaccess to some set of hosts using a generic pattern, to which youintend to make an exception.

See also the warning about regular expressions inallowallconnects.

Type:slist

Allowed input range: (arbitrary string)

Example:

code

bodyservercontrol{denyconnects=>{"badhost\.domain\.evil","host3\.domain\.com"};}

logallconnections

Deprecated: This attribute was deprecated in 3.7.0.

logencryptedtransfers

Description: true/false log all successful transfers required tobe encrypted. Only applies to classic protocol connections(because the new protocol uses TLS which enforces encryption for everything).

If true the server will log all transfers of files which the serverrequires to encrypted in order to grant access (seeifencrypted)to syslog. These files are deemed to be particularly sensitive.

Type:boolean

Default value: false

Example:

code

bodyservercontrol{logencryptedtransfers=>"true";}

maxconnections

Description: Maximum number of concurrent connections the server will accept. Recommended value for a hub istwo times the total number of hosts bootstrapped to this hub.

Type:int

Allowed input range:0,99999999999

Default value: 30

Example:

code

# client sidebodyagentcontrol{maxconnections=>"1000";}# server sidebodyservercontrol{maxconnections=>"1000";}

port

Description: Default port for the CFEngine server

Type:int

Allowed input range:1,65535

Default value: 5308

Example:

code

bodyhubcontrol{port=>"5308";}bodyservercontrol{specialhost::port=>"5308";!specialhost::port=>"5308";}

Notes:

The standard or registered port number is tcp/5308. CFEngine doesnot presently use its registered udp port with the same number, butthis could change in the future.

Changing the standard port number is not recommended practice. Youshould not do it without a good reason.

serverfacility

Description: Menu option for syslog facility level

Type: (menu option)

Allowed input range:

code

LOG_USERLOG_DAEMONLOG_LOCAL0LOG_LOCAL1LOG_LOCAL2LOG_LOCAL3LOG_LOCAL4LOG_LOCAL5LOG_LOCAL6LOG_LOCAL7

See syslog notes.

Default value:LOG_USER

Example:

code

bodyservercontrol{serverfacility=>"LOG_USER";}

skipverify

Description: This option is obsolete, does nothing and is retainedfor backward compatibility.

Type:slist

Allowed input range: (arbitrary string)

Example:

code

bodyservercontrol{skipverify=>{"special_host.*","192.168\..*"};}

trustkeysfrom

Description: List of IPs from whom the server will accept and trustnew (untrusted) public keys. They are denoted in either IP or subnetform. For compatibility reasons, regular expressions are alsoaccepted.

The new accepted public keys are written to theppkeysdirectory, and a message is logged:

code

192.168.122.254> Trusting new key: MD5=0d5603d68dd62d35bab2150e35d055ae

NOTE:trustkeysfrom should normally be an empty list except incontrolled circumstances, for example when the network is being set upand keys are to be exchanged for the first time.

See also the warning about regular expressions inallowallconnects.

Type:slist

Allowed input range: (arbitrary string)

Example:

code

bodyservercontrol{trustkeysfrom=>{"10.0.1.1","192.168.0.0/16"};}

listen

Description: true/false enable server daemon to listen on definedport

This attribute allows to disablecf-serverd from listening on anyport. Should be used in conjunction withcall_collect_interval.

This setting only applies to CFEngine clients, the policy hub willnot be affected. Changing this setting requires a restart ofcf-serverd for the change to take effect.

Type:boolean

Default value: true

Example:

code

bodyservercontrol{listening_host_context::listen=>"true";!listening_host_context::listen=>"false";}

History: Was introduced in 3.4.0, Enterprise 3.0 (2012)

Deprecated attributes in body server control

The following attributes were functional in previous versionsof CFEngine, but today they are deprecated, either becausetheir functionality is being handled trasparently or becauseit doesn't apply to current CFEngine version.