diff options
Diffstat (limited to 'lib/puppet/reference')
| -rw-r--r-- | lib/puppet/reference/configuration.rb | 149 | ||||
| -rw-r--r-- | lib/puppet/reference/function.rb | 13 | ||||
| -rw-r--r-- | lib/puppet/reference/report.rb | 21 | ||||
| -rw-r--r-- | lib/puppet/reference/type.rb | 152 |
4 files changed, 335 insertions, 0 deletions
diff --git a/lib/puppet/reference/configuration.rb b/lib/puppet/reference/configuration.rb new file mode 100644 index 000000000..b7076a1e5 --- /dev/null +++ b/lib/puppet/reference/configuration.rb @@ -0,0 +1,149 @@ +config = Puppet::Util::Reference.newreference(:configuration, :depth => 1, :doc => "A reference for all configuration parameters") do + docs = {} + Puppet.config.each do |name, object| + docs[name] = object + end + + str = "" + docs.sort { |a, b| + a[0].to_s <=> b[0].to_s + }.each do |name, object| + # Make each name an anchor + header = name.to_s + str += h(header, 3) + + # Print the doc string itself + begin + str += object.desc.gsub(/\n/, " ") + rescue => detail + puts detail.backtrace + puts detail + end + str += "\n\n" + + # Now print the data about the item. + str += "" + val = object.default + if name.to_s == "vardir" + val = "/var/puppet" + elsif name.to_s == "confdir" + val = "/etc/puppet" + end + str += "- **Section**: %s\n" % object.section + unless val == "" + str += "- **Default**: %s\n" % val + end + str += "\n" + end + + return str +end + +config.header = " +Specifying Configuration Parameters +----------------------------------- + +On The Command-Line ++++++++++++++++++++ +Every Puppet executable (with the exception of ``puppetdoc``) accepts all of +the arguments below, but not all of the arguments make sense for every executable. +Each argument has a section listed with it in parentheses; often, that section +will map to an executable (e.g., ``puppetd``), in which case it probably only +makes sense for that one executable. If ``puppet`` is listed as the section, +it is most likely an option that is valid for everyone. + +This will not always be the case. I have tried to be as thorough as possible +in the descriptions of the arguments, so it should be obvious whether an +argument is appropriate or not. + +These arguments can be supplied to the executables either as command-line +arugments or in the configuration file for the appropriate executable. For +instance, the command-line invocation below would set the configuration directory +to ``/private/puppet``:: + + $ puppetd --confdir=/private/puppet + +Note that boolean options are turned on and off with a slightly different syntax +on the command line:: + + $ puppetd --storeconfigs + + $ puppetd --no-storeconfigs + +The invocations above will enable and disable, respectively, the storage of +the client configuration. + +Configuration Files ++++++++++++++++++++ +As mentioned above, the configuration parameters can also be stored in a +configuration file located in the configuration directory (`/etc/puppet` +by default). All executables look for ``puppet.conf`` in their +configuration directory (although they used to each look to separate files). + +All executables will set any parameters set within the ``main`` section, +while each executable will also look for a section named for the executable +and load those parameters. For example, ``puppetd`` will look for a +section named ``puppetd`, and ``puppetmasterd`` looks for a section +named ``puppetmasterd``. This allows you to use a single configuration file +to customize the settings for all of your executables. + +File Format +''''''''''' +The file follows INI-style formatting. Here is an example of a very simple +``puppet.conf`` file:: + + [main] + confdir = /private/puppet + storeconfigs = true + +Note that boolean parameters must be explicitly specified as `true` or +`false` as seen above. + +If you need to change file parameters (e.g., reset the mode or owner), do +so within curly braces on the same line:: + + [main] + myfile = /tmp/whatever {owner = root, mode = 644} + +If you're starting out with a fresh configuration, you may wish to let +the executable generate a template configuration file for you by invoking +the executable in question with the `--genconfig` command. The executable +will print a template configuration to standard output, which can be +redirected to a file like so:: + + $ puppetd --genconfig > /etc/puppet/puppetd.conf + +Note that this invocation will \"clobber\" (throw away) the contents of any +pre-existing `puppetd.conf` file, so make a backup of your present config +if it contains valuable information. + +Like the `--genconfig` argument, the executables also accept a `--genmanifest` +argument, which will generate a manifest that can be used to manage all of +Puppet's directories and files and prints it to standard output. This can +likewise be redirected to a file:: + + $ puppetd --genmanifest > /etc/puppet/manifests/site.pp + +Puppet can also create user and group accounts for itself (one `puppet` group +and one `puppet` user) if it is invoked as `root` with the `--mkusers` argument:: + + $ puppetd --mkusers + +Signals +------- +The ``puppetd`` and ``puppetmasterd`` executables catch some signals for special +handling. Both daemons catch (``SIGHUP``), which forces the server to restart +tself. Predictably, interrupt and terminate (``SIGINT`` and ``SIGHUP``) will shut +down the server, whether it be an instance of ``puppetd`` or ``puppetmasterd``. + +Sending the ``SIGUSR1`` signal to an instance of ``puppetd`` will cause it to +immediately begin a new configuration transaction with the server. This +signal has no effect on ``puppetmasterd``. + +Configuration Parameter Reference +--------------------------------- +Below is a list of all documented parameters. Not all of them are valid with all +Puppet executables, but the executables will ignore any inappropriate values. + +" + diff --git a/lib/puppet/reference/function.rb b/lib/puppet/reference/function.rb new file mode 100644 index 000000000..5c62c88d5 --- /dev/null +++ b/lib/puppet/reference/function.rb @@ -0,0 +1,13 @@ +function = Puppet::Util::Reference.newreference :function, :doc => "All functions available in the parser" do + Puppet::Parser::Functions.functiondocs +end +function.header = " +There are two types of functions in Puppet: Statements and rvalues. +Statements stand on their own and do not return arguments; they are used for +performing stand-alone work like importing. Rvalues return values and can +only be used in a statement requiring a value, such as an assignment or a case +statement. + +Here are the functions available in Puppet: + +" diff --git a/lib/puppet/reference/report.rb b/lib/puppet/reference/report.rb new file mode 100644 index 000000000..a8086f8bc --- /dev/null +++ b/lib/puppet/reference/report.rb @@ -0,0 +1,21 @@ +report = Puppet::Util::Reference.newreference :report, :doc => "All available transaction reports" do + Puppet::Network::Handler.report.reportdocs +end + +report.header = " +Puppet clients can report back to the server after each transaction. This +transaction report is sent as a YAML dump of the +``Puppet::Transaction::Report`` class and includes every log message that was +generated during the transaction along with as many metrics as Puppet knows how +to collect. See `ReportsAndReporting Reports and Reporting`:trac: +for more information on how to use reports. + +Currently, clients default to not sending in reports; you can enable reporting +by setting the ``report`` parameter to true. + +To use a report, set the ``reports`` parameter on the server; multiple +reports must be comma-separated. You can also specify ``none`` to disable +reports entirely. + +Puppet provides multiple report handlers that will process client reports: +" diff --git a/lib/puppet/reference/type.rb b/lib/puppet/reference/type.rb new file mode 100644 index 000000000..0093a555a --- /dev/null +++ b/lib/puppet/reference/type.rb @@ -0,0 +1,152 @@ +type = Puppet::Util::Reference.newreference :type, :doc => "All Puppet resource types and all their details" do + types = {} + Puppet::Type.loadall + + Puppet::Type.eachtype { |type| + next if type.name == :puppet + next if type.name == :component + types[type.name] = type + } + + str = %{ +Metaparameters +-------------- +Metaparameters are parameters that work with any element; they are part of the +Puppet framework itself rather than being part of the implementation of any +given instance. Thus, any defined metaparameter can be used with any instance +in your manifest, including defined components. + +Available Metaparameters +++++++++++++++++++++++++ +} + begin + params = [] + Puppet::Type.eachmetaparam { |param| + params << param + } + + params.sort { |a,b| + a.to_s <=> b.to_s + }.each { |param| + str += paramwrap(param.to_s, scrub(Puppet::Type.metaparamdoc(param)), :level => 4) + #puts "<dt>" + param.to_s + "</dt>" + #puts tab(1) + Puppet::Type.metaparamdoc(param).scrub.indent($tab)gsub(/\n\s*/,' ') + #puts "<dd>" + #puts indent(scrub(Puppet::Type.metaparamdoc(param)), $tab) + #puts scrub(Puppet::Type.metaparamdoc(param)) + #puts "</dd>" + + #puts "" + } + rescue => detail + puts detail.backtrace + puts "incorrect metaparams: %s" % detail + exit(1) + end + + str += %{ + +Resource Types +-------------- + +- The *namevar* is the parameter used to uniquely identify a type instance. + This is the parameter that gets assigned when a string is provided before + the colon in a type declaration. In general, only developers will need to + worry about which parameter is the ``namevar``. + + In the following code:: + + file { "/etc/passwd": + owner => root, + group => root, + mode => 644 + } + + ``/etc/passwd`` is considered the title of the file object (used for things like + dependency handling), and because ``path`` is the namevar for ``file``, that + string is assigned to the ``path`` parameter. + +- *Features* are abilities that some providers might not support. You can use the list + of supported features to determine how a given provider can be used. + +- *Parameters* determine the specific configuration of the instance. They either + directly modify the system (internally, these are called properties) or they affect + how the instance behaves (e.g., adding a search path for ``exec`` instances + or determining recursion on ``file`` instances). + +- *Providers* provide low-level functionality for a given resource type. This is + usually in the form of calling out to external commands. + + When required binaries are specified for providers, fully qualifed paths + indicate that the binary must exist at that specific path and unqualified + binaries indicate that Puppet will search for the binary using the shell + path. + + Resource types define features they can use, and providers can be tested to see + which features they provide. + + } + + types.sort { |a,b| + a.to_s <=> b.to_s + }.each { |name,type| + + str += " + +---------------- + +" + + str += h(name, 3) + str += scrub(type.doc) + "\n\n" + + # Handle the feature docs. + if featuredocs = type.featuredocs + str += h("Features", 4) + str += featuredocs + end + + docs = {} + type.validproperties.sort { |a,b| + a.to_s <=> b.to_s + }.reject { |sname| + property = type.propertybyname(sname) + property.nodoc + }.each { |sname| + property = type.propertybyname(sname) + + unless property + raise "Could not retrieve property %s on type %s" % [sname, type.name] + end + + doc = nil + unless doc = property.doc + $stderr.puts "No docs for %s[%s]" % [type, sname] + next + end + doc = doc.dup + tmp = doc + tmp = scrub(tmp) + + docs[sname] = tmp + } + + str += h("Parameters", 4) + "\n" + type.parameters.sort { |a,b| + a.to_s <=> b.to_s + }.each { |name,param| + #docs[name] = indent(scrub(type.paramdoc(name)), $tab) + docs[name] = scrub(type.paramdoc(name)) + } + + docs.sort { |a, b| + a[0].to_s <=> b[0].to_s + }.each { |name, doc| + namevar = type.namevar == name and name != :name + str += paramwrap(name, doc, :namevar => namevar) + } + str += "\n" + } + + str +end |