Ping Identity Documentation

https://docs.pingidentity.com
Admin
Ping Identity provides a comprehensive suite of identity and access management (IAM) solutions,...
Tokens:53,696,811
Snippets:284,376
Trust Score:9.9
Update:1 year ago
Show doc for...
Tokens:
Raw
### PingDirectory server-profiles setup-arguments.txt Example

Source: https://docs.pingidentity.com/pingdirectory/10.1/pingdatasync_server_administration_guide/pd_sync_logs_messages

Illustrates the format and content of the `setup-arguments.txt` file used with PingDirectory server profiles for automated setup. It specifies arguments for profile generation and server installation.

```properties
# PingDirectory server profile setup-arguments.txt

# Arguments for generate-profile command
--profileName=my-directory-profile
--include-server-root
--include-config-files

# Arguments for setup command (when applying the profile)
--acceptLicense
--nodeps
--profileLocation=/path/to/profiles/my-directory-profile
--rootUserDN="cn=Directory Manager"
--rootUserPassword=password123

```

--------------------------------

### Configuration API GET Example

Source: https://docs.pingidentity.com/pingdirectory/10.1/installing_the_pingdirectory_suite_of_products/pd_ds_download_install_packages

Demonstrates a GET request example for the Configuration API, used for retrieving configuration data from the PingDirectory or PingDirectoryProxy server.

```bash
# GET example
curl -X GET "https://<host>:<port>/<api-version>/config/servers/<server-id>" -H "Accept: application/json" -u <username>:<password>
```

--------------------------------

### Configuration API Examples (GET, POST, PATCH)

Source: https://docs.pingidentity.com/pingdirectory/9.3/pingdirectory_security_guide/pd_sec_managing_pw_policy_state

Provides examples for interacting with the Configuration API, demonstrating GET, GET list, and PATCH operations. These examples illustrate how to retrieve, list, and update configuration objects within the PingDirectory environment.

```shell
curl -X GET \
  https://{server-host}:{port}/admin/v1/config/servers/02f7526a-38c8-428f-9874-c6076090470e \
  -u "admin:adminPassword"
```

```shell
curl -X GET \
  https://{server-host}:{port}/admin/v1/config/servers \
  -u "admin:adminPassword"
```

```shell
curl -X PATCH \
  https://{server-host}:{port}/admin/v1/config/servers/02f7526a-38c8-428f-9874-c6076090470e \
  -u "admin:adminPassword" \
  -H "Content-Type: application/json" \
  -d '{
    "listenPort": 8080
  }'
```

--------------------------------

### Setup Arguments File Example (setup-arguments.txt)

Source: https://docs.pingidentity.com/pingdirectory/10.1/troubleshooting_the_pingdirectory_suite_of_products/pd_sync_synchronize_troubleshooting

Illustrates the `setup-arguments.txt` file, used for non-interactive server setup. It contains parameters that would typically be provided on the command line during the initial server configuration.

```Properties
# Example setup-arguments.txt file

# Directory Server Settings
directory-port=389
directory-ssl-port=636
admin-port=4444
root-dn=cn=Directory Manager
root-password=password

# Backend Configuration
backend-id=userroot
backend-base-dn=dc=example,dc=com

```

--------------------------------

### AM Configurator Tool Output Example

Source: https://docs.pingidentity.com/pingam/7.5/install-guide/silent-install

This is an example output from the AM configurator tool during a silent installation. It shows the progression of setup steps, including license acceptance, configuration store initialization, OpenDJ setup, and final configuration completion.

```bash
java -jar openam-configurator-tool-14.1.3.30.jar --file config.properties
Checking license acceptance…License terms accepted.
Checking configuration directory /home/openam….Success.
Installing OpenAM configuration store…Success RSA/ECB/OAEPWithSHA1AndMGF1…
Extracting OpenDJ, please wait…Complete
Running OpenDJ setupSetup command: --cli --adminConnectorPort 4444
--baseDN dc=openam,dc=forgerock,dc=org --rootUserDN uid=admin
--ldapPort 50389 --skipPortCheck --rootUserPassword xxxxxxx --jmxPort 1689
--no-prompt --doNotStart --hostname openam.example.com …
…Success
Installing OpenAM configuration store in /home/openam/… …Success.
Creating OpenAM suffixImport+task+ … …Success
Tag swapping schema files….Success.
Loading Schema opendj_config_schema.ldif…Success.

…

…Success.
Reinitializing system properties….Done
Registering service dashboardService.xml…Success.

…

Configuring system….Done
Configuring server instance….Done
Creating demo user….Done
Creating Web Service Security Agents….Done
Setting up monitoring authentication file.
Configuration complete!
```

--------------------------------

### Display Setup Tool Help Options

Source: https://docs.pingidentity.com/pingauthorize/10.3/installing_and_uninstalling_pingauthorize/paz_install_server_manually

This command displays all available options and examples for the `setup` tool, useful for understanding configuration parameters for non-interactive installation.

```shell
$ ./setup --help
```

--------------------------------

### Server Profiles: setup-arguments.txt Example

Source: https://docs.pingidentity.com/pingdirectory/10.1/pingdirectoryproxy_server_administration_guide/pd_proxy_ldap_ext_servers

An example of the `setup-arguments.txt` file used within server profiles. This file defines arguments passed to the setup process, enabling automated and customized server deployments.

```plaintext
# Example setup-arguments.txt
--adminUID admin
--adminPassword password
--replication-port 8989
--port 389
```

--------------------------------

### Use sample applications with QuickStart

Source: https://docs.pingidentity.com/pingaccess/8.0/pingaccess_user_interface_reference_guide/pa_application_resources

Demonstrates the usage of sample applications provided with the PingAccess QuickStart utility to test integrations and configurations.

```text
Using sample applications
```

--------------------------------

### Non-interactive PingAuthorize Server Setup Example

Source: https://docs.pingidentity.com/pingauthorize/10.3/installing_and_uninstalling_pingauthorize/paz_install_server_manually

This example demonstrates a non-interactive installation of PingAuthorize Server with specific configurations including license, administrative credentials, ports, self-signed certificate generation, JVM memory allocation, instance name, and location. It utilizes the `--cli`, `--no-prompt`, and `--acceptLicense` flags for automated setup.

