b537f26600e0f7924eb1088903cca14402da987dbuliabyak<?xml version="1.0" encoding="UTF-8"?>

1dcdfe80a39221844d0b90c5b7ebc625047f9252acspike<chapter xml:id='chap-troubleshooting'

d2ef6868b0ca327abfd5a6c54e8c8364af1636f8acspike xmlns='http://docbook.org/ns/docbook'

d2ef6868b0ca327abfd5a6c54e8c8364af1636f8acspike version='5.0' xml:lang='en'

001487ea1099b8f734d0f1dce7d5d13cf4e1e6aepjrm xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'

a32edf750ea3213bf97dfc2885df5426f87d8c6falvinpenner xsi:schemaLocation='http://docbook.org/ns/docbook http://docbook.org/xml/5.0/xsd/docbook.xsd'

b537f26600e0f7924eb1088903cca14402da987dbuliabyak xmlns:xlink='http://www.w3.org/1999/xlink'

deab3914a965aa587631d120fe60c932e23b3d70alvinpenner xmlns:xinclude='http://www.w3.org/2001/XInclude'>

deab3914a965aa587631d120fe60c932e23b3d70alvinpenner <title>Troubleshooting</title>

deab3914a965aa587631d120fe60c932e23b3d70alvinpenner <indexterm><primary>Troubleshooting</primary></indexterm>

deab3914a965aa587631d120fe60c932e23b3d70alvinpenner <para>This chapter offers solutions to issues during installation of OpenAM

deab3914a965aa587631d120fe60c932e23b3d70alvinpenner policy agents.</para>

deab3914a965aa587631d120fe60c932e23b3d70alvinpenner

b537f26600e0f7924eb1088903cca14402da987dbuliabyak <qandaset xml:id="solutions-to-common-issues" defaultlabel="qanda">

b537f26600e0f7924eb1088903cca14402da987dbuliabyak <title>Solutions to Common Issues</title>

b537f26600e0f7924eb1088903cca14402da987dbuliabyak

b537f26600e0f7924eb1088903cca14402da987dbuliabyak <para>This section offers solutions to common problems when installing

b537f26600e0f7924eb1088903cca14402da987dbuliabyak OpenAM policy agents.</para>

b537f26600e0f7924eb1088903cca14402da987dbuliabyak

b537f26600e0f7924eb1088903cca14402da987dbuliabyak <qandaentry xml:id="web-agent-error-page">

b537f26600e0f7924eb1088903cca14402da987dbuliabyak <question>

b537f26600e0f7924eb1088903cca14402da987dbuliabyak <para>How can I configure a custom error page to be returned by the web

b537f26600e0f7924eb1088903cca14402da987dbuliabyak policy agent on HTTP 403 Forbidden or HTTP 500 Internal Server Error for

b537f26600e0f7924eb1088903cca14402da987dbuliabyak example?</para>

b537f26600e0f7924eb1088903cca14402da987dbuliabyak </question>

b537f26600e0f7924eb1088903cca14402da987dbuliabyak

b537f26600e0f7924eb1088903cca14402da987dbuliabyak <answer>

b537f26600e0f7924eb1088903cca14402da987dbuliabyak <para>Web servers generally let you set custom error pages for specific

b537f26600e0f7924eb1088903cca14402da987dbuliabyak HTTP status codes. Check the documentation for your web server to see

b537f26600e0f7924eb1088903cca14402da987dbuliabyak how to set the custom pages.</para>

b537f26600e0f7924eb1088903cca14402da987dbuliabyak

b537f26600e0f7924eb1088903cca14402da987dbuliabyak <itemizedlist>

b537f26600e0f7924eb1088903cca14402da987dbuliabyak <listitem>

1dcdfe80a39221844d0b90c5b7ebc625047f9252acspike <para>Apache HTTP Server uses the <link xlink:show="new"

b537f26600e0f7924eb1088903cca14402da987dbuliabyak xlink:href="http://httpd.apache.org/docs/2.0/mod/core.html#errordocument"

b537f26600e0f7924eb1088903cca14402da987dbuliabyak ><literal>ErrorDocument</literal> directive</link>.</para>

001487ea1099b8f734d0f1dce7d5d13cf4e1e6aepjrm </listitem>

a32edf750ea3213bf97dfc2885df5426f87d8c6falvinpenner

b537f26600e0f7924eb1088903cca14402da987dbuliabyak <listitem>

