capistrano-ssh-agent 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 5d3e8cc5d12269f8aa8a757bae27765b38efb379
+  data.tar.gz: 2c705d0126103905d58d70bb1b7b7467f7f59393
+SHA512:
+  metadata.gz: db30855c96f83102e2e8c465b8d634831e60b4d1f8c7616bb82e93e4b26dc30b4a8c762f48d01da45f5d92602f4e7a9f8b6ed53c3ff17a912962288ede15f3db
+  data.tar.gz: 7252c3eda9fa25dbf27120f8a4f7bd1178c3c3cb0364fe21e17153642628348c59852742252fe4b130bf64c4efbc9ed01c1a07bb61479b810f351debc56b2ac6

data/LICENSE.md

@@ -0,0 +1,19 @@
+Copyright (C) 2014 Bruno Sutic
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the "Software"),
+to deal in the Software without restriction, including without limitation
+the rights to use, copy, modify, merge, publish, distribute, sublicense,
+and/or sell copies of the Software, and to permit persons to whom the
+Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included
+in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
+OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,
+DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE
+OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,113 @@
+# Capistrano::SshAgent
+
+This plugin helps you setup and debug `ssh-agent` forwarding for Capistrano
+deployment.
+
+It's created to complement the official [capistrano authentication guide](http://capistranorb.com/documentation/getting-started/authentication-and-authorisation/).
+
+The following is presumed:
+- you're using `git`
+- you want to use passwordless ssh login to the servers
+- you want to use the `ssh-agent` forwarding strategy for checking out code in
+the remote repository (btw. good choice, it's a least hassle)
+
+The plugin will report errors (and offer steps to solution) if you deviate from
+this configuration. The above assumptions should hold true for 98% users.
+
+`capistrano-ssh-agent` works only with Capistrano **3+**.
+
+### Who should use it?
+
+If you have enough knowldge/experience with `ssh` tool and you're sure you have
+`ssh-agent` forwarding working for your server, feel free to uninstall this
+plugin.
+
+The plugin is made for beginners and users that are not sure if their setup is
+good, so they want to confirm or debug it.
+
+### Installation
+
+Put the following in your application's `Gemfile`:
+
+    group :development do
+      gem 'capistrano', '~> 3.1'
+      gem 'capistrano-ssh-agent'
+    end
+
+Then run in the console:
+
+    $ bundle install
+
+Put the following in `Capfile` file:
+
+    require 'capistrano/ssh_agent'
+
+### Usage
+
+This plugin is intended to be used **before** any deployment task.
+
+In the console run:
+
+    $ bundle exec cap production check_ssh_agent
+
+The plugin will perform a number of checks and output a report at the end.
+
+**Solving Errors**
+
+In case there are errors in your setup, specific instructions for next
+steps will be provided in report output.
+
+**Important:** errors should be tackled in the order of their output. So, if
+you got errors 2, 5 and 7 in the report, start by solving error 2.
+
+It is very probable that "solving" one or two initial errors will actually make
+everything work. A lot of the checks are inter-dependent. So don't be
+discouraged if you see a lot of the errors in the beginning.
+
+Once you solved a problem, run the `check_ssh_agent` task again to see the
+progress.
+
+Repeat the process until `check_ssh_agent` task reports success for all the
+tasks. You're ok with proceeding with the deployment then.
+
+### Which checks are performed?
+
+1. checks that you're using `git` repository protocol
+2. checks that ssh private key file exists locally
+3. checks if `ssh-agent` process is running locally
+4. checks that `ssh-add` process can communicate with `ssh-agent`
+5. checks that ssh private keys are loaded to `ssh-agent`
+6. checks that remote code repository is accessible from local machine
+7. checks passwordless ssh login is used for all servers
+8. checks `forward_agent` capistrano option is set to `true` for all servers
+9. checks `ssh-agent` is actually forwared to all the servers
+10. checks remote code repository is accessible from all the servers
+
+You'll see the results for all the checks in the output of `check_ssh_agent`
+task.
+
+### More Capistrano automation?
+
+If you'd like to streamline your Capistrano deploys, you might want to check
+these zero-configuration, plug-n-play plugins:
+
+- [capistrano-unicorn-nginx](https://github.com/bruno-/capistrano-unicorn-nginx)<br/>
+no-configuration unicorn and nginx setup with sensible defaults
+- [capistrano-postgresql](https://github.com/bruno-/capistrano-postgresql)<br/>
+plugin that automates postgresql configuration and setup
+- [capistrano-rbenv-install](https://github.com/bruno-/capistrano-rbenv-install)<br/>
+would you like Capistrano to install rubies for you automatically?
+- [capistrano-safe-deploy-to](https://github.com/bruno-/capistrano-safe-deploy-to)<br/>
+if you're annoyed that Capistrano does **not** create a deployment path for the
+app on the server (default `/var/www/myapp`), this is what you need!
+
+### Contributing and bug reports
+
+If you got stuck at some point and really can't find a solution, please open a
+[github issue](/issues) and maybe I can help you.
+
+Also, I can use your problem to improve this plugin.
+
+### License
+
+[MIT](LICENSE.md)

data/Rakefile

@@ -0,0 +1 @@
+require "bundler/gem_tasks"

data/capistrano-ssh-agent.gemspec

@@ -0,0 +1,30 @@
+# -*- encoding: utf-8 -*-
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'capistrano/ssh_agent/version'
+
+Gem::Specification.new do |gem|
+  gem.name          = 'capistrano-ssh-agent'
+  gem.version       = Capistrano::SshAgent::VERSION
+  gem.authors       = ['Bruno Sutic']
+  gem.email         = ['bruno.sutic@gmail.com']
+  gem.description   = <<-EOF.gsub(/^\s+/, '')
+    This plugin helps you setup and debug `ssh-agent` forwarding for Capistrano
+    deployment.
+
+    It peforms a number of checks on the local machine as well as on the
+    servers. Report output with suggested next steps is provided in case there
+    are any errors with the setup.
+  EOF
+  gem.summary       = 'This plugin helps you setup and debug `ssh-agent` forwarding for Capistrano deployment.'
+  gem.homepage      = 'https://github.com/bruno-/capistrano-ssh-agent'
+
+  gem.license       = 'MIT'
+
+  gem.files         = `git ls-files`.split($/)
+  gem.require_paths = ['lib']
+
+  gem.add_dependency 'capistrano', '>= 3.1'
+
+  gem.add_development_dependency 'rake'
+end

data/lib/capistrano/ssh_agent.rb

@@ -0,0 +1 @@
+load File.expand_path("../tasks/ssh_agent.rake", __FILE__)

data/lib/capistrano/ssh_agent/helper_methods.rb

@@ -0,0 +1,21 @@
+require_relative 'report'
+
+module Capistrano
+  module SshAgent
+    module HelperMethods
+
+      def initalize_report
+        @report = Capistrano::SshAgent::Report.new
+      end
+
+      def report_error_for(task_name, hosts=nil)
+        @report.report_error_for(task_name, hosts)
+      end
+
+      def print_report
+        @report.print
+      end
+
+    end
+  end
+end

data/lib/capistrano/ssh_agent/report.rb

@@ -0,0 +1,63 @@
+require_relative 'report/messages'
+
+module Capistrano
+  module SshAgent
+    class Report
+
+      include Capistrano::SshAgent::Report::Messages
+
+      def initialize
+        @report_messages = default_messages
+      end
+
+      def report_error_for(key, hosts=nil)
+        error_message = send(key + "_error", hosts)
+        set_error(key.to_sym, error_message)
+      end
+
+      def print
+        print_header
+        @report_messages.each_with_index do |(key, message), index|
+          print_message(index + 1, message)
+        end
+        print_footer
+      end
+
+    private
+
+      def set_error(key, message)
+        @report_messages[key] = [ :error, message ]
+      end
+
+      def has_errors?
+        @report_messages.any? {|key, value| value[0] == :error }
+      end
+
+      def print_header
+        puts
+        puts "SSH agent forwarding report"
+        puts "---------------------------"
+        puts
+      end
+
+      def print_message(index, message)
+        puts "#{index}. [#{message[0]}] #{message[1]}"
+        puts
+      end
+
+      def print_footer
+        puts "----------------------"
+        puts
+        if has_errors?
+          puts "It seems SSH agent forwarding is not set up correctly."
+          puts "Follow the suggested steps described in error messages."
+          puts "Errors (if more than one) are ordered by importance, so always start with the first one."
+        else
+          puts "It seems SSH agent forwarding is set up correctly!"
+          puts "You can continue with the deployment process."
+        end
+      end
+
+    end
+  end
+end

data/lib/capistrano/ssh_agent/report/messages.rb

@@ -0,0 +1,171 @@
+module Capistrano
+  module SshAgent
+    class Report
+      module Messages
+
+        def default_messages
+          {
+            config_repo_url: [
+              :success, '`repo_url` setting ok'
+            ],
+            config_repo_url: [
+              :success, '`repo_url` setting ok'
+            ],
+            local_private_key_exists: [
+              :success, 'ssh private key file exists'
+            ],
+            local_agent_running_env_var: [
+              :success, '`ssh-agent` process seems to be running locally'
+            ],
+            local_agent_running_ssh_add: [
+              :success, '`ssh-agent` process recognized by `ssh-add` command'
+            ],
+            local_keys_added_to_agent: [
+              :success, 'ssh private keys added to `ssh-agent`'
+            ],
+            local_repo_access: [
+              :success, 'application repository accessible from local machine'
+            ],
+            config_password: [
+              :success, 'all hosts using passwordless login'
+            ],
+            config_agent_forwarding: [
+              :success, '`forward_agent` ok for all hosts'
+            ],
+            remote_agent_running: [
+              :success, 'ssh agent successfully forwarded to remote hosts'
+            ],
+            remote_repo_access: [
+              :success, 'application repository accessible from remote hosts'
+            ]
+          }
+        end
+
+        def config_repo_url_error(_)
+          <<-EOF.gsub(/^\s+/, '')
+            It seems the git repository url in `repo_url` setting uses https
+            protocol. Https protocol prompts for password and so git protocol
+            should be used.
+
+            Actions:
+            - change `repo_url` setting in `config/deploy.rb` file to use git protocol.
+            Example for github: `git@github.com:username/repo.git`
+          EOF
+        end
+
+        def config_password_error(hosts)
+          msg = "It seems Capistrano connects to the following hosts using password login:\n"
+          msg << hosts.map(&:to_s).join(', ')
+          msg.concat "\n"
+          msg.concat <<-EOF.gsub(/^\s+/, '')
+            It is strongly suggested to use passwordless ssh login.
+
+            Actions:
+            - make sure you're *not* using password to connect to any of the  servers.
+            - remove any password setting from `ssh_options` in Capistrano stage files
+            (e.g. `config/deploy/production.rb`).
+            By removing password configuration - the default, passwordless ssh
+            connection will be used.
+            - setup passwordless ssh connection
+            http://askubuntu.com/questions/4830/easiest-way-to-copy-ssh-keys-to-another-machine/4833#4833
+          EOF
+        end
+
+        def config_agent_forwarding_error(hosts)
+          msg = "It seems Capistrano connects without ssh agent forwarding to the following hosts:\n"
+          msg << hosts.join(', ')
+          msg.concat "\n"
+          msg.concat <<-EOF.gsub(/^\s+/, '')
+            Actions:
+            - make sure Capistrano uses the default ssh option for `forward_agent`.
+            Just remove any `forward_agent` setting from the stage file (e.g.
+            `config/deploy/production.rb`) and the default, `true` value will be used.
+          EOF
+        end
+
+        def local_private_key_exists_error(_)
+          <<-EOF.gsub(/^\s+/, '')
+            Uh, oh. It seems you do not have ssh private keys generated, or they're
+            not located in standard location.
+
+            Actions:
+            - here's a good guide how to generate ssh private keys and set them
+            up with github
+            https://help.github.com/articles/generating-ssh-keys
+          EOF
+        end
+
+        def local_agent_running_env_var_error(_)
+          <<-EOF.gsub(/^\s+/, '')
+            It seems `ssh-agent` is not running on local machine.
+
+            Actions:
+            - follow this guide
+            http://mah.everybody.org/docs/ssh
+          EOF
+        end
+
+        def local_agent_running_ssh_add_error(_)
+          <<-EOF.gsub(/^\s+/, '')
+            It seems ssh-add cannot make a connection with ssh-agent process
+            on local machine.
+
+            Actions:
+            - are you sure all the previous checks are passing? Make sure all
+            the above checks are successful before trying to make this one
+            pass
+            - try adding ssh keys to ssh-agent by executing
+            $ ssh-add ~/.ssh/id_rsa
+            - if the above does not work follow this guide to setup ssh-agent process
+            http://mah.everybody.org/docs/ssh
+          EOF
+        end
+
+        def local_keys_added_to_agent_error(_)
+          <<-EOF.gsub(/^\s+/, '')
+            It seems local ssh-agent process has no loaded keys.
+
+            Actions:
+            - add ssh private key to ssh-agent with this command
+            $ ssh-add /path/to/ssh_private_key
+            If ssh private key is in a standard location, then you most likely need this
+            $ ssh-add ~/.ssh/id_rsa
+          EOF
+        end
+
+        def local_repo_access_error(_)
+          <<-EOF.gsub(/^\s+/, '')
+            It seems git application repository cannot be accessed from local machine.
+
+            Actions:
+            - here's a guide to setting passwordless access to github repositories.
+            You should most likely follow just steps 3 and 4 from the guide if
+            all the previous checks are successful.
+            https://help.github.com/articles/generating-ssh-keys#step-3-add-your-ssh-key-to-github
+          EOF
+        end
+
+        def remote_agent_running_error(hosts)
+          msg = "It seems Capistrano did not succeed in making ssh agent forwarding for these hosts:\n"
+          msg << hosts.join(', ')
+          msg.concat "\n"
+          msg.concat <<-EOF.gsub(/^\s+/, '')
+            Actions:
+            - make sure all the previous checks pass
+          EOF
+        end
+
+        def remote_repo_access_error(hosts)
+          msg = "It seems Capistrano cannot access application git repository from these hosts:\n"
+          msg << hosts.join(', ')
+          msg.concat "\n"
+          msg.concat <<-EOF.gsub(/^\s+/, '')
+            Actions:
+            - make sure all the previous checks pass. That should make this one work too.
+          EOF
+        end
+
+      end
+    end
+  end
+end

data/lib/capistrano/ssh_agent/version.rb

@@ -0,0 +1,5 @@
+module Capistrano
+  module SshAgent
+    VERSION = "0.0.1"
+  end
+end

data/lib/capistrano/tasks/ssh_agent.rake

@@ -0,0 +1,123 @@
+require 'capistrano/ssh_agent/helper_methods'
+
+include Capistrano::SshAgent::HelperMethods
+
+namespace :ssh_agent do
+
+  namespace :config do
+
+    task :git do
+      unless fetch(:scm) == :git
+        puts 'It seems you are NOT using git as a Capistrano strategy. At the moment capistrano-ssh-agent supports only git.'
+        puts 'Please change `scm` setting to `:git`.'
+        exit 1
+      end
+    end
+
+    task :repo_url do
+      if fetch(:repo_url) =~ /^http/
+        report_error_for('config_repo_url')
+      end
+    end
+
+    task :password do
+      hosts = []
+      on release_roles :all do
+        if host.netssh_options[:password]
+          hosts << host
+        end
+      end
+      report_error_for('config_password', hosts) if hosts.any?
+    end
+
+    task :agent_forwarding do
+      hosts = []
+      on release_roles :all do
+        unless host.netssh_options[:forward_agent]
+          hosts << host
+        end
+      end
+      report_error_for('config_agent_forwarding', hosts) if hosts.any?
+    end
+
+  end
+
+  namespace :local do
+
+    task :private_key_exists do
+      specified_keys = fetch(:ssh_options, {})[:keys] || ''
+      unless File.exists?(File.expand_path('~/.ssh/id_rsa')) ||
+        File.exists?(File.expand_path('~/.ssh/id_dsa')) ||
+        File.exists?(specified_keys)
+        report_error_for('local_private_key_exists')
+      end
+    end
+
+    task :agent_running_env_var do
+      unless ENV.include?('SSH_AUTH_SOCK')
+        report_error_for('local_agent_running_env_var')
+      end
+    end
+
+    task :agent_running_ssh_add do
+      if !system('ssh-add -l') && $? == 2
+        report_error_for('local_agent_running_ssh_add')
+      end
+    end
+
+    task :keys_added_to_agent do
+      if !system('ssh-add -l') && $? == 1
+        report_error_for('local_keys_added_to_agent')
+      end
+    end
+
+    task :repo_access do
+      unless system({ 'GIT_ASKPASS' => '/bin/echo' }, "git ls-remote #{fetch(:repo_url)}")
+        report_error_for('local_repo_access')
+      end
+    end
+
+  end
+
+  namespace :remote do
+
+    task :agent_running do
+      hosts = []
+      on release_roles :all do
+        if capture(:echo, '$SSH_AUTH_SOCK').empty?
+          hosts << host
+        end
+      end
+      report_error_for('remote_agent_running', hosts) if hosts.any?
+    end
+
+    task repo_access: :'git:wrapper' do
+      hosts = []
+      on release_roles :all do
+        with fetch(:git_environmental_variables) do
+          hosts << host unless strategy.check
+        end
+      end
+      report_error_for('remote_repo_access', hosts) if hosts.any?
+    end
+
+  end
+
+end
+
+desc 'Perform ssh agent checks'
+task :check_ssh_agent do
+  initalize_report
+  invoke 'ssh_agent:config:git'
+  invoke 'ssh_agent:config:repo_url'
+  invoke 'ssh_agent:config:password'
+  invoke 'ssh_agent:config:agent_forwarding'
+  invoke 'ssh_agent:local:private_key_exists'
+  invoke 'ssh_agent:local:agent_running_env_var'
+  invoke 'ssh_agent:local:agent_running_ssh_add'
+  invoke 'ssh_agent:local:keys_added_to_agent'
+  invoke 'ssh_agent:local:repo_access'
+  invoke 'ssh_agent:remote:agent_running'
+  invoke 'ssh_agent:remote:repo_access'
+  print_report
+end

metadata

@@ -0,0 +1,90 @@
+--- !ruby/object:Gem::Specification
+name: capistrano-ssh-agent
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- Bruno Sutic
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2014-04-16 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: capistrano
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.1'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: |
+  This plugin helps you setup and debug `ssh-agent` forwarding for Capistrano
+  deployment.
+  It peforms a number of checks on the local machine as well as on the
+  servers. Report output with suggested next steps is provided in case there
+  are any errors with the setup.
+email:
+- bruno.sutic@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.md
+- README.md
+- Rakefile
+- capistrano-ssh-agent.gemspec
+- lib/capistrano-ssh-agent.rb
+- lib/capistrano/ssh_agent.rb
+- lib/capistrano/ssh_agent/helper_methods.rb
+- lib/capistrano/ssh_agent/report.rb
+- lib/capistrano/ssh_agent/report/messages.rb
+- lib/capistrano/ssh_agent/version.rb
+- lib/capistrano/tasks/ssh_agent.rake
+homepage: https://github.com/bruno-/capistrano-ssh-agent
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.1.5
+signing_key: 
+specification_version: 4
+summary: This plugin helps you setup and debug `ssh-agent` forwarding for Capistrano
+  deployment.
+test_files: []