capistrano-ssh-doctor 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 7f6a315084d957611956b98eb45770af4d663d31
+  data.tar.gz: 2ed9041723f8508c57e4e54d2166fee521d67dc9
+SHA512:
+  metadata.gz: 736cb8e50188ecd0dc1144a7cd0d3624e5adbfd878623ad2f725ab3d7154aec681b6cfc19bda5d53154f098dc663743b8ba225d79c4bcc9a168bf3ab4d42774d
+  data.tar.gz: 67a494421f56b50a120a3527d9af164d9e40cdc37cf3f4f212ece7203705ffdf480a4fde641c19a07d286f787136fd3a3fd9820b374d6d0663126d583ebfc8ef

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,116 @@
+# Capistrano SSH Doctor
+
+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-doctor` works only with Capistrano **3+**.
+
+### Who should use it?
+
+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.
+
+If you have enough knowldge/experience with `ssh` tool and you're sure you have
+`ssh-agent` forwarding working for your server, you probably don't need this
+plugin.
+
+### Installation
+
+Put the following in your application's `Gemfile`:
+
+    group :development do
+      gem 'capistrano', '~> 3.1'
+      gem 'capistrano-ssh-doctor'
+    end
+
+Then run in the console:
+
+    $ bundle install
+
+Put the following in `Capfile` file:
+
+    require 'capistrano/ssh_doctor'
+
+### Usage
+
+This plugin is intended to be used **before** any deployment task.
+
+In the console run:
+
+    $ bundle exec cap production ssh:doctor
+
+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 `ssh:doctor` task again to see the
+progress.
+
+Repeat the process until `ssh:doctor` 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 `ssh:doctor`
+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)
+
+# TODO
+- do not store text in report hash, store only success/fail there

data/Rakefile

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

data/capistrano-ssh-doctor.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_doctor/version'
+
+Gem::Specification.new do |gem|
+  gem.name          = 'capistrano-ssh-doctor'
+  gem.version       = Capistrano::SshDoctor::VERSION
+  gem.authors       = ['Bruno Sutic']
+  gem.email         = ['bruno.sutic@gmail.com']
+  gem.description   = <<-EOF.gsub(/^\s+/, '')
+    This plugin helps you setup and debug `ssh-doctor` 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-doctor` forwarding for Capistrano deployment.'
+  gem.homepage      = 'https://github.com/bruno-/capistrano-ssh-doctor'
+
+  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_doctor.rb

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

data/lib/capistrano/ssh_doctor/dsl.rb

@@ -0,0 +1,14 @@
+require_relative 'report'
+
+module Capistrano
+  module SshDoctor
+    module DSL
+
+      def report
+        Capistrano::SshDoctor::Report.report
+      end
+
+    end
+  end
+end
+self.extend Capistrano::SshDoctor::DSL

data/lib/capistrano/ssh_doctor/report.rb

@@ -0,0 +1,67 @@
+require_relative 'report/messages'
+
+module Capistrano
+  module SshDoctor
+    class Report
+
+      include Capistrano::SshDoctor::Report::Messages
+
+      def self.report
+        @report ||= new
+      end
+
+      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_doctor/report/messages.rb

@@ -0,0 +1,168 @@
+module Capistrano
+  module SshDoctor
+    class Report
+      module Messages
+
+        def default_messages
+          {
+            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 for your servers
+            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_doctor/version.rb

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

data/lib/capistrano/tasks/ssh_doctor.rake

@@ -0,0 +1,117 @@
+require 'capistrano/ssh_doctor/dsl'
+
+namespace :ssh 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-doctor supports only git.'
+        puts 'Please change `scm` setting to `:git`.'
+        exit 1
+      end
+    end
+
+    task :repo_url do
+      if fetch(:repo_url) =~ /^http/
+        report.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.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.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.report_error_for('local_private_key_exists')
+      end
+    end
+
+    task :agent_running_env_var do
+      unless ENV.include?('SSH_AUTH_SOCK')
+        report.report_error_for('local_agent_running_env_var')
+      end
+    end
+
+    task :agent_running_ssh_add do
+      if !system('ssh-add -l')
+        if $? == 2
+          report.report_error_for('local_agent_running_ssh_add')
+        elsif $? == 1
+          report.report_error_for('local_keys_added_to_agent')
+        end
+      end
+    end
+
+    task :repo_access do
+      unless system({ 'GIT_ASKPASS' => '/bin/echo' }, "git ls-remote #{fetch(:repo_url)}")
+        report.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.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.report_error_for('remote_repo_access', hosts) if hosts.any?
+    end
+
+  end
+
+  desc 'Perform ssh doctor checks'
+  task :doctor do
+    invoke 'ssh:config:git'
+    invoke 'ssh:config:repo_url'
+    invoke 'ssh:config:password'
+    invoke 'ssh:config:agent_forwarding'
+    invoke 'ssh:local:private_key_exists'
+    invoke 'ssh:local:agent_running_env_var'
+    invoke 'ssh:local:agent_running_ssh_add'
+    invoke 'ssh:local:repo_access'
+    invoke 'ssh:remote:agent_running'
+    invoke 'ssh:remote:repo_access'
+    report.print
+  end
+
+end

metadata

@@ -0,0 +1,90 @@
+--- !ruby/object:Gem::Specification
+name: capistrano-ssh-doctor
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- Bruno Sutic
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2014-04-23 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-doctor` 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-doctor.gemspec
+- lib/capistrano-ssh-doctor.rb
+- lib/capistrano/ssh_doctor.rb
+- lib/capistrano/ssh_doctor/dsl.rb
+- lib/capistrano/ssh_doctor/report.rb
+- lib/capistrano/ssh_doctor/report/messages.rb
+- lib/capistrano/ssh_doctor/version.rb
+- lib/capistrano/tasks/ssh_doctor.rake
+homepage: https://github.com/bruno-/capistrano-ssh-doctor
+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-doctor` forwarding for Capistrano
+  deployment.
+test_files: []