Blocks that create, copy, change and remove files and directories, and set their permissions.

Clean Up Old Files

Deletes files under a directory that haven’t changed for a number of days.

Generates: a files promise.

Settings

Setting Required Description
Directory Yes Its contents are cleaned, not the directory itself, e.g. /var/tmp.
Older than (days) Yes At least 1. Default: 7.
Recursion depth Yes “inf” for the whole tree, or a number like “1” for just the directory’s own files. Default: inf.

Example

The policy it generates, for example:

# Clean up old temp files
files:
  "/var/tmp"
    delete => default:tidy,
    file_select => default:days_old("14"),
    depth_search => default:recurse("inf");

Copy Directory

Recursively copies a directory tree and enforces permissions on every file.

Generates: a files promise.

Settings

Setting Required Description
Destination directory Yes Where the copy goes, e.g. /opt/app/static.
Source directory Yes The directory to copy, on the host itself, e.g. /srv/build/static.
Recursion depth Yes How many levels deep to copy — “inf” for the whole tree, or a number like “1” for just its immediate contents. Default: inf.
Permissions Yes Applied to every file; directories also keep their execute bits, so they stay enterable. Default: 644.
Owner Yes Default: root.
Group Yes Default: root.

Example

The policy it generates, for example:

# Copy the static files
files:
  "/opt/app/static/."
    create => "true",
    copy_from => default:local_cp("/srv/build/static"),
    depth_search => default:recurse("inf"),
    perms => mog_dirs("644", "root", "root");

body perms mog_dirs(mode, user, group)
{
  owners => { "$(user)" };
  groups => { "$(group)" };
  mode => "$(mode)";
  rxdirs => "true";
}

Copy File

Copies a file from a source path known to the agent, enforcing permissions.

Generates: a files promise.

Settings

Setting Required Description
Destination path Yes Where the file is copied to, e.g. /etc/motd.
Source path Yes An absolute path on this host, or on the server when one is given.
From server No Copy from this host instead, e.g. $(sys.policy_hub), comparing content. Its cf-serverd must allow access to the source path (the hub’s default policy shares /var/cfengine/masterfiles).
Permissions Yes Default: 644.
Owner Yes Default: root.
Group Yes Default: root.

Example

The policy it generates, for example:

# Copy the message of the day
files:
  "/etc/motd"
    copy_from => default:local_cp("/srv/files/motd"),
    perms => default:mog("644", "root", "root");

Create Directory

Ensures directories exist with the given ownership and mode, parents included.

Generates: a files promise.

Settings

Setting Required Description
Directory Yes One absolute path per line. Missing parent directories are created too (mode 700).
Permissions Yes Default: 755.
Owner Yes Default: root.
Group Yes Default: root.

Example

The policy it generates, for example:

# Create the web root
files:
  "/var/www/html/."
    create => "true",
    perms => default:mog("755", "www-data", "www-data");

Ensures a symbolic link points at a target.

Generates: a files promise.

Settings

Setting Required Description
Link Yes Where the link goes, e.g. /etc/nginx/sites-enabled/app.
Points to Yes Created even if the target doesn’t exist yet.
If something else is there Yes One of: Leave it, and fail, Move it aside. Default: Leave it, and fail.

Example

The policy it generates, for example:

# Enable the app site
files:
  "/etc/nginx/sites-enabled/app"
    link_from => default:ln_s("/etc/nginx/sites-available/app"),
    move_obstructions => "false";

Create/Edit File

Ensures a file exists with exactly the given content and permissions.

Generates: a files promise.

Settings

Setting Required Description
File path Yes The file to create, or keep with this content, e.g. /etc/app.conf.
Content Yes The whole file: anything else in it is replaced. $(name) references are expanded by CFEngine.
Permissions Yes Default: 644.
Owner Yes Default: root.
Group Yes Default: root.

Example

The policy it generates, for example:

# Write the app config
files:
  "/etc/app.conf"
    create => "true",
    content => "name = \"app\"
port = 8080
",
    perms => default:mog("644", "root", "root");

Remove Directory

Deletes directories and everything in them.

Generates: a methods promise.

Settings

Setting Required Description
Directory Yes One absolute path per line; the whole tree goes. A plain file at the path is removed too.

Example

The policy it generates, for example:

# Remove the build cache
methods:
  "remove /tmp/build" usebundle => default:rm_rf("/tmp/build");

Remove File

Ensures one or more files are absent.

Generates: a files promise.

Settings

Setting Required Description
File path Yes One absolute path per line. Taken literally, not as a pattern.

Example

The policy it generates, for example:

# Remove the default site
files:
  "/etc/nginx/sites-enabled/default"
    delete => default:tidy,
    pathtype => "literal";

Render Template

Renders a Mustache template to a destination file.

Generates: a files promise.

Settings

Setting Required Description
Destination path Yes The file rendered on the managed host, e.g. /etc/nginx/nginx.conf.
Template content Yes Mustache: {{{vars.:vars.}}} inserts a variable (triple braces: not HTML-escaped), {{#classes.:}}…{{/classes.:}} keeps a section only while the class is set. It’s saved as its own .mustache file next to the policy, used as written: $(name) isn’t expanded there, use {{{vars.…}}}.
Permissions Yes Default: 644.
Owner Yes Default: root.
Group Yes Default: root.

Example

The policy it generates, for example:

# Render the app config
files:
  "/etc/app.conf"
    create => "true",
    edit_template => "$(this.promise_dirname)/templates/example_render_the_app_config.mustache",
    template_method => "mustache",
    perms => default:mog("644", "root", "root");

Rotate Log

Rotates log files once they grow past a size, keeping a number of old copies.

Generates: a methods promise.

Settings

Setting Required Description
Log file Yes One absolute path per line; a missing file is skipped.
Rotate when bigger than Yes Bytes, or with a unit: 500k, 10M, 1G. Default: 10M.
Old copies to keep Yes The file moves to .1, .2 … and the oldest is overwritten. At least 1. Default: 5.

Example

The policy it generates, for example:

# Rotate the app log
methods:
  "rotate /var/log/app.log"
    usebundle => default:logrotate("/var/log/app.log", "50M", "5");

Set Permissions

Enforces ownership and mode on one or more paths, without managing content.

Generates: a files promise.

Settings

Setting Required Description
Path Yes One absolute path per line.
Permissions Yes Directories keep their execute bits, so they stay enterable. Default: 644.
Owner Yes Default: root.
Group Yes Default: root.
Everything under each path too No Applies to every file and directory below, on the same filesystem. Directories stay enterable whatever the mode. Default: No.

Example

The policy it generates, for example:

# Lock down the shadow file
files:
  "/etc/shadow" perms => mog_dirs("640", "root", "shadow");

body perms mog_dirs(mode, user, group)
{
  owners => { "$(user)" };
  groups => { "$(group)" };
  mode => "$(mode)";
  rxdirs => "true";
}

Watch File for Changes

Reports when a file’s content changes (repaired on a change).

Generates: a files promise.

Settings

Setting Required Description
File path Yes One absolute path per line. The first run only records the hash, and counts as a change.

Example

The policy it generates, for example:

# Watch the account files
vars:
  "watch_the_account_files_path" slist => { "/etc/passwd", "/etc/group" };

files:
  "$(watch_the_account_files_path)" changes => default:detect_content;