Data Sync Server Documentation Index
Command-Line Tool Reference Home

replace-certificate

Description
Examples
Subcommands
Arguments

Description

Replace the listener certificate for this Ping Identity Data Sync Server server instance.

Examples

Update any connection handlers that use the 'JKS' key manager provider to use a new listener certificate contained in the 'new-listener-certificate-keystore.jks' key store under the alias 'new-listener-cert':
replace-certificate replace-listener-certificate \
     --bindDN uid=admin,dc=example,dc=com --bindPasswordFile admin-password.txt \
     --source-key-store-file new-listener-certificate-keystore.jks \
     --source-key-store-password-file new-listener-certificate-keystore.pin \
     --source-certificate-alias new-listener-cert --key-manager-provider JKS \
     --trust-manager-provider JKS --target-certificate-alias server-cert


Replace the server's current inter-server certificate with the certificate contained in the 'new-inter-server-certificate-keystore.jks' key store under the alias 'new-inter-server-cert':
replace-certificate replace-inter-server-certificate \
     --bindDN uid=admin,dc=example,dc=com --bindPasswordFile admin-password.txt \
     --source-key-store-file new-inter-server-certificate-keystore.jks \
     --source-key-store-password-file new-inter-server-certificate-keystore.pin \
     --source-certificate-alias new-inter-server-cert


Purges any retired listener certificates for the local instance from the topology registry:
replace-certificate purge-retired-listener-certificates \
     --bindDN uid=admin,dc=example,dc=com --bindPasswordFile admin-password.txt


Purges any retired inter-server certificates for the local instance from the topology registry:
replace-certificate purge-retired-inter-server-certificates \
     --bindDN uid=admin,dc=example,dc=com --bindPasswordFile admin-password.txt

Subcommands

purge-retired-inter-server-certificates
purge-retired-listener-certificates
replace-inter-server-certificate
replace-listener-certificate

purge-retired-inter-server-certificates

Purge any retired inter-server certificates for the local instance from the topology registry


purge-retired-inter-server-certificates Examples

Purges any retired inter-server certificates for the local instance from the topology registry:
replace-certificate purge-retired-inter-server-certificates \
     --bindDN uid=admin,dc=example,dc=com --bindPasswordFile admin-password.txt

purge-retired-listener-certificates

Purge any retired listener certificates for the local instance from the topology registry


purge-retired-listener-certificates Examples

Purges any retired listener certificates for the local instance from the topology registry:
replace-certificate purge-retired-listener-certificates \
     --bindDN uid=admin,dc=example,dc=com --bindPasswordFile admin-password.txt

replace-inter-server-certificate

Replace the inter-server certificate that the server uses to authenticate itself to other instances in the topology


replace-inter-server-certificate Examples

Replace the server's current inter-server certificate with the certificate contained in the 'new-inter-server-certificate-keystore.jks' key store under the alias 'new-inter-server-cert':
replace-certificate replace-inter-server-certificate \
     --bindDN uid=admin,dc=example,dc=com --bindPasswordFile admin-password.txt \
     --source-key-store-file new-inter-server-certificate-keystore.jks \
     --source-key-store-password-file new-inter-server-certificate-keystore.pin \
     --source-certificate-alias new-inter-server-cert

replace-inter-server-certificate Arguments

--source-key-store-file {path}

Description The path to the key store file that holds the new inter-server certificate. It must exist, and it must be a key store in JKS or PKCS #12 format that contains at least one private key entry with a complete certificate chain. The new inter-server certificate must use an RSA key with a key size of at least 2048 bits. Each instance in the topology must have a unique inter-server certificate. We recommend that this certificate be self-signed and have a long validity window to ensure that it does not need to be replaced frequently
Required Yes
Multi-Valued No

--source-key-store-password {password}

Description The password needed to interact with the source key store. Exactly one of the --source-key-store-password and --source-key-store-password-file arguments must be provided
Required No
Multi-Valued No

--source-key-store-password-file {path}

Description The path to a file containing the password needed to interact with the source key store. If provided, this file must exist, and it must contain exactly one line with the password to use. The file may have optionally been encrypted with the encrypt-file tool using a key from the server's encryption settings database. Exactly one of the --source-key-store-password and --source-key-store-password-file arguments must be provided
Required No
Multi-Valued No

