OpenAMインストール時の注意点とトラブルシューティングの方法

OpenAMインストール時(warのデプロイから初期設定まで)の注意点や、よくある問題とその対策方法について説明します。

OpenAM 11.0.0の公式なインストールガイドは以下にあります。各入力フィールドの意味などが記載されているので、詳細を知りたい方はこちらを熟読して下さい。

OpenAM 11.0.0 Installation Guide

英語が辛いという方は、以前CodeZineにインストール方法を書いたので、このページを参考にして下さい。最新バージョンがOpenAM 10.0だったころに書きましたが、手順はほとんど変わっていません。OpenAMのインストールは、基本的にTomcatなどのサーブレットコンテナにwarファイルをデプロイして初期設定するだけですが、以下に記載する通りいくつかの注意すべき点があります。


■ インストール前の注意事項 (事前設定)

OpenAMをインストールする前に、インストールできる環境であるか確認が必要です。

・サポート(動作確認)されているプラットフォームの確認

以下のページに、OpenAMを稼働する上で必要なOSやサーブレットコンテナについて記載されています。まずはこの条件を確認して下さい。

OpenAM Release Notes – Chapter 2. Before You Install OpenAM 11.0.0 Software

information ForgeRock社で動作確認がされているものが記載されていますが、これ以外の環境でも正常に動作する可能性はあります。

・FQDNの準備

OpenAMをセットアップする際に、完全修飾ドメイン名(FQDN)を指定する必要があります。セットアップの前に、openam.example.comのようなFQDNでサーバーにアクセスできることを確認して下さい。評価目的でOpenAMを使用する場合は、/etc/hostsファイル(Linux)や%SystemRoot%\system32\drivers\etc\hostsファイル(Windows)に、FQDNが適切に割り当てられていることを確認して下さい。私がテスト用にインストールするときは、/etc/sysconfig/networkのHOSTNAMEもFQDNにしています。

$ vi /etc/hosts

# 以下を追加
192.168.1.1 openam.example.com

$ vi /etc/sysconfig/network
HOSTNAME=openam.example.com
warning テスト目的のためであっても、localhostドメインを使用しないで下さい。 OpenAMの動作は、ドメイン名に基づいて返されるブラウザのクッキーに依存しています。基本的には、少なくとも2つの「.」(ドットを含むドメイン名を使用していることを確認して下さい。※Cookieドメインの仕様に関しては、後述する「インストール時の注意事項」を参照下さい。
例) openam.example.com
information 一般的に、従来からあるCookieを使用したSSOでは、SSOの適用範囲をCookieが共有可能な同一ドメイン内に限定します。そのため、上記のようなドメインの設定に関する制限事項を守る必要があります。

・JREの事前設定

 Sun / Oracle Javaを使用する場合は、次のオプションの設定が必要です

-server
-client(クライアントVM)ではなく、-server(サーバーVM)を使用してください。通常、サーバーVMはクライアントVMよりも起動が遅いですが、長期的には実行速度を速くします。
-XX:MaxPermSize=256m
Permanent 領域の最大値256 MBに設定します。
-Xmx1024m
OpenAMは、少なくとも1 GBのヒープを必要とします。組み込みOpenDJを含める場合は、そのスペースの50%がOpenDJに割り当てられるように、OpenAMには最低2 GBのヒープを設定します。システム構成によってはさらに追加のヒープを必要とします。

・ファイルディスクリプタの最大値の設定

組み込みのOpenDJを使用する場合は、必ずファイルディスクリプタが十分であることを確認して下さい。Linuxでは多くの場合、ユーザーあたり1024に制限されていますが、OpenDJにはこの値は低すぎます。以下のコマンドで確認します。

$ ulimit -n
1024
information CentOSの場合、CentOS 5まではデフォルトで無制限だったようですが、CentOS 6からは1024になっています。

OpenDJには、少なくとも64Kのファイルディスクリプタを使用できるようにしておいた方がいいです。組み込みOpenDJは、OpenAMプロセス空間内で実行されるため、OpenAMの実行ユーザーに対する設定値を変更します。ユーザー制限を設定するために/etc/security/limits.confが使用されている場合は、次の行を追加することで、ソフト制限とハード制限を設定できます。

openam soft nofile 65536
openam hard nofile 131072

Linuxシステム全体の最大値を確認することができます。

$ cat /proc/sys/fs/file-max
204252

