<?xml version="1.0" encoding="UTF-8"?>

<refentry xml:id="dsconfig-1" xmlns="http://docbook.org/ns/docbook"

version="5.0" xml:lang="en"

xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

xsi:schemaLocation="http://docbook.org/ns/docbook http://docbook.org/xml/5.0/xsd/docbook.xsd"

xmlns:xlink="http://www.w3.org/1999/xlink"

xmlns:xi="http://www.w3.org/2001/XInclude">

<xi:include href="common.xml" xpointer='xpointer(//info[@name="info"])'/>

<refmeta>

<refentrytitle><application>dsconfig</application></refentrytitle>

<xi:include href="common.xml" xpointer='xpointer(//manvolnum[@name="v1m"])'/>

</refmeta>

<refnamediv>

<refname><application>dsconfig</application></refname>

<refpurpose>manage OpenDJ directory server configuration</refpurpose>

</refnamediv>

<refsynopsisdiv>

<cmdsynopsis>

<command>dsconfig</command>

<arg choice="opt"><replaceable>subcommand</replaceable></arg>

<arg choice="opt"><replaceable>subcommand_opts</replaceable></arg>

<arg>--advanced</arg>

<arg>-I <replaceable class="parameter">adminUID</replaceable></arg>

<sbr/><sbr/>

<xi:include href="common.xml"

xpointer='xpointer(//para[@name="s-remote"]/*)'/>

<xi:include href="common.xml"

xpointer='xpointer(//para[@name="s-auth"]/*[not(@name="sc-dn")])'/>

<sbr/><sbr/>

<arg>-F <replaceable>batchFile</replaceable></arg>

<arg>--displayCommand</arg>

<arg>--commandFilePath <replaceable class="parameter">path</replaceable></arg>

<arg>-n</arg>

<xi:include href="common.xml"

xpointer='xpointer(//para[@name="s-props"]/*)'/>

<xi:include href="common.xml"

xpointer='xpointer(//para[@name="s-misc"]/*[not(@name="sc-enc")])'/>

<xi:include href="common.xml"

xpointer='xpointer(//para[@name="s-general"]/*)'/>

</cmdsynopsis>

</refsynopsisdiv>

<refsection>

<title>Description</title>

<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 into <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 <link

xlink:href="http://opendj.forgerock.org/opendj-server/configref/index.html"

><citetitle>OpenDJ Configuration Reference</citetitle></link> 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>

</refsection>

<refsection 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><command>dsconfig --help-all</command></term>

<listitem>

<para>Display all subcommands</para>

</listitem>

</varlistentry>

<varlistentry>

<term><command>dsconfig --help-core-server</command></term>

<listitem>

<para>Display subcommands relating to core server</para>

</listitem>

</varlistentry>

<varlistentry>

<term><command>dsconfig --help-database</command></term>

<listitem>

<para>Display subcommands relating to caching and back-ends</para>

</listitem>

</varlistentry>

<varlistentry>

<term><command>dsconfig --help-logging</command></term>

<listitem>

<para>Display subcommands relating to logging</para>

</listitem>

</varlistentry>

<varlistentry>

<term><command>dsconfig --help-replication</command></term>

<listitem>

<para>Display subcommands relating to replication</para>

</listitem>

</varlistentry>

<varlistentry>

<term><command>dsconfig --help-security</command></term>

<listitem>

<para>Display subcommands relating to authentication and authorization</para>

</listitem>

</varlistentry>

<varlistentry>

<term><command>dsconfig --help-user-management</command></term>

<listitem>

<para>Display subcommands relating to user management</para>

</listitem>

</varlistentry>

</variablelist>

<para>

For help with individual subcommands, either use <command>dsconfig <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>

</refsection>

<refsection 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>

<listitem>

<para>

Allows the configuration of advanced components and properties.

</para>

</listitem>

</varlistentry>

</variablelist>

<refsection>

<title>LDAP Connection Options</title>

<variablelist>

<xi:include href="common.xml"

xpointer='xpointer(//para[@name="l-remote"]/*)'/>

<varlistentry>

<term><option>-I, --adminUID</option> <replaceable

class="parameter">adminUID</replaceable></term>

<listitem>

<para>

User ID of the global administrator to use to bind to the server. For the

<command>enable</command> subcommand, if no global administrator was defined

previously for any servers, the global administrator will be created using the

UID provided. (Default: admin).

</para>

</listitem>

</varlistentry>

<xi:include href="common.xml"

xpointer='xpointer(//para[@name="l-auth"]/*[not(@name="lc-dn")])'/>

</variablelist>

</refsection>

<refsection>

<title>Utility Input/Output Options</title>

<variablelist>

<varlistentry>

<term><option>--commandFilePath</option> <replaceable

class="parameter">path</replaceable></term>

<listitem>

<para>

The full path to the file where the equivalent non-interactive commands will be

written when this command is run in interactive mode.

</para>

</listitem>

</varlistentry>

<varlistentry>

<term><option>--displayCommand</option></term>

<listitem>

<para>

Display the equivalent non-interactive option on standard output when this

command is run in interactive mode.</para>

</listitem>

</varlistentry>

<varlistentry>

<term><option>-F, --batchFilePath</option> <replaceable

class="parameter">batchFilePath</replaceable></term>

<listitem>

<para>

Path to a batch file containing a set of dsconfig commands to be executed.

</para>

</listitem>

</varlistentry>

<varlistentry>

<term><option>-n, --no-prompt</option></term>

<listitem>

<para>

Use non-interactive mode. If data in the command is missing, the user is not

