Property-file templates are available for each command option. The template files are located in the <pf_install>/pingfederate/bin/configcopy_templates directory.

Note:

Refer to the README.txt file in the configcopy_templates directory for a list of all commands and summary information. See the template files themselves for parameters associated with each command (or with use cases), as well as lists of Override Properties (configuration settings that can be modified in transit), where applicable.

Copies of the templates can be configured as needed and then used together (or combined into one file). Use the applicable file names as an argument when running configcopy.bat or configcopy.sh (depending on your operating system) for particular configurations, using the following command syntax:

(On Windows) 

configcopy.bat -Dconfigcopy.conf.file=<properties_file1>; <properties_file2>;...

When paths are included with the file names, you cannot use backslashes (\). Use forward slashes (/) or escape the backslash (\\).

(On Linux) 

configcopy.sh -Dconfigcopy.conf.file=<properties_file1>:<properties_file2>:...

Note that the file separators are platform specific, corresponding to the syntax used for system-level path separators.

Alternatively (or in addition), you can specify any property values via command-execution arguments, using the following syntax:

configcopy[.sh] -D<property>=<value> ...

where <property> is any property named in the properties file and <value> is the value.

Command-line property designations take precedence over any values set in the properties file.

Note:

Access to the Connection Management Service is password-protected. The usernames and passwords may be set in the properties file for both the source and target web services (passwords can be obfuscated). If passwords are set in the properties file, they cannot be overridden using the command line. If a password is not set, the configcopy tool prompts for it. Usernames always must be supplied where applicable, either in the command line or in the properties file.

The configcopy utility generates its own log file, configcopy.log, located in the <pf_install>/pingfederate/log directory. You can control settings for this log, as needed, in the file configcopy.log4j2.xml, located in the bin directory.

CAUTION:

Importing connections or other discrete configurations at the target server is not subject to the same rigorous data validation performed by the administrative console during manual configuration. Although some checks are made, it is possible to create invalid connections using the connection-migration process. Therefore, you should not use the configcopy tool to attempt to create settings at the target that do not exist at the source; for connections and other configurations copied separately, the tool is designed only for modifying the values of existing source settings to make them applicable to the target environment.

In addition, to avoid errors and prevent unstable target configurations due to missing components or faulty cross-component references (for example, invalid ID references from connection configurations to datastore configurations), be sure to adhere closely to the instructions provided in the following procedure.

  1. Ensure access to the Connection Management Service is enabled for both the source and target PingFederate servers (see Configuring service authentication).
  2. Determine which component configurations need to be copied, including plugins.
    For example, connection configurations always reference either adapter or token-translator configurations (or both) and may reference datastore configurations. These are all separate configurations, and must be copied separately (unless they already exist at the target) in conjunction with copying connection configurations.

    Server Settings, unless pre-configured at the target, also need to be copied over separately.

    Provisioning settings may be copied separately as needed to update target connections.

  3. Determine whether any configuration property files or other supporting files need to be copied.
  4. Ensure necessary plugin JAR files are installed on the target server.
    The configcopy tool does not copy over these files, which include libraries for adapters, token translators, and JDBC or any custom database drivers.

    The JAR files are located in either:

    <pf_install>/pingfederate/server/default/deploy

    or:

    <pf_install>/pingfederate/server/default/lib

  5. On the target server, ensure that signing certificates (or certificates used for XML decryption) are already in place (see Certificate and key management ).
    Private keys are not copied from server to server (public certificates may be copied); however, you may use configcopy to upload keys/certificates to the target server.

    Make note of identifying information about the target keys so you can reference the certificates in connection-copy properties.

  6. If you have not yet installed your organization's (CA-issued) SSL server certificate on both the target and source servers, either do so—you can use a configcopy command for this—or use one of the following work-arounds to ensure that configcopy can contact both servers:
    Either:
    • (Recommended) Install the Issuer certificate for the PingFederate SSL certificate in a separately managed trust store. Then the location of the file can be specified when running configcopy using the property configcopy.connection.trust.keystore.

      Or:

    • Install the Issuer certificate for the PingFederate SSL certificate into the trust store for the Java runtime under which configcopy runs.
      Note:

      If different SSL certificates are installed on the two servers, the configcopy tool must be able to trust both. In this case, both certificates must be installed in the trust store used by configcopy, or in the trust store for the Java runtime under which configcopy runs.

  7. Create properties files for the necessary commands and associated command-parameter values needed to copy the required configurations and any additional files.

    Refer to the REAME.txt file and to the properties-file templates in the <pf_install>/pingfederate/bin/configcopy_templates directory.

    Note:

    This step and those following assume the use of properties files based on the templates provided; you may also use command-line parameters (see information earlier in this section).

  8. If you are copying connections, override ID properties referencing adapter, datastores or other plugin configurations, as needed (see step 2).
    Important:

    Ensure that the plugin configurations are either previously defined at the target or are part of the same configcopy process used to copy the connections that depend on them.

  9. Create a script or run a command (or command series) that executes configcopy for each of the prepared properties files.
    See the discussion above for syntax requirements, or the README.txt file.