全体的な最大値が低すぎる場合は、次のようにして値を増やして下さい。スーパーユーザーとして、/etc/sysctl.confを編集し、カーネルパラメータfs.file-maxを高い最大値に設定します。/etc/sysctl.confの設定をリロードするには次のコマンドを実行します。

sysctl -p

・ファイアウォールとSELinuxの設定

テスト目的でOpenAMをLinux上にインストールするのであれば、ファイアウォールとSELinuxをオフにしておいた方が簡単です。以下を設定した後、設定を反映させるためにOSを再起動します。

$ service iptables stop
$ chkconfig iptables off

$ vi /etc/sysconfig/selinux
#SELINUX=enforcing
SELINUX=disabled
information OpenAMが使用するポートについては以下に記載されています。
OpenAM Reference – Chapter 4. Ports Used

・サーブレットコンテナ(Tomcat)の設定

Tomcatを使用する場合は、server.xmlのConnectorタグにURIEncoding=”UTF-8″を追記しておいた方がいいです。いくつかの画面の文字化けや文字コードに起因する問題を回避できます。

<Connector port="8080" protocol="HTTP/1.1"
   connectionTimeout="20000"
   redirectPort="8443" URIEncoding="UTF-8" />

■ インストール時の注意事項

インストール時の注意事項としては以下が挙げられます。

デフォルトインストールは実施しないこと

デフォルト設定ではなく、カスタム設定を実施して下さい。デフォルト設定のCookie ドメインの生成ロジックにバグがあり、インストール後に問題が発生することがあります。

installpage

詳細はこのページを参照して下さい。

Cookie ドメインは「.」から始めること

手順2の「サーバー設定」でCookieドメインの入力フィールドがありますが、ここでは「.」で始めるCookieドメインを入力する必要があります。例えば、ホスト名が「openam.example.com」の場合は、「.example.com」とします。詳細はこのページを参照して下さい。

また、画面を表示した時点で「.com」となっている場合は、「.example.com」に変更する必要があります(「.com」ではドメインの範囲が広すぎるので)。さらにドメインが ?.com のようなgTLDの場合は「.」が2つでも構いませんが、「 ?.jp」のようなccTLDの場合は「.」が3つ以上必要です。これはCookieのdomain属性の仕様のためです(HTTPの仕様であり、OpenAM独自の制限事項ではありません)。
例) 「.example.com」、「.example.co.jp」 → OK、「.example.jp」 → NG


■ よくある問題とその対策

書き込みアクセスエラー画面が表示される

【事象】
以下のような書き込みアクセスエラー画面が表示される。
nowrite
【原因】
Tomcatディレクトリの所有者の設定が不適切なため。

【対策】
Tomcatディレクトリの所有者とグループをtomcatに変更します。

chown -R tomcat:tomcat /usr/share/tomcat6/

アップグレード画面が表示される

【事象】
以下のようなアップグレード画面が表示される。
upgrade

【原因】
古いバージョンの設定ディレクトリが残っているため。以前OpenAMをセットアップした際に生成された古いバージョンの設定ディレクトリが残っていると、OpenAMはインストールではなくアップグレードを行います。

【対策】
サーブレットコンテナを停止し、OpenAMの設定ディレクトリを削除して下さい。その後サーブレットコンテナを起動して設定をやり直して下さい。

rm -fr /usr/share/tomcat6/openam

service tomcat6 restart

・ UnknownHostExceptionが発生する

【事象】
以下のエラーがinstall.logに出力されて、初期設定の実行中で処理が停止する。

If you want to report this error, provide the contents of file /usr/share/tomcat/temp/opendj-setup-○○.log

To see basic server configuration status and configuration you can launch /home/tomcat/openam/opends/bin/status
...失敗しました。
...失敗 5
AMSetupServlet.processRequest: errorcom.sun.identity.setup.ConfiguratorException: configurator.embsetupopendsfailed
at com.sun.identity.setup.EmbeddedOpenDS.setupOpenDS(EmbeddedOpenDS.java:371)
at com.sun.identity.setup.EmbeddedOpenDS.setup(EmbeddedOpenDS.java:251)
at com.sun.identity.setup.AMSetupServlet.setupEmbeddedDS(AMSetupServlet.java:834)
at com.sun.identity.setup.AMSetupServlet.setupSMDatastore(AMSetupServlet.java:890)
at com.sun.identity.setup.AMSetupServlet.configure(AMSetupServlet.java:962)
at com.sun.identity.setup.AMSetupServlet.processRequest(AMSetupServlet.java:639)
at com.sun.identity.config.wizard.Wizard.createConfig(Wizard.java:304)
at sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method)
...