--source-certificate-alias {alias}

Description The alias, or nickname, of the source key store entry that contains the complete certificate chain and private key for the new inter-server certificate. This must be provided if the source key store contains more than one private key entry
Required No
Multi-Valued No

--source-private-key-password {password}

Description The password used to protect the source certificate's private key. This may be omitted if the private key password matches the key store password (which is often the case). If the private key password differs from the key store password, then exactly one of the --source-private-key-password and --source-private-key-password-file arguments must be provided
Required No
Multi-Valued No

--source-private-key-password-file {path}

Description The path to a file containing the password used to protect the source certificate's private key. This may be omitted if the private key password matches the key store password (which is often the case). If provided, this file must exist, and it must contain exactly one line with the password to use. The file may have optionally been encrypted with the encrypt-file tool using a key from the server's encryption settings database. If the private key password differs from the key store password, then exactly one of the --source-private-key-password and --source-private-key-password-file arguments must be provided
Required No
Multi-Valued No

replace-listener-certificate

Replace a listener certificate that the server uses for TLS communication


replace-listener-certificate Examples

Update any connection handlers that use the 'JKS' key manager provider to use a new listener certificate contained in the 'new-listener-certificate-keystore.jks' key store under the alias 'new-listener-cert':
replace-certificate replace-listener-certificate \
     --bindDN uid=admin,dc=example,dc=com --bindPasswordFile admin-password.txt \
     --source-key-store-file new-listener-certificate-keystore.jks \
     --source-key-store-password-file new-listener-certificate-keystore.pin \
     --source-certificate-alias new-listener-cert --key-manager-provider JKS \
     --trust-manager-provider JKS --target-certificate-alias server-cert

replace-listener-certificate Arguments

--source-key-store-file {path}

Description The path to the key store file that holds the new listener certificate. It must exist, and it must be a key store in JKS or PKCS #12 format that contains at least one private key entry with a complete certificate chain
Required Yes
Multi-Valued No

--source-key-store-password {password}

Description The password needed to interact with the source key store. Exactly one of the --source-key-store-password and --source-key-store-password-file arguments must be provided
Required No
Multi-Valued No

--source-key-store-password-file {path}

Description The path to a file containing the password needed to interact with the source key store. If provided, this file must exist, and it must contain exactly one line with the password to use. The file may have optionally been encrypted with the encrypt-file tool using a key from the server's encryption settings database. Exactly one of the --source-key-store-password and --source-key-store-password-file arguments must be provided
Required No
Multi-Valued No

--source-certificate-alias {alias}

Description The alias, or nickname, of the source key store entry that contains the complete certificate chain and private key for the new listener certificate. This must be provided if the source key store contains more than one private key entry
Required No
Multi-Valued No

--source-private-key-password {password}

Description The password used to protect the source certificate's private key. This may be omitted if the private key password matches the key store password (which is often the case). If the private key password differs from the key store password, then exactly one of the --source-key-store-password and --source-key-store-password-file arguments must be provided
Required No
Multi-Valued No

--source-private-key-password-file {path}

Description The path to a file containing the password used to protect the source certificate's private key. This may be omitted if the private key password matches the key store password (which is often the case). If provided, this file must exist, and it must contain exactly one line with the password to use. The file may have optionally been encrypted with the encrypt-file tool using a key from the server's encryption settings database. If the private key password differs from the key store password, then exactly one of the --source-key-store-password and --source-key-store-password-file arguments must be provided
Required No
Multi-Valued No

--key-manager-provider {name}

Description The name of the key manager provider that is defined in the server configuration and specifies the settings for the key store to update with the new listener certificate. It must be a file-based key manager provider, and it must be enabled. Any LDAP or JMX connection handlers configured to use this key manager provider will automatically start using the new certificate immediately. Any HTTP connection handlers configured to use this key manager provider will start using the new certificate after the server is restarted or the reload-http-connection-handler-certificates tool is invoked. If this argument is not provided, a default value of 'JKS' will be assumed
Default Value jks
Required Yes
Multi-Valued No

