From c5cd1ce89a9627e2e9fd95dc492bd5d45894510a Mon Sep 17 00:00:00 2001 From: Nico Schottelius Date: Wed, 11 Jan 2012 17:11:11 +0100 Subject: [PATCH] split tutorial into quickstart, make tutorial a guide Signed-off-by: Nico Schottelius --- doc/man/man7/cdist-best-practice.text | 2 +- doc/man/man7/cdist-quickstart.text | 109 ++++++++++++++++++++++++++ doc/man/man7/cdist-tutorial.text | 86 ++------------------ 3 files changed, 117 insertions(+), 80 deletions(-) create mode 100644 doc/man/man7/cdist-quickstart.text diff --git a/doc/man/man7/cdist-best-practice.text b/doc/man/man7/cdist-best-practice.text index 7d947fce..dfc06167 100644 --- a/doc/man/man7/cdist-best-practice.text +++ b/doc/man/man7/cdist-best-practice.text @@ -146,5 +146,5 @@ SEE ALSO COPYING ------- -Copyright \(C) 2011 Nico Schottelius. Free use of this software is +Copyright \(C) 2011-2012 Nico Schottelius. Free use of this software is granted under the terms of the GNU General Public License version 3 (GPLv3). diff --git a/doc/man/man7/cdist-quickstart.text b/doc/man/man7/cdist-quickstart.text new file mode 100644 index 00000000..5012a331 --- /dev/null +++ b/doc/man/man7/cdist-quickstart.text @@ -0,0 +1,109 @@ +cdist-quickstart(7) +=================== +Nico Schottelius + + +NAME +---- +cdist-quickstart - jump in and enjoy 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 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. + + +CONTINUE READING +----------------- + + +SEE ALSO +-------- +- cdist(1) +- cdist-type(7) +- cdist-best-practice(7) +- cdist-stages(7)? + + +COPYING +------- +Copyright \(C) 2011-2012 Nico Schottelius. Free use of this software is +granted under the terms of the GNU General Public License version 3 (GPLv3). diff --git a/doc/man/man7/cdist-tutorial.text b/doc/man/man7/cdist-tutorial.text index 5e257824..d80a4fe2 100644 --- a/doc/man/man7/cdist-tutorial.text +++ b/doc/man/man7/cdist-tutorial.text @@ -10,85 +10,8 @@ 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 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. +This document gives you a pointer on what to read in +which order and is thus more a "guide to the right locations". @@ -193,3 +116,8 @@ SEE ALSO - cdist-type(7) - cdist-best-practice(7) - cdist-stages(7)? + +COPYING +------- +Copyright \(C) 2011-2012 Nico Schottelius. Free use of this software is +granted under the terms of the GNU General Public License version 3 (GPLv3).