358 lines
9 KiB
Text
Executable file
358 lines
9 KiB
Text
Executable file
cdist-tutorial(7)
|
|
=================
|
|
Nico Schottelius <nico-cdist--@--schottelius.org>
|
|
|
|
|
|
NAME
|
|
----
|
|
cdist-tutorial - a guided introduction into cdist
|
|
|
|
|
|
INTRODUCTION
|
|
------------
|
|
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.
|
|
|
|
|
|
|
|
QUICK START
|
|
-----------
|
|
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
|
|
--------------------------------------------------------------------------------
|
|
|
|
|
|
Before you can start using cdist, you need to ensure that
|
|
you can login
|
|
sshd config!
|
|
|
|
|
|
|
|
|
|
|
|
You can copy and paste the following
|
|
code into your shell to get started and even configure your system.
|
|
|
|
--------------------------------------------------------------------------------
|
|
# 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
|
|
chmod 0700 conf/manifest/init
|
|
|
|
echo 'Ensure that you can login as root to localhost without password'
|
|
echo '(i.e. via public key) and then press return'
|
|
read tmp
|
|
|
|
# Configure localhost
|
|
./bin/cdist config localhost
|
|
|
|
# Find out that cdist created /etc/cdist-configured
|
|
ls -l /etc/cdist-configured
|
|
--------------------------------------------------------------------------------
|
|
|
|
The file 'conf/manifest/init' is usually the entry point for cdist,
|
|
to find out what to configure on which host. All manifests are
|
|
essentially shell scripts. Every manifest can use the types known to
|
|
cdist, which are usually underline prefixed (\_\_).
|
|
|
|
|
|
|
|
Everything you specify in manifests
|
|
|
|
|
|
# Intro of quickstart
|
|
#
|
|
cat << eof
|
|
$banner cdist version $__cdist_version
|
|
|
|
Welcome to the interactive guide to cdist!
|
|
This is the interactive tutorial and beginners help for cdist and here's
|
|
our schedule:
|
|
|
|
- Stages: How cdist operates
|
|
- Explorer: Explore facts of the target host
|
|
- Manifest: Map configurations to hosts
|
|
- Types: Bundled functionality
|
|
- Deploy a configuration to the local host!
|
|
|
|
eof
|
|
__prompt "$continue"
|
|
|
|
################################################################################
|
|
# Stages
|
|
#
|
|
cat << eof
|
|
|
|
To deploy configurations to a host, you call
|
|
|
|
cdist-deploy-to <hostname>
|
|
|
|
which makes calls to other scripts, which realise the so called "stages".
|
|
Usually you'll not notice this, but in case you want to debug or hack cdist,
|
|
you can run each stage on its own. Besides that, you just need to remember
|
|
that the command cdist-deploy-to is the main cdist command.
|
|
|
|
See also:
|
|
|
|
Source of cdist-deploy-to(1), cdist-stages(7)
|
|
|
|
eof
|
|
__prompt "$continue"
|
|
|
|
################################################################################
|
|
# Explorer
|
|
#
|
|
cat << eof
|
|
|
|
The first thing cdist always does is running different explorers on the
|
|
target host. The explorers can be found in the directory
|
|
|
|
${__cdist_explorer_dir}
|
|
|
|
An explorer is executed on the target host and its output is saved to a file.
|
|
You can use these files later to decide what or how to configure the host.
|
|
|
|
For a demonstration, we'll call the OS explorer locally now, but remember:
|
|
This is only for demonstration, normally it is run on the target host.
|
|
The os explorer will which either displays the detected operating system or
|
|
nothing if it does not know your OS.
|
|
|
|
See also:
|
|
|
|
cdist-explorer(7)
|
|
|
|
eof
|
|
explorer="${__cdist_explorer_dir}/os"
|
|
|
|
__prompt "Press enter to execute $explorer"
|
|
|
|
set -x
|
|
"$explorer"
|
|
set +x
|
|
|
|
################################################################################
|
|
# Manifest
|
|
#
|
|
cat << eof
|
|
|
|
The initial manifest is the entry point for cdist to find out, what you would
|
|
like to have configured. It is located at
|
|
|
|
${__cdist_manifest_init}
|
|
|
|
And can be as simple as
|
|
|
|
--------------------------------------------------------------------------------
|
|
__file /etc/cdist-configured --type file
|
|
--------------------------------------------------------------------------------
|
|
|
|
See also:
|
|
|
|
cdist-manifest(7)
|
|
|
|
eof
|
|
__prompt "$continue"
|
|
|
|
cat << eof
|
|
|
|
Let's take a deeper look at the initial manifest to understand what it means:
|
|
|
|
__file /etc/cdist-configured --type file
|
|
| | | \\
|
|
| | The parameter type \\ With the value file
|
|
| |
|
|
| |
|
|
| | This is the object id
|
|
|
|
|
__file is a so called "type"
|
|
|
|
|
|
This essentially looks like a standard command executed in the shell.
|
|
eof
|
|
__prompt "$continue"
|
|
|
|
cat << eof
|
|
|
|
And that's exactly true. Manifests are shell snippets that can use
|
|
types as commands with arguments. cdist prepends a special path
|
|
that contain links to the cdist-type-emulator, to \$PATH, so you
|
|
can use your types as a command.
|
|
|
|
This is also the reason why types should always be prefixed with
|
|
"__", to prevent collisions with existing binaries.
|
|
|
|
The object id is unique per type and used to prevent you from creating
|
|
the same object twice.
|
|
|
|
Parameters are type specific and are always specified as --parameter <value>.
|
|
|
|
See also:
|
|
|
|
cdist-type-build-emulation(1), cdist-type-emulator(1)
|
|
|
|
eof
|
|
__prompt "$continue"
|
|
|
|
################################################################################
|
|
# Types
|
|
#
|
|
cat << eof
|
|
|
|
Types are bundled functionality and are the main component of cdist.
|
|
If you want to have a feature x, you write the type __x. Types are stored in
|
|
|
|
${__cdist_type_dir}
|
|
|
|
And cdist ships with some types already!
|
|
|
|
See also:
|
|
|
|
cdist-type(7)
|
|
|
|
eof
|
|
__prompt "Press enter to see available types"
|
|
|
|
set -x
|
|
ls ${__cdist_type_dir}
|
|
set +x
|
|
|
|
cat << eof
|
|
|
|
Types consist of the following parts:
|
|
|
|
- ${__cdist_name_parameter} (${__cdist_name_parameter_required}/${__cdist_name_parameter_optional}
|
|
- ${__cdist_name_manifest}
|
|
- ${__cdist_name_explorer}
|
|
- ${__cdist_name_gencode}
|
|
|
|
eof
|
|
__prompt "$continue"
|
|
|
|
|
|
cat << eof
|
|
|
|
Every type must have a directory named ${__cdist_name_parameter}, which
|
|
contains required or optional parameters (in newline seperated files).
|
|
|
|
If an object of a specific type was created in the initial manifest,
|
|
the manifest of the type is run and may create other objects.
|
|
|
|
A type may have ${__cdist_name_explorer}, which are very similar to the
|
|
${__cdist_name_explorer} seen above, but with a different purpose:
|
|
They are specific to the type and are not relevant for other types.
|
|
|
|
You may use them for instance to find out details on the target host,
|
|
so you can decide what to do on the target host eventually.
|
|
|
|
After the ${__cdist_name_manifest} and the ${__cdist_name_explorer} of
|
|
a type have been run, ${__cdist_name_gencode} is executed, which creates
|
|
code to be executed on the target on stdout.
|
|
|
|
eof
|
|
__prompt "$continue"
|
|
|
|
################################################################################
|
|
# Deployment
|
|
#
|
|
|
|
cat << eof
|
|
|
|
Now you've got some basic knowledge about cdist, let's configure your a host!
|
|
|
|
Ensure that you have a ssh server running on the host and that you can login as root.
|
|
|
|
eof
|
|
|
|
__prompt "Enter hostname or press enter for localhost: "
|
|
|
|
if [ "$answer" ]; then
|
|
host="$answer"
|
|
else
|
|
host="localhost"
|
|
fi
|
|
|
|
manifestinit="conf/manifest/init"
|
|
cat << eof
|
|
|
|
I'll now setup $manifestinit, containing the following code:
|
|
|
|
--------------------------------------------------------------------------------
|
|
# Every machine becomes a marker, so sysadmins know that automatic
|
|
# configurations are happening
|
|
__file /etc/cdist-configured
|
|
|
|
case "\$__target_host" in
|
|
$host)
|
|
__link /tmp/cdist-testfile --source /etc/cdist-configured --type symbolic
|
|
__addifnosuchline /tmp/cdist-welcome --line "Welcome to cdist"
|
|
;;
|
|
esac
|
|
--------------------------------------------------------------------------------
|
|
|
|
WARNING: This will overwrite ${manifestinit}.
|
|
|
|
eof
|
|
|
|
cat > "$__cdist_abs_mydir/../$manifestinit" << eof
|
|
|
|
# Every machine becomes a marker, so sysadmins know that automatic
|
|
# configurations are happening
|
|
__file /etc/cdist-configured
|
|
|
|
case "\$__target_host" in
|
|
$host)
|
|
__link /tmp/cdist-testfile --source /etc/cdist-configured --type symbolic
|
|
__addifnosuchline /tmp/cdist-welcome --line "Welcome to cdist"
|
|
;;
|
|
esac
|
|
|
|
eof
|
|
|
|
chmod u+x "$__cdist_abs_mydir/../$manifestinit"
|
|
|
|
cmd="cdist-deploy-to $host"
|
|
|
|
__prompt "Press enter to run \"$cmd\""
|
|
|
|
# No quotes, we need field splitting
|
|
$cmd
|
|
|
|
################################################################################
|
|
# End
|
|
#
|
|
|
|
cat << eof
|
|
|
|
|
|
--------------------------------------------------------------------------------
|
|
That's it, this is the end of the cdist-quickstart.
|
|
|
|
I hope you've got some impression on how cdist works, here are again some
|
|
pointers on where to continue to read:
|
|
|
|
|
|
eof
|
|
|
|
SEE ALSO
|
|
--------
|
|
cdist(1), cdist-type(7), cdist-stages(7)
|
|
|