Jossh - Your SSH Buddy

Jossh is

• a command line utility for running local scripts and commands over SSH.
• a ruby library for easier and prettier SSH deployment and automation.

Install

Add to your Gemfile

gem 'jossh'

Or install manually

gem install jossh

Features

1. Allows running one or more commands over SSH.
2. Allows running local scripts remotely
3. Allows running a script on multiple hosts.
4. Has four commands: ssh, ssh!, ssh_script and ssh_script!. The 'bang' versions generate pretty and indented output.
5. Uses a single SSH connection.
6. Uses a simple hash for defining hosts.
7. Allows storing host specifications in a YAML file.
8. Supports all options available in Net::SSH#start.
9. Prints output Heroku-style.
10. Has a command line interface - jossh <host> <script>

Command Line Usage

After installing, you can call jossh from the command line to run arbitrary commands or a local script over SSH.

$ jossh -h

Jossh

Usage:
  jossh <host> <script> [-- <arguments>...]
  jossh -m | --make-hostfile
  jossh -e | --edit-hostfile
  jossh -l | --list
  jossh -h | --help 
  jossh -v | --version

Arguments:
  <host>
    can be:
    - :symbol    : in this case we will look in ./ssh_hosts.yml or ~/ssh_hosts.yml
    - host       : in this case we will use the current logged in user
    - user@host

  <script> 
    can be:
    - a file in the current directory
    - a file in ~/jossh directory
    - one or more direct command

  <arguments>...
    When specifying a filename as the <script>, you may also pass additional
    arguments to it. 
    Use $1 - $9 in your script file to work with these arguments.
    Use $@ (or $*) to use the entire arguments string

Options:
  -m --make-hostfile     Generate a template ssh_hosts.yml 
  -e --edit-hostfile     Open the currently used ssh_hosts.yml file for editing
  -l --list              Show hosts in ./ssh_hosts.yml or ~/ssh_hosts.yml
  -h --help              Show this screen
  -v --version           Show version

Examples: 
  jossh :production "git status"
  jossh jack@server.com "cd ~ && ls -l"
  jossh server.com deploy
  jossh server.com rake -- db:migrate

---

Library Usage

Example 1: Host specifications in a YAML file

# example.rb
require 'jossh'

ssh! :localhost, ["cd /opt/app", "git pull"]

# ssh_hosts.yml
:localhost:
  :host: 'localhost'
  :user: 'vagrant'

Example 2: Host specifications directly in the code

# example.rb
require 'jossh'

localhost = {
  host: 'localhost',
  user: 'vagrant',
  forward_agent: true,
}

ssh! localhost, ["cd /opt/app", "git pull"]

Example 3: Run an external local script remotely

# example.rb
require 'jossh'

ssh_script! :production, deploy

# deploy
cd /opt/app
echo "-> Pulling source from origin"
git pull
echo "-> Restarting server"
touch 'tmp/restart.txt'
echo "-> Done"

See also: The examples folder

Host Specification File

When using a :symbol as the host name, Jossh will look for a YAML configuration file named ssh_hosts.yml. The file is expected to be either in the current directory or the user's home directory.

If you wish to use a different filename or location, use the ssh_hostfile method. If you specify only a filename or a relative path, Jossh will still look for this file in both the current directory and user's home directory.

# Specify exact location
ssh_hostfile "/etc/my_hosts.yml"
ssh! :myhost, 'ls'

# Look for ./configs/hosts.yml or ~/configs/hosts.yml
ssh_hostfile "configs/hosts.yml"
ssh! :myhost, 'ls'

You can ask Jossh to create a sample file for you by running:

$ jossh --make-hostfile

Working with Multiple Hosts

Define multiple hosts in the ssh_hosts.yml file by simply providing an array of other keys:

:web01:
  :host: web01.server.com
  :user: admin

:web02:
  :host: web02.server.com
  :user: admin

:production: 
  - :web01
  - :web02

See ssh_hosts.example.yml as an example.

Writing Scripts

The scripts you execute with Jossh are simple shell scripts. These variables are available to you inside the script:

$1 - $9 and $@ or $*

When running through the command line and using the jossh <host> <script> -- <arguments> syntax, these variables hold the arguments.

$@ and $* hold the entire arguments string.

Example:

# myscript
echo "-> Running requested rake task"
rake $@

And call it with: $ jossh :host myscript -- db:migrate

%{key}

When this syntax appears in your script, it will be replaced with any key from the host configuration.

Example:

echo "-> Migrating database on %{host}"
rake db:migrate