Language: Handling File Paths on Windows
Included in Puppet Enterprise 3.3. A newer version is available; see the version menu above for details.
Several resource types (including
package) take file paths as values for various attributes.
When writing Puppet manifests to manage Windows systems, there are two extra issues to take into account when writing file paths: directory separators, and filesystem redirection.
This version of Puppet always runs as a 32-bit process on Windows systems. On 64-bit versions of Windows, this means Puppet is affected by the File System Redirector. This can be an issue when trying to manage files in the system directory, like IIS configuration files.
When a Puppet resource accesses any files in the
%windir%\system32 directory, Windows will silently change the path to point to
To prevent redirection, you should use the
sysnative alias in place of
system32 whenever you need to access files in the system directory.
C:\Windows\sysnative\inetsrv\config\application Host.config will always point to
C:\Windows\system32\inetsrv\config\application Host.config, and never to
Note: 64-bit Windows Server 2003 requires hotfix KB942589 to use the sysnative alias.
Windows traditionally uses the backslash (
\) to separate directories in file paths. (For example,
C:\Program Files\PuppetLabs.) However, the Puppet language also uses the backslash (
\) as an escape character in quoted strings. This can make it awkward to write literal backslashes.
To complicate things further: the Windows file system APIs will accept both the backslash (
\) and forward-slash (
/) in file paths, but some Windows programs still only accept backslashes.
- Using forward-slashes in paths is easier, but sometimes you must use backslashes.
- When you use backslashes, you must pay extra attention to keep them from being suppressed by Puppet’s string quoting.
The following guidelines will help you use backslashes safely in Windows file paths with Puppet.
When to Use Each Kind of Slash
If Puppet itself is interpreting the file path, forward slashes are generally okay. If the file path is being passed directly to a Windows program, backslashes may be mandatory. If the file path is meant for the puppet master, forward-slashes may be mandatory.
The most notable instances of each kind of path are listed below.
Forward slashes MUST be used in:
- Template paths (e.g.
Forward- and Backslashes Both Allowed
You can choose which kind of slash to use in:
pathattribute or title of a
- Local paths in a
execresource, unless the executable requires backslashes, e.g. cmd.exe
Backslashes MUST be used in:
sourceattribute of a
- Any file paths included in the
- Any file paths included in the
Using Backslashes in Double-Quoted Strings
Puppet supports two kinds of string quoting. See the reference section about strings for full details.
Strings surrounded by double quotes (
") allow many escape sequences that begin with backslashes. (For example,
\n for a newline.) Any lone backslashes will be interpreted as part of an escape sequence.
When using backslashes in a double-quoted string, you must always use two backslashes for each literal backslash. There are no exceptions and no special cases.
Using Backslashes in Single-Quoted Strings
Strings surrounded by single quotes
'like this' do not interpolate variables. Only one escape sequence is permitted:
\' (a literal single quote). Line breaks within the string are interpreted as literal line breaks.
Any backslash (
\) not followed by a single quote is interpreted as a literal backslash. This means there’s no way to end a single-quoted string with a backslash; if you need to refer to a string like
C:\Program Files(x86)\, you’ll have to use a double-quote string instead.
Note: This behavior is different when the
parsersetting is set to
future. In the future parser, lone backslashes are literal backslashes unless followed by a single quote or another backslash. That is:
- When a backslash occurs at the very end of a single-quoted string, a double backslash must be used instead of a single backslash. For example:
path => 'C:\Program Files(x86)\\'
- When a literal double backslash is intended, a quadruple backslash must be used.
Known Issues Prior to Puppet 3.0
In Puppet 2.7, there was one additional place where backslashes were not allowed: the
modulepath setting required forward-slashes. For example:
puppet apply --modulepath="Z:/path/to/my/modules" "Z:/path/to/my/site.pp"
This was fixed in Puppet 3.0 / Puppet Enterprise 3.0.