Deployment Example 1: Access Manager 7.1 Load Balancing, Distributed Authentication UI, and Session Failover

Previous: Chapter 4 Installing Sun Java System Directory Server and Creating Instances for Sun Java System Access Manager Configuration Data
Next: Chapter 6 Installing and Configuring Access Manager

Chapter 5 Configuring Instances of Sun Java System Directory Server for User Data

This chapter contains instructions for creating instances of Directory Server to hold user data called am-users. If you have an existing user data store, you can go directly to the instructions in 7.2 Creating and Configuring a Realm for Test Users to configure Access Manager to recognize your data store and users. This chapter contains the following sections:

5.1 Creating Directory Server Instances for User Data

This section contains information on creating user data instances on the Directory Server 1 and Directory Server 2 host machines. Use the following list of procedures as a checklist for these tasks.

To Create a User Data Instance for Directory Server 1

In this procedure, you create a Directory Server instance named am-users for storing user data on Directory Server 1. The new instance uses the ports for non-root users: 1489 for LDAP and 1736 for LDAPS. This instance will be populated with user information in Chapter 7, Configuring an Access Manager Realm for User Authentication.

Note –

By default, Directory Server always creates a secure LDAP port when creating an instance. We do not use this port.

As a root user, log in to the DirectoryServer–1 host machine.

Run dsadm create to create a user data instance called am-users.

# cd /var/opt/mps/serverroot/ds6/bin
# ./dsadm create -p 1489 -P 1736 /var/opt/mps/am-users
Choose the Directory Manager password: d1rm4n4ger
Confirm the Directory Manager password: d1rm4n4ger

Use 'dsadm start /var/opt/mps/am-users' to start the instance

Run dsadm start to start the instance.

# ./dsadm start /var/opt/mps/am-users

Server started: pid=10381

Run netstat to verify that the new instance is up and running.

# netstat -an | grep 1489

.1489		*.*		0		0  49152		0 LISTEN

Run ldapsearch to verify that you can read the root Directory Server entry (DSE) of the new instance.

# ldapsearch -h DirectoryServer-1.example.com 
  -p 1489 -b "" -s base "(objectclass=*)"

version: 1
dn:
objectClass: top
...
supportedLDAPVersion: 3
vendorname: Sun Microsystems, Inc.
vendorVersion: Sun-Java(tm)-System-Directory/6.0
...

To Create a Base Suffix for the User Data Instance on Directory Server 1

After creating the user data instance, you create a base suffix in which the entries will be stored.

Before You Begin

This procedure assumes you have just completed To Create a User Data Instance for Directory Server 1.

As a root user on the DirectoryServer–1 host machine, run dsconf create-suffix to create a base suffix.

# ./dsconf create-suffix -p 1489 -B dbExample 
  -L /var/opt/mps/am-users/db/exampleDS dc=company,dc=com

Provide information when prompted.

Certificate "CN=DirectoryServer-1, CN=1736, CN=directory Server, O=Sun Microsystems" 
presented by the server is not trusted.
Type "Y" to accept, "y" to accept just one, "n" to refuese, "d" for more details: Y
Enter "cn=Directory Manager" password: d1rm4n4ger

Note –

When you enter an uppercase Y, you are not asked for the certificate again in the next steps.

Run dsconf list-suffixes to verify that the base suffix was successfully created.
# ./dsconf list-suffixes -p 1489 Enter "cn=Directory Manager" password: d1rm4n4ger dc=company,dc=com
If the base suffix was successfully created, dc=company, dc=com is returned. You can also see am-users in the list of directory instances:
# cd /var/opt/mps # ls am-config am-users serverroot

Log out of the DirectoryServer–1 host machine.

To Create a User Data Instance for Directory Server 2

In this procedure, you create a Directory Server instance named am-users for storing user data on Directory Server 2. The new instance uses the ports for non-root users: 1489 for LDAP and 1736 for LDAPS. This instance will be populated with user information in Chapter 7, Configuring an Access Manager Realm for User Authentication.

Note –

By default, Directory Server always creates a secure LDAP port when creating an instance. We do not use this port.