```shell
$ ./setup \
  --cli --no-prompt --acceptLicense \
  --licenseKeyFile  _<path-to-license>_  \
  --rootUserDN "cn=directory manager" \
  --rootUserPassword  _<your-password>_  \
  --ldapPort 8389 --ldapsPort 8636 \
  --httpsPort 8443 \
  --generateSelfSignedCertificate \
  --maxHeapSize 1g \
  --instanceName pingauthorize1 \
  --location Austin
```

--------------------------------

### Non-Interactive PingAuthorize Server Setup Example

Source: https://docs.pingidentity.com/pingauthorize/10.1/installing_and_uninstalling_pingauthorize/paz_install_server_manually

This example demonstrates a non-interactive setup of PingAuthorize Server using various command-line arguments. It specifies ports, license, administrative credentials, certificate generation, JVM memory, instance name, and server location.

```shell
./setup \
  --cli --no-prompt --acceptLicense \
  --licenseKeyFile  _<path-to-license>_  \
  --rootUserDN "cn=directory manager" \
  --rootUserPassword  _<your-password>_  \
  --ldapPort 8389 --ldapsPort 8636 \
  --httpsPort 8443 \
  --generateSelfSignedCertificate \
  --maxHeapSize 1g \
  --instanceName pingauthorize1 \
  --location Austin
```

--------------------------------

### Server profiles setup-arguments.txt example

Source: https://docs.pingidentity.com/pingdirectory/10.1/pingdirectory_server_administration_guide/pd_ds_move_restore_user_database

An example of the `setup-arguments.txt` file used for server profiles. This file contains arguments passed to the setup command, enabling automated server configuration.

```properties
# Arguments for PingDirectory setup
port=389
ldaps-port=636
admin-port=4444
root-dn=cn=Directory Manager
root-password=password123
ldif-file=/path/to/initial_data.ldif
```

--------------------------------

### Deploying a Standard PingDirectoryProxy Server

Source: https://docs.pingidentity.com/pingdirectory/10.2/installing_the_pingdirectory_suite_of_products/pd_da_install_application

Step-by-step guide for deploying a standard PingDirectoryProxy server, covering initial setup, configuration, and testing.

```APIDOC
## Deploying a Standard PingDirectoryProxy Server

### Description

This section outlines the process for deploying a standard PingDirectoryProxy server, including automatic server discovery, multi-location deployments, and testing procedures.

### Method

Installation and Configuration Scripts

### Endpoint

N/A

### Parameters

#### Automatic Server Discovery

- **`--discovery`** (Boolean) - Enables automatic server discovery.
- **`--topology-url`** (URL) - URL of the existing PingDirectory server topology.

#### Multi-location Deployment Steps

1. Install the first PingDirectoryProxy server.
2. Configure the first PingDirectoryProxy server.
3. Define locations.
4. Configure external servers for specified locations.
5. Apply the configuration.
6. Configure additional PingDirectoryProxy server instances.

### Request Example (Joining existing topology)

```bash
<path-to-your-install>/bin/dsconfig create-tool-config --tool PingDirectoryProxy --discovery true --topology-url ldap://existing-dc1:389
```

### Response

N/A (Deployment involves server-side configuration and setup.)
```

--------------------------------

### Display Setup Tool Help Options

Source: https://docs.pingidentity.com/pingauthorize/10.2/installing_and_uninstalling_pingauthorize/paz_install_server_manually

This command displays all available options and examples for the 'setup' tool, allowing users to understand the full range of configuration possibilities for non-interactive installation. No specific output is shown here, but it's crucial for discovering all parameters.

```shell
# Display all available setup options and examples
./setup --help
```

--------------------------------

### Deploying PingDirectoryProxy Server - Initial Setup Example

Source: https://docs.pingidentity.com/pingdirectory/10.3/pingdirectory_server_administration_guide/pd_ds_set_up_initial_topology

Outlines the initial steps and commands for deploying a standard PingDirectoryProxy server. This includes automatic server discovery and basic configuration.

```shell
# Example: Installing the first PingDirectoryProxy server
/path/to/install/pingdirectory/bin/install.sh ...

# Example: Configuring the first PingDirectoryProxy server
dsconfig --no-prompt --add-server-group my-server-group --set enabled=true ...
```

--------------------------------

### PingDirectory Configuration API GET Example

Source: https://docs.pingidentity.com/pingdirectory/10.3/managing_servers_and_certificates/pd_ds_troubleshoot_tls_related_issues

This snippet provides an example of using the Configuration API to retrieve configuration details for a PingDirectory server. It demonstrates a GET request to fetch specific configuration objects, which is essential for auditing, monitoring, and understanding the current server setup.

```bash
# Example: Using curl to get server group configuration
curl -X GET "https://localhost:8080/api/v1/server-groups/default-group" \
     -H "Accept: application/json" \
     -u "admin@example.com:password" \
     --cacert /path/to/server.crt
```

--------------------------------

### Display Setup Tool Help and Options

Source: https://docs.pingidentity.com/pingauthorize/10.1/installing_and_uninstalling_pingauthorize/paz_install_server_manually

This command displays the help information for the 'setup' tool, listing all available command-line options and providing usage examples. This is useful for understanding the full range of configuration possibilities.

```shell
./setup --help
```

--------------------------------

### setup-arguments.txt Example for Server Profiles

Source: https://docs.pingidentity.com/pingdirectory/10.1/pingdirectoryproxy_server_administration_guide/pd_proxy_create_global_attribute_index

This example shows the content of a `setup-arguments.txt` file, which is used in conjunction with server profiles for automated PingDirectory server setup. It specifies arguments passed to the setup process.

```text
# Example setup-arguments.txt

# Base DN for the user root
--set user-root/base-dn:dc=example,dc=com

# Admin user's password (sensitive, often handled via secure means)
# --admin-user-password "yourSecurePassword"

# Enable specific features
--enable-feature "replication"
--set replication/initial-topology-data-path:replication-data.zip
```

--------------------------------

### GET /config Example

Source: https://docs.pingidentity.com/pingdirectory/10.1/pingdirectoryproxy_server_administration_guide/pd_proxy_monitor_size_global_indexes

