Table of Contents
cdist [-h] [-V]
cdist banner
cdist config [-h] [-d] [-V] [-c CDIST_HOME] [-i MANIFEST] [-p] [-s] host [host …]
cdist is the frontend executable to the cdist configuration management. +cdist supports different as explained below. The options to the main +program are:
Configure a system
# Configure ikq05.ethz.ch with debug enabled +cdist config -d ikq05.ethz.ch + +# Configure hosts in parallel and use a different home directory +cdist config -c ~/p/cdist-nutzung \ + -p ikq02.ethz.ch ikq03.ethz.ch ikq04.ethz.ch + +# Display banner +cdist banner + +# Show help +cdist --help + +# Show Version +cdist --version
Table of Contents
It is recommended to run cdist with public key authentication. +This requires a private/public key pair and the entry +"PermitRootLogin without-password" in the sshd server. +See sshd_config(5) and ssh-keygen(1).
When connecting to a new host, the initial delay with ssh connections +is pretty big. You can work around this by +"sharing of multiple sessions over a single network connection" +(quote from ssh_config(5)). The following code is suitable for +inclusion into your ~/.ssh/config:
Host * + ControlPath ~/.ssh/master-%l-%r@%h:%p + ControlMaster auto + ControlPersist 10
If you plan to distribute cdist among servers or use different +environments, you can do so easily with the included version +control git. For instance if you plan to use the typical three +environments production, integration and development, you can +realise this with git branches:
# Go to cdist checkout +cd /path/to/cdist + +# Create branches +git branch development +git branch integration +git branch production + +# Make use of a branch, for instance production +git checkout production
Similar if you want to have cdist checked out at multiple machines, +you can clone it multiple times:
machine-a % git clone git://your-git-server/cdist +machine-b % git clone git://your-git-server/cdist
If you are working with different groups on one cdist-configuration, +you can delegate to other manifests and have the groups edit only +their manifests. You can use the following snippet in +conf/manifests/init:
# Include other groups +sh -e "$__manifest/systems" + +sh -e "$__manifest/cbrg"
When you need to manage multiple sites with cdist, like company_a, company_b +and private for instance, you can easily use git for this purpose. +Including a possible common base that is reused accross the different sites:
# create branches +git branch company_a company_b common private + +# make stuff for company a +git checkout company_a +# work, commit, etc. + +# make stuff for company b +git checkout company_b +# work, commit, etc. + +# make stuff relevant for all sites +git checkout common +# work, commit, etc. + +# change to private and include latest common stuff +git checkout private +git merge common
The following .git/config is taken from a a real world scenario:
# Track upstream, merge from time to time +[remote "upstream"] + url = git://git.schottelius.org/cdist + fetch = +refs/heads/*:refs/remotes/upstream/* + +# Same as upstream, but works when being offline +[remote "local"] + fetch = +refs/heads/*:refs/remotes/local/* + url = /home/users/nico/p/cdist + +# Remote containing various ETH internal branches +[remote "eth"] + url = sans.ethz.ch:/home/services/sans/git/cdist-eth + fetch = +refs/heads/*:refs/remotes/eth/* + +# Public remote that contains my private changes to cdist upstream +[remote "nico"] + url = git.schottelius.org:/home/services/git/cdist-nico + fetch = +refs/heads/*:refs/remotes/nico/* + +# The "nico" branch will be synced with the remote nico, branch master +[branch "nico"] + remote = nico + merge = refs/heads/master + +# ETH stable contains rock solid configurations used in various places +[branch "eth-stable"] + remote = eth + merge = refs/heads/stable
Have a look at git-remote(1) to adjust the remote configuration, which allows
If you are working in an environment that requires different people to +work on the same configuration, but having different privileges, you can +implement this scenario with a gateway host and sudo:
For more details consult sudoers(5)
Table of Contents
This document describes the usual steps recommended for a new +cdist setup. It is recommended that you have read and understood +cdist-quickstart(7) before digging into this.
First of all, you should think about where to store your configuration +database and who will be accessing or changing it. Secondly you have to +think about where to configure your hosts from, which may be a different +location.
For starters, having cdist (which includes the configuration database) on +your notebook should be fine. +Additionally an external copy of the git repository the configuration +relies in is recommended, for use as backup as well to allow easy collaboration +with others.
For more sophisticated setups developing cdist configurations with multiple +people, have a look at cdist-best-practice(7).
I assume you have a fresh copy of the cdist tree in ~/cdist, cloned from +one of the official urls (see cdist-quickstart(7) if you don’t). +Entering the command "git branch" should show you "* master", which indicates +you are on the master branch.
The master branch reflects the latest development of cdist. As this is the +development branch, it may or may not work. There are also version branches +available, which are kept in a stable state. Let’s use git branch -r +to list all branches:
cdist% git branch -r + origin/1.0 + origin/1.1 + origin/1.2 + origin/1.3 + origin/1.4 + origin/1.5 + origin/1.6 + origin/1.7 + origin/2.0 + origin/HEAD -> origin/master + origin/archive_shell_function_approach + origin/master
So 2.0 is the latest version branch in this example. +All versions (2.0.x) within one version branch (2.0) are compatible to each +other and won’t break your configuration when updating.
It’s up to you decide on which branch you want to base your own work: +master contains more recent changes, newer types, but may also break. +The versions branches are stable, but thus may miss the latest features. +Your decision can be changed later on, but may result in merge conflicts, +which you’d have to solve.
Let’s assume you want latest stuff and select the master branch as base for +your own work. Now it’s time to create your branch, which contains your +local changes. I usually name it by the company/area I am working for: +ethz-systems, localch, customerX, … But this is pretty much up to you.
In this tutorial I use the branch mycompany:
cdist% git checkout -b mycompany origin/master +Branch mycompany set up to track remote branch master from origin. +Switched to a new branch 'mycompany' +cdist-user% git branch + master +* mycompany
From now on, you can use git as usual to commit your changes in your own branch.
Usually a development machine like a notebook should be considered +temporary only. For this reason and to enable shareability, the configuration +should be published to another device as early as possible. The following +example shows how to publish the configuration to another host that is +reachable via ssh and has git installed:
# Create bare git repository on the host named "loch" +cdist% ssh loch "GIT_DIR=/home/nutzer/cdist git init" +Initialized empty Git repository in /home/nutzer/cdist/ + +# Add remote git repo to git config +cdist% git remote add loch loch:/home/nutzer/cdist + +# Configure the mycompany branch to push to loch +cdist% git config branch.mycompany.remote loch + +# Configure mycompany branch to push into remote master branch +cdist% git config branch.mycompany.merge refs/heads/master + +# Push mycompany branch to remote branch master initially +cdist% git push loch mycompany:refs/heads/master
Now you have setup the git repository to synchronise the mycompany +branch with the master branch on the host loch. Thus you can commit +as usual in your branch and push out changes by entering git push.
Whenever you want to update your cdist installation, you can use git to do so:
# Update git repository with latest changes from origin +cdist% git fetch origin + +# Update current branch with master branch from origin +cdist% git merge origin/master + +# Alternative: Update current branch with 2.0 branch from origin +cdist% git merge origin/2.0
Table of Contents
Explorer are small shell scripts, which will be executed on the target +host. The aim of the explorer is to give hints to types on how to act on the +target system. An explorer outputs the result to stdout, which is usually +a one liner, but may be empty or multi line especially in the case of +type explorers.
There are general explorers, which are run in an early stage, and +type explorers. Both work almost exactly the same way, with the difference +that the values of the general explorers are stored in a general location and +the type specific below the object.
Explorers can reuse other explorers on the target system by calling +$explorer/<explorer_name> (general and type explorer) or +$type_explorer/<explorer name> (type explorer).
In case of significant errors, the explorer may exit non-zero and return an +error message on stderr, which will cause cdist to abort.
You can also use stderr for debugging purposes while developing a new +explorer.
A very simple explorer may look like this:
hostname
Which is in practise the hostname explorer.
A type explorer, which could check for the status of a package may look like this:
if [ -f "$__object/parameter/name" ]; then + name="$(cat "$__object/parameter/name")" +else + name="$__object_id" +fi + +# Except dpkg failing, if package is not known / installed +dpkg -s "$name" 2>/dev/null || exit 0
Table of Contents
Welcome dear hacker! I invite you to a tour of pointers to +get into the usable configuration mangament system, cdist.
The first thing to know is probably that cdist is brought to +you by people who care about how code looks like and who think +twice before merging or implementing a feature: Less features +with good usability are far better than the opposite.
If you believe you’ve found a bug and verified that it is +in the latest version, drop a mail to the cdist mailing list, +subject prefixed with "[BUG] " or create an issue on github.
If something should be better done or needs to fixed, add the word FIXME +nearby, so grepping for FIXME gives all positions that need to be fixed.
Indention is 4 spaces (welcome to the python world).
If you did some cool changes to cdist, which you value as a benefit for +everybody using cdist, you’re welcome to propose inclusion into upstream.
There are though some requirements to ensure your changes don’t break others +work nor kill the authors brain:
As soon as your work meets these requirements, you can contact me +(IRC, Mailinglist, Phone, RFC 1149) and I’ll check your code before +including it.
For detailled information about types, see cdist-type(7).
Submitting a type works as described above, with the additional requirement +that a corresponding manpage named man.text in asciidoc format with +the manpage-name "cdist-type__NAME" is included in the type directory +AND asciidoc is able to compile it (i.e. do NOT have to many "=" in the second +line).
Warning: Submitting "exec" or "run" types that simply echo their parameter in +gencode* will not be accepted, because they are of no use. Every type can output +code and thus such a type introduces redundant functionality that is given by +core cdist already.
Table of Contents
Manifests are used to define which objects to create. +Objects are instances of types, like in object orientated programming languages. +An object is represented by the combination of +type + slash + object name: file/etc/cdist-configured is an +object of the type file with the name etc/cdist-configured.
All available types can be found in the conf/type/ directory, +use ls conf/type to get the list of available types. If you have +setup the MANPATH correctly, you can use man cdist-reference to access +the reference with pointers to the manpages.
Types in manifests are used like normal command line tools. Let’s have a look +at an example:
# Create object of type __package with the parameter state = removed +__package apache2 --state removed + +# Same with the __directory type + __directory /tmp/cdist --state present
These two lines create objects, which will later be used to realise the +configuration on the target host.
Manifests are executed locally as a shell script using /bin/sh -e. +The resulting objects are stored in an internal database.
The same object can be redefined in multiple different manifests as long as +the parameters are exactly the same.
In general, manifests are used to define which types are used depending +on given conditions.
Cdist nows about two types of manifests: The initial manifest and type +manifests. The initial manifest is used to define, which configurations +to apply to which hosts. The type manifests are used to create objects +from types. More about manifests in types can be found in cdist-type(7).
The initial manifest is the entry point for cdist to find out, which +objects to configure on the selected host. +Cdist searches for the initial manifest at conf/manifest/init.
Within this initial manifest, you define, which objects should be +created on which host. To distinguish between hosts, you can use the +environment variable __target_host. Let’s have a look at a simple +example:
__cdistmarker + +case "$__target_host" in + localhost) + __directory /home/services/kvm-vm --parents yes + ;; +esac
This manifest says: Independent of the host, always use the type +__cdistmarker, which creates the file /etc/cdist-configured, +with the timestamp as content. +The directory /home/services/kvm-vm, including all parent directories, +is only created on the host localhost.
As you can see, there is no magic involved, the manifest is simple shell code that +utilises cdist types. Every available type can be executed like a normal +command.
If you want to split up your initial manifest, you can create other shell +scripts in conf/manifest/ and include them in conf/manifest/init. +Cdist provides the environment variable __manifest to reference to +the directory containing the initial manifest (see cdist-reference(7)).
The following example would include every file with a .sh suffix:
# Include *.sh +for manifest in $__manifest/*.sh; do + # And source scripts into our shell environment + . "$manifest" +done
If you want to describe that something requires something else, just +setup the variable "require" to contain the requirements. Multiple +requirements can be added white space seperated.
# No dependency +__file /etc/cdist-configured + +# Require above object +require="__file/etc/cdist-configured" __link /tmp/cdist-testfile \ + --source /etc/cdist-configured --type symbolic + +# Require two objects +require="__file/etc/cdist-configured __link/tmp/cdist-testfile" \ + __file /tmp/cdist-another-testfile
All objects that are created in a type manifest are automatically required +from the type that is calling them. This is called "autorequirement" in +cdist jargon.
The initial manifest may for instance contain the following code:
# Always create this file, so other sysadmins know cdist is used. +__file /etc/cdist-configured --type file + +case "$__target_host" in + my.server.name) + __file /root/bin/ --type directory + __file /etc/issue.net --type file --source "$__manifest/issue.net + ;; +esac
The manifest of the type "nologin" may look like this:
__file /etc/nologin --type file --source "$__type/files/default.nologin"
Table of Contents
This tutorial is aimed at people learning cdist and shows +typical approaches as well as gives an easy start into +the world of configuration management.
This tutorial assumes you are configuring localhost, because +it is always available. Just replace localhost with your target +host for real life usage.
For those who just want to configure a system with the +cdist configuration management and do not need (or want) +to understand everything.
Cdist uses ssh for communication and transportation +and usually logs into the target host as the +root user. So you need to configure the ssh server +of the target host to allow root logins: Edit +the file /etc/ssh/sshd_config and add one of the following +lines:
# Allow login only via public key +PermitRootLogin without-password + +# Allow login via password and public key +PermitRootLogin yes
As cdist uses ssh intensively, it is recommended to setup authentication +with public keys:
# Generate pubkey pair as a normal user +ssh-keygen + +# Copy pubkey over to target host +ssh-copy-id root@localhost
Have a look at ssh-agent(1) and ssh-add(1) on how to cache the password for +your public key. Usually it looks like this:
# Start agent and export variables +eval `ssh-agent` + +# Add keys (requires password for every identity file) +ssh-add
At this point you should be able to ssh root@localhost without +re-entering the password. If something failed until here, ensure that +all steps went successfully and you have read and understood the +documentation.
As soon as you are able to login without password to localhost, +we can use cdist to configure it. You can copy and paste the following +code into your shell to get started and configure localhost:
# Get cdist +git clone git://git.schottelius.org/cdist + +# Create manifest (maps configuration to host(s) +cd cdist +echo '__file /etc/cdist-configured' > conf/manifest/init + +# Configure localhost in verbose mode +./bin/cdist config -v localhost + +# Find out that cdist created /etc/cdist-configured +ls -l /etc/cdist-configured
That’s it, you’ve successfully used cdist to configure your first host! +Continue reading the next sections, to understand what you did and how +to create a more sophisticated configuration.
Table of Contents
The following global explorers are available:
If not specified otherwise, all paths are relative to the checkout directory.
+ Home of the type <name>. +
This directory is referenced by the variable __type (see below).
For object to object communication and tests, the following paths are +usable within a object directory:
+ The type unique object id. + Available for: type manifest, type explorer, type gencode +
Note: The leading and the trailing "/" will always be stripped (caused by +the filesystem database and ensured by the core).
Note: Double slashes ("//") will not be fixed and result in an error.
+__self::
+ DEPRECATED: Same as __object_name, do not use anymore, use __object_name instead.
+ Will be removed in cdist 3.x.
+__object_name::
+ The full qualified name of the current object.
+ Available for: type manifest, type explorer, type gencode
+__target_host::
+ The host we are deploying to.
+ Available for: initial manifest, type manifest, type gencode
+__type::
+ Path to the current type.
+ Available for: type manifest, type gencode
+__type_explorer::
+ Directory that contains the type explorers.
+ Available for: type explorerTable of Contents
Starting the execution of deployment with cdist, cdist passes +through different stages.
In this stage information is collected about the target host using so called +explorers. Every existing explorer is run on the target and the output of all +explorers are copied back into the local cache. The results can be used by +manifests and types.
The initial manifest, which should be used for mappings of hosts to types, +is executed. This stage creates objects in a cconfig database that contains +the objects as defined in the manifest for the specific host. In this stage, +no conflicts may occur, i.e. no object of the same type with the same id may +be created.
Every object is checked whether its type has explorers and if so, these are +executed on the target host. The results are transfered back +and can be used in the following stages to decide what changes need to be made +on the target to implement the desired state.
Every object is checked whether its type has a executable manifest. The +manifest script may generate and change the created objects. In other words, +one type can reuse other types.
For instance the object apache/www.test.ch is of type apache, which may +contain a manifest script, which creates new objects of type __file.
The newly created objects are merged back into the existing tree. No conflicts +may occur during the merge. A conflict would mean that two different objects +try to create the same object, which indicates a broken configuration.
In this stage for every created object its type is checked for executable +gencode scripts. The gencode scripts generate the code to be executed on the +target on stdout. If the gencode executables fail, they must print diagnostic +messages on stderr and exit non-zero.
For every object the resulting code from the previous stage is transferred to +the target host and executed there to apply the configuration changes.
If, and only if, all the stages complete without an errors, the configuration +will be applied to the target.
Table of Contents
This document gives you a pointer on what to read in +which order and is thus a "guide to the right locations". +So in case you are just starting, just "begin at the beginning" +(Brave New World). You can see the target audience in [] brackets +after the description.
Table of Contents
__TYPE ID --parameter value [--parameter value …]
__TYPE --parameter value [--parameter value …] (for singletons)
Types are the main component of cdist and define functionality. If you +use cdist, you’ll write a type for every functionality you would like +to use.
You can use types from the initial manifest or the type manifest like a +normal command:
# Creates empty file /etc/cdist-configured +__file /etc/cdist-configured --type file + +# Ensure tree is installed +__package tree --state installed
A list of supported types can be found in the cdist-reference(7) manpage.
If a type is flagged as a singleton, it may be used only +once per host. This is useful for types which can be used only once on a +system. Singleton types do not take an object name as argument.
Example:
# __issue type manages /etc/issue +__issue + +# Probably your own type - singletons may use parameters +__myfancysingleton --colour green
A type consists of
Types are stored below conf/type/. Their name should always be prefixed with +two underscores (__) to prevent collisions with other executables in $PATH.
To begin a new type, just create the directory conf/type/__NAME.
Every type consists of optional and required parameters, which must +be created in a newline seperated file in parameters/required and +parameters/optional. If either or both missing, the type will have +no required, no optional or no parameters at all.
Example:
echo servername >> conf/type/__nginx_vhost/parameter/required +echo logdirectory >> conf/type/__nginx_vhost/parameter/optional
In the manifest of a type you can use other types, so your type extends +their functionality. A good example is the __package type, which in +a shortened version looks like this:
os="$(cat "$__global/explorer/os")" +case "$os" in + archlinux) type="pacman" ;; + debian|ubuntu) type="apt" ;; + gentoo) type="emerge" ;; + *) + echo "Don't know how to manage packages on: $os" >&2 + exit 1 + ;; +esac + +__package_$type "$@"
As you can see, the type can reference different environment variables, +which are documented in cdist-reference(7).
Always ensure the manifest is executable, otherwise cdist will not be able +to execute it. For more information about manifests see cdist-manifest(7).
If you want to ensure that a type can only be used once per target, you can +mark it as a singleton: Just create the (empty) file "singleton" in your type +directory:
touch conf/type/__NAME/singleton
This will also change the way your type must be called:
__YOURTYPE --parameter value
As you can see, the object ID is omitted, because it does not make any sense, +if your type can be used only once.
If a type needs to explore specific details, it can provide type specific +explorers, which will be executed on the target for every created object.
The explorers are stored under the "explorer" directory below the type. +It could for instance contain code to check the md5sum of a file on the +client, like this (shortened version from the type __file):
if [ -f "$__object/parameter/destination" ]; then + destination="$(cat "$__object/parameter/destination")" +else + destination="/$__object_id" +fi + +if [ -e "$destination" ]; then + md5sum < "$destination" +fi
There are two gencode scripts: gencode-local and gencode-remote. +The output of gencode-local is executed locally, whereas +the output of gencode-remote is executed on the target.
The gencode scripts can make use of the parameters, the global explorers +and the type specific explorers. The output (stdout) of these script is +saved by cdist and will be executed on the target.
If the gencode scripts encounter an error, it should print diagnostic +messages to stderr and exit non-zero. If you need to debug the gencode +script, you can write to stderr:
# Debug output to stderr +echo "My fancy debug line" >&2 + +# Output to be saved by cdist for execution on the target +echo "touch /etc/cdist-configured"
It must be assumed that the target is pretty dumb and thus does not have high +level tools like ruby installed. If a type requires specific tools to be present +on the target, there must be another type that provides this tool and the first +type should create an object of the specific type.
If your type wants to save temporary data, that may be used by other types +later on (for instance file), you can save them in the subdirectory +"files" below $object (but you must create it yourself). +cdist will not touch this directory.
If your type contains static files, it’s also recommended to place them in +a folder named "files" within the type (again, because cdist guarantees to +never ever touch this folder).
If you think your type may be useful for others, ensure it works with the +current master branch of cdist and submit the git url containing the type for +inclusion to the mailinglist cdist at cdist — at — l.schottelius.org +or open a pull request at http://github.com/telmich/cdist.
Ensure a corresponding manpage named man.text in asciidoc format with +the manpage-name "cdist-type__NAME" is included in the type directory.
Table of Contents
This type can be used to check a file for existence of a +specific line and adding it, if it was not found.
# Creates or appends the line specifiend in "include_www" to the file "lighttpd.conf" +__addifnosuchline www --file /etc/lighttpd.conf --line include_www + +# Adds the line "include_git" to the file "lighttpd.conf" +__addifnosuchline /etc/lighttpd.conf --line include_git
Table of Contents
# Enable a ppa repository +__apt_ppa ppa:sans-intern/missing-bits --state enabled + +# Disable a ppa repository +__apt_ppa ppa:sans-intern/missing-bits --state disabled
Table of Contents
Table of Contents
# Add auto mounter at /net +__autofs_map /net --map /etc/auto.net --type program + +# Add auto mounter at /pub +__autofs_map /pub --map /etc/auto.pub \ + --type file --options nosuid,rw,bg,hard,intr --ghost
Table of Contents
This cdist type generates a auto.master configuration from given autofs_map +definitions. See cdist-typeauto_map(7).
# auto.master with default header +__autofs_master + +# auto.master with custom header +__autofs_master --header /path/to/header
Table of Contents
This type is used to add a common marker file which indicates that a given +machine is being managed by cdist. The contents of this file consist of a +timestamp, which can be used to determine the most recent time at which cdist +was run against the machine in question.
# Creates the marker as normal. +__cdistmarker + +# Creates the marker differently. +__cdistmarker --file /tmp/cdist_marker --format '+%s'
Table of Contents
# add cronjob +__cron some-id --user root --command "/path/to/script" + +# remove cronjob +__cron some-id --user root --command "/path/to/script" --state absent
On Debian and alike systems debconf-set-selections(1) can be used +to setup configuration parameters.
# Setup configuration for nslcd +__debconf_set_selections nslcd --file /path/to/file + +# Setup configuration for nslcd from another type +__debconf_set_selections nslcd --file "$__type/files/preseed/nslcd"
Table of Contents
# A silly example +__directory /tmp/foobar + +# Remove a directory +__directory /tmp/foobar --state absent + +# Ensure /etc exists correctly +__directory /etc --owner root --group root --mode 0755 + +# Create nfs service directory, including parents +__directory /home/services/nfs --parents yes + +# Change permissions recursively +__directory /home/services --recursive yes --owner root --group root + +# Setup a temp directory +__directory /local --mode 1777
Table of Contents
This cdist type allows you to create files, remove files and set file +attributes on the target.
# Create /etc/cdist-configured as an empty file +__file /etc/cdist-configured +# The same thing +__file /etc/cdist-configured --state present +# Delete existing file +__file /etc/cdist-configured --state absent + +# Use __file from another type +__file /etc/issue --source "$__type/files/archlinux" --state present + +# Supply some more settings +__file /etc/shadow --source "$__type/files/shadow" \ + --owner root --group shadow --mode 0640 \ + --state present
Table of Contents
# Create a group 'foobar' with operating system default settings +__group foobar + +# Same but with a specific gid +__group foobar --gid 1234 + +# Same but with a gid and password +__group foobar --gid 1234 --password 'crypted-password-string'
Table of Contents
__issue + +# When called from another type +__issue --source "$__type/files/myfancyissue"
Table of Contents
# Set the maximum system user id +__key_value SYS_UID_MAX --file /etc/login.defs --value 666 --delimiter ' ' + +# Same with fancy id +__key_value my-fancy-id --file /etc/login.defs --key SYS_UID_MAX --value 666 \ + --delimiter ' ' + +# Enable packet forwarding +__key_value net.ipv4.ip_forward --file /etc/sysctl.conf --value 1 \ + --delimiter '=' + +# Remove existing key/value +__key_value LEGACY_KEY --file /etc/somefile --state absent --delimiter '='
Table of Contents
This cdist type allows you to manage hard and symbolic links. +The given object id is the destination for the link.
# Create hard link of /etc/shadow +__link /root/shadow --source /etc/shadow --type hard + +# Relative symbolic link +__link /etc/apache2/sites-enabled/www.test.ch \ + --source ../sites-available/www.test.ch \ + --type symbolic + +# Absolute symbolic link +__link /opt/plone --source /home/services/plone --type symbolic + +# Remove link +__link /opt/plone --state absent
Table of Contents
# reiserfs /dev/sda5 +__mkfs /dev/sda5 --type reiserfs +# same thing with explicit device +__mkfs whatever --device /dev/sda5 --type reiserfs + +# jfs with journal on /dev/sda2 +__mkfs /dev/sda1 --type jfs --options "-j /dev/sda2"
Table of Contents
# Use cdist defaults +__motd + +# Supply source file from a different type +__motd --source "$__type/files/my-motd"
Table of Contents
This cdist type allows you to install or uninstall packages on the target. +It dispatches the actual work to the package system dependant types.
# Install the package vim on the target +__package vim --state installed + +# Same but install specific version +__package vim --state installed --version 7.3.50 + +# Force use of a specific package type +__package vim --state installed --type __package_apt
Table of Contents
# Ensure zsh in installed +__package_apt zsh --state installed + +# In case you only want *a* webserver, but don't care which one +__package_apt webserver --state installed --name nginx + +# Remove obsolete package +__package_apt puppet --state removed
Table of Contents
# Ensure luasocket is installed +__package_luarocks luasocket --state installed + +# Remove package +__package_luarocks luasocket --state removed
Table of Contents
# Ensure zsh in installed +__package_pacman zsh --state installed + +# If you don't want to follow pythonX packages, but always use python +__package_pacman python --state installed --name python2 + +# Remove obsolete package +__package_pacman puppet --state removed
Table of Contents
Pip is used in Python environments to install packages. +It is also included in the python virtualenv environment.
# Install a package +__package_pip pyro --state present + +# Use pip in a virtualenv located at /root/shinken_virtualenv +__package_pip pyro --state present --pip /root/shinken_virtualenv/bin/pip
Table of Contents
# Ensure zsh is installed +__package_pkg_openbsd zsh --state installed + +# Ensure vim is installed, use flavor no_x11 +__package_pkg_openbsd vim --state installed --flavor no_x11 + +# If you don't want to follow pythonX packages, but always use python +__package_pkg_openbsd python --state installed --name python2 + +# Remove obsolete package +__package_pkg_openbsd puppet --state removed
Table of Contents
# Ensure sinatra is installed +__package_rubygem sinatra --state installed + +# Remove package +__package_rubygem rails --state removed
Table of Contents
Yum is usually used on the Fedora distribution to manage packages. +If you specify an unknown package, yum will display the +slightly confusing error message "Error: Nothing to do".
# Ensure zsh in installed +__package_yum zsh --state installed + +# If you don't want to follow pythonX packages, but always use python +__package_yum python --state installed --name python2 + +# Remove obsolete package +__package_yum puppet --state removed
Table of Contents
# 128MB, linux, bootable +__partition_msdos /dev/sda1 --type 83 --size 128M --bootable true +# 512MB, swap +__partition_msdos /dev/sda2 --type 82 --size 512M +# 100GB, extended +__partition_msdos /dev/sda3 --type extended --size 100G +# 10GB, linux +__partition_msdos /dev/sda5 --type 83 --size 10G +# 50% of the free space of the extended partition, linux +__partition_msdos /dev/sda6 --type 83 --size 50% +# rest of the extended partition, linux +__partition_msdos /dev/sda7 --type 83 --size +
Table of Contents
Table of Contents
All optional parameter map directly to the corresponding postgres createrole +parameters.
__postgres_role myrole --state present
__postgres_role myrole --state present --password secret
__postgres_role admin --state present --password very-secret --superuser true
__postgres_role dbcustomer --state present --password bla --createdb true
SEE ALSO
Table of Contents
+ Process name to match on when using pgrep -f -x. +
This is useful, if the name starts with a "/", +because the leading slash is stripped away from +the object id by cdist.
# Start if not running +__process /usr/sbin/syslog-ng --state running + +# Start if not running with a different binary +__process /usr/sbin/nginx --state running --start "/etc/rc.d/nginx start" + +# Stop the process using kill (the type default) - DO NOT USE THIS +__process /usr/sbin/sshd --state stopped + +# Stop the process using /etc/rc.d/sshd stop - THIS ONE NOT AS WELL +__process /usr/sbin/sshd --state stopped --stop "/etc/rc.d/sshd stop" + +# Ensure cups is running, which runs with -C ...: +__process cups --start "/etc/rc.d/cups start" --state running \ + --name "/usr/sbin/cupsd -C /etc/cups/cupsd.conf" + +# Ensure rpc.statd is running (which usually runs with -L) using a regexp +__process rpcstatd --state running --start "/etc/init.d/statd start" \ + --name "rpc.statd.*"
Table of Contents
This type can be used to check a file for existence of a +specific line and removeing it, if it was found.
# Removes the line specifiend in "include_www" from the file "lighttpd.conf" +__removeline www --file /etc/lighttpd.conf --line include_www + +# Removes the line "include_git" from the file "lighttpd.conf" +__removeline /etc/lighttpd.conf --line include_git
# Install rvm for user billie +__rvm billie --state installed + +# Remove rvm +__rvm billie --state removed
Table of Contents
# Install the rails gem in gemset ruby-1.9.3-p0@myset for user bill +__rvm_gemset rails --gemset ruby-1.9.3-p0@myset --user bill --state installed + +# Do the same and also make ruby-1.9.3-p0@myset the default gemset +__rvm_gemset rails --gemset ruby-1.9.3-p0@myset --user bill \ + --state installed --default yes + +# Remove it +__rvm_ruby rails --gemset ruby-1.9.3-p0@myset --user bill --state removed
Table of Contents
# Install the gemset @myset for user charles on based on ruby-1.9.3-0 +__rvm_gemset ruby-1.9.3-p0@myset --user charles --state installed + +# Do the same and make ruby-1.9.3-p0@myset the default gemset +__rvm_gemset ruby-1.9.3-p0@myset --user charles --state installed --default yes + +# Remove the gemset @myset for user john +__rvm_ruby ruby-1.9.3-p0@myset --user john --state removed
Table of Contents
default: + If set to anything but "no" (the default), set the given version as default
# Install ruby 1.9.3 through rvm for user thelonious +__rvm_ruby ruby-1.9.3-p0 --user thelonious --state installed + +# Install ruby 1.9.3 through rvm for user ornette and make it the default +__rvm_ruby ruby-1.9.3-p0 --user ornette --state installed --default yes + +# Remove ruby 1.9.3 for user john +__rvm_ruby ruby-1.9.3-p0 --user john --state removed
Table of Contents
This type sends a rsa key. By default uses root’s key and sends it to root’s authorized_keys
#deploy root's public key +__ssh_authorized_key admin +#deploy bob's public key to alice's authorized_keys +__ssh_authorized_key --srcuser bob --dstuser alice
Table of Contents
This type creates a symlink (/etc/localtime) to the selected timezone +(which should be available in /usr/share/zoneinfo).
#Set up Europe/Andorra as our timezone. +__timezone Europe/Andorra + +#Set up US/Central as our timezone. +__timezone US/Central
Table of Contents
# Create user account for foobar with operating system default settings +__user foobar + +# Same but with a different shell +__user foobar --shell /bin/zsh + +# Set explicit uid and home +__user foobar --uid 1001 --shell /bin/zsh --home /home/foobar