> NOTE: This page was generated from the Puppet source code on 2024-08-28 16:45:59 -0700

# file

- Attributes
- Providers
- Provider Features

## Description

Manages files, including their content, ownership, and permissions.

The `file` type can manage normal files, directories, and symlinks; the type should be specified in the `ensure` attribute.

File contents can be managed directly with the `content` attribute, or downloaded from a remote source using the `source` attribute; the latter can also be used to recursively serve directories (when the `recurse` attribute is set to `true` or `local`). On Windows, note that file contents are managed in binary mode; Puppet never automatically translates line endings.

Autorequires: If Puppet is managing the user or group that owns a file, the file resource will autorequire them. If Puppet is managing any parent directories of a file, the file resource autorequires them.

Warning: Enabling `recurse` on directories containing large numbers of files slows agent runs. To manage file attributes for many files, consider using alternative methods such as the `chmod_r`, `chown_r`, or `recursive_file_permissions` modules from the Forge.

## Attributes

    file { 'resource title':
      path                    => # (namevar) The path to the file to manage.  Must be fully...
      ensure                  => # Whether the file should exist, and if so what...
      backup                  => # Whether (and how) file content should be backed...
      checksum                => # The checksum type to use when determining...
      checksum_value          => # The checksum of the source contents. Only md5...
      content                 => # The desired contents of a file, as a string...
      ctime                   => # A read-only state to check the file ctime. On...
      force                   => # Perform the file operation even if it will...
      group                   => # Which group should own the file.  Argument can...
      ignore                  => # A parameter which omits action on files matching
      links                   => # How to handle links during file actions.  During
      max_files               => # In case the resource is a directory and the...
      mode                    => # The desired permissions mode for the file, in...
      mtime                   => # A read-only state to check the file mtime. On...
      owner                   => # The user to whom the file should belong....
      provider                => # The specific backend to use for this `file...
      purge                   => # Whether unmanaged files should be purged. This...
      recurse                 => # Whether to recursively manage the _contents_ of...
      recurselimit            => # How far Puppet should descend into...
      replace                 => # Whether to replace a file or symlink that...
      selinux_ignore_defaults => # If this is set, Puppet will not call the SELinux
      selrange                => # What the SELinux range component of the context...
      selrole                 => # What the SELinux role component of the context...
      seltype                 => # What the SELinux type component of the context...
      seluser                 => # What the SELinux user component of the context...
      show_diff               => # Whether to display differences when the file...
      source                  => # A source file, which will be copied into place...
      source_permissions      => # Whether (and how) Puppet should copy owner...
      sourceselect            => # Whether to copy all valid sources, or just the...
      staging_location        => # When rendering a file first render it to this...
      target                  => # The target for creating a link.  Currently...
      type                    => # A read-only state to check the file...
      validate_cmd            => # A command for validating the file's syntax...
      validate_replacement    => # The replacement string in a `validate_cmd` that...
      # ...plus any applicable metaparameters.
    }

### path

(Namevar: If omitted, this attribute’s value defaults to the resource’s title.)

The path to the file to manage. Must be fully qualified.

On Windows, the path should include the drive letter and should use `/` as the separator character (rather than `\\`).

(↑ Back to file attributes)

### ensure

(Property: This attribute represents concrete state on the target system.)

Whether the file should exist, and if so what kind of file it should be. Possible values are `present`, `absent`, `file`, `directory`, and `link`.

- `present` accepts any form of file existence, and creates a normal file if the file is missing. (The file will have no content unless the `content` or `source` attribute is used.)
- `absent` ensures the file doesn’t exist, and deletes it if necessary.
- `file` ensures it’s a normal file, and enables use of the `content` or `source` attribute.
- `directory` ensures it’s a directory, and enables use of the `source`, `recurse`, `recurselimit`, `ignore`, and `purge` attributes.
- `link` ensures the file is a symlink, and requires that you also set the `target` attribute. Symlinks are supported on all Posix systems and on Windows Vista / 2008 and higher. On Windows, managing symlinks requires Puppet agent’s user account to have the “Create Symbolic Links” privilege; this can be configured in the “User Rights Assignment” section in the Windows policy editor. By default, Puppet agent runs as the Administrator account, which has this privilege.