b537f26600e0f7924eb1088903cca14402da987dbuliabyak <para>Microsoft IIS 6 Manager lets you configure <link xlink:show="new"

b537f26600e0f7924eb1088903cca14402da987dbuliabyak xlink:href="http://www.microsoft.com/technet/prodtechnol/WindowsServer2003/Library/IIS/80cb8d8d-8fd8-4af5-bb3b-4d11fff3ab9c.mspx?mfr=true"

b537f26600e0f7924eb1088903cca14402da987dbuliabyak >Custom Errors settings</link>.</para>

a32edf750ea3213bf97dfc2885df5426f87d8c6falvinpenner </listitem>

8e20eef3b0047d54e0b0141b415cd5658ac8bcbfalvinpenner

a32edf750ea3213bf97dfc2885df5426f87d8c6falvinpenner <listitem>

bee224bac95dc2683569954c2a1818f675bc5e2dalvinpenner <para>Microsoft IIS 7 also lets you create <link

bee224bac95dc2683569954c2a1818f675bc5e2dalvinpenner xlink:href="http://technet.microsoft.com/en-us/library/cc753103(v=ws.10).aspx"

bee224bac95dc2683569954c2a1818f675bc5e2dalvinpenner xlink:show="new">custom HTTP error responses</link>, and generally <link

bee224bac95dc2683569954c2a1818f675bc5e2dalvinpenner xlink:href="http://technet.microsoft.com/en-us/library/cc731570(v=ws.10).aspx"

bee224bac95dc2683569954c2a1818f675bc5e2dalvinpenner xlink:show="new">configure HTTP error responses</link>.</para>

a32edf750ea3213bf97dfc2885df5426f87d8c6falvinpenner </listitem>

bee224bac95dc2683569954c2a1818f675bc5e2dalvinpenner </itemizedlist>

bee224bac95dc2683569954c2a1818f675bc5e2dalvinpenner

bee224bac95dc2683569954c2a1818f675bc5e2dalvinpenner <para>When you set up the error pages, make sure they are in the agent's

bee224bac95dc2683569954c2a1818f675bc5e2dalvinpenner list of Not Enforced URLs as described in <link xlink:show="new"

b537f26600e0f7924eb1088903cca14402da987dbuliabyak xlink:href="admin-guide#web-agent-not-enforced-url-properties"

bee224bac95dc2683569954c2a1818f675bc5e2dalvinpenner xlink:role="http://docbook.org/xlink/role/olink"><citetitle>Not Enforced URL

bee224bac95dc2683569954c2a1818f675bc5e2dalvinpenner Processing properties</citetitle></link>, or alternatively make sure the

bee224bac95dc2683569954c2a1818f675bc5e2dalvinpenner pages are on a web server that is not protected by the web policy agent.

bee224bac95dc2683569954c2a1818f675bc5e2dalvinpenner You do not want the agent to prevent user from seeing the HTTP 403 Forbidden

bee224bac95dc2683569954c2a1818f675bc5e2dalvinpenner custom error page for instance.</para>

deab3914a965aa587631d120fe60c932e23b3d70alvinpenner </answer>

deab3914a965aa587631d120fe60c932e23b3d70alvinpenner </qandaentry>

deab3914a965aa587631d120fe60c932e23b3d70alvinpenner

deab3914a965aa587631d120fe60c932e23b3d70alvinpenner <qandaentry xml:id="cannot-install-over-https">

deab3914a965aa587631d120fe60c932e23b3d70alvinpenner <question>

deab3914a965aa587631d120fe60c932e23b3d70alvinpenner <para>I am trying to install a policy agent, connecting to OpenAM over

deab3914a965aa587631d120fe60c932e23b3d70alvinpenner HTTPS, and seeing the following error.</para>

deab3914a965aa587631d120fe60c932e23b3d70alvinpenner

deab3914a965aa587631d120fe60c932e23b3d70alvinpenner <screen>OpenAM server URL: https://openam.example.com:8443/openam

deab3914a965aa587631d120fe60c932e23b3d70alvinpenner

bee224bac95dc2683569954c2a1818f675bc5e2dalvinpennerWARNING: Unable to connect to OpenAM server URL. Please specify the

bee224bac95dc2683569954c2a1818f675bc5e2dalvinpennercorrect OpenAM server URL by hitting the Back button (&lt;) or if the OpenAM

bee224bac95dc2683569954c2a1818f675bc5e2dalvinpennerserver URL is not started and you want to start it later, please proceed with

8e20eef3b0047d54e0b0141b415cd5658ac8bcbfalvinpennerthe installation.

