ssh-capture (on Unix)

ssh-capture — Captures TCP connections for tunneling or FTP-SFTP conversion

Synopsis

ssh-capture [options...] COMMAND [arguments...]

Description

ssh-capture is a component of Tectia ConnectSecure on Unix.

The ssh-capture command runs the specified command with the given arguments. The command and its child processes will have automatic TCP connection capturing enabled. Depending on the filter rules configured for the Tectia Connection Broker, the captured connections may then be converted from FTP to SFTP, tunneled, blocked, or passed through in plaintext.

Options

The following options are available:

-D, --debug=LEVEL

Sets the debug level string to LEVEL. The following debug levels can be used:

1 - includes information about fatal errors
3 - includes initialization messages
5 - includes information about the TCP connections
7 - includes information about DNS resolving, and other more detailed debugging information.

-F, --fallback

Falls back to plaintext connection mode if a secure connection cannot be established (default: no fallback). Note that this option is effective only if ssh-capture cannot connect to Connection Broker and the value of the fallback-to-plain attribute in the rule element in the configuration file cannot be checked.

-l, --localhost

Enables capturing connections to the local host (127.0.0.1). The default is to let local host connections pass through in plaintext.

Usually, there is no need to capture connections within the local host. For testing purposes and for generic scripts, capturing can be activated with this setting. Notice, however, that this setting stops the fallback option from working for FTP-SFTP conversion in case the Secure Shell server does not answer.

-h, --help

Displays a short summary of command-line options and exits.

Examples

The Tectia ConnectSecure software includes an example configuration for filter rules that enable FTP-SFTP conversion for any FTP connections (to port 21) and transparent tunneling of any telnet connections (to port 23). See the ssh-broker-config-example-capture.xml configuration file in the /etc/ssh2 directory. The examples below assume that the example configuration is used.

Start a telnet session to telnet.example.org with transparent tunneling enabled:

$ ssh-capture telnet telnet.example.org

Start an FTP session to ftp.example.org with FTP-SFTP conversion enabled:

$ ssh-capture ftp ftp.example.org

Start an FTP session to ftp.example.org and allow the fallback to plaintext FTP in case the secure SFTP connection cannot be established:

$ ssh-capture -F ftp ftp.example.org

Start an FTP session to local host 127.0.0.1 with FTP-SFTP conversion enabled:

$ ssh-capture -l ftp 127.0.0.1

Start a bash shell session with connection capturing enabled for all commands:

$ ssh-capture bash

	Note
There are the following restrictions on capturing applications that have the 'Set User ID' (suid) bit set: In general, suid applications can be captured only by the owner of the application. As an exception, on AIX, selected suid applications can be captured by all users. These applications are /bin/ftp and /usr/bin/ftp. However, capturing these applications will not work from a captured shell session. To capture /bin/ftp or /usr/bin/ftp on AIX, the application must be started directly using the ssh-capture command: $ ssh-capture ftp <host-address>

Note

There are the following restrictions on capturing applications that have the 'Set User ID' (suid) bit set:

In general, suid applications can be captured only by the owner of the application.
As an exception, on AIX, selected suid applications can be captured by all users. These applications are /bin/ftp and /usr/bin/ftp.
However, capturing these applications will not work from a captured shell session. To capture /bin/ftp or /usr/bin/ftp on AIX, the application must be started directly using the ssh-capture command:
```
$ ssh-capture ftp <host-address>
```

Exit Values

If a command was invoked, ssh-capture returns the exit status of that command. Typically, the exit value shows the success of the command:

If an error occurred when executing the command, the exit value is non-zero. The exact value depends on the operating system.
If an error occurred when parsing the command-line arguments, an error message is output to stderr and the exit value is 1.
If the platform is unsupported, an error message is output to stderr and the exit value is 2.
If no errors occurred, the exit value is whatever the given command returns. So in this case the exit value may be nonzero even if the command succeeds. This means that the exit value alone does not provide exact information about how the command succeeded.