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, enable or disable debug mode on the running ssh-server-g3, servants and/or user SFTP server processes or to pause the server. Furthermore, on Windows it can be used for password cache management.
ssh-server-ctl (ssh-server-ctl.exe on Windows) must be run as a privileged user (root or administrator).
To use the server control utility on Windows command-line, the
Windows PowerShell or
C:\CustomDir\SSH Tectia Server\Tectia> .\ssh-server-ctl.exe status
The following options are available:
Connects to the current server.
Defines the debug level for ssh-server-ctl utility itself.
Displays the help text for the command.
Same as the
Connects to the previous retired server.
Targets the command to the ssh-server-g3 process identified with
PID. Available on Unix only.
Targets the command to the ssh-server-g3 process running on the
PORT. The default port 22 is assumed if this option is
The path to the server control socket.
Displays little or no output depending on the command.
Displays a shorter more machine readable output.
Displays more information if it is available.
Displays the version string.
ssh-server-ctl (ssh-server-ctl.exe on Windows) accepts the following commands:
Start a new servant or new servants.
Defines the number of servants to be started.
Continue a previously paused service.
Debug the running service. Sets or clears debug level in running server or reads debug information from it.
Usage: ssh-server-ctl debug [options] <command> [<debug_level>]
The 'set' and 'clear' commands are directed to the main server and all servants. New servants will get the same debug level the main server has. By using '--servant <id|'active'|'current'>' option before command the debug level will be set only to some servant. The 'active' means all running, not retired, servants. The 'current' is the servant that previously accepted new connection. The 'id' is the servant ID number from ssh-server-ctl status output.
The levels 1-9 are the recommended debug levels. If
level over 4 is needed, it is recommended to set only the
specific module(s) with higher debug level, for example
If debug is enabled, remember to disable it with ssh-server-ctl debug clear command. It should always be used after reproducing the problem. If the service has been restarted since debug mode was enabled on Unix, the ssh-server-ctl --old debug clear is needed to clear the debug settings from any retired server processes.
The 'set' command sets the debug level to running server and all servants connected to it.
The 'set-one' command starts a new servant and sets the debug level only to it. The debug is only enabled for the servant that is going to process the next incoming connection. Note that this will increase the preferred number of servants.
The 'clear' will reset the debug level and also close all
debug hooks. The level only can be cleared by setting it to '0'.
Use with 'ssh-server-ctl' option
--old to clear
debug settings from previous, retired server.
The 'log-file' will open the 'filename' and instruct the server to start writing the debug log into it. Note that ssh-server-ctl will return immediately but the server will continue writing the log until 'clear' command is issued. This command will not affect the current debug level.
The 'syslog' command is used to turn on or off writing debug messages to syslog in Unix systems. The default is off. This command will not affect the current debug level.
Enable only if there are handful of connections and low <debug_level> has been set in order to avoid syslogd slowing down the processes and system further. Available on Unix only.
The 'monitor' will cause ssh-server-ctl to stay running and print out the server logs. This command will not affect current debug level. Not supported on SELinux-enabled systems.
Apart from normal debug level <debug_level> definitions such as '4' or 'sshuser*=9,6', the server supports the following SFTP related debug options, that can be used as debug level for 'set' command with 'sftpfile=<filename>;sftpdebug=<level>' syntax.
Passed to the sft-server-g3, the sft server will write its
debug to the given file. The
%U will be
substituted with a user name and the
a host name in file path.
Normally the sft-server-g3 will get the same debug level as the ssh-server-g3. With this a different debug level can be used in sft and in main server.
By default sft debug messages are sent to the ssh-servant-g3 process. This enables sending standard error to the client.
The following example sets the global debug level to 4 for all Tectia Server processes, SFTP debug level to 8 with user-specific logs.
ssh-server-ctl debug set '4;sftpfile=/tmp/sftp_%U.log;sftpdebug=8'
Show and manipulate server performance profiling data.
Enroll a certificate for user or host authentication.
Check or change FIPS mode switch for installed Tectia products.
Shows the server's hostkey and information.
Pause the service. Existing connections continue to function, but new connections will not be accepted until the continue command has been given.
Prints the server process ID.
Causes the server process to validate and reload its configuration.
The configuration is read
ssh-server-config.xml file. Existing
connections stay open using the old configuration and the new
connections will use the new configuration.
Attempts to start the server process by executing ssh-server-g3.
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. Available on Unix only.
Start the server on an alternate port (the default port is 22).
Uses the given file as a configuration.
Write server debug log to FILE, for example
Set debug LEVEL to server on startup.
|If debug is enabled, remember to disable it with ssh-server-ctl debug clear command. It should always be used after reproducing the problem, even if the service will be stopped on Unix. If the service has been restarted since debug mode was enabled on Unix, the ssh-server-ctl --old debug clear is needed to clear the debug settings from any retired server processes.
When the server is running, this command outputs the following information:
Server status and process ID
Date and time of starting the server
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:
Number of connections, unauthenticated connections, and channels
All-time total number of connections
Causes the server process to start shutting down. The
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.
Forcefully disconnects connections to shut down the server quicker. The
force option should be given with the initial
Instructs the server to stop servants specified by their ID numbers. You can use a
space-separated list to enter several IDs or
all in which case all
running servants will be stopped. If
one is specified, a servant with least number
of connections is selected and then either stopped or retired, depending on other
If number of running servants falls below preferred number, a new servant will be started automatically unless --no-restart option is used.
Retire servants instead of stopping them immediately. The servant stops accepting new connections and will exit after the last client connection disconnects.
Do not start new servant, lowers preferred number of servants if needed.
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
The following commands related to password cache management are supported on Windows only:
(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.
(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.
(Windows only) Exports the current password database into an
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
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
entering a path to an external program or script that outputs the password
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.
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.
(Windows only) Imports a previously exported password database
from an external encrypted
FILE. The external password
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
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.
(Windows only) Displays all stored user names from the currently active server password cache. The passwords are not displayed, only the user names.