Example of retrieving configuration objects using the GET method.

```APIDOC
## GET /config Example

### Description
Retrieves a list of configuration objects.

### Method
GET

### Endpoint
`/config`

### Parameters
#### Path Parameters
None

#### Query Parameters
- **filter** (string) - Optional - Filters the results.
- **sort** (string) - Optional - Sorts the results.

### Request Example
```
GET /config?filter=enabled%3Dtrue HTTP/1.1
Host: localhost:8080
```

### Response
#### Success Response (200)
- **data** (array) - A list of configuration objects.
- **totalResults** (integer) - The total number of results.

#### Response Example
```json
{
  "data": [
    {
      "urn:pingidentity:proxy:config:httphandler:1.0:httphandler": {
        "name": "default-http-handler",
        "enabled": true
      }
    }
  ],
  "totalResults": 1
}
```
```

--------------------------------

### PingAccess QuickStart Utility Usage

Source: https://docs.pingidentity.com/pingaccess/7.2/release_notes/pa_release_notes

Guide for using the PingAccess QuickStart utility, covering installation, configuration, connection to PingAccess and PingFederate, and usage of sample applications. It also includes instructions for restoring PingFederate or PingAccess.

```plaintext
Installing and configuring QuickStart components
Connecting the QuickStart utility to PingAccess and PingFederate
Using sample applications
Restoring PingFederate or PingAccess
```

--------------------------------

### Deploying a Standard PingDirectoryProxy Server - Initial Setup

Source: https://docs.pingidentity.com/pingdirectory/10.2/pingdirectory_server_administration_guide/pd_ds_backup_restore_data

Overview of the steps involved in installing and configuring the first PingDirectoryProxy server in a standard deployment.

```APIDOC
## Initial PingDirectoryProxy Server Deployment

### Description
This section outlines the initial steps for deploying a standard PingDirectoryProxy server, including installation and basic configuration.

### Overview of Deployment Steps:

1.  **Install PingDirectoryProxy Server**: Download and install the PingDirectoryProxy server software on your target machine.
2.  **Run `create-initial-proxy-config` tool**: Use this tool to generate the initial configuration files for the proxy server.
3.  **Configure Standard PingDirectoryProxy Server Deployment**: Proceed with detailed configuration using `dsconfig` or the Configuration API.

### Installing the First PingDirectoryProxy Server:

- Follow the installation guide specific to your operating system.
- Ensure all prerequisites are met, including Java runtime environment.

### Configuring the First PingDirectoryProxy Server:

- **Using `create-initial-proxy-config`**: This tool assists in setting up the fundamental proxy configuration.
  - `Tools/create-initial-proxy-config --propertiesFile /path/to/proxy.properties`
- **Using `dsconfig`**: Once the initial setup is done, use `dsconfig` for further configuration.
  - Interactive mode: `dsconfig`
  - Non-interactive mode: `dsconfig set-proxy-server-group-prop ...`
- **Using Configuration API**: For automated deployments, leverage the Configuration API endpoints.

### Defining Locations:

- Use `dsconfig` or the Configuration API to define logical locations for your backend PingDirectory servers (e.g., 'east', 'west').
  - `dsconfig create-location --name east --set "description:East Coast Servers"`

### Configuring External Servers:

- Define templates for your backend PingDirectory servers.
  - `dsconfig create-ldap-external-server-template --name "pingdirectory-template" ...`
- Associate these templates with specific locations and configure load balancing algorithms.
  - `dsconfig create-load-balancing-algorithm --name "round-robin" ...`
  - `dsconfig set-location-prop --name east --set "load-balancing-algorithm:round-robin"`

### Applying Configuration:

- Ensure the configuration is applied to the PingDirectoryProxy server instance.

### Next Steps:

- Configure additional PingDirectoryProxy server instances if building a clustered environment.
- Test external server communications and simulate failures.
```

--------------------------------

### Configuration API - GET Example

Source: https://docs.pingidentity.com/pingdirectory/10.3/delegated_admin_application_guide/pd_da_generic_resource_types

Provides an example of how to make a GET request to the Configuration API.

```APIDOC
## GET /api/config

### Description
Retrieves a specific configuration object or a list of configuration objects.

### Method
GET

### Endpoint
/api/config

### Parameters
#### Query Parameters
- **filter** (string) - Optional - Filters the results based on specified criteria.
- **sort** (string) - Optional - Sorts the results by a specified field.

### Request Example
```json
{
  "example": "GET /api/config?filter=objectClass:inetOrgPerson&sort=cn"
}
```

### Response
#### Success Response (200)
- **result** (array) - A list of configuration objects matching the filter.

#### Response Example
```json
{
  "example": {
    "result": [
      {
        "dn": "cn=example,ou=users,dc=example,dc=com",
        "uid": "exampleUser"
      }
    ]
  }
}
```
```

--------------------------------

### Configuration API Examples (GET, GET List, PATCH)

Source: https://docs.pingidentity.com/pingdirectory/9.3/pingdirectory_security_guide/pd_sec_supported_password_vals

Examples demonstrating how to interact with the PingDirectory Configuration API using GET, GET list, and PATCH operations. These examples are useful for automating server configuration and retrieving data.

```shell
curl -X GET https://<server-host>:<port>/<api-version>/config --user <username>:<password>

```

```shell
curl -X GET https://<server-host>:<port>/<api-version>/config/server-group --user <username>:<password>

```

```shell
curl -X PATCH https://<server-host>:<port>/<api-version>/config/server-group/<group-name> --user <username>:<password> -d '{"description": "Updated server group description"}'

```

--------------------------------

### Install and configure QuickStart components

Source: https://docs.pingidentity.com/pingaccess/8.0/pingaccess_user_interface_reference_guide/pa_application_resources

Installs and configures the necessary components for the PingAccess QuickStart utility, preparing it for integration testing.

```text
Installing and configuring QuickStart components
```

--------------------------------

### PingDataMetrics Configuration API Examples (GET, GET list, PATCH)

Source: https://docs.pingidentity.com/pingdirectory/9.3/pingdirectory_server_administration_guide/pd_ds_server_root_permissions_properties

