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