opendj-setup-○○.logを確認すると、以下のUnknownHostExceptionが発生している。

[18/9/2014:18:24:15 +0900] category=RUNTIME_INFORMATION severity=NOTICE msgID=20381714 msg=JVM Host: Unknown (java.net.UnknownHostException: openam1: openam1: 名前解決時の一時的な失敗), running Linux 2.6.32-358.el6.x86_64 amd64, 1968766976 bytes physical memory size, number of processors available 1

【原因】
localhostのOpenAMサーバーがFQDNで名前解決できないことが原因。

【対策】
/etc/hostsや/etc/sysconfig/networkのHOSTNAMEの設定を見直して下さい。

途中で停止し、応答が無くなる

【事象】
稀に初期設定の実行中で処理が停止してしまう場合があります。サービスXMLをディレクトリサーバーに登録中に、画面上に「サービス ○○.xml を登録しています」のメッセージが表示されてから「…成功しました。」が出ない状態になります。

installing

【原因】
このときOpenAMの内部では、無限ループが発生している可能性があります。

【対策】
こういった場合は、サーブレットコンテナのプロセスを終了して、OpenAMの設定ディレクトリを削除して、もう一度インストールをやり直して下さい。無限ループの問題については以下にまとめています。

information このバグは、2015/03/03のOpenAM 13.0.0のナイトリービルドで対策しました。com.sun.identity.shared.ldap.LDAPEntryというかなり昔からあるクラスの潜在的な問題でした。

URLEncoder.encode()でNullPointerExceptionが発生する

【事象】
初期設定の実行中に、以下のようにURLEncoder.encode()でNullPointerExceptionが発生する。

Checking configuration directory /usr/share/openam....Success.
Reinitializing system properties....Done
Configuring server instance....Done
Setting up monitoring authentication file.AMSetupServlet.processRequest: errorjava.lang.NullPointerException
        at java.net.URLEncoder.encode(URLEncoder.java:205)
        at com.sun.identity.setup.BootstrapCreator.getBootStrapURL(BootstrapCreator.java:190)
        at com.sun.identity.setup.BootstrapCreator.update(BootstrapCreator.java:105)
        at com.sun.identity.setup.BootstrapCreator.updateBootstrap(BootstrapCreator.java:83)
        at com.sun.identity.common.configuration.ServerConfigXMLObserver.update(ServerConfigXMLObserver.java:108)
        at com.sun.identity.setup.AMSetupServlet.processRequest(AMSetupServlet.java:647)
        at com.sun.identity.config.wizard.Wizard.createConfig(Wizard.java:294)
        at sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method)
        at sun.reflect.NativeMethodAccessorImpl.invoke(NativeMethodAccessorImpl.java:57)
        at sun.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:43)
        at java.lang.reflect.Method.invoke(Method.java:616)
        at org.apache.click.util.ClickUtils.invokeMethod(ClickUtils.java:3317)
        at org.apache.click.util.ClickUtils.invokeListener(ClickUtils.java:2088)
...

この問題は、JIRAにも登録されています。

【原因】
初期設定の手順3で、外部ディレクトリサーバーとして、既存の設定データストア(=過去にOpenAMの設定データストアとして使ったことがあるディレクトリサーバー)を設定していることが原因。入力した暗号化鍵と既存の設定データストアの暗号化鍵が一致しないため、復号化に失敗してNullPointerExceptionが発生します。

【対策】
設定データを含んでいない新しいディレクトリサーバーを使用するか、既存の設定データストアのルートサフィックス(例えば、dc=openam,dc=forgerock,dc=org)以下のou=admins以外のエントリを削除して下さい。

information このバグの修正は、14.0.0にコミットする予定です。

・configurator.embsetupopendsfailedが表示される

【事象】
初期設定の実行中に、以下のように”configurator.embsetupopendsfailed”という文字列を含むエラーが発生する。

djStarted

install.logには以下のようなスタックトレースが出力されている。

If you want to report this error, provide the contents of file
/opt/tomcat7/temp/opendj-setup-4620378611651538995.log

To see basic server configuration status and configuration you can launch
/opt/tomcat7/openam/opends/bin/status