Examples demonstrating how to interact with the PingDataMetrics Configuration API using GET, GET list, and PATCH operations. These examples show how to retrieve, list, and update configuration objects.

```bash
# GET example
curl -X GET "https://localhost:8443/config/servers/my_server" \
  --user user:password \
  -H "Content-Type: application/json"
```

```bash
# GET list example
curl -X GET "https://localhost:8443/config/alert-handlers?filter=enabled eq true" \
  --user user:password \
  -H "Content-Type: application/json"
```

```bash
# PATCH example
curl -X PATCH "https://localhost:8443/config/log-publishers/my_log_publisher" \
  --user user:password \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": false
  }'
```

--------------------------------

### Run PingIDM Sample Configuration

Source: https://docs.pingidentity.com/pingidm/7.2/samples-guide/start-here

This command starts an instance of PingIDM using a specified sample configuration. Ensure you replace `/path/to/openidm` with the actual path to your IDM installation and `sample-name` with the desired sample directory.

```bash
cd /path/to/openidm
./startup -p samples/sample-name
```

--------------------------------

### Configuration API Examples (GET, GET List, PATCH)

Source: https://docs.pingidentity.com/pingdirectory/9.3/pingdirectoryproxy_server_administration_guide/pd_proxy_config_locations

Examples demonstrating how to interact with the Configuration API for retrieving and updating server configurations. These examples showcase GET, GET list, and PATCH operations, with specific API paths and sorting/filtering capabilities.

```bash
curl -X GET "https://your-server.com/config/api/v1/servers/server1"
curl -X GET "https://your-server.com/config/api/v1/servers?filter=enabled+eq+true&sort=name:ascending"
curl -X PATCH "https://your-server.com/config/api/v1/servers/server1" -H "Content-Type: application/json" -d '{"listenPort": 8080}'
```

--------------------------------

### Configuration API Examples (GET, GET List, PATCH)

Source: https://docs.pingidentity.com/pingdirectory/9.3/pingdirectoryproxy_server_administration_guide/pd_proxy_apply_config_to_dps

Examples demonstrating how to interact with the PingDataMetrics Configuration API using GET, GET list, and PATCH operations. These examples illustrate common use cases for retrieving and modifying server configurations.

```shell
# GET example
curl -X GET https://your-ds-host:8080/manage/config/api/config/serverGroup/default -H "ds-token: YOUR_API_TOKEN"

# GET list example
curl -X GET https://your-ds-host:8080/manage/api/config/servers -H "ds-token: YOUR_API_TOKEN"

# PATCH example
curl -X PATCH https://your-ds-host:8080/manage/api/config/servers/server1 -H "ds-token: YOUR_API_TOKEN" -d '{"description": "Updated server description"}'
```

--------------------------------

### Deploying a Standard PingDirectoryProxy Server

Source: https://docs.pingidentity.com/pingdirectory/10.2/installing_the_pingdirectory_suite_of_products/pd_ds_before_you_begin_install

Step-by-step guide for deploying a standard multi-location PingDirectoryProxy server environment, including automatic server discovery and setup.

```APIDOC
## Deploying a Standard PingDirectoryProxy Server

### Description
This section outlines the process for deploying a standard multi-location PingDirectoryProxy server. It includes initial setup, configuration, and testing steps.

### Overview
1. Install the first PingDirectoryProxy server.
2. Configure the first PingDirectoryProxy server.
3. Define locations.
4. Configure external servers.
5. Apply configuration.
6. Configure additional PingDirectoryProxy server instances.
7. Test communication and failure scenarios.

### Steps
#### Installing the first PingDirectoryProxy server
- Follow the standard installation procedures for PingDirectoryProxy.

#### Configuring the first PingDirectoryProxy server
- Use `dsconfig` or the Configuration API to set up initial parameters, including:
  - Network listen ports
  - Security settings
  - Backend server definitions

#### Defining Locations
- Configure the geographical or logical locations for your servers using `dsconfig` or the Configuration API.

#### Configuring External Servers
- Create and configure external server templates and definitions using `dsconfig` or the Configuration API, specifying:
  - Server addresses
  - Load-balancing algorithms
  - Health check configurations

#### Applying Configuration
- Ensure all configurations are applied to the PingDirectoryProxy server instances.

#### Configuring Additional PingDirectoryProxy Server Instances
- Repeat installation and configuration steps for additional servers to expand the deployment.

#### Testing
- Test external server communications.
- Simulate external server failures to verify failover mechanisms.
```

--------------------------------

### Use Configuration API Examples (GET, GET list, PATCH)

Source: https://docs.pingidentity.com/pingdirectory/9.3/pingdirectory_server_administration_guide/pd_ds_sign_on_admin_console

Examples demonstrating how to interact with the PingDataMetrics server's configuration API using GET, GET list, and PATCH operations. These examples show how to retrieve and modify server configurations.

```shell
# GET example
curl -X GET https://localhost:8080/api/config/servers/server1

# GET list example
curl -X GET https://localhost:8080/api/config/servers

# PATCH example
curl -X PATCH https://localhost:8080/api/config/servers/server1 \
-H "Content-Type: application/json" \
-d '{"listenPort": 8081}'
```

--------------------------------

### Example Output of Docker Image Installation

Source: https://docs.pingidentity.com/pingintelligence/5.2/installing_pingintelligence_for_apis/pingintelligence_install_docker_images

This example demonstrates the expected output after running the `sudo ./bin/start.sh install` command. It shows the sequential loading of various PingIntelligence Docker images, including their versions, and confirms successful installation.

```text
Tue Dec 28 01:59:50 MST 2021 : loading ASE image
Loaded image: pingidentity/ase:5.1
Tue Dec 28 01:59:54 MST 2021 : loading ABS image
Loaded image: pingidentity/abs:5.1
Tue Dec 28 02:00:03 MST 2021 : loading API Publish image
Loaded image: pingidentity/apipublish:5.1
Tue Dec 28 02:00:11 MST 2021 : loading Dashboard image
Loaded image: pingidentity/dashboard:5.1
Tue Dec 28 02:00:43 MST 2021 : loading mongo image
Loaded image: pingidentity/mongo:4.2.0
Tue Dec 28 02:00:50 MST 2021 : loading Kafka image
Loaded image: pingidentity/kafka:5.1
Tue Dec 28 02:01:07 MST 2021 : loading Zookeeper image
Loaded image: pingidentity/zookeeper:5.1
Tue Dec 28 02:01:18 MST 2021 : loading client image
Loaded image: pingidentity/client:5.1
Tue Dec 28 02:01:25 MST 2021 : loading server image
Loaded image: pingidentity/server:5.1
Tue Dec 28 02:01:32 MST 2021 : Installation completed successfully
```

