Cabal

Cabal is a simple system for SSH key distribution and consumption. This is a CLI application that allows one to consume those keys.

Installation

    $ gem install cabal

Usage

To get started, you'll need to create .cabal.yml in your user's home directory, and you'll need to provide at least the URL of your Cabal::API. If you plan to use the ssh command to connect to a server that has an authorized Cabal key, you'll also need to specify your access token and secret token (provided by your Cabal::API administrator):

---
:url: http://your-cabal-hostname/path/to/the/api
:access_key: your-access-token
:secret_key: your-secret-token

Getting Help

The cabal application provides some nicely-formatted help on the command line. To access the help, provided that you've created your ~/.cabal.yml, run the following:

cabal --help

That will output something like this:

NAME
  cabal - An interface to the Cabal API

SYNOPSIS
  cabal command

OPTIONS
  -h, --help - Shows this message

COMMANDS
  key - Get the public key for a cluster
  ssh - Connect to a node on a cluster

To get help on a specific command, you can cabal command --help (ie cabal key --help).

Listing Known Clusters

To learn more, check out cabal list --help

This is a privileged call, so you need an access key and a secret key in your configuration file.

To get a list of the clusters that Cabal knows about, you'd do the following:

cabal list

Getting A Public Key

To learn more, check out cabal key --help

To get a public key for a cluster named "totallyarealcluster," you'd do the following:

cabal key totallyarealcluster

Only one key can be retrieved per call, but we process all of the arguments as part of the cluster name. In short, all of the following variations have the same result:

cabal key "Totally a real cluster"
cabal key "totally a real cluster"
cabal key Totally a real clusteR
cabal key totallyarealcluster

This command is an alternative to hitting the API endpoint via curl (or similar) to grab a public key, which might be used when installing an authorized key on a server. The following example would append the key for "totallyarealcluster" to the current user's authorized_keys file if it wasn't already present:

if ! grep -q totallyarealcluster ~/.ssh/authorized_keys
then
    cabal key totallyarealcluster >> ~/.ssh/authorized_keys
fi

This is an unprivileged call, so you won't actually need an access key or a secret key.

Connecting To A Server

To learn more, check out cabal ssh --help

This is a privileged call, so you need an access key and a secret key in your configuration file.

To connect to a server that has an authorized key that was generated by your Cabal API, you'll do the following (providing the cluster name for the key is "totallyarealcluster"):

cabal ssh -c totallyarealcluster user@hostname

This basically does the following:

Retrieves the private key for "totallyarealcluster"
Adds the private key as an identity in your ssh-agent
Connects you to the server, forwarding your ssh-agent
Removes the key and ALL ssh-agent identities on disconnect

By default, the forwarded ssh-agent will only have access to the private key for 30 minutes. To change this, you can use the --lifetime option to specify a different lifetime for your session.

For tasks that may take a very long time (cluster upgrades, etc), you can pass a lifetime of 0 to keep the agent forwarding in place for the entirety of your session.

Development

Branches and releases for this project are managed by git-flow.

After checking out the repo, run bin/setup to install dependencies. Then, run bin/console for an interactive prompt that will allow you to experiment.

Contributing

Note: Please base all feature branches on the develop branch.

Fork it ( https://github.com/engineyard/cabal/fork )
Create your feature branch (git checkout -b my-new-feature)
Commit your changes (git commit -am 'Add some feature')
Push to the branch (git push origin my-new-feature)
Create a new Pull Request against the develop branch