(maint) - Fix cut off summary for apt_key
[puppet-modules/puppetlabs-apt.git] / REFERENCE.md
1 # Reference
2 <!-- DO NOT EDIT: This document was generated by Puppet Strings -->
3
4 ## Table of Contents
5
6 **Classes**
7
8 _Public Classes_
9
10 * [`apt`](#apt): Main class, includes all other classes.
11 * [`apt::backports`](#aptbackports): Manages backports.
12
13 _Private Classes_
14
15 * `apt::params`: Provides defaults for the Apt module parameters.
16 * `apt::update`: Updates the list of available packages using apt-get update.
17
18 **Defined types**
19
20 * [`apt::conf`](#aptconf): Specifies a custom Apt configuration file.
21 * [`apt::key`](#aptkey): Manages the GPG keys that Apt uses to authenticate packages.
22 * [`apt::pin`](#aptpin): Manages Apt pins. Does not trigger an apt-get update run.
23 * [`apt::ppa`](#aptppa): Manages PPA repositories using `add-apt-repository`. Not supported on Debian.
24 * [`apt::setting`](#aptsetting): Manages Apt configuration files.
25 * [`apt::source`](#aptsource): Manages the Apt sources in /etc/apt/sources.list.d/.
26
27 **Resource types**
28
29 _Public Resource types_
30
31
32 _Private Resource types_
33
34 * `apt_key`: This type provides Puppet with the capabilities to manage GPG keys needed
35 by apt to perform package validation. Apt has it's own GPG keyring that can
36 be manipulated through the `apt-key` command.
37
38 **Tasks**
39
40 * [`init`](#init): Allows you to perform apt functions
41
42 ## Classes
43
44 ### apt
45
46 Main class, includes all other classes.
47
48 * **See also**
49 https://docs.puppetlabs.com/references/latest/function.html#createresources
50 for the create resource function
51
52 #### Parameters
53
54 The following parameters are available in the `apt` class.
55
56 ##### `provider`
57
58 Data type: `String`
59
60 Specifies the provider that should be used by apt::update.
61
62 Default value: $apt::params::provider
63
64 ##### `keyserver`
65
66 Data type: `String`
67
68 Specifies a keyserver to provide the GPG key. Valid options: a string containing a domain name or a full URL (http://, https://, or
69 hkp://).
70
71 Default value: $apt::params::keyserver
72
73 ##### `ppa_options`
74
75 Data type: `Optional[String]`
76
77 Supplies options to be passed to the `add-apt-repository` command.
78
79 Default value: $apt::params::ppa_options
80
81 ##### `ppa_package`
82
83 Data type: `Optional[String]`
84
85 Names the package that provides the `apt-add-repository` command.
86
87 Default value: $apt::params::ppa_package
88
89 ##### `backports`
90
91 Data type: `Optional[Hash]`
92
93 Specifies some of the default parameters used by apt::backports. Valid options: a hash made up from the following keys:
94
95 Options:
96
97 * **:location** `String`: See apt::backports for documentation.
98 * **:repos** `String`: See apt::backports for documentation.
99 * **:key** `String`: See apt::backports for documentation.
100
101 Default value: $apt::params::backports
102
103 ##### `confs`
104
105 Data type: `Hash`
106
107 Creates new `apt::conf` resources. Valid options: a hash to be passed to the create_resources function linked above.
108
109 Default value: $apt::params::confs
110
111 ##### `update`
112
113 Data type: `Hash`
114
115 Configures various update settings. Valid options: a hash made up from the following keys:
116
117 Options:
118
119 * **:frequency** `String`: Specifies how often to run `apt-get update`. If the exec resource `apt_update` is notified, `apt-get update` runs regardless of this value.
120 Valid options: 'always' (at every Puppet run); 'daily' (if the value of `apt_update_last_success` is less than current epoch time minus 86400);
121 'weekly' (if the value of `apt_update_last_success` is less than current epoch time minus 604800); and 'reluctantly' (only if the exec resource
122 `apt_update` is notified). Default: 'reluctantly'.
123 * **:loglevel** `Integer`: Specifies the log level of logs outputted to the console. Default: undef.
124 * **:timeout** `Integer`: Specifies how long to wait for the update to complete before canceling it. Valid options: an integer, in seconds. Default: undef.
125 * **:tries** `Integer`: Specifies how many times to retry the update after receiving a DNS or HTTP error. Default: undef.
126
127 Default value: $apt::params::update
128
129 ##### `purge`
130
131 Data type: `Hash`
132
133 Specifies whether to purge any existing settings that aren't managed by Puppet. Valid options: a hash made up from the following keys:
134
135 Options:
136
137 * **:sources.list** `Boolean`: Specifies whether to purge any unmanaged entries from sources.list. Default false.
138 * **:sources.list.d** `Boolean`: Specifies whether to purge any unmanaged entries from sources.list.d. Default false.
139 * **:preferences** `Boolean`: Specifies whether to purge any unmanaged entries from preferences. Default false.
140 * **:preferences.d.** `Boolean`: Specifies whether to purge any unmanaged entries from preferences.d. Default false.
141
142 Default value: $apt::params::purge
143
144 ##### `proxy`
145
146 Data type: `Apt::Proxy`
147
148 Configures Apt to connect to a proxy server. Valid options: a hash matching the locally defined type apt::proxy.
149
150 Default value: $apt::params::proxy
151
152 ##### `sources`
153
154 Data type: `Hash`
155
156 Creates new `apt::source` resources. Valid options: a hash to be passed to the create_resources function linked above.
157
158 Default value: $apt::params::sources
159
160 ##### `keys`
161
162 Data type: `Hash`
163
164 Creates new `apt::key` resources. Valid options: a hash to be passed to the create_resources function linked above.
165
166 Default value: $apt::params::keys
167
168 ##### `ppas`
169
170 Data type: `Hash`
171
172 Creates new `apt::ppa` resources. Valid options: a hash to be passed to the create_resources function linked above.
173
174 Default value: $apt::params::ppas
175
176 ##### `pins`
177
178 Data type: `Hash`
179
180 Creates new `apt::pin` resources. Valid options: a hash to be passed to the create_resources function linked above.
181
182 Default value: $apt::params::pins
183
184 ##### `settings`
185
186 Data type: `Hash`
187
188 Creates new `apt::setting` resources. Valid options: a hash to be passed to the create_resources function linked above.
189
190 Default value: $apt::params::settings
191
192 ##### `auth_conf_entries`
193
194 Data type: `Array[Apt::Auth_conf_entry]`
195
196 An optional array of login configuration settings (hashes) that are recorded in the file /etc/apt/auth.conf. This file has a netrc-like
197 format (similar to what curl uses) and contains the login configuration for APT sources and proxies that require authentication. See
198 https://manpages.debian.org/testing/apt/apt_auth.conf.5.en.html for details. If specified each hash must contain the keys machine, login and
199 password and no others.
200
201 Default value: $apt::params::auth_conf_entries
202
203 ##### `root`
204
205 Data type: `String`
206
207 Specifies root directory of Apt executable.
208
209 Default value: $apt::params::root
210
211 ##### `sources_list`
212
213 Data type: `String`
214
215 Specifies the path of the sources_list file to use.
216
217 Default value: $apt::params::sources_list
218
219 ##### `sources_list_d`
220
221 Data type: `String`
222
223 Specifies the path of the sources_list.d file to use.
224
225 Default value: $apt::params::sources_list_d
226
227 ##### `conf_d`
228
229 Data type: `String`
230
231 Specifies the path of the conf.d file to use.
232
233 Default value: $apt::params::conf_d
234
235 ##### `preferences`
236
237 Data type: `String`
238
239 Specifies the path of the preferences file to use.
240
241 Default value: $apt::params::preferences
242
243 ##### `preferences_d`
244
245 Data type: `String`
246
247 Specifies the path of the preferences.d file to use.
248
249 Default value: $apt::params::preferences_d
250
251 ##### `config_files`
252
253 Data type: `Hash`
254
255 A hash made up of the various configuration files used by Apt.
256
257 Default value: $apt::params::config_files
258
259 ##### `update_defaults`
260
261 Data type: `Hash`
262
263
264
265 Default value: $apt::params::update_defaults
266
267 ##### `purge_defaults`
268
269 Data type: `Hash`
270
271
272
273 Default value: $apt::params::purge_defaults
274
275 ##### `proxy_defaults`
276
277 Data type: `Hash`
278
279
280
281 Default value: $apt::params::proxy_defaults
282
283 ##### `include_defaults`
284
285 Data type: `Hash`
286
287
288
289 Default value: $apt::params::include_defaults
290
291 ##### `source_key_defaults`
292
293 Data type: `Hash`
294
295
296
297 Default value: $apt::params::source_key_defaults
298
299 ### apt::backports
300
301 Manages backports.
302
303 #### Examples
304
305 ##### Set up a backport for linuxmint qiana
306
307 ```puppet
308 apt::backports { 'qiana':
309   location => 'http://us.archive.ubuntu.com/ubuntu',
310   release  => 'trusty-backports',
311   repos    => 'main universe multiverse restricted',
312   key      => {
313     id     => '630239CC130E1A7FD81A27B140976EAF437D05B5',
314     server => 'hkps.pool.sks-keyservers.net',
315   },
316 }
317 ```
318
319 #### Parameters
320
321 The following parameters are available in the `apt::backports` class.
322
323 ##### `location`
324
325 Data type: `Optional[String]`
326
327 Specifies an Apt repository containing the backports to manage. Valid options: a string containing a URL. Default value for Debian and
328 Ubuntu varies:
329
330 - Debian: 'http://deb.debian.org/debian'
331
332 - Ubuntu: 'http://archive.ubuntu.com/ubuntu'
333
334 Default value: `undef`
335
336 ##### `release`
337
338 Data type: `Optional[String]`
339
340 Specifies a distribution of the Apt repository containing the backports to manage. Used in populating the `source.list` configuration file.
341 Default: on Debian and Ubuntu, '${lsbdistcodename}-backports'. We recommend keeping this default, except on other operating
342 systems.
343
344 Default value: `undef`
345
346 ##### `repos`
347
348 Data type: `Optional[String]`
349
350 Specifies a component of the Apt repository containing the backports to manage. Used in populating the `source.list` configuration file.
351 Default value for Debian and Ubuntu varies:
352
353 - Debian: 'main contrib non-free'
354
355 - Ubuntu: 'main universe multiverse restricted'
356
357 Default value: `undef`
358
359 ##### `key`
360
361 Data type: `Optional[Variant[String, Hash]]`
362
363 Specifies a key to authenticate the backports. Valid options: a string to be passed to the id parameter of the apt::key defined type, or a
364 hash of parameter => value pairs to be passed to apt::key's id, server, content, source, and/or options parameters. Default value
365 for Debian and Ubuntu varies:
366
367 - Debian: 'A1BD8E9D78F7FE5C3E65D8AF8B48AD6246925553'
368
369 - Ubuntu: '630239CC130E1A7FD81A27B140976EAF437D05B5'
370
371 Default value: `undef`
372
373 ##### `pin`
374
375 Data type: `Optional[Variant[Integer, String, Hash]]`
376
377 Specifies a pin priority for the backports. Valid options: a number or string to be passed to the `id` parameter of the `apt::pin` defined
378 type, or a hash of `parameter => value` pairs to be passed to `apt::pin`'s corresponding parameters.
379
380 Default value: 200
381
382 ## Defined types
383
384 ### apt::conf
385
386 Specifies a custom Apt configuration file.
387
388 #### Parameters
389
390 The following parameters are available in the `apt::conf` defined type.
391
392 ##### `content`
393
394 Data type: `Optional[String]`
395
396 Required unless `ensure` is set to 'absent'. Directly supplies content for the configuration file.
397
398 Default value: `undef`
399
400 ##### `ensure`
401
402 Data type: `Enum['present', 'absent']`
403
404 Specifies whether the configuration file should exist. Valid options: 'present' and 'absent'.
405
406 Default value: present
407
408 ##### `priority`
409
410 Data type: `Variant[String, Integer]`
411
412 Determines the order in which Apt processes the configuration file. Files with lower priority numbers are loaded first.
413 Valid options: a string containing an integer or an integer.
414
415 Default value: 50
416
417 ##### `notify_update`
418
419 Data type: `Optional[Boolean]`
420
421 Specifies whether to trigger an `apt-get update` run.
422
423 Default value: `undef`
424
425 ### apt::key
426
427 Manages the GPG keys that Apt uses to authenticate packages.
428
429 * **Note** The apt::key defined type makes use of the apt_key type, but includes extra functionality to help prevent duplicate keys.
430
431 #### Examples
432
433 ##### Declare Apt key for apt.puppetlabs.com source
434
435 ```puppet
436 apt::key { 'puppetlabs':
437   id      => '6F6B15509CF8E59E6E469F327F438280EF8D349F',
438   server  => 'hkps.pool.sks-keyservers.net',
439   options => 'http-proxy="http://proxyuser:proxypass@example.org:3128"',
440 }
441 ```
442
443 #### Parameters
444
445 The following parameters are available in the `apt::key` defined type.
446
447 ##### `id`
448
449 Data type: `Pattern[/\A(0x)?[0-9a-fA-F]{8}\Z/, /\A(0x)?[0-9a-fA-F]{16}\Z/, /\A(0x)?[0-9a-fA-F]{40}\Z/]`
450
451 Specifies a GPG key to authenticate Apt package signatures. Valid options: a string containing a key ID (8 or 16 hexadecimal
452 characters, optionally prefixed with "0x") or a full key fingerprint (40 hexadecimal characters).
453
454 Default value: $title
455
456 ##### `ensure`
457
458 Data type: `Enum['present', 'absent']`
459
460 Specifies whether the key should exist. Valid options: 'present' and 'absent'.
461
462 Default value: present
463
464 ##### `content`
465
466 Data type: `Optional[String]`
467
468 Supplies the entire GPG key. Useful in case the key can't be fetched from a remote location and using a file resource is inconvenient.
469
470 Default value: `undef`
471
472 ##### `source`
473
474 Data type: `Optional[Pattern[/\Ahttps?:\/\//, /\Aftp:\/\//, /\A\/\w+/]]`
475
476 Specifies the location of an existing GPG key file to copy. Valid options: a string containing a URL (ftp://, http://, or https://) or
477 an absolute path.
478
479 Default value: `undef`
480
481 ##### `server`
482
483 Data type: `Pattern[/\A((hkp|http|https):\/\/)?([a-z\d])([a-z\d-]{0,61}\.)+[a-z\d]+(:\d{2,5})?$/]`
484
485 Specifies a keyserver to provide the GPG key. Valid options: a string containing a domain name or a full URL (http://, https://, or
486 hkp://).
487
488 Default value: $::apt::keyserver
489
490 ##### `options`
491
492 Data type: `Optional[String]`
493
494 Passes additional options to `apt-key adv --keyserver-options`.
495
496 Default value: `undef`
497
498 ### apt::pin
499
500 Manages Apt pins. Does not trigger an apt-get update run.
501
502 * **See also**
503 http://linux.die.net/man/5/apt_preferences
504 for context on these parameters
505
506 #### Parameters
507
508 The following parameters are available in the `apt::pin` defined type.
509
510 ##### `ensure`
511
512 Data type: `Optional[Enum['file', 'present', 'absent']]`
513
514 Specifies whether the pin should exist. Valid options: 'file', 'present', and 'absent'.
515
516 Default value: present
517
518 ##### `explanation`
519
520 Data type: `Optional[String]`
521
522 Supplies a comment to explain the pin. Default: "${caller_module_name}: ${name}".
523
524 Default value: `undef`
525
526 ##### `order`
527
528 Data type: `Variant[Integer]`
529
530 Determines the order in which Apt processes the pin file. Files with lower order numbers are loaded first.
531
532 Default value: 50
533
534 ##### `packages`
535
536 Data type: `Variant[String, Array]`
537
538 Specifies which package(s) to pin.
539
540 Default value: '*'
541
542 ##### `priority`
543
544 Data type: `Variant[Numeric, String]`
545
546 Sets the priority of the package. If multiple versions of a given package are available, `apt-get` installs the one with the highest
547 priority number (subject to dependency constraints). Valid options: an integer.
548
549 Default value: 0
550
551 ##### `release`
552
553 Data type: `Optional[String]`
554
555 Tells APT to prefer packages that support the specified release. Typical values include 'stable', 'testing', and 'unstable'.
556
557 Default value: ''
558
559 ##### `release_version`
560
561 Data type: `Optional[String]`
562
563 Tells APT to prefer packages that support the specified operating system release version (such as Debian release version 7).
564
565 Default value: ''
566
567 ##### `component`
568
569 Data type: `Optional[String]`
570
571 Names the licensing component associated with the packages in the directory tree of the Release file.
572
573 Default value: ''
574
575 ##### `originator`
576
577 Data type: `Optional[String]`
578
579 Names the originator of the packages in the directory tree of the Release file.
580
581 Default value: ''
582
583 ##### `label`
584
585 Data type: `Optional[String]`
586
587 Names the label of the packages in the directory tree of the Release file.
588
589 Default value: ''
590
591 ##### `origin`
592
593 Data type: `Optional[String]`
594
595
596
597 Default value: ''
598
599 ##### `version`
600
601 Data type: `Optional[String]`
602
603
604
605 Default value: ''
606
607 ##### `codename`
608
609 Data type: `Optional[String]`
610
611
612
613 Default value: ''
614
615 ### apt::ppa
616
617 Manages PPA repositories using `add-apt-repository`. Not supported on Debian.
618
619 #### Examples
620
621 ##### Example declaration of an Apt PPA
622
623 ```puppet
624 apt::ppa{ 'ppa:openstack-ppa/bleeding-edge': }
625 ```
626
627 #### Parameters
628
629 The following parameters are available in the `apt::ppa` defined type.
630
631 ##### `ensure`
632
633 Data type: `String`
634
635 Specifies whether the PPA should exist. Valid options: 'present' and 'absent'.
636
637 Default value: 'present'
638
639 ##### `options`
640
641 Data type: `Optional[String]`
642
643 Supplies options to be passed to the `add-apt-repository` command. Default: '-y'.
644
645 Default value: $::apt::ppa_options
646
647 ##### `release`
648
649 Data type: `Optional[String]`
650
651 Optional if lsb-release is installed (unless you're using a different release than indicated by lsb-release, e.g., Linux Mint).
652 Specifies the operating system of your node. Valid options: a string containing a valid LSB distribution codename.
653
654 Default value: $facts['lsbdistcodename']
655
656 ##### `package_name`
657
658 Data type: `Optional[String]`
659
660 Names the package that provides the `apt-add-repository` command. Default: 'software-properties-common'.
661
662 Default value: $::apt::ppa_package
663
664 ##### `package_manage`
665
666 Data type: `Boolean`
667
668 Specifies whether Puppet should manage the package that provides `apt-add-repository`.
669
670 Default value: `false`
671
672 ### apt::setting
673
674 Manages Apt configuration files.
675
676 * **See also**
677 https://docs.puppetlabs.com/references/latest/type.html#file-attributes
678 for more information on source and content parameters
679
680 #### Parameters
681
682 The following parameters are available in the `apt::setting` defined type.
683
684 ##### `priority`
685
686 Data type: `Variant[String, Integer, Array]`
687
688 Determines the order in which Apt processes the configuration file. Files with higher priority numbers are loaded first.
689
690 Default value: 50
691
692 ##### `ensure`
693
694 Data type: `Optional[Enum['file', 'present', 'absent']]`
695
696 Specifies whether the file should exist. Valid options: 'present', 'absent', and 'file'.
697
698 Default value: file
699
700 ##### `source`
701
702 Data type: `Optional[String]`
703
704 Required, unless `content` is set. Specifies a source file to supply the content of the configuration file. Cannot be used in combination
705 with `content`. Valid options: see link above for Puppet's native file type source attribute.
706
707 Default value: `undef`
708
709 ##### `content`
710
711 Data type: `Optional[String]`
712
713 Required, unless `source` is set. Directly supplies content for the configuration file. Cannot be used in combination with `source`. Valid
714 options: see link above for Puppet's native file type content attribute.
715
716 Default value: `undef`
717
718 ##### `notify_update`
719
720 Data type: `Boolean`
721
722 Specifies whether to trigger an `apt-get update` run.
723
724 Default value: `true`
725
726 ### apt::source
727
728 Manages the Apt sources in /etc/apt/sources.list.d/.
729
730 #### Examples
731
732 ##### Install the puppetlabs apt source
733
734 ```puppet
735 apt::source { 'puppetlabs':
736   location => 'http://apt.puppetlabs.com',
737   repos    => 'main',
738   key      => {
739     id     => '6F6B15509CF8E59E6E469F327F438280EF8D349F',
740     server => 'hkps.pool.sks-keyservers.net',
741   },
742 }
743 ```
744
745 #### Parameters
746
747 The following parameters are available in the `apt::source` defined type.
748
749 ##### `location`
750
751 Data type: `Optional[String]`
752
753 Required, unless ensure is set to 'absent'. Specifies an Apt repository. Valid options: a string containing a repository URL.
754
755 Default value: `undef`
756
757 ##### `comment`
758
759 Data type: `String`
760
761 Supplies a comment for adding to the Apt source file.
762
763 Default value: $name
764
765 ##### `ensure`
766
767 Data type: `String`
768
769 Specifies whether the Apt source file should exist. Valid options: 'present' and 'absent'.
770
771 Default value: present
772
773 ##### `release`
774
775 Data type: `Optional[String]`
776
777 Specifies a distribution of the Apt repository.
778
779 Default value: `undef`
780
781 ##### `repos`
782
783 Data type: `String`
784
785 Specifies a component of the Apt repository.
786
787 Default value: 'main'
788
789 ##### `include`
790
791 Data type: `Optional[Variant[Hash]]`
792
793 Configures include options. Valid options: a hash of available keys.
794
795 Options:
796
797 * **:deb** `Boolean`: Specifies whether to request the distribution's compiled binaries. Default true.
798 * **:src** `Boolean`: Specifies whether to request the distribution's uncompiled source code. Default false.
799
800 Default value: {}
801
802 ##### `key`
803
804 Data type: `Optional[Variant[String, Hash]]`
805
806 Creates a declaration of the apt::key defined type. Valid options: a string to be passed to the `id` parameter of the `apt::key`
807 defined type, or a hash of `parameter => value` pairs to be passed to `apt::key`'s `id`, `server`, `content`, `source`, and/or
808 `options` parameters.
809
810 Default value: `undef`
811
812 ##### `pin`
813
814 Data type: `Optional[Variant[Hash, Numeric, String]]`
815
816 Creates a declaration of the apt::pin defined type. Valid options: a number or string to be passed to the `id` parameter of the
817 `apt::pin` defined type, or a hash of `parameter => value` pairs to be passed to `apt::pin`'s corresponding parameters.
818
819 Default value: `undef`
820
821 ##### `architecture`
822
823 Data type: `Optional[String]`
824
825 Tells Apt to only download information for specified architectures. Valid options: a string containing one or more architecture names,
826 separated by commas (e.g., 'i386' or 'i386,alpha,powerpc'). Default: undef (if unspecified, Apt downloads information for all architectures
827 defined in the Apt::Architectures option).
828
829 Default value: `undef`
830
831 ##### `allow_unsigned`
832
833 Data type: `Boolean`
834
835 Specifies whether to authenticate packages from this release, even if the Release file is not signed or the signature can't be checked.
836
837 Default value: `false`
838
839 ##### `notify_update`
840
841 Data type: `Boolean`
842
843 Specifies whether to trigger an `apt-get update` run.
844
845 Default value: `true`
846
847 ## Resource types
848
849 ## Tasks
850
851 ### init
852
853 Allows you to perform apt functions
854
855 **Supports noop?** false
856
857 #### Parameters
858
859 ##### `action`
860
861 Data type: `Enum[update, upgrade]`
862
863 Action to perform 
864