--------------------------------

### Configuration API Examples

Source: https://docs.pingidentity.com/pingdirectory/10.3/installing_the_pingdirectory_suite_of_products/pd_sync_installing_pds

Examples demonstrating how to interact with the Configuration API, including GET and PATCH operations.

```APIDOC
## GET /config/objects/{objectType}/{objectName}

### Description
Retrieves a specific configuration object.

### Method
GET

### Endpoint
/config/objects/{objectType}/{objectName}

### Parameters
#### Path Parameters
- **objectType** (string) - Required - The type of the configuration object.
- **objectName** (string) - Required - The name of the configuration object.

### Response
#### Success Response (200)
- **object** (object) - The configuration object details.

### Response Example
{
  "example": "{\"last-modified\": \"2023-10-27T10:00:00Z\", \"description\": \"Example configuration object\"}"
}

## GET /config/objects/{objectType}

### Description
Retrieves a list of configuration objects of a specified type.

### Method
GET

### Endpoint
/config/objects/{objectType}

### Parameters
#### Path Parameters
- **objectType** (string) - Required - The type of configuration objects to list.

### Response
#### Success Response (200)
- **objects** (array) - A list of configuration objects.

### Response Example
{
  "example": "{\"items\": [{\"objectName\": \"config1\"}, {\"objectName\": \"config2\"}]}"
}

## PATCH /config/objects/{objectType}/{objectName}

### Description
Updates properties of an existing configuration object.

### Method
PATCH

### Endpoint
/config/objects/{objectType}/{objectName}

### Parameters
#### Path Parameters
- **objectType** (string) - Required - The type of the configuration object.
- **objectName** (string) - Required - The name of the configuration object.

#### Request Body
- **properties** (object) - Required - A map of property names to their new values.

### Request Example
{
  "example": "{\"properties\": {\"description\": \"Updated description\"}}"
}

### Response
#### Success Response (200)
- **last-modified** (string) - The timestamp of the last modification.

### Response Example
{
  "example": "{\"last-modified\": \"2023-10-27T10:05:00Z\"}"
}

```

--------------------------------

### GET /config/backends/userRoot Example

Source: https://docs.pingidentity.com/pingdirectory/10.1/pingdirectoryproxy_server_administration_guide/pd_proxy_get_example

This section provides an example of a GET request and response for retrieving information about the userRoot backend.

```APIDOC
## GET /config/backends/userRoot

### Description
Retrieves information about the `userRoot` backend configuration.

### Method
GET

### Endpoint
/config/backends/userRoot

### Parameters

#### Query Parameters
- **Accept** (string) - Required - Specifies the desired response format, e.g., `application/scim+json`.

### Request Example
```
GET /config/backends/userRoot
Host: example.com:5033
Accept: application/scim+json
```

### Response
#### Success Response (200)
- **backendID** (string) - The unique identifier for the backend.
- **baseDN** (string) - The base distinguished name for the backend.
- **enabled** (boolean) - Indicates if the backend is enabled.
- **description** (string) - A description of the backend.

#### Response Example
```json
{
  "backendID": "userRoot",
  "baseDN": "dc=example,dc=com",
  "enabled": true,
  "description": "Primary user data backend"
}
```
```

--------------------------------

### Non-interactive PingAuthorize Server Setup Example

Source: https://docs.pingidentity.com/pingauthorize/10.2/installing_and_uninstalling_pingauthorize/paz_install_server_manually

This example demonstrates a non-interactive setup for PingAuthorize Server, including essential configurations like license acceptance, administrative credentials, network ports (LDAP, LDAPS, HTTPS), certificate generation, JVM heap size, instance name, and server location. It utilizes command-line arguments to bypass prompts.

```shell
# Non-interactive setup with specified ports, self-signed certificate, JVM memory, instance name, and location
./setup \
  --cli --no-prompt --acceptLicense \
  --licenseKeyFile  _<path-to-license>_  \
  --rootUserDN "cn=directory manager" \
  --rootUserPassword  _<your-password>_  \
  --ldapPort 8389 --ldapsPort 8636 \
  --httpsPort 8443 \
  --generateSelfSignedCertificate \
  --maxHeapSize 1g \
  --instanceName pingauthorize1 \
  --location Austin
```

--------------------------------

### Configuration API - Specific Examples

Source: https://docs.pingidentity.com/pingdirectory/9.3/installing_the_pingdirectory_suite_of_products/pd_da_install_application

Illustrative examples for specific administrative actions and configurations using the Configuration API.

```APIDOC
## POST /api/config/servers/{id}/actions/update

### Description
Initiates an update for a specific server.

### Method
POST

### Endpoint
`/api/config/servers/{id}/actions/update`

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the server to update.

### Response
#### Success Response (200)
- **status** (string) - The status of the update action.

### Response Example
```json
{
  "status": "Update initiated."
}
```

## POST /api/config/serverGroups/{id}/actions/update

### Description
Initiates an update for a specific server group.

### Method
POST

### Endpoint
`/api/config/serverGroups/{id}/actions/update`

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the server group to update.

### Response
#### Success Response (200)
- **status** (string) - The status of the update action.

### Response Example
```json
{
  "status": "Update initiated."
}
```
```

--------------------------------

### Configuration API GET List Example

Source: https://docs.pingidentity.com/pingdirectory/10.1/pingdirectory_server_administration_guide/pd_ds_submapping_element

This example demonstrates how to use the Configuration API to retrieve a list of configuration objects, such as all configured servers. This is useful for auditing and understanding the current server setup. The API supports filtering and sorting of results.

