Skip to main content

Use Cases

This section describes the common use cases which Key Manager controller can be applied to.

Manage Key Manager Licenses​

You can use the Key Manager controller to import, delete, and check licenses.

note

Key Manager licenses can also be managed via the Key Manager GUI, on the Settings→Licenses page.

To verify whether your Key Manager system has a valid license:

# /opt/sshmgr/bin/ssh-mgr-controller --check-license

The previous command displays an error if no valid licenses are imported to the Key Manager system. If the Key Manager system already has a valid license, the command returns no output.

To import a license, use a command like the following (replace /path/to/license.dat with the actual path of the license file):

# /opt/sshmgr/bin/ssh-mgr-controller --import-license=/path/to/license.dat

Note that the license file must be readable for the Key Manager user sshmgr.

To list the licenses currently imported to the Key Manager system, including their primary key and license- file contents:

# /opt/sshmgr/bin/ssh-mgr-controller --list-licenses

To delete a license with a given primary key from the Key Manager (replace 1234 with the primary key of the license you want to delete):

# /opt/sshmgr/bin/ssh-mgr-controller --delete-license=1234

Managing Key Manager Administrator Accounts​

You can use the Key Manager controller to create and modify Key Manager administrator accounts. Particularly, the Key Manager controller offers some features that may be used for troubleshooting certain scenarios where users have locked themselves out of the system.

note

General Key Manager account management can be performed via the Key Manager GUI. For more information about managing Key Manager accounts, see Key Manager Account and Permission Management.

When managing Key Manager accounts, use the --admin-account option to provide the user name of the account you are managing. If the provided user name matches to an existing Key Manager account, then the command modifies that account. Otherwise, the command creates a new Key Manager account with the given user name.

# /opt/sshmgr/bin/ssh-mgr-controller --admin-account=username <options>

Provide additional admin-account options for setting the values of the account. For example, to create (or modify) a regular Key Manager account with a password and some roles:

# /opt/sshmgr/bin/ssh-mgr-controller --admin-account=alice \
--admin-account-password=example_password \
--admin-account-roles=keyoperators,apiusers

Key Manager accounts can be deleted as follows:

# /opt/sshmgr/bin/ssh-mgr-controller --admin-account=bob --delete-admin-account

Deleted Key Manager accounts can be recovered as follows:

# /opt/sshmgr/bin/ssh-mgr-controller --admin-account=bob --restore-admin-account

You can set superuser permissions to a Key Manager account using --admin-account-superuser:

# /opt/sshmgr/bin/ssh-mgr-controller --admin-account=alice \
--admin-account-superuser=yes

In situations where you forgot the superuser account password, you can reset it with a command like the following:

# /opt/sshmgr/bin/ssh-mgr-controller --admin-account=superuser \
--admin-account-password=example_password --admin-account-superuser=yes
note

When running Key Manager controller commands on superuser accounts, you must add the --admin-account-superuser=yes option to retain the superuser privileges of that account. If you do not specify the option, the superuser privileges for the account are removed.

Managing Key-Activity Data for a Host​

You can use the Key Manager controller to reset key-activity data for a selected host. Resetting key-activity data can be useful in situations where the key-activity information of a certain host is incorrect, and you want to re-import the key-activity information. You can also set the first key-activity date for a selected host if it is not automatically detected by Key Manager.

caution

Resetting key-activity data irrevocably removes all key-activity information about the target host from the Key Manager system. Before resetting the key-activity data of a host, make sure that the syslog files of the host contain all the key-activity information that you want to re-import.

To manage key-activity data for a host, you must provide the ID of the target host. You can use the Key Manager command-line client to determine the ID of a host by its hostname:

# ssh-mgr-client list-hosts -F \
hostname="server.example.com" -C hostname,id -H

Resetting the key-activity information of a host can be useful when you want to cleanly re-import key- activity information from the existing syslog and syslog-backup files of the host. Doing so might resolve key-activity and time-zone issues on hosts that were initially deployed into Key Manager 1.2 or earlier versions. To reset key-activity information for a selected host (replace 999 with the ID of the target host):

# /opt/sshmgr/bin/ssh-mgr-controller --reset-key-activity-data --host-id=999

The previous command deletes all key-activity information associated to the selected host. On subsequent key-activity scans, key-activity information for the selected host is re-imported from the available syslog and syslog-backup files.

The first key-activity date may be missing for hosts that were initially deployed into Key Manager 1.2 or earlier versions. In such situations, you can enter this date manually:

# /opt/sshmgr/bin/ssh-mgr-controller \
--set-first-key-activity-date=2014-12-31T23:59:59+0200 \
--host-id=999

Managing Alerts​

You can use the Key Manager controller to change the status of active alerts.

note

Key Manager alerts can also be managed via the Key Manager GUI. For more information about managing Key Manager alerts, see Using Alerts to Review Changes in the Key Environment.

To dismiss all the active alerts associated to a certain host (replace 999 with the ID of the host):

# /opt/sshmgr/bin/ssh-mgr-controller --set-alert-status=dismissed --host-id=999

Similarly, to mark all the active alerts of a host as resolved:

# /opt/sshmgr/bin/ssh-mgr-controller --set-alert-status=resolved --host-id=999

Resetting Pending Key Operations​

A pending operation on a user key indicates that the key is undergoing a management action that blocks other jobs from modifying the key. Typically, the pending-operation status is automatically reset after the blocking job completes. However in some situations, such as when a job terminates abnormally, the pending-operation status may not be reset for the key, which prevents subsequent modifications to the key.

