Command Line Utility Reference Guide

PAM – Privileged Access Management

CLU – PAM Command Line Utility

CLI – command line interface

$PAM_HOME – PAM Server deployment folder

ADS – internal user directory service

CDN – content distribution network for PAM binaries

PAM Command Line Utility (CLU) is a helper utility to simplify and to facilitate PAM Server configuration and deployment activities.

This guide expects CLU will be launched from the $PAM_HOME folder by providing full or relative path to the utility launcher. A typical issue with launching CLU is running it from a location other than the $PAM_HOME folder (typically $PAM_HOME/bin which is incorrect).

Example of the launch command for Linux hosts is given below:

1
./bin/PamDirectory.sh COMMAND PARAMETER1 PARAMETER2 …

Example of the launch command for Windows hosts is given below:

1
.\bin\PamDirectory.cmd COMMAND PARAMETER1 PARAMETER2 …

Below are several examples of the command run on a Linux host to integrate with Active Directory prompting for the user’s password:

1
./bin/PamDirectory.sh ADConnect web dc-server ad-service-user -

1
./bin/PamDirectory.sh ADConnect web ldaps://dc-server:636 ad-service-user -

• catalina.home is the folder where PAM Server WEB Container is located. Typically, it is $PAM_HOME/web folder. When the CLU is launched from the $PAM_HOME folder it could be specified using a relative path: web

 

• password – in the majority of the cases it is possible to specify dash ( - ) instead of the password in the command line to make the CLU to allow a user to type the password in a secure input prompt. This option masks the password during CLU execution and to simplify the entry of special characters.

 

• File PATH_TO_THE_INSTRUCTION_FILE – parameter File allows one to provide CLU the text file with the list of parameters instead of providing command parameters using command line.

  The parameters file is a regular properties file with all parameters defined under the same section called: instruction.

  Command parameter is specified using property command.

  All other parameters are specified as properties with the property name as it is defined in this guide.

  Note that unlike the ordered unnamed command line parameters, parameters given by file specification are unordered and named with the required names defined in this document in the Parameters section.

  Example of the File properties file for the command SetAdminPassword is given below:

 

[instruction]

catalina.home=web

admin.password=pam-generate

The command replaces the password of the service account (DN: uid=admin,ou=system) in the local user directory services. The current password is obtained from the existing configuration. The command also updates this password encrypted in the PAM Server configuration file. A service restart is required after executing this command.

Parameters

• catalina.home

• admin.password - New administrator password parameter might be a password itself, a dash to prompt a user to enter a password, or one of the keywords <generate> or pam-generate to generate new password. The generated password will be printed on the console after the command execution

The command sets a new master password used to encrypt and decrypt sensitive data in the PAM Vault. Note that the command does not re-encrypt existing records so updating master password might cause existing records to become unreadable by the system in case they were encrypted by different master password.

The command is useful in cases like deploying new node to the existing farm or to migrate back-end database to another system.

Parameters

• catalina.home

• master.password - New master password parameter might be a password itself, a dash to prompt a user to enter a password, or one of the keywords <generate> or pam-generate to generate new password. The generated password will be printed on the console after the command execution

This command replaces the password of a service account for the embedded database in cases when the system is deployed with the internal Apache Derby database. The command also updates this password encrypted in the PAM Server configuration file. A service restart is required after executing this command.

Parameters

• catalina.home

• db.home is a folder where the internal Apache Derby database is deployed. Typically, it is $PAM_HOME/db folder. When the CLU is launched from the $PAM_HOME folder it could be specified using the relative path: db

• db.password – New database administrator password parameter might be a password itself, a dash to prompt a user to enter a password, or one of the keywords <generate> or pam-generate to generate new password. The generated password will be printed on the console after the command execution

The command initializes new local user directory service with the LDAP structure required for PAM operations.

Parameters

• catalina.home

This command creates a local user in the local user directory.

Parameters

• catalina.home

• user.login is the login name of the newly created account

• user.firstName is the first name

