Server profiles

Regardless of the service model that your company follows, server profiles help you achieve your goals. At a basic level, a server profile defines a format for the configuration of a server by combining the following files into a single concrete structure:

dsconfig
Initial DIT (PingDirectory only)
Setup arguments
Server SDK extensions
Additional miscellaneous files

Server profiles can simplify the deployment of the server and related products. They help reduce the amount of scripting needed to use deployment automation frameworks such as Docker, Kubernetes, and Ansible.

The following image shows the role that a PingDirectory server profile plays in building a fully functional running server:

The following image shows the role of a PingDirectoryProxy or PingDataSync server profile:

Benefits of using server profiles

As a declarative form of a full server configuration, a server profile provides the following advantages:

Provides a more complete and easily comparable way to define an individual server’s configuration. Changes between different servers are easier to understand, and incremental changes to a server’s configuration are easier to track.
Ensures that each server instance is configured identically to its peers.
Can be applied directly to new as well as previously installed instances.
Shares a common configuration across a deployment pipeline of development, test, and production environments without unnecessary duplication. For information about substituting variables that differ by environment, see Variable substitution.
Facilitates deployment automation by representing configuration as code.
Reduces the number of additional configuration steps that are required to place a server into production.
Makes the execution of various configuration changes more consistent and repeatable. The strategy of using a server profile to represent the final state of a server is less error-prone than recording a step-by-step process to attain that state.
Can be managed easily in a version-control system.
Simplifies the management of servers outside deployment automation frameworks.

A continuous deployment workflow can work with server profiles to make certain that changes to a server profile are moved automatically into production. In a stateful environment, the manage-profile replace-profile subcommand can be used to update existing servers. In a stateless environment, in which servers are considered immutable, manage-profile setup can be used to deploy new servers whenever a profile changes. With multiple environments, this deployment can be performed in a test environment before moving to production.

When working with compressed server SDK extensions and other files that might not be stored in a version-control system, the server profile can be modified to include these files before its use. For example, if the code for an extension is stored in a separate repository, it can be built and dropped into the server profile immediately before the manage-profile tool is run. This process is part of the deployment automation logic that uses the server profile, and it can be followed for any files that are needed by the server profile but whose versions aren’t controlled.

For more information about the manage-profile tool, see About the manage-profile tool.

Variable substitution

You can use the manage-profile tool to substitute different variables in server profiles.

The manage-profile tool uses the format ${VARIABLE} to support the substitution of variables in profiles. This format can be escaped by using another $. For example, after substitution, $${VARIABLE} becomes ${VARIABLE}. Learn more by running bin/manage-profile --help.

Variable values can be read from a profile variables file or from environment variable values. If both options are used, the values that are specified in the file overwrite any environment variables.

The following code provides an example of how you can set user-defined variables by using a variables file in the server profile:

HOSTNAME=testserver.example.com
PORT=389

The following built-in variables can also be referenced in the server profile. Use these variables in the format previously described:

PING_SERVER_ROOT

Evaluates to the absolute path of the server’s root directory

PING_PROFILE_ROOT

Evaluates to the individual profile’s root directory

Use PING_PROFILE_ROOT only with files that aren’t needed after initial setup, such as password files in setup-arguments.txt. Don’t use the PING_PROFILE_ROOT variable for files needed while the server is running. The manage-profile tool creates a temporary copy of the server profile that gets deleted after the tool completes, so files aren’t accessible under PING_PROFILE_ROOT when the server is running. For files you need while the server is running, such as keystore and truststore files, copy the files into the server root using the profile’s server-root/pre-setup directory, and then refer to the files using the PING_SERVER_ROOT variable.

Profile structure

Use either of the following methods to create a server profile, adding files to each directory as needed:

Use the template named server-profile-template.zip, which is located in the resource directory.
Run the manage-profile generate-profile subcommand. The manage-profile tool references a file system directory structure rather than a .zip file.

The following hierarchy represents the file structure of a basic server PingDirectory profile:

-server-profile/
  |-- dsconfig/
  |-- ldif/
  |   |-- userRoot/
  |-- misc-files/
  |-- pre-setup-dsconfig/
  |-- server-root/
  |   |-- post-setup/
  |   |-- pre-setup/
  |-- server-sdk-extensions/
  |-- setup-arguments.txt
  |-- variables-ignore.txt

