forked from puppetlabs/puppet
/
defaults.rb
2038 lines (1941 loc) · 81.2 KB
/
defaults.rb
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
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
module Puppet
# counter used to bypass first hook execution for
# the *trusted_oid_mapping_file* option
@@trusted_oid_mapping_file_setting_counter = 0
def self.default_diffargs
if (Facter.value(:kernel) == "AIX" && Facter.value(:kernelmajversion) == "5300")
""
else
"-u"
end
end
############################################################################################
# NOTE: For information about the available values for the ":type" property of settings,
# see the docs for Settings.define_settings
############################################################################################
AS_DURATION = %q{This setting can be a time interval in seconds (30 or 30s), minutes (30m), hours (6h), days (2d), or years (5y).}
STORECONFIGS_ONLY = %q{This setting is only used by the ActiveRecord storeconfigs and inventory backends, which are deprecated.}
# This is defined first so that the facter implementation is replaced before other setting defaults are evaluated.
define_settings(:main,
:cfacter => {
:default => false,
:type => :boolean,
:desc => 'Whether or not to use the native facter (cfacter) implementation instead of the Ruby one (facter). Defaults to false.',
:hook => proc do |value|
return unless value
raise ArgumentError, 'facter has already evaluated facts.' if Facter.instance_variable_get(:@collection)
require 'puppet/facts'
raise ArgumentError, 'cfacter version 0.2.0 or later is not installed.' unless Puppet::Facts.replace_facter
end
}
)
define_settings(:main,
:confdir => {
:default => nil,
:type => :directory,
:desc => "The main Puppet configuration directory. The default for this setting
is calculated based on the user. If the process is running as root or
the user that Puppet is supposed to run as, it defaults to a system
directory, but if it's running as any other user, it defaults to being
in the user's home directory.",
},
:vardir => {
:default => nil,
:type => :directory,
:owner => "service",
:group => "service",
:desc => "Where Puppet stores dynamic and growing data. The default for this
setting is calculated specially, like `confdir`_.",
},
### NOTE: this setting is usually being set to a symbol value. We don't officially have a
### setting type for that yet, but we might want to consider creating one.
:name => {
:default => nil,
:desc => "The name of the application, if we are running as one. The
default is essentially $0 without the path or `.rb`.",
}
)
define_settings(:main,
:logdir => {
:default => nil,
:type => :directory,
:mode => 0750,
:owner => "service",
:group => "service",
:desc => "The directory in which to store log files",
},
:log_level => {
:default => 'notice',
:type => :enum,
:values => ["debug","info","notice","warning","err","alert","emerg","crit"],
:desc => "Default logging level for messages from Puppet. Allowed values are:
* debug
* info
* notice
* warning
* err
* alert
* emerg
* crit
",
},
:disable_warnings => {
:default => [],
:type => :array,
:desc => "A comma-separated list of warning types to suppress. If large numbers
of warnings are making Puppet's logs too large or difficult to use, you
can temporarily silence them with this setting.
If you are preparing to upgrade Puppet to a new major version, you
should re-enable all warnings for a while.
Valid values for this setting are:
* `deprecations` --- disables deprecation warnings.",
:hook => proc do |value|
values = munge(value)
valid = %w[deprecations]
invalid = values - (values & valid)
if not invalid.empty?
raise ArgumentError, "Cannot disable unrecognized warning types #{invalid.inspect}. Valid values are #{valid.inspect}."
end
end
}
)
define_settings(:main,
:priority => {
:default => nil,
:type => :priority,
:desc => "The scheduling priority of the process. Valid values are 'high',
'normal', 'low', or 'idle', which are mapped to platform-specific
values. The priority can also be specified as an integer value and
will be passed as is, e.g. -5. Puppet must be running as a privileged
user in order to increase scheduling priority.",
},
:trace => {
:default => false,
:type => :boolean,
:desc => "Whether to print stack traces on some errors",
},
:profile => {
:default => false,
:type => :boolean,
:desc => "Whether to enable experimental performance profiling",
},
:autoflush => {
:default => true,
:type => :boolean,
:desc => "Whether log files should always flush to disk.",
:hook => proc { |value| Log.autoflush = value }
},
:syslogfacility => {
:default => "daemon",
:desc => "What syslog facility to use when logging to syslog.
Syslog has a fixed list of valid facilities, and you must
choose one of those; you cannot just make one up."
},
:statedir => {
:default => "$vardir/state",
:type => :directory,
:mode => 01755,
:desc => "The directory where Puppet state is stored. Generally,
this directory can be removed without causing harm (although it
might result in spurious service restarts)."
},
:rundir => {
:default => nil,
:type => :directory,
:mode => 0755,
:owner => "service",
:group => "service",
:desc => "Where Puppet PID files are kept."
},
:genconfig => {
:default => false,
:type => :boolean,
:desc => "When true, causes Puppet applications to print an example config file
to stdout and exit. The example will include descriptions of each
setting, and the current (or default) value of each setting,
incorporating any settings overridden on the CLI (with the exception
of `genconfig` itself). This setting only makes sense when specified
on the command line as `--genconfig`.",
},
:genmanifest => {
:default => false,
:type => :boolean,
:desc => "Whether to just print a manifest to stdout and exit. Only makes
sense when specified on the command line as `--genmanifest`. Takes into account arguments specified
on the CLI.",
},
:configprint => {
:default => "",
:desc => "Print the value of a specific configuration setting. If the name of a
setting is provided for this, then the value is printed and puppet
exits. Comma-separate multiple values. For a list of all values,
specify 'all'.",
},
:color => {
:default => "ansi",
:type => :string,
:desc => "Whether to use colors when logging to the console. Valid values are
`ansi` (equivalent to `true`), `html`, and `false`, which produces no color.
Defaults to false on Windows, as its console does not support ansi colors.",
},
:mkusers => {
:default => false,
:type => :boolean,
:desc => "Whether to create the necessary user and group that puppet agent will run as.",
},
:manage_internal_file_permissions => {
:default => true,
:type => :boolean,
:desc => "Whether Puppet should manage the owner, group, and mode of files it uses internally",
},
:onetime => {
:default => false,
:type => :boolean,
:desc => "Perform one configuration run and exit, rather than spawning a long-running
daemon. This is useful for interactively running puppet agent, or
running puppet agent from cron.",
:short => 'o',
},
:path => {
:default => "none",
:desc => "The shell search path. Defaults to whatever is inherited
from the parent process.",
:call_hook => :on_define_and_write,
:hook => proc do |value|
ENV["PATH"] = "" if ENV["PATH"].nil?
ENV["PATH"] = value unless value == "none"
paths = ENV["PATH"].split(File::PATH_SEPARATOR)
Puppet::Util::Platform.default_paths.each do |path|
ENV["PATH"] += File::PATH_SEPARATOR + path unless paths.include?(path)
end
value
end
},
:libdir => {
:type => :directory,
:default => "$vardir/lib",
:desc => "An extra search path for Puppet. This is only useful
for those files that Puppet will load on demand, and is only
guaranteed to work for those cases. In fact, the autoload
mechanism is responsible for making sure this directory
is in Ruby's search path\n",
:call_hook => :on_initialize_and_write,
:hook => proc do |value|
$LOAD_PATH.delete(@oldlibdir) if defined?(@oldlibdir) and $LOAD_PATH.include?(@oldlibdir)
@oldlibdir = value
$LOAD_PATH << value
end
},
:ignoreimport => {
:default => false,
:type => :boolean,
:desc => "If true, allows the parser to continue without requiring
all files referenced with `import` statements to exist. This setting was primarily
designed for use with commit hooks for parse-checking.",
},
:environment => {
:default => "production",
:desc => "The environment Puppet is running in. For clients
(e.g., `puppet agent`) this determines the environment itself, which
is used to find modules and much more. For servers (i.e., `puppet master`)
this provides the default environment for nodes we know nothing about."
},
:environmentpath => {
:default => "",
:desc => "A search path for directory environments, as a list of directories
separated by the system path separator character. (The POSIX path separator
is ':', and the Windows path separator is ';'.)
This setting must have a value set to enable **directory environments.** The
recommended value is `$confdir/environments`. For more details, see
http://docs.puppetlabs.com/puppet/latest/reference/environments.html",
:type => :path,
},
:diff_args => {
:default => lambda { default_diffargs },
:desc => "Which arguments to pass to the diff command when printing differences between
files. The command to use can be chosen with the `diff` setting.",
},
:diff => {
:default => (Puppet.features.microsoft_windows? ? "" : "diff"),
:desc => "Which diff command to use when printing differences between files. This setting
has no default value on Windows, as standard `diff` is not available, but Puppet can use many
third-party diff tools.",
},
:show_diff => {
:type => :boolean,
:default => false,
:desc => "Whether to log and report a contextual diff when files are being replaced.
This causes partial file contents to pass through Puppet's normal
logging and reporting system, so this setting should be used with
caution if you are sending Puppet's reports to an insecure
destination. This feature currently requires the `diff/lcs` Ruby
library.",
},
:daemonize => {
:type => :boolean,
:default => (Puppet.features.microsoft_windows? ? false : true),
:desc => "Whether to send the process into the background. This defaults
to true on POSIX systems, and to false on Windows (where Puppet
currently cannot daemonize).",
:short => "D",
:hook => proc do |value|
if value and Puppet.features.microsoft_windows?
raise "Cannot daemonize on Windows"
end
end
},
:maximum_uid => {
:default => 4294967290,
:desc => "The maximum allowed UID. Some platforms use negative UIDs
but then ship with tools that do not know how to handle signed ints,
so the UIDs show up as huge numbers that can then not be fed back into
the system. This is a hackish way to fail in a slightly more useful
way when that happens.",
},
:route_file => {
:default => "$confdir/routes.yaml",
:desc => "The YAML file containing indirector route configuration.",
},
:node_terminus => {
:type => :terminus,
:default => "plain",
:desc => "Where to find information about nodes.",
},
:node_cache_terminus => {
:type => :terminus,
:default => nil,
:desc => "How to store cached nodes.
Valid values are (none), 'json', 'msgpack', 'yaml' or write only yaml ('write_only_yaml').
The master application defaults to 'write_only_yaml', all others to none.",
},
:data_binding_terminus => {
:type => :terminus,
:default => "hiera",
:desc => "Where to retrive information about data.",
},
:hiera_config => {
:default => "$confdir/hiera.yaml",
:desc => "The hiera configuration file. Puppet only reads this file on startup, so you must restart the puppet master every time you edit it.",
:type => :file,
},
:binder => {
:default => false,
:desc => "Turns the binding system on or off. This includes bindings in modules.
The binding system aggregates data from modules and other locations and makes them available for lookup.
The binding system is experimental and any or all of it may change.",
:type => :boolean,
},
:binder_config => {
:default => nil,
:desc => "The binder configuration file. Puppet reads this file on each request to configure the bindings system.
If set to nil (the default), a $confdir/binder_config.yaml is optionally loaded. If it does not exists, a default configuration
is used. If the setting :binding_config is specified, it must reference a valid and existing yaml file.",
:type => :file,
},
:catalog_terminus => {
:type => :terminus,
:default => "compiler",
:desc => "Where to get node catalogs. This is useful to change if, for instance,
you'd like to pre-compile catalogs and store them in memcached or some other easily-accessed store.",
},
:catalog_cache_terminus => {
:type => :terminus,
:default => nil,
:desc => "How to store cached catalogs. Valid values are 'json', 'msgpack' and 'yaml'. The agent application defaults to 'json'."
},
:facts_terminus => {
:default => 'facter',
:desc => "The node facts terminus.",
:call_hook => :on_initialize_and_write,
:hook => proc do |value|
require 'puppet/node/facts'
# Cache to YAML if we're uploading facts away
if %w[rest inventory_service].include? value.to_s
Puppet.info "configuring the YAML fact cache because a remote terminus is active"
Puppet::Node::Facts.indirection.cache_class = :yaml
end
end
},
:inventory_terminus => {
:type => :terminus,
:default => "$facts_terminus",
:desc => "Should usually be the same as the facts terminus",
},
:default_file_terminus => {
:type => :terminus,
:default => "rest",
:desc => "The default source for files if no server is given in a
uri, e.g. puppet:///file. The default of `rest` causes the file to be
retrieved using the `server` setting. When running `apply` the default
is `file_server`, causing requests to be filled locally."
},
:httplog => {
:default => "$logdir/http.log",
:type => :file,
:owner => "root",
:mode => 0640,
:desc => "Where the puppet agent web server logs.",
},
:http_proxy_host => {
:default => "none",
:desc => "The HTTP proxy host to use for outgoing connections. Note: You
may need to use a FQDN for the server hostname when using a proxy. Environment variable
http_proxy or HTTP_PROXY will override this value",
},
:http_proxy_port => {
:default => 3128,
:desc => "The HTTP proxy port to use for outgoing connections",
},
:http_proxy_user => {
:default => "none",
:desc => "The user name for an authenticated HTTP proxy. Requires http_proxy_host.",
},
:http_proxy_password =>{
:default => "none",
:hook => proc do |value|
if Puppet.settings[:http_proxy_password] =~ /[@!# \/]/
raise "Special characters in passwords must be URL compliant, we received #{value}"
end
end,
:desc => "The password for the user of an authenticated HTTP proxy. Requires http_proxy_user.
NOTE: Special characters must be escaped or encoded for URL compliance",
},
:filetimeout => {
:default => "15s",
:type => :duration,
:desc => "The minimum time to wait between checking for updates in
configuration files. This timeout determines how quickly Puppet checks whether
a file (such as manifests or templates) has changed on disk. #{AS_DURATION}",
},
:environment_timeout => {
:default => "3m",
:type => :ttl,
:desc => "The time to live for a cached environment.
#{AS_DURATION}
This setting can also be set to `unlimited`, which causes the environment to
be cached until the master is restarted."
},
:queue_type => {
:default => "stomp",
:desc => "Which type of queue to use for asynchronous processing.",
},
:queue_type => {
:default => "stomp",
:desc => "Which type of queue to use for asynchronous processing.",
},
:queue_source => {
:default => "stomp://localhost:61613/",
:desc => "Which type of queue to use for asynchronous processing. If your stomp server requires
authentication, you can include it in the URI as long as your stomp client library is at least 1.1.1",
},
:async_storeconfigs => {
:default => false,
:type => :boolean,
:desc => "Whether to use a queueing system to provide asynchronous database integration.
Requires that `puppet queue` be running.",
:hook => proc do |value|
if value
# This reconfigures the termini for Node, Facts, and Catalog
Puppet.settings.override_default(:storeconfigs, true)
# But then we modify the configuration
Puppet::Resource::Catalog.indirection.cache_class = :queue
Puppet.settings.override_default(:catalog_cache_terminus, :queue)
else
raise "Cannot disable asynchronous storeconfigs in a running process"
end
end
},
:thin_storeconfigs => {
:default => false,
:type => :boolean,
:desc =>
"Boolean; whether Puppet should store only facts and exported resources in the storeconfigs
database. This will improve the performance of exported resources with the older
`active_record` backend, but will disable external tools that search the storeconfigs database.
Thinning catalogs is generally unnecessary when using PuppetDB to store catalogs.",
:hook => proc do |value|
Puppet.settings.override_default(:storeconfigs, true) if value
end
},
:config_version => {
:default => "",
:desc => "How to determine the configuration version. By default, it will be the
time that the configuration is parsed, but you can provide a shell script to override how the
version is determined. The output of this script will be added to every log message in the
reports, allowing you to correlate changes on your hosts to the source version on the server.
Setting a global value for config_version in puppet.conf is deprecated. Please set a
per-environment value in environment.conf instead. For more info, see
http://docs.puppetlabs.com/puppet/latest/reference/environments.html",
:deprecated => :allowed_on_commandline,
},
:zlib => {
:default => true,
:type => :boolean,
:desc => "Boolean; whether to use the zlib library",
},
:prerun_command => {
:default => "",
:desc => "A command to run before every agent run. If this command returns a non-zero
return code, the entire Puppet run will fail.",
},
:postrun_command => {
:default => "",
:desc => "A command to run after every agent run. If this command returns a non-zero
return code, the entire Puppet run will be considered to have failed, even though it might have
performed work during the normal run.",
},
:freeze_main => {
:default => false,
:type => :boolean,
:desc => "Freezes the 'main' class, disallowing any code to be added to it. This
essentially means that you can't have any code outside of a node,
class, or definition other than in the site manifest.",
},
:stringify_facts => {
:default => true,
:type => :boolean,
:desc => "Flatten fact values to strings using #to_s. Means you can't have arrays or
hashes as fact values.",
},
:trusted_node_data => {
:default => false,
:type => :boolean,
:desc => "Stores trusted node data in a hash called $trusted.
When true also prevents $trusted from being overridden in any scope.",
},
:immutable_node_data => {
:default => '$trusted_node_data',
:type => :boolean,
:desc => "When true, also prevents $trusted and $facts from being overridden in any scope",
}
)
Puppet.define_settings(:module_tool,
:module_repository => {
:default => 'https://forgeapi.puppetlabs.com',
:desc => "The module repository",
},
:module_working_dir => {
:default => '$vardir/puppet-module',
:desc => "The directory into which module tool data is stored",
},
:module_skeleton_dir => {
:default => '$module_working_dir/skeleton',
:desc => "The directory which the skeleton for module tool generate is stored.",
},
:forge_authorization => {
:default => nil,
:desc => "The authorization key to connect to the Puppet Forge. Leave blank for unauthorized or license based connections",
},
:module_groups => {
:default => nil,
:desc => "Extra module groups to request from the Puppet Forge",
}
)
Puppet.define_settings(
:main,
# We have to downcase the fqdn, because the current ssl stuff (as oppsed to in master) doesn't have good facilities for
# manipulating naming.
:certname => {
:default => lambda { Puppet::Settings.default_certname.downcase },
:desc => "The name to use when handling certificates. When a node
requests a certificate from the CA puppet master, it uses the value of the
`certname` setting as its requested Subject CN.
This is the name used when managing a node's permissions in
[auth.conf](http://docs.puppetlabs.com/puppet/latest/reference/config_file_auth.html).
In most cases, it is also used as the node's name when matching
[node definitions](http://docs.puppetlabs.com/puppet/latest/reference/lang_node_definitions.html)
and requesting data from an ENC. (This can be changed with the `node_name_value`
and `node_name_fact` settings, although you should only do so if you have
a compelling reason.)
A node's certname is available in Puppet manifests as `$trusted['certname']`. (See
[Facts and Built-In Variables](http://docs.puppetlabs.com/puppet/latest/reference/lang_facts_and_builtin_vars.html)
for more details.)
* For best compatibility, you should limit the value of `certname` to
only use letters, numbers, periods, underscores, and dashes. (That is,
it should match `/\A[a-z0-9._-]+\Z/`.)
* The special value `ca` is reserved, and can't be used as the certname
for a normal node.
Defaults to the node's fully qualified domain name.",
:hook => proc { |value| raise(ArgumentError, "Certificate names must be lower case; see #1168") unless value == value.downcase }},
:certdnsnames => {
:default => '',
:hook => proc do |value|
unless value.nil? or value == '' then
Puppet.warning <<WARN
The `certdnsnames` setting is no longer functional,
after CVE-2011-3872. We ignore the value completely.
For your own certificate request you can set `dns_alt_names` in the
configuration and it will apply locally. There is no configuration option to
set DNS alt names, or any other `subjectAltName` value, for another nodes
certificate.
Alternately you can use the `--dns_alt_names` command line option to set the
labels added while generating your own CSR.
WARN
end
end,
:desc => <<EOT
The `certdnsnames` setting is no longer functional,
after CVE-2011-3872. We ignore the value completely.
For your own certificate request you can set `dns_alt_names` in the
configuration and it will apply locally. There is no configuration option to
set DNS alt names, or any other `subjectAltName` value, for another nodes
certificate.
Alternately you can use the `--dns_alt_names` command line option to set the
labels added while generating your own CSR.
EOT
},
:dns_alt_names => {
:default => '',
:desc => <<EOT,
The comma-separated list of alternative DNS names to use for the local host.
When the node generates a CSR for itself, these are added to the request
as the desired `subjectAltName` in the certificate: additional DNS labels
that the certificate is also valid answering as.
This is generally required if you use a non-hostname `certname`, or if you
want to use `puppet kick` or `puppet resource -H` and the primary certname
does not match the DNS name you use to communicate with the host.
This is unnecessary for agents, unless you intend to use them as a server for
`puppet kick` or remote `puppet resource` management.
It is rarely necessary for servers; it is usually helpful only if you need to
have a pool of multiple load balanced masters, or for the same master to
respond on two physically separate networks under different names.
EOT
},
:csr_attributes => {
:default => "$confdir/csr_attributes.yaml",
:type => :file,
:desc => <<EOT
An optional file containing custom attributes to add to certificate signing
requests (CSRs). You should ensure that this file does not exist on your CA
puppet master; if it does, unwanted certificate extensions may leak into
certificates created with the `puppet cert generate` command.
If present, this file must be a YAML hash containing a `custom_attributes` key
and/or an `extension_requests` key. The value of each key must be a hash, where
each key is a valid OID and each value is an object that can be cast to a string.
Custom attributes can be used by the CA when deciding whether to sign the
certificate, but are then discarded. Attribute OIDs can be any OID value except
the standard CSR attributes (i.e. attributes described in RFC 2985 section 5.4).
This is useful for embedding a pre-shared key for autosigning policy executables
(see the `autosign` setting), often by using the `1.2.840.113549.1.9.7`
("challenge password") OID.
Extension requests will be permanently embedded in the final certificate.
Extension OIDs must be in the "ppRegCertExt" (`1.3.6.1.4.1.34380.1.1`) or
"ppPrivCertExt" (`1.3.6.1.4.1.34380.1.2`) OID arcs. The ppRegCertExt arc is
reserved for four of the most common pieces of data to embed: `pp_uuid` (`.1`),
`pp_instance_id` (`.2`), `pp_image_name` (`.3`), and `pp_preshared_key` (`.4`)
--- in the YAML file, these can be referred to by their short descriptive names
instead of their full OID. The ppPrivCertExt arc is unregulated, and can be used
for site-specific extensions.
EOT
},
:certdir => {
:default => "$ssldir/certs",
:type => :directory,
:mode => 0755,
:owner => "service",
:group => "service",
:desc => "The certificate directory."
},
:ssldir => {
:default => "$confdir/ssl",
:type => :directory,
:mode => 0771,
:owner => "service",
:group => "service",
:desc => "Where SSL certificates are kept."
},
:publickeydir => {
:default => "$ssldir/public_keys",
:type => :directory,
:mode => 0755,
:owner => "service",
:group => "service",
:desc => "The public key directory."
},
:requestdir => {
:default => "$ssldir/certificate_requests",
:type => :directory,
:mode => 0755,
:owner => "service",
:group => "service",
:desc => "Where host certificate requests are stored."
},
:privatekeydir => {
:default => "$ssldir/private_keys",
:type => :directory,
:mode => 0750,
:owner => "service",
:group => "service",
:desc => "The private key directory."
},
:privatedir => {
:default => "$ssldir/private",
:type => :directory,
:mode => 0750,
:owner => "service",
:group => "service",
:desc => "Where the client stores private certificate information."
},
:passfile => {
:default => "$privatedir/password",
:type => :file,
:mode => 0640,
:owner => "service",
:group => "service",
:desc => "Where puppet agent stores the password for its private key.
Generally unused."
},
:hostcsr => {
:default => "$ssldir/csr_$certname.pem",
:type => :file,
:mode => 0644,
:owner => "service",
:group => "service",
:desc => "Where individual hosts store and look for their certificate requests."
},
:hostcert => {
:default => "$certdir/$certname.pem",
:type => :file,
:mode => 0644,
:owner => "service",
:group => "service",
:desc => "Where individual hosts store and look for their certificates."
},
:hostprivkey => {
:default => "$privatekeydir/$certname.pem",
:type => :file,
:mode => 0640,
:owner => "service",
:group => "service",
:desc => "Where individual hosts store and look for their private key."
},
:hostpubkey => {
:default => "$publickeydir/$certname.pem",
:type => :file,
:mode => 0644,
:owner => "service",
:group => "service",
:desc => "Where individual hosts store and look for their public key."
},
:localcacert => {
:default => "$certdir/ca.pem",
:type => :file,
:mode => 0644,
:owner => "service",
:group => "service",
:desc => "Where each client stores the CA certificate."
},
:ssl_client_ca_auth => {
:type => :file,
:mode => 0644,
:owner => "service",
:group => "service",
:desc => "Certificate authorities who issue server certificates. SSL servers will not be
considered authentic unless they possess a certificate issued by an authority
listed in this file. If this setting has no value then the Puppet master's CA
certificate (localcacert) will be used."
},
:ssl_server_ca_auth => {
:type => :file,
:mode => 0644,
:owner => "service",
:group => "service",
:desc => "Certificate authorities who issue client certificates. SSL clients will not be
considered authentic unless they possess a certificate issued by an authority
listed in this file. If this setting has no value then the Puppet master's CA
certificate (localcacert) will be used."
},
:hostcrl => {
:default => "$ssldir/crl.pem",
:type => :file,
:mode => 0644,
:owner => "service",
:group => "service",
:desc => "Where the host's certificate revocation list can be found.
This is distinct from the certificate authority's CRL."
},
:certificate_revocation => {
:default => true,
:type => :boolean,
:desc => "Whether certificate revocation should be supported by downloading a
Certificate Revocation List (CRL)
to all clients. If enabled, CA chaining will almost definitely not work.",
},
:certificate_expire_warning => {
:default => "60d",
:type => :duration,
:desc => "The window of time leading up to a certificate's expiration that a notification
will be logged. This applies to CA, master, and agent certificates. #{AS_DURATION}"
},
:digest_algorithm => {
:default => 'md5',
:type => :enum,
:values => ["md5", "sha256"],
:desc => 'Which digest algorithm to use for file resources and the filebucket.
Valid values are md5, sha256. Default is md5.',
}
)
define_settings(
:ca,
:ca_name => {
:default => "Puppet CA: $certname",
:desc => "The name to use the Certificate Authority certificate.",
},
:cadir => {
:default => "$ssldir/ca",
:type => :directory,
:owner => "service",
:group => "service",
:mode => 0755,
:desc => "The root directory for the certificate authority."
},
:cacert => {
:default => "$cadir/ca_crt.pem",
:type => :file,
:owner => "service",
:group => "service",
:mode => 0644,
:desc => "The CA certificate."
},
:cakey => {
:default => "$cadir/ca_key.pem",
:type => :file,
:owner => "service",
:group => "service",
:mode => 0640,
:desc => "The CA private key."
},
:capub => {
:default => "$cadir/ca_pub.pem",
:type => :file,
:owner => "service",
:group => "service",
:mode => 0644,
:desc => "The CA public key."
},
:cacrl => {
:default => "$cadir/ca_crl.pem",
:type => :file,
:owner => "service",
:group => "service",
:mode => 0644,
:desc => "The certificate revocation list (CRL) for the CA. Will be used if present but otherwise ignored.",
},
:caprivatedir => {
:default => "$cadir/private",
:type => :directory,
:owner => "service",
:group => "service",
:mode => 0750,
:desc => "Where the CA stores private certificate information."
},
:csrdir => {
:default => "$cadir/requests",
:type => :directory,
:owner => "service",
:group => "service",
:mode => 0755,
:desc => "Where the CA stores certificate requests"
},
:signeddir => {
:default => "$cadir/signed",
:type => :directory,
:owner => "service",
:group => "service",
:mode => 0755,
:desc => "Where the CA stores signed certificates."
},
:capass => {
:default => "$caprivatedir/ca.pass",
:type => :file,
:owner => "service",
:group => "service",
:mode => 0640,
:desc => "Where the CA stores the password for the private key."
},
:serial => {
:default => "$cadir/serial",
:type => :file,
:owner => "service",
:group => "service",
:mode => 0644,
:desc => "Where the serial number for certificates is stored."
},
:autosign => {
:default => "$confdir/autosign.conf",
:type => :autosign,
:desc => "Whether (and how) to autosign certificate requests. This setting
is only relevant on a puppet master acting as a certificate authority (CA).
Valid values are true (autosigns all certificate requests; not recommended),
false (disables autosigning certificates), or the absolute path to a file.
The file specified in this setting may be either a **configuration file**
or a **custom policy executable.** Puppet will automatically determine
what it is: If the Puppet user (see the `user` setting) can execute the
file, it will be treated as a policy executable; otherwise, it will be
treated as a config file.
If a custom policy executable is configured, the CA puppet master will run it
every time it receives a CSR. The executable will be passed the subject CN of the
request _as a command line argument,_ and the contents of the CSR in PEM format
_on stdin._ It should exit with a status of 0 if the cert should be autosigned
and non-zero if the cert should not be autosigned.
If a certificate request is not autosigned, it will persist for review. An admin
user can use the `puppet cert sign` command to manually sign it, or can delete
the request.
For info on autosign configuration files, see
[the guide to Puppet's config files](http://docs.puppetlabs.com/guides/configuring.html).",
},
:allow_duplicate_certs => {
:default => false,
:type => :boolean,
:desc => "Whether to allow a new certificate
request to overwrite an existing certificate.",
},
:ca_ttl => {
:default => "5y",
:type => :duration,
:desc => "The default TTL for new certificates.
#{AS_DURATION}"
},
:req_bits => {
:default => 4096,
:desc => "The bit length of the certificates.",
},
:keylength => {
:default => 4096,
:desc => "The bit length of keys.",
},
:cert_inventory => {
:default => "$cadir/inventory.txt",
:type => :file,
:mode => 0644,
:owner => "service",
:group => "service",
:desc => "The inventory file. This is a text file to which the CA writes a
complete listing of all certificates."
}
)
# Define the config default.
define_settings(:application,
:config_file_name => {
:type => :string,
:default => Puppet::Settings.default_config_file_name,
:desc => "The name of the puppet config file.",
},
:config => {
:type => :file,
:default => "$confdir/${config_file_name}",
:desc => "The configuration file for the current puppet application.",
},
:pidfile => {
:type => :file,
:default => "$rundir/${run_mode}.pid",
:desc => "The file containing the PID of a running process.
This file is intended to be used by service management frameworks
and monitoring systems to determine if a puppet process is still in
the process table.",
},
:bindaddress => {
:default => "0.0.0.0",
:desc => "The address a listening server should bind to.",
}
)
define_settings(:master,
:user => {
:default => "puppet",
:desc => "The user puppet master should run as.",
},
:group => {
:default => "puppet",
:desc => "The group puppet master should run as.",
},
:manifestdir => {
:default => "$confdir/manifests",
:type => :directory,
:desc => "Used to build the default value of the `manifest` setting. Has no other purpose.
This setting is deprecated.",
:deprecated => :completely,
},