Puppet avoids destroying directories unless the `force` attribute is set to `true`. This means that if a file is currently a directory, setting `ensure` to anything but `directory` or `present` will cause Puppet to skip managing the resource and log either a notice or an error.

There is one other non-standard value for `ensure`. If you specify the path to another file as the ensure value, it is equivalent to specifying `link` and using that path as the `target`:

    # Equivalent resources:

    file { '/etc/inetd.conf':
      ensure => '/etc/inet/inetd.conf',
    }

    file { '/etc/inetd.conf':
      ensure => link,
      target => '/etc/inet/inetd.conf',
    }

However, we recommend using `link` and `target` explicitly, since this behavior can be harder to read and is deprecated as of Puppet 4.3.0.

Allowed values:

- `absent`
- `false`
- `file`
- `present`
- `directory`
- `link`
- `/./`

(↑ Back to file attributes)

### backup

Whether (and how) file content should be backed up before being replaced. This attribute works best as a resource default in the site manifest (`File { backup => main }`), so it can affect all file resources.

- If set to `false`, file content won’t be backed up.
- If set to a string beginning with `.`, such as `.puppet-bak`, Puppet will use copy the file in the same directory with that value as the extension of the backup. (A value of `true` is a synonym for `.puppet-bak`.)
- If set to any other string, Puppet will try to back up to a filebucket with that title. Puppet automatically creates a local filebucket named `puppet` if one doesn’t already exist. See the `filebucket` resource type for more details.

Default value: `false`

Backing up to a local filebucket isn’t particularly useful. If you want to make organized use of backups, you will generally want to use the primary Puppet server’s filebucket service. This requires declaring a filebucket resource and a resource default for the `backup` attribute in site.pp:

    # /etc/puppetlabs/puppet/manifests/site.pp
    filebucket { 'main':
      path   => false,                # This is required for remote filebuckets.
      server => 'puppet.example.com', # Optional; defaults to the configured primary Puppet server.
    }

    File { backup => main, }

If you are using multiple primary servers, you will want to centralize the contents of the filebucket. Either configure your load balancer to direct all filebucket traffic to a single primary server, or use something like an out-of-band rsync task to synchronize the content on all primary servers.

> Note: Enabling and using the backup option, and by extension the filebucket resource, requires appropriate planning and management to ensure that sufficient disk space is available for the file backups. Generally, you can implement this using one of the following two options:

- Use a `find` command and `crontab` entry to retain only the last X days of file backups. For example:

    find /opt/puppetlabs/server/data/puppetserver/bucket -type f -mtime +45 -atime +45 -print0 | xargs -0 rm

- Restrict the directory to a maximum size after which the oldest items are removed.

Default: `false`

(↑ Back to file attributes)

### checksum

The checksum type to use when determining whether to replace a file’s contents.

The default checksum type is sha256.

Allowed values:

- `sha256`
- `sha256lite`
- `md5`
- `md5lite`
- `sha1`
- `sha1lite`
- `sha512`
- `sha384`
- `sha224`
- `mtime`
- `ctime`
- `none`

(↑ Back to file attributes)

### checksum_value

(Property: This attribute represents concrete state on the target system.)

The checksum of the source contents. Only md5, sha256, sha224, sha384 and sha512 are supported when specifying this parameter. If this parameter is set, source_permissions will be assumed to be false, and ownership and permissions will not be read from source.

(↑ Back to file attributes)

### content

(Property: This attribute represents concrete state on the target system.)

The desired contents of a file, as a string. This attribute is mutually exclusive with `source` and `target`.

Newlines and tabs can be specified in double-quoted strings using standard escaped syntax — \n for a newline, and \t for a tab.

With very small files, you can construct content strings directly in the manifest…

    define resolve($nameserver1, $nameserver2, $domain, $search) {
        $str = "search ${search}
            domain ${domain}
            nameserver ${nameserver1}
            nameserver ${nameserver2}
            "

        file { '/etc/resolv.conf':
          content => $str,
        }
    }

…but for larger files, this attribute is more useful when combined with the template or file function.

(↑ Back to file attributes)

### ctime

(Property: This attribute represents concrete state on the target system.)

A read-only state to check the file ctime. On most modern *nix-like systems, this is the time of the most recent change to the owner, group, permissions, or content of the file.

