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] <String> (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] <String>

    (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] <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.
    [-Node] <String> 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 Postgres 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> [-Certificate] <String>
    [-CertificatePassword] <String> [-DBUser] <String> [-DBPassword] <String> [-DBServer] <String> [-DBPort] <String> [-DBDatabase] <String> [-RedisServer] <String> [-RedisPort] <String> [-NewRelayCertificate]
    [-NewLoggingRelayCertificate]

    Example:

    .\Centrify-PAS-ModifyInstallation.ps1 -Hostname pas.corpnet.com -Certificate c:\_corpnet.p12

    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.

    [-Certificate] <String>

    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] <String>]

    (Optional) Passphrase for the supplied certificate. If provided, the passphrase used to extract the plain text certificate, which is stored in the configuration.

    [-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.

    [-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.

    [-DBDatabase] <String> Enter the PostgreSQL database name to use when verifying access, if not specified in configuration file.

    [-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.

    [-NewRelayCertificate] [<SwitchParameter>]

    Use this parameter to generate and configure a new security certificate for the TCP Relay node. This is only necessary when your certificates have been compromised.

    Once you run this command, any previous TCP Relay nodes stop working, as their security parameters do not match. You must create a new deployment and deploy new TCP Relay nodes.

    [NewLoggingRelayCertificate] [<SwitchParameter>]

    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.

    Centrify-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, see Hyper-scalable PAS Command Reference.

    Note:   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 Centrify.

    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.

    Note:   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).