forked from ungleich-public/cdist
cleanup tutorial, fillup todo
Signed-off-by: Nico Schottelius <nico@kr.ethz.ch>
This commit is contained in:
Nico Schottelius
parent
1dcc3b771e
commit
d87deba30e
|
|
@ -8,6 +8,286 @@
|
|||
- and that ssh will wait for answer of prompt
|
||||
- nasty if used in parallel mode (scroll up!)
|
||||
|
||||
|
||||
SSH HINTS
|
||||
---------
|
||||
Control master, ssh agent
|
||||
|
||||
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
|
||||
--------------------------------------------------------------------------------
|
||||
|
||||
- Initial install support
|
||||
|
|
|
|||
|
|
@ -52,19 +52,9 @@ ssh-keygen
|
|||
ssh-copy-id root@target_host
|
||||
--------------------------------------------------------------------------------
|
||||
|
||||
As soon as you are able to login to the target host
|
||||
|
||||
|
||||
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.
|
||||
As soon as you are able to login without passwort to the target host,
|
||||
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
|
||||
|
|
@ -75,10 +65,6 @@ 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
|
||||
|
||||
|
|
@ -92,287 +78,6 @@ essentially shell scripts. Every manifest can use the types known to
|
|||
cdist, which are usually underline prefixed (\_\_).
|
||||
|
||||
|
||||
SSH HINTS
|
||||
---------
|
||||
Control master, ssh agent
|
||||
|
||||
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)
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue