sshproxy

image:https://github.com/cea-hpc/sshproxy/actions/workflows/tests.yml/badge.svg[ "Build Status", link="https://github.com/cea-hpc/sshproxy/actions/workflows/tests.yml"]

What is sshproxy?

sshproxy is used on a gateway to transparently proxy a user SSH connection on the gateway to an internal host via SSH. scp, sftp, rsync, etc. are supported.

sshproxy defines routes which bind an SSH listening address to a pool of destination hosts. It can then choose the first available destination or load-balance the connections with a simple round-robin algorithm.

Because of its design sshproxy is stateless (it is launched as a +ForceCommand+ by sshd). It can be made stateful by using etcd allowing to:

remember users connections and always connects a user to the same destination while a connection to this destination is alive,
periodically check if destination hosts are alive.

States stored in etcd can be displayed or modified with the +sshproxyctl+ command.

sshproxy can be configured to monitor SSH sessions and either to save them in files or to send them to the very simple +sshproxy-dumpd+ daemon. Sessions can be replayed with the +sshproxy-replay+ command.

Compilation

Install the Go (version >= 1.24) compiler suite: see http://golang.org/doc/install for details.

Define and export the +$GOPATH+ directory where the source code will be unpacked (e.g. '$HOME/go'):

$ export GOPATH=$HOME/go
$ mkdir -p $GOPATH/src/github.com/cea-hpc
$ cd $GOPATH/src/github.com/cea-hpc
$ tar xvJf sshproxy-X.Y.Z.tar.xz

Compile everything:

$ make

Installation

Install binaries and manpages:

# make install

+sshproxy+ and +sshproxy-dumpd+ are installed in +/usr/sbin+, +sshproxyctl+ and +sshproxy-replay+ in +/usr/bin+.

Optional installation

If you want to use clustershell groups with sshproxy, you have to install +libnodeset.so+ from https://github.com/fdiakh/nodeset-rs

If you don't, you'll still be able to use nodesets, but not clustershell groups.

You can check if sshproxy uses +libnodeset.so+ with this command:

$ sshproxyctl show config
[…]
libnodeset.so found
[…]

Configuration

There is a commented configuration file in the +config+ directory.

Configure +/etc/sshproxy/sshproxy.yaml+ to suit your needs.

Modify the SSH daemon configuration +/etc/ssh/sshd_config+ by adding:

ForceCommand /usr/sbin/sshproxy

Migrating to sshproxy 2

Version 2 brings a lot of changes to sshproxy:

configuration file:

all configuration options can now be set outside of overrides (those are the default values) or inside an override

users, groups and routes options have been replaced by the overrides system:

old style:

routes:
  default:
    some_default_options…
  service1:
    source: [an.ip.sshd.listens.to]
    some_sources_options…
users:
  - alice,bob:
      some_users_options…
groups:
  - foo,bar:
      some_groups_options…

new style:

some_default_options…
overrides:
  - match:
      - sources: [an.ip.sshd.listens.to]
    some_sources_options…
  - match:
      - users: [alice,bob]
    some_users_options…
overrides:
  - match:
      - groups: [foo,bar]
    some_groups_options…

the match conditions of the overrides system can be combined. Here is an example meaning "match if (the user is in the group foo and in the group bar) or ((the user is alice or bob) and the user is connected to an.ip.sshd.listens.to)":
```
overrides:
  - match:
      - groups: [foo]
        groups: [bar]
      - users: [alice,bob]
        sources: [an.ip.sshd.listens.to]
```
nodesets can now be used for the dest key
if libnodeset.so (from https://github.com/fdiakh/nodeset-rs) is found, it allows the use of clustershell groups where nodesets are allowed
new option: blocking_command runs a command before starting the ssh connection to the destination. If the command does not return 0, the connection is aborted

command line interface:

sshproxyctl convert has been added: it converts your old v1 configuration file to the v2 format. Can be used like this: sshproxyctl -c /etc/sshproxy/sshproxy.old.yaml convert > /etc/sshproxy/sshproxy.new.yaml
in all the tables, Host and Port columns are now merged into a single Host:Port
sshproxyctl get_config has been removed and replaced by sshproxyctl show config
sshproxyctl show hosts and sshproxyctl show users -all now display persist info
sshproxyctl enable HOST [PORT] has been removed and replaced by sshproxyctl enable -all|-host HOST [-port PORT]
sshproxyctl disable HOST [PORT] has been removed and replaced by sshproxyctl disable -all|-host HOST [-port PORT]
sshproxyctl forget HOST [PORT] has been removed and replaced by sshproxyctl forget host -all|-host HOST [-port PORT]
sshproxyctl error_banner (without any parameter) has been removed and replaced by sshproxyctl forget error_banner
sshproxyctl forget persist [-user USER] [-service SERVICE] [-host HOST] [-port PORT] has been added

Copying

sshproxy is distributed under the CeCILL-B, a French transposition of the BSD license. See the included files +Licence_CeCILL-B_V1-en.txt+ (English version) and +Licence_CeCILL-B_V1-fr.txt+ (French version) or visit http://www.cecill.info for details.

Authors

Current maintainer:

Cyril Servant https://github.com/cyrilst cyril.servant@cea.fr

Original author:

Arnaud Guignard https://github.com/arno

Contributors:

Olivier Delhomme https://github.com/od-cea
François Diakhaté https://github.com/fdiakh
Romain Fihue https://github.com/fihuer
Dominique Martinet https://github.com/martinetd

Documentation

See files in the +doc+ directory.

// vim:tw=78:ft=asciidoc:

Sshproxy

Install / Use

README