Project: Puppet (Provisioning / Automation & Configuration)
File: http_file_metadata.md

File Metadata ============= The `file_metadata` endpoint returns select metadata for a single file or many files. There are find and search variants of the endpoint; the search variant has a trailing 's' so is actually `file_metadatas`. Although the term 'file' is used generically in the endpoint name and documentation, each returned item can be one of the following three types: File Directory Symbolic link The endpoint path includes a `:mount` which can be one of the following types: Custom file serving mounts as specified in fileserver.conf see . `modules/<MODULE>` a semi-magical mount point which allows access to the `files` subdirectory of `<MODULE>` see . `plugins` a highly magical mount point which merges the `lib` directory of every module together. Used for syncing plugins; not intended for general consumption. Per-module sub-paths can not be specified. `pluginfacts` a highly magical mount point which merges the `facts.d` directory of every module together. Used for syncing external facts; not intended for general consumption. Per-module sub-paths can not be specified. `tasks/<MODULE>` a semi-magical mount point which allows access to files in the `tasks` subdirectory of `<MODULE>` see the . Note: JSON responses in the examples below are pretty-printed for readability. Find Get file metadata for a single file GET /puppet/v3/file_metadata/:mount/path/to/file?environment=:environment GET `application/json` Optional parameters to GET: `links` -- either `manage` (default) or `follow`. See examples in Search below. `checksum_type` -- the checksum type to calculate the checksum value for the result metadata; one of `md5` (default), `md5lite`, `sha256`, `sha256lite`, `mtime`, `ctime`, and `none`. `source_permissions` -- whether (and how) Puppet should copy owner, group, and mode permissions; one of `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. `usewhencreating` will only apply the owner, group, and mode from the source when creating a file; existing files will not have their permissions overwritten. GET /puppet/v3/filemetadata/modules/example/justa_file.txt?environment=env HTTP/1.1 200 OK Content-Type: application/json { "checksum": { "type": "md5", "value": "{md5}d0a10f45491acc8743bc5a82b228f89e" }, "destination": null, "group": 20, "links": "manage", "mode": 420, "owner": 501, "path": "/etc/puppetlabs/code/modules/example/files/justafile.txt", "relative_path": null, "type": "file" } GET /puppet/v3/file_metadata/modules/example/subdirectory?environment=env HTTP/1.1 200 OK Content-Type: application/json { "checksum": { "type": "ctime", "value": "{ctime}2013-10-01 13:16:10 -0700" }, "destination": null, "group": 20, "links": "manage", "mode": 493, "owner": 501, "path": "/etc/puppetlabs/code/modules/example/files/subdirectory", "relative_path": null, "type": "directory" } GET /puppet/v3/filemetadata/modules/example/linktofile.txt?environment=env&sourcepermissions=ignore HTTP/1.1 200 OK Content-Type: application/json { "checksum": { "type": "md5", "value": "{md5}d0a10f45491acc8743bc5a82b228f89e" }, "destination": "/etc/puppetlabs/code/modules/example/files/justafile.txt", "group": 20, "links": "manage", "mode": 420, "owner": 501, "path": "/etc/puppetlabs/code/modules/example/files/linktofile.txt", "relative_path": null, "type": "link" } GET /puppet/v3/filemetadata/modules/example/doesnot_exist?environment=env HTTP/1.1 404 Not Found Not Found: Could not find filemetadata modules/example/doesnot_exist Search Get a list of metadata for multiple files GET /puppet/v3/file_metadatas/foo.txt?environment=env GET `application/json` `recurse` -- should always be set to `yes`; unfortunately the default is `no`, which causes a search to behave like a find operation. `ignore` -- file or directory regex to ignore; can be repeated. `links` -- either `manage` (default) or `follow`. See examples

`checksum_type` -- the checksum type to calculate the checksum value for the result metadata; one of `md5` (default), `md5lite`, `sha256`, `sha256lite`, `mtime`, `ctime`, and `none`. `source_permissions` -- whether (and how) Puppet should copy owner, group, and mode permissions; one of `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. `usewhencreating` will only apply the owner, group, and mode from the source when creating a file; existing files will not have their permissions overwritten. GET /puppet/v3/file_metadatas/modules/example?environment=env&recurse=yes HTTP 200 OK Content-Type: application/json [ { "checksum": { "type": "ctime", "value": "{ctime}2013-10-01 13:15:59 -0700" }, "destination": null, "group": 20, "links": "manage", "mode": 493, "owner": 501, "path": "/etc/puppetlabs/code/modules/example/files", "relative_path": ".", "type": "directory" }, { "checksum": { "type": "md5", "value": "{md5}d0a10f45491acc8743bc5a82b228f89e" }, "destination": null, "group": 20, "links": "manage", "mode": 420, "owner": 501, "path": "/etc/puppetlabs/code/modules/example/files", "relativepath": "justa_file.txt", "type": "file" }, { "checksum": { "type": "md5", "value": "{md5}d0a10f45491acc8743bc5a82b228f89e" }, "destination": "/etc/puppetlabs/code/modules/example/files/justafile.txt", "group": 20, "links": "manage", "mode": 493, "owner": 501, "path": "/etc/puppetlabs/code/modules/example/files", "relativepath": "linkto_file.txt", "type": "link" }, { "checksum": { "type": "ctime", "value": "{ctime}2013-10-01 13:15:59 -0700" }, "destination": null, "group": 20, "links": "manage", "mode": 493, "owner": 501, "path": "/etc/puppetlabs/code/modules/example/files", "relative_path": "subdirectory", "type": "directory" }, { "checksum": { "type": "md5", "value": "{md5}d41d8cd98f00b204e9800998ecf8427e" }, "destination": null, "group": 20, "links": "manage", "mode": 420, "owner": 501, "path": "/etc/puppetlabs/code/modules/example/files", "relativepath": "subdirectory/anotherfile.txt", "type": "file" } ] GET /puppet/v3/file_metadatas/modules/example?environment=env&recurse=true&ignore=sub*&links=manage HTTP 200 OK Content-Type: application/json [ { "checksum": { "type": "ctime", "value": "{ctime}2013-10-01 13:15:59 -0700" }, "destination": null, "group": 20, "links": "manage", "mode": 493, "owner": 501, "path": "/etc/puppetlabs/code/modules/example/files", "relative_path": ".", "type": "directory" }, { "checksum": { "type": "md5", "value": "{md5}d0a10f45491acc8743bc5a82b228f89e" }, "destination": null, "group": 20, "links": "manage", "mode": 420, "owner": 501, "path": "/etc/puppetlabs/code/modules/example/files", "relativepath": "justa_file.txt", "type": "file" }, { "checksum": { "type": "md5", "value": "{md5}d0a10f45491acc8743bc5a82b228f89e" }, "destination": "/etc/puppetlabs/code/modules/example/files/justafile.txt", "group": 20, "links": "manage", "mode": 493, "owner": 501, "path": "/etc/puppetlabs/code/modules/example/files", "relativepath": "linkto_file.txt", "type": "link" } ] This example is identical to the above example, except for the links parameter. The resulting JSON, then, is identical to the above example, except for: the "links" field is set to "follow" rather than "manage" in all metadata objects in the "linktofile.txt" metadata: for "manage" the "destination" field is the link destination; for "follow", it's null for "manage" the "type" field is "link"; for "follow" it's "file" for "manage" the "mode", "owner" and "group" fields are the link's values; for "follow" the destination's values ~~~ GET /puppet/v3/file_metadatas/modules/example?environment=env&recurse=true&ignore=sub*&links=follow HTTP 200 OK Content-Type: application/json [ { "checksum": { "type": "ctime", "value": "{ctime}2013-10-01 13:15:59 -0700" }, "destination": null, "group": 20, "links": "follow", "mode": 493, "owner": 501, "path": "/etc/puppetlabs/code/modules/example/files", "relative_path": ".", "type": "directory" }, { "checksum": { "type": "md5", "value": "{md5}d0a10f45491acc8743bc5a82b228f89e" }, "destination": null, "group": 20, "links": "follow", "mode": 420, "owner": 501, "path": "/etc/puppetlabs/code/modules/example/files", "relativepath": "justa_file.txt", "type": "file" }, { "checksum": { "type": "md5", "value": "{md5}d0a10f45491acc8743bc5a82b228f89e" }, "destination": null, "group": 20, "links": "follow", "mode": 420, "owner": 501, "path": "/etc/puppetlabs/code/modules/example/files", "relativepath": "linkto_file.txt", "type": "file" } ] ~~~ Schema The file metadata response body conforms to Sample Module The examples above use this (faux) module: /etc/puppetlabs/code/modules/example/ files/ justafile.txt linktofile.txt -> /etc/puppetlabs/code/modules/example/files/justafile.txt subdirectory/ another_file.txt