Updating docs

git-svn-id: https://reductivelabs.com/svn/puppet/trunk@1843 980ebf18-57e1-0310-9a29-db15c13687c0

8 files changed, 135 insertions, 65 deletions

diff --git a/documentation/Rakefile b/documentation/Rakefile
index cb01fdc21..3da422e6d 100644
--- a/documentation/Rakefile
+++ b/documentation/Rakefile
@@ -32,7 +32,7 @@ task :html => htmlfiles
 
 task :default => :html
 
-docs = %w{configref types reports functions}
+docs = %w{configref typedocs reports functions}
 
 docs.each do |doc|
     task doc do
diff --git a/documentation/documentation/about/glossary.page b/documentation/documentation/about/glossary.page
index cd7a94b3a..cc3ef2fe0 100644
--- a/documentation/documentation/about/glossary.page
+++ b/documentation/documentation/about/glossary.page
@@ -2,7 +2,6 @@
 inMenu: true
 title: A Glossary of Terms
 orderInfo: 3
-subtreeLevel: 6
 ---
 
 As developers have found time and time again, terminology is critical to
diff --git a/documentation/documentation/about/index.page b/documentation/documentation/about/index.page
index 6956fc505..f1480aa63 100644
--- a/documentation/documentation/about/index.page
+++ b/documentation/documentation/about/index.page
@@ -12,7 +12,4 @@ About Puppet
 * [Puppet vs. Cfengine](notcfengine.html)
 * [Glossary](glossary.html)
 
-
-
-
 *$Id$*
diff --git a/documentation/documentation/reference/configref.page b/documentation/documentation/reference/configref.page
index d31442d40..4f7ba3dd6 100644
--- a/documentation/documentation/reference/configref.page
+++ b/documentation/documentation/reference/configref.page
@@ -1,12 +1,14 @@
 ---
 inMenu: true
 title: Configuration Reference
-orderInfo: 30
+orderInfo: 40
 ---
 # Puppet Configuration Reference
 
+## Specifying Configuration Parameters
+
 Every Puppet executable (with the exception of ``puppetdoc``) accepts all of
-these arguments, but not all of the arguments make sense for every executable.
+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,
@@ -73,12 +75,30 @@ and one `puppet` user) if it is invoked as `root` with the `--mkusers` argument:
 
     $ puppetd --mkusers
   
-Any default values are in ``block type`` at the end of the description.
+## 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.  Any default values are in ``block type`` at the end of the description.
 
 #### <a name="authconfig">authconfig</a> (<em>puppet</em>)
 
 The configuration file that defines the rights to the different namespaces and methods.  This can be used as a coarse-grained authorization system for both ``puppetd`` and ``puppetmasterd``.  ``/etc/puppet/namespaceauth.conf``
 
+#### <a name="autoflush">autoflush</a> (<em>puppet</em>)
+
+Whether log files should always flush to disk.
+
 #### <a name="autosign">autosign</a> (<em>ca</em>)
 
 Whether to enable autosign.  Valid values are true (which autosigns any key request, and is a very bad idea), false (which never autosigns any key request), and the path to a file, which uses that configuration file to determine which keys to sign.  ``/etc/puppet/autosign.conf``
@@ -127,6 +147,10 @@ Where the CA stores private certificate information.  ``/etc/puppet/ssl/ca/priva
 
 The CA public key.  ``/etc/puppet/ssl/ca/ca_pub.pem``
 
+#### <a name="cert_inventory">cert_inventory</a> (<em>ca</em>)
+
+A Complete listing of all certificates  ``/etc/puppet/ssl/ca/inventory.txt``
+
 #### <a name="certdir">certdir</a> (<em>certificates</em>)
 
 The certificate directory.  ``/etc/puppet/ssl/certs``
@@ -137,7 +161,7 @@ The file in which puppetd stores a list of the classes associated with the retri
 
 #### <a name="color">color</a> (<em>puppet</em>)
 
