ssh-server-ctl — Tectia Server control utility.
ssh-server-ctl (ssh-server-ctl.exe on Windows) is a control utility that can be used to start, stop, or reload the configuration of Tectia Server (ssh-server-g3). It can also be used to add new servants or to stop servants, to check the status of the server and to pause the server. Furthermore, on Windows it can be used for password cache management.
Note | |
---|---|
ssh-server-ctl (ssh-server-ctl.exe on Windows) must be run as a privileged user (root or administrator). |
The following options are available:
-C, --current
Connects to the current server.
-D, --debug=
LEVEL
Defines the debug level.
-h, --help
Displays the help text for the command.
-l, --listen=
PORT
Same as the port
option.
-O, --old
Connects to the backup listener.
-P, --pid
PID
Targets the command to the ssh-server-g3 process identified with
the given PID
. Available on Unix only.
-p, --port
PORT
Targets the command to the ssh-server-g3 process running on the
given PORT
. The default port 22 is assumed if this option is
not used.
--server-address
The path to the server control socket.
-q, --quiet
Displays little or no output depending on the command.
-s, --short
Displays a shorter more machine readable output.
-v, --verbose
Displays more information if it is available.
-V, --version
Displays the version string.
ssh-server-ctl (ssh-server-ctl.exe on Windows) accepts the following commands:
add-servant
Start a new servant or new servants.
Options:
num
Defines the number of servants to be started.
continue
Continue a previously paused service.
enroll-certificate
Enroll a certificate for user or host authentication.
pause
Pause the service. Existing connections continue to function, but new connections will not be accepted until the continue command has been given.
pid
Prints the server process ID.
reload
Causes the server process to reload its configuration. The configuration is read
from the ssh-server-config.xml
file. Existing connections stay open
using the old configuration and the new connections will use the new
configuration.
start
Attempts to start the server process by executing ssh-server-g3.
The start
command will check if there is a server process currently
running; if yes, the tool will report the case and will not make any starting
attempts.
Options:
-p, --port
PORT
Start the server on an alternate port (the default port is 22).
-f, --config-file
FILE
Uses the given file as a configuration.
status
When the server is running, this command outputs the following information:
Server status and process ID
Date and time of starting the server
Cryptographic mode
Address family type
Path to the server control socket
Number of successful reconfigurations
Date and time of the last reconfiguration (if applicable)
Number of connections received
Number of servants
Preferred number of servants
Maximum number of servants
Maximum number of connections per servant
Total number of connections after which servants are retired
Status of load control (enabled/disabled)
Maximum size for the server's white list
Discard limit for the server's white list
Additionally, for each servant:
Process ID
Status
Number of connections, unauthenticated connections, and channels
All-time total number of connections
stop
Causes the server process to start shutting down. The stop
command
checks if there is a server process currently running; if not, the tool will report the
case and will not make any stopping attempts.
On AIX, if an error occurs when the server is stopped by using ssh-server-ctl stop, it falls back to stop the server process directly.
Options:
-F, --force
Forcefully disconnects connections to shut down the server quicker. The
force
option should be given with the initial
stop command.
stop-servant
id ...
Causes the server to stop servants specified by their ID numbers. You can use a space-separated list to enter several IDs.
view-white-list
Prints the IP addresses on the server's white list in reverse chronological order.
The white list is a list of IP addresses of connections that have recently had a
successful authentication. (For more information, see
load-control
in ssh-server-config(5).)
The following commands related to password cache management are supported on Windows only:
add-pwd-cache-user
username
(Windows only) Adds the specified user and entered password to the server password cache database. If the user already exists, the existing password gets replaced with the new one. The password is read from the console or standard input.
del-pwd-cache-user
username
(Windows only) Removes the specified user's password from the currently active server password cache. The command will report an error if the specified user is not present in the password cache.
export-pwd-cache
[
--password
]
FILE
(Windows only) Exports the current password database into an
external encrypted FILE
. If FILE
already exists, the export will fail (no files will be overwritten).
FILE
must reside on a local drive.
The password that will be used to protect the password database
FILE
will be requested interactively, unless it is provided
as a command-line argument (with the --password
option).
Options:
--password=
PASSWORD
|
file://
PASSWORDFILE
|
env://
VARIABLE
|
extprog://
PROGRAM
Sets the user password. It is possible to give the
PASSWORD
directly as an argument to this option or
through an environment VARIABLE
, but these options are
not recommended. Better alternatives are entering a path to a file on a local
drive that contains the password
(--password=file://
PASSWORDFILE
), or
entering a path to an external program or script that outputs the password
(--password=extprog://
PROGRAM
).
Caution | |
---|---|
Supplying the password on the command line or setting it as an environment variable are not secure options. For example, in a multiuser environment, the password given directly on the command line is trivial to recover from the process table. |
Note | |
---|---|
If you use a |
Tectia enforces the use of strong passwords for the password cache export and import functions. Instead of explicit password requirements, we use a "password class" system. For example, a password that consists of eight unique characters from three different character classes or a password of eleven unique characters from two character classes are deemed strong enough. The character classes are: digits, lower-case letters, upper-case letters, and other characters. When calculating the number of different character classes, upper-case letters used as the first character and digits used as the last character of a password are ignored.
import-pwd-cache
[
--password
]
FILE
(Windows only) Imports a previously exported password database
from an external encrypted FILE
. The external password
database FILE
must reside on a local drive. All entries from
FILE
will be added or overwritten into the current password
cache database that is in use by the server. The password that is protecting the
FILE
will be requested interactively, unless it is provided
as a command-line argument (with the --password
option).
Caution | |
---|---|
The passwords of user names that already exist in the current password cache
will be overwritten by those in the imported password database
|
Options are the same as for export-pwd-cache.
show-pwd-cache-users
(Windows only) Displays all stored user names from the currently active server password cache. The passwords are not displayed, only the user names.