access
Access promises are conditional promises made by the server about file
objects. The promise has two consequences. For file copy requests, the
file becomes transferable to the remote client according to the
conditions specified in the server promise; in other words, if the
connection encryption requirements are met, and if the client has been
granted appropriate privileges with maproot (like its NFS counterpart)
to be able to see file objects not owned by the server process owner.
The promise has two mutally exclusive attributes admit and deny. Use of admit is preferred as mistakes and omissions can easily be made when excluding from a group.
When access is granted to a directory, the promise is automatically given about all of its contents and sub-directories. The access promise allows overlapping promises to be made, and these are kept on a first-come-first-served basis. Thus file objects (promisers) should be listed in order of most-specific file first. In this way, specific promises will override less specific ones.
access:
"/path/file_object"
admit = { "hostname", "ipv4_address", "ipv6_address" };
Example:
body server control
{
allowconnects => { "127.0.0.1" , "::1" };
allowallconnects => { "127.0.0.1" , "::1" };
trustkeysfrom => { "127.0.0.1" , "::1" };
}
bundle server access_rules()
{
access:
"/source/directory"
comment => "Access to file transfer",
admit => { "127.0.0.1" };
# Grant orchestration communication
"did.*"
comment => "Access to class context (enterprise)",
resource_type => "context",
admit => { "127.0.0.1" };
"value of my test_scalar, can expand variables here - $(sys.host)"
comment => "Grant access to the string in quotes, by name test_scalar",
handle => "test_scalar",
resource_type => "literal",
admit => { "127.0.0.1" };
"XYZ"
comment => "Grant access to contents of persistent scalar variable XYZ",
resource_type => "variable",
admit => { "127.0.0.1" };
# Client grants access to CFEngine hub access
"delta"
comment => "Grant access to cfengine hub to collect report deltas",
resource_type => "query",
report_data_select => report_filter,
admit => { "127.0.0.1" };
"full"
comment => "Grant access to cfengine hub to collect full report dump",
resource_type => "query",
report_data_select => report_filter,
admit => { "127.0.0.1" };
policy_hub::
"collect_calls"
comment => "Grant access to cfengine client to request the collection of its reports",
resource_type => "query",
admit => { "10.1.2.*" };
}
body report_data_select report_filter
{
variables_include => { "sys..*", "mon..*" };
variables_exclude => { "sys.host" };
}
Entries may be literal addresses of IPv4 or IPv6, or any name registered
in the POSIX gethostbyname service.
Attributes
admit
Description: The admit slist contains host names or IP addresses
to grant access to file objects.
Admit promises grant access to file objects on the server. Arguments may be IP addresses or hostnames, provided DNS name resolution is active. In order to reach this stage, a client must first have passed all of the standard connection tests in the control body.
The lists may contain network addresses in CIDR notation or regular expressions to match the IP address or name of the connecting host.
Type: slist
Allowed input range: (arbitrary string)
Example:
access:
"/home/mark/LapTop"
admit => { "127.0.0.1", "192.168.0.1/24", ".*\.domain\.tld" };
deny
Description: The deny slist contains host names or IP addresses
to deny access to file objects.
Denial is for special exceptions. A better strategy is always to grant on a need to know basis. A security policy based on exceptions is a weak one.
Type: slist
Allowed input range: (arbitrary string)
Example:
bundle server access_rules()
{
access:
"/path"
admit => { ".*\.example\.org" },
deny => { "badhost_1\.example\.org", "badhost_1\.example\.org" };
}
Notes: Only regular expressions or exact matches are allowed in this list, as non-specific matches are too greedy for denial.
maproot
Description: The maproot slist contains host names or IP addresses
to grant full read-privilege on the server.
Normally users authenticated by the server are granted access only to
files owned by them and no-one else. Even if the cf-serverd process
runs with root privileges on the server side of a client-server
connection, the client is not automatically granted access to download
files owned by non-privileged users. If maproot is true then remote
root users are granted access to all files.
A typical case where mapping is important is in making backups of many user files.
Type: slist
Allowed input range: (arbitrary string)
Example:
access:
"/home"
admit => { "backup_host.example.org" },
ifencrypted => "true",
# Backup needs to have access to all users
maproot => { "backup_host.example.org" };
Notes:
On Windows, cf-serverd, maproot is required to read files if the
connecting user does not own the file on the server.
ifencrypted
Description: The ifencrypted menu option determines whether the
current file access promise is conditional on the connection from the
client being encrypted.
If this flag is true a client cannot access the file object unless its connection is encrypted.
Type: boolean
Default value: false
Example:
access:
"/path/file"
admit => { ".*\.example\.org" },
ifencrypted => "true";
resource_type
Description: The resource_type is the type of object being granted
access.
By default, access to resources granted by the server are files.
However, sometimes it is useful to cache literal strings, hints and
data on the server for easy access (e.g. the contents of variables or
hashed passwords). In the case of literal data, the promise handle
serves as the reference identifier for queries. Queries are instigated
by function calls by any agent.
Type: (menu option)
Allowed input range:
path
literal
context
query
variable
If the resource type is literal, CFEngine will grant access to a
literal data string. This string is defined either by the promiser
itself, but the name of the variable is the identifier given by the
promise handle of the access promise, since the promiser string might be
complex.
If the resource type is variable then the promiser is the name of a
persistent scalar variable defined on the server-host. Currently
persistent scalars are only used internally by Enterprise CFEngine to
hold enumerated classes for orchestration purposes.
If you want to send the value of a policy defined variable in the server host (which for some reason is not available directly through policy on the client, e.g. because they have different policies), then you could use the following construction:
access:
"$(variable_name)"
handle => "variable_name",
resource_type => "literal";
If the resource type is context, the promiser is treated as a regular
expression to match persistent classes defined on the server host. If
these are matched by the request from the client, they will be
transmitted (See Function
remoteclassesmatching).
The term query may also be used in CFEngine Enterprise to query the server
for data from embedded databases. This is currently for internal use only, and
is used to grant access to report 'menus'. If the promiser of a query request
is called collect_calls, this grants access to server peering collect-call
tunneling.
Example:
bundle server access_rules()
{
access:
"value of my test_scalar, can expand variables here - $(sys.host)"
handle => "test_scalar",
comment => "Grant access to contents of test_scalar VAR",
resource_type => "literal",
admit => { "127.0.0.1" };
"XYZ"
resource_type => "variable",
handle => "XYZ",
admit => { "127.0.0.1" };
# On the policy hub
"collect_calls"
resource_type => "query",
admit => { "127.0.0.1" };
# On the isolated client in the field
"delta"
comment => "Grant access to cfengine hub to collect report deltas",
resource_type => "query",
admit => { "127.0.0.1" };
"full"
comment => "Grant access to cfengine hub to collect full report dump",
resource_type => "query",
admit => { "127.0.0.1" };
}
report_data_select
This body is only available in CFEngine Enterprise.
Description: The report_data_select body restricts access to data
for the specified query types reported to the CFEngine Enterprise Database.
This body template allows users to control the content of reports collected by the Enterprise Database Server, and allows users to strip unwanted data (e.g. temporary variables from reporting).
Report content can be differentiated between hosts that are controlled by the class expression on access promiser.
If more than one select statement applies to the same host, all of them are applied.
Usage of this body is only allowed in conjunction with using
resource_type => "query", as this is the resource type that is being affected.
Type: body report_data_select
Example:
body report_data_select
{
variables_include => { "sys..*" };
monitoring_exclude => { ".*" };
}
History: Introduced in Enterprise 3.5.0
classes_include
Description: The classes_include attribute is used to filter content
of the class report collected by Enterprise Hub, to include classes matching
specified regular expressions on the list.
Only classes matching the specified regular expressions on the list will be sent back in the report.
If this attribute is not used, the report content is not reduced.
Type: slist
Allowed input range: (arbitrary string)
Example:
body report_data_select
{
classes_include => { "report_only_my_classes_.*" };
}
History: Introduced in Enterprise 3.5.0
classes_exclude
Description: The classes_exclude attribute is used to filter content
of the class report collected by Enterprise Hub, to exclude classes matching
specified regular expressions on the list.
If this attribute is used in conjunction with classes_include it will
exclude entries from the subset selected by the include expression.
Type: slist
Allowed input range: (arbitrary string)
Example:
body report_data_select
{
classes_exclude => { "my_tmp_class.*" };
}
Notes:
History: Introduced in Enterprise 3.5.0
variables_include
Description: The variables_include attribute is used to filter
content of the variables report collected by Enterprise Hub, to contain
only variables matching specified regular expressions on the list.
If the attribute is not used, the report content is not reduced.
Type: slist
Allowed input range: (arbitrary string)
Regular expressions for this attribute use the form <scope>.<variable_name>.
Example:
body report_data_select
{
variables_include => { "my_bundle.my_variable_prefix_.*" };
}
History: Introduced in Enterprise 3.5.0
variables_exclude
Description: The variables_exclude attribute is used to filter
content of the variable report collected by Enterprise Hub, to exclude
variables matching specified regular expression list.
Type: slist
Allowed input range: (arbitrary string)
Regular expressions for this attribute use the form
Example:
body report_data_select
{
variables_exclude => { "my_bundle.tmp_var_test.*" };
}
Notes:
If this attribute is used in conjunction with variables_include, it will
exclude entries from the subset selected by the include expression.
History: Introduced in Enterprise 3.5.0
promise_notkept_log_include
Description: The promise_notkept_log_include attribute is used to
filter content of the not kept log report collected by Enterprise Hub,
to contain promise handles matching specified regular expressions on
the list.
Only those handles matching the regular expressions on the list will be sent back in the report.
If the attribute is not used, the report content will not be reduced.
Type: slist
Allowed input range: (arbitrary string)
Example:
body report_data_select
{
promise_notkept_log_include => { "my_none_important_promises_.*" };
}
History: Introduced in Enterprise 3.5.0
promise_notkept_log_exclude
Description: The promise_notkept_log_exclude attribute is used to
filter content of the not kept log report collected by Enterprise Hub,
to exclude promise handles matching specified regular expressions on the
list.
Only those handles matching regular expression on the list will be excluded from the report.
Type: slist
Allowed input range: (arbitrary string)
Example:
body report_data_select
{
promise_notkept_log_exclude => { "my_tmp_promise_handle.*" };
}
Notes: If this attribute is used in conjunction with the
promise_notkept_log_include attribute, it will exclude entries
from the subset selected by the include expression.
History: Introduced in Enterprise 3.5.0
promise_repaired_log_include
Description: The promise_repaired_log_include attribute is used to
filter content of the repaired log report collected by Enterprise Hub,
to include regular expressions matched on the list.
Only those handles matching the regular expression on the list will be sent back in the report. If attribute is not used, the report content will not be filtered.
Type: slist
Allowed input range: (arbitrary string)
Example:
body report_data_select
{
promise_repaired_log_include => { "my_none_important_promises_.*" };
}
History: Introduced in Enterprise 3.5.0
promise_repaired_log_exclude
Description: The promise_repaired_log_exclude attribute is used to
filter content of the repaired log report collected by Enterprise Hub,
to exclude promise handles matching regular expression on the list.
Only those handles matching regular expression on the list will be excluded from the report.
Type: slist
Allowed input range: (arbitrary string)
Example:
body report_data_select
{
promise_repaired_log_exclude => { "my_tmp_promise_handle.*" };
}
Notes:
If this attribute is used in conjunction with promise_repaired_log_include,
it will exclude entries from the subset selected by the include expression.
History: Introduced in Enterprise 3.5.0
monitoring_include
Description: The monitoring_include attribute is used to filter
content of the monitoring report collected by Enterprise Hub, to contain
only observed objects matching regular expressions on the list.
Only object names matching regular expression on the list will be sent back in the report. If the attribute is not used, the report content will not be filtered.
Type: slist
Allowed input range: (arbitrary string)
Example:
body report_data_select
{
monitoring_include => { "mem_.*" };
}
History: Introduced in Enterprise 3.5.0
monitoring_exclude
Description: The monitoring_exclude attribute is used to filter
content of the monitoring report collected by Enterprise Hub, to exclude
observed objects matching specified regular expressions on the list.
Only object names matching regular expression list will be excluded from the report.
Type: slist
Allowed input range: (arbitrary string)
Example:
body report_data_select
{
monitoring_exclude => { "mem_swap", "mem_freeswap" };
}
Notes:
If this attribute is used in conjunction with monitoring_include it will
exclude entries from the subset selected by the include expression.
History: Introduced in Enterprise 3.5.0