-Whether to use ANSI colors when logging to the console.  ``true``
+Whether to use colors when logging to the console. Valid values are ``ansi`` (equivalent to ``true``), ``html`` (mostly used during testing with TextMate), and ``false``, which produces no color.  ``ansi``
 
 #### <a name="confdir">confdir</a> (<em>puppet</em>)
 
@@ -155,30 +179,6 @@ Print the value of a specific configuration parameter.  If a parameter is provid
 
 Where the CA stores certificate requests  ``/etc/puppet/ssl/ca/requests``
 
-#### <a name="dbadapter">dbadapter</a> (<em>puppetmaster</em>)
-
-The type of database to use.  ``sqlite3``
-
-#### <a name="dblocation">dblocation</a> (<em>puppetmaster</em>)
-
-The database cache for client configurations.  Used for querying within the language.  ``/var/puppet/state/clientconfigs.sqlite3``
-
-#### <a name="dbname">dbname</a> (<em>puppetmaster</em>)
-
-The name of the database to use.  ``puppet``
-
-#### <a name="dbpassword">dbpassword</a> (<em>puppetmaster</em>)
-
-The database password for Client caching. Only used when networked databases are used.  ``puppet``
-
-#### <a name="dbserver">dbserver</a> (<em>puppetmaster</em>)
-
-The database server for Client caching. Only used when networked databases are used.  ``puppet``
-
-#### <a name="dbuser">dbuser</a> (<em>puppetmaster</em>)
-
-The database user for Client caching. Only used when networked databases are used.  ``puppet``
-
 #### <a name="factdest">factdest</a> (<em>puppet</em>)
 
 Where Puppet should store facts that it pulls down from the central server.  ``/var/puppet/facts``
@@ -355,6 +355,10 @@ Just check the syntax of the manifests.
 
 Where puppetd stores the password for its private key. Generally unused.  ``/etc/puppet/ssl/private/password``
 
+#### <a name="path">path</a> (<em>puppet</em>)
+
+The shell search path.  Defaults to whatever is inherited from the parent process.  ``none``
+
 #### <a name="plugindest">plugindest</a> (<em>puppet</em>)
 
 Where Puppet should store plugins that it pulls down from the central server.  ``/var/puppet/plugins``
@@ -399,21 +403,13 @@ The log file for puppetd.  This is generally not used.  ``/var/puppet/log/puppet
 
 Which port puppetd listens on.  ``8139``
 
-#### <a name="railslog">railslog</a> (<em>puppetmaster</em>)
-
-Where Rails-specific logs are sent  ``/var/puppet/log/puppetrails.log``
-
 #### <a name="report">report</a> (<em>puppetd</em>)
 
 Whether to send reports after every transaction.
 
-#### <a name="reportdirectory">reportdirectory</a> (<em>reporting</em>)
-
-The directory in which to store reports received from the client.  Each client gets a separate subdirectory.  ``/var/puppet/reports``
-
 #### <a name="reports">reports</a> (<em>reporting</em>)
 
-The list of reports to generate.  All reports are looked for in puppet/reports/<name>.rb, and multiple report names should be comma-separated (whitespace is okay).  ``none``
+The list of reports to generate.  All reports are looked for in puppet/reports/<name>.rb, and multiple report names should be comma-separated (whitespace is okay).  ``store``
 
 #### <a name="reportserver">reportserver</a> (<em>puppetd</em>)
 
@@ -425,12 +421,16 @@ The bit length of the certificates.  ``2048``
 
 #### <a name="rrddir">rrddir</a> (<em>metrics</em>)
 
-The directory where RRD database files are stored.  ``/var/puppet/rrd``
+The directory where RRD database files are stored. Directories for each reporting host will be created under this directory.  ``/var/puppet/rrd``
 
 #### <a name="rrdgraph">rrdgraph</a> (<em>metrics</em>)
 
 Whether RRD information should be graphed.
 
+#### <a name="rrdinterval">rrdinterval</a> (<em>metrics</em>)
+
+How often RRD should expect data. This should match how often the hosts report back to the server.  ``1800``
+
 #### <a name="rundir">rundir</a> (<em>puppet</em>)
 
 Where Puppet PID files are kept.  ``/var/puppet/run``