You can use the Key Manager controller to reset the pending operation of a user key. To reset the pending operation of an authorized key (replace 999 with the ID of the key):

# /opt/sshmgr/bin/ssh-mgr-controller --reset-pending-auth-key-operation=999

Similarly, to reset the pending operation of a private key:

# /opt/sshmgr/bin/ssh-mgr-controller --reset-pending-private-key-operation=999

After the pending operation is reset, you should once again be able to perform actions on the affected keys.

Setting Key Manager Server Roles​

A Key Manager Server can act as a front end, a back end, or as both. You can use the command-line client to set the possible roles of a Key Manager Server.

note

Key Manager controller commands for reviewing and setting server roles only apply to the Key Manager Server on which the command is run. Ensure that you are performing all server-role- related commands on the correct Key Manager Server.

To review the roles of the current Key Manager Server:

# /opt/sshmgr/bin/ssh-mgr-controller --show-server-roles

You can also query the status of a specific role:

# /opt/sshmgr/bin/ssh-mgr-controller --check-server-role=backend
# /opt/sshmgr/bin/ssh-mgr-controller --check-server-role=frontend

Note that commands involving --check-server-role use exit codes to indicate the status of the specified role. 0 is returned if the role is enabled, and a non-zero value is returned if the role is disabled.

To check the exit status of the previously-run command:

# echo $?

The following commands can be used for enabling/disabling the back-end role:

# /opt/sshmgr/bin/ssh-mgr-controller --enable-server-role=backend
# /opt/sshmgr/bin/ssh-mgr-controller --disable-server-role=backend

Similarly, to enable/disable the front-end role:

# /opt/sshmgr/bin/ssh-mgr-controller --enable-server-role=frontend
# /opt/sshmgr/bin/ssh-mgr-controller --disable-server-role=frontend

Changing Key Manager Server roles only affects what services may be henceforth started on the Key Manager Server. Note that the operation does not affect currently-running services. After enabling or disabling a server role, you need to manually start or stop the corresponding Key Manager service. The backend: service is started or stopped using the following commands:

# supervisorctl start backend:
# supervisorctl stop backend:
note

The colon notes that the command is given to a supervisor group. backend: controls the backend and the host-executor, and frontend: controls the front-end and the api-executor. All of these can also be controlled separately.

Similarly, to start or stop the frontend: service:

# supervisorctl start frontend:
# supervisorctl stop frontend:
note

In situations where you attempt to start a disabled Key Manager service, the supervisorctl will falsely claim that the service was started. After starting services using supervisorctl, you may run the following command to verify that the desired services are actually running:

# supervisorctl status

Remove Key Manager Servers from the System​

You can remove an existing Key Manager Server from the Key Manager system. This is done as follows:

  1. On the target Key Manager Server, stop all the Key Manager services:

    # supervisorctl stop all

  2. After the Key Manager services on the target server have been stopped, you can remove it from the Key Manager system by running the following command from any Key Manager Server (replace unique-id with the unique ID of the target Key Manager Server):

    # /opt/sshmgr/bin/ssh-mgr-controller --delete-server=unique-id
    note

    Deleting a server fails if it still has leftover processes. In such cases, wait for the leftover processes to be cleaned up before attempting to delete the server again.

    Cleanup should be completed within the time specified by the host setting Maximum duration of a single job state. Also, to prevent the target server from picking up new jobs, set its Maximum processes to 0.

After a Key Manager Server that has been removed, Key Manager services cannot be run on the target server. If you have removed a Key Manager Server in error, you can restore it as follows:

  1. Restore the target Key Manager Server to the Key Manager system by running the following command from any Key Manager Server:

    # /opt/sshmgr/bin/ssh-mgr-controller --restore-server unique-id \
    fqdn keymanageruser sshport

    In the example command, replace the values as follows:

    • unique-id: The unique ID of the target server.

    • fqdn: The FQDN of the target server.

    • keymanageruser: The name of the user that runs the Key Manager services on the target server. The user name of this user is typically sshmgr.

    • sshport: The number of the port on which the Tectia SSH Server is running on the target Key Manager Server. This port is typically 22.

    A working example of the command:

    # /opt/sshmgr/bin/ssh-mgr-controller --restore-server hW7GZTItWapgQjRPtfVg \
    server.example.com sshmgr 22

  2. All the Key Manager Server roles and services on a restored server are initially disabled. You will need to manually enable the role(s) that the restored Key Manager Server is to perform. You will also need to start the corresponding Key Manager service(s).

    Back-end and front-end roles can be enabled with the following commands respectively:

    # /opt/sshmgr/bin/ssh-mgr-controller --enable-server-role=backend
    # /opt/sshmgr/bin/ssh-mgr-controller --enable-server-role=frontend

    Backend: and frontend: services can be started with the following commands respectively:

    # supervisorctl start backend:
    # supervisorctl start frontend:

For more information about Key Manager Server roles, see Setting Key Manager Server Roles.

note

The unique ID is not the same thing as a numeric ID. The unique ID is a relatively long string consisting of alphanumeric characters, such as hW7GZTItWapgQjRPtfVg, whereas the numeric ID is an integer, such as 12.

Restored Key Manager Servers do not retain any tags, back-end tags, or server-specific settings from the time before the server was removed.