Host-Deployment Prerequisites

Key Manager must be allowed to perform management actions using an existing user account on the host. This account is called the management account.

The following types of management accounts are supported:

Accounts with root privileges, such as root.
Unprivileged accounts able to run management commands via sudo. Commands run by Key Manager via sudo are logged as per standard sudo logging facilities, which offers auditability. sudo requirements are described in sudo Setup for Unprivileged Management Accounts.

note
sudo is not to be treated as a mechanism for restricting what commands can be run on a host, but rather as a means for auditing and logging Key Manager actions.
On RHEL-10 hosts, you should set up a non-root user with sudo as the management account. If you want to deploy a RHEL-10 host using root user, they must in any case have a sudoers file in place for the deployment.
Unprivileged accounts able to obtain privileged shell using 3rd-party privilege-elevation software. Privilege-elevation setup is described in Settings for Hosts Using Privilege-Elevation Software.

For agentless hosts: You can specify the management account when deploying the host.

For agentless Windows hosts: Permissions required from Windows user:

Must have read and execure permissions in winrm users group
Must have a home directory with read, write, and execute permissions
Recommended to be a member of Administrators group for full scanning capabilities

For agent-based hosts: On Unix hosts, the management account is root by default, but you can specify another sufficiently privileged account in the agent-initialization script. On Windows hosts, the agent service runs under an Administrator account.

Enabling Key-Activity Monitoring

Key-activity monitoring is a functionality for tracking usage information about the authorizations in the managed environment.

Key Manager detects key activity from syslog files. To enable key-activity monitoring on a target host, ensure that SSH logins are logged where Key Manager can find them:

If the host runs OpenSSH 6.2 or earlier, or any SSH server based on such OpenSSH versions, the SSH server loglevel must be configured to write login events to syslog. Ensure that the SSH server LogLevel is set to VERBOSE.

By default, you need to change the LogLevel to VERBOSE (from INFO). To do this, find the following line in the SSH server-configuration file:

#Loglevel INFO

And change it to:

LogLevel VERBOSE

Apply your changes by restarting the SSH server.
By default Key Manager detects key activity from standard syslog locations. If SSH servers on the host log to non-standard locations, you must configure these locations to Key manager using the following host settings:
- Authorized keys receiving activity (syslog_update)
- OS based syslog paths (syslog_setting_os_overwrite)
- Syslog content filter patterns for KA (syslog_patterns)
- Syslog file directories on host (syslog_directories)
- Syslog file name patterns (syslog_files)
- Syslog pre-filtering pattern (syslog_prefilter)
For more information about host settings, see Host Settings.

If you need help configuring key-activity scans in your environment, please contact SSH Communications Security support at https://support.ssh.com/
note
Key Manager can read logs from following compressed file formats:
- .bz
- .gz
- .xz
- .Z
Ensure that the syslog service is running on the host.

note
We recommend disabling agent forwarding on your hosts to ensure that the connections originate from the addresses reported in key-activity logs. As Key Manager is unable to determine between logins using actual private keys, and logins using agent-forwarded private keys.
For example consider the following scenario: A user has access from server01 to server02, and a user-key authorization from server01 to server03. Furthermore, server03 belongs to the managed environment. When agent forwarding is enabled, the user can first use SSH to connect to server02, and subsequently access server03 via server02. In this case, key-activity logs reports that the user was authorized from server02 to server03, which can be erroneously interpreted as the user having a private key on server02.
note
These are the default locations from which the Key Manager attempts to read syslog-files from:
- AIX: /var/adm/
- FreeBSD: /var/log/
- HP-UX: /var/adm/syslog/
- Linux: /var/log/
- SunOS: /var/adm/
- Windows: %SYSTEMROOT%\System32\Config\
- z/OS: /var/log

Enabling Reading OpenSSH Key Activity from Windows Hosts

To enable Key Manager to be able to read OpenSSH key activity from Windows hosts you need to do the following:

Modify the Key Manager global setting OS based syslog paths at Settings→General→Global. The Windows portion of the setting needs additions that are bolded in the following example:

 - "Windows.",{"syslog_directories":["{{Win32_NTLogEvent}}"],"syslog_files":\
["{{Application}}","{{OpenSSH/Operational}}"],"syslog_prefilter":\
"OpenSSH|SSH Tectia Server|BvSshServer"},"OS/390.",null]

On all Windows target hosts, a new key needs to be added to registry. Add a key OpenSSH/Operational to HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\EventLog. You do not need to add values to the new key.

Enabling User-Key Scans for Users with Restricted Shells

sudo must be installed on hosts where users have restricted shells (such as rsh, nologin, and custom shells). Otherwise, such users are not scanned for user keys.