```http
GET /config/servers HTTP/1.1
Host: localhost:8080
Authorization: Basic YWxhZGRpbjpvcGVuc2VzYW1l
Accept: application/json
```

--------------------------------

### Configuration API GET Example

Source: https://docs.pingidentity.com/pingdirectory/9.3/installing_the_pingdirectory_suite_of_products/pd_da_preparing_install

This example demonstrates how to use the Configuration API to retrieve configuration data. It shows a sample GET request to fetch specific configuration details.

```http
GET /config/v1/servers/1 HTTP/1.1
Host: localhost:8443
Authorization: Basic BASE64_ENCODED_CREDENTIALS
```

--------------------------------

### Standard Deployment Steps

Source: https://docs.pingidentity.com/pingdirectory/10.2/pingdatasync_server_administration_guide/pd_sync_create_log_publisher

Outlines the steps for deploying a standard PingDirectoryProxy server, including initial setup, server discovery, and configuration.

```APIDOC
## Standard PingDirectoryProxy Server Deployment

### Description
This section details the process of deploying a standard PingDirectoryProxy server, from initial installation to configuring multiple instances and locations.

### Method
Installation and `dsconfig` commands, Configuration API

### Endpoint
N/A

### Steps
1.  **Install the first PingDirectoryProxy server**.
2.  **Configure the first PingDirectoryProxy server** using `dsconfig` or Configuration API.
3.  **Define locations** for your deployment.
4.  **Configure external servers** in different locations.
5.  **Apply the configuration** to the PingDirectoryProxy server.
6.  **Configure additional PingDirectoryProxy server instances**.
7.  **Test** server communications and simulated failures.

### Request Example (Conceptual dsconfig command for initial setup)
```bash
dsconfig create-server --host <host> --port <port> --admin-port <admin_port>
```

### Response
#### Success Response
- Server deployed and configured.

#### Response Example
- Successful execution of installation and configuration commands.
```

--------------------------------

### Noninteractive PingAuthorize Server Installation Setup

Source: https://docs.pingidentity.com/pingauthorize/10.2/installing_and_uninstalling_pingauthorize/paz_install_server_manually

Illustrates the command structure for running the 'setup' tool in noninteractive mode. This is used for automated installations via setup scripts, requiring specific arguments instead of interactive prompts.

```shell
# Example for noninteractive setup (arguments not shown, but would be included here)
./setup --no-prompt [other_required_arguments]
```

--------------------------------

### Configuration API - GET Example

Source: https://docs.pingidentity.com/pingdirectory/9.3/pingdirectory_server_administration_guide/pd_ds_encryption_settings_tool

Provides an example of how to use the GET method with the Configuration API to retrieve configuration details.

```APIDOC
## GET /config

### Description
Retrieves configuration details for a specific object or a list of objects.

### Method
GET

### Endpoint
/config

### Parameters
#### Query Parameters
- **filter** (string) - Optional - Filters the results based on specified criteria.
- **sort** (string) - Optional - Sorts the results.

### Request Example
```json
{
  "example": "GET /config?filter=eq(objectClass,inetorgperson)"
}
```

### Response
#### Success Response (200)
- **data** (array) - An array of configuration objects.
- **totalCount** (integer) - The total number of matching configuration objects.

#### Response Example
```json
{
  "example": {
    "data": [
      {
        "dn": "cn=user,ou=users,dc=example,dc=com",
        "objectClass": "inetorgperson",
        "uid": "user1"
      }
    ],
    "totalCount": 1
  }
}
```
```

--------------------------------

### Initial Setup of PingDirectory Instance

Source: https://docs.pingidentity.com/pingdirectory/10.2/pingdirectoryproxy_server_administration_guide/pd_proxy_join_dps_existing_ds_topology

This command initiates the setup process for a PingDirectory instance, accepting license, specifying heap size, hostnames, ports, and security configurations. It requires license key file, password files, and keystore/truststore information.

```shell
$ ./setup --acceptLicense \
     --licenseKeyFile PingDirectory.lic\
     --maxHeapSize 2g \
     --localHostName proxy2.example.com \
     --skipHostnameCheck \
     --instanceName proxy2 \
     --location Austin \
     --rootUserDN "cn=Directory Manager" \
     --rootUserPasswordFile directory-manager-password.txt \
     --ldapPort 389 \
     --ldapsPort 636 \
     --httpsPort 443 \
     --enableStartTLS \
     --useJavaKeyStore config/keystore \
     --keyStorePasswordFile config/keystore.pin \
     --certNickname server-cert \
     --useJavaTrustStore config/truststore \
     --trustStorePasswordFile config/truststore.pin \
     --encryptDataWithPassphraseFromFile encryption-passphrase.txt \
     --peerHostName proxy1.example.com \
     --peerPort 636 \
     --peerUseSSL \
     --no-prompt
```

--------------------------------

### GET Example - Configuration API

Source: https://docs.pingidentity.com/pingdirectory/10.1/pingdirectoryproxy_server_administration_guide/pd_proxy_move_subtree_tool

Example of how to retrieve a specific configuration object using the GET method with the Configuration API.

```APIDOC
## GET /config/{configID}

### Description
Retrieves a specific configuration object.

### Method
GET

### Endpoint
`/config/{configID}`

### Parameters
#### Path Parameters
- **configID** (string) - Required - The identifier of the configuration object to retrieve.

#### Query Parameters
N/A

#### Request Body
N/A

### Request Example
N/A

### Response
#### Success Response (200)
- **configurationObject** (object) - The retrieved configuration object.

#### Response Example
```json
{
  "dn": "cn=example,cn=config",
  "objectClass": "configObject"
}
```
```

--------------------------------

### Configuration API - GET Example

Source: https://docs.pingidentity.com/pingdirectory/10.3/installing_the_pingdirectory_suite_of_products/pd_da_install_application

Demonstrates how to retrieve configuration using the Configuration API.

