From ae57abea41b1a1c805fee27ffcfeabc0ae07e969 Mon Sep 17 00:00:00 2001
From: Mark Craig <mark.craig@forgerock.com>
Date: Mon, 31 Mar 2014 07:17:12 +0000
Subject: [PATCH] Backport CR-3283 Fix for Server docs patch for OPENDJ-980: Allow copy/ paste of formatted shell commands; OPENDJ-1376: Add <userinput> and potential <computeroutput> to <screen> content
---
opends/src/main/docbkx/admin-guide/chap-monitoring.xml | 418 +++++++++++++++++++++++++++++++++--------------------------
1 files changed, 234 insertions(+), 184 deletions(-)
diff --git a/opends/src/main/docbkx/admin-guide/chap-monitoring.xml b/opends/src/main/docbkx/admin-guide/chap-monitoring.xml
index f3b7c4c..2091319 100644
--- a/opends/src/main/docbkx/admin-guide/chap-monitoring.xml
+++ b/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>
--
Gitblit v1.10.0