Clockwork

res_file(5)

NAME

res_file - Clockwork Resource Type for managing files

DESCRIPTION

A fair portion of Linux system administration involves creating and maintaining configuration files. The res_file resource for Clockwork automates much of this work by allowing an administrator to specify almost every attribute of a file in a system policy:

1. Ownership (user and group)
2. Permissions
3. Contents (both static and dynamic)

ATTRIBUTES

owner

The name of the user who should own the file.

group

The name of the group who should own this file.

mode

File access permissions. The value must be specified in octal notation, i.e. 0755 for rwxr-xr-x.

source

The path (from the policy master's point of view) to the source file. If specified, the client-side file will be updated to match this static file.

Has no affect on directories, hard links or symbolic links.

template

The path (from the policy master's point of view) to a source file template. Like the source attribute, specifying this will cause the client-side file to be updated from the copy on the master. A template, however, is evaluated against the client's set of facts and a custom source file is generated.

Has no affect on directories, hard links or symbolic links.

path

The path (from the client's point of view) to the file to be managed.

present

Whether or not this file should exist. Valid values are "yes" and "no". The default value is "yes".

EXAMPLES

Ownership and Permissions

Ensure ownership and permissions on /etc/sudoers:

file "/etc/sudoers" {
    owner: "root"
    group: "root"
    mode:  "0440" # required mode for sudo to work
}

Complete Control

In this scenario, local changes to /etc/foo.conf, including edits, file removal, and ownership / permissions changes will be undone by the Clockwork agent.

file "/etc/foo.conf" {
    owner:  "foo"
    group:  "root"
    mode:   "0640"
    source: "/clockwork/files/foo.conf"
}

Templates

Templates can be used to flexibly push out files that are similar on all hosts, but differ with host-specific details. Assuming the following template (/clockwork/templates/banner.tpl):

<%= sys.fqdn %> - Widgets Co. Ltd.

Unauthorized access to this machine is prohibited.
Use of this system is limited to authorized individuals only.
All activity is monitored.

This host resource will enforce a banner for all hosts that contains the standard "warning" verbiage and the local hostname:

file "/etc/banner" {
    owner:    "root"
    group:    "root"
    mode:     "0400"
    template: "/clockwork/templates/banner.tpl"
}

When evaluated on the host named 'labs.example.net', /etc/banner will contain the following:

labs.example.net - Widgets Co. Ltd.

Unauthorized access to this machine is prohibited.
Use of this system is limited to authorized individuals only.
All activity is monitored.

CAVEATS

Symbolic links and hard links cannot be created with the file resource. Use res_symlink(5) instead.

DEPENDENCIES

File resources implicitly create the following dependencies:

User Owner (owner)

If the owner attribute is specified, the file resource will depend on the existence of that user. This is designed to ensure that files are owned by valid system users.

Group Owner (group)

If the group attribute is specified, the file resource will depend on the existence of that group. This is designed to ensure that files are owned by valid system groups.

Parent Directories

All parent components of the file path will be created if the file should exist and does not. By default, these parent directories will be owned by root:root with mode 0755. However, if the policy defines res_dir(5) resources with paths matching any component of the parent directory chain, the file resource will be set to depend on them.

An example should clear up any confusion:

file "/u/apps/test.example.net/index.html" {
    owner: "apache"
    group: "web"
    mode:  0664
    source: "/srv/clockwork/www/under-constr.html"
}

dir "/u/apps" {
    owner: "webmaster"
    group: "web"
    mode:  0755
}

dir "/u/apps/test.example.net" {
    owner: "apache"
    group: "web"
    mode:  0775
}

If the above policy was enforced on a host without the /u directory, the following would happen (in order):

1. Create /u, per defaults (root:root; 0755)
2. Create /u/apps, per policy (webmaster:web; 0755)
3. Create /u/apps/test.example.net, per policy (apache:web; 0775)
4. Create the file and retrieve its contents from the policy master.

AUTHOR

Clockwork was designed and written by James Hunt.

The Clockwork website is licensed under the Creative Commons Attribution-NoDerivs 3.0 United States License