mirror of https://github.com/OpenIdentityPlatform/OpenDJ.git
opends/src/main/docbkx/admin-guide/chap-monitoring.xml
@@ -53,8 +53,9 @@ xlink:show="new" xlink:role="http://docbook.org/xlink/role/olink" >Evolving</link></para> <screen>$ ldapsearch --port 1389 --baseDN cn=monitor "(cn=userRoot backend)" dn: cn=userRoot backend,cn=Disk Space Monitor,cn=monitor <screen> $ <userinput>ldapsearch --port 1389 --baseDN cn=monitor "(cn=userRoot backend)"</userinput> <computeroutput>dn: cn=userRoot backend,cn=Disk Space Monitor,cn=monitor disk-state: normal objectClass: top objectClass: ds-monitor-entry @@ -73,8 +74,8 @@ ds-backend-entry-count: 163 ds-backend-id: userRoot ds-base-dn-entry-count: 163 dc=example,dc=com ds-backend-base-dn: dc=example,dc=com </screen> ds-backend-base-dn: dc=example,dc=com</computeroutput> </screen> <para>You can set global ACIs on the Access Control Handler if you want to limit read access under <literal>cn=monitor</literal>.</para> @@ -102,7 +103,9 @@ <para>To run the OpenDMK installer, use the self-extracting .jar.</para> <screen>$ java -jar ~/Downloads/opendmk-1.0-b02-*.jar</screen> <screen> $ <userinput>java -jar ~/Downloads/opendmk-1.0-b02-*.jar</userinput> </screen> <para>If you install under <filename>/path/to</filename>, then the runtime library needed for SNMP is @@ -112,66 +115,74 @@ for SNMP by enabling the connection handler, and pointing OpenDJ to your installation of the OpenDMK <filename>jdmkrt.jar</filename> library.</para> <screen>$ dsconfig set-connection-handler-prop --port 4444 --hostname opendj.example.com --bindDN "cn=Directory Manager" --bindPassword password --handler-name "SNMP Connection Handler" --set enabled:true --set opendmk-jarfile:/path/to/OpenDMK-bin/lib/jdmkrt.jar --trustAll --no-prompt</screen> <screen> $ <userinput>dsconfig \ set-connection-handler-prop \ --port 4444 \ --hostname opendj.example.com \ --bindDN "cn=Directory Manager" \ --bindPassword password \ --handler-name "SNMP Connection Handler" \ --set enabled:true \ --set opendmk-jarfile:/path/to/OpenDMK-bin/lib/jdmkrt.jar \ --trustAll \ --no-prompt</userinput> </screen> <para>By default, the SNMP Connection Handler listens on port 161 and uses port 162 for traps. On UNIX and Linux systems, only root can normally open these ports. Therefore if you install as a normal user, you might want to change the listen and trap ports.</para> <screen>$ dsconfig set-connection-handler-prop --port 4444 --hostname opendj.example.com --bindDN "cn=Directory Manager" --bindPassword password --handler-name "SNMP Connection Handler" --set listen-port:11161 --set trap-port:11162 --trustAll --no-prompt</screen> <screen> $ <userinput>dsconfig \ set-connection-handler-prop \ --port 4444 \ --hostname opendj.example.com \ --bindDN "cn=Directory Manager" \ --bindPassword password \ --handler-name "SNMP Connection Handler" \ --set listen-port:11161 \ --set trap-port:11162 \ --trustAll \ --no-prompt</userinput> </screen> <para>Restart the SNMP Connection Handler to take the port number changes into account.</para> <para> To restart the connection handler, you disable it, then enable it again.</para> <screen>$ dsconfig set-connection-handler-prop --port 4444 --hostname opendj.example.com --bindDN "cn=Directory Manager" --bindPassword password --handler-name "SNMP Connection Handler" --set enabled:false --trustAll --no-prompt $ dsconfig set-connection-handler-prop --port 4444 --hostname opendj.example.com --bindDN "cn=Directory Manager" --bindPassword password --handler-name "SNMP Connection Handler" --set enabled:true --trustAll --no-prompt</screen> <screen> $ <userinput>dsconfig \ set-connection-handler-prop \ --port 4444 \ --hostname opendj.example.com \ --bindDN "cn=Directory Manager" \ --bindPassword password \ --handler-name "SNMP Connection Handler" \ --set enabled:false \ --trustAll \ --no-prompt</userinput> $ <userinput>dsconfig \ set-connection-handler-prop \ --port 4444 \ --hostname opendj.example.com \ --bindDN "cn=Directory Manager" \ --bindPassword password \ --handler-name "SNMP Connection Handler" \ --set enabled:true \ --trustAll \ --no-prompt</userinput> </screen> <para>Use a command such as <command>snmpwalk</command> to check that the SNMP listen port works.</para> <screen>$ snmpwalk -v 2c -c OpenDJ@OpenDJ localhost:11161 SNMPv2-SMI::mib-2.66.1.1.1.1 = STRING: "OpenDJ <?eval ${docTargetVersion}?>..." <screen> $ <userinput>snmpwalk -v 2c -c OpenDJ@OpenDJ localhost:11161</userinput> SNMPv2-SMI::mib-2.66.1.1.1.1 = STRING: "OpenDJ ${docTargetVersion}..." SNMPv2-SMI::mib-2.66.1.1.2.1 = STRING: "/path/to/opendj" ...</screen> @@ -192,31 +203,35 @@ xlink:show="new" xlink:role="http://docbook.org/xlink/role/olink" >Evolving</link></para> <screen>$ dsconfig set-connection-handler-prop --port 4444 --hostname opendj.example.com --bindDN "cn=Directory Manager" --bindPassword password --handler-name "JMX Connection Handler" --set enabled:true --trustAll --no-prompt</screen> <screen> $ <userinput>dsconfig \ set-connection-handler-prop \ --port 4444 \ --hostname opendj.example.com \ --bindDN "cn=Directory Manager" \ --bindPassword password \ --handler-name "JMX Connection Handler" \ --set enabled:true \ --trustAll \ --no-prompt</userinput> </screen> <para>By default, no users have privileges to access the JMX connection. The following command adds JMX privileges for Directory Manager.</para> <screen>$ dsconfig set-root-dn-prop --port 4444 --hostname opendj.example.com --bindDN "cn=Directory Manager" --bindPassword password --add default-root-privilege-name:jmx-notify --add default-root-privilege-name:jmx-read --add default-root-privilege-name:jmx-write --trustAll --no-prompt</screen> <screen> $ <userinput>dsconfig \ set-root-dn-prop \ --port 4444 \ --hostname opendj.example.com \ --bindDN "cn=Directory Manager" \ --bindPassword password \ --add default-root-privilege-name:jmx-notify \ --add default-root-privilege-name:jmx-read \ --add default-root-privilege-name:jmx-write \ --trustAll \ --no-prompt</userinput> </screen> <para>You must also configure security to login remotely. See the section on <citetitle>Using SSL</citetitle> in <link @@ -227,9 +242,11 @@ <para>Alternatively, you can connect to a local server process by using the server process identifier.</para> <screen>$ cat ../logs/server.pid 3363 $ jvisualvm --openpid 3363 &</screen> <screen> $ <userinput>cat ../logs/server.pid</userinput> <computeroutput>3363</computeroutput> $ <userinput>jvisualvm --openpid 3363 &</userinput> </screen> </section> <section xml:id="monitoring-status-and-tasks"> @@ -243,8 +260,9 @@ <para>The <command>status</command> command takes administrative credentials to read the configuration, as does the Control Panel.</para> <screen>$ status --bindDN "cn=Directory Manager" --bindPassword password <screen> $ <userinput>status --bindDN "cn=Directory Manager" --bindPassword password</userinput> <computeroutput> --- Server Status --- Server Run Status: Started Open Connections: 1 @@ -253,8 +271,8 @@ Host Name: localhost Administrative Users: cn=Directory Manager Installation Path: /path/to/opendj Version: OpenDJ <?eval ${docTargetVersion}?> Java Version: 1.6.0_24 Version: OpenDJ ${docTargetVersion} Java Version: <replaceable>version</replaceable> Administration Connector: Port 4444 (LDAPS) --- Connection Handlers --- @@ -269,24 +287,27 @@ Base DN: dc=example,dc=com Backend ID: userRoot Entries: 163 Replication: Disabled</screen> Replication: Disabled</computeroutput> </screen> <para>The <command>manage-tasks</command> command connects over the administration port, and so can connect to both local and remote servers.</para> <screen>$ manage-tasks --hostname opendj.example.com --port 4444 --bindDN "cn=Directory Manager" --bindPassword password --trustAll --no-prompt <screen> $ <userinput>manage-tasks \ --hostname opendj.example.com \ --port 4444 \ --bindDN "cn=Directory Manager" \ --bindPassword password \ --trustAll \ --no-prompt</userinput> <computeroutput> ID Type Status -------------------------------------------------------- example Backup Recurring example-20110623030000000 Backup Waiting on start time</screen> example-20110623030000000 Backup Waiting on start time</computeroutput> </screen> </section> <section xml:id="logging"> @@ -313,7 +334,8 @@ message.</para> <para>The following access log excerpt shows a search operation from the local host, with the first three lines wrapped for readability.</para> <screen> <programlisting language="none"> [21/Jun/2011:08:01:53 +0200] CONNECT conn=4 from=127.0.0.1:49708 to=127.0.0.1:1389 protocol=LDAP [21/Jun/2011:08:01:53 +0200] SEARCH REQ conn=4 op=0 msgID=1 @@ -321,7 +343,8 @@ [21/Jun/2011:08:01:53 +0200] SEARCH RES conn=4 op=0 msgID=1 result=0 nentries=1 etime=3 [21/Jun/2011:08:01:53 +0200] UNBIND REQ conn=4 op=1 msgID=2 [21/Jun/2011:08:01:53 +0200] DISCONNECT conn=4 reason="Client Unbind"</screen> [21/Jun/2011:08:01:53 +0200] DISCONNECT conn=4 reason="Client Unbind" </programlisting> <para> Notice that by default OpenDJ directory server logs a message @@ -349,7 +372,8 @@ conditions, and warnings, categorized and identified by severity.</para> <para>The following errors log excerpt shows log entries about a backup task, with lines wrapped for readability.</para> <screen> <programlisting language="none"> [22/Jun/2011:12:32:23 +0200] category=BACKEND severity=NOTICE msgID=9896349 msg=Backup task 20110622123224088 started execution [22/Jun/2011:12:32:23 +0200] category=TOOLS severity=NOTICE msgID=10944792 @@ -359,7 +383,8 @@ [22/Jun/2011:12:32:24 +0200] category=TOOLS severity=NOTICE msgID=10944795 msg=The backup process completed successfully [22/Jun/2011:12:32:24 +0200] category=BACKEND severity=NOTICE msgID=9896350 msg=Backup task 20110622123224088 finished execution</screen> msg=Backup task 20110622123224088 finished execution </programlisting> </listitem> <listitem> @@ -463,7 +488,8 @@ the default configuration. Lines are folded and space reformatted for the printed page.</para> <screen>- 192.168.0.15 bjensen 22/May/2013:10:06:18 +0200 <programlisting language="none"> - 192.168.0.15 bjensen 22/May/2013:10:06:18 +0200 GET /users/bjensen?_prettyPrint=true HTTP/1.1 200 curl/7.21.4 3 40 - 192.168.0.15 bjensen 22/May/2013:10:06:52 +0200 @@ -476,8 +502,9 @@ GET /users/missing?_prettyPrint=true HTTP/1.1 401 curl/7.21.4 6 0 - 192.168.0.15 kvaughan 22/May/2013:10:09:10 +0200 POST /users?_action=create&_prettyPrint=true HTTP/1.1 200 curl/7.21.4 7 120</screen> POST /users?_action=create&_prettyPrint=true HTTP/1.1 200 curl/7.21.4 7 120 </programlisting> <para>You can configure the <literal>log-format</literal> for the access log using the <command>dsconfig</command> command. In addition to the default @@ -515,7 +542,8 @@ <para>The <firstterm>replication log</firstterm> traces replication events, with entries similar to the errors log. The following excerpt has lines wrapped for readability.</para> <screen> <programlisting language="none"> [22/Jun/2011:14:37:34 +0200] category=SYNC severity=NOTICE msgID=15139026 msg=Finished total update: exported domain "dc=example,dc=com" from this directory server DS(24065) to all remote directory servers. @@ -525,7 +553,9 @@ server will now try to connect to another replication server in order to receive changes for the domain "dc=example,dc=com" [22/Jun/2011:14:37:35 +0200] category=SYNC severity=NOTICE msgID=15138894 msg=The generation ID for domain "dc=example,dc=com" has been reset to 3679640</screen> msg=The generation ID for domain "dc=example,dc=com" has been reset to 3679640 </programlisting> <para>Notice that the replication log does not trace replication operations. Use the external change log instead to get notifications about changes to directory data over protocol. You can alternatively configure an audit @@ -564,54 +594,60 @@ <para>For example, view the log rotation policies with the following command.</para> <screen width="101">$ dsconfig list-log-rotation-policies --port 4444 --hostname opendj.example.com --bindDN "cn=Directory Manager" --bindPassword password <screen width="101"> $ <userinput>dsconfig \ list-log-rotation-policies \ --port 4444 \ --hostname opendj.example.com \ --bindDN "cn=Directory Manager" \ --bindPassword password</userinput> <computeroutput> Log Rotation Policy : Type : file-size-limit : rotation-interval : time-of-day ------------------------------------:------------:-----------------:-------------------:------------ 24 Hours Time Limit Rotation Policy : time-limit : - : 1 d : - 7 Days Time Limit Rotation Policy : time-limit : - : 1 w : - Fixed Time Rotation Policy : fixed-time : - : - : 2359 Size Limit Rotation Policy : size-limit : 100 mb : - : -</screen> Size Limit Rotation Policy : size-limit : 100 mb : - : -</computeroutput> </screen> <para>View the log retention policies with the following command.</para> <screen width="105">$ dsconfig list-log-retention-policies --port 4444 --hostname opendj.example.com --bindDN "cn=Directory Manager" --bindPassword password <screen width="105"> $ <userinput>dsconfig \ list-log-retention-policies \ --port 4444 \ --hostname opendj.example.com \ --bindDN "cn=Directory Manager" \ --bindPassword password</userinput> <computeroutput> Log Retention Policy : Type : disk-space-used : free-disk-space : number-of-files ---------------------------------:-----------------:-----------------:-----------------:---------------- File Count Retention Policy : file-count : - : - : 10 Free Disk Space Retention Policy : free-disk-space : - : 500 mb : - Size Limit Retention Policy : size-limit : 500 mb : - : -</screen> Size Limit Retention Policy : size-limit : 500 mb : - : -</computeroutput> </screen> <para>Use the <command>dsconfig get-log-publisher-prop</command> command to examine the policies that apply to a particular logger.</para> <screen>$ dsconfig get-log-publisher-prop --port 4444 --hostname opendj.example.com --bindDN "cn=Directory Manager" --bindPassword password --publisher-name "File-Based Access Logger" --property retention-policy --property rotation-policy Property : Value(s) <screen> $ <userinput>dsconfig \ get-log-publisher-prop \ --port 4444 \ --hostname opendj.example.com \ --bindDN "cn=Directory Manager" \ --bindPassword password \ --publisher-name "File-Based Access Logger" \ --property retention-policy \ --property rotation-policy</userinput> <computeroutput>Property : Value(s) -----------------:------------------------------------------------------------- retention-policy : File Count Retention Policy rotation-policy : 24 Hours Time Limit Rotation Policy, Size Limit Rotation : Policy</screen> : Policy</computeroutput> </screen> <para>In other words, by default OpenDJ keeps 10 access log files, rotating the access log each day, or when the log size reaches 100 MB.</para> @@ -692,48 +728,57 @@ due to administrative connections over LDAPS on ports 1636 and 4444.</para> <para>Create access log filtering criteria rules.</para> <screen>$ dsconfig create-access-log-filtering-criteria --port 4444 --hostname opendj.example.com --bindDN "cn=Directory Manager" --bindPassword password --publisher-name "File-Based Access Logger" --criteria-name "Exclude LDAPS on 1636 and 4444" --type generic --set connection-port-equal-to:1636 --set connection-port-equal-to:4444 --set connection-protocol-equal-to:ldaps --trustAll --no-prompt</screen> <screen> $ <userinput>dsconfig \ create-access-log-filtering-criteria \ --port 4444 \ --hostname opendj.example.com \ --bindDN "cn=Directory Manager" \ --bindPassword password \ --publisher-name "File-Based Access Logger" \ --criteria-name "Exclude LDAPS on 1636 and 4444" \ --type generic \ --set connection-port-equal-to:1636 \ --set connection-port-equal-to:4444 \ --set connection-protocol-equal-to:ldaps \ --trustAll \ --no-prompt</userinput> </screen> <para>Activate filtering to exclude messages from the default access log according to the criteria you specified.</para> <screen>$ dsconfig set-log-publisher-prop --port 4444 --hostname opendj.example.com --bindDN "cn=Directory Manager" --bindPassword password --publisher-name "File-Based Access Logger" --set filtering-policy:exclusive --trustAll --no-prompt</screen> <screen> $ <userinput>dsconfig \ set-log-publisher-prop \ --port 4444 \ --hostname opendj.example.com \ --bindDN "cn=Directory Manager" \ --bindPassword password \ --publisher-name "File-Based Access Logger" \ --set filtering-policy:exclusive \ --trustAll \ --no-prompt</userinput> </screen> <para>At this point, OpenDJ filters out connections over LDAPS to ports 1636 and 4444. While performing operations in OpenDJ Control Panel, if you perform a simple <command>ldapsearch --port 1389 --baseDN dc=example,dc=com uid=bjensen cn</command>, then all you see in the access log is the effect of the <command>ldapsearch</command> command.</para> <screen>$ tail -f /path/to/opendj/logs/access [19/Oct/2011:16:37:16 +0200] CONNECT conn=8 from=127.0.0.1:54165 <screen> $ <userinput>tail -f /path/to/opendj/logs/access</userinput> <computeroutput>[19/Oct/2011:16:37:16 +0200] CONNECT conn=8 from=127.0.0.1:54165 to=127.0.0.1:1389 protocol=LDAP [19/Oct/2011:16:37:16 +0200] SEARCH REQ conn=8 op=0 msgID=1 base="dc=example,dc=com" scope=wholeSubtree filter="(uid=bjensen)" attrs="cn" [19/Oct/2011:16:37:16 +0200] SEARCH RES conn=8 op=0 msgID=1 result=0 nentries=1 etime=14 [19/Oct/2011:16:37:16 +0200] UNBIND REQ conn=8 op=1 msgID=2 [19/Oct/2011:16:37:16 +0200] DISCONNECT conn=8 reason="Client Unbind"</screen> [19/Oct/2011:16:37:16 +0200] DISCONNECT conn=8 reason="Client Unbind"</computeroutput> </screen> </example> <para>In addition to the filtering policy, you can also adjust how OpenDJ @@ -756,45 +801,50 @@ events. Yet alert notifications are not enabled by default. You can use the <command>dsconfig</command> command to enable alert notifications.</para> <screen>$ dsconfig set-alert-handler-prop --port 4444 --hostname opendj.example.com --bindDN "cn=Directory Manager" --bindPassword password --handler-name "JMX Alert Handler" --set enabled:true --trustAll --no-prompt</screen> <screen> $ <userinput>dsconfig \ set-alert-handler-prop \ --port 4444 \ --hostname opendj.example.com \ --bindDN "cn=Directory Manager" \ --bindPassword password \ --handler-name "JMX Alert Handler" \ --set enabled:true \ --trustAll \ --no-prompt</userinput> </screen> <para>OpenDJ can also send mail over SMTP instead of JMX notifications. Before you set up the SMTP-based alert handler, you must identify an SMTP server to which OpenDJ sends messages.</para> <screen>$ dsconfig set-global-configuration-prop --port 4444 --hostname opendj.example.com --bindDN "cn=Directory Manager" --bindPassword password --set smtp-server:smtp.example.com --trustAll --no-prompt $ dsconfig create-alert-handler --port 4444 --hostname opendj.example.com --bindDN "cn=Directory Manager" --bindPassword password --handler-name "SMTP Alert Handler" --type smtp --set enabled:true --set message-subject:"OpenDJ Alert, Type: %%alert-type%%, ID: %%alert-id%%" --set message-body:"%%alert-message%%" --set recipient-address:kvaughan@example.com --set sender-address:opendj@example.com --trustAll --no-prompt</screen> <screen> $ <userinput>dsconfig \ set-global-configuration-prop \ --port 4444 \ --hostname opendj.example.com \ --bindDN "cn=Directory Manager" \ --bindPassword password \ --set smtp-server:smtp.example.com \ --trustAll \ --no-prompt</userinput> $ <userinput>dsconfig \ create-alert-handler \ --port 4444 \ --hostname opendj.example.com \ --bindDN "cn=Directory Manager" \ --bindPassword password \ --handler-name "SMTP Alert Handler" \ --type smtp \ --set enabled:true \ --set message-subject:"OpenDJ Alert, Type: %%alert-type%%, ID: %%alert-id%%" \ --set message-body:"%%alert-message%%" \ --set recipient-address:kvaughan@example.com \ --set sender-address:opendj@example.com \ --trustAll \ --no-prompt</userinput> </screen> <variablelist xml:id="alert-types"> <title>Alert Types</title>