As a root user, log in to the DirectoryServer–2 host machine.

Run dsadm create to create a user data instance called am-users.

# cd /var/opt/mps/serverroot/ds6/bin
# ./dsadm create -p 1489 -P 1736 /var/opt/mps/am-users
Choose the Directory Manager password: d1rm4n4ger
Confirm the Directory Manager password: d1rm4n4ger

Use 'dsadm start /var/opt/mps/am-users' to start the instance

Run dsadm start to start the instance.

# ./dsadm start /var/opt/mps/am-users

Server started: pid=10381

Run netstat to verify that the new instance is up and running.

# netstat -an | grep 1489

.1489		*.*		0		0  49152		0 LISTEN

Run ldapsearch to verify that you can read the root DSE of the new instance.

# ldapsearch -h DirectoryServer-2.example.com 
  -p 1489 -b "" -s base "(objectclass=*)"

version: 1
dn:
objectClass: top
...
supportedLDAPVersion: 3
vendorname: Sun Microsystems, Inc.
vendorVersion: Sun-Java(tm)-System-Directory/6.0
...

To Create a Base Suffix for the User Data Instance on Directory Server 2

After creating an instance, you must create a base suffix in which the entries will be stored.

Before You Begin

This procedure assumes you have just completed To Create a User Data Instance for Directory Server 2.

As a root user on the DirectoryServer–2 host machine, run dsconf create-suffix to create a base suffix.

# ./dsconf create-suffix -p 1489 -B dbExample 
  -L /var/opt/mps/am-users/db/exampleDS dc=company,dc=com

Provide information when prompted.

Certificate "CN=DirectoryServer-2, CN=1736, CN=directory Server, O=Sun Microsystems" 
presented by the server is not trusted.
Type "Y" to accept, "y" to accept just one, "n" to refuese, "d" for more details: Y
Enter "cn=Directory Manager" password: d1rm4n4ger

Note –

When you enter an uppercase Y, you are not asked for the certificate again in the next steps.

Run dsconf list-suffixes to verify that the base suffix was successfully created.
# ./dsconf list-suffixes -p 1489 Enter "cn=Directory Manager" password: d1rm4n4ger dc=company,dc=com
If the base suffix was successfully created, dc=company, dc=com is returned. You can also see am-users in the list of directory instances as follows:
# cd /var/opt/mps # ls am-config am-users serverroot

Log out of the DirectoryServer–2 host machine.

5.2 Enabling Multi-Master Replication of the User Data Instances

This section contains the instructions to enable multi-master replication (MMR) between two directory masters. This includes creating replication agreements between the masters and initializing the second directory master with the data and schema from the first directory master. The previously created am-users instances will serve as the two masters. An illustration of the architecture can be seen in Figure 4–1.

Use the following list of procedures as a checklist for completing the tasks.

To Enable Multi-Master Replication for User Data Instance on Directory Server 1

As a root user, log in to the DirectoryServer–1 host machine.

(Optional) Run dsconf list-suffixes to verify that the instance is not already enabled for replication.

# cd /var/opt/mps/serverroot/ds6/bin
# ./dsconf list-suffixes -p 1489 -v
Enter "cn=Directory Manager" password: d1rm4n4ger
...
dc=company,dc=com 	1		not-replicated		N/A		N/A		29
The "list-suffixes" operation succeeded on "DirectoryServer-1.example.com:1489"

The base suffix of the instance is not-replicated as displayed in the resulting list.

Run dsconf enable-repl to enable replication.

# ./dsconf enable-repl -h DirectoryServer-1.example.com 
  -p 1489 -d 11 master dc=company,dc=com
Enter "cn=Directory Manager" password: d1rm4n4ger
Use "dsconf create-repl-agmt" to create replication agreements on
"dc=company,dc=com".

The -d option takes as input a randomly chosen identifier to represent the Directory Server 1 configuration data instance; in this case, 11. master indicates that the instance is a master and not a replica. The base suffix is specified as dc=company,dc=com.

Run dsconf list-suffixes again to verify that the instance is now enabled for replication.