...???????
...?? 5
AMSetupServlet.processRequest: errorcom.sun.identity.setup.ConfiguratorException: configurator.embsetupopendsfailed
 at com.sun.identity.setup.EmbeddedOpenDS.setupOpenDS(EmbeddedOpenDS.java:378)
 at com.sun.identity.setup.EmbeddedOpenDS.setup(EmbeddedOpenDS.java:259)
 at com.sun.identity.setup.AMSetupServlet.setupEmbeddedDS(AMSetupServlet.java:836)
 at com.sun.identity.setup.AMSetupServlet.setupSMDatastore(AMSetupServlet.java:884)
 at com.sun.identity.setup.AMSetupServlet.configure(AMSetupServlet.java:922)
 at com.sun.identity.setup.AMSetupServlet.processRequest(AMSetupServlet.java:594)
 at com.sun.identity.config.wizard.Wizard.createConfig(Wizard.java:305)
 at sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method)
...

【原因】
一度初期設定に失敗して、再度やり直した場合にこのエラーが出ます。最初に失敗した際に、組み込みのOpenDJが起動しており、それにもかかわらず再度起動しようとしてエラーになります。

【対策】
この場合も、サーブレットコンテナのプロセスを終了して、OpenAMの設定ディレクトリを削除して、もう一度インストールをやり直して下さい。

■ 既知の問題

2014年10月15日現在、上であげた以外にもOpenAMのJIRAには、未対策のバグが登録されています。

他にもいくつかあります。問題に遭遇した場合は、エラーメッセージなどをキーにしてJIRAで検索してみて下さい。


■ トラブルシューティングの方法

・install.logの確認

インストール時のログはOpenAMの設定ディレクトリ直下のinstall.logに出力されます。インストールに失敗した場合は、まずこのファイルに原因を特定可能なメッセージが出力されていないか確認して下さい。組み込みのOpenDJのセットアップに失敗している場合もありますので、OpenDJのセットアップログも確認して下さい。OpenDJのセットアップログのファイル名(opendj-setup-○○.log)とパスは、install.logの中に出力されています。

warning OpenDJのセットアップログには以下のようなスタックトレースが出力されますが、これは問題ではありません。INFOレベルのログなので無視して下さい。

9 16, 2014 3:02:18 午後 org.opends.quicksetup.CurrentInstallStatus getPort
情報: Failed to get port
java.io.FileNotFoundException: /home/tomcat/openam/opends/./config/config.ldif
 (そのようなファイルやディレクトリはありません)
at java.io.FileInputStream.open(Native Method)
at java.io.FileInputStream.(FileInputStream.java:146)
at java.io.FileReader.(FileReader.java:72)
at org.opends.quicksetup.Configuration.load(Configuration.java:331)
at org.opends.quicksetup.Configuration.getLowerCaseContents(Configuration.java:298)
at org.opends.quicksetup.Configuration.getLDAPPort(Configuration.java:191)
at org.opends.quicksetup.Configuration.getPort(Configuration.java:92)
at org.opends.quicksetup.CurrentInstallStatus.getPort(CurrentInstallStatus.java:178)
at org.opends.quicksetup.CurrentInstallStatus.(CurrentInstallStatus.java:80)
at org.opends.server.tools.InstallDS.checkInstallStatus(InstallDS.java:622)
at org.opends.server.tools.InstallDS.execute(InstallDS.java:417)
at org.opends.server.tools.InstallDS.mainCLI(InstallDS.java:341)
...

紛らわしいので修正したいのですが…

・デバッグモードでインストール

OpenAMの初期設定時にデバッグモードでログを出力することができます。サーブレットコンテナのJVMに、次のJVMオプションを追加して下さい。/tmp/debugに詳細なデバッグログが出力されています。

  • com.iplanet.services.debug.directory=/tmp/debug
  • com.iplanet.services.debug.level=message
warning インストール完了後はこのオプションを取り除いて下さい。以降のデバッグログがこのファイルに出力され続けてしまいます。

それでも原因が分からない場合は、IDE(IntelliJやEclipseなど)のデバッガーでTomcatプロセスにアタッチして原因を調査して下さい。


他にも問題(とその対策)をご存知の方がいましたら、情報を共有していただけるとうれしいです。

広告

コメントを残す

以下に詳細を記入するか、アイコンをクリックしてログインしてください。

WordPress.com ロゴ

WordPress.com アカウントを使ってコメントしています。 ログアウト / 変更 )

Twitter 画像

Twitter アカウントを使ってコメントしています。 ログアウト / 変更 )

Facebook の写真

Facebook アカウントを使ってコメントしています。 ログアウト / 変更 )

Google+ フォト

Google+ アカウントを使ってコメントしています。 ログアウト / 変更 )

%s と連携中