SSH

ssh-server-g3

ssh-server-g3 — Secure Shell server - Generation 3

Synopsis

ssh-server-g3 [ -4 ] [ -6 ] [ -D, --debug= LEVEL ] [ -f, --config-file= FILE ] [ -H, --hostkey= FILE ]
[ -l, --listen= [ ADDRESS: ] PORT ] [ -n, --num-processes= NUM ]
[ --auxdata-path= PATH ] [ --fips-mode [ =yes | no ] ]
[ --libexec-path= PATH ] [ --max-num-processes= NUM ] [ --plugin-path= PATH ]
[ -V, --version ] [ -h, --help ]

Description

ssh-server-g3 is the Secure Shell server program for Tectia Server.

The ssh-server-g3 command should not be used directly, except for debugging purposes. Use instead the startup script with the same name, ssh-server-g3.

The path to the ssh-server-g3 startup script varies between operating systems:

  • On Linux with systemd:

    # systemctl [command] ssh-server-g3
  • On Solaris, and Linux without systemd:

    # /etc/init.d/ssh-server-g3 [command]
    
  • On HP-UX:

    # /sbin/init.d/ssh-server-g3 [command]
    

Supported commands:

start

Start the server.

stop

Stop the server. Existing connections stay open until closed from the client side.

restart

Start a new server process. Existing connections stay open using the old server process. The old process is closed after the last old connection is closed from the client side.

reload

Reload the configuration file. Existing connections stay open.

On AIX platforms, use the System Resource Controller (SRC) of the operating system to stop and start the server process manually.

To start Tectia Server on AIX, enter command:

startsrc -s ssh-tectia-server

To stop Tectia Server on AIX, enter command:

stopsrc -s ssh-tectia-server

On AIX, using startsrc starts two ssh-server-g3 processes. One process is so-called service launcher that interfaces with the SRC and the actual SSH server process. By using a separate service launcher, the SRC is able to start a new server process in the case that old server process has been stopped but it is still serving open connections.

On Windows, use the Tectia Server Configuration GUI or the Windows Services console to stop and start the server process.

Options

When the ssh-server-g3 command is used directly, it accepts the following options:

-4

Accepts only IPv4 connections and works in IPv4 mode.

-6

Accepts only IPv6 connections and works in IPv6 mode.

-D, --debug= LEVEL

Sets the debug level string to LEVEL.

--direct

Required on Linux with systemd for enabling the following options: --listen, --port, -p, -l, --old, --pid, --server-address. Note that systemd cannot correctly track the server status when using the --direct option.

-f, --config-file= FILE

Reads the Tectia Server configuration file from FILE instead of the default location.

-H, --hostkey= FILE

Specifies the host key file to be used.

-l, --listen= [ ADDRESS: ]PORT

Specifies the listen address and port. If ADDRESS is unspecified, listen on any IP address. If IPv6 address is used, the address must be inside brackets, for example, [::1].

-n, --num-processes= NUM

Sets the number of Servant processes to NUM. This value defines also the maximum number of Servants that the master server is allowed to have running at a time.

--auxdata-path= PATH

Sets the path to the auxiliary data directory.

--fips-mode [ =yes | no ]

When set to yes, uses the FIPS mode for the cryptographic library. When set to no, uses the standard mode for the cryptographic library. If the option is given without the yes|no argument, yes is assumed. If the option is not given at all on the command line, the mode specified in the ssh-server-config.xml file is used (by default, the standard mode).

--libexec-path= PATH

Sets the path to the libexec directory.

--max-num-processes= NUM

Sets the maximum number of Servant processes to NUM.

--plugin-path= PATH

Sets the path to the plugin directory.

-V, --version

Displays program version and exits.

-h, --help

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

Login Process

When a user logs in successfully, ssh-server-g3 does the following:

  1. Changes process to run with normal user privileges.

  2. Sets up the basic environment.

  3. (On Solaris) Reads /etc/default/login, if it exists.

  4. (On Unix) Reads /etc/environment, if it exists.

  5. (On Unix) Reads $HOME/.ssh2/environment, if it exists.

    Note that setting the environment variables included in this file on the client side must be allowed in the Tectia Server configuration using the environment element.

  6. Changes to the user's home directory.

  7. Checks for RC files and runs it from the user's home directory (by default $HOME/.ssh2/rc) or, if that does not exist, runs /etc/ssh2/sshrc. Any RC file stored in the user's home directory will be run with the user's shell, and any global RC file will be run with /bin/sh.

  8. Runs the user's shell, or the specified command or subsystem.

Environment Variables

Upon connection, Tectia Server will automatically set a number of environment variables that can be used by Secure Shell clients. The clients can also set or change the value of the environment variables if allowed by the server configuration (ssh-server-config.xml). The following variables are set by ssh-server-g3:

