All docs moved over now, and the real index page exists again

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

1 files changed, 0 insertions, 314 deletions

diff --git a/documentation/introduction.page b/documentation/introduction.page
deleted file mode 100644
index 837bbb305..000000000
--- a/documentation/introduction.page
+++ /dev/null
@@ -1,314 +0,0 @@
----
-inMenu: true
----
-# Introduction
-
-Puppet is a system configuration tool.  It has a library for managing the
-system, a language for specifying the configuration you want, and a set of
-clients and servers for communicating the configuration and other information.
-
-The library is entirely responsible for all action, and the language is
-entirely responsible for expressing configuration choices.  Everything is
-developed so that the language operations can take place centrally on a single
-server (or bank of servers), and all library operations will take place on each
-individual client.  Thus, there is a clear demarcation between language
-operations and library operations, as this document will mention.
-
-# Setup
-
-The vast majority of Puppet architectures will look like a star, with a
-central server running `puppetmasterd`, and each client node running
-`puppetd`, contacting that central server.  Your central manifest, which
-contains the configuration for all of your nodes, needs to be on the central
-server, most likely at `/etc/puppet/manifests/site.pp`.
-
-Start the `puppetmasterd` daemon, and then tell your clients to contact that
-server by specifying `-s <servername>` as arguments to `puppetd`,
-replacing ``<servername>`` with the name of the server.  Alternatively,
-`puppetd` defaults to looking for a server named ``puppet``, so you can just
-create a CNAME for your server, so that it answers to ``puppet``.
-
-It is a good idea to run both the server and client in verbose mode, enabled
-with the `-v` flag, until you are sure everything is working.  As each new
-client connects, you will need to run `puppetca --list` to list the
-certificates waiting to be signed, and then ``puppetca --sign <name>``,
-replacing ``<name>`` with the name of the client whose certificate you want to
-sign.  You can turn on autosigning by creating `/etc/puppet/autosign.conf` and
-put the hosts, domains, or IP addresses or ranges that you want to sign in
-there.
-
-# Language
-
-The language is declarative, and is modeled somewhat after cfengine's concept
-of actions, action instances, and instance parameters.  Here is how a file
-element would look in puppet:
-
-    file { "/etc/passwd":
-        owner => root,
-        group => root,
-        mode => 644
-    }
-
-Each instance of a low-level element like ``file`` must have a name parameter
-defined, because that is how you uniquely refer to the element you are
-managing.  Any string that doesn't match ``\w+`` or ``\d+`` needs to be quoted
-(e.g., file names).
-
-There are two ways for types to be available in the language:  They'll either
-be ``primitive types`` included in the Puppet framework itself, or they'll be
-``defined types`` resulting from definitions or server classes.
-
-## Definitions
-
-Because experience with cfengine showed that objects of different types are
-often related, puppet focuses on making creation of associations between
-objects of any type easier than making many objects of the same type.  The
-fundamental unit of association is a 'definition':
-
-    # currently, the variables don't have '$' attached in the definition prototype
-    # this might change
-    define sudo(source,group) {
-        package { sudo:
-            version => "1.6.7"
-        }
-        file { "/etc/sudoers":
-            source => $source, # parameterization; copy the file from where?
-            mode => 440 # the 'file' type converts this appropriately to
-                        # octal
-        }
-        file { "/usr/sbin/sudo":
-            owner => root,
-            group => $group
-        }
-    }
-
-A definition has its own scope, so variables defined within it are only
-available within the definition itself.
-
-This definition can now be treated as a type:
-
-    sudo {
-        group => root,
-        source => "http://fileserver/files/sudoers?v=production"
-    }
-
-One significant difference between definitions and types is that types
-generally have many associated parameters, most of which are optional, while a
-given definition will (at this point) always require all parameters.  You can
-manage as little or as much of a file as you want, for instance, but once you
-wrap it in a definition you have to pass every specified parameter to instances
-of the definition.
-
-It is appropriate to think of definitions as declarative functions; referring
-to the name of a definition results in the associated declarative code being
-executed with the provided parameters.
-
-I will likely soon add the ability to provide defaults to definition
-parameters; any other feature requests are welcome.
-
-## Classes
-
-In addition to definitions, the language supports server classes.  Classes are
-different from definitions in two fundamental ways:  They do not (currently)
-support parameterization, and sub classes can override base classes.
-
-Classes can be called using the same syntax as definitions, although always
-without arguments and usually without names, but they are generally called
-with the ``include`` keyword, which is more flexible in that it supports
-variable interpolation and conditional expressions:
-
-    class base {
-        include sudo
-    }
-
-    class server inherits base {
-        include ssh
-    }
-
-    case $hostname {
-        myhost: { include server }
-        default: { include base }
-    }
-
-    include $operatingsystem
-
-
-## Variables
-
-Because it is assumed that strings will be used far more than variables, simple
-strings don't have be quoted or otherwise marked, but variables must have the
-``$`` attached:
-
-    $group = "root"
-
-    file { "/etc/sudoers":
-        group => $group
-    }
-
-Strings and booleans (``true`` and ``false``) are the only data types; even
-numbers are converted to strings.  Arrays are supported, although their
-behaviour has not been characterized for all cases.  One particular use of
-arrays is for implicit iteration:
-
-    $files = ["/etc/passwd","/etc/group","/etc/fstab"]
-
-    file { $files:
-        owner => root,
-        group => root
-    }
-
-This implicitly iterates across the file list and performs all of the
-appropriate checks.
-
-Currently, ``puppet`` collects as much information as it can (using the
-``Facter`` library) and sets all of it as top-level variables.  So, you can
-expect variables like ``$operatingsystem`` and ``$ipaddress``.
-
-Also, because ``puppet`` is a declarative language, reassigning a variable
-within the same scope is currently an error.  The language is written such that
-this could be disabled (please let me know if you need this feature), but it is
-currently always enabled.  You can override defaults in a lower scope:
-
-    $var = default
-
-    define test {
-        $var = override
-        ...
-    }
-
-It is expected that parameter passing to definitions will be the primary
-mechanism for variable assignment, so it seems unlikely that this limitation
-will cause much trouble.
-
-## Importing
-
-Files can be imported using the ``import`` command:
-
-    import "filename"
-
-There is currently no search path or anything; files are looked for in the same
-directory as the file doing the importing.  Each file should have its own
-lexical scope, but I haven't yet figured out how to do that.
-
-## Control Structures
-
-There are currently two basic control structures, one meant to return a value
-and the other just a normal 'if/elsif/else' structure.
-
-### Selectors
-
-One of the primary goals of Puppet is to simplify building a single
-configuration that works across multiple machines and machine classes. One
-mechanism for this is currently called a 'selector'; it is similar to the
-trinary operator ``:?``:
-
-    $value = $variable ? {
-        value1 => setvalue1,
-        value2 => setvalue2,
-        default => other
-    }
-
-This sets the variable ``$value`` depending on the value of ``$variable``.  If
-it is ``value1``, then ``$value`` gets set to ``setvalue1``, else the value
-gets set to ``other``.
-
-The brackets can be in either part of the expression, or not at all:
-
-    $value = $variable ? "value1" => "setvalue1"
-
-A selector that doesn't match a value is a compile error.
-
-These structures are useful for simplistic abstraction across platforms:
-
-    file { "/etc/sudoers":
-        owner => root,
-        group => $operatingsystem ? {
-            SunOS => root,
-            Linux => root,
-            FreeBSD => wheel
-        }
-    }
-
-Selectors can specify default values using the ``default`` keyword.
-
-### Case Statements
-
-Puppet currently supports a normal Case structure similar to so many other
-languages:
-
-    case $operatingsystem {
-        solaris: { include sunos }
-        debian: { include linux }
-        default: { include $operatingsystem }
-    }
-
-As you can see, case statements also support defaults.
-
-The difference between the case stateements and the selectors is that the
-selectors just return values while the case statements execute arbitrary
-Puppet code.
-
-# Library
-
-This section discusses some aspects of the internals of the Puppet library.
-This information can be useful but is not critical for use and understanding
-of Puppet.
-
-The library is composed of two fundamental types of objects: Types and states
-(yes, the terminology is atrocious).  States are things that can be configured
-to change one aspect of an object (e.g., a file's owner), types are essentially
-named collections of states.  So, there is a File type, and it is a collection
-of all of the states available to modify files.
-
-In addition to states, which necessarily modify 'the bits on disk', as it were,
-types can also have non-state parameters which modify how that type instance
-behaves:
-
-    file { "/bin":
-        owner => bin,
-        recurse => true
-    }
-
-The ``recurse`` parameter to ``file`` does not modify the system itself, it
-modifies how the ``file`` type manages ``/bin``.
-
-Not all types as expressed in the language are types defined in the library;
-some language types are actually definitions or server classes.  Types that
-are defined in the language itself are termed ``primitive types`` or just
-``primitives``, and types that generate other types are termed ``metatypes``.
-
-At this point, all types have a unique name (within the current scope, but it
-probably should actually be global).  This name is set using a class instance
-variable: :
-
-    # in the library
-    Puppet::Type.newtype(:mytype)
-        ...
-    end
-
-    # in the language
-    mytype { "yay": ... }
-
-The states similarly have unique names, although this uniqueness is only
-per-type.  When a type is defined, all states and parameters are added using
-class methods.  Here is the File type declaration:
-
-    newstate(:ensure) do ... end
-    newstate(:owner) do ... end
-    newstate(:group) do ... end
-    ...
-    newparam(:path) do ... end
-
-Lastly, each type must either provide a state or parameter of ':name', or it
-must mark a parameter as the namevar so that the system knows what is
-considered the name:
-
-    newparam(:path) do 
-        isnamevar
-    end
-
-With this declaration, ``file { "/tmp/file": }`` is basically equivalent to ``file { path => "/tmp/file" }``.
-
-See [Creating a Puppet Type](creating-a-puppet-type.html) for more
-information.
-*$Id$*