copying all documentation from the plone site

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

1 files changed, 322 insertions, 0 deletions

diff --git a/documentation/structures.rst b/documentation/structures.rst
new file mode 100644
index 000000000..1c5818d5b
--- /dev/null
+++ b/documentation/structures.rst
@@ -0,0 +1,322 @@
+This is a brief overview of the language structures 
+available for making site configurations in Puppet.
+For futher documentation, visit the `Puppet homepage`_.
+
+.. _puppet homepage: /projects/puppet
+
+Types
+-----
+The basic unit of configuration in Puppet are ``types``.  Types model objects
+on the computer being managed, and each builtin type has attributes that
+determine the final type configuration::
+
+    file { "/etc/passwd": owner => root, mode => 644 } 
+    package { apache: install => true }
+
+Puppet also provides facilities for defining new types as collections of
+existing types (see Components_ below), but there is no syntactic difference
+between using builtin types like ``file`` and ``package`` and using defined
+types.  Any operation or syntax that succeeds for builtin types should also
+work for defined types.
+
+See the `Type Reference`_ for the documentation for the
+Puppet Library's primitive types.
+
+Assignment
+-----------
+
+``$variable = value``
+
+Variables available in the current scope are referenced
+by preceding them with the ``$`` character. 
+
+Once assigned, variables cannot be reassigned. However,
+within a sub-scope a new assignment can be made for a
+variable name for that sub-scope and any further 
+sub-scopes created within it::
+  
+  $x = foo
+  $y = bar
+  $z = "$x$y"
+
+Bringing Config files together
+------------------------------
+
+::
+
+    import "filename"
+
+Starts the parsing of the file specified and creates any specified definitions
+and classes at the current scope.  Currently files are only searched for
+within the same directory as the file doing the importing.
+
+Files can also be imported using globbing, as implemented by Ruby's
+``Dir.glob`` method::
+
+    import "classes/*"
+    import "packages/[a-z]*"
+
+Scope
+-----
+
+Generally speaking, any language structure that involves curly braces creates
+a new scope inside those braces.  This currently includes server and class
+definitions and if/then/else structures.  Each file should also introduce its
+own scope but currently does not.
+
+Once assigned, variables cannot be reassigned within the same scope. However,
+within a sub-scope a new assignment can be made for a variable name for that
+sub-scope and any further scopes created within it::
+
+    $var = value
+
+    # override $var
+    define testing {
+        $var = othervalue
+    }
+
+Service and class definitions are scoped just as variable assignments are.
+Functions defined and Classes created within a scope will not be available
+outside the scope in which they are created::
+
+    define testing {
+        file { "/etc/passwd": owner => root }
+    }
+
+    class osx {
+        # override the existing testing definition
+        define testing {
+            file { "/etc/other": owner => root }
+        }
+    }
+
+The evaluation by Puppet of following example would be result in the copying
+of ``/file_repository/test-httpd.conf`` to ``/etc/httpd/conf/httpd.conf``::
+ 
+    $filename = "/etc/apache/httpd.conf"
+
+    class webserver {
+        $filename = "/etc/httpd/conf/httpd.conf"
+        define httpd_service (config_file) {
+            file { $filename : source => $config_file }
+        }
+        httpd_service { "test_httpd" : 
+            config_file => "/file_repository/test-httpd.conf"
+        }
+    }
+
+    webserver {}
+
+Components
+----------
+
+``define <name>(<param1>,<param2>,...) {...}``
+
+Definition of fuctions allows the composition of lower level types into higher
+level types.
+
+Parameters of defined functions can be referenced within the definition scope,
+similarly to variables, by preceding their names with the ``$`` character::
+
+    define svnserve(source, path, user = false, password = false) {
+        file { $path:
+            create => directory,
+            owner => root,
+            group => root
+        }
+        $svncmd = $user ? {
+            false => "/usr/bin/svn co --non-interactive $source/$name .",
+            default => "/usr/bin/svn co --non-interactive --username $user --password '$password' $source/$name ."
+        }   
+        exec { $svncmd: 
+            cwd => $path,
+            require => file[$path],
+            creates => "$path/.svn"
+        }   
+    }
+
+    svnserve { dist:
+        source => "https://reductivelabs.com/svn",
+        path => "/dist",
+        user => "puppet",
+        password => "password"
+    }
+
+    svnserve { "dist/config/apps/puppet":
+        source => "https://reductivelabs.com/svn",
+        path => "/etc/puppet",
+        user => "puppet",
+        password => "password"
+    }
+
+Note that calling components results in a unique instance of all contained
+objects.  In the above case, each of the calls to ``svnserver`` results in an
+``exec`` and a ``file`` instance.  So, it's important that all of your
+components are written that they support this.
+
+A good rule of thumb is that you should only include statements in your
+components that have variables in their names.  If a statement doesn't
+have a variable in the name, then you are likely to result in a situation
+where multiple components will try to manage the same instance, which will
+result in an error at run time.
+
+Server Classes
+--------------
+
+``class <class_name> [inherits <super_class_name>] { ... }``
+
+Class definitions allow the specification of a hierarchy of server classes; a
+host that is a member of a subclass will apply the configuration from the
+subclass and all parent classes.  The primary difference between classes and
+components is that classes are singletons -- there will only ever be a single
+instance of a given class on a given server.  Thus, if you have a server which
+is a member of three different classes, each of which share the same parent
+class, then you will get one instance of the parent class and one instance of
+each of the subclasses.
+
+::
+
+    # really simple example
+    class solaris {
+        file {
+            "/etc/passwd": owner => root, group => root, mode => 644;
+            "/etc/shadow": owner => root, group => root, mode => 440
+        }
+    }
+
+    class solworkstation inherits solaris {
+        file {
+            "/etc/sudoers": owner => root, group => root, mode => 440;
+            "/bin/sudo": owner => root, group => root, mode => 4111
+        }
+    }
+
+    include solworkstation
+
+The ``include`` syntax is syntactically equivalent to specifying a class
+with no arguments.  The above statement is equivalent to this statement::
+
+    solworkstation {}
+
+Subclassing
++++++++++++
+The primary benefit of using subclasses instead of just including the parent
+class is that the subclass can override elements in the parent class::
+
+    class unix {
+        file { "/etc/sudoers":
+            owner => root,
+            group => root,
+            mode => 440
+        }
+    }
+
+    class bsd inherits unix {
+        file { "/etc/sudoers":
+            group => wheel
+        }
+    }
+
+Including the ``unix`` class sets the group to ``root``, but including the
+``bsd`` class overrides the vale to ``wheel``.
+
+Using Classes Outside of Puppet
++++++++++++++++++++++++++++++++
+This isn't really a "language" thing, but it seemed the best place to document
+this.
+
+All classes set on a Puppet client are stored in an external file (usually
+``/etc/puppet/classes.txt``, but can be modified with the ``classfile``
+argument or setting).  This means other tools can easily read in the classes
+that Puppet sets and use them for their own logic.
+
+There is also (as of 0.15.4) a new command to set arbitrary classes that do
+not have any code associated with them::
+
+    class freebsd {
+        tag unix, bsd
+    }
+
+    class redhat {
+        tag unix, sysv
+    }
+
+These classes will then be written to the classes.txt file like all others,
+even though there is no code associated with them.  The syntax is just like
+``include``, so you can use variables, also::
+
+    tag $operatingsystem
+
+Nodes
+-----
+
+``node <hostname> { ... }``
+
+Node definitions specify the configuration to apply to a specific node.  By
+default they are looked for by ``puppetmasterd`` but not by ``puppet``.  See
+the documentation for each to enable or disable them.
+
+Any code outside of a node definition will be applied to all nodes, while any
+code inside will only apply to the specified node or nodes::
+
+    class webserver { ... }
+    class dbserver { ... }
+
+    file { "/etc/sudoers": mode => 440 } # apply to everyone
+
+    node host1, host2 {
+        include webserver
+    }
+    node host3, host4 {
+        include dbserver
+    }
+
+Nodes can also inherit from other nodes, so it's easy to apply defaults::
+
+    node base {
+        include $operatingsystem
+    }
+
+    node kirby inherits base {
+        include webserver
+    }
+
+Conditionals
+------------
+Puppet currently supports two types of conditionals: in-statement and around
+statements.  We call the in-statement conditionals ``selectors``, as they are
+essentially a select-style operator, which support the use of ``default`` to
+specify a default value::
+
+    define testing(os) {
+        owner = $os ? {
+            sunos => adm,
+            redhat => bin,
+            default => root
+        }
+        file { "/some/file": owner => $owner }
+    }
+
+
+
+``case`` provides the ability to conditionally apply
+types::
+
+    case $operatingsystem {
+        sunos:      { solaris {} } # apply the solaris class
+        redhat:     { redhat  {} } # apply the redhat class
+        default:    { generic {} } # apply the generic class
+    }
+
+Reserved words
+--------------
+Generally, any word that the syntax uses for special meaning is probably also
+a reserved word, meaning you cannot use it for variable or type names.  Thus,
+words like ``true``, ``define``, ``inherits``, and ``class`` are all reserved.
+
+Comments
+--------
+Puppet supports sh-style comments; they can either be on their own line or at
+the end of a line (see the Conditionals_ example above).
+
+.. _type reference: /projects/puppet/documentation/typedocs