DISPLAY (Unix)

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 or equal than 1. Secure Shell clients use this special value to forward X11 connections over the secure channel.

HOME (Unix)

The user's home directory.

LOGNAME (Unix)

Synonym for USER; set for compatibility with systems using this variable.

MAIL (Unix)

The user's mailbox.

PATH (Unix)

Set to the default PATH, depending on the operating system or, on some systems, /etc/environment or /etc/default/login.

SSH_SOCKS_SERVER (Unix)

The address of the SOCKS server used by the client.

SSH2_AUTH_SOCK (Unix)

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 (Unix)

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, SSH_ORIGINAL_COMMAND

This will be the original command given to the Secure Shell client 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 (Unix)

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.

TERM

The terminal type of the Secure Shell client.

TZ (Unix)

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 (Unix)

The name of the user.

Files

ssh-server-g3 uses the following files:

[Note]Note

<INSTALLDIR> indicates the default Tectia installation directory on Windows:

  • "C:\Program Files\SSH Communications Security\SSH Tectia" on 32-bit Windows versions

  • "C:\Program Files (x86)\SSH Communications Security\SSH Tectia" on 64-bit Windows versions

/etc/ssh2/ssh-server-config.xml

This is the ssh-server-g3 configuration file. The format of this file is described in ssh-server-config(5).

On Windows, the configuration file is located in "<INSTALLDIR>\SSH Tectia Server\ssh-server-config.xml".

/etc/ssh2/hostkey[.pub]

These files are the default host key pair used by Tectia Server for authenticating itself to the clients. A 2048-bit RSA key pair is automatically generated during the installation. It consists of the private key (hostkey) and the public key (hostkey.pub).

On Windows, the default host key pair is located in "<INSTALLDIR>\SSH Tectia Server\hostkey[.pub]".

/etc/ssh2/random_seed

This file is used for seeding the random number generator. This file is created the first time the program is run and it is updated automatically. You should never need to read or modify this file.

On Windows, the random seed file is located in "<INSTALLDIR>\SSH Tectia Server\random_seed".

/etc/ssh2/trusted_hosts

This directory is for storing the client host public keys that are trusted for host-based authentication.

The public-key files should be named according to the following pattern:

<hostname>.<keytype>.pub

In the key name, <hostname> is the hostname the client is sending to the server and <keytype> is the type of the public key (ssh-dss, ssh-rsa, ecdsa-sha2-nistp256, ecdsa-sha2-nistp384, or ecdsa-sha2-nistp521). For example, a key called client.example.com.ssh-dss.pub is a DSS key that is trusted for login from the host client.example.com.

On Windows, the trusted host key directory is located in "<INSTALLDIR>\SSH Tectia Server\trusted_hosts".

For more information, see Host-Based User Authentication.

$HOME/.ssh2/authorized_keys (user-specific)

This directory is the default location used for the user public keys that are authorized for login.

On Windows, the default directory for user public keys is %APPDATA%\SSH\UserKeys.

$HOME/.ssh2/authorization (user-specific)

This is the default file that lists the user public keys that are authorized for login.

Using the authorization file is optional. If the file does not exist, Tectia Server looks for authorized keys in the $HOME/.ssh2/authorized_keys directory, by default, or in another authorized-keys directory defined in the Tectia Server configuration.

The authorization file contains a list of public key filenames each preceded by the keyword Key, and each one on its own line. All public keys listed in the authorization file are authorized for login. An example file is shown below:

Key         mykey.pub

This directs Tectia Server to use $HOME/.ssh2/mykey.pub as a valid public key when authorizing login.

The files are by default assumed to be in the $HOME/.ssh2 directory, but also a path to the key file can be given. The path can be absolute or relative to the $HOME/.ssh2 directory. The directory path can also contain a pattern string that is expanded by Tectia Server.

The following pattern strings can be used:

  • %D is the user's home directory

  • %U is the user's login name; expands to domain.user with Windows domain users.

  • %IU is the user's user ID (uid); not supported on Windows

  • %IG is the user's group ID (gid); not supported on Windows

Examples of allowed key paths are shown below:

Key authorized_keys/key1.pub
Key /tmp/key2.pub
Key /usr/%U/key3.pub

Optionally, additional parameters can be specified for the keys by using the Options keyword. See the section called “Authorization File Options” for more information.

On Windows, the default authorization file is located in %APPDATA%\SSH\authorization. Key paths in the file can be absolute or relative to the %APPDATA%\SSH directory.

$HOME/.ssh/authorized_keys (user-specific)

This is the default file used by OpenSSH server that contains the user public keys that are authorized for login. It is supported also by Tectia Server from version 5.1 onwards. The location of the file must be defined in the ssh-server-config.xml file by using the openssh-authorized-keys-file attribute. See auth-publickey .