bee224bac95dc2683569954c2a1818f675bc5e2dalvinpennerIf OpenAM server is SSL enabled and the root CA certificate for the OpenAM

8e20eef3b0047d54e0b0141b415cd5658ac8bcbfalvinpennerserver certificate has been not imported into installer JVMs key store (see

a32edf750ea3213bf97dfc2885df5426f87d8c6falvinpennerinstaller-logs/debug/Agent.log for detailed exception), import the root

bee224bac95dc2683569954c2a1818f675bc5e2dalvinpennerCA certificate and restart the installer; or continue installation without

8e20eef3b0047d54e0b0141b415cd5658ac8bcbfalvinpennerverifying OpenAM server URL.</screen>

a32edf750ea3213bf97dfc2885df5426f87d8c6falvinpenner

b537f26600e0f7924eb1088903cca14402da987dbuliabyak <para>What should I do?</para>

1dcdfe80a39221844d0b90c5b7ebc625047f9252acspike </question>

1dcdfe80a39221844d0b90c5b7ebc625047f9252acspike

1dcdfe80a39221844d0b90c5b7ebc625047f9252acspike <answer>

1dcdfe80a39221844d0b90c5b7ebc625047f9252acspike <para>The Java platform includes certificates from many Certificate

1dcdfe80a39221844d0b90c5b7ebc625047f9252acspike Authorities (CAs). If however you run your own CA, or you use self-signed

1dcdfe80a39221844d0b90c5b7ebc625047f9252acspike certificates for HTTPS on the container where you run OpenAM, then the

1dcdfe80a39221844d0b90c5b7ebc625047f9252acspike <command>agentadmin</command> command cannot trust the certificate

1dcdfe80a39221844d0b90c5b7ebc625047f9252acspike presented during connection to OpenAM, and so cannot complete installation

d2ef6868b0ca327abfd5a6c54e8c8364af1636f8acspike correctly.</para>

1dcdfe80a39221844d0b90c5b7ebc625047f9252acspike

1dcdfe80a39221844d0b90c5b7ebc625047f9252acspike <para>After setting up the container where you run OpenAM to use HTTPS,

1dcdfe80a39221844d0b90c5b7ebc625047f9252acspike get the certificate to trust in a certificate file. The certificate you

1dcdfe80a39221844d0b90c5b7ebc625047f9252acspike want is the that of the CA who signed the container certificate, or the

1dcdfe80a39221844d0b90c5b7ebc625047f9252acspike certificate itself if the container certificate is self-signed.</para>

1dcdfe80a39221844d0b90c5b7ebc625047f9252acspike

1dcdfe80a39221844d0b90c5b7ebc625047f9252acspike <para>Copy the certificate file to the system where you plan to install the

1dcdfe80a39221844d0b90c5b7ebc625047f9252acspike policy agent. Import the certificate into a trust store that you will use

1dcdfe80a39221844d0b90c5b7ebc625047f9252acspike during policy agent installation. If you import the certificate into the

60bbcba041e80a4b29118269c0897df5c068563eacspike default trust store for the Java platform, then the

1dcdfe80a39221844d0b90c5b7ebc625047f9252acspike <command>agentadmin</command> command can recognize it without additional

60bbcba041e80a4b29118269c0897df5c068563eacspike configuration.</para>

1dcdfe80a39221844d0b90c5b7ebc625047f9252acspike

b537f26600e0f7924eb1088903cca14402da987dbuliabyak <para>Export and import of self-signed certificates is demonstrated in the

b537f26600e0f7924eb1088903cca14402da987dbuliabyak <citetitle>Administration Guide</citetitle> chapter on <link

b537f26600e0f7924eb1088903cca14402da987dbuliabyak xlink:show="new" xlink:href="admin-guide#chap-certs-keystores"

60bbcba041e80a4b29118269c0897df5c068563eacspike xlink:role="http://docbook.org/xlink/role/olink"><citetitle>Managing

60bbcba041e80a4b29118269c0897df5c068563eacspike Certificates</citetitle></link>.</para>

60bbcba041e80a4b29118269c0897df5c068563eacspike </answer>

b759a0250777628a0fbbf91e913d1b60069c2ac7acspike </qandaentry>

60bbcba041e80a4b29118269c0897df5c068563eacspike

1dcdfe80a39221844d0b90c5b7ebc625047f9252acspike <qandaentry xml:id="debug-file-and-SELinux">

