sshg3 — Secure Shell terminal client - Generation 3
sshg3 (sshg3.exe on Windows) is a
program for logging in to a remote machine and executing commands on a
remote machine. sshg3 provides secure, encrypted
communication channels between two hosts over an unsecured network. It
can be used to replace the unsecured rlogin
,
rsh
, and telnet
programs. Also X11 connections
and arbitrary TCP/IP ports can be forwarded over secure channels with
sshg3.
To connect to a remote host using sshg3, give either the
name of a connection profile defined in the
ssh-broker-config.xml
file (profile
)
or the IP address or DNS name of the remote host, optionally with the remote
username and the port of the Secure Shell server
([user@]host[#port]
). If no username is given,
the local username is assumed. If no port is given, the default Secure Shell
port 22 is assumed. The remote host must be running a Secure Shell version 2
server.
sshg3 launches ssh-broker-g3 as a
transport. ssh-broker-g3 will ask for passwords or
passphrases if they are needed for authentication. sshg3
uses the configuration specified in the ssh-broker-config.xml
file.
When the user's identity has been accepted by the server, the server either executes the given command, or logs in to the machine and gives the user a normal shell. All communication with the remote command or shell will be automatically encrypted.
If no pseudo-tty has been allocated, the session is transparent and can be used to securely transfer binary data.
The session terminates when the command or shell on the remote machine exits and all X11 and TCP/IP connections have been closed. The exit status of the remote program is returned as the exit status of sshg3.
ssh-broker-g3 acts as an authentication agent, and the
connection to the agent is automatically forwarded to the remote side unless
disabled in the ssh-broker-config.xml
file or on the
sshg3 command line (with the -a
option).
If the user is using X11 (the DISPLAY
environment
variable is set), the connection to the X11 display can be automatically
forwarded to the remote side in such a way that any X11 programs started
from the shell (or command) will go through the encrypted channel, and the
connection to the real X server will be made from the local machine. The
user should not manually set DISPLAY
. X11 connection
forwarding can be allowed in the ssh-broker-config.xml
file or
on the sshg3 command line (with the +x
option). By default, X11 forwarding is disabled.
The DISPLAY
value set by sshg3 will
point to the server machine, but with a display number greater than zero.
This is normal, and happens because sshg3 creates a "proxy" X
server on the server machine for forwarding the connections over the
encrypted channel.
sshg3 will also automatically set up the Xauthority data on the server machine. For this purpose, it will generate a random authentication cookie, store it in the Xauthority data on the server, and verify that any forwarded connections carry this cookie and replace it with the real cookie when the connection is opened. The real authentication cookie is never sent to the server machine (and no cookies are sent in the plain).
Command-line options override the settings in the
ssh-broker-config.xml
file if the same option has been
configured in both places. The following options are available:
-a, --no-agent-forwarding
Disables authentication agent forwarding.
+a
Enables authentication agent forwarding. This is the default value.
-B, --batch-mode
Uses batch mode. Fails authentication if it requires user interaction on the terminal.
Using batch mode requires that you have previously saved the server host key on the client and set up a non-interactive method for user authentication (for example, host-based authentication or public-key authentication without a passphrase).
-D, --debug=
LEVEL
Sets the debug level. LEVEL
is a number
from 0 to 99, where 99 specifies that all debug information should be
displayed. This should be the first argument on the command line.
Note | |
---|---|
Option |
Note | |
---|---|
The debug level can be set only when the sshg3 command starts the Connection Broker. This option has no effect in the command if the Connection Broker is already running. |
-e, --escape-char=
CHAR
Sets escape character (none: disabled, default: ~
).
-f
Forks into background mode (Unix).
-g, --gateway
Gateways ports, which means that also other hosts may connect to
locally forwarded ports. This option has to be specified before the
"-L
" option. Note the logic of +
and
-
in this option.
+g
Does not gateway ports. Listens to tunneling connections originating
only from the localhost. This is the default value. Note the logic of
+
and -
in this option.
-l, --user=
USERNAME
Logs in using this username.
-L
[protocol/
] [listen-address:
] listen-port:dst-host:dst-port
Forwards a port on the local (client) host to a remote destination host and port.
This allocates a listener port (listen-port
)
on the local client. Whenever a connection is made to this listener, the
connection is tunneled over Secure Shell to the remote server and another
connection is made from the server to a specified destination host and port
(dst-host:dst-port
). The connection from the
server onwards will not be secure, it is a normal TCP connection.
Giving the argument protocol
enables
protocol-specific forwarding. The protocols implemented are
tcp
(default, no special processing), ftp
(temporary forwarding is created for FTP data channels, effectively securing
the whole FTP session), and socks
.
With the socks
protocol, the syntax of the argument is
"-L
socks/[listen-address:]listen-port
".
When this is set, SSH Tectia Client will act as a SOCKS server for other applications,
creating forwards as requested by the SOCKS transaction. This supports both
SOCKS4 and SOCKS5.
If listen-address
is given, only that
interface on the client is listened. If it is omitted, all interfaces are
listened.
-n
Redirects input from /dev/null
(Unix).
-o
option
Processes an option as if it was read from a SSH Tectia Client 4.x-style
configuration file. The supported options are ForwardX11
and
ForwardAgent
(for example, -o "ForwardX11=yes"
).
-p, --port=
PORT
Connects to this port on the remote host. A Secure Shell server must be listening on the same port.
-R
[protocol/
] [listen-address:
] listen-port:dst-host:dst-port
Forwards a port on the remote (server) host to a destination host and port on the local side.
This allocates a listener port (listen-port
)
on the remote server. Whenever a connection is made to this listener, the
connection is tunneled over Secure Shell to the local client and another
connection is made from the client to a specified destination host and port
(dst-host:dst-port
). The connection from the
client onwards will not be secure, it is a normal TCP connection.
Giving the argument protocol
enables
protocol-specific forwarding. The protocols implemented are
tcp
(default, no special processing) and ftp
(temporary forwarding is created for FTP data channels, effectively securing
the whole FTP session).
If listen-address
is given, only that
interface on the server is listened. If it is omitted, all interfaces are
listened.
-s, --subsystem
Sets the executed command to be a subsystem rather than a shell executable.
-S, --no-session-channel
Does not request a session channel. This can be used with port-forwarding requests if a session channel (and tty) is not needed, or the server does not give one.
+S
Requests a session channel. This is the default value.
-t, --tty
Allocates a tty even if a command is given.
-v, --verbose
Uses verbose mode (equal to -D 2
).
-w
Does not try an empty password.
+w, --try-empty-password
Tries an empty password.
+x, +X
Enables X11 connection forwarding.
-x, -X, --no-x11-forwarding
Disables X11 connection forwarding. This is the default value.
-z, --broker-log-file=
FILE
Sets the Connection Broker log file to FILE
. This
option works only if ssh-broker-g3 gets started by this
process).
--abort-on-failing-tunnel
Aborts if creating a tunnel listener fails (for example, if the port is already reserved).
--remote-environment
name=value
When this option is used, the defined environment variables are passed to the server from the client side. The environment variables are applied on the server when requesting a command, shell or subsystem.
Note that the server can restrict the setting of environment variables.
You can also configure the environment variables to be passed to the
server in the ssh-broker-config.xml
configuration file with the
<remote-environment>
element in the
default-settings
and per profile.
See remote-environment.
If the same variable is entered on the command-line client and configured in
the ssh-broker-config.xml
, the command-line version will be used.
--remote-environment-format
name=value
The defined environment variables are passed to the server from the client side. The Connection Broker processes the value before sending it to the server.
You can use %U
in the value
to indicate a
user name. The Connection Broker replaces the %U
with the actual user name
before sending it to the server.
For more information, see --remote-environment
name=value
.
--password=
PASSWORD
| file://
PASSWORDFILE
| extprog://
PROGRAM
Sets user password that the client will send as a response to password
authentication. The PASSWORD
can be given
directly as an argument to this option (not recommended), or a path to file
containing the password can be given, or a path to a program or a script
that outputs the password can be given.
Caution | |
---|---|
Supplying the password on the command line is not a secure option. For example, in a multi-user environment, the password given directly on the command line is trivial to recover from the process table. You should set up a more secure way to authenticate. For non-interactive batch jobs, it is more secure to use public-key authentication without a passphrase, or host-based authentication. At a minimum, use a file or a program to supply the password. |
-V, --version
Displays program version and exits.
-h, --help
Displays a short summary of command-line options and exits.
The command can be either of the following:
remote_command
[arguments] ...
Runs the command on a remote host.
-s
service
Enables a service in remote server.
sshg3 supports escape sequences to manage a running
session. For an escape sequence to take effect, it must be typed directly
after a newline character (press Enter
first). The escape
sequences are not displayed on screen during typing.
The following escape sequences are supported:
Terminates the connection.
Ctrl
-ZSuspends the session.
Sends the escape character literally.
Lists forwarded connections.
Disables the escape character irrevocably.
Displays a summary of escape sequences.
Initiates rekeying manually.
Gives connection statistics, including server and client version, packets in, packets out, compression, key exchange algorithms, public-key algorithms, and symmetric ciphers.
Gives statistics for individual channels (data window sizes etc). This is for debugging purposes.
Dumps the client version number to stderr (useful for troubleshooting).
Upon connection, the Secure Shell server will automatically set a number of environment variables that can be used by sshg3. The exact variables set depend on the Secure Shell server. The following variables can be used by sshg3:
DISPLAY
The DISPLAY
variable indicates the location of the
X11 server. It is automatically set by the server to point to a value of
the form hostname:n
where hostname
indicates the host on which the server and the shell are running, and
n
is an integer greater than or equal to 1.
sshg3 uses this special value to forward X11 connections over
the secure channel.
The user should normally not set DISPLAY
explicitly, as that will render the X11 connection unsecured (and will
require the user to manually copy any required authorization
cookies).
HOME
The user's home directory.
LOGNAME
Synonym for USER
; set for compatibility with
systems using this variable.
MAIL
The user's mailbox.
PATH
Set to the default PATH, depending on the operating system or, on some
systems, /etc/environment
or /etc/default/login
.
SSH_SOCKS_SERVER
The address of the SOCKS server used by sshg3.
SSH2_AUTH_SOCK
If this exists, it is used to indicate the path of a Unix-domain socket used to communicate with the authentication agent (or its local representative).
SSH2_CLIENT
Identifies the client end of the connection. The variable contains three space-separated values: client IP address, client port number, and server port number.
SSH2_ORIGINAL_COMMAND
This will be the original command given to sshg3 if a forced command is run. It can be used, for example, to fetch arguments from the other end. This does not have to be a real command, it can be the name of a file, device, parameters or anything else.
SSH2_TTY
This is set to the name of the tty (path to the device) associated with the current shell or command. If the current session has no tty, this variable is not set.
TZ
The time-zone variable is set to indicate the present time zone if it was set when the server was started (the server passes the value to new connections).
USER
The name of the user.
For a list of varibles set by SSH Tectia Server, see the ssh-server-g3(8) man page.
On successful execution, sshg3 returns
normally 0
(zero) as the exit value. If sshg3
encounters an error, you usually see the reason in an error message. In this
case, the exit value is 1
.
When executing remote commands, sshg3 exits with
the status of the command run. On successful runs this is normally
0
(zero). The error code 127
is usually returned
by the shell if the requested remote command is not found.
Connect as the local username to host
remotehost
, port 2222, and open shell:
$ sshg3 remotehost#2222
Connect to the host specified by the connection profile
profile1
in the ssh-broker-config.xml
file, and run the who
command (and exit after running the
command):
$ sshg3 profile1 who
Connect as user
to host
remotehost
, and open a local port forwarding from
port 143 on the client to port 143 on imapserver
.
Do not open shell. Also other hosts may connect to the local port. The
connection from remotehost
to
imapserver
will not be secured:
$ sshg3 -L 143:imapserver:143 -g -S user@remotehost