Chapter 21. Troubleshooting

A:

If the user running the web container has a $HOME directory, then the configuration directory is stored there, and you probably do not have this problem. If you do not know the user running the web container, use the ps command to check. In the following example, the user is mark, the web container tomcat.

$ ps -ef | grep tomcat
mark      1739     1  0 14:47...

For a container installed from native packages with a dedicated user, $HOME may not be where you think it is. Look at the user's entry in /etc/passwd to locate the home directory. The user running the web container where you install OpenAM must be able to read from and write in this directory.

If you cannot change the permissions to the user's home directory, you can, as a workaround, unpack , set the configuration.dir property in the WEB-INF/classes/bootstrap.properties to a directory with appropriate permissions, and repack openam.war with the adjusted file before deploying that.

$ cd ~/Downloads/openam/
$ mkdir unpacked ; cd unpacked
$ jar xf ../
$ vi WEB-INF/classes/bootstrap.properties 
$ grep ^config WEB-INF/classes/bootstrap.properties 
configuration.dir=/my/readwrite/config/dir
$ jar cf ../openam.war *

A:

OpenAM requires at least a maximum heap size of 1024 MB, with a 256 MB maximum permanent generation heap size. For the Sun JVM, ensure the container starts with -Xmx1024m -XX:MaxPermSize=256m for these settings.

If you do not know the settings used when the web container was started, use the ps command to check. In the following example, the web container is tomcat.

$ ps -ef | grep tomcat | grep Xm
... -Xmx1024m -XX:MaxPermSize=256m ...

Make sure you have at least 2 GB of RAM on the system where you run OpenAM to avoid running out of memory.

If you make it through deployment and seem to be running out of memory later, you can confirm memory errors in OpenAM by searching the config-dir/openam/debug/* files for java.lang.OutOfMemoryError.

A:

OpenAM requires that you use a fully qualified domain name (FQDN) that the host can resolve.

$ ping openam-ter.example.com
PING openam-ter (192.168.56.2) 56(84) bytes of data.
64 bytes from openam (192.168.56.2): icmp_seq=1 ttl=64 time=0.025 ms
64 bytes from openam (192.168.56.2): icmp_seq=2 ttl=64 time=0.032 ms
64 bytes from openam (192.168.56.2): icmp_seq=3 ttl=64 time=0.030 ms

For a test deployment (at home, on a laptop), you can use fake FQDNs in /etc/hosts (%SystemRoot%\system32\drivers\etc\hosts on Windows), depending on how your network is configured.

$ cat /etc/hosts | grep openam
192.168.56.2 openam openam.example.com
192.168.56.3 openam-bis openam-bis.example.com
192.168.56.5 openam-ter openam-ter.example.com

A:

OpenAM uses a file in $HOME/.openamcfg/ to bootstrap and find its configuration. The file is named after the path to OpenAM and contains the path to the configuration. The following example shows what the file looks like for OpenAM deployed in Apache Tomcat under /path/to/tomcat/webapps/openam, and running as user amuser with $HOME /home/amuser.

$ cat .openamcfg/AMConfig_path_to_tomcat_webapps_openam_ 
/home/amuser/openam

If OpenAM cannot find its configuration, then it displays the configuration screen.

A:

Every OpenAM component must be upgraded, not just the main OpenAM .war file. If you did not upgrade the tools too, they may not work as intended.

A:

For security reasons, ssoadm.jsp is not activated by default. To activate it, browse to Configuration > Servers and Sites > Servers > ServerName > Advanced, and then add a property named ssoadm.disabled with value false.

A:

Virtual machine random devices do not always produce enough random data. The ssoadm command can hang while reading random data from the virtual machine's random device, with the result that you can wait a minute or more for a single command to finish.

To work around this limitation on virtual machines, make sure you install something that generates enough random data, such as a timer entropy daemon.

A:

When you set up a New Data Store to use OpenDJ as an identity repository under Access Control > Realm Name > Data Stores > New..., you need to check the Load schema when saved box if you want OpenAM to add the schema to OpenDJ. The box is not selected by default.

The full version of OpenAM includes directory server schema in the ~/Downloads/openam/ldif/ directory. To add the schema to OpenDJ afterwards, you can try the following command.

$ /path/to/OpenDJ/bin/ldapmodify
 --port 1389
 --bindDN "cn=Directory Manager"
 --bindPassword password
 --filename ~/Downloads/openam/ldif/fam_sds_schema.ldif
Processing MODIFY request for CN=schema
MODIFY operation successful for DN CN=schema

A:

When you have session failover configured for a site, OpenAM servers run health checks against other servers in the same site. By default, the health checks are run every second (1000 milliseconds) with a timeout of 1 second (1000 milliseconds).

If there is network latency between servers in a site, for example if you are running your servers in virtual machines, the default settings might not be right for your deployment. In that case, consider changing the following advanced server properties.

To set advanced properties, either use the OpenAM console page under Configuration > Servers and Sites > Default Server Settings > Advanced, or set the properties using the ssoadm update-server-cfg command as in the following example, which updates the default server configuration:

$ ./ssoadm update-server-cfg -s default -u amadmin -f /tmp/pwd.txt
 -a com.iplanet.am.session.failover.cluster.stateCheck.timeout=2000