(↑ Back to file attributes)

### force

Perform the file operation even if it will destroy one or more directories. You must use `force` in order to:

- `purge` subdirectories
- Replace directories with files or links
- Remove a directory when `ensure => absent`

Default: `false`

Allowed values:

- `true`
- `false`
- `yes`
- `no`

(↑ Back to file attributes)

### group

(Property: This attribute represents concrete state on the target system.)

Which group should own the file. Argument can be either a group name or a group ID.

On Windows, a user (such as “Administrator”) can be set as a file’s group and a group (such as “Administrators”) can be set as a file’s owner; however, a file’s owner and group shouldn’t be the same. (If the owner is also the group, files with modes like `"0640"` will cause log churn, as they will always appear out of sync.)

(↑ Back to file attributes)

### ignore

A parameter which omits action on files matching specified patterns during recursion. Uses Ruby’s builtin globbing engine, so shell metacharacters such as `[a-z]*` are fully supported. Matches that would descend into the directory structure are ignored, such as `*/*`.

(↑ Back to file attributes)

### links

How to handle links during file actions. During file copying, `follow` will copy the target file instead of the link and `manage` will copy the link itself. When not copying, `manage` will manage the link, and `follow` will manage the file to which the link points.

Default: `manage`

Allowed values:

- `follow`
- `manage`

(↑ Back to file attributes)

### max_files

In case the resource is a directory and the recursion is enabled, puppet will generate a new resource for each file file found, possible leading to an excessive number of resources generated without any control.

Setting `max_files` will check the number of file resources that will eventually be created and will raise a resource argument error if the limit will be exceeded.

Use value `0` to log a warning instead of raising an error.

Use value `-1` to disable errors and warnings due to max files.

Default: `0`

Allowed values:

- `/^[0-9]+$/`
- `/^-1$/`

(↑ Back to file attributes)

### mode

(Property: This attribute represents concrete state on the target system.)

The desired permissions mode for the file, in symbolic or numeric notation. This value must be specified as a string; do not use un-quoted numbers to represent file modes.

If the mode is omitted (or explicitly set to `undef`), Puppet does not enforce permissions on existing files and creates new files with permissions of `0644`.

The `file` type uses traditional Unix permission schemes and translates them to equivalent permissions for systems which represent permissions differently, including Windows. For detailed ACL controls on Windows, you can leave `mode` unmanaged and use the puppetlabs/acl module.

Numeric modes should use the standard octal notation of `<SETUID/SETGID/STICKY><OWNER><GROUP><OTHER>` (for example, “0644”).

- Each of the “owner,” “group,” and “other” digits should be a sum of the permissions for that class of users, where read = 4, write = 2, and execute/search = 1.
- The setuid/setgid/sticky digit is also a sum, where setuid = 4, setgid = 2, and sticky = 1.
- The setuid/setgid/sticky digit is optional. If it is absent, Puppet will clear any existing setuid/setgid/sticky permissions. (So to make your intent clear, you should use at least four digits for numeric modes.)
- When specifying numeric permissions for directories, Puppet sets the search permission wherever the read permission is set.

Symbolic modes should be represented as a string of comma-separated permission clauses, in the form `<WHO><OP><PERM>`:

- “Who” should be any combination of u (user), g (group), and o (other), or a (all)
- “Op” should be = (set exact permissions), + (add select permissions), or - (remove select permissions)
- “Perm” should be one or more of:
  - r (read)
  - w (write)
  - x (execute/search)
  - t (sticky)
  - s (setuid/setgid)
  - X (execute/search if directory or if any one user can execute)
  - u (user’s current permissions)
  - g (group’s current permissions)
  - o (other’s current permissions)

Thus, mode `"0664"` could be represented symbolically as either `a=r,ug+w` or `ug=rw,o=r`. However, symbolic modes are more expressive than numeric modes: a mode only affects the specified bits, so `mode => 'ug+w'` will set the user and group write bits, without affecting any other bits.

See the manual page for GNU or BSD `chmod` for more details on numeric and symbolic modes.

On Windows, permissions are translated as follows:

