Configuring locations

The PingDirectoryProxy server defines locations, both for the LDAP external servers and the directory proxy instances themselves. A location defines a collection of servers that share access and latency characteristics. For example, your deployment might include two data centers, one in the east and one in the west. These data centers would be configured as two locations in the Directory Proxy Server. Each location is associated with a name and an ordered list of failover locations, which could be used if none of the servers in the preferred location are available. You can define these locations using the administrative console or the command line.

The PingDirectoryProxy server itself is also associated with a location. This location is specified in the global configuration properties of the server. If the load balancing algorithm’s use-location property is set to true, then the load balancing component of the PingDirectoryProxy server refers to the server’s location to determine the external servers it prefers to communicate with.

Modifying locations using dsconfig

Steps

To configure existing LDAP external server locations, use the dsconfig tool.
```
$ bin/dsconfig
```
Enter the host name or IP address for your PingDirectoryProxy server, or press Enter to accept the default, localhost.
```
Directory Proxy Server host name or IP address [localhost]:
```
Enter the number corresponding to how you want to connect to the PingDirectoryProxy server, or press Enter to accept the default, LDAP.
```
How do you want to connect?
  1) LDAP
  2) LDAP with SSL
  3) LDAP with StartTLS
```
Enter the port number for your PingDirectoryProxy server, or press Enter to accept the default, 389.
```
Directory Proxy Server port number [389]:
```
Enter the administrator’s bind distinguished name (DN) or press Enter to accept the default cn=Directory Manager, and then enter the password.
```
Administrator user bind DN [cn=Directory Manager]:
Password for user 'cn=Directory Manager':
```
In the PingDirectoryProxy main menu, enter the number corresponding to Global Configuration. Then enter the number to view and edit the Global Configuration.
Enter the number associated with the location configuration property.
```
Enter choice [b]: 2
```

Specify a new location for this PingDirectoryProxy server instance, in this example the East location.

Example:

Operations involving communications with other servers might prefer servers in the same location to ensure low-latency responses.

>>>> Configuring the 'location' property

...

Do you want to modify the 'location' property?

  1) Leave undefined
  2) Change it to the location: East
  3) Change it to the location: West
  4) Create a new location

  b) back
  q) quit

Enter choice [b]: 2

To finish the operation, enter f.
```
Enter choice [b]: f
```

Configuring locations using `dsconfig`

Steps

To configure the LDAP external server locations, use the dsconfig tool.
```
$ bin/dsconfig
```
Enter the host name or IP address for your PingDirectoryProxy server, or press Enter to accept the default, localhost.
```
Directory Proxy Server host name or IP address [localhost]:
```
Enter the number corresponding to how you want to connect to the PingDirectoryProxy server, or press Enter to accept the default, LDAP.
```
How do you want to connect?
  1) LDAP
  2) LDAP with SSL
  3) LDAP with StartTLS
```
Enter the port number for your PingDirectoryProxy server, or press Enter to accept the default, 389.
```
Directory Proxy Server port number [389]:
```
Enter the administrator’s bind distinguished name (DN) or press Enter to accept the default, cn=Directory Manager, and then enter the password.
```
Administrator user bind DN [cn=Directory Manager]:
Password for user 'cn=Directory Manager':
```
In the PingDirectoryProxy main menu, enter the number corresponding to location configuration. Then enter the number to create a new location.

Enter the name of the new location.

Example:

This example demonstrates configuring a location called East.

>>>>  Enter a name for the location that you want to create: east

>>>>  Configure the properties of the location

      Property                   Value(s)
      -----------------------------------
   1) description                  -
   2) preferred-failover-location  -

   ?) help
   f) finish – create the new location
   d) display the equivalent dsconfig arguments to
      create this object
   b) back
   q) quit

Enter choice [b]: f

To finish configuring the location, enter f.

Edit the configuration of an existing location, in this example a location named East.

Example:

>>>> Location menu
What would you like to do?

  1) List existing locations
  2) Create a new location
  3) View and edit an existing location
  4) Delete an existing location

  b) back
  q) quit

Enter choice [b]: 3

>>>> Select the location from the following list:
   1) East
   2) West

   b) back
   q) quit

Enter choice [b]: 1

Define the preferred-failover-location property for East.

This property provides alternate locations that can be used if servers in this location are not available. If more than one location is provided, the PingDirectoryProxy server tries the locations in the order listed.

Example:

 >>>> Configure the properties of the Location

     Property                   Value(s)
     -----------------------------------
  1) description                  -
  2) preferred-failover-location  -

  ?) help
  f) finish – create the new location
  d) display the equivalent dsconfig arguments to create this object
  b) back
  q) quit

Enter choice [b]: 2

...

Do you want to modify the 'preferred-failover-location' property?

   1) Add one or more values

   ?) help
   q) quit

Enter choice [1]: 2

Select the locations you wish to add:

  1) East
  2) West
  3) Create a new location
  4) Add all locations

...

Enter one or more choices separated by commas[b]: 2

Verify and apply your change to the property.

Example:

Do you want to modify the 'preferred-failover-location' property?

  1) Use the value: West
  2) Add one or more values
  3) Remove one or more values
  4) Leave undefined
  5) Revert changes

  ?) help
  q) quit

Enter choice [1]:

>>>> Configure the properties of the location

     Property                   Value(s)
     -----------------------------------
  1) description                  -
  2) preferred-failover-location  West

  ?) help
  f) finish – apply any changes to the Location
  d) display the equivalent dsconfig command lines to either
     re-create this object or only to apply pending changes
  b) back
  q) quit

Enter choice [b]: f