[[PageOutline]]
= freepuppet-helper =

freepuppet-helper is a python script for executing commands either locally or on a series of remote hosts.

Our [wiki:puppet puppet repo] contains a helper directory with freepuppet-helper.py and freepuppet-helper.

== Why do we need a python script 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).

The freepuppet-helper script allows us to execute/copy a command/file to one or more servers once and witness the output. Also, it 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 it? ==

It's already there with the git repo. For convenience, you should take a couple extra steps:

 * Add a symlink to your freepuppet-helper in your ~/bin directory (or another directory in your $PATH)
 * Add this line to your ~/.bashrc file, changing the path to the appropriate value:
{{{
export FREEPUPPET_REPO_PATH=/home/jamie/projects/mfpl/puppet/confdir
}}}

== How do I use it? ==

Run freepuppet-helper followed by one or more sub-commands.

For example:

{{{
freepuppet-helper ls
}}}

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:~$ freepuppet-helper ls:mandela
mandela
0 jamie@chicken:~$
}}}

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

{{{
0 jamie@chicken:~$ freepuppet-helper ls:mosh
albizu
chavez
daza
debs
didier
dorothy
eagle
ella
galeano
jones
julia
june
lucius
lucy
lumumba
malcolm
mandela
menchu
proudhon
rodolpho
roe
sojourner
viewsic
0 jamie@chicken:~$
}}}

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


== What other commands are available? ==

You can search for server information to find specifics about the server using the ld command.

Show manifest details for a specific server.
{{{
0 Thu Nov 10 ross:~/testing/puppet/confdir/helper$ freepuppet-helper ld:debord

debord

 | node | => debord.mayfirst.org

 | m_backupninja::server::configure_node | => debord

 | $mfpl_location | => telehouse

 | $mfpl_purpose | => saharareporters web server

 | monkeysphere::publish_server_keys | => debord

 | $mfpl_namesake | => https://wikimedia.org/en/wiki/Guy_Debord

 | $mfpl_backup_rsync_target | => ali.mayfirst.org

 | hostgroups |  =>  | telehouse-servers | ssh-servers

 | m_nagios_host | => debord

 | parents |  =>  | avensys-gateway | bolivar | telehouse-gateway

 | address | => 209.51.180.236

 | include |  =>  | m_sshd::default | m_minimal | m_addroutes | m_esmtp | m_backupninja::mysql

 | gpg::publish_user_key | => root

 | $mfpl_backup_rdiff_target | => robideau.mayfirst.org


0 Thu Nov 10 ross:~/testing/puppet/confdir/helper$ 

}}}

Or you can search for a particular component in the manifest by adding search terms.

{{{
0 Thu Nov 10 ross:~/testing/puppet/confdir/helper$ freepuppet-helper ld:debord backup

debord

 | m_backupninja::server::configure_node |  => debord

 | $mfpl_backup_rdiff_target |  => robideau.mayfirst.org

 | $mfpl_backup_rsync_target |  => ali.mayfirst.org


0 Thu Nov 10 ross:~/testing/puppet/confdir/helper$ 
}}}

ld is a subcommand of freepuppet-helper.

Run:

{{{
fab -l
}}}

To see a list of all available commands (and their aliases)

== How can I add new commands? ==

Simply edit the freepuppet-helper.py script and commit and push your changes.

== How can I do system upgrades? ==

You can follow these [wiki:puppet/running-operating-system-updates instructions for system upgrades].