The pre-setup-dsconfig directory is only required when using a pre-existing encryption settings database.

The following hierarchy represents the file structure of a basic server PingDirectoryProxy or PingDataSync profile:

-server-profile/
  |-- dsconfig/
  |-- misc-files/
  |-- server-root/
  |   |-- post-setup/
  |   |-- pre-setup/
  |-- server-sdk-extensions/
  |-- setup-arguments.txt
  |-- variables-ignore.txt

`setup-arguments.txt`

When creating a profile, the first step is to add arguments to the setup-arguments.txt file, located in the resources/server-profile-template.zip file.

When you run the manage-profile setup command, these arguments are passed to the server’s setup tool. To view the arguments available in this file, run the server’s setup --help command.

To provide the equivalent, non-interactive command-line interface (CLI) arguments after any prompts have been completed, run setup interactively. The setup-arguments.txt file in the server profile template contains an example set of arguments that can be changed.

setup-arguments.txt is the only required file in the profile.

`dsconfig` and `pre-setup-dsconfig`

You can include dsconfig batch files in the server profile with information about changes to apply to the out-of-box system configuration. Any batch files in the server profile must include a .dsconfig extension. dsconfig batch files in the server profile can’t make changes to any topology configuration, including topology admins and server instances, so you should make topology configuration changes outside of the server profile.

If multiple batch files are present in the directory that the manage-profile tool is using, the files are processed in ascending lexicographic order. For example, 00-base.dsconfig is processed before 01-second.dsconfig.
You can use the config-diff tool to create a dsconfig batch file that reproduces the current topology configuration.

The batch files can be placed in the following server profile directories:

dsconfig: Contains information about changes to apply after the manage-profile tool runs setup, copies any post-setup files into place, and installs any Server SDK extensions contained in the server profile. The dsconfig directory should be used for most configuration changes applied to the server.
pre-setup-dsconfig (PingDirectory only): Holds information about changes to apply immediately before the manage-profile tool runs setup. You should only use the pre-setup-dsconfig directory when setting up the server with a pre-existing encryption settings database and applying the changes required for configuring and activating the cipher stream provider needed to access the encryption settings database.

server-root

Any server root files can be added to the server-root directory, including schema files, email template files, custom password dictionaries, and other files that must be present on the final server root. Add these files to the server-root/pre-setup or server-root/post-setup directory, depending on when they need to be copied to the server root. Most server root files are added to the server-root/pre-setup directory.

ldif

The following applies only to PingDirectory.

Use LDIF files in the server profile to supply a base DIT, but not to import user data. Add LDIF files under the ldif directory. Place each LDIF file in a subdirectory that indicates the backend to which it’s imported, such as ldif/userRoot for the userRoot backend.

LDIF files require an .ldif extension and are ordered lexicographically.

server-sdk-extensions

Add server SDK extension .zip files to the server-sdk-extensions directory. Include any configuration that’s necessary for the extensions in the profile’s dsconfig batch files.

variables-ignore.txt

The variables-ignore.txt file is an optional component of the server profile. It’s useful when adding bash scripts to the server root because such files often contain expressions that the manage-profile tool normally interprets as variables.

Add variables-ignore.txt to a profile’s root directory to indicate the relative paths of any files that aren’t to have their variables substituted.

The following example shows the contents of a typical variables-ignore.txt file:

server-root/pre-setup/script-to-ignore.sh
server-root/post-setup/another-file-to-ignore.txt

server-root/permissions.properties

The permissions.properties file, located in the server-root directory, is an optional file that specifies the permissions to apply to files that are copied to the server root. These permissions are represented in octal notation. By default, server root files maintain their permissions when copied.

The following example shows the contents of a typical permissions.properties file:

default=700
file-with-special-permissions.txt=600
new-subdirectory/file-with-special-permissions.txt=644
bin/example-script.sh=760

misc-files

Additional documentation and other files can be added to the misc-files directory, which the manage-profile tool doesn’t use. Use the variable PING_PROFILE_ROOT to refer to files in this directory from other locations, such as setup-arguments.txt.

For example, a password file named password.txt in the misc-files directory could be referenced with ${PING_PROFILE_ROOT}/misc-files/password.txt in setup-arguments.txt. Use a reference like this example to supply the file for the --rootUserPasswordFile argument in setup-arguments.txt.