- Owner and group names are mapped to Windows SIDs
- The “other” class of users maps to the “Everyone” SID
- The read/write/execute permissions map to the `FILE_GENERIC_READ`, `FILE_GENERIC_WRITE`, and `FILE_GENERIC_EXECUTE` access rights; a file’s owner always has the `FULL_CONTROL` right
- “Other” users can’t have any permissions a file’s group lacks, and its group can’t have any permissions its owner lacks; that is, “0644” is an acceptable mode, but “0464” is not.

(↑ Back to file attributes)

### mtime

(Property: This attribute represents concrete state on the target system.)

A read-only state to check the file mtime. On *nix-like systems, this is the time of the most recent change to the content of the file.

(↑ Back to file attributes)

### owner

(Property: This attribute represents concrete state on the target system.)

The user to whom the file should belong. Argument can be a user name or a user ID.

On Windows, a group (such as “Administrators”) can be set as a file’s owner and a user (such as “Administrator”) can be set as a file’s group; however, a file’s owner and group shouldn’t be the same. (If the owner is also the group, files with modes like `"0640"` will cause log churn, as they will always appear out of sync.)

(↑ Back to file attributes)

### provider

The specific backend to use for this `file` resource. You will seldom need to specify this — Puppet will usually discover the appropriate provider for your platform.

Available providers are:

- `posix`
- `windows`

(↑ Back to file attributes)

### purge

Whether unmanaged files should be purged. This option only makes sense when `ensure => directory` and `recurse => true`.

- When recursively duplicating an entire directory with the `source` attribute, `purge => true` will automatically purge any files that are not in the source directory.
- When managing files in a directory as individual resources, setting `purge => true` will purge any files that aren’t being specifically managed.

If you have a filebucket configured, the purged files will be uploaded, but if you do not, this will destroy data.

Unless `force => true` is set, purging will not delete directories, although it will delete the files they contain.

If `recurselimit` is set and you aren’t using `force => true`, purging will obey the recursion limit; files in any subdirectories deeper than the limit will be treated as unmanaged and left alone.

Default: `false`

Allowed values:

- `true`
- `false`
- `yes`
- `no`

(↑ Back to file attributes)

### recurse

Whether to recursively manage the contents of a directory. This attribute is only used when `ensure => directory` is set. The allowed values are:

- `false` — The default behavior. The contents of the directory will not be automatically managed.

- `remote` — If the `source` attribute is set, Puppet will automatically manage the contents of the source directory (or directories), ensuring that equivalent files and directories exist on the target system and that their contents match.

  Using `remote` will disable the `purge` attribute, but results in faster catalog application than `recurse => true`.

  The `source` attribute is mandatory when `recurse => remote`.

- `true` — If the `source` attribute is set, this behaves similarly to `recurse => remote`, automatically managing files from the source directory.

  This also enables the `purge` attribute, which can delete unmanaged files from a directory. See the description of `purge` for more details.

  The `source` attribute is not mandatory when using `recurse => true`, so you can enable purging in directories where all files are managed individually.

By default, setting recurse to `remote` or `true` will manage all subdirectories. You can use the `recurselimit` attribute to limit the recursion depth.

Allowed values:

- `true`
- `false`
- `remote`

(↑ Back to file attributes)

### recurselimit

How far Puppet should descend into subdirectories, when using `ensure => directory` and either `recurse => true` or `recurse => remote`. The recursion limit affects which files will be copied from the `source` directory, as well as which files can be purged when `purge => true`.

Setting `recurselimit => 0` is the same as setting `recurse => false` — Puppet will manage the directory, but all of its contents will be treated as unmanaged.

Setting `recurselimit => 1` will manage files and directories that are directly inside the directory, but will not manage the contents of any subdirectories.

Setting `recurselimit => 2` will manage the direct contents of the directory, as well as the contents of the first level of subdirectories.

This pattern continues for each incremental value of `recurselimit`.

Allowed values:

- `/^[0-9]+$/`

(↑ Back to file attributes)

### replace

Whether to replace a file or symlink that already exists on the local system but whose content doesn’t match what the `source` or `content` attribute specifies. Setting this to false allows file resources to initialize files without overwriting future changes. Note that this only affects content; Puppet will still manage ownership and permissions.

Default: `true`

Allowed values:

- `true`
- `false`
- `yes`
- `no`

(↑ Back to file attributes)

### selinux_ignore_defaults