@@ -471,6 +471,10 @@ Where puppetd and puppetmasterd store state associated with the running configur
 
 Whether to store each client's configuration.  This requires ActiveRecord from Ruby on Rails.
 
+#### <a name="syslogfacility">syslogfacility</a> (<em>puppet</em>)
+
+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.  ``daemon``
+
 #### <a name="tags">tags</a> (<em>transaction</em>)
 
 Tags to use to find objects.  If this is set, then only objects tagged with the specified tags will be applied. Values must be comma-separated.
@@ -504,4 +508,4 @@ Where Puppet stores dynamic and growing data.  ``/var/puppet``
 ----------------
 
 
-*This page autogenerated on Mon Sep 25 14:05:16 CDT 2006*
+*This page autogenerated on Thu Nov 09 14:32:06 CST 2006*
diff --git a/documentation/documentation/reference/functions.page b/documentation/documentation/reference/functions.page
index f494df4d8..63e664390 100644
--- a/documentation/documentation/reference/functions.page
+++ b/documentation/documentation/reference/functions.page
@@ -45,4 +45,4 @@ Here are the functions available in Puppet:
 ----------------
 
 
-*This page autogenerated on Thu Nov 09 14:09:57 CST 2006*
+*This page autogenerated on Thu Nov 09 14:32:10 CST 2006*
diff --git a/documentation/documentation/reference/index.page b/documentation/documentation/reference/index.page
index 003323415..21b054976 100644
--- a/documentation/documentation/reference/index.page
+++ b/documentation/documentation/reference/index.page
@@ -9,6 +9,8 @@ subtreeLevel: 6
 Reference
 =========
 * [Configuration Parameter Reference](configref.html)
+* [Function Reference](functions.html)
+* [Reports Reference](reports.html)
 * [Type Reference](typedocs.html)
 
 
diff --git a/documentation/documentation/reference/reports.page b/documentation/documentation/reference/reports.page
index 61776efce..9493e1e50 100644
--- a/documentation/documentation/reference/reports.page
+++ b/documentation/documentation/reference/reports.page
@@ -6,6 +6,9 @@ as Puppet knows how to collect.
 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.
+
 Puppet provides multiple report handlers that will process client reports:
 
 ## rrdgraph
@@ -65,4 +68,4 @@ webservers that are not also from mailservers to ``httpadmins@domain.com``.
 ----------------
 
 
-*This page autogenerated on Thu Nov 09 14:29:10 CST 2006*
+*This page autogenerated on Thu Nov 09 14:47:22 CST 2006*
diff --git a/documentation/documentation/reference/typedocs.page b/documentation/documentation/reference/typedocs.page
index c928e5e92..29d1fd03e 100644
--- a/documentation/documentation/reference/typedocs.page
+++ b/documentation/documentation/reference/typedocs.page
@@ -1,7 +1,7 @@
 ---
 inMenu: true
 title: Type Reference
-orderInfo: 30
+orderInfo: 40
 ---
 # Type Reference
 
@@ -16,6 +16,7 @@ orderInfo: 30
 1. <a href='#group'>Group</a>
 1. <a href='#host'>Host</a>
 1. <a href='#mount'>Mount</a>
+1. <a href='#notify'>Notify</a>
 1. <a href='#package'>Package</a>
 1. <a href='#port'>Port</a>
 1. <a href='#schedule'>Schedule</a>
@@ -293,6 +294,10 @@ job.  If you already have cron jobs with environment settings,
 then Puppet will keep those settings in the same place in the file,
 but will not associate them with a specific job.
 
+Settings should be specified exactly as they should appear in
+the crontab, e.g., 'PATH=/bin:/usr/bin:/usr/sbin'.  Multiple
+settings should be specified as an array.
+
 #### hour
 The hour at which to run the cron job. Optional;
 if specified, must be between 0 and 23, inclusive.
@@ -554,7 +559,7 @@ for file copying, but it can also be used to monitor files somewhat
 like Tripwire without managing the file contents in any way.  You can
 specify that a file's checksum should be monitored and then subscribe to
 the file from another object and receive events to signify
