--- title: Server profiles description: 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: component: pingdirectory version: 11.0 page_id: pingdirectory:pingdirectory_server_administration_guide:pd_ds_server_profiles canonical_url: https://docs.pingidentity.com/pingdirectory/11.0/pingdirectory_server_administration_guide/pd_ds_server_profiles.html revdate: September 13, 2023 page_aliases: ["pd_ds_variable_substitution.adoc", "pd_ds_profile_structure.adoc", "pd_ds_setup_arguments_txt.adoc", "pd_ds_dsconfig.adoc", "pd_ds_server_root.adoc", "pd_ds_ldif.adoc", "pd_ds_server_sdk_extentions.adoc", "pd_ds_variables_ignore_txt.adoc", "pd_ds_server_root_permissions_properties.adoc", "pd_ds_misc_files.adoc", "pingdirectoryproxy_server_administration_guide:pd_proxy_server_profiles.adoc", "pingdirectoryproxy_server_administration_guide:pd_proxy_variable_substitution.adoc", "pingdirectoryproxy_server_administration_guide:pd_proxy_profile_structure.adoc", "pingdirectoryproxy_server_administration_guide:pd_proxy_setup_arguments_txt.adoc", "pingdirectoryproxy_server_administration_guide:pd_proxy_dsconfig.adoc", "pingdirectoryproxy_server_administration_guide:pd_proxy_server_root.adoc", "pingdirectoryproxy_server_administration_guide:pd_proxy_server_sdk_extentions.adoc", "pingdirectoryproxy_server_administration_guide:pd_proxy_variables_ignore_txt.adoc", "pingdirectoryproxy_server_administration_guide:pd_proxy_server_root_permissions_properties.adoc", "pingdirectoryproxy_server_administration_guide:pd_proxy_misc_files.adoc", "pingdatasync_server_administration_guide:pd_sync_server_profiles.adoc", "pingdatasync_server_administration_guide:pd_sync_variable_substitution.adoc", "pingdatasync_server_administration_guide:pd_sync_profile_structure.adoc", "pingdatasync_server_administration_guide:pd_sync_setup_arguments_txt.adoc", "pingdatasync_server_administration_guide:pd_sync_dsconfig.adoc", "pingdatasync_server_administration_guide:pd_sync_server_root.adoc", "pingdatasync_server_administration_guide:pd_sync_server_sdk_extentions_devops.adoc", "pingdatasync_server_administration_guide:pd_sync_variables_ignore_txt.adoc", "pingdatasync_server_administration_guide:pd_sync_server_root_permissions_properties.adoc", "pingdatasync_server_administration_guide:pd_sync_misc_files.adoc"] section_ids: variable-substitution: Variable substitution profile-structure: Profile structure setup-arguments-txt: setup-arguments.txt dsconfig-pre-setup-dsconfig: dsconfig and pre-setup-dsconfig server-root: server-root ldif: ldif server-sdk-extensions: server-sdk-extensions variables-ignore-txt: variables-ignore.txt server-rootpermissions-properties: server-root/permissions.properties misc-files: misc-files --- # 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: ![An image that illustrates the role that a PingDirectory server profile plays in building a fully functional running server. It includes the server profile, topology information, data, and variables.](_images/uta1564011905287.png) The following image shows the role of a PingDirectoryProxy or PingDataSync server profile: ![An image that illustrates the role that a PingDirectoryProxy or PingDataSync server profile plays in building a fully functional running server. It includes the server profile, topology information, and variables.](_images/fkn1573504138722.png) > **Collapse: 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](#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](pd_ds_manage_profile_tool.html). ## 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](#dsconfig-pre-setup-dsconfig). | 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`. | | | | - | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | | 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. | 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`.