• user.lastName is the last name

• user.password is a new user password that might be a password itself, a dash to prompt a user to enter a password, a keyword GENERATE to generate new password. The generated password will be printed on the console after the command execution. The password might start with base64- prefix. In this case the command will treat the string after the prefix as a Base64 decided password.

This command creates a local group in the local user directory optionally with one specified group member.

Parameters

• catalina.home

• group.name is the name of a new group

• group.description is a description of a new group

• group.member is the optional member of a new group given as the login name of the account

The command renames a local group in the local user directory.

Parameters

• catalina.home

• group.name is the existing group name

• group.newName is the new group name

This command sets a new password for an existing local user.

Parameters

• catalina.home

• ads.password is a local user directory service account password

• user.login is the user login

• user.password is the new user password. The password might start with base64- prefix. In this case the command will treat the string after the prefix as a Base64 decided password.

This command sets up integration with Microsoft Active Directory. The result of the successful execution of this command is the set of AD connection properties defined in the $PAM_HOME/web/conf/catalina.properties file. The PAM service needs to be restarted after executing this command. This command establishes connection to one Active Directory server. Establishing another connection will replace the previous connection. To manage integration with multiple LDAP / AD servers use the LdapConnect command.

Read more about integration with MS Active Directory in the application’s help system.

Parameters

• catalina.home

• ldap.server is the AD Domain Controller server or URL. When just server is specified the CLU attempts to connect to the AD Global Catalogue first and then to the AD Domain Controller itself using LDAPS protocol. Custom protocols or ports could be specified using full URL notation like in the example, ldaps://ad-server.company.com:port.

Note that for the secure communications using LDAPS protocol the AD server certificate should be imported into the PAM Server keystore (see the command SSLImport) and the name on the certificate should match the name of the AD-server host in the URL.

• ldap.user is the service account in MS Active Directory

• ldap.password is the service account password that might be a password itself or a dash to prompt a user to enter a password. The password might start with base64- prefix. In this case the command will treat the string after the prefix as a Base64 decided password.

Example

Configure a new AD connection requesting the command to prompt for the service user password

1
./bin/PamDirectory.sh ADConnect web ldaps://eu-dc-server pam-service-eu -

This command executes a provided LDAP Query in the first integrated MS Active Directory to test the connection and to test the query.

Parameters

• catalina.home

• ldap.query is the LDAP query to execute

• -v is the optional parameter to enable additional logging information printed during the query execution.

  Note that for the File method to pass parameters this parameter in the properties file should be called verbose

This command manages integrations with multiple LDAP user directories. Specifically, the command can either add new or delete existing integrations. The result of the successful execution of this command is the set of LDAP connection properties defined in the $PAM_HOME/web/conf/catalina.properties file. The PAM service needs to be restarted after executing this command. To manage integration with a single AD server, administrators might use the ADConnect command.

Read more about integration with multiple LDAP user directories in the application’s help system.

Parameters

catalina.home

ldap.name is the friendly name of the integrated LDAP server. This name is used in the consequent LDAP management commands as well as in the PAM system as a reference point for the external users. Use alphanumeric characters only.

ldap.server is LDAP server or URL. Custom protocols or ports could be specified using full URL notation like in the example, ldaps://ldap-server.company.com:port.

ldap.user is the service account in LDAP server

ldap.password is the service account password that might be a password itself or a dash to prompt a user to enter a password. The password might be started with base64- prefix. In this case the command will treat the string after the prefix as a Base64 decided password.

Examples

Configure new LDAP connection assigning it new name EU-DC requesting the command to prompt for the service user password:

1
./bin/PamDirectory.sh LDAPConnect web EU-DC ldaps://eu-dc-server pam-service-eu -

Delete configured LDAP connection with the name EU-DC:

1
./bin/PamDirectory.sh LDAPConnect web EU-DC DISABLE

This command establishes a connection with the internal user directory service (ADS). The connection with the local internal user directory is established during installation. The command is useful to connect to a remotely deployed internal user directory.