# ./dsconf list-suffixes -p 1489 -v
Enter "cn=Directory Manager" password: d1rm4n4ger
...
dc=company,dc=com 	1		master(11)		N/A		N/A		29
The "list-suffixes" operation succeeded on 
"DirectoryServer-1.example.com:1489"

The base suffix of the instance is master(11) as displayed in the resulting list, indicating that the master was successfully enabled.

Log out of the DirectoryServer–1 host machine.

To Enable Multi-Master Replication for User Data Instance on Directory Server 2

As a root user, log in to the DirectoryServer–2 host machine.

(Optional) Run dsconf list-suffixes to verify that the instance is not already enabled for replication.

# cd /var/opt/mps/serverroot/ds6/bin
# ./dsconf list-suffixes -p 1489 -v
Enter "cn=Directory Manager" password: d1rm4n4ger
...
dc=company,dc=com 	1		not-replicated		N/A		N/A		29
The "list-suffixes" operation succeeded on "DirectoryServer-2.example.com:1489"

The base suffix of the instance is not-replicated as displayed in the resulting list.

Run dsconf enable-repl to enable replication.

# ./dsconf enable-repl -h DirectoryServer-2.example.com 
  -p 1489 -d 22 master dc=company,dc=com
Enter "cn=Directory Manager" password: d1rm4n4ger
Use "dsconf create-repl-agmt" to create replication agreements on
"dc=company,dc=com".

The -d option takes as input a randomly chosen identifier to represent the Directory Server 1 configuration data instance; in this case, 22. master indicates that the instance is a master and not a replica. The base suffix is specified as dc=company,dc=com.

Run dsconf list-suffixes again to verify that the instance is now enabled for replication.

# ./dsconf list-suffixes -p 1489 -v
Enter "cn=Directory Manager" password: d1rm4n4ger
...
dc=company,dc=com 	1		master(22)		N/A		N/A		29
The "list-suffixes" operation succeeded on "DirectoryServer-2.example.com:1489"

The base suffix of the instance is master(22) as displayed in the resulting list, indicating that the master was successfully enabled.

Log out of the DirectoryServer–2 host machine.

To Change the Default Replication Manager Passwords for Each User Data Instance

The replication manager is the user that suppliers use to bind to the consumer server when sending replication updates. (In MMR the consumer server refers to whichever master happens to be the consumer for that particular operation.) It is recommended by the Directory Server documentation to change the default password created during the process of enabling replication.

As a root user, log in to the DirectoryServer–1 host machine.

Create a temporary file that contains the new replication manager password.

This file is read once, and the password is stored for future use.
# cd /var/opt/mps/serverroot/ds6/bin # echo replm4n4ger > pwd.txt

Verify that the file was successfully created.
# cat pwd.txt replm4n4ger

Run dsconf set-server-prop to set the replication manager password using pwd.txt as input.

# ./dsconf set-server-prop -h DirectoryServer-1.example.com 
  -p 1489 def-repl-manager-pwd-file:pwd.txt
Enter "cn=Directory Manager" password: d1rm4n4ger

Remove the pwd.txt file.

Log out of the DirectoryServer–1 host machine.

As a root user, log in to the DirectoryServer–2 host machine.

Create a temporary file that contains the new replication manager password.

This file is read once, and the password is stored for future use.
# cd /var/opt/mps/serverroot/ds6/bin # echo replm4n4ger > pwd.txt

Verify that the file was successfully created.
# cat pwd.txt replm4n4ger

Run dsconf set-server-prop to set the replication manager password using pwd.txt as input.

# ./dsconf set-server-prop -h DirectoryServer-2.example.com 
  -p 1489 def-repl-manager-pwd-file:pwd.txt
Enter "cn=Directory Manager" password: d1rm4n4ger

Remove the pwd.txt file.

Log out of the DirectoryServer–2 host machine.

To Create Replication Agreements for Each User Data Instance

A replication agreement is a set of parameters on a supplier that controls how updates are sent to a given consumer. In this case, we are making the user data instances aware of each other.

As a root user, log in to the DirectoryServer–1 host machine.

Run dsconf create-repl-agmt to create the replication agreement.

# cd /var/opt/mps/serverroot/ds6/bin
# ./dsconf create-repl-agmt -h DirectoryServer-1.example.com 
  -p 1489 dc=company,dc=com DirectoryServer-2.example.com:1489
Enter "cn=Directory Manager" password: d1rm4n4ger

Use "dsconf init-repl-dest dc=company,dc=com DirectoryServer-2.example.com:1489" 
to start replication of "dc=company,dc=com" data.

Run dsconf list-repl-agmts to verify that the replication agreement was successfully created.
# ./dsconf list-repl-agmts -p 1489 Enter "cn=Directory Manager" password: d1rm4n4ger dc=company,dc=com DirectoryServer-2.example.com:1489
This response indicates that the Directory Server 1 base suffix will be replicated to Directory Server 2.

Log out of the DirectoryServer–1 host machine.

As a root user, log in to the DirectoryServer–2 host machine.

Run dsconf create-repl-agmt to create the replication agreement.

# cd /var/opt/mps/serverroot/ds6/bin
# ./dsconf create-repl-agmt -h DirectoryServer-2.example.com 
  -p 1489 dc=company,dc=com DirectoryServer-1.example.com:1489
Enter "cn=Directory Manager" password: d1rm4n4ger

Use "dsconf init-repl-dest dc=company,dc=com DirectoryServer-1.example.com:1489" 
to start replication of "dc=company,dc=com" data.

Run dsconf list-repl-agmts to verify that the replication agreement was successfully created.
# ./dsconf list-repl-agmts -p 1489 Enter "cn=Directory Manager" password: d1rm4n4ger dc=company,dc=com DirectoryServer-1.example.com:1489
This response indicates that the Directory Server 2 base suffix will be replicated to Directory Server 1.

Log out of the DirectoryServer–2 host machine.

To Initialize the User Data Instance Replication Agreements

In this procedure, initialize the user data instance on Directory Server 1. The previously created agreements will replicate the data to Directory Server 2.

Note –

Initialization is not required on both instances when configuring for MMR.

As a root user, log in to the DirectoryServer–1 host machine.

Run dsconf show-repl-agmt-status to verify that the replication agreements are not yet initialized.

# cd /var/opt/mps/serverroot/ds6/bin
# ./dsconf show-repl-agmt-status -h DirectoryServer-1.example.com 
  -p 1489 dc=company,dc=com DirectoryServer-2.example.com:1489
Enter "cn=Directory Manager" password: d1rm4n4ger

Configuration Status 		: OK
Authentication Status		: OK
Initialization Status		: NOT OK

Status:										: Dest. Not Initialized

Run dsconf init-repl-dest to initialize the replication agreements.

# ./dsconf init-repl-dest -h DirectoryServer-1.example.com 
  -p 1489 dc=company,dc=com DirectoryServer-2.example.com:1489
Enter "cn=Directory Manager" password: d1rm4n4ger

Sent 1 entries...
Sent 2 entries...
Completed initialization of "DirectoryServer-2.example.com:1489"; 
May 15, 2007 1:53:32 PM

Run dsconf show-repl-agmt-status again to verify that the replication agreements are now initialized.

# cd /var/opt/mps/serverroot/ds6/bin
# ./dsconf show-repl-agmt-status -h DirectoryServer-1.example.com 
  -p 1489 dc=company,dc=com DirectoryServer-2.example.com:1489
Enter "cn=Directory Manager" password: d1rm4n4ger
Configuration Status 		: OK
Authentication Status		: OK
Initialization Status		: OK

Status:										: Enabled
Last Update Date						: Jul 12, 2007 8:47:42 PM

Log out of the DirectoryServer–1 host machine.

To Verify that User Data Replication Works Properly

As a root user, log in to the DirectoryServer–1 host machine.

Run ldapmodify to create a new directory entry.

# ldapmodify -a -h DirectoryServer-1.example.com -p 1489 
  -D cn=admin,cn=Administrators,cn=config -w d1rm4n4ger

dn: ou=People,dc=company,dc=com
objectclass: top
objectclass: organizationalUnit
ou: People
description: Container for user entries

Hit ENTER to indicate end of input.

adding new entry ou=People,dc=company,dc=com

Hit Control C to terminate the command.

^C

This step creates a new organizational unit on Directory Server 1.

After the entry is created, as a root user, log in to the DirectoryServer–2 host machine.

Run ldapsearch on Directory Server 2 to verify that the directory entry was successfully replicated.

# ldapsearch -b "dc=company,dc=com" -p 1489 -D "cn=Directory Manager" 
  -w d1rm4n4ger "objectclass=organizationalUnit"

version: 1
dn: ou=People,dc=company,dc=com
objectClass: top
objectClass: organizationalUnit
ou: People
description Container for user entries

Now run ldapdelete on Directory Server 2 to delete the entry just created.

# ldapdelete -h DirectoryServer-2.example.com -p 1489 
  -D "cn=Directory Manager" -w d1rm4n4ger "ou=People,dc=company,dc=com"

As a root user on Directory Server 1, run ldapsearch to verify that the entry was deleted.
# ldapsearch -b "dc=company,dc=com" -p 1489 -D "cn=Directory Manager" -w d1rm4n4ger "objectclass=organizationalUnit"
If the delete was successfully replicated to Directory Server 1, the search will return no results.

Log out of the Directory Server host machines.

5.3 Configuring the Load Balancer for the User Data Instances

Two load balancers are configured for the Directory Server installations. Load Balancer 1 fronts the configuration data instances and Load Balancer 2 fronts the user data instances. In the following procedure, you configure a load balancer in front of the configuration data instances. Figure 4–1 illustrates this architecture.

To Configure User Data Load Balancer 2

This procedure assumes that you have already installed a load balancer.
The load balancer hardware and software used in the lab facility for this deployment is BIG-IP® manufactured by F5 Networks. If you are using different load balancer software, see the documentation that comes with that product for detailed settings information.
Contact your network administrator to obtain an available virtual IP address for the load balancer you want to configure.
Know the IP address of the load balancer hardware, the URL for the load balancer login page, and a username and password for logging in to the load balancer application.
Get the IP addresses for Directory Server 1 and Directory Server 2 by running the following command on each host machine:
# ifconfig -a

Access https://is-f5.example.com, the BIG-IP load balancer login page, in a web browser.

Click Configure your BIG-IP (R) using the Configuration Utility.

Create a Pool.

A pool contains all the backend server instances.
1. In the left pane, click Pools.
2. On the Pools tab, click Add.
3. In the Add Pool dialog, provide the following information:
  
  Pool Name
  
  DirectoryServer-UserData-Pool
  
  Load Balancing Method
  
  Round Robin
  
  Resources
  
  Add the IP address and port number of both Directory Server hosts: DirectoryServer-1:1489 and DirectoryServer-2:1489.
4. Click Done.

Add a Virtual Server.

This step defines instances of the load balancer.

Tip –
If you encounter JavaScript^TM errors or otherwise cannot proceed to create a virtual server, try using Internet Explorer.
1. In the left frame, click Virtual Servers.
2. On the Virtual Servers tab, click Add.
3. In the Add a Virtual Server dialog box, provide the following information:
  
  Address
  
  Enter the IP address for LoadBalancer-2.example.com
  
  Service
  
  489
  
  Pool
  
  DirectoryServer-UserData-Pool
4. Continue to click Next until you reach the Pool Selection dialog box.
5. In the Pool Selection dialog box, assign DirectoryServer-UserData-Pool to the virtual server.
6. Click Done.

Add Monitors

Monitors are required for the load balancer to detect the backend server failures.
1. In the left frame, click Monitors.
2. Click the Basic Associations tab.
3. Add an LDAP monitor for the Directory Server 1 node.
  
  In the Node column, locate the IP address and port number, DirectoryServer-1:1489, and select the Add checkbox.
4. Add an LDAP monitor for the Directory Server 2 node.
  
  In the Node column, locate the IP address and port number, DirectoryServer–2:1489, and select the Add checkbox.
5. At the top of the Node column, in the drop-down list, choose ldap-tcp.
6. Click Apply.

Configure the load balancer for persistence.

The user data load balancer is configured for simple persistence. With simple persistence, all requests sent within a specified interval are processed by the same Directory Server instance, ensuring complete replication of entries. For example, when a request requires information to be written to Directory Server 1, that information must also be replicated to Directory Server 2. As the replication takes time to complete, if a related request is directed by the load balancer to Directory Server 2 during the replication process itself, the request may fail as the entry might only be partially created. When properly configured, simple persistence ensures that both requests are routed to Directory Server 1 and processed in consecutive order; the first request is finished before the second request begins processing. Simple persistence ensures that within the specified interval, no errors or delays occur due to replication time or redirects when retrieving data. Simple persistence tracks connections based only on the client IP address.
1. In the left frame, click Pools.
2. Click the name of the pool you want to configure.
  
  In this example, DirectoryServer-UserData-Pool.
3. Click the Persistence tab.
4. Under Persistence Type, select Simple.
5. Enter 300 seconds for the Timeout interval.
6. Click Apply.

Verify the Directory Server load balancer configuration.
1. Log in as a root user to the host machine of each Directory Server instance.
2. On each Directory Server host machine, use the tail command to monitor the Directory Server access log.
  # cd /var/opt/mps/am-users/logs # tail -f access
  You should see connections to the load balancer IP address opening and closing. For example:
```
[12/Oct/2006:13:10:20-0700] conn=54 op=-1 msgId=-1 — 
fd=22 slot=22 LDAP connection from IP_address to IP_address
[12/Oct/2006:13:10:20-0700] conn=54 op=-1 msgId=-1 — closing — B1
[12/Oct/2006:13:10:20-0700] conn=54 op=-1 msgId=-1 — closed.
```
3. Execute the following LDAP search against the Directory Server load balancer.
  # ldapsearch -h LoadBalancer-2.example.com -p 489 -b "dc=company,dc=com" -D "cn=directory manager" -w d1rm4n4ger "(objectclass=*)"
  The ldapsearch operation should return entries. Make sure they display in the access log on only one Directory Server.
4. Run dsadm stop to stop Directory Server 1.
  # cd /var/opt/mps/serverroot/ds6/bin # ./dsadm stop /var/opt/mps/am-users
5. Again perform the following LDAP search against the Directory Server load balancer.
  # ldapsearch -h LoadBalancer-2.example.com -p 489 -b "dc=company,dc=com" -D "cn=directory manager" -w d1rm4n4ger "(objectclass=*)"
  The ldapsearch operation should return entries. Verify that the entries display in the access log on only Directory Server 2.
  
  Note –
  You may encounter the following error message:
```
ldap_simple_bind: Cant' connect to the LDAP 
server — Connection refused
```
  This means that the load balancer may not fully detect that Directory Server 1 is stopped. In this case, you may have started the search too soon based on the polling interval setting. For example, if the polling interval is set to 10 seconds, you should wait ten seconds to start the search. You can reset the timeout properties to a lower value using the following procedure.
  1. Click the Monitors tab.
  2. Click the ldap-tcp monitor name.
  3. In the Interval field, set the value to 5.
    
    This tells the load balancer to poll the server every 5 seconds.
  4. In the Timeout field, set the value to 16.
  5. Click Apply and repeat the LDAP search.
  See your load balancer documentation for more information on the timeout property.
6. Start Directory Server 1.
  # ./dsadm start /var/opt/mps/am-users
7. Stop Directory Server 2.
  # cd /var/opt/mps/serverroot/ds6/bin # ./dsadm stop /var/opt/mps/am-users
8. Perform the following LDAP search against the Directory Server load balancer to confirm that the request is forwarded to the running Directory Server 1.
  # ldapsearch -h LoadBalancer-2.example.com -p 489 -b "dc=company,dc=com" -D "cn=Directory Manager" - w d1rm4n4ger "(objectclass=*)"
  The ldapsearch operation should return entries. Make sure the entries display in the access log on only Directory Server 1.
9. Start Directory Server 2.
  # ./dsadm start /var/opt/mps/am-users
10. Log out of both Directory Server host machines and the load balancer console.