prompted and the command exits with an error.

</para>

</listitem>

</varlistentry>

<xi:include href="common.xml"

xpointer='xpointer(//para[@name="l-props"]/*)'/>

<xi:include href="common.xml"

xpointer='xpointer(//para[@name="l-misc"]/*[not(@name="lc-enc")])'/>

</variablelist>

</refsection>

<refsection>

<title>General Options</title>

<variablelist>

<xi:include href="common.xml"

xpointer='xpointer(//para[@name="l-general"]/*)'/>

</variablelist>

</refsection>

</refsection>

<refsection 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>

<para>

Component properties for the <command>dsconfig</command> command are covered in

the <link

xlink:href="http://opendj.forgerock.org/opendj-server/configref/index.html"

><citetitle>OpenDJ Configuration Reference</citetitle></link>.

</para>

<para>

Many subcommands let you set property values. Notice in the reference for the

subcommands below that specific options are available for handling multi-valued

properties. Whereas you can assign a single property value using the

<option>--set</option> option, you assign multiple values to a multi-valued

property using the <option>--add</option> option. You can reset the values of

the multi-valued property using the <option>--reset</option> option.

</para>

<itemizedlist>

<para>

Some property values take a time duration. Durations are expressed as numbers

followed by units. For example <literal>1 s</literal> means one second, and

<literal>2 w</literal> means two weeks. Some durations have minimum granularity

or maximum units, so you cannot necessary specify every duration in milliseconds

or weeks for example. Some durations allow you to use a special value to mean

unlimited. Units are specified as follows.

</para>

<listitem>

<para><literal>ms</literal>: milliseconds</para>

</listitem>

<listitem>

<para><literal>s</literal>: seconds</para>

</listitem>

<listitem>

<para><literal>m</literal>: minutes</para>

</listitem>

<listitem>

<para><literal>h</literal>: hours</para>

</listitem>

<listitem>

<para><literal>d</literal>: days</para>

</listitem>

<listitem>

<para><literal>w</literal>: weeks</para>

</listitem>

</itemizedlist>

<xi:include href="scmd-dsconfig.xml" xpointer='xpointer(//refsection)'/>

</refsection>

<refsection>

<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>

<informalexample>

<para>

The following example starts <command>dsconfig</command> in interactive,

menu-driven mode on the default port of the current host.

</para>

<literallayout><prompt

>$ </prompt><command>dsconfig -h `hostname` -p 4444 -D "cn=Directory Manager" \

-w password</command></literallayout>

<screen>

&gt;&gt;&gt;&gt; OpenDJ configuration console main menu

What do you want to configure?

1) Access Control Handler 21) Log Publisher

2) Access Log Filtering Criteria 22) Log Retention Policy

3) Account Status Notification Handler 23) Log Rotation Policy

4) Administration Connector 24) Matching Rule

5) Alert Handler 25) Monitor Provider

6) Attribute Syntax 26) Password Generator

7) Backend 27) Password Policy

8) Certificate Mapper 28) Password Storage Scheme

9) Connection Handler 29) Password Validator

10) Crypto Manager 30) Plugin

11) Debug Target 31) Plugin Root

12) Entry Cache 32) Replication Domain

13) Extended Operation Handler 33) Replication Server

14) External Changelog Domain 34) Root DN

15) Global Configuration 35) Root DSE Backend

16) Group Implementation 36) SASL Mechanism Handler

17) Identity Mapper 37) Synchronization Provider

18) Key Manager Provider 38) Trust Manager Provider

19) Local DB Index 39) Virtual Attribute

20) Local DB VLV Index 40) Work Queue

q) quit

Enter choice:

</screen>

</informalexample>

<informalexample>

<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>

<literallayout><prompt

>$ </prompt><command>dsconfig --hostname `hostname` --port 4444 \

--bindDN "cn=Directory Manager" --bindPassword password \

--commandFilePath ~/enable-debug-log.batch ...</command>

<prompt>$ </prompt><command>cat ~/enable-debug-log.batch</command></literallayout>

<programlisting>

# 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 $OpenDJ/config/admin-truststore \

--bindDN cn=Directory\ Manager \

--bindPassword ****** \

--no-prompt

</programlisting>

<literallayout><prompt

>$ </prompt><command>cp ~/enable-debug-log.batch ~/disable-debug-log.batch</command>

<prompt>$ </prompt><command>vi ~/disable-debug-log.batch</command>

<prompt>$ </prompt><command>cat ~/disable-debug-log.batch</command></literallayout>

<programlisting>

set-log-publisher-prop \

--publisher-name File-Based\ Debug\ Logger \

--set enabled:false \

--hostname opendj.example.com \

--port 4444 \

--trustStorePath $OpenDJ/config/admin-truststore \

--bindDN cn=Directory\ Manager \

--bindPassword password \

--no-prompt

</programlisting>

<literallayout><prompt

>$ </prompt><command>dsconfig --batchFilePath ~/disable-debug-log.batch --no-prompt</command></literallayout>

<screen>

set-log-publisher-prop

--publisher-name

File-Based Debug Logger

--set

enabled:false

--hostname

--port

4444

--trustStorePath

$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 a 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>

</informalexample>

</refsection>

<xi:include href="common.xml" xpointer='xpointer(//refsection[@name="env"])'/>

<xi:include href="common.xml" xpointer='xpointer(//refsection[@name="exit-0-gt0"])'/>

<xi:include href="common.xml" xpointer='xpointer(//refsection[@name="seeAlso"])'/>

</refentry>