Contributing to Net::SSH

Contributions are welcome! Whether you're fixing a bug, adding a feature, or improving documentation, your help is appreciated.

Development Setup

  1. Fork and Clone: Fork the repository on GitHub, then clone your fork locally.

    git clone https://github.com/your-username/net-ssh.git
cd net-ssh

  2. Install Dependencies: Net::SSH uses Bundler to manage its dependencies. Make sure you have Bundler installed (gem install bundler), then run:

    bundle install

Running Tests

Net::SSH has a comprehensive test suite. You can run all tests using Rake:

bundle exec rake test

Integration Tests

Some tests are integration tests that require a running SSH server. They are disabled by default. To run them, you need to set the NET_SSH_RUN_INTEGRATION_TESTS environment variable.

NET_SSH_RUN_INTEGRATION_TESTS=1 bundle exec rake test

The project includes a Vagrant and Ansible setup to create a suitable environment for these tests. See test/integration/README.md for more details.

You can also use the provided Docker setup for a consistent testing environment. See the Docker for Development guide.

Test Helper Tests

Tests for the Net::SSH::Test framework itself are run separately:

bundle exec rake test_test

Code Style

This project uses RuboCop to enforce a consistent code style. Before submitting a pull request, please run RuboCop to check for offenses:

bundle exec rubocop

Our CI setup will also run this check, so it's best to fix any issues locally first.

Debugging

If you need to debug interactions with an SSH server, you can run a local OpenSSH server in debug mode. First, clone the OpenSSH repository:

git clone https://github.com/openssh/openssh-portable.git
cd openssh-portable

Then, build it. On macOS with Homebrew, you might do:

brew install openssl
autoreconf
./configure --with-ssl-dir=$(brew --prefix openssl) --with-audit=debug --enable-debug CPPFLAGS="-DDEBUG -DPACKET_DEBUG" CFLAGS="-g -O0"
make

Finally, run the server in debug mode on a custom port (e.g., 2222):

echo '#' > /tmp/sshd_config
ssh-keygen -t rsa -f /tmp/ssh_host_rsa_key -N ''

./sshd -p 2222 -D -d -d -d -e -f /tmp/sshd_config -h /tmp/ssh_host_rsa_key

This will provide extremely verbose output about the SSH protocol exchange, which can be invaluable for debugging.

Reporting Issues

  • Bug Reports & Feature Requests: Please use the GitHub Issues tracker. Use the provided ISSUE_TEMPLATE.md to ensure you provide all necessary information, including an example script to reproduce the problem.
  • Security Vulnerabilities: To report a security vulnerability, please use the private vulnerability reporting feature on GitHub.