From cbab2599fe87dac1e8267802408f3046316224ca Mon Sep 17 00:00:00 2001
From: Mark Craig <mark.craig@forgerock.com>
Date: Wed, 19 Oct 2011 09:13:11 +0000
Subject: [PATCH] Fix for OPENDJ-321: Expand dsconfig reference with more examples and descriptions of subcommands
---
opendj3/src/main/docbkx/shared/man-dsconfig.xml | 170 +++++++++++++++++++++++++++++++++++++++++++++++++++-----
1 files changed, 153 insertions(+), 17 deletions(-)
diff --git a/opendj3/src/main/docbkx/shared/man-dsconfig.xml b/opendj3/src/main/docbkx/shared/man-dsconfig.xml
index 3b367ba..15f85ff 100644
--- a/opendj3/src/main/docbkx/shared/man-dsconfig.xml
+++ b/opendj3/src/main/docbkx/shared/man-dsconfig.xml
@@ -39,61 +39,107 @@
</refnamediv>
<refsynopsisdiv>
<cmdsynopsis>
- <command>dsconfig</command>
- <command><replaceable>subcommand</replaceable></command>
+ <command>dsconfig <replaceable>subcommand</replaceable></command>
<arg choice="req">options</arg>
</cmdsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Description</title>
- <para>This utility can be used to define a base configuration for the
- directory server.</para>
+ <para>This utility serves to configure a running directory server.</para>
+
+ <para>The <command>dsconfig</command> command is the primary command-line tool
+ for viewing and editing OpenDJ configuration. When started without arguments,
+ <command>dsconfig</command> prompts you for administration connection
+ information, including the host name, administration port number,
+ administrator bind DN and administrator password. The
+ <command>dsconfig</command> command then connects securely to the directory
+ server over the administration port. Once connected it presents you with a
+ menu-driven interface to the server configuration.</para>
+
+ <para>When you pass connection information, subcommands, and additional
+ options to <command>dsconfig</command>, the command runs in script mode and
+ so is not interactive, though it can prompt you to ask whether to apply
+ changes and whether to trust certificates (unless you use the
+ <option>--no-prompt</option> and <option>--trustAll</option> options,
+ respectively).</para>
+
+ <para>You can prepare <command>dsconfig</command> batch scripts by running
+ the tool with the <option>--commandFilePath</option> option in interactive
+ mode, then reading from the batch file with the <option>--batchFile</option>
+ option in script mode. Batch files can be useful when you have many
+ <command>dsconfig</command> commands to run and want to avoid starting
+ the JVM and setting up a new connection for each command.</para>
+
+ <para>The <command>dsconfig</command> command categorizes directory server
+ configuration by <firstterm>components</firstterm>, also called
+ <firstterm>managed objects</firstterm>. Actual components often inherit from
+ a parent component type. For example, one component is a Connection Handler.
+ An LDAP Connection Handler is a type of Connection Handler. You configure the
+ LDAP Connection Handler component to specify how OpenDJ directory server
+ handles LDAP connections coming from client applications.</para>
+
+ <para>Configuration components have <firstterm>properties</firstterm>.
+ For example, the LDAP Connection Handler component has properties such as
+ <literal>listen-port</literal> and <literal>allow-start-tls</literal>. You
+ can set the component's <literal>listen-port</literal> property to
+ <literal>389</literal> to use the default LDAP port number. You can set the
+ component's <literal>allow-start-tls</literal> property to
+ <literal>true</literal> to permit LDAP client applications to use StartTLS.
+ Much of the configuration you do with <command>dsconfig</command> involves
+ setting component properties. The <citetitle>OpenDJ Configuration
+ Reference</citetitle> covers all <command>dsconfig</command> component
+ properties in detail, drawing on the documentation you also view when
+ getting help through the <command>dsconfig</command> command.</para>
+ <!-- TODO: Add olink to configuration reference -->
</refsect1>
- <refsect1>
- <title>Subcommands</title>
+ <refsect1 xml:id="dsconfig-getting-help">
+ <title>Getting Help</title>
<para>The <command>dsconfig</command> command provides many subcommands.
Use the following options to view help for subcommands.</para>
+ <para>See <link linkend="dsconfig-subcommands-ref"><citetitle>dsconfig
+ Subcommands</citetitle></link> for details of individual subcommands.</para>
+
<variablelist>
<varlistentry>
- <term><option>--help-all</option></term>
+ <term><command>dsconfig --help-all</command></term>
<listitem>
<para>Display all subcommands</para>
</listitem>
</varlistentry>
<varlistentry>
- <term><option>--help-core-server</option></term>
+ <term><command>dsconfig --help-core-server</command></term>
<listitem>
<para>Display subcommands relating to core server</para>
</listitem>
</varlistentry>
<varlistentry>
- <term><option>--help-database</option></term>
+ <term><command>dsconfig --help-database</command></term>
<listitem>
<para>Display subcommands relating to caching and back-ends</para>
</listitem>
</varlistentry>
<varlistentry>
- <term><option>--help-logging</option></term>
+ <term><command>dsconfig --help-logging</command></term>
<listitem>
<para>Display subcommands relating to logging</para>
</listitem>
</varlistentry>
<varlistentry>
- <term><option>--help-replication</option></term>
+ <term><command>dsconfig --help-replication</command></term>
<listitem>
<para>Display subcommands relating to replication</para>
</listitem>
</varlistentry>
<varlistentry>
- <term><option>--help-security</option></term>
+ <term><command>dsconfig --help-security</command></term>
<listitem>
<para>Display subcommands relating to authentication and authorization</para>
</listitem>
</varlistentry>
<varlistentry>
- <term><option>--help-user-management</option></term>
+ <term><command>dsconfig --help-user-management</command></term>
<listitem>
<para>Display subcommands relating to user management</para>
</listitem>
@@ -104,10 +150,14 @@
<replaceable>subcommand</replaceable> --help</command>, or start
<command>dsconfig</command> in interactive mode, without specifying a
subcommand.</para>
+
+ <para>To view component properties, use the <command>dsconfig
+ list-properties</command> command.</para>
</refsect1>
- <refsect1>
- <title>Options</title>
- <para>The following options are supported.</para>
+ <refsect1 xml:id="dsconfig-general-options">
+ <title>Generally Applicable Options</title>
+ <para>The following options are supported for all <command>dsconfig</command>
+ subcommands.</para>
<variablelist>
<varlistentry>
<term><option>--advanced</option></term>
@@ -304,6 +354,24 @@
</variablelist>
</refsect2>
</refsect1>
+ <refsect1 xml:id="dsconfig-subcommands-ref">
+ <title>dsconfig Subcommands</title>
+ <para>This section covers individual <command>dsconfig</command>
+ subcommands.</para>
+
+ <para>Subcommands let you create, list, and delete entire configuration
+ components, and also let you get and set component properties. Subcommands
+ therefore have names that reflect these five actions.</para>
+ <itemizedlist>
+ <listitem><para>create-<replaceable>component</replaceable></para></listitem>
+ <listitem><para>list-<replaceable>component</replaceable>s</para></listitem>
+ <listitem><para>delete-<replaceable>component</replaceable></para></listitem>
+ <listitem><para>get-<replaceable>component</replaceable>-prop</para></listitem>
+ <listitem><para>set-<replaceable>component</replaceable>-prop</para></listitem>
+ </itemizedlist>
+
+ <!-- TODO: OPENDJ-321: Expand dsconfig reference with more examples and descriptions of subcommands -->
+ </refsect1>
<refsect1>
<title>Exit Codes</title>
<variablelist>
@@ -323,11 +391,15 @@
</refsect1>
<refsect1>
<title>Examples</title>
+ <para>Much of the <citetitle>OpenDJ Administration Guide</citetitle> consists
+ of <command>dsconfig</command> examples with text in between. This section
+ therefore remains short.</para>
+
<para>The following example starts <command>dsconfig</command> in interactive,
menu-driven mode on the default port of the current host.</para>
<screen>$ dsconfig -h `hostname` -p 4444 -D "cn=Directory Manager" -w password
->>>> OpenDS configuration console main menu
+>>>> OpenDJ configuration console main menu
What do you want to configure?
@@ -357,5 +429,69 @@
q) quit
Enter choice: </screen>
+
+ <para>The following examples demonstrates generating a batch file that
+ corresponds to an interactive session enabling the debug log. The example
+ then demonstates using a modified batch file to disable the debug log.</para>
+ <screen>$ dsconfig
+ --hostname `hostname`
+ --port 4444
+ --bindDN "cn=Directory Manager"
+ --bindPassword password
+ --commandFilePath ~/enable-debug-log.batch
+ ...
+$ cat ~/enable-debug-log.batch
+# dsconfig session start date: 19/Oct/2011:08:52:22 +0000
+
+# Session operation number: 1
+# Operation date: 19/Oct/2011:08:55:06 +0000
+dsconfig set-log-publisher-prop \
+ --publisher-name File-Based\ Debug\ Logger \
+ --set enabled:true \
+ --hostname opendj.example.com \
+ --port 4444 \
+ --trustStorePath /path/to/OpenDJ/config/admin-truststore \
+ --bindDN cn=Directory\ Manager \
+ --bindPassword ****** \
+ --no-prompt
+
+$ cp ~/enable-debug-log.batch ~/disable-debug-log.batch
+$ vi ~/disable-debug-log.batch
+$ cat ~/disable-debug-log.batch
+set-log-publisher-prop \
+ --publisher-name File-Based\ Debug\ Logger \
+ --set enabled:false \
+ --hostname opendj.example.com \
+ --port 4444 \
+ --trustStorePath /path/to/OpenDJ/config/admin-truststore \
+ --bindDN cn=Directory\ Manager \
+ --bindPassword password \
+ --no-prompt
+
+$ dsconfig --batchFilePath ~/disable-debug-log.batch --no-prompt
+set-log-publisher-prop
+--publisher-name
+File-Based Debug Logger
+--set
+enabled:false
+--hostname
+Mark-Craigs-iMac.local
+--port
+4444
+--trustStorePath
+/path/to/OpenDJ/config/admin-truststore
+--bindDN
+cn=Directory Manager
+--bindPassword
+password
+--no-prompt
+
+$</screen>
+ <para>Notice that the original command file looks like a shell script with
+ the bind password value replaced by asterisks. To pass the content as batch
+ file to <command>dsconfig</command>, strip <literal>dsconfig</literal>
+ itself, and include the bind password for the administrative user (or
+ replace that option with an alternative, such as reading the password from
+ a file).</para>
</refsect1>
</refentry>
--
Gitblit v1.10.0