The migration tool, configcopy, can be used in conjunction with one or more property files to define the operational command and other parameters, including the source and/or target PingFederate servers, and to modify configuration settings as needed for the target environment.
Property-file templates are available for each command option. The template files are located in the <pf_install>/pingfederate/bin/configcopy_templates directory.
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.
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.
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.