Parameters

• catalina.home

• ads.server is ADS server or URL. Custom protocols or ports could be specified using full URL notation like in the example, ldaps://ldap-server.company.com:port.

• ads.password is the service account (for the account DN: uid=admin,ou=system) password that might be a password itself or a dash to prompt a user to enter a password. The password might start with base64- prefix. In this case the command will treat the string after the prefix as a Base64 decided password.

This command establishes a local user directory replication with the other node of a two-node deployment. Executing this command with a different server will replace the previously established replication. To manage replication for more than two node deployments use the ADSReplication command.

Read more about the internal user directory replication in high availability deployments in the help system.

Parameters

• catalina.home

• ads.remote.server is the host of the replicating system

• ads.remote.password is the service account (for the account DN: uid=admin,ou=system) password that might be a password itself or a dash to prompt a user to enter a password. The password might start with base64- prefix. In this case the command will treat the string after the prefix as a Base64 decided password.

This command manages internal user directory replication between multiple nodes. Each replication process in the local node is associated with the numerical index (1, 2, 3, …) used in this command. For example, in three-node deployment each node will maintain two replication processes indexed by numbers 1 and 2 on each node with each of the other nodes.

Read more about the internal user directory replication in high availability deployments in the help system.

Parameters

• catalina.home

• ads.remote.index is the replication process index on this node to apply below parameters to. Alternatively, this parameter might have a keyword list. This list command will list parameters of all configured replication processes on this node. When list command is specified, no other parameters are needed.

• ads.remote.server is the host of the replicating system. Alternatively, this parameter might contain keywork delete to delete this replication process from the local node.

• ads.remote.password is the service account (for the account DN: uid=admin,ou=system) password that might be a password itself or a dash to prompt a user to enter a password. The password might start with base64- prefix. In this case the command will treat the string after the prefix as a Base64 decided password.

Examples

List configured replication slots:

1
./bin/PamDirectory.sh ADSReplication web list

Delete configured replication slots number 3:

1
./bin/PamDirectory.sh ADSReplication web 3 delete

Configure replication slot number 3 requesting the command to prompt for the password:

1
./bin/PamDirectory.sh ADSReplication web 3 pam-node-d -

This command exports content of internal local user directory service to an external XML file.

Parameters

• catalina.home

• file is the file path

• encrypted is a true or false parameter indicating whether the export file should contain sensitive data encrypted

This command imports the content of the exported file to the internal user directory service.

Parameters

• catalina.home

• file is the file

This command changes connection to a new back-end database. The command expects the database server to exist with the appropriate instance and the data-storage with the name PamDB pre-created. A service restart is required after successful execution of this command.

Parameters

• catalina.home

• db.type is the vendor of the back-end database with possible values: Derby, MySql, MSSQL, Oracle, PostgreSQL

• db.server is the host name of the back-end database. The command will try the port default for the vendor in case the port is not specified. Otherwise, specify port in host:port notation.

• db.user is the service account for the database integration.

• db.password is the service account password that might be a password itself or a dash to prompt a user to enter a password. The password might start with base64- prefix. In this case the command will treat the string after the prefix as a Base64 decided password.

This command runs on the remote PAM node and establishes a connection with the master node. The communication between remote and master node is done using the https protocol.

Parameters

• catalina.home

• pam.server is the host of the master node in the form of host, host:port or https://host:port.

• pam.user is the service account with the Service role in the master node.

• pam.password is the service account password that might be a password itself or a dash to prompt a user to enter a password. The password might start with base64- prefix. In this case the command will treat the string after the prefix as a Base64 decided password.

This command manages single server integration with MS Active Directory services. The PAM service should be restarted after successful execution of this command. The command is used by the installation process leaving the configuration complete after the successful installation. The command modifies properties in $PAM_HOME/web/conf/server.xml that could be otherwise managed directly without this command.

Parameters

• catalina.home

• auth.catalina.enable is an indicator with possible true or false values to manage combined user realm.