```APIDOC
## GET /config

### Description
Retrieves a specific configuration object or a list of configuration objects.

### Method
GET

### Endpoint
/config

### Parameters
#### Query Parameters
- **filter** (string) - Optional - Filters the results based on specified criteria.
- **view** (string) - Optional - Specifies the view of the configuration object to retrieve.

### Request Example
```json
{
  "example": "GET /config?filter=eq(objectClass,inetorgperson)"
}
```

### Response
#### Success Response (200)
- **result** (array) - An array of configuration objects matching the filter.

#### Response Example
```json
{
  "example": "{
  \"result\": [
    {
      \"id\": \"cn=read only,ou=groups,dc=example,dc=com\",
      \"schemas\": [\"urn:pingidentity:schemas:configuration:2.0\"],
      \"objectClass\": [\"groupofuniquenames\", \"top\"]
    }
  ]
}"
}
```
```

--------------------------------

### GET Example for Configuration API

Source: https://docs.pingidentity.com/pingdirectory/10.1/pingdirectory_security_guide/pd_sec_ldap_simple_authn

Example demonstrating how to retrieve configuration details using the GET method of the Configuration API.

```APIDOC
## GET Example for Configuration API

### Description
This example shows how to fetch configuration details for a specific component or the entire server using the GET endpoint of the Configuration API.

### Method
GET

### Endpoint
/config/{componentPath}

### Parameters
#### Path Parameters
- **componentPath** (string) - Required - The path to the configuration component to retrieve.

#### Query Parameters
- **filter** (string) - Optional - Filter for sorting and filtering objects.
- **sortBy** (string) - Optional - Specifies the property to sort objects by.

### Request Example
```http
GET /config/servers/my-proxy-server
```

### Response
#### Success Response (200)
- **componentData** (object) - The retrieved configuration data for the specified component.

#### Response Example
```json
{
  "componentData": {
    "listenPort": 8080,
    "sslEnabled": true
  }
}
```
```

--------------------------------

### GET Example - Configuration API

Source: https://docs.pingidentity.com/pingdirectory/10.1/pingdirectory_security_guide/pd_sec_aggregate_request_criteria

Example demonstrating how to retrieve configuration information using the GET method with the Configuration API.

```APIDOC
## GET Example - Configuration API

### Description
This example shows a GET request to retrieve a specific configuration object using the Configuration API.

### Method
GET

### Endpoint
`/config/{object_type}/{object_name}`

### Parameters
#### Path Parameters
- **object_type** (string) - Required - The type of configuration object (e.g., `servers`).
- **object_name** (string) - Required - The name of the specific server configuration to retrieve.

#### Query Parameters
None

#### Request Body
None

### Request Example
```bash
GET /config/servers/my-proxy-server
```

### Response
#### Success Response (200)
- **schemas** (array) - Schema information for the response.
- **id** (string) - The name of the server.
- **enabled** (boolean) - Indicates if the server is enabled.
- **host** (string) - The hostname of the server.
- **port** (integer) - The port of the server.

#### Response Example
```json
{
  "schemas": [
    "urn:pingidentity:1.0:ProxyServer:Server"
  ],
  "id": "my-proxy-server",
  "enabled": true,
  "host": "localhost",
  "port": 8080
}
```
```

--------------------------------

### Setting up Initial Topology (Shell)

Source: https://docs.pingidentity.com/pingdirectory/10.1/pingdirectory_security_guide/pd_sec_ldap_simple_authn

This snippet provides a conceptual example of setting up an initial server topology using command-line tools. It highlights the process of initializing data on all servers, a critical step in distributed deployments. This is foundational for establishing a robust and scalable environment.

```shell
# Example: Initialize data on server1
bin/manage-profile --profile-dir /path/to/profile/server1 --initialize-data --prompt-for-password

# Example: Initialize data on server2
bin/manage-profile --profile-dir /path/to/profile/server2 --initialize-data --prompt-for-password
```

--------------------------------

### Start IDM Provisioning Sample - Shell Script

Source: https://docs.pingidentity.com/pingidm/7.2/samples-guide/provisioning-with-workflow

This script starts the IDM server with the configuration for the provisioning sample. It requires navigating to the IDM installation directory and executing the startup script with specific parameters. Ensure the path to IDM is correct.

```shell
cd /path/to/openidm/
./startup.sh -p samples/provisioning-with-workflow
```

--------------------------------

### Configuration API Examples (GET, GET list, PATCH)

Source: https://docs.pingidentity.com/pingdirectory/9.3/pingdatasync_server_administration_guide/pd_sync_use_dsconfig_interactive

Examples demonstrating the use of the Configuration API for retrieving and updating server configurations. These examples are useful for automating management tasks and integrating with other systems. The API supports GET, GET list, and PATCH operations.

```json
{
  "operation": "GET",
  "path": "/config/servers/my-server/properties"
}
```

```json
{
  "operation": "GET",
  "path": "/config/servers"
}
```

```json
{
  "operation": "PATCH",
  "path": "/config/servers/my-server",
  "body": {
    "propertyName": "newValue"
  }
}
```

--------------------------------

### PingDirectoryProxy Server Initial Setup

Source: https://docs.pingidentity.com/pingdirectory/10.3/pingdatasync_server_administration_guide/pd_sync_start_real_time_sync

This section outlines the initial steps for deploying a standard PingDirectoryProxy server, including automatic server discovery and joining an existing topology.

```shell
# Example command to join a PingDirectoryProxy server to an existing topology
# Assumes you have prepared the external server template and have its details
# The exact command might vary based on the specific step in the deployment guide.
# This is a conceptual representation.
/path/to/pingdirectory/bin/dsconfig create-external-server --tool-args "--template <template-file> --bindDN <proxy-bind-dn> --bindPasswordFile <password-file> --hostname <proxy-hostname> --port <proxy-port> --serverGroup <server-group-name>"

# Example command to configure load balancing algorithms
dsconfig --hostname <proxy-hostname> --port <proxy-port> --bindDN <bindDN> --bindPasswordFile <password-file> --no-prompt dsconfig create-load-balancing-algorithm --algorithm-name "round-robin-weights" --set algorithm-type=round-robin --set "weight=server1:10,server2:5"
```

--------------------------------

### Configuration API GET List Example

Source: https://docs.pingidentity.com/pingdirectory/9.3/pingdirectory_security_guide/pd_sec_config_data_encryption

This example demonstrates how to use the Configuration API to retrieve a list of configuration objects. This is useful for auditing and understanding the current server setup. It requires authentication and authorization, and the output is a JSON array of configuration objects.

