Fix for OPENDJ-321: Expand dsconfig reference with more examples and descri...

Mark Craig

19.13.2011 cbab2599fe87dac1e8267802408f3046316224ca

Fix for OPENDJ-321: Expand dsconfig reference with more examples and descriptions of subcommands

Initial hand-written updates to the reference.
Still TODO is the full list of subcommands.

 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

&gt;&gt;&gt;&gt; OpenDS configuration console main menu
&gt;&gt;&gt;&gt; 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>