• auth.ad.enable is an indicator with possible true or false values to manage Active Directory pool connector as a part of the combined realm.

This command manages configuration of the Federated Sign-In module. The command is used by the installation process, leaving the configuration complete after a successful installation. The command modifies properties in $PAM_HOME/web/conf/server.xml that could be otherwise managed directly without this command. A service restart is required after successful execution of this command.

Parameters

• catalina.home

• managed.path is the expected managed path of the PAM WEB Application it will be accessed by its WEB users.

• sso.enable enable is an indicator with possible true or false values to enable or disable the Federated Sign-In configuration.

This command generates a new self-signed SSL certificate to secure the PAM server WEB application traffic and applies it to the PAM WEB container. A service restart is required after successful execution of this command.

Parameters

• catalina.home

This command checks PAM system logs to detect whether PAM service had started up.

Parameters

• catalina.home

This command checks ADS system logs to detect whether ADS service had started up.

Parameters

• catalina.home

• ads.check.timeout.ms is the delay in milliseconds.

This command generates unique encryption and signature keys for use by the Federated Sign-In module. Each installation procedure runs this command to generate unique keys for each deployment. A service restart is required after successful execution of this command.

Read more about synchronizing encryption and signature keys for high availability deployments in the help system.

Parameters

• catalina.home

This command encrypts provided sensitive password using the algorithm

used by the Federated Sign-In module to put to the configuration file so that sensitive password would not be stored in the configuration files unencrypted.

Read more in the system help for the information about the technique to use encrypted Federated Sign-In module passwords in the configuration files.

Parameters

• catalina.home

• password might be a password itself or a dash to prompt a user to enter a password.

This command generates a unique certificate bundle for use by the WEB Session manager to protect traffic between the PAM master node and the WEB Session Manager. The command also uploads the bundle into the ADS storage.

Parameters

• catalina.home

• bundle.file.name is the file name for the generated new ZIP bundle.

This command extracts the WEB Session Manager certificate bundle from the ADS storage to the local file system.

Parameters

• catalina.home

• bundle.file.name is the file name for the extracted new ZIP bundle. For example, pamcert.zip

This command allows one to replace all positional command line parameters with the instruction file that contains all these parameters named with the names given in this guide. This option provides better control over the command execution by automated scripts and over special characters that can appear in the parameter.

See more details about the instruction file structure with the example in the Common Parameters File description in this guide.

This command enables non-open mode in Federated Sign-In module that forbids logins to the PAM WEB application with the unapproved destination service provided in the login URL.

Parameters

• catalina.home

This command signs a binary file with the signature key from the provided key store. PAM Server can verify the signature using the public key certificate included with every deployment.

Parameters

• KEYSTORE_PATH – path to the keystore with the signature private key

• KEYSTORE_PASSWORD – password to the keystore

• FILE_PATH – binary file to sign

This command encrypts a provided text string so it could be used in the configuration file $PAM_HOME/web/conf/catalina.properties for sensitive data. PAM Server internally decrypts passwords in the configuration files encrypted by this command.

Parameters

• SECRET is the secret sensitive data to decrypt. Alternatively, it is possible to type dash (-) instead of the data itself for the command to prompt user to type the data in the hidden prompt.

This command attempts to connect to the provider HTTPS URL to test the validity of the certificate securing this URL endpoint. The command issues a connection error in case of issues.

Parameters

• URL is the HTTPS URL to connect

This command attempts to connect to the TCP endpoint given by host and port parameters. After connection the command obtains a certificate from the connected endpoint and analyzes its validity.

Parameters

• Host is the endpoint host

• Port is the endpoint port

This command connects to the specified TCP endpoint, validates its SSL certificate and imports it to the PAM Server keystore. After successful connection, the command lists all certificates from the certificate chain retrieved from the connected endpoint allowing a user to import selected certificates into the PAM Server keystore. The command also generates errors of certificate validation and trust in case of the detected certificate or trust issues.