```bash
# Example GET list request to the Configuration API
curl -X GET "https://<host>:<port>/config/api/v1/<config_object_type>" \
  -H "Accept: application/json" \
  -u <username>:<password>
```

--------------------------------

### OpenIDM Startup Script Execution Example

Source: https://docs.pingidentity.com/pingidm/7.5/install-guide/repository-postgresql

This output shows the successful execution of the OpenIDM startup script, including the resolved `OPENIDM_OPTS` environment variable and confirmation that OpenIDM is ready.

```bash
Executing ./startup.sh...
Using OPENIDM_HOME:   /path/to/openidm
Using PROJECT_HOME:   /path/to/openidm
Using OPENIDM_OPTS:   -Xmx2048m -Xms2048m -Dopenidm.repo.host=localhost -Dopenidm.repo.port=5432
Using LOGGING_CONFIG: -Djava.util.logging.config.file=/path/to/openidm/conf/logging.properties
Using boot properties at /path/to/openidm/resolver/boot.properties
-> OpenIDM version "7.5.1"
OpenIDM ready
```

--------------------------------

### Configuration API Examples (GET, GET List, PATCH)

Source: https://docs.pingidentity.com/pingdirectory/9.3/pingdirectory_server_administration_guide/pd_ds_client_connection_policy

Examples demonstrating how to interact with the PingDataMetrics Configuration API using GET, GET list, and PATCH operations. These examples illustrate fetching configuration data, retrieving lists of configuration objects, and modifying existing configurations.

```shell
# GET example
curl -X GET https://localhost:8080/config/api/v1/servers/server1

# GET list example
curl -X GET https://localhost:8080/config/api/v1/servers

# PATCH example
curl -X PATCH https://localhost:8080/config/api/v1/servers/server1 -d '{"listen-port": 8081}'
```

--------------------------------

### Configuration API - GET Example

Source: https://docs.pingidentity.com/pingdirectory/9.3/pingdatametrics_server_administration_guide/pd_met_start_pdm_server_background_proc

This section provides an example of how to use the GET method with the Configuration API to retrieve configuration details.

```APIDOC
## GET /config

### Description
Retrieves configuration details for the PingDirectoryProxy server.

### Method
GET

### Endpoint
/config

### Parameters
#### Query Parameters
- **filter** (string) - Optional - Filter to apply to the configuration objects.
- **fields** (string) - Optional - Comma-separated list of fields to return.

### Request Example
```json
{
  "example": "GET /config?filter=objectClass=topology&fields=id,name"
}
```

### Response
#### Success Response (200)
- **id** (string) - The unique identifier of the configuration object.
- **name** (string) - The name of the configuration object.

#### Response Example
```json
{
  "example": [
    {
      "id": "topology1",
      "name": "Primary Topology"
    }
  ]
}
```
```

--------------------------------

### GET Example

Source: https://docs.pingidentity.com/pingdirectory/9.3/installing_the_pingdirectory_suite_of_products/pd_ds_before_you_begin_install

Demonstrates how to retrieve configuration data using a GET request to the Configuration API.

```APIDOC
## GET Example

### Description
Retrieves a specific configuration object or a list of configuration objects.

### Method
GET

### Endpoint
`/servers/{serverID}/config/{configObjectName}` or `/servers/{serverID}/config`

### Query Parameters
- `filter` (string) - Optional - Filter to apply to the results.
- `sort-by` (string) - Optional - Attribute to sort the results by.
- `sort-order` (string) - Optional - Order of sorting (ascending or descending).

### Response
#### Success Response (200)
- `result` (array) - List of configuration objects.

### Response Example
```json
{
  "result": [
    {
      "id": "example-id",
      "type": "example-type",
      "description": "An example configuration"
    }
  ]
}
```
```

--------------------------------

### Install PingDirectory Server

Source: https://docs.pingidentity.com/pingdirectory/latest/pingdirectory_security_guide/pd_sec_encoded_pw_caching

This example shows the basic command to start the PingDirectory server installation process. It typically involves running an installation script provided with the package.

```bash
# Example: Running the PingDirectory installer
sh PingDirectory-10.3.0.0.sh
```

--------------------------------

### Configuration API - GET Example

Source: https://docs.pingidentity.com/pingdirectory/10.2/pingdirectory_server_administration_guide/pd_ds_generate_access_log_summaries

This section provides an example of how to use the GET method with the Configuration API to retrieve specific configuration details.

```APIDOC
## GET /<api_path>

### Description
Retrieves a specific configuration object or a list of objects based on the provided path.

### Method
GET

### Endpoint
`/<api_path>`

### Parameters

#### Query Parameters
- **filter** (string) - Optional - Filters the results based on specified criteria.
- **sortBy** (string) - Optional - Specifies the field to sort the results by.

### Request Example
```json
{
  "example": "GET /config/server-groups/my-server-group"
}
```

### Response
#### Success Response (200)
- **<field_name>** (<type>) - Description of the configuration property.

#### Response Example
```json
{
  "example": "{\"id\": \"my-server-group\", \"servers\": [\"server1\", \"server2\"]}"
}
```
```

--------------------------------

### GET List Example - Configuration API

Source: https://docs.pingidentity.com/pingdirectory/10.1/pingdirectoryproxy_server_administration_guide/pd_proxy_move_subtree_tool

Example of how to retrieve a list of configuration objects using the GET method with the Configuration API.

```APIDOC
## GET /config

### Description
Retrieves a list of configuration objects.

### Method
GET

### Endpoint
`/config`

### Parameters
#### Path Parameters
N/A

#### Query Parameters
- **filter** (string) - Optional - Filter criteria for the list.
- **sort** (string) - Optional - Sorting criteria for the list.

#### Request Body
N/A

### Request Example
N/A

### Response
#### Success Response (200)
- **configurationObjects** (array) - An array of configuration objects.

#### Response Example
```json
[
  {
    "dn": "cn=config1,cn=config",
    "objectClass": "configObject"
  },
  {
    "dn": "cn=config2,cn=config",
    "objectClass": "configObject"
  }
]
```
```
Tokens:
Raw