Hyper-scalable PAS Command Reference
The scripts / commands described in this section are used to install and manage
the Hyper-scalable PAS. These commands are available once you download the
Hyper-scalable PAS software package to the computer designated to be the
Management node. Once the software package is downloaded, you run the
Hyper-scalable PAS installer (install.ps1) to install the software package which
contains a directory structure with the following items:
All PowerShell sessions must be elevated; that is RunAs Administrator mode.
Centrify-PAS-Deploy
Once the Deployment file (<deployment_id>.zip) is copied from the Management
node to a target node (Web, Background, TCP Relay) and unzipped (e.g., using
Expand-Archive), running Centrify-PAS-Deploy.ps1 installs and creates the node.
The deployment process is the same for each node with the exception of the
command node type parameter.
In addition to Web and Background nodes, you can also deploy two types of TCP
Relay nodes: Logging node and the regular Relay node.
Usage:
.\Centrify-PAS-Deploy.ps1 [-BackgroundNode] [-RemoveNode] [-Report] [-ID]
<String> [-URI] <String>
Example:
.\Centrify-PAS-Deploy.ps1 -BackgroundNode -ID PrimaryBackground
Command parameters:
|
Parameter |
Description |
|---|---|
|
[-WebNode] [-BackgroundNode] [-RelayNode] [-LoggingNode] [-RemoveNode] |
Enter the node type where you are deploying the software. String variance depends on node type. Remove this node from the cluster. (Decommission.) |
|
[-Report] |
Provides data for the installed node. |
|
[-ID] |
(Optional ID) Enter a unique instance ID to act as a node identifier. If you do not enter a value, a GUID is created. The ID must be unique across the installation, but is not verified at deployment, so only use this parameter if you're certain it is unique. |
|
[-URI] |
(TCP Relay or Logging nodes only) Hostname or IP Address that can reach the TCP Relay or Logging Service. If not provided, the internal network address is used. |
Centrify-PAS-ForceRemoveNode
Use Centrify-PAS-ForceRemoveNode.ps1 to remove an unused or malfunctioning node
from the Hyper-scalable PAS installation. This does not decommission the node on
the server. Generally, you should run the Centrify-PAS-Deploy -RemoveNode
command on the node to be removed.
Usage:
.\Centrify-PAS-ForceRemoveNode.ps1 [-Hostname] <String> [-Node] <String>
Example:
.\Centrify-PAS-ForceRemoveNode -Hostname pas.corpnet.com -Node
PrimaryBackgroundNode
Command parameters:
|
Parameter |
Description |
|---|---|
|
[-Hostname] |
Enter the hostname you use to define the Installation (for example, pas.corpnet.com). This also serves as the configuration name in the Installations\Config directory. The Hostname defines the Installation. |
|
[-Node] |
Enter the name of the node you want to remove (for example. WebNode, BackgroundNode, RelayNode, or LoggingNode) |
Centrify-PAS-GetDeployment
Use the Centrify-PAS-GetDeployment.ps1 command to see if a deployment is active.
Running this command from the Management node retrieves the currently-active
Deployment ID for all the nodes associated with the installation.
Usage:
.\Centrify-PAS-GetDeployment.ps1 [-ListDeployments]
Command parameters:
|
Parameter |
Description |
|---|---|
|
[-ListDeployments] |
Enter the Deployment ID to get a list of nodes associated with the installation. |
Centrify-PAS-ModifyInstallation
Use the Centrify-PAS-ModifyInstallation.ps1 command to modify an existing
Hyper-scalable PAS Installation. You can change significant elements of the
installation, such as:
-
Changing the PostgreSQL database or database credentials
-
Changing the Redis (cache) server
-
Rotating the TCP Relay node certificates
-
Changing the host certificate
In order to implement the changes, you must create and deploy a new deployment
to Web and Background nodes.
Usage:
.\Centrify-PAS-ModifyInstallation.ps1 [[-Hostname] <String>] [[-NewHostname]
<String>] [[-Certificate] <String>] [[-CertificatePassword] <String>]
[[-DBUser] <String>] [[-DBPassword] <String>] [[-DBServer] <String>]
[[-DBPort] <String>] [[-DBDatabase] <String>] [[-RedisServer] <String>]
[[-RedisPort] <String>] [[-RedisPassword] <String>] [-DBSSL]
[-DBTrustServerSSL] [-NewRelayCertificate] [-NewLoggingRelayCertificate]
[-DBNoPLV8] [-RedisSSL] [<CommonParameters>] (Deprecated)
The RedisTrustServerSSL parameter is not supported in Web RDP/SSH.
Example:
.\Centrify-PAS-ModifyInstallation.ps1 -Hostname pas.corpnet.com -Certificate
c:\_corpnet.p12
Command Parameters:
|
Parameter |
Description |
|---|---|
|
[-Hostname] |
Enter the hostname you use to define the Installation (for example, pas.corpnet.com). This also serves as the configuration name in the Installations\Config directory. The Hostname defines the Installation. |
|
[-NewHostname] |
(Optional) Replacement hostname for the installation. If set, the installation files will be moved to a new matching directory, and the previous Installation will be marked "Deprecated". Note: Use this with caution. |
|
[-Certificate] |
Enter the source location for the new certificate, if not specified in the configuration file. Make sure that the certificate used is from a trusted certificate authority, is PKCS #12 SSL in either .pfx (Personal Information Exchange) or .p12 format (successor format to .pfx), and the hostname is supported by the certificate. Hyper-scalable PAS does not generate self-signed certs. |
|
[-CertificatePassword] ] |
(Optional) Passphrase for the supplied certificate. If provided, the passphrase used to extract the plain text certificate, which is stored in the configuration. |
|
[-DBUser] |
Type the user name used to log in to the database, if not specified in the configuration file. |
|
[-DBPassword] |
Type the password credential used to log in to the PostgreSQL database, if not specified in configuration file. |
|
[-DBServer] |
Enter the server hostname (URI) for PostgreSQL, if not specified in configuration file. |
|
[-DBPort] |
Enter the PostgreSQL server port, typically 5432, if not specified in configuration file. |
|
[-DBDatabase] |
Enter the PostgreSQL database name to use when verifying access, if not specified in configuration file. |
|
[-RedisServer] |
Enter the Redis server hostname (URI), if not specified in configuration file. |
|
[-RedisPort] |
Enter the Redis server port, typically 6379, if not specified in configuration file. |
|
[-RedisPassword] |
Enter the Redis access key if required. |
|
[-DBSSL] |
Specifies to use SSL to communicate to the database. |
|
[-DBTrustServerSSL] |
Tells the client to accept the server without verifying the certificate chain. See SSL information in the Prerequisites section for more detail. |
|
[-NewRelayCertificate] |
Use this parameter to generate and configure a new security certificate for the TCP Relay node. Note: This is only necessary when your certificates have been compromised. Once you run this command, any previous TCP Relay nodes will stop working, since their security parameters do not match. You must create a new deployment and deploy new TCP Relay nodes. |
|
[NewLoggingRelayCertificate] |
Use this parameter to generate and configure a new security certificate for the TCP Relay Logging node. This is only necessary when your certificates have been compromised. Once you run this command , logging to the TCP Relay Logging node stops working as the security parameters do not match. You must create a new deployment and deploy a new TCP Relay Logging node, then restart Web and Background nodes. |
|
[-DBNoPLV8] (Deprecated) |
Required if this switch was previously used, to bypass checking the database for PLV8. |
|
[-RedisSSL] |
Specifies that SSL (TLS 1.2 or 1.3) is to be used with Redis. |
|
|
This cmdlet supports the common parameters: Verbose, Debug,ErrorAction, ErrorVariable, WarningAction, WarningVariable, OutBuffer, PipelineVariable, and OutVariable. For more information, see about_CommonParameters. |
|
[-RedisTrustServerSSL] |
This parameter is not supported in Web RDP/SSH. |
Centrality-PAS-NewDeployment
The Centrify-PAS-NewDeployment.ps1 creates a Deployment package (a .zip file)
that you can distribute to cluster node machines (Web nodes, Background nodes,
and TCP Relay nodes). The Centrify-PAS-NewDeployment.ps1 script updates the
database schema and creates a Deployment in a new folder under the
Installations\<hostname>\Deployments directory on the Management node, with
the current date and the Deployment ID (as specified or as a GUID).
Usage:
.\Centrify-PAS-NewDeployment.ps1 [-Hostname] <String> [-ID] <String>
Example:
.\Centrify-PAS-NewDeployment.ps1 -Hostname pas.corpnet.com
Command parameters:
|
Parameter |
Description |
|---|---|
|
[-Hostname] <String> |
Enter the hostname you use to define the Installation (for example, pas.corpnet.com). This also serves as the configuration name in the Installations\Config directory. The Hostname defines the Installation. |
|
[-ID] <String> |
(Optional) Enter a unique ID (such as First, Second, Third) to set the new Deployment ID. The Deployment ID acts as the Installation version to identify the Deployment and to determine which nodes are active and inactive. You can see it when you issue the NodeList command. If you do not provide an ID, a GUID is created and used to identify the Installation version. Only alpha-numeric characters are allowed. |
Centrify-PAS-NewInstallation
The first step in creating a new installation is to run the
Centrify-PAS-NewInstallation.ps1 command on the Management node. This creates
the configuration file, verifies the configuration inputs, checks for the Redis
and database servers, initializes the database, and checks for the required
database extensions.
You can also pass configuration parameters via config.json file. If you use this
method, you need to populate the config.json file with the required data prior
to running the script.
Do not re-run Centrify-PAS-NewInstallation.ps1 on a configuration
with active data, as it will reformat the database and destroy the data. Use Centrify-PAS-ModifyInstallation instead.
Usage:
.\Centrify-PAS-NewInstallation.ps1
[-Hostname] <String>
[-Certificate]<String>
[-DBUser] <String>
[-DBPassword] <String>
[-DBServer] <String>
[-RedisServer] <String>
[-AdministratorName] <String>
[-AdministratorPassword] <String>
[-AdministratorEmail] <String>
[-CompanyName] <String>
Example:
.\Centrify-PAS-NewInstallation.ps1
-Hostname pas.corpnet.com
-Certificate C:\corpnet.com.p12
-DBUser centrifyAccount
-DBPassword secretCode
-DBServer postgres.corpnet
-RedisServer cache.corpnet
-AdministratorName PASAdmin
-AdministratorPassword EvenM0reS3cret
-AdministratorEmail pasadmin@corpnet.com
-CompanyName Corpnet
-LicenseKey 234KL43
Command parameters:
|
Parameter |
Description |
|---|---|
|
[-Hostname] <String> |
Enter the hostname you use to define the Installation (for example, pas.corpnet.com). This also serves as the configuration name in the Installations\Config directory. The Hostname defines the Installation. |
|
[-Conf] <String> |
Enter the source location for the configuration file (config.json) to copy values from. This is updated and stored in the installations\Config\hostname subdirectory, for use by Centrify-PAS-NewDeployment.ps1. |
|
[-Certificate] <String> |
Enter the source location for the certificate. Make sure that the certificate used is from a trusted certificate authority, is PKCS #12 SSL in either .pfx (Personal Information Exchange) or .p12 format (successor format to .pfx), and the hostname is supported by the certificate. Hyper-scalable PAS does not generate self-signed certs. |
|
[-DBDatabase] <String> |
Enter the PostgreSQL database name to use when verifying access, if not specified in configuration file. |
|
[-DBServer] <String> |
Enter the server hostname (URI) for PostgreSQL, if not specified in configuration file. |
|
[-DBPort] <String> |
Enter the PostgreSQL server port, typically 5432, if not specified in configuration file. |
|
[-DBUser] <String> |
Type the user name used to log in to the database, if not specified in the configuration file. |
|
[-DBPassword] <String> |
Type the password credential used to log in to the PostgreSQL database, if not specified in configuration file. |
|
[-DBSSL] |
Specifies to use SSL to communicate to the database. |
|
[-DBTrustServerSSL] |
Tells the client to accept the server without verifying the certificate chain. See SSL information in the Prerequisites section for more detail. |
|
[-RedisServer] <String> |
Enter the Redis server hostname (URI), if not specified in configuration file. |
|
[-RedisPort] <String> |
Enter the Redis server port, typically 6379, if not specified in configuration file. |
|
[-RedisPassword] <String> |
Enter the Redis access key if required. |
|
[-RedisSSL] |
Specifies that SSL (TLS 1.2 or 1.3) is to be used with Redis. |
|
[-AdministratorName] <String> |
Enter the name for initial administrative account, if not specified in configuration file. |
|
[-AdministratorPassword] <String> |
Enter the password for initial administrative account, if not specified in the configuration file. |
|
[-AdministratorEmail] <String> |
Enter the email address for initial administrative account, if not specified in the configuration file. |
|
[-CompanyName] <String> |
Enter the company name exactly as it appears in the license key data. |
|
[-LicenseKey] <String> |
Enter the license key for this installation. The license key is provided by IBM Security. |
Centrify-PAS-NodeList
This command provides a lists of all nodes (Web, Background, and Relay)
associated with the Hyper-scalable PAS installation and their status. The
following status information is available:
-
Active: a status of Active indicates that the node is part of the current
deployment. -
Inactive: a status of Inactive indicates that the node is registered with a
different Deployment ID than the current active one. -
Online: indicates a node is running and connected to the database.
-
Offline: indicates a node that is not running or not able to connect to the
database.
Even though TCP Relay nodes have an associated Deployment ID,
they are not tied to a Deployment. For a TCP Relay node, the Deployment ID
is considered to be the version rather than a grouping, as they don't parse
or handle data structures.
Usage:
.\Centrify-Pas-NodeList.ps1 [-Hostname] <String>] [-Detailed] [-Relays]
[-DiagnosticRelays]
Example:
Command parameters:
|
Parameter |
Description |
|---|---|
|
[-Hostname] <String> |
Enter the hostname used for the deployment you want to access. This command impacts all hostnames (of which there should really be just one), but allows for partitioning of the configurations. |
|
[-Detailed] <SwitchParameter>] |
List out the system info (CPU, Disk, etc.) for each node at the time of Deployment. Does not apply to TCP Relay nodes or Relay Logging nodes. |
|
[-Relays] <SwitchParameter> |
Displays active TCP Relay data. |
|
[-DiagnosticRelays] <SwitchParameter> |
Displays active Logging data. |
Centrify-PAS-SetActiveDeployment
Use the Centrify-PAS-SetActiveDeployment.ps1 command to switch to the new
Deployment ID and activate new nodes (Web and Background). The Deployment ID is
created or assigned when creating a new deployment. Once the deployment is
created, new nodes can be created, but those nodes won't respond to traffic
until the load balancer points to the new Web nodes, and the new Deployment is
set to Active. To activate inactive nodes, you run the
.\Centrify-PAS-SetActiveDeployment.ps1 script from the Management node,
specifying the desired Deployment ID.
Any nodes in a previous Deployment ID are inactive and show as unhealthy or down
in your load balancer, while the new nodes with matching Deployment IDs are
active and show as healthy or up. Depending on the load balancer settings there
may be a delay.
Usage:
.\Centrify-PAS-SetActiveDeployment.ps1 [-Hostname] <String> [-ID] <String>
Example:
.\Centrify-PAS-SetActiveDeployment -Hostname pas.corpnet.com -ID Aug21Deploy
Command parameters:
|
Parameter |
Description |
|---|---|
|
[-Hostname] <String> |
Enter the hostname used for this deployment. This command impacts all hostnames (of which there should really be just one), but allows for partitioning of the configurations. |
|
[-ID] <String> |
Enter the Deployment ID or GUID to activate the deployment. |
Centrify-PAS-WatchLogs
Use the Centrify-PAS-WatchLogs.ps1 command to watch or capture logs from the
Web, Background, and Relay nodes. The command Centrify-Pas-WatchLogs.ps1 does
not work without a dedicated logging node.
Usage:
.\Centrify-Pas-WatchLogs.ps1 [-Hostname] <String>]
Example:
.\Centrify-Pas-WatchLogs.ps1 -Hostname pas.corpnet.com
Command parameters:
|
Parameter |
Description |
|---|---|
|
[-Hostname] <String> |
Enter the hostname you use to define the Installation (for example, pas.corpnet.com). |