Adding file server mount points

Puppet Server includes a file server for transferring static file content to agents. If you need to serve large files that you don't want to store in source control or distribute with a module, you can make a custom file server mount point and let Puppet serve those files from another directory.

In Puppet code, you can tell the file server is being used when you see a file resource that has a source => puppet:///... attribute specified.

To set up a mount point:

  1. Choose a directory on disk for the mount point, make sure Puppet Server can access it, and add your files to the directory.

  2. Edit fileserver.conf on your Puppet Server node, so Puppet knows which directory to associate with the new mount point.

  3. (Optional) If you want to restrict which nodes can access this mount point, adjust access settings in the auth.conf file.

After the mount point is set up, Puppet cod can reference the files you added to the directory at puppet:///<MOUNT POINT>/<PATH>.

Mount points in the Puppet URI

Puppet URIs look like this: puppet://<SERVER>/<MOUNT POINT>/<PATH>.

The <SERVER> is optional, so it common practice to use puppet:/// URIs with three slashes. Usually, there is no reason to specify the server. For Puppet agent, <SERVER> defaults to the value of the server setting. For Puppet apply, <SERVER> defaults to a special mock server with a modules mount point.

<MOUNT POINT> is a unique identifier for some collection of files. There are different kinds of mount points:

  • Custom mount points correspond to a directory that you specify.

  • The task mount point works in a similar way to the modules mount point but for files that live under the modules tasks directory, rather than the files directory.

  • The special modules mount point serves files from the files directory of every module. It behaves as if someone had copied the files directory from every module into one big directory, renaming each of them with the name of their module. For example, the files in apache/files/... are available at puppet:///modules/apache/....

  • The special plugins mount point serves files from the lib directory of every module. It behaves as if someone had copied the contents of every lib directory into one big directory, with no additional namespacing. Puppet agent uses this mount point when syncing plugins before a run, but there’s no reason to use it in a file resource.

  • The special pluginfacts mount point serves files from the facts.d directory of every module to support external facts. It behaves like the plugins mount point, but with a different source directory.

  • The special locales mount point serves files from the locales directory of every module to support automatic downloading of module translations to agents. It also behaves like the plugins mount point, and also has a different source directory.

<PATH> is the remainder of the path to the file, starting from the directory (or imaginary directory) that corresponds to the mount point.

Creating a new mount point in fileserver.conf

The fileserver.conf file uses the following syntax to define mount points:
[<NAME OF MOUNT POINT>]
    path <PATH TO DIRECTORY>
           allow *
In the following example, a file at /etc/puppetlabs/puppet/installer_files/oracle.pkg would be available in manifests as puppet:///installer_files/oracle.pkg:
[installer_files]
    path /etc/puppetlabs/puppet/installer_files
    allow

Make sure that the puppet user has the right permissions to access that directory and its contents.

Always include the allow * line, because the default behavior is to deny all access. To change access to a custom mount point, update the rules in auth.conf, as described below. Putting authorization rules in fileserver.conf is deprecated.

CAUTION: Always restrict write access to mounted directories. The file server follows any symlinks in a file server mount, including links to files that agent nodes cannot access (such as SSL keys). When following symlinks, the file server can access any files readable by Puppet Server’s user account.

Controlling access to a custom mount point in auth.conf

By default, any node with a valid certificate can access the files in your new mount point. If a node can fetch a catalog, it can fetch files. If the node can’t fetch a catalog, it can’t fetch files. This is the same behavior as the special modules and plugins mount points. If necessary, you can restrict access to a custom mount point in auth.conf.

Both the location of auth.conf, and the process for editing auth.conf differ depending on whether you're using the new Puppet Server authentication configuration, or the legacy configuration.

If you’re using the new configuration, and you've disabled the legacy auth.conf file by setting jruby-puppet.use-legacy-auth-conf: false, you can add a rule to Puppet Server’s HOCON-format auth.conf file, located at /etc/puppetlabs/puppetserver/conf.d/auth.conf.

Your new auth rule must meet the following requirements:

  • It must match requests to all four of these prefixes:

    • /puppet/v3/file_metadata/<MOUNT POINT>

    • /puppet/v3/file_metadatas/<MOUNT POINT>

    • /puppet/v3/file_content/<MOUNT POINT>

    • /puppet/v3/file_contents/<MOUNT POINT>

  • Its sort-order must be lower than 500, so that it overrides the default rule for the file server.

For example:
{
    # Allow limited access to files in /etc/puppetlabs/puppet/installer_files:
    match-request: {
        path: "^/puppet/v3/file_(content|metadata)s?/installer_files"
        type: regex
    }
    allow: "*.dev.example.com"
    sort-order: 400
    name: "dev.example.com large installer files"
},

If you haven’t disabled the legacy auth.conf file, add a rule to /etc/puppetlabs/puppet/auth.conf.

Your new auth rule must meet the following requirements:

  • It must match requests to all four of these prefixes:

    • /puppet/v3/file_metadata/<MOUNT POINT>

    • /puppet/v3/file_metadatas/<MOUNT POINT>

    • /puppet/v3/file_content/<MOUNT POINT>

    • /puppet/v3/file_contents/<MOUNT POINT>

  • It must be located earlier in the auth.conf file than the default /puppet/v3/file rule.

For example:
# Allow limited access to files in /etc/puppetlabs/puppet/installer_files:
path ~ ^/file_(metadata|content)s?/installer_files/
auth yes
allow *.dev.example.com
           allow_ip 192.168.100.0/24

Related topics: Module fundamentals, fileserver.conf: Custom fileserver mount points, Puppet Server configuration files: puppetserver.conf, Puppet Server configuration files: auth.conf.