If this is set, Puppet will not call the SELinux function selabel_lookup to supply defaults for the SELinux attributes (seluser, selrole, seltype, and selrange). In general, you should leave this set at its default and only set it to true when you need Puppet to not try to fix SELinux labels automatically.

Default: `false`

Allowed values:

- `true`
- `false`

(↑ Back to file attributes)

### selrange

(Property: This attribute represents concrete state on the target system.)

What the SELinux range component of the context of the file should be. Any valid SELinux range component is accepted. For example `s0` or `SystemHigh`. If not specified, it defaults to the value returned by selabel_lookup for the file, if any exists. Only valid on systems with SELinux support enabled and that have support for MCS (Multi-Category Security).

(↑ Back to file attributes)

### selrole

(Property: This attribute represents concrete state on the target system.)

What the SELinux role component of the context of the file should be. Any valid SELinux role component is accepted. For example `role_r`. If not specified, it defaults to the value returned by selabel_lookup for the file, if any exists. Only valid on systems with SELinux support enabled.

(↑ Back to file attributes)

### seltype

(Property: This attribute represents concrete state on the target system.)

What the SELinux type component of the context of the file should be. Any valid SELinux type component is accepted. For example `tmp_t`. If not specified, it defaults to the value returned by selabel_lookup for the file, if any exists. Only valid on systems with SELinux support enabled.

(↑ Back to file attributes)

### seluser

(Property: This attribute represents concrete state on the target system.)

What the SELinux user component of the context of the file should be. Any valid SELinux user component is accepted. For example `user_u`. If not specified, it defaults to the value returned by selabel_lookup for the file, if any exists. Only valid on systems with SELinux support enabled.

(↑ Back to file attributes)

### show_diff

Whether to display differences when the file changes, defaulting to true. This parameter is useful for files that may contain passwords or other secret data, which might otherwise be included in Puppet reports or other insecure outputs. If the global `show_diff` setting is false, then no diffs will be shown even if this parameter is true.

Default: `true`

Allowed values:

- `true`
- `false`
- `yes`
- `no`

(↑ Back to file attributes)

### source

A source file, which will be copied into place on the local system. This attribute is mutually exclusive with `content` and `target`. Allowed values are:

- `puppet:` URIs, which point to files in modules or Puppet file server mount points.
- Fully qualified paths to locally available files (including files on NFS shares or Windows mapped drives).
- `file:` URIs, which behave the same as local file paths.
- `http(s):` URIs, which point to files served by common web servers.

The normal form of a `puppet:` URI is:

`puppet:///modules/<MODULE NAME>/<FILE PATH>`

This will fetch a file from a module on the Puppet master (or from a local module when using Puppet apply). Given a `modulepath` of `/etc/puppetlabs/code/modules`, the example above would resolve to `/etc/puppetlabs/code/modules/<MODULE NAME>/files/<FILE PATH>`.

Unlike `content`, the `source` attribute can be used to recursively copy directories if the `recurse` attribute is set to `true` or `remote`. If a source directory contains symlinks, use the `links` attribute to specify whether to recreate links or follow them.

HTTP URIs cannot be used to recursively synchronize whole directory trees. You cannot use `source_permissions` values other than `ignore` because HTTP servers do not transfer any metadata that translates to ownership or permission details.

Puppet determines if file content is synchronized by computing a checksum for the local file and comparing it against the `checksum_value` parameter. If the `checksum_value` parameter is not specified for `puppet` and `file` sources, Puppet computes a checksum based on its `Puppet[:digest_algorithm]`. For `http(s)` sources, Puppet uses the first HTTP header it recognizes out of the following list: `X-Checksum-Sha256`, `X-Checksum-Sha1`, `X-Checksum-Md5` or `Content-MD5`. If the server response does not include one of these headers, Puppet defaults to using the `Last-Modified` header. Puppet updates the local file if the header is newer than the modified time (mtime) of the local file.

HTTP URIs can include a user information component so that Puppet can retrieve file metadata and content from HTTP servers that require HTTP Basic authentication. For example `https://<user>:<pass>@<server>:<port>/path/to/file.`

When connecting to HTTPS servers, Puppet trusts CA certificates in the puppet-agent certificate bundle and the Puppet CA. You can configure Puppet to trust additional CA certificates using the `Puppet[:ssl_trust_store]` setting.