-checksum changes, for instance.  Valid values are ``nosum``, ``mtime``, ``md5lite``, ``time``, ``timestamp``, ``md5``.  Values can also match ``(?-mix:^\{md5|md5lite|timestamp|mtime|time\})``.
+checksum changes, for instance.  Valid values are ``timestamp``, ``nosum``, ``md5``, ``mtime``, ``time``, ``md5lite``.  Values can also match ``(?-mix:^\{md5|md5lite|timestamp|mtime|time\})``.
 
 #### content
 Specify the contents of a file as a string.  Newlines, tabs, and
@@ -607,7 +612,7 @@ something similar.
 You can also make recursive symlinks, which will create a
 directory structure that maps to the target directory,
 with directories corresponding to each directory
-and links corresponding to each file.  Valid values are ``absent`` (also called ``false``), ``link``, ``directory``, ``file``, ``present``.  Values can also match ``(?-mix:.)``.
+and links corresponding to each file.  Valid values are ``link``, ``absent`` (also called ``false``), ``directory``, ``present``, ``file``.  Values can also match ``(?-mix:.)``.
 
 #### force
 Force the file operation.  Currently only used when replacing
@@ -830,14 +835,21 @@ make those aliases available in your Puppet scripts and also on
 disk.
 
 #### ensure
-The basic state that the object should be in.  Valid values are ``absent``, ``present``.
+  Valid values are ``absent``, ``present``.
 
 #### ip
-The host's IP address.
+The host's IP address, IPv4 or IPv6.
 
 #### name (*namevar*)
 The host name.
 
+#### provider
+The specific backend for provider to use. You will
+seldom need to specify this -- Puppet will usually discover the
+appropriate provider for your platform.  Available providers are:
+
+* **parsed**:   
+
 
 
 
@@ -892,6 +904,33 @@ The pass in which the mount is checked.
 #### path (*namevar*)
 The mount path for the mount.
 
+#### provider
+The specific backend for provider to use. You will
+seldom need to specify this -- Puppet will usually discover the
+appropriate provider for your platform.  Available providers are:
+
+* **parsed**:     Required binaries: ``umount``, ``mount``, ``df``.
+
+
+
+
+----------------
+
+
+<h2><a name='notify'>notify</a></h2>
+Sends an arbitrary message to the puppetd run-time log.
+
+
+### Notify Parameters
+#### message
+The message to be sent to the log.
+
+#### name (*namevar*)
+An arbitrary tag for your own reference; the name of the message.
+
+#### withpath
+Whether to not to show the full object path.  Sends the message at the current loglevel.  Valid values are ``true``, ``false``.
+
 
 
 
@@ -927,6 +966,10 @@ Normally apt will bail if you try this.  Valid values are ``true``, ``false``.
 #### category
 A read-only parameter set by the package.
 
+#### configfiles
+Whether configfiles should be kept or replaced.  Most packages
+types do not support this parameter.  Valid values are ``keep``, ``replace``.
+
 #### description
 A read-only parameter set by the package.
 
@@ -935,7 +978,7 @@ What state the package should be in.
 *latest* only makes sense for those packaging formats that can
 retrieve new packages on their own and will throw an error on
 those that cannot.  For those packaging systems that allow you
-to specify package versions, specify them here.  Valid values are ``absent``, ``latest``, ``present`` (also called ``installed``).  Values can also match ``(?-mix:.)``.
+to specify package versions, specify them here.  Valid values are ``absent``, ``present`` (also called ``installed``), ``latest``.  Values can also match ``(?-mix:.)``.
 
 #### instance
 A read-only parameter set by the package.
@@ -987,8 +1030,8 @@ appropriate provider for your platform.  Available providers are:
 * **apple**: Package management based on OS X's builtin packaging system.  This is
         essentially the simplest and least functional package system in existence --
         it only supports installation; no deletion or upgrades.  Default for ``operatingsystem`` == ``darwin``.    Required binaries: ``/usr/sbin/installer``.
