Draft tools ref complete for Admin and Dev guides

Mark Craig

21.32.2011 def05ed8de5b653d3fed997ca56444e4f60a4dca

 opendj3/src/main/docbkx/shared/man-setup.xml

@@ -35,72 +35,309 @@
 </refmeta>
 <refnamediv>
  <refname>setup</refname>
  <refpurpose>TODO one-line description</refpurpose>
  <refpurpose>install OpenDJ directory server</refpurpose>
 </refnamediv>
 <refsynopsisdiv>
  <cmdsynopsis>
   <command>setup</command>
   <command><replaceable>subcommand</replaceable></command>
   <arg choice="opt">--options</arg>
   <arg choice="opt">options</arg>
  </cmdsynopsis>
 </refsynopsisdiv>
 <refsect1>
  <title>Description</title>
  <para>TODO description.</para>
  <para>This utility can be used to setup the directory server.</para>
 </refsect1>
 <refsect1>
  <title>Global Options</title>
  <para>The following global options are supported.</para>
  <title>Options</title>
  <para>The following options are supported.</para>
  <variablelist>
   <varlistentry>
    <term><option>TODO</option></term>
    <term><option>-a, --addBaseEntry</option></term>
    <listitem>
     <para>TODO Description.</para>
     <para>Indicates whether to create the base entry in the directory server
     database</para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term><option>--adminConnectorPort {port}</option></term>
    <listitem>
     <para>Port on which the Administration Connector should listen for
     communication</para>
     <para>Default value: 4444</para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term><option>-b, --baseDN {baseDN}</option></term>
    <listitem>
     <para>Base DN for user information in the directory server. Multiple base
     DNs may be provided by using this option multiple times</para>
     <para>Default value: dc=example,dc=com</para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term><option>-d, --sampleData {numEntries}</option></term>
    <listitem>
     <para>Specifies that the database should be populated with the specified
     number of sample entries</para>
     <para>Default value: 0</para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term><option>-D, --rootUserDN {rootUserDN}</option></term>
    <listitem>
     <para>DN for the initial root user for the directory server</para>
     <para>Default value: cn=Directory Manager</para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term><option>--generateSelfSignedCertificate</option></term>
    <listitem>
     <para>Generate a self-signed certificate that the server should use when
     accepting SSL-based connections or performing StartTLS negotiation</para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term><option>-h, --hostname {host}</option></term>
    <listitem>
     <para>Directory server host name or IP address that will be used to
     generate the self-signed certificate.  This argument will be taken into
     account only if the self-signed certificate argument
     generateSelfSignedCertificate is specified</para>
     <para>Default value: localhost.localdomain</para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term><option>-i, --cli</option></term>
    <listitem>
     <para>Use the command line install. If not specified the graphical
     interface will be launched.  The rest of the options (excluding help and
     version) will only be taken into account if this option is specified</para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term><option>-j, --rootUserPasswordFile {rootUserPasswordFile}</option></term>
    <listitem>
     <para>Path to a file containing the password for the initial root user for
     the directory server</para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term><option>-l, --ldifFile {ldifFile}</option></term>
    <listitem>
     <para>Path to an LDIF file containing data that should be added to the
     directory server database. Multiple LDIF files may be provided by using
     this option multiple times</para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term><option>-N, --certNickname {nickname}</option></term>
    <listitem>
     <para>Nickname of the certificate that the server should use when
     accepting SSL-based connections or performing StartTLS negotiation</para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term><option>-O, --doNotStart</option></term>
    <listitem>
     <para>Do not start the server when the configuration is completed</para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term><option>-p, --ldapPort {port}</option></term>
    <listitem>
     <para>Port on which the Directory Server should listen for LDAP
     communication</para>
     <para>Default value: 389</para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term><option>-q, --enableStartTLS</option></term>
    <listitem>
     <para>Enable StartTLS to allow secure communication with the server using
     the LDAP port</para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term><option>-R, --rejectFile {rejectFile}</option></term>
    <listitem>
     <para>Write rejected entries to the specified file</para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term><option>-S, --skipPortCheck</option></term>
    <listitem>
     <para>Skip the check to determine whether the specified ports are
     usable</para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term><option>--skipFile {skipFile}</option></term>
    <listitem>
     <para>Write skipped entries to the specified file</para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term><option>-u, --keyStorePasswordFile {keyStorePasswordFile}</option></term>
    <listitem>
     <para>Certificate key store PIN file.  A PIN is required when you specify
     to use an existing certificate (JKS, JCEKS, PKCS#12 or PKCS#11) as server
     certificate</para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term><option>--useJavaKeystore {keyStorePath}</option></term>
    <listitem>
     <para>Path of a Java Key Store (JKS) containing a certificate to be used
     as the server certificate</para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term><option>--useJCEKS {keyStorePath}</option></term>
    <listitem>
     <para>Path of a JCEKS containing a certificate to be used as the server
    certificate</para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term><option>--usePkcs11Keystore</option></term>
    <listitem>
     <para>Use a certificate in a PKCS#11 token that the server should use when
    accepting SSL-based connections or performing StartTLS negotiation</para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term><option>--usePkcs12keyStore {keyStorePath}</option></term>
    <listitem>
     <para>Path of a PKCS#12 key store containing the certificate that the
     server should use when accepting SSL-based connections or performing
     StartTLS negotiation</para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term><option>-w, --rootUserPassword {rootUserPassword}</option></term>
    <listitem>
     <para>Password for the initial root user for the Directory Server</para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term><option>-W, --keyStorePassword {keyStorePassword}</option></term>
    <listitem>
     <para>Certificate key store PIN.  A PIN is required when you specify
     to use an existing certificate (JKS, JCEKS, PKCS#12 or PKCS#11) as server
     certificate</para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term><option>-x, --jmxPort {jmxPort}</option></term>
    <listitem>
     <para>Port on which the Directory Server should listen for JMX
     communication</para>
     <para>Default value: 1689</para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term><option>-Z, --ldapsPort {port}</option></term>
    <listitem>
     <para>Port on which the Directory Server should listen for LDAPS
     communication. The LDAPS port will be configured and SSL will be enabled
     only if this argument is explicitly specified</para>
     <para>Default value: 636</para>
    </listitem>
   </varlistentry>
  </variablelist>
 </refsect1>
 <refsect1>
  <title>Subcommands</title>
  <para>The following subcommands are supported.</para>
  <refsect2>
   <para>TODO Description.</para>
   <cmdsynopsis>
    <command>setup</command>
    <command>TODO</command>
    <arg choice="opt">--options</arg>
   </cmdsynopsis>
   <title>Utility Input/Output Options</title>
   <variablelist>
    <varlistentry>
     <term><option>TODO</option></term>
     <term><option>-n, --no-prompt</option></term>
     <listitem>
      <para>TODO description.</para>
      <para>Use non-interactive mode.  If data in the command is missing, the
      user is not prompted and the tool will fail</para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><option>--noPropertiesFile</option></term>
     <listitem>
      <para>No properties file will be used to get default command line
      argument values</para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><option>--propertiesFilePath {propertiesFilePath}</option></term>
     <listitem>
      <para>Path to the file containing default property values used for
      command line arguments</para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><option>-Q, --quiet</option></term>
     <listitem>
      <para>Run setup in quiet mode.  Quiet mode will not output progress
      information to standard output</para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><option>-v, --verbose</option></term>
     <listitem>
      <para>Use verbose mode</para>
     </listitem>
    </varlistentry>
   </variablelist>
  </refsect2>
  <refsect2>
   <title>General Options</title>
   <variablelist>
    <varlistentry>
     <term><option>-V, --version</option></term>
     <listitem>
      <para>Display version information</para>
     </listitem>
    </varlistentry>
     <varlistentry>
     <term><option>-?, -H, --help</option></term>
     <listitem>
      <para>Display usage information</para>
     </listitem>
    </varlistentry>
   </variablelist>
  </refsect2>
 </refsect1>
 <refsect1>
  <title>Files</title>
  <para>TODO if command has configuration file.</para>
 </refsect1>
 <refsect1>
  <title>Environment</title>
  <para>TODO if command reads environment variables.</para>
 </refsect1>
 <refsect1>
  <title>Exit Codes</title>
   <variablelist>
    <varlistentry>
     <term>TODO exit code</term>
     <listitem>
      <para>TODO description.</para>
     </listitem>
    </varlistentry>
   </variablelist>
  <variablelist>
   <varlistentry>
    <term>0</term>
    <listitem>
     <para>The command completed successfully.</para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term>&gt; 0</term>
    <listitem>
     <para>An error occurred.</para>
    </listitem>
   </varlistentry>
  </variablelist>
 </refsect1>
 <refsect1>
  <title>Examples</title>
  <para>TODO</para>
  <para>The following command installs OpenDJ directory server, enabling
  StartTLS and importing 100 example entries without interaction.</para>
  <screen width="80">$ ./OpenDJ/setup --cli -b dc=example,dc=com -d 100 -D "cn=Directory Manager" \
&gt; -w password -h `hostname` -p 1389 \
&gt; --generateSelfSignedCertificate --enableStartTLS -n 

OpenDJ <?eval ${project.version}?>
Please wait while the setup program initializes...

See /var/.../opends-setup-484...561.log for a detailed log of this operation.

Configuring Directory Server ..... Done.
Configuring Certificates ..... Done.
Importing Automatically-Generated Data (100 Entries) ......... Done.
Starting Directory Server .......... Done.

To see basic server configuration status and configuration you can launch
 /path/to/OpenDJ/bin/status</screen>
 </refsect1>
</refentry>