The command is useful to establish trust for PAM Server with various components connected using various protocols in case the protocols are secured by the self-signed SSL certificate generated in-house as oppose to well-known Internet certificate authorities. Examples of such components include: MS Active Directory, external LDAP server (eDirectory, OpenLDAP), PAM Remote Session Manager, PAM ADS, PAM WEB Container, PAM Load Balancer, etc

Parameters

• Host is the endpoint host

• Port is the endpoint port

• in-place is an optional parameter with true (default) or false values that allows to import the certificate into the temporary local file instead of directly to the PAM Server keystore

Example

1
./bin/PamDirectory.sh SSLImport remote-session-manager-host 4822

This command tests connection to the provided LDAP server without making configuration changes in the system.

Parameters

• LDAP_SERVER is an LDAP server host or URL

• LDAP_USER is an LDAP server user

• LDAP_PASSWORD is an LDAP server password or a dash to prompt a user to enter a password. The password might start with base64- prefix. In this case the command will treat the string after the prefix as a Base64 decided password.

This command decrypts a file (such as session recording stored on the file system) encrypted by PAM Server using provided master password.

Parameters

• encrypted.file is path to the source encrypted file

• unencrypted.file is path to the destination decrypted file

This command downloads the last published PAM Server version from PAM binaries content distribution network. The command allows to test the connection from the server hosting PAM deployment to the PAM CDN. The command also allows to test connection established through HTTP proxy in case direct traffic to PAM CDN is blocked but proxy traffic is allowed.

Parameters

• pam.edition is the optional parameter with the possible values product (default) for production version or qa for QA version.

• proxy is the optional parameter to specify proxy host and port in the notation proxy:port to test indirect proxied connection to PAM CDN. Alternatively, specify dash (-) in this parameter to indicate that direct connection should be used instead of proxy to allow to use next positional parameter to test protocol security.

• security.level is the optional parameter to specify different levels of protocol security with possible values SSLv3, TLSv1, TLSv1.1, TLSv1.2.

This command lists records from the system export that match the provided criteria.

Parameters

• export.file is the full path to the export file or to the export file base: a file name without extension and export index to include all export files into the archive search.

• match is the criteria to search for records. The command will perform a case insensitive search for a match criterion as a substring of record name, description or host. Alternatively, a criterion might be a record ID.

This command extracts sensitive information of the specified records from the system export and prints it on the screen. The command requires the master password.

Parameters

• export.file is the full path to the export file or to the export file base: a file name without extension and export index to include all export files into the archive search.

• name is the criteria to search for records. The command will perform a case insensitive search for a match criterion as a substring of record name, description or host. Alternatively, a criterion might be a record ID.

• master is a master password to decrypt the records sensitive data. The master password might be a password itself or a dash to prompt a user to enter a password. The password might start with base64- prefix. In this case the command will treat the string after the prefix as a Base64 decided password.

This command removes Administrator block from all workflow bindings in the system to unlock system administrators who accidentally locked themselves by applying workflow bindings they could not pass (blocking, interactive approval with missed required approvers). The command requires a valid master password.

Parameters

• catalina.home

• master is a master password to decrypt the records sensitive data. The master password might be a password itself or a dash to prompt a user to enter a password. The password might start with base64- prefix. In this case the command will treat the string after the prefix as a Base64 decided password.

This command lists cached users for further analysis. The command requires a valid master password.

Parameters

• catalina.home

• master is a master password to decrypt the records sensitive data. The master password might be a password itself or a dash to prompt a user to enter a password. The password might start with base64- prefix. In this case the command will treat the string after the prefix as a Base64 decided password.

This command unblocks the user by provided login. The command requires a valid master password.

The command is useful to unlock locked administrators in cases of single system administrator present in the system.

Parameters

• catalina.home

• user is the user login to unlock

• master is a master password to decrypt the records sensitive data. The master password might be a password itself or a dash to prompt a user to enter a password. The password might start with base64- prefix. In this case the command will treat the string after the prefix as a Base64 decided password.