The file contains public keys, one on each row, and options. The format of each row is as follows:

options  keytype  base64-encoded-key  comment

Tectia Server supports all OpenSSH-style authorized_keys file options, except permitopen="host:port" and tunnel="n".

For more information on the format of this file, see the OpenSSH sshd(8) man page.

Authorization File Options

On the first line of the authorization file, you can optionally specify the regular expression syntax that is used when parsing hostname patterns in the allow-from and deny-from options (see below). The format of the first line is as follows:

## REGEX-SYNTAX egrep

The value for the syntax can be egrep (default), ssh, zsh_fileglob, or traditional. The values are not case-sensitive. zsh_fileglob and traditional are synonymous.

[Note]Note

The Tectia Server implementation of matching and parsing the patterns does not fully behave as egrep, because in the case of egrep and ssh REGEX syntax, Tectia Server encloses the pattern with ^(<existing_pattern>)$, and therefore the parsed string must have the same length as the text to match.

For each key in the authorization file, options can be specified using the Options keyword. This keyword, if used, must follow the Key keyword above. Multiple options must be specified as a comma-separated list on one line. Tectia Server supports the following options:

allow-from and deny-from

In addition to public-key authentication, the canonical name of the remote host must match the given pattern(s). You can use a host name or an IP address to specify the remote host. Enter the host name or IP address with or without quotation marks.

[Note]Note

Because of Tectia Server's implementation for handling egrep REGEX syntax, when providing host names and IP addresses as pattern(s), use the escape character for periods, for instance host.example.com should be given as pattern host\.example\.com.

Specify one pattern per keyword; multiple keywords can be used. See the example below.

If you specify host names in the allow-from or deny-from options, ensure that you set the following attribute values in the server configuration file ssh-server-config.xml:

  • require-dns-match="yes" under the auth-publickey element

  • resolve-client-hostname="yes" under the settings element

These settings will prevent authentications from failing in case of problems with DNS lookups and reverse mapping.

[Note]Note

The authorization file is read first to find the keys allowed for authentication. The deny-from option will not work if the key is stored in the authorized_files directory or other location later in the reading order defined by the auth-publickey element (see auth-publickey ) in ssh-server-config.xml.

command="command"

This is used to specify a "forced command" that will be executed on the server side instead of anything else when the user is authenticated. The command supplied by the user (if any) is put in the environment variable SSH2_ORIGINAL_COMMAND. The command is run on a pty if the connection requests a pty; otherwise it is run without a tty. Quotes may be used in the command if escaped with backslashes.

This option is useful for restricting certain public keys to perform just a specific operation. An example might be a key that permits remote backups but nothing else. Notice that the client may specify TCP/IP and/or X11 forwarding, unless they are explicitly denied (see no-port-forwarding and no-x11-forwarding below).

If terminal is explicitly allowed in the ssh-server-config.xml file, the forced command is run only when the user tries to run remote commands. If the user requests a shell, he can get it normally and the forced command is not run.

If a forced command is defined in the ssh-server-config.xml file, it overrides any commands in the authorization files. The configuration file might also allow only specific commands, or deny all remote commands. These restrictions apply also to commands in the authorization file.

For more information on command restrictions in the configuration file, see command .

environment="NAME=value"

This option specifies that the string is to be added to the environment when logging in using this key. Environment variables set this way override other default environment values. Multiple options of this type are permitted.

idle-timeout="time"

This option sets idle timeout limit to time either in seconds (s or nothing after the number), in minutes (m), in hours (h), in days (d), or in weeks (w). If the connection has been idle (all channels) this long, the connection is closed.

no-port-forwarding

This option forbids TCP/IP forwarding when this key is used for authentication. Any port forward (tunneling) requests by the client will return an error. This is useful in combination with the command option.

no-x11-forwarding

This option forbids X11 forwarding when this key is used for authentication. Any X11 forward requests by the client will return an error.

no-agent-forwarding

This option forbids authentication agent forwarding when this key is used for authentication.

no-pty

This option prevents tty allocation (a request to allocate a pty will fail).

An example of an authorization file is shown below:

## REGEX-SYNTAX egrep

# First key: login allowed only from the specified IP address
Key     key1.pub
Options allow-from="10\.1\.100\.1", command="echo FOOBAR", no-x11-forwarding

# Second key: login allowed and denied only from the specified IP addresses 
Key     key2.pub
Options allow-from="10\.1\.100\.2", deny-from="10\.1\.100\.1"

# Third key: forced command for doing a backup of the disk drive
Key     key3.pub
Options command="dd if=/dev/hda", no-port-forwarding, no-x11-forwarding