1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
|
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 [the docs on configuring mount points](https://puppet.com/docs/puppet/latest/file_serving.html).
* `modules/<MODULE>` --- a semi-magical mount point which allows access to the `files` subdirectory of `<MODULE>` --- see [the docs on file serving](https://puppet.com/docs/puppet/latest/file_serving.html).
* `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 [the docs on file serving](https://puppet.com/docs/puppet/latest/file_serving.html).
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
### Supported HTTP Methods
GET
### Supported Response Formats
`application/json`
### Parameters
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.
* `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.
### Example Response
#### File metadata found for a file
GET /puppet/v3/file_metadata/modules/example/just_a_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/just_a_file.txt",
"relative_path": null,
"type": "file"
}
#### File metadata found for a directory
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"
}
#### File metadata found for a link ignoring source permissions
GET /puppet/v3/file_metadata/modules/example/link_to_file.txt?environment=env&source_permissions=ignore
HTTP/1.1 200 OK
Content-Type: application/json
{
"checksum": {
"type": "md5",
"value": "{md5}d0a10f45491acc8743bc5a82b228f89e"
},
"destination": "/etc/puppetlabs/code/modules/example/files/just_a_file.txt",
"group": 20,
"links": "manage",
"mode": 420,
"owner": 501,
"path": "/etc/puppetlabs/code/modules/example/files/link_to_file.txt",
"relative_path": null,
"type": "link"
}
#### File not found
GET /puppet/v3/file_metadata/modules/example/does_not_exist?environment=env
HTTP/1.1 404 Not Found
Not Found: Could not find file_metadata modules/example/does_not_exist
Search
------
Get a list of metadata for multiple files
GET /puppet/v3/file_metadatas/foo.txt?environment=env
### Supported HTTP Methods
GET
### Supported Response Formats
`application/json`
### Parameters
* `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 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.
* `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.
### Example Response
#### Basic search
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",
"relative_path": "just_a_file.txt",
"type": "file"
},
{
"checksum": {
"type": "md5",
"value": "{md5}d0a10f45491acc8743bc5a82b228f89e"
},
"destination": "/etc/puppetlabs/code/modules/example/files/just_a_file.txt",
"group": 20,
"links": "manage",
"mode": 493,
"owner": 501,
"path": "/etc/puppetlabs/code/modules/example/files",
"relative_path": "link_to_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",
"relative_path": "subdirectory/another_file.txt",
"type": "file"
}
]
#### Search ignoring 'sub*' and links = manage
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",
"relative_path": "just_a_file.txt",
"type": "file"
},
{
"checksum": {
"type": "md5",
"value": "{md5}d0a10f45491acc8743bc5a82b228f89e"
},
"destination": "/etc/puppetlabs/code/modules/example/files/just_a_file.txt",
"group": 20,
"links": "manage",
"mode": 493,
"owner": 501,
"path": "/etc/puppetlabs/code/modules/example/files",
"relative_path": "link_to_file.txt",
"type": "link"
}
]
#### Search ignoring "sub*" and links = follow
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 "link_to_file.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",
"relative_path": "just_a_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",
"relative_path": "link_to_file.txt",
"type": "file"
}
]
~~~
Schema
------
The file metadata response body conforms to
[the `file_metadata` schema.](../schemas/file_metadata.json)
Sample Module
-------------
The examples above use this (faux) module:
/etc/puppetlabs/code/modules/example/
files/
just_a_file.txt
link_to_file.txt -> /etc/puppetlabs/code/modules/example/files/just_a_file.txt
subdirectory/
another_file.txt
|