--trust-manager-provider {name}

Description The name of the trust manager provider that is defined in the server configuration and specifies the settings for the trust store to be updated with information needed to trust the new source certificate. This argument must not be used in conjunction with the --use-jvm-default-trust-manager-provider argument. If this argument is provided, then the value must specify the name of an enabled file-based trust manager provider. Any connection handlers configured to use the specified key manager provider will also be updated if necessary to use this new trust manager provider. If neither the --trust-manager-provider nor the --use-jvm-default-trust-manager-provider argument is provided, the tool will assume that the trust manager provider uses the same name as the key manager provider
Required No
Multi-Valued No

--use-jvm-default-trust-manager-provider

Description Indicates that the connection handlers configured to use the target key manager provider should be updated with a trust manager provider that will automatically trust any certificate signed by any certificate in the JVM's default set of trusted issuers. This argument must not be used in conjunction with the --trust-manager-provider argument. It is only recommended for use if the new listener certificate, and any certificates that clients may present to the server, are signed with one of those trusted issuers

--target-certificate-alias {alias}

Description The alias, or nickname, that will be used to for the new listener certificate in the target key manager provider's key store. If the key store already contains an entry with this alias, the existing entry will be renamed before the new entry is written. If this argument is not provided, a default value of 'server-cert' will be assumed
Default Value server-cert
Required Yes
Multi-Valued No

--reload-http-connection-handler-certificates

Description Request that the server reload any certificates associated with HTTP connection handlers configured with support for HTTPS. Note that this may prevent clients from resuming TLS sessions created before the reload

Arguments

-V
--version

Description Display Data Sync Server version information

-H
--help

Description Display general usage information

--help-debug

Description Display help for using debug options
Advanced Yes

-D {dn}
--bindDN {dn}

Description The DN to use to bind to the directory server when performing simple authentication.
Required No
Multi-Valued No

-w {password}
--bindPassword {password}

Description The password to use to bind to the directory server when performing simple authentication or a password-based SASL mechanism.
Required No
Multi-Valued No

-j {path}
--bindPasswordFile {path}

Description The path to the file containing the password to use to bind to the directory server when performing simple authentication or a password-based SASL mechanism.
Required No
Multi-Valued No

--promptForBindPassword

Description Indicates that the tool should interactively prompt the user for the bind password.

-K {path}
--keyStorePath {path}

Description The path to the file to use as the key store for obtaining client certificates when communicating securely with the directory server.
Required No
Multi-Valued No

-W {password}
--keyStorePassword {password}

Description The password to use to access the key store contents.
Required No
Multi-Valued No

-u {path}
--keyStorePasswordFile {path}

Description The path to the file containing the password to use to access the key store contents.
Required No
Multi-Valued No

--promptForKeyStorePassword

Description Indicates that the tool should interactively prompt the user for the password to use to access the key store contents.

--keyStoreFormat {format}

Description The format (e.g., JKS, PKCS12, PKCS11, BCFKS, etc.) for the key store file.
Required No
Multi-Valued No

--enableSSLDebugging

Description Enable Java's low-level support for debugging SSL/TLS communication. This is equivalent to setting the 'javax.net.debug' property to 'all'.

-o {name=value}
--saslOption {name=value}

Description A name-value pair providing information to use when performing SASL authentication.
Required No
Multi-Valued Yes

--useSASLExternal

Description Use the SASL EXTERNAL mechanism to authenticate.

--helpSASL

Description Provide information about the supported SASL mechanisms, including the properties available for use with each.

--interactive

Description Launch the tool in interactive mode.

--helpSubcommands

Description Display the names and descriptions of the supported subcommands.

--propertiesFilePath {path}

Description The path to a properties file used to specify default values for arguments not supplied on the command line.
Required No
Multi-Valued No

--generatePropertiesFile {path}

Description Write an empty properties file that may be used to specify default values for arguments.
Required No
Multi-Valued No

--noPropertiesFile

Description Do not obtain any argument values from a properties file.

--suppressPropertiesFileComment

Description Suppress output listing the arguments obtained from a properties file.