Multiple `source` values can be specified as an array, and Puppet will use the first source that exists. This can be used to serve different files to different system types:

    file { '/etc/nfs.conf':
      source => [
        "puppet:///modules/nfs/conf.${host}",
        "puppet:///modules/nfs/conf.${os['name']}",
        'puppet:///modules/nfs/conf'
      ]
    }

Alternately, when serving directories recursively, multiple sources can be combined by setting the `sourceselect` attribute to `all`.

(↑ Back to file attributes)

### source_permissions

Whether (and how) Puppet should copy owner, group, and mode permissions from the `source` to `file` resources when the permissions are not explicitly specified. (In all cases, explicit permissions will take precedence.) Valid values are `use`, `use_when_creating`, and `ignore`:

- `ignore` (the default) will never apply the owner, group, or mode from the `source` when managing a file. When creating new files without explicit permissions, the permissions they receive will depend on platform-specific behavior. On POSIX, Puppet will use the umask of the user it is running as. On Windows, Puppet will use the default DACL associated with the user it is running as.
- `use` will cause Puppet to apply the owner, group, and mode from the `source` to any files it is managing.
- `use_when_creating` will only apply the owner, group, and mode from the `source` when creating a file; existing files will not have their permissions overwritten.

Default: `ignore`

Allowed values:

- `use`
- `use_when_creating`
- `ignore`

(↑ Back to file attributes)

### sourceselect

Whether to copy all valid sources, or just the first one. This parameter only affects recursive directory copies; by default, the first valid source is the only one used, but if this parameter is set to `all`, then all valid sources will have all of their contents copied to the local system. If a given file exists in more than one source, the version from the earliest source in the list will be used.

Default: `first`

Allowed values:

- `first`
- `all`

(↑ Back to file attributes)

### staging_location

When rendering a file first render it to this location. The default location is the same path as the desired location with a unique filename. This parameter is useful in conjuction with validate_cmd to test a file before moving the file to it’s final location. WARNING: File replacement is only guaranteed to be atomic if the staging location is on the same filesystem as the final location.

(↑ Back to file attributes)

### target

(Property: This attribute represents concrete state on the target system.)

The target for creating a link. Currently, symlinks are the only type supported. This attribute is mutually exclusive with `source` and `content`.

Symlink targets can be relative, as well as absolute:

    # (Useful on Solaris)
    file { '/etc/inetd.conf':
      ensure => link,
      target => 'inet/inetd.conf',
    }

Directories of symlinks can be served recursively by instead using the `source` attribute, setting `ensure` to `directory`, and setting the `links` attribute to `manage`.

Allowed values:

- `notlink`
- `/./`

(↑ Back to file attributes)

### type

(Property: This attribute represents concrete state on the target system.)

A read-only state to check the file type.

(↑ Back to file attributes)

### validate_cmd

A command for validating the file’s syntax before replacing it. If Puppet would need to rewrite a file due to new `source` or `content`, it will check the new content’s validity first. If validation fails, the file resource will fail.

This command must have a fully qualified path, and should contain a percent (`%`) token where it would expect an input file. It must exit `0` if the syntax is correct, and non-zero otherwise. The command will be run on the target system while applying the catalog, not on the primary Puppet server.

Example:

    file { '/etc/apache2/apache2.conf':
      content      => 'example',
      validate_cmd => '/usr/sbin/apache2 -t -f %',
    }

This would replace apache2.conf only if the test returned true.

Note that if a validation command requires a `%` as part of its text, you can specify a different placeholder token with the `validate_replacement` attribute.

(↑ Back to file attributes)

### validate_replacement

The replacement string in a `validate_cmd` that will be replaced with an input file name.

Default: `%`

(↑ Back to file attributes)

## Providers

### posix

Uses POSIX functionality to manage file ownership and permissions.

- Confined to: `feature == posix`
- Supported features: `manages_symlinks`

### windows

Uses Microsoft Windows functionality to manage file ownership and permissions.

- Confined to: `os.name == windows`

## Provider Features

Available features:

- `manages_symlinks` — The provider can manage symbolic links.

Provider support:

- posix - manages symlinks
- windows - No supported Provider features