Skip to content

Commit

Permalink
Minor wordsmithing for better readability
Browse files Browse the repository at this point in the history
  • Loading branch information
@ahonor
ahonor committed Dec 1, 2010
1 parent b93561f commit 6f33b28
Show file tree
Hide file tree
Showing 8 changed files with 139 additions and 133 deletions.
78 changes: 29 additions & 49 deletions docs/en/00-introduction/00-chapter1.md
View file
Expand Up @@ -9,43 +9,32 @@
Welcome to the RunDeck user guide. This guide was written to help
administrators quickly become productive with the RunDeck server and tools.

RunDeck is open source software that helps administrators automate
ad-hoc and routine procedures. RunDeck provides a number of features
that help you scale your scripting in a distributed environment for
multi-step procedures. RunDeck helps alleviate time-consuming grunt
work that comes from managing many systems in a dynamic environment.
## What is RunDeck?

RunDeck is open source software that helps you automate ad-hoc and routine
procedures in data center or cloud environments. RunDeck provides a number
of features that will alleviate time-consuming grunt work and make it easy for
you to scale up your scripting efforts.

### Who makes the RunDeck software?

RunDeck is hosted at GitHub as a project called
RunDeck is developed on GitHub as a project called
[dtolabs/rundeck](https://github.com/dtolabs/rundeck).
Dtolabs is a project where various open sources tools are
being developed by [DTO Solutions](http://www.dtosolutions.com)
engineers working in the field.
Many ideas for RunDeck come from [DTO Solutions](http://www.dtosolutions.com)
consultants working in the field, however all are welcome to join the project
and contribute.

RunDeck is free software and is public under the [Apache Software License].

[Apache Software License]: http://www.apache.org/licenses/LICENSE-2.0.html

### Why is RunDeck open source?

We believe this kind of software project must be open source because
it is an interesting blending of technologies, philosophies and
therefore, RunDeck's ideas and code should be easily transferable.

### Why is it called RunDeck

The RunDeck name has meanings at a couple levels. The first level
sees RunDeck as a place (deck) to conduct your automation.
Another meaning suggests that groups of actions can be run at
once, like a workflow. This second meaning is more like a deck of
cards or to be really old fashioned, a deck of punch cards!

RunDeck also conjures up the idea of a tool for [run book automation]
but concentrates on being lightweight and focused on scripting rather
than serious development of workflow modules and state machines.
## Getting help

[run book automation]: http://en.wikipedia.org/wiki/Run_Book_Automation
* Mailing list:
[http://groups.google.com/group/rundeck-discuss](http://groups.google.com/group/rundeck-discuss)
* IRC: irc://irc.freenode.net/rundeck
* Unix manual pages: RunDeck installation includes a set of Unix
manual pages describing the shell tools. <code>man -k rundeck</code>

## RunDeck from 30,000 feet

Expand All @@ -61,28 +50,28 @@ than serious development of workflow modules and state machines.

### RunDeck in context

RunDeck is meant to compliment the tools you already use and is geared
RunDeck is meant to compliment the tools you already use
(including frameworks like Puppet, Chef, and Rightscale) and is geared
towards helping you automate actions across them. If you currently
manage your servers by running commands from the terminal or through
scripts that SSH commands in a loop, RunDeck is a more user friendly
alternative. Instead of managing node lists in a spreadsheet or wiki
page and then having to transcribe the list to where you execute commands,
RunDeck acts as a command and control portal that lets you execute
commands using node filtering.
commands using features like node filtering and parallel execution.

RunDeck also works well for managing virtual servers, be they from a
cloud provider or from locally hosted virtualization software. The
node abstraction enabled by the RunDeck command dispatcher (eg
leveraging filtering tags and using node information from external sources)
helps cope managing dynamic environments.
node abstraction enabled by the RunDeck command dispatcher
helps you cope with managing dynamic environments.

Many automation tasks cross the boundaries of tool sets. For example,
deploying software or maintaining an application often involves
using tools up down the management tool chain. RunDeck gives a simple
to use interface to create a multi-step workflow that might call a
package mangager (eg RPM), a configuration mangement (eg Puppet or
Chef), system utilities, and your own scripts. RunDeck is really meant
to help glue tools together and in return enable a push button interface.
using tools up and down the management tool chain. RunDeck has a simple
to use interface to create multi-step workflows that might call a
package mangager, configuration mangement tool, system utilities, or your
own scripts. RunDeck is really meant to help glue tools together and
in return enable a push button interface you can hand off to others.

### RunDeck architecture

Expand All @@ -109,9 +98,9 @@ password as well as one or more user groups. An alternative
configuration to the flat file user directory, is LDAP (or
ActiveDirectory).
Users must also be authorized to perform actions like command and job
execution. This is controled by an access control facility that reads
policy files defined on disk. Privilege is granted if a user's group
membership meets the requirements of the policy.
execution. This is controlled by an access control facility that reads
policy files defined by the RunDeck administrator. Privilege is
granted if a user's group membership meets the requirements of the policy.

Two installation methods are supported:

Expand All @@ -123,15 +112,6 @@ Two installation methods are supported:
running right away. Perfect for bootstrapping a project or trying
a new feature.

## Getting help

* Mailing list:
[http://groups.google.com/group/rundeck-discuss](http://groups.google.com/group/rundeck-discuss)
* IRC: irc://irc.freenode.net/rundeck
* Unix manual pages: RunDeck installation includes a set of Unix
manual pages describing the shell tools. <code>man -k rundeck</code>


## What's next?

The remainder of the guide will give you a quick conceptual overview,
Expand Down
76 changes: 43 additions & 33 deletions docs/en/01-getting-started/01-chapter1.md
View file
Expand Up @@ -4,11 +4,11 @@

# Getting Started #

This chapter will be about getting started with RunDeck. We will begin
by explaining ... , then move on to ..., finally ... At the end of
this chapter you should understand what RunDeck is, how you should use
it and you should be all setup to do so.

This chapter helps new users getting started with RunDeck. We will begin
by explaining the basics, covering essential RunDeck concepts and
terminology and then move on to installation and finally, setup.
At the end of this chapter you should understand what RunDeck is, how
you should use it and you should be all setup to do so.

## RunDeck Basics ##

Expand All @@ -22,27 +22,29 @@ RunDeck supports a notion called Command dispatching wherein a
user specifies dispatch critera along with an action (called a
command) and this specification is used to perform a distributed execution.

Internally, a mechanism called the command dispatcher does
a lookup to find node resources meeting specified filtering criteria and
The *command dispatcher* is an internal mechanism that looks up
node resources meeting specified filtering criteria and then
performs the distributed command execution. The command executes in a data
context that contains information about the Node resource.
context that contains information about the Node resource. Besides
node filtering, dispatcher options include parameters to control
parrallel execution, ordering and error handling.

The command dispatcher supports two methods of command execution:

* Ad hoc commands: Execute any shell command or shell script across a
* *Ad-hoc commands*: Execute any shell command or shell script across a
set of hosts.
* Jobs: Encapsulate commands as a named Job and tie them
together into Job workflows.
* *Jobs*: Encapsulate commands as a named Job and tie them
together into multi-step workflows.

RunDeck provides both graphical and command line interfaces to
interact with the command dispatcher.

### Resource model ###

The command dispatcher works in conjunction with a resource model. A
resource model is a representation of hosts deployed in your
network. A _Node_ resource is either a physical or virtual instance
of an operating system that is network accessible.
*resource model* is a representation of nodes deployed in your
network. A _Node_ is a resource that is either a physical or virtual instance
of a network accessible host.

Nodes have a number of basic properties but these properties can be
extended to include arbitrary named key value pairs.
Expand All @@ -53,24 +55,24 @@ document requirement.

### Authorization ###

RunDeck uses an authorization model where users belong to groups and
those groups are associated with abitrarily defined roles.

RunDeck enforces an *access control policy* that grants certain
privileges to groups of users.
Every action executed through the RunDeck command dispatcher must meet
the requirements of an access control policy definition.

Since RunDeck respects the ACLs definition, you can use role-based
Since RunDeck respects the policy definition, you can use role-based
authorization to restrict some users to only a subset of actions. This
provides a Self-Service type interface, where some users can have
provides a self-service type interface, where some users can have
access to a limited set of actions to execute.

### Project ###

All RunDeck activities occur within the context of a single project.
A *project* is a place to separate management activity.
All RunDeck activities occur within the context of a project.
Each project has its own resource model and Job store.

Multiple projects can be maintained on the same RunDeck server.
Projects are independent of one another, so you can use them to
Projects are independent from one another, so you can use them to
organize unrelated systems within a single RunDeck
installation. This can be useful for managing different infrastructures.

Expand All @@ -83,16 +85,17 @@ either from source, system package or via the launcher.

The following operating systems are known to support RunDeck:

* Linux: Most recent distributions are likely to work
* Linux: Most recent distributions are likely to work
* Windows: XP, Server and above
* Mac OS X 10.4 or later
* Solaris or OpenSolaris

Root (or Administrator on Windows) is not required or recommended. We
recommend using a dedicated user account such as "rundeck".

If there is need for root access, please set up the RunDeck user
to have access via sudo.
to have access via [sudo].

[sudo]: http://en.wikipedia.org/wiki/Sudo

#### Java ####

Expand All @@ -102,7 +105,7 @@ runtime.
The install process requires that the latest version of Java 1.6
be installed. Both the [Open JDK](http://openjdk.java.net/) and [Sun/Oracle](http://java.com/) JVMs can be used.
You must have the JAVA_HOME environment variable defined
in your environment before running the install script.
in your environment before running the installation.

Verify your Java version to check it meets the requirement:

Expand All @@ -115,7 +118,7 @@ Verify your Java version to check it meets the requirement:

Cients should be set up to allow the RunDeck server user to connect to
the clients using SSH via public-key authentication. It should not
prompt for a password. There are various ways of installing SSH on
prompt for a password. There are various ways for installing SSH on
Windows; we recommend [Cygwin](http://www.cygwin.com/).

TCP ports 8080 and 1055 need to be open on the server. In addition,
Expand Down Expand Up @@ -145,10 +148,18 @@ Build clean

./build.sh -clean

The build will generate a launcher jar. On Linux build servers, an RPM
will also be generated.

### Installing on Linux ###

If you want to install RunDeck on Linux via a binary installer, you can generally do so through the basic package-management tool that comes with your distribution. If you’re on Fedora, you can use yum:
If you want to install RunDeck on Linux via a binary installer, you
can generally do so through the RPM tool that comes with your distribution.

$ rpm -i rundeck-1.0.0.noarch.rpm

To install it using yum:

$ yum install rundeck

### Installing on other platforms ###
Expand All @@ -159,7 +170,7 @@ Use the launcher as an alternative to a system package:
1. Define RDECK_BASE environment variable to the location of the install

~~~~~~~
export RDECK_BASE=$HOME/rundeck
export RDECK_BASE=$HOME/rundeck; # or where you like it
~~~~~~~

1. Create the directory for the installation.
Expand All @@ -174,7 +185,7 @@ Use the launcher as an alternative to a system package:
cp rundeck-launcher-1.0.0.jar $RDECK_BASE
~~~~~~~

1. Change directory and start the jar.
1. Change directory and run the jar.

~~~~~~~
cd $RDECK_BASE
Expand Down Expand Up @@ -219,9 +230,8 @@ logins useful during the getting started phase.

## Summary ##

You should have a basic understanding of what RunDeck. You
should also now have a working version of RunDeck on your system
that’s set up with your personal identity. It is now time to learn some
RunDeck basics.
You should now have a basic understanding of RunDeck. You
should also have a working version of RunDeck on your system
and login access. It is now time to learn some RunDeck basics.


0 comments on commit 6f33b28

Please sign in to comment.