[[PageOutline]]
= Fabric =

[http://fabfile.org fabric] is a python framework for executing commands either locally or on a series of remote hosts.

Our [wiki:puppet puppet repo] contains a fabric directory with a fabfile.py the defines commands to help with the management of our servers.

== Why do we need fabric if we have puppet? ==

Puppet allows us to easily ensure that a set of commands and files are executed and copied to our servers (and will execute/copy the commands/files over and over again if necessary).

fabric allows us to execute/copy a command/file to one or more servers once and witness the output. Also, fabric allows us to perform operations locally, like list available servers or automate setting up a git remote for each server's puppet repository.

== How do I install fabric? ==

{{{
apt-get install fabric
}}}

I've written our fabfile.py using fabric 0.9.1.

== How do I use our fabric commands? ==

First, cd into the fabric directory. All fabric commands must be executed from the fabric directory.

Next, run the fab command followed by one or more sub-commands.

For example:

{{{
fab listServers
}}}

Will generate a list of servers located in our manifests/nodes/production directory.

You can limit the list by adding a colon separted argument to the command, by either specifying a specific server:

{{{
0 jamie@chicken:fabric$ fab listServers:mandela
mandela

Done.
0 jamie@chicken:fabric$
}}}

Or, by specifying a phrase to grep all server manifests for:

{{{
0 jamie@chicken:fabric$ fab listServers:mosh
albizu
chavez
daza
debs
didier
eagle
ella
jones
julia
june
lucius
lucy
lumumba
malcolm
mandela
menchu
proudhon
rodolpho
roe
sojourner
viewsic

Done.
0 jamie@chicken:fabric$
}}}

listServers is a local command, meaning it is executed on your computer.

In addition, there are several available remote commands, which will execute on remote servers. When running a remote command, the hosts you want to execute on much be specified with the h command, using the same syntax as listServers. For example, the true command is a test command that simply executes /usr/bin/true on the remote server:

{{{
0 jamie@chicken:fabric$ fab h:mandela true
[root@mandela.mayfirst.org] run: true

Done.
Disconnecting from root@mandela.mayfirst.org... done.
0 jamie@chicken:fabric$
}}}

== What other commands are available? ==

Run:

{{{
fab -l
}}}

To see a list of all available commands.

== How can I add new commands? ==

Simply edit the fabfile.py and commit and push your changes.