Chapter 21. Troubleshooting
Prev |  | Next

# Chapter 21. Troubleshooting

This chapter covers how to get debugging information and troubleshoot issues in OpenAM deployments.

## Solutions to Common Issues

This section offers solutions to common problems when working with OpenAM.

### 21.1. OpenAM Installation
Q: | OpenAM configuration could not write to the configuration directory. Where must I change permissions, and what permissions are required?
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 *
Q: | Deployment failed due to lack of memory. What do I do?
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`.
Q: | Deployment failed due to invalid hostname configuration. What do I do?
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
Q: | I configured OpenAM, and now am seeing the configuration screen again. Who deleted my configuration?
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.
### 21.2. OpenAM Upgrades
Q: | I have upgraded OpenAM, now my tools are not working properly. What happened?
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.
### 21.3. OpenAM Administration
Q: | I cannot use the browser-based equivalent of ssoadm, `http://openam.example.com:8080/openam/ssoadm.jsp`. Why not?
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`.
Q: | The ssoadm command is very, very slow on my virtual machine (VMWare, VirtualBox, etc.). How can I speed it up?
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.
Q: | I added OpenDJ as a data store, and now I cannot add a user. OpenAM gives me the following error. ERROR: LDAPv3Repo.create failed. errorCode=65 Entry uid=test,ou=people,dc=example,dc=com violates the Directory Server schema configuration because it includes attribute inetUserStatus which is not allowed by any of the objectclasses defined in that entry
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
Q: | I have session failover configured for an OpenAM site. I see many connections in `TIME_WAIT` state, and the connections seem to be used only for communication between OpenAM servers in that site. What should I set to have fewer connections in `TIME_WAIT`?
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. By lengthening `com.iplanet.am.session.failover.cluster.stateCheck.timeout` and `com.iplanet.am.session.failover.cluster.stateCheck.period` to something longer than the default, you can work around issues with network latency. By setting `com.sun.identity.urlchecker.dorequest` to `true` or `false`, you can change whether OpenAM performs an HTTP GET request or only checks the Socket connection of `com.sun.identity.urlchecker.targeturl` as a health check. 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

Prev |  | Next
Chapter 20. Securing OpenAM | Home | OpenAM Glossary