Key Manager raises alerts when scans skip users.

`sudo` Setup for Privileged Management Accounts

The configurations in this section need to be performed on hosts that satisfy all of the following criteria:

sudo version 1.7.0 or later is installed on the host.
The management account is root.

For hosts that satisfy the previously-listed conditions, you need to perform either of the following configurations:

Ensure that the management account has permissions to use sudo to run all the possible commands as any target user: Key Manager must be able to read and write user-specific SSH keys and settings as their respective owners. Note that even privileged users do not have sudo permissions unless they are explicitly defined in the sudoers file.

For example, when using root as the management account, the sudoers file must have a line like the following:
```
root    ALL=(ALL)   ALL
```
After you have deployed the host, enable the setting Prefer su over sudo for the host. Key Manager will use su instead of sudo to run management actions involving user switching. Note that Key Manager performance with su is typically slower than with sudo.

For more information about configuring host settings, see Configuring Host and Host-Credential Settings. For more information about the Prefer su over sudo host setting, see Host Settings. For instructions about additional configurations required for hosts using privilege-elevation software, see Settings for Hosts Using Privilege-Elevation Software.

`sudo` Setup for Unprivileged Management Accounts

This section describes how you can set up an unprivileged management account with sufficient sudo permissions. Skip this section if you are opting to use a privileged account as the management account, or if the management account uses other privilege-elevation software for root permissions.

The instructions in this section are based on provided sudo templates. sudo templates are available on all Key Manager Servers under:

/opt/sshmgr/examples/sudoers

To set up an unprivileged management account with sufficient sudo permissions, perform the following on the target host:

Ensure the host has sudo version 1.7.0 or later. Install or upgrade sudo if necessary.
Copy the sudo template to /etc/sudoers.d/ukm.
In the sudo template, specify the name of the management account on the line that looks like the following (replace sshmgr with the name of the management account):
```
User_Alias      SSHUKM=sshmgr
```

The example sudo template contains all the commands run by Key Manager. For example:

Cmnd_Alias      SSHUKM_CHOWN=/bin/chown * /tmp/ssh-mgr-tmp/*, \
                          /bin/chown * /etc/ssh/*, \
                          /bin/chown * /etc/ssh2/*, \
                          /bin/chown * /opt/tectia/etc/*, \
                          /bin/chown * /opt/ssh_keys/*

Check that the listed commands are valid for the host. Some paths, such as paths related to homedirectory locations, may have to be corrected for hosts with custom configurations.

On target hosts, the host setting Elevate command must be blank. You can ensure this, for example, by creating a host group for sudo-using hosts, and explicitly set a blank Elevate command to the host group. Hosts added to this host group automatically inherit the blank privilege-elevation setting. For more information about host-group management, see Host-Group Management.

note

Hosts may inherit other privilege-elevation settings if they are subsequently added to other host groups of higher priority.

After you have deployed the host, you may use the verify its effective Elevate command using the command-line client (replace server.example.com with the target-host name):

$ ssh-mgr-client list-host-settings -I hostname=server.example.com \\
-F 'category=secure' -C value

Ensure that all the values returned by the previous command are either empty strings (""), or empty lists ([]).

On Ubuntu hosts using sudo with management account, hosts may time out while attempting to switch to Monitored state. In such cases, you may try one the following workarounds:

Disable exit value optimization on the host
Add the following to the sudo configuration of the management account:
```
Defaults !use_pty
```
Establish management connections via a different SSH server on the host.

Obtaining `sudo` Password from a Credentials Vault

If the management account requires a password for sudo, you need to set up Key Manager to obtain the password from a credentials vault.

We recommend configuring sudo-password settings in a host group, and deploying any hosts that require a sudo password into that host group. This way Key Manager will be able to fetch sudo credentials during host deployment.

To enable sudo-password fetching for a host group, modify the following host-group settings:

Listen for sudo password prompts: Set to Yes.
Configuration data for the sudo password API: Parameters for fetching the sudo password from the credentials vault.

Configuration data for the sudo password API is to be provided in the following JSON format:

{
    "url": "<required always>",
    "params": {},
    "headers": {},
    "body": {},
    "content_key": "",
    "ca_cert_path": "",
    "auth_url": "<required if vault needs authentication>",
    "auth_params": {},
    "auth_headers": {},
    "auth_body": {},
    "auth_content_key": "",
    "auth_expiry_key": ""
}               

You can configure queries with or without authentication:

The auth_* properties can be omitted if the credentials vault does not require authentication. Key Manager fetches the sudo password using a GET query, with params, headers, and body including relevant data for the GET query. Set the ca_cert_path path to point to relevant CA certificates.
Authentication is attempted if auth_url has a value. In this case use auth_params, auth_headers, and auth_body to provide the relevant data used in the POST query to the authentication endpoint.

The auth_expiry_key should contain the name of the key that, in the authentication query response, maps to the expiry time (in seconds) of the access token. This expiry time will be used to determine whether reauthentication is needed for additional GET queries.

If the vault response is in JSON format, set content_key to the name of the property that contains the password. If the vault response is just the password in string format, leave content_key empty.

You may include host attributes to the JSON values. For example, if the JSON block with params contains a key-value pair "example": "HOST_ATTR=custom1", then Key Manager would attempt to replace the value HOST_ATTR=custom1 with the host's custom1 attribute of the target host.

For example, a configuration using the PrivX password vault would look like the following:

{
    "auth_url": "https://privx.example.com/auth/api/v1/oauth/token",
    "auth_body": {
        "grant_type": "password",
        "username": "<API_CLIENT_ID>",
        "password": "<API_CLIENT_SECRET>"
    },
    "auth_expiry_key": "expires_in",
    "auth_headers": {
        "username": "<OAUTH_CLIENT_ID>",
        "password": "<OAUTH_CLIENT_SECRET>"
    },
    "auth_content_key": "access_token",
    "url": "https://privx.example.com/vault/api/v1/secrets/<SECRET_NAME>",
    "headers": {
        "Authorization": "Bearer TOKEN"
    },
    "ca_cert_path": "<CA_CERT_PATH e.g. /etc/ssl/certs/ca-certificates.crt>",
    "content_key": "pass"
}  

Settings for Hosts Using Privilege-Elevation Software

Privilege-elevation settings are required if and only if the management account on the target host is non-privileged and privilege-elevation software is used for providing root privileges to the management account.

We recommend configuring privilege-elevation settings using Key Manager host groups. This method allows you to restrict privilege-elevation settings only to hosts that require them. A separate host group is required for each group of hosts that use different privilege-elevation credentials and/or different privilege- elevation software.

For more information about privilege-elevation settings, see Privilege-Elevation Settings.

An example about adding a host that uses privilege elevation is provided in Example: Adding an Agentless Host that Uses Privilege Elevation.

Set Access Credentials (Optional, Agentless Hosts Only)

This section describes Key Manager configurations and behavior related to:

Deployment credentials: Key Manager uses these to log into agentless hosts to perform host deployment.
Login credentials: Key Manager uses these to log into agentless hosts after deployment.

If the management accounts on your agentless hosts share the same credentials, consider storing these in Key Manager. This allows you to deploy hosts with the use existing deployment credentials option, without you having to specify the credentials every time. For more information about deployment credentials, see Host-Credential Settings.

After host deployment, Key Manager by default generates a new SSH key pair used for authenticating subsequent management connections (except when deploying with HSM management keys). But if required, you may provide your own login credentials to be used for establishing management connections.

To override the credentials with which Key Manager establishes management connections, use the command-line client command set-credentials to set login credentials. For syntax examples, see set-credentials.

Host-Preparation Script (Optional)

PKM allows you to generate a host-preparation script that:

Creates the management user on the host.
Allow PKM to deploy the host by adding public keys to the management user.

The host-preparation script requires the target host to be equipped with Python 3. The host-preparation script is only supported on Linux.

To create a host-preparation script:

You will need a key pair used for deploying the host. You may for example use existing deployment credentials, or create a new key pair.
On System→Deployment, provide the following information:
- Deployment Username: The name of the account on the management account.
- Public Key: Public key that allows PKM to access the management account.
Click Generate Script to create and download the host-preparation script.
Upload the host-preparation script to the host and run as root (replace path/to/prepare_host with the path to the script):
```
# cd path/to/prepare_host
# ./prepare_script
```
note
The host-deployment script may also be run as a sudo user.

The script will:

Create the management user if it does not exist already.
Set up access to the management user with the provided public key. The script will set up both the OpenSSH and the equivalent Tectia public key regardless of the provided key type.

If you want the management user to run key-management commands via sudo, also configure sudo templates according to sudo Setup for Privileged Management Accounts or sudo Setup for Unprivileged Management Accounts.
You can now deploy the host to PKM using the corresponding private key.

Enabling Key-Activity Monitoring​

Enabling Reading OpenSSH Key Activity from Windows Hosts​

Enabling User-Key Scans for Users with Restricted Shells​

sudo Setup for Privileged Management Accounts​

sudo Setup for Unprivileged Management Accounts​

Obtaining sudo Password from a Credentials Vault​

Settings for Hosts Using Privilege-Elevation Software​

Set Access Credentials (Optional, Agentless Hosts Only)​

Host-Preparation Script (Optional)​