b537f26600e0f7924eb1088903cca14402da987dbuliabyak <question>

b537f26600e0f7924eb1088903cca14402da987dbuliabyak <para>I am trying to install the policy agent on SELinux and I am getting error messages

60bbcba041e80a4b29118269c0897df5c068563eacspike after installation. What happened?</para>

60bbcba041e80a4b29118269c0897df5c068563eacspike </question>

b537f26600e0f7924eb1088903cca14402da987dbuliabyak <answer>

b537f26600e0f7924eb1088903cca14402da987dbuliabyak <para>SELinux must be properly configured to connect the web policy agent and OpenAM

b537f26600e0f7924eb1088903cca14402da987dbuliabyak nodes. Either re-configure SELinux or disable it, then reinstall the policy agent.</para>

b537f26600e0f7924eb1088903cca14402da987dbuliabyak </answer>

b537f26600e0f7924eb1088903cca14402da987dbuliabyak </qandaentry>

60bbcba041e80a4b29118269c0897df5c068563eacspike

b537f26600e0f7924eb1088903cca14402da987dbuliabyak <qandaentry xml:id="apache-defaults-to-port-80">

b537f26600e0f7924eb1088903cca14402da987dbuliabyak <question>

b537f26600e0f7924eb1088903cca14402da987dbuliabyak <para>My Apache HTTPD server is not using port 80. But when I install the

b537f26600e0f7924eb1088903cca14402da987dbuliabyak web policy agent it defaults to port 80. How do I fix this?</para>

1dcdfe80a39221844d0b90c5b7ebc625047f9252acspike </question>

1dcdfe80a39221844d0b90c5b7ebc625047f9252acspike

1dcdfe80a39221844d0b90c5b7ebc625047f9252acspike <answer>

b537f26600e0f7924eb1088903cca14402da987dbuliabyak <para>You probably set <literal>ServerName</literal> in Apache HTTPD's

a223910930e4cf964962a08cf1d30928395652c5pjrm configuration to the host name, but did not specify the port number.</para>

a223910930e4cf964962a08cf1d30928395652c5pjrm

a223910930e4cf964962a08cf1d30928395652c5pjrm <para>Instead you must set both the host name and port number for

77d65c763568495a6ffc7c15a81964448139f47apjrm <literal>ServerName</literal> in Apache HTTPD's configuration. For

77d65c763568495a6ffc7c15a81964448139f47apjrm example, if you have Apache HTTPD configured to listen on port 8080, then

a4030d5ca449e7e384bc699cd249ee704faaeab0Chris Morgan set <literal>ServerName</literal> appropriately as in the following

excerpt.</para>

<programlisting language="plain"

>&lt;VirtualHost *:8080&gt;

ServerName www.localhost.example:8080</programlisting>

</answer>

</qandaentry>

<qandaentry xml:id="cannot-install-with-ibm-java">

<question>

<para>I am trying to install the WebSphere policy agent on Linux.

The system has IBM Java. When I run <command>agentadmin --install</command>,

the script fails to encrypt the password from the password file, ending

with this message:</para>

<literallayout class="monospaced"

>ERROR: An unknown error has occurred (null). Please try again.</literallayout>

<para>What should I do?</para>

</question>

<answer>

<para>You must edit <command>agentadmin</command> to use IBMJCE, and then

try again.</para>

<para>See <link xlink:href="agent-install-guide#install-with-ibm-jvm"

xlink:role="http://docbook.org/xlink/role/olink"><citetitle>To Install

With IBM Java</citetitle></link>.</para>

</answer>

</qandaentry>

<qandaentry xml:id="web-agent-cannot-rotate-logs">

<question>

<para>My web server and web policy agent are installed as root, and the

agent cannot rotate logs. I am seeing this error.</para>

<literallayout class="monospaced">Could not rotate log file ... (error: 13)</literallayout>

<para>What should I do?</para>

</question>

<answer>

<para>First, avoid installing the web server (and therefore also the web

policy agent) as root, but instead create a web server user and install

as that user.</para>

<para>If however you cannot avoid installing the web server and policy agent

as root, the you must give all users read and write permissions to the

<filename>logs/</filename> and <filename>logs/debug</filename> directories

under the agent instance directory (

<filename>/path/to/web_agents/<replaceable>type</replaceable>/Agent_<replaceable>number</replaceable>/logs/</filename>).

Otherwise the web policy agent fails to rotate log files with the error

you observed.</para>

</answer>

</qandaentry>

</qandaset>

</chapter>