From 2df42ebd910158bc772b18e5c8e8bd453f0156ff Mon Sep 17 00:00:00 2001 From: Nico Schottelius Date: Thu, 5 Jan 2012 14:43:35 +0100 Subject: [PATCH] rewrite/rephrase/check quick start section in tutorial Signed-off-by: Nico Schottelius --- doc/man/man7/cdist-tutorial.text | 161 +++++++++++++++++-------------- 1 file changed, 91 insertions(+), 70 deletions(-) diff --git a/doc/man/man7/cdist-tutorial.text b/doc/man/man7/cdist-tutorial.text index 65f3811c..24e665b5 100644 --- a/doc/man/man7/cdist-tutorial.text +++ b/doc/man/man7/cdist-tutorial.text @@ -8,9 +8,100 @@ 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. + +This tutorial assumes you are configuring **localhost**, because +it is always available. Just replace **localhost** with your target +host for real life usage. + + + +QUICK START - GET YOUR HANDS DIRTY NOW +-------------------------------------- +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 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 +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. + +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 (__). + + + PREPARING YOUR MACHINE / SETUP ------------------------------ +Before you actually - ensure sshd is running on the target host: @@ -123,76 +214,6 @@ __debug:: - - -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. - -This tutorial assumes you are configuring **localhost**, because -it is always available. Just repace **localhost** with your target -host for real life usage. - - - -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 --------------------------------------------------------------------------------- - -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 --------------------------------------------------------------------------------- - -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 -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 - -# 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 (__). SEE ALSO