documentation updates

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

1 files changed, 233 insertions, 0 deletions

diff --git a/documentation/faq.page b/documentation/faq.page
new file mode 100644
index 000000000..865bc2498
--- /dev/null
+++ b/documentation/faq.page
@@ -0,0 +1,233 @@
+---
+inMenu: true
+title: FAQ
+---
+What is Puppet?
+----------------
+Puppet is an open-source next-generation server automation tool.  It is
+composed of a *declarative* language for expressing system configuration, a
+*client* and *server* for distributing it, and a *library* for realizing the
+configuration.
+
+The primary design goal of Puppet is that it have an expressive enough
+language backed by a powerful enough library that you can write your own
+server automation applications in just a few lines of code.  With Puppet, you
+can express the configuration of your entire network in one program capable of
+realizing the configuration.  The fact that Puppet has open source combined
+with how easily it can be extended means that you can add whatever
+functionality you think is missing and then contribute it back to the main
+project if you desire.
+
+You can learn more about Puppet by reading its [Documentation][].
+
+What license is Puppet released under?
+--------------------------------------
+Puppet is open source and is released under the [GNU Public License][].
+
+Why does Puppet exist?
+----------------------
+Luke Kanies, who founded Reductive Labs, has been doing server automation for
+years, and Puppet is the result of his frustration with existing tools.  After
+significant effort spent trying to enhance cfengine, plus a stint at a
+commercial server automation vendor, Luke concluded that the only way to get a
+great automation tool was to develop one.
+
+Puppet is actually the result of years of design and prototyping (called Blink
+during its prototype phases), but only in 2005 was a commercial company
+(Reductive Labs) built to be fully dedicated to its creation.  If Puppet is
+not the most powerful and most flexible server automation platform available,
+then its goals are not being met.
+
+Why does Puppet have its own language?
+--------------------------------------
+This actually is a frequently asked question, and people most often ask why I
+did not choose to use something like XML or YAML as the configuration
+format; otherwise people ask why I didn't just choose to just use Ruby as the
+input language.
+
+The input format for Puppet is not XML or YAML because these are data formats
+developed to be easy for computers to handle.  They do not do conditionals
+(although, yes, they support data structures that could be considered
+conditionals), but mostly, they're just horrible human interfaces.  While some
+people are comfortable reading and writing them, there's a reason why we use
+web browsers instead of just reading the HTML directly.  Also, using XML or
+YAML would limit the ability to make sure the interface is declarative -- one
+process might treat an XML configuration differently from another.
+
+As to just using Ruby as the input format, that unnecessarily ties Puppet to
+Ruby, which is undesirable, and Ruby provides a bit too much functionality.
+For more detail, see the [thread][] on the puppet-dev list.
+
+
+How does Puppet compare to cfengine?
+------------------------------------
+Puppet could be said to be the next-generation cfengine.  The overall design
+is heavily influenced by cfengine, but the language is more powerful than
+cfengine's and the library is more flexible.  In addition, Puppet's client and
+server use standard protocols like XMLRPC and are easy to enhance with new
+functionality, so they are well-positioned to become the platform for the
+network applications of the future, while cfengine's client and server rely
+entirely on cfengine-specific protocols and are quite difficult to enhance.
+
+See [How Puppet Compares to Cfengine][] for more information.
+
+How does Puppet compare to available commercial products?
+---------------------------------------------------------
+The primary commercial vendors are BladeLogic and OpsWare.  While they both
+have useful product lines, Puppet surpasses them by reframing the entire
+server automation problem -- while the commercial vendors are writing GUI
+applications for you, Reductive Labs is providing a development platform with
+all the features of a great language, like library development, code sharing,
+and the ability to version control your configurations.
+
+Trying to express a complex network configuration entirely through a GUI is an
+exercise in frustration that no one should suffer, but expressing the
+abstraction necessary to share those GUI configurations goes beyond
+frustrating.
+
+Of course, another great difference between Puppet and the commercial products
+is that Puppet is open sourced under the [GNU Public License][].  You can
+[download][] the product, try it out, peruse the source, and make whatever
+modifications you want.  You have to have more than 100 servers just to get a
+demo from the commercial vendors, but Puppet is available for testing by any
+company that needs to reduce its server administration costs.
+
+Who would find Puppet useful?
+-----------------------------
+Any organization that would like to reduce the cost of maintaining its
+computers could benefit from using Puppet.  However, because the return on
+investment is linked to multiple factors, like current administrative
+overhead, diversity among existing computers, and cost of downtime, it can be
+difficult for organizations to determine whether they should invest in any
+configuration management tools, much less Puppet.  Reductive Labs can always
+be contacted directly at info at reductivelabs.com to help answer this question.
+
+Generally, however, an organization should be using server automation if any
+of the following are true:
+
+* It has high server administration costs
+* It pays a high price for downtime, either because of contracts or
+  opportunity cost
+* It has many servers that are essentially either identical or nearly
+  identical
+* Flexibility and agility in server configuration are essential
+
+Can Puppet manage workstations?
+-------------------------------
+Yes, Puppet can manage any type of machine.  We have found that most
+organizations are more concerned with server management than workstation
+management, and frankly, the term 'server' is slightly more aesthetically
+appealing than 'computer', but Puppet would be ideal for organizations with a
+large number of workstations.
+
+Does Puppet run on Windows?
+---------------------------
+The short answer is 'not yet'.  It will eventually, but Reductive Labs does
+not yet have the development bandwidth to make this work.
+
+What size organizations should use Puppet?
+------------------------------------------
+There is no minimum or maximum organization size that can benefit from Puppet,
+but there are sizes that are more likely to benefit.  Organizations with fewer
+than 10-20 servers are unlikely to consider maintaining those servers to be a
+real problem, and thus they can avoid investment in tools even though those
+tools could likely provide savings.
+
+There is no real upper limit to who could benefit from using Puppet.
+Obviously as the server count increases the investment must increase somewhat,
+but with Puppet that increase is not linear.
+
+My servers are all unique; can Puppet still help?
+-------------------------------------------------
+All servers are at least somewhat unique -- with different host names and
+different IP addresses -- but very few servers are entirely unique, since
+nearly every one runs a relatively standard operating system.  Servers are
+also often very similar to other servers within a single organization -- all
+Solaris servers might have similar security settings, or all web servers might
+have roughly equivalent configurations -- even if they're very different from
+servers in other organizations.  Finally, servers are often needlessly unique,
+in that they have been built and managed manually with no attempt at retaining
+appropriate consistency.
+
+Puppet can help both on the side of consistency and uniqueness.  Puppet
+can be used to express the consistency that should exist, even if
+that consistency spans arbritrary sets of servers based on any type of data
+like operating system, data center, or physical location.  Puppet can also be
+used to handle uniqueness, either by allowing special provision of what makes
+a given host unique or through specifying exceptions to otherwise standard
+classes.
+
+Who is Reductive Labs?
+----------------------
+Reductive Labs is a small, private company focused on reframing the server
+automation problem.  Our primary focus is Puppet, but Reductive Labs also
+provides automation consulting, training, and custom development.  For more
+information email info at reductivelabs.com.
+
+The [Projects][] page lists our active projects.
+
+How Do I Install Puppet?
+------------------------
+
+The [Installation Guide][] documents the fastest way to start using Puppet.
+
+What is a Manifest?
+-------------------
+Because the word *script* implies a procedural one-step-after-another program,
+the word does not apply well to Puppet programs.  Thus, we use the word
+*manifest* to describe declarative Puppet programs.  Speaking of applying,
+Puppet *applies* a manifest to a server or a network, rather than *executing*
+it.
+
+How Do I Write Manifests?
+-------------------------
+The best way is to download Puppet and just start writing.  There are multiple
+sets of examples, including the [examples][] used in [unit testing][],
+and the [reference][]will obviously be useful.
+
+How Do I Run Manifests?
+-----------------------
+Once you have Puppet installed according the the [Installation Guide][],
+just run the ``puppet`` executable against your example:
+
+    puppet -v example.pp
+
+How do I contribute?
+--------------------
+First join the [Mailing List][] -- there is currently only a development list,
+but as the community grows a user list will be created.  You can also join the
+IRC channel ``#puppet`` on irc.freenode.net, where Puppet's developers will be
+hanging out most days (and nights).
+
+The most valuable contribution you can make, though, is to use Puppet and
+submit your feedback, either directly on IRC or through the mailing list, or
+via the [bug database][].  We're always looking for great ideas to incorporate
+into Puppet.
+
+When is the Next Release?
+-------------------------
+There are regular feature and release updates on the [Mailing List][],
+and you can always find the latest release in the [download][] directory.
+
+I keep getting "certificates were not trusted".  What's wrong?
+--------------------------------------------------------------
+Historically this has usually been a problem with the client machine having
+such a different date setting that the certificate is not yet valid.
+
+You can figure the problem out by manually verifying the certificate with
+openssl:
+
+    sudo openssl verify -CAfile /etc/puppet/ssl/certs/ca.pem /etc/puppet/ssl/certs/myhostname.domain.com.pem
+
+[Mailing List]: http://mail.madstop.com/mailman/listinfo/puppet-dev
+[Projects]: /projects/
+[Documentation]: index.html
+[Installation Guide]: installation.html
+[How Puppet Compares to Cfengine]: notcfengine.html
+[GNU Public License]: http://www.gnu.org/copyleft/gpl.html
+[examples]: /cgi-bin/puppet.cgi/browser/trunk/examples/code/
+[unit testing]: http://www.pragmaticprogrammer.com/starter_kit/ut/
+[bug database]: /cgi-bin/puppet.cgi/report
+[reference]: typedocs.html
+[download]: /downloads
+[thread]: http://mail.madstop.com/pipermail/puppet-dev/2006-April/000393.html