From f24a0848ca5884bed65d84abc6f8f3eabf33f91a Mon Sep 17 00:00:00 2001 From: Nico Schottelius Date: Thu, 15 Nov 2012 11:30:34 +0100 Subject: [PATCH] add new cdist 2.1 documentation Signed-off-by: Nico Schottelius --- software/cdist.mdwn | 330 +---------------------------- software/cdist/cdist-logo.png | Bin 0 -> 1542 bytes software/cdist/features.mdwn | 26 +++ software/cdist/install-update.mdwn | 218 +++++++++++++++++++ software/cdist/support.mdwn | 25 +++ 5 files changed, 274 insertions(+), 325 deletions(-) create mode 100644 software/cdist/cdist-logo.png create mode 100644 software/cdist/features.mdwn create mode 100644 software/cdist/install-update.mdwn create mode 100644 software/cdist/support.mdwn diff --git a/software/cdist.mdwn b/software/cdist.mdwn index ffd0bcb5..ab501f56 100644 --- a/software/cdist.mdwn +++ b/software/cdist.mdwn @@ -1,25 +1,7 @@ [[!meta title="cdist - usable configuration management"]] - - .. . .x+=:. s - dF @88> z` ^% :8 - '88bu. %8P . = 2.0.4)](man) + * Browse the **documentation** for the [latest version](man/latest) or [all versions (>= 2.0.4)](man) + * Read how to [[install or update cdist|install-update]] + * [[Support|support]] ### OS support @@ -68,6 +22,7 @@ cdist was tested or is know to run on at least * [Debian](http://www.debian.org/) * [CentOS](http://www.centos.org/) * [Fedora](http://fedoraproject.org/) + * [FreeBSD](http://www.freebsd.org) * [Gentoo](http://www.gentoo.org/) * [Mac OS X](http://www.apple.com/macosx/) * [OpenBSD](http://www.openbsd.org) @@ -75,279 +30,4 @@ cdist was tested or is know to run on at least * [Ubuntu](http://www.ubuntu.com/) * [XenServer](http://www.citrix.com/xenserver/) - -## Requirements - -### Server - - * A posix like shell - * Python (>= 3.2 required) - * SSH client - * Asciidoc (for building the manpages) - -### Client ("target host") - - * A posix like shell - * SSH server - - -## Installation - -### Preparation - -Ensure you have Python 3.2 installed on the machine you use to **deploy to the targets** -(the ***source host***). - -#### Archlinux - -Archlinux already has python >= 3.2, so you only need to do: - - pacman -S python - -#### CentOS - -See the "From source" section - -#### Debian - -For Debian >= wheezy: - - aptitude install python3 - -On squeeze you can add following line in **/etc/apt/sources.list** - - deb http://ftp.debian.org/debian wheezy main - -And add pinning entry in **/etc/apt/preferences.d/wheezy**: - - Package: * - Pin: release n=wheezy - Pin-Priority: 1 - -Please be aware that both **openssh-server** and **openssh-client** might be -removed on **python3.2** installation. You surely want to reinstall them: - - apt-get install -t wheezy openssh-server openssh-client - -For older Debian versions, installing python 3.2 manually is required. - - -#### Fedora - -For Fedora >= 15: - - yum install python3 - -#### FreeBSD - -For the port: - - cd /usr/ports/lang/python32/ && make install clean - -For the package: - - pkg_add -r python32 - -#### Gentoo - -Gentoo only provides python 3.2 in testing packages (http://www.gentoo.org/doc/en/handbook/handbook-x86.xml?part=3&chap=3). -If you want to ensure nothing breaks you must set back the python version to what was default before. - - emerge -av =python-3.2.2 --autounmask-write - emerge -av =python-3.2.2 - eselect python list - eselect python list set python3.2 - -#### Max OS X - -You can choose between Homebrew and Macports, either way works: - -[Homebrew](http://mxcl.github.com/homebrew/) variant: - - brew install python3 - -[Macports](http://www.macports.org/install.php) variant: - - port install python32 - ln -s /opt/local/bin/python3.2 /opt/local/bin/python3 - -#### From Source - -For those operating systems not yet support Python 3.2: - - pyversion=3.2.3 - wget http://www.python.org/ftp/python/$pyversion/Python-${pyversion}.tar.bz2 - tar xvfj Python-${pyversion}.tar.bz2 - cd Python-${pyversion} - ./configure - make - sudo make install - -This installs python 3.2 to /usr/local/bin. Ensure this directory is in -your PATH environment variable. - - -### Get cdist - -You can clone cdist from git, which gives you the advantage of having -a version control in place for development of your own stuff as well. -To install cdist, execute the following commands: - - git clone git://git.schottelius.org/cdist - cd cdist - export PATH=$PATH:$(pwd -P)/bin - - # If you want the manpages - ./build man - export MANPATH=$MANPATH:$(pwd -P)/doc/man - - -### Available versions - -There are at least the following branches available: - - * Development: master - * 2.0: Python rewrite of cdist core [stable branch] - -Old versions: - - * 1.7: Bugfixes, cleanups, new type and explorer rename - * 1.6: New types, cleaned up \_\_package* types, internal cleanup - * 1.5: Focus on object orientation instead of global stage orientation - * 1.4: Support for redefiniton of objects (if equal) - * 1.3: Support for local and remote code execution (current stable) - * 1.2: Dependencies supported - * 1.1: \_\_file to \_\_file, \_\_directory, \_\_link migration - * 1.0: First official release - -Other branches may be available for features or bugfixes, but they -may vanish at any point. To select a specific branch use - - # Generic code - git checkout -b origin/ - - # Stay on a specific version - version=2.0 - git checkout -b $version origin/$version - -### Mirrors - - * git://github.com/telmich/cdist.git ([github](https://github.com/telmich/cdist)) - * git://git.code.sf.net/p/cdist/code ([sourceforge](https://sourceforge.net/p/cdist/code)) - -## Update - -To upgrade cdist in the current branch use - - git pull - - # Also update the manpages - ./build man - export MANPATH=$MANPATH:$(pwd -P)/doc/man - -If you stay on a version branche (i.e. 1.0, 1.1., ...), nothing should break. -The master branch on the other hand is the development branch and may not be -working, break your setup or eat the tree in your garden. - -### Upgrading from 1.7 to 2.0 - -* Ensure python (>= 3.2) is installed on the server -* Use "cdist config host" instead of "cdist-deploy-to host" -* Use "cdist config -p host1 host2" instead of "cdist-mass-deploy" -* Use "cdist banner" for fun -* Use **\_\_object_fq** instead of **\_\_self** in manifests - -### Upgrading from 1.6 to 1.7 - -* If you used the global explorer **hardware_type**, you need to change - your code to use **machine** instead. - -### Upgrading from 1.5 to 1.6 - -* If you used **\_\_package_apt --preseed**, you need to use the new - type **\_\_debconf_set_selections** instead. -* The **\_\_package** types accepted either --state deinstalled or - --state uninstaaled. Starting with 1.6, it was made consistently - to --state removed. - -### Upgrading from 1.3 to 1.5 - -No incompatiblities. - -### Upgrading from 1.2 to 1.3 - -Rename **gencode** of every type to **gencode-remote**. - -### Upgrading from 1.1 to 1.2 - -No incompatiblities. - -### Upgrading from 1.0 to 1.1 - -In 1.1 the type **\_\_file** was split into **\_\_directory**, **\_\_file** and -**\_\_link**. The parameter **--type** was removed from **\_\_file**. Thus you -need to replace **\_\_file** calls in your manifests: - - * Remove --type from all \_\_file calls - * If type was symlink, use \_\_link and --type symbolic - * If type was directory, use \_\_directory - - -## Support - -### IRC - -You can join the development ***IRC channel*** -[#cstar on irc.freenode.net](irc://irc.freenode.org/#cstar). - -### Mailing list - -Bug reports, questions, patches, etc. should be send to the -[cdist mailing list](http://l.schottelius.org/mailman/listinfo/cdist). - -### Linkedin - -If you have an account -at [Linked in](http://www.linkedin.com/), -you can join the -[cdist group](http://www.linkedin.com/groups/cdist-configuration-management-3952797). - -### Commercial support - -You can request commercial support for cdist from -[my company](http://firma.schottelius.org/english/). - -## Used by - -If you're using cdist, feel free to send a report to the mailing list. -Interesting information are for instance - - * Which services do you manage? - * How many machines do you manage? - * What are the pros/cons you see in cdist? - * General comments/critics - -### Nico Schottelius, Systems Group ETH Zurich, local.ch and privately - -Yes, I'm actually eating my own dogfood and currently managing - - * [plone](http://plone.org/) (cms) - * [moinmoin](http://moinmo.in/) (wiki) - * [apache](http://httpd.apache.org/) (webserver) - * [kerberos (mit)](http://web.mit.edu/kerberos/) (authentication) - * [nss-pam-ldapd](http://arthurdejong.org/nss-pam-ldapd/) (authentication) - * [ircd-hybrid](http://www.ircd-hybrid.org/) (chat) - * [stunnel](http://stunnel.mirt.net/) (SSL tunnel) - * [mercurial-server](http://www.lshift.net/mercurial-server.html) (version control) - * [xfce](http://www.xfce.org/) (lightweight desktop environment) - * [slim](http://slim.berlios.de/) (graphical login manager for X11) - -with cdist on more than **60** production machines of the -[Systems Group](http://www.systems.ethz.ch) at the -[ETH Zurich](http://www.ethz.ch) as well at home. - -### Steven Armstrong, CBRG ETH Zurich - -The CBRG is managing most of their compute clusters with cdist. - [[!tag cdist unix]] diff --git a/software/cdist/cdist-logo.png b/software/cdist/cdist-logo.png new file mode 100644 index 0000000000000000000000000000000000000000..13c2792728d20511f18ae60df8524d68b8a35cbf GIT binary patch literal 1542 zcmV+h2Ko7kP)Px#22e~?MF0Q*|NsA`*`M72000SaNLh0L01FcU01FcV0GgZ_00007bV*G`2ipS@ z0U8oZ%R(#w00o9gL_t(o!|j;OOC(1Wz^mIa(<@6fGKU5*AnRX5Vhb0Zp zl-0j^^}hPms}|z_>pi<{At%Dr`U@U4gF4RoGSKpzdV%|9@IftRZLXV9@rE>N@N!C~ zGe!OUp&qdMyVA_e*UFQ*nQ6FwG6UDY#;;ZQdr1m53*5jARMf$*1#sLK#5utjPU&db zU785>|Q;`jcYt&fW8y13Dv?GjzEFS5zgd^L_8Dcpp*UC7%Q|3g| zeW!0Xc2ln5Rr4S=Vw`9rom{QR%eaLoD99VfwGKs%e!wYXuc>Ro!YNg8JEj$j^K%vMI*!X+fZJ61zup&| z_&2@o@#j2c4Ow58Hv--l{9E;X!t)PThohc&SqQ&#?tli zeQ~q`w_7_Q4-|PvJ%@O73;v3uexPskGwxuUxYYml(wYAUI%ek9r9qEY?};s1j`9Ns zws+2%V_kFL`}_%&3B=6YnssgO7v^UEE^rn<`DuRG-WhWykyiNA+NRs7e#(n=#)dSo zC4b`2WX@hcQKUGP1Q;~i_~10#_Lg>}wnLWcfIX@<+++6!>FOsE(lNYg;o!>kuYLrZ zgn0Pmn(d&{8hK&l4S+j!SA~?-kZ(d{hS{KtRyo7mHqy$s_JuIA?hdVknB7 zLmcRLeo>TXD!t|!#KppS^(U1G?uTqIrW6TN&L%q)1U|fh!8$5_6|fyo5;wJD>?Nn8 z7@(SuyO_)`(2ft;4l8l7-_6;9W~(mlmj~#Vqtq{l($Q`rzu?yO%mX=fdC=B&2+U{e4Ydo2tmeVMoEvfXx48|#$#HqW zTvw#rm^=`@-JY`kV#Va)&A7P1?!T;r((*!4!$HtGcXKPzc`S^6g>{Se%ENDB0rpaV z5LWU)8vnI-KXJt}pCil*k@~kQ_nrqXYSH9EMl)|%efJ-1(-zZu5F_WnM!-h{74^xT z;0|clXTjlN%3T{{fFAO-|Ift!@>@-G2m|qxhyoK=0!BZA|iCn43h9NNJLMXkOv16dzyd&)Y5*|k+R=&8w!jnSNv6LK39 saY9X~U}r+kn~+= 3.2 required) + * SSH client + * Asciidoc (for building the manpages) + +### Client ("target host") + + * A posix like shell + * SSH server + + +## Installation + +### Preparation + +Ensure you have Python 3.2 installed on the machine you use to **deploy to the targets** +(the ***source host***). + +#### Archlinux + +Archlinux already has python >= 3.2, so you only need to do: + + pacman -S python + +#### CentOS + +See the "From source" section + +#### Debian + +For Debian >= wheezy: + + aptitude install python3 + +On squeeze you can add following line in **/etc/apt/sources.list** + + deb http://ftp.debian.org/debian wheezy main + +And add pinning entry in **/etc/apt/preferences.d/wheezy**: + + Package: * + Pin: release n=wheezy + Pin-Priority: 1 + +Please be aware that both **openssh-server** and **openssh-client** might be +removed on **python3.2** installation. You surely want to reinstall them: + + apt-get install -t wheezy openssh-server openssh-client + +For older Debian versions, installing python 3.2 manually is required. + + +#### Fedora + +For Fedora >= 15: + + yum install python3 + +#### FreeBSD + +For the port: + + cd /usr/ports/lang/python32/ && make install clean + +For the package: + + pkg_add -r python32 + +#### Gentoo + +Gentoo only provides python 3.2 in testing packages (http://www.gentoo.org/doc/en/handbook/handbook-x86.xml?part=3&chap=3). +If you want to ensure nothing breaks you must set back the python version to what was default before. + + emerge -av =python-3.2.2 --autounmask-write + emerge -av =python-3.2.2 + eselect python list + eselect python list set python3.2 + +#### Max OS X + +You can choose between Homebrew and Macports, either way works: + +[Homebrew](http://mxcl.github.com/homebrew/) variant: + + brew install python3 + +[Macports](http://www.macports.org/install.php) variant: + + port install python32 + ln -s /opt/local/bin/python3.2 /opt/local/bin/python3 + +#### From Source + +For those operating systems not yet support Python 3.2: + + pyversion=3.2.3 + wget http://www.python.org/ftp/python/$pyversion/Python-${pyversion}.tar.bz2 + tar xvfj Python-${pyversion}.tar.bz2 + cd Python-${pyversion} + ./configure + make + sudo make install + +This installs python 3.2 to /usr/local/bin. Ensure this directory is in +your PATH environment variable. + + +### Get cdist + +You can clone cdist from git, which gives you the advantage of having +a version control in place for development of your own stuff as well. +To install cdist, execute the following commands: + + git clone git://git.schottelius.org/cdist + cd cdist + export PATH=$PATH:$(pwd -P)/bin + + # If you want the manpages + ./build man + export MANPATH=$MANPATH:$(pwd -P)/doc/man + + +### Available versions + +There are at least the following branches available: + + * Development: master + * 2.0: Python rewrite of cdist core [stable branch] + +Old versions: + + * 1.7: Bugfixes, cleanups, new type and explorer rename + * 1.6: New types, cleaned up \_\_package* types, internal cleanup + * 1.5: Focus on object orientation instead of global stage orientation + * 1.4: Support for redefiniton of objects (if equal) + * 1.3: Support for local and remote code execution (current stable) + * 1.2: Dependencies supported + * 1.1: \_\_file to \_\_file, \_\_directory, \_\_link migration + * 1.0: First official release + +Other branches may be available for features or bugfixes, but they +may vanish at any point. To select a specific branch use + + # Generic code + git checkout -b origin/ + + # Stay on a specific version + version=2.0 + git checkout -b $version origin/$version + +### Mirrors + + * git://github.com/telmich/cdist.git ([github](https://github.com/telmich/cdist)) + * git://git.code.sf.net/p/cdist/code ([sourceforge](https://sourceforge.net/p/cdist/code)) + +## Update + +To upgrade cdist in the current branch use + + git pull + + # Also update the manpages + ./build man + export MANPATH=$MANPATH:$(pwd -P)/doc/man + +If you stay on a version branche (i.e. 1.0, 1.1., ...), nothing should break. +The master branch on the other hand is the development branch and may not be +working, break your setup or eat the tree in your garden. + +### Upgrading from 1.7 to 2.0 + +* Ensure python (>= 3.2) is installed on the server +* Use "cdist config host" instead of "cdist-deploy-to host" +* Use "cdist config -p host1 host2" instead of "cdist-mass-deploy" +* Use "cdist banner" for fun +* Use **\_\_object_fq** instead of **\_\_self** in manifests + +### Upgrading from 1.6 to 1.7 + +* If you used the global explorer **hardware_type**, you need to change + your code to use **machine** instead. + +### Upgrading from 1.5 to 1.6 + +* If you used **\_\_package_apt --preseed**, you need to use the new + type **\_\_debconf_set_selections** instead. +* The **\_\_package** types accepted either --state deinstalled or + --state uninstaaled. Starting with 1.6, it was made consistently + to --state removed. + +### Upgrading from 1.3 to 1.5 + +No incompatiblities. + +### Upgrading from 1.2 to 1.3 + +Rename **gencode** of every type to **gencode-remote**. + +### Upgrading from 1.1 to 1.2 + +No incompatiblities. + +### Upgrading from 1.0 to 1.1 + +In 1.1 the type **\_\_file** was split into **\_\_directory**, **\_\_file** and +**\_\_link**. The parameter **--type** was removed from **\_\_file**. Thus you +need to replace **\_\_file** calls in your manifests: + + * Remove --type from all \_\_file calls + * If type was symlink, use \_\_link and --type symbolic + * If type was directory, use \_\_directory + + +[[!tag cdist unix]] diff --git a/software/cdist/support.mdwn b/software/cdist/support.mdwn new file mode 100644 index 00000000..7515070d --- /dev/null +++ b/software/cdist/support.mdwn @@ -0,0 +1,25 @@ +## Support + +### IRC + +You can join the development ***IRC channel*** +[#cstar on irc.freenode.net](irc://irc.freenode.org/#cstar). + +### Mailing list + +Bug reports, questions, patches, etc. should be send to the +[cdist mailing list](http://l.schottelius.org/mailman/listinfo/cdist). + +### Linkedin + +If you have an account +at [Linked in](http://www.linkedin.com/), +you can join the +[cdist group](http://www.linkedin.com/groups/cdist-configuration-management-3952797). + +### Commercial support + +You can request commercial support for cdist from +[my company](http://firma.schottelius.org/english/). + +[[!tag cdist unix]]