diff --git a/documentation/documentation/installation.page b/documentation/documentation/installation.page index b7fa3099e..b5ea6d372 100644 --- a/documentation/documentation/installation.page +++ b/documentation/documentation/installation.page @@ -1,376 +1,378 @@ --- inMenu: true orderInfo: 3 --- # Comments If there is anything about this introduction that is unclear or not correct, please email luke at madstop.com about it or file a bug at [the bug tracker](/cgi-bin/puppet.cgi). # Getting the Files You will need to install Puppet on all machines that will use it, including both clients and servers. There are [packages][] available for some platforms, but for the rest you will have to install using the [tarball][] or [GEMs][]. Install instructions do not cover installing packages, since it is assumed you know how to retrieve and install packages for your specific platform. ## Prerequisites The only prerequisite for Puppet that doesn't come as part of the Ruby standard library is [facter][], which is also developed by Reductive Labs. All other prerequisites for Puppet are Ruby libraries, and they should all come with any standard Ruby 1.8.2 install. The other prerequisites, should your OS not come with the complete standard library, are: * **base64** * **cgi** * **digest/md5** * **etc** * **fileutils** * **ipaddr** * **openssl** * **strscan** * **syslog** * **uri** * **webrick** * **webrick/https** * **xmlrpc** ### Ruby I recommend using whatever Ruby comes with your system, since that's what I've tested against in most cases and it's most likely to work correctly. If you feel the particular need to build it manually, you can get the source from [the Ruby site](http://ruby-lang.org/). #### Red Hat Puppet and Facter are now available in Fedora Extras, thanks to David Lutterkort at Red Hat. Fedora users should be able to retrieve them via yum from the Fedora Extras repository. Users of RHEL4 can get the package from David's [yum repository](http://people.redhat.com/dlutter/yum/rhel4). Please let the puppet-users mailing list know if you have built RPM's for RHEL2.1 or RHEL3 (or the equivalent CentOS builds) If you are building ruby on Red Hat (at least on version 3), you apparently must build it with ``CPPFLAGS=-I/usr/kerberos/include/``, else you will have all kinds of unreasonable problems (thanks to Mario Martelli for tracking that one down). #### Solaris There are Solaris packages for Puppet and Facter in the [downloads](http://reductivelabs.com/downloads/packages/SunOS. These packages suffice for both sparc and x86 (even though they're marked x86), but they don't specify dependencies. They're automatically built during new releases, so they should always be the latest. I have had mixed results with the Ruby packages from both [Sunfreeware](http://sunfreeware.com) and [BlastWave](http://www.blastwave.org). It might almost be easier to compile it manually for Solaris, but Ruby 1.8.4 from BlastWave seems to be working right now. If you get segfaults, core dumps, or 'library missing ciphers' errors, that is almost definitely a problem with that specific ruby package, not Puppet or Ruby itself. #### Debian and Ubuntu -Facter and Puppet now have quality Debian packges , thanks to Matthew Palmer -and Jamie Wilkinson. You can download these packages from any Debian mirror. +Facter and Puppet now have quality +[Debian packges](http://packages.debian.org/unstable/admin/puppet), +thanks to Matthew Palmer and Jamie Wilkinson. You can download these packages +from any Debian mirror. The package maintainer for Ruby on these platforms has decided to split the Ruby standard library into many packages. According to Eric Hollensbe, this is the package dependency list for Puppet on Debian: * ruby * irb * ri * rdoc * libxmlrpc-ruby * libopenssl-ruby * libstrscan-ruby * libsyslog-ruby * libwebrick-ruby ##### Note on Debian/Testing Note that **libruby1.8** versions above **1.8.4-1** on Debian/testing seem to be broken, resulting in segfaults. Until an update gets released to fix this, you should pin to library1.8, by putting something like the following into ``/etc/apt/preferences``: Package: libruby1.8 Pin: version 1.8.4-1 Pin-Priority: 1001 If you have already upgraded your library1.8 package, you can downgrade it by adding ``deb http://snapshot.debian.net/archive pool ruby1.8`` to your ``/etc/apt/sources.list`` and then running ``apt-get install libruby1=1.8.4-1``. #### SuSE Martin Vuk is maintaining a SuSE [yum repository](http://lmmri.fri.uni-lj.si/suse/) with Puppet and Facter packages. #### Gentoo There are [now](http://www.mail-archive.com/gentoo-server@lists.gentoo.org/msg02175.html) ebuilds available for Puppet, created by José González Gómez. Also, as of September 2006 there is a problem with the PPC Ruby package that causes ``rdoc/usage`` to fail. The bug has been reported to the Gentoo folks. ### Facter First install facter. Like Puppet, there are [packages][] available for some platforms, but you might have to use the tarball: # get the latest tarball wget http://reductivelabs.com/downloads/facter/facter-latest.tgz # untar and install it gzip -d -c facter-latest.tgz | tar xf - cd facter-* sudo ruby install.rb # or become root and run install.rb There are also gems available in the [download][] directory. ## Install Puppet Using the same mechanism, install the puppet libraries and executables: # get the latest tarball wget http://reductivelabs.com/downloads/puppet/puppet-latest.tgz # untar and install it gzip -d -c puppet-latest.tgz | tar xf - cd puppet-* sudo ruby install.rb # or become root and run install.rb ## Alternative: Using RubyGems You can also use Reductive Labs' Gems server to install Facter and Puppet: gem install --remote --source http://reductivelabs.com/downloads facter gem install --remote --source http://reductivelabs.com/downloads puppet For more information on RubyGems, see the [Gems User Guide][]. ## Alternative alternative: Native Packages It is our goal to provide as many native packages as possible, but it's been slow going. Until I have official native packages, David Lutterkort used spec and init files from Duane Griffin to create native RPMs that should work on Red Hat Enterprise 4 and Fedora Core 4. You can get them from his [yum repository][]. There are also [Debian packages][], although they are not quite as well maintained as the RPMs. # Building the Server ## Create Your Site Manifest Because the Puppet language is declarative, it does not make as much sense to speak of "executing" Puppet programs, or to describe them as "scripts". We choose to use the word *manifest* to describe Puppet programs, and we speak of *applying* those manifests to the local system. Thus, a *manifest* is a text document written in the Puppet language and meant to result in a desired configuration. Puppet is written with the assumption that you will have one central manifest capable of configuring your entire network, which we call the *site manifest*. You could have multiple, separate site manifests if you wanted, but at this point each of them would need their own servers. For more information on how to create the site manifest, see the [Language Reference][] and the [Library Reference][]. Puppet will look for your site manifest in ``/etc/puppet/manifests/site.pp``, so create ``/etc/puppet/manifests`` and add your manifest, along with any files it includes, to that directory. It is highly recommended that you use some kind of [version control][] on your manifests. ### Example Manifests The site manifest can be as simple or as complicated as you want. A good starting point is to make sure that your sudoers file has the appropriate permissions: # site.pp file { "/etc/sudoers": owner => root, group => root, mode => 440 } If you want to get more complicated, it's a good idea to split your manifest into multiple files. For instance, you could split it based on operating systems (e.g., Solaris and Red Hat) and server classes (e.g., 'webserver' and 'logserver'). I also find it useful to have a set of functions, in an external file included first: # site.pp # import the functions import "functions.pp" # import all of the os classes, like redhat.pp and solaris.pp import "os/*" # import all of the server classes, like webserver.pp import "classes/*" Here's an example of a generically useful function I use; it encapsulates the source of files that I copy from a central server, and just saves a little typing: # functions.pp define remotefile(owner = root, server = puppet, group = root, mode, source, backup = false, recurse = false) { file { $name: mode => $mode, owner => $owner, group => $group, backup => $backup, source => "puppet://$server/dist/$source" } } You would use the function like this: remotefile { "/etc/sudoers": mode => 440, source => "apps/sudo/sudoers" } ## Start the Central Daemon Most sites should only need a single central server. Reductive Labs will soon publish a document describing how to build puppet architectures with failover capabilities and achitectures that are capable of handling large loads, but for now only a single server is supported. Decide which machine you want to be your central server; this is where you will be starting ``puppetmasterd``. The best way to start any daemon is using your local server's service management system, often in the form of ``init`` scripts. Eventually Puppet will ship with an appropriate script for each platform (it already has appropriate scripts for Red Hat, Debian, and Solaris), but in the meantime you can either create your own, using an existing script as an example, or simply run without one (not recommended for production environments). Other than the system manifest at ``/etc/puppet/manifests/site.pp``, the last thing you'll need is to create the puppet user and group that the daemon runs as. You can create these manually, or you can just start the daemon with the ``--mkusers`` flag, and it should create both of them for you (of course, this flag is only necessary the first time the daemon is run): /usr/bin/puppetmasterd --mkusers Even without the ``mkusers`` flag, it will automatically create all necessary certificates, directories, and files. If you want the daemon to also function as a file server, so your clients can copy files from it, you will need to create a [fileserver configuration file][]; the daemon checks for the existence of this file at startup and automatically enables or disables file serving functionality. If you are still only testing, and do not have node definitions in your site manifest (such as with the above example manifest) , tell ``puppetmasterd`` not to look for them: /usr/bin/puppetmasterd --nonodes Otherwise, you will need to define each of your nodes in your site manifest: node culain { include workstation } Alternatively, you can tell ``puppetmasterd`` to use [LDAP for node storage](ldapnodes.html). # Verifying Installation To verify that your daemon is working as expected, pick a single client to use as a testbed. Once Puppet is installed on that machine, run a single client against the central server to verify that everything is working appropriately. You should start the first client in verbose mode, with the ``--waitforcert`` flag enabled: puppetd --server myserver.domain.com --waitforcert 60 --test The default server for ``puppetd`` is ``puppet``, so you could just create a CNAME of that to whatever server is running ``puppetmasterd``. Adding the ``--test`` flag here is equivalent to adding ``--verbose --onetime --no-usecacheonfailure``. This causes ``puppetd`` to stay in the foreground, print extra output, only run once and then exit, and to just exit if the remote configuration fails to compile (by default, ``puppetd`` will use a cached configuration if there is a problem with the remote manifests). In running the client, you should see a message that the client did not receive a certificate (this message will repeat every 60 seconds with the above command). This is normal, since your server is not autosigning certificates as a security precaution. On your server, list the waiting certificates: puppetca --list You should see the name of the test client. Now go ahead and sign the certificate: puppetca --sign mytestclient.domain.com Within 60 seconds, your test client should receive its certificate from the server, receive its configuration, apply it locally, and exit normally. By default, ``puppetd`` runs with a ``waitforcert`` of five minutes; set the value to 0 to disable it entirely. # Finishing Installation There are already init scripts available for some platforms (notably, Red Hat versions, thanks to David Lutterkort's work on the [RPMs][]), but for not-yet-supported platforms, you will need to create an init script that can start and stop ``puppetd``. The process creates a PID file in its run directory (``/var/puppet/run``, by default), so you can use that to stop it. The process will log to syslog by default in the daemon facility. Beta Notes ========== There are some important notes to keep in mind about using the current versions of Puppet: * Files are currently automatically reread when they are changed, within a timeout of 60 seconds. * Patches are welcome and encouraged. [developed]: /projects/facter/ [download]: /downloads/ [version control]: http://svnbook.red-bean.com/ [fileserver configuration file]: fsconfigref [Gems User Guide]: http://docs.rubygems.org/read/book/1 [Language Reference]: structures.html [Library Reference]: typedocs.html [packages]: /downloads/packages/ [tarball]: /downloads/puppet/ [gems]: /downloads/gems/ [rpms]: /downloads/rpm/ [yum repository]: http://people.redhat.com/~dlutter/yum/ [debian packages]: /downloads/packages/Debian/ *$Id$*