# 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 ##

```ruby
    $ 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 key and secret key:

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

### 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 [global options] command [command options] [arguments...]

VERSION
    0.2.0

GLOBAL OPTIONS
    --help    - Show this message
    --version - Display the program version

COMMANDS
    help - Shows a list of commands or help for one command
    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 help command` (ie `cabal help key`).

### Getting A Public Key ###

***To learn more, check out `cabal help key`***

This is an unprivileged call, so you won't actually need an access key or a secret key. This is more for somebody that wants to use the cabal cli utility to rather than curl or the like to grab a public key from the API to install as an authorized key on their servers.

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
```

### Connecting To A Server ###

***To learn more, check out `cabal help ssh`***

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

## Development ##

Branches and releases for this project are managed by [git-flow](https://github.com/nvie/gitflow).

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.**

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