-* **apt**: Package management via ``apt-get``.  Default for ``operatingsystem`` == ``debian``.    Required binaries: ``/usr/bin/apt-get``, ``/usr/bin/apt-cache``.
-* **aptitude**: Package management via ``aptitude``.    Required binaries: ``/usr/bin/aptitude``, ``/usr/bin/apt-cache``.
+* **apt**: Package management via ``apt-get``.  Default for ``operatingsystem`` == ``debian``.    Required binaries: ``/usr/bin/apt-cache``, ``/usr/bin/debconf-set-selections``, ``/usr/bin/apt-get``.
+* **aptitude**: Package management via ``aptitude``.    Required binaries: ``/usr/bin/apt-cache``, ``/usr/bin/aptitude``.
 * **blastwave**: Package management using Blastwave.org's ``pkg-get`` command on Solaris.    Required binaries: ``pkg-get``.
 * **darwinport**: Package management using DarwinPorts on OS X.    Required binaries: ``/opt/local/bin/port``.
 * **dpkg**: Package management via ``dpkg``.  Because this only uses ``dpkg``
@@ -1002,13 +1045,14 @@ appropriate provider for your platform.  Available providers are:
 * **gem**: Ruby Gem support.  By default uses remote gems, but you can specify
         the path to a local gem via ``source``.    Required binaries: ``gem``.
 * **openbsd**: OpenBSD's form of ``pkg_add`` support.  Default for ``operatingsystem`` == ``openbsd``.    Required binaries: ``pkg_info``, ``pkg_add``, ``pkg_delete``.
-* **portage**: Provides packaging support for Gentoo's portage system.  Default for ``operatingsystem`` == ``gentoo``.    Required binaries: ``/usr/bin/eix``, ``/usr/bin/emerge``.
+* **pkgdmg**: Package management based on Apple's Installer.app and DiskUtility.app    Required binaries: ``/usr/sbin/installer``, ``/usr/bin/hdiutil``.
+* **portage**: Provides packaging support for Gentoo's portage system.  Default for ``operatingsystem`` == ``gentoo``.    Required binaries: ``/usr/bin/emerge``, ``/usr/bin/eix``.
 * **ports**: Support for FreeBSD's ports.  Again, this still mixes packages
         and ports.  Default for ``operatingsystem`` == ``freebsd``.    Required binaries: ``/usr/local/sbin/portupgrade``, ``/usr/local/sbin/portversion``, ``/usr/local/sbin/pkg_deinstall``, ``/usr/sbin/pkg_info``.
 * **rpm**: RPM packaging support; should work anywhere with a working ``rpm``
         binary.  Default for ``operatingsystem`` == ``redhat``.    Required binaries: ``rpm``.
 * **sun**: Sun's packaging system.  Requires that you specify the source for
-        the packages you're managing.  Default for ``operatingsystem`` == ``solaris``.    Required binaries: ``/usr/bin/pkginfo``, ``/usr/sbin/pkgadd``, ``/usr/sbin/pkgrm``.
+        the packages you're managing.  Default for ``operatingsystem`` == ``solaris``.    Required binaries: ``/usr/sbin/pkgrm``, ``/usr/bin/pkginfo``, ``/usr/sbin/pkgadd``.
 * **sunfreeware**: Package management using sunfreeware.com's ``pkg-get`` command on Solaris.
         At this point, support is exactly the same as ``blastwave`` support and
         has not actually been tested.    Required binaries: ``pkg-get``.
@@ -1062,7 +1106,7 @@ those aliases available in your Puppet scripts and also on disk.
 The port description.
 
 #### ensure
-The basic state that the object should be in.  Valid values are ``absent``, ``present``.
+  Valid values are ``absent``, ``present``.
 
 #### name (*namevar*)
 The port name.
@@ -1077,6 +1121,13 @@ both protocols, you must specify that; Puppet replaces the
 current values, it does not merge with them.  If you specify
 multiple protocols they must be as an array.
 
+#### provider
+The specific backend for provider to use. You will
+seldom need to specify this -- Puppet will usually discover the
+appropriate provider for your platform.  Available providers are:
+
+* **parsed**:   
+
 
 
 
@@ -1227,7 +1278,7 @@ provided.
 Whether a service should be enabled to start at boot.
 This state behaves quite differently depending on the platform;
 wherever possible, it relies on local tools to enable or disable
-a given service.  *true*/*false*/*runlevels*  Valid values are ``false``, ``true``.
+a given service.  *true*/*false*/*runlevels*  Valid values are ``true``, ``false``.
 
 #### ensure
 Whether a service should be running.  **true**/*false*  Valid values are ``running`` (also called ``true``), ``stopped`` (also called ``false``).
@@ -1281,6 +1332,8 @@ appropriate provider for your platform.  Available providers are:
         so using ``init``.  
 * **debian**: Debian's form of ``init``-style management.  The only difference
         is that this supports service enabling and disabling via ``update-rc.d``.  Default for ``operatingsystem`` == ``debian``.    Required binaries: ``/usr/sbin/update-rc.d``.
+* **gentoo**: Gentoo's form of ``init``-style service
+        management; uses ``rc-update`` for service enabling and disabling.  Default for ``operatingsystem`` == ``gentoo``.    Required binaries: ``/sbin/rc-update``.
 * **init**: Standard init service management.  This provider assumes that the
         init script has not ``status`` command, because so few scripts do,
         so you need to either provide a status command or specify via ``hasstatus``
@@ -1339,7 +1392,7 @@ as one of the metaparams; using this state to set aliases will
 make those aliases available in your Puppet scripts.
 
 #### ensure
-The basic state that the object should be in.  Valid values are ``absent``, ``present``.
+  Valid values are ``absent``, ``present``.
 
 #### key
 The key itself; generally a long string of hex digits.
@@ -1347,6 +1400,13 @@ The key itself; generally a long string of hex digits.
 #### name (*namevar*)
 The host name.
 
+#### provider
+The specific backend for provider to use. You will
+seldom need to specify this -- Puppet will usually discover the
+appropriate provider for your platform.  Available providers are:
+
+* **parsed**:   
+
 #### type
 The encryption type used.  Probably ssh-dss or ssh-rsa.
 
@@ -1394,13 +1454,17 @@ are created in the destination, and any files are linked over.
 
 
 <h2><a name='tidy'>tidy</a></h2>
-Remove unwanted files based on specific criteria.
+Remove unwanted files based on specific criteria.  Multiple
+criteria or OR'd together, so a file that is too large but is not
+old enough will still get tidied.
 
 
 ### Tidy Parameters
 #### age
 Tidy files whose age is equal to or greater than
-the specified number of days.
+the specified number of days.  You can choose seconds, minutes,
+hours, days, or weeks by specifying the first letter of any
+of those words (e.g., '1w').
 
 #### backup
 Whether files should be backed up before
@@ -1446,6 +1510,8 @@ into the directory looking for files to tidy.
 #### rmdirs
 Tidy directories in addition to files; that is, remove
 directories whose age is older than the specified criteria.
+This will only remove empty directories, so all contained
+files must also be tidied before a directory gets removed.
 
 #### size
 Tidy files whose size is equal to or greater than
@@ -1455,8 +1521,7 @@ and *megabytes*, respectively.  Only the first character is
 significant, so the full word can also be used.
 
 #### type
-Set the mechanism for determining age.
-**atime**/*mtime*/*ctime*.
+Set the mechanism for determining age.  Valid values are ``atime``, ``mtime``, ``ctime``.
 
 
 
@@ -1636,7 +1701,7 @@ Solaris zones.
 
 ### Zone Parameters
 #### autoboot
-Whether the zone should automatically boot.  Valid values are ``false``, ``true``.
+Whether the zone should automatically boot.  Valid values are ``true``, ``false``.
 
 #### ensure
 The running state of the zone.  The valid states directly reflect
@@ -1717,4 +1782,4 @@ so Puppet only checks for it at that time.
 ----------------
 
 
-*This page autogenerated on Mon Sep 25 14:59:47 EDT 2006*
+*This page autogenerated on Thu Nov 09 14:43:00 CST 2006*