mirror of https://github.com/OpenIdentityPlatform/OpenDJ.git
opends/resource/man/man1/dsconfig.1
@@ -1,48 +1,526 @@ '\" te .\" Copyright (c) 2008, Sun Microsystems Inc. All .\" Rights Reserved. .TH dsconfig 1 "December 2008" "1.1" "User Commands" .SH NAME dsconfig \- configures a directory server instance .SH SYNOPSIS .LP '\" t .\" Title: dsconfig .\" Author: Mark Craig .\" Generator: DocBook XSL-NS Stylesheets v1.76.1 <http://docbook.sf.net/> .\" Date: October\ \&20,\ \&2011 .\" Manual: Tools Reference .\" Source: OpenDJ 2.5.0 .\" Language: English .\" .TH "DSCONFIG" "1" "October\ \&20,\ \&2011" "OpenDJ 2.5.0" "Tools Reference" .\" ----------------------------------------------------------------- .\" * Define some portability stuff .\" ----------------------------------------------------------------- .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .\" http://bugs.debian.org/507673 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" ----------------------------------------------------------------- .\" * set default formatting .\" ----------------------------------------------------------------- .\" disable hyphenation .nh .\" disable justification (adjust text to left margin only) .ad l .\" ----------------------------------------------------------------- .\" * MAIN CONTENT STARTS HERE * .\" ----------------------------------------------------------------- .SH "NAME" dsconfig \- manage OpenDJ directory server configuration .SH "SYNOPSIS" .HP \w'\fBdsconfig\ [\fR\fB\fIsubcommand\fR\fR\fB]\fR\ 'u \fBdsconfig [\fR\fB\fIsubcommand\fR\fR\fB]\fR [options] .SH "DESCRIPTION" .PP This utility serves to configure a running directory server\&. .PP The \fBdsconfig\fR command is the primary command\-line tool for viewing and editing OpenDJ configuration\&. When started without arguments, \fBdsconfig\fR prompts you for administration connection information, including the host name, administration port number, administrator bind DN and administrator password\&. The \fBdsconfig\fR 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\&. .PP When you pass connection information, subcommands, and additional options to \fBdsconfig\fR, 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 \fB\-\-no\-prompt\fR and \fB\-\-trustAll\fR options, respectively)\&. .PP You can prepare \fBdsconfig\fR batch scripts by running the tool with the \fB\-\-commandFilePath\fR option in interactive mode, then reading from the batch file with the \fB\-\-batchFile\fR option in script mode\&. Batch files can be useful when you have many \fBdsconfig\fR commands to run and want to avoid starting the JVM and setting up a new connection for each command\&. .PP The \fBdsconfig\fR command categorizes directory server configuration into components, also called managed objects\&. 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\&. .PP Configuration components have properties\&. For example, the LDAP Connection Handler component has properties such as listen\-port and allow\-start\-tls\&. You can set the component\*(Aqs listen\-port property to 389 to use the default LDAP port number\&. You can set the component\*(Aqs allow\-start\-tls property to true to permit LDAP client applications to use StartTLS\&. Much of the configuration you do with \fBdsconfig\fR involves setting component properties\&. The OpenDJ Configuration Reference covers all \fBdsconfig\fR component properties in detail, drawing on the documentation you also view when getting help through the \fBdsconfig\fR command\&. .SH "GETTING HELP" .PP The \fBdsconfig\fR command provides many subcommands\&. Use the following options to view help for subcommands\&. .PP See dsconfig Subcommands for details of individual subcommands\&. .PP \fBdsconfig \-\-help\-all\fR .RS 4 Display all subcommands .RE .PP \fBdsconfig \-\-help\-core\-server\fR .RS 4 Display subcommands relating to core server .RE .PP \fBdsconfig \-\-help\-database\fR .RS 4 Display subcommands relating to caching and back\-ends .RE .PP \fBdsconfig \-\-help\-logging\fR .RS 4 Display subcommands relating to logging .RE .PP \fBdsconfig \-\-help\-replication\fR .RS 4 Display subcommands relating to replication .RE .PP \fBdsconfig \-\-help\-security\fR .RS 4 Display subcommands relating to authentication and authorization .RE .PP \fBdsconfig \-\-help\-user\-management\fR .RS 4 Display subcommands relating to user management .RE .PP For help with individual subcommands, either use \fBdsconfig \fR\fB\fIsubcommand\fR\fR\fB \-\-help\fR, or start \fBdsconfig\fR in interactive mode, without specifying a subcommand\&. .PP To view component properties, use the \fBdsconfig list\-properties\fR command\&. .SH "GENERALLY APPLICABLE OPTIONS" .PP The following options are supported for all \fBdsconfig\fR subcommands\&. .PP \fB\-\-advanced\fR .RS 4 Allows the configuration of advanced components and properties .RE .SS "LDAP Connection Options" .PP \fB\-\-connectTimeout {timeout}\fR .RS 4 Maximum length of time (in milliseconds) that can be taken to establish a connection\&. Use \*(Aq0\*(Aq to specify no time out\&. .sp Default value: 30000 .RE .PP \fB\-h, \-\-hostname {host}\fR .RS 4 Directory server hostname or IP address .sp Default value: localhost\&.localdomain .RE .PP \fB\-I, \-\-adminUID {adminUID}\fR .RS 4 User ID of the global administrator to use to bind to the server\&. For the \fBenable\fR subcommand, if no global administrator was defined previously for any servers, the global administrator will be created using the UID provided\&. .sp Default value: admin .RE .PP \fB\-j, \-\-adminPasswordFile {bindPasswordFile}\fR .RS 4 Global administrator password file .RE .PP \fB\-K, \-\-keyStorePath {keyStorePath}\fR .RS 4 Certificate key store path .RE .PP \fB\-N, \-\-certNickname {nickname}\fR .RS 4 Nickname of certificate for SSL client authentication .RE .PP \fB\-o, \-\-saslOption {name=value}\fR .RS 4 SASL bind options .RE .PP \fB\-p, \-\-port {port}\fR .RS 4 Directory server administration port number .sp Default value: 4444 .RE .PP \fB\-P, \-\-trustStorePath {trustStorePath}\fR .RS 4 Certificate trust store path .sp Default value: /path/to/OpenDJ/config/admin\-truststore .RE .PP \fB\-T, \-\-trustStorePassword {trustStorePassword}\fR .RS 4 Certificate trust store PIN .RE .PP \fB\-u, \-\-keyStorePasswordFile {keyStorePasswordFile}\fR .RS 4 Certificate key store PIN file .RE .PP \fB\-U, \-\-trustStorePasswordFile {path}\fR .RS 4 Certificate trust store PIN file .RE .PP \fB\-w, \-\-adminPassword {bindPassword}\fR .RS 4 Password for the global administrator .RE .PP \fB\-W, \-\-keyStorePassword {keyStorePassword}\fR .RS 4 Certificate key store PIN .RE .PP \fB\-X, \-\-trustAll\fR .RS 4 Trust all server SSL certificates .RE .SS "Utility Input/Output Options" .PP \fB\-\-commandFilePath {path}\fR .RS 4 The full path to the file where the equivalent non\-interactive commands will be written when this command is run in interactive mode\&. .RE .PP \fB\-\-displayCommand\fR .RS 4 Display the equivalent non\-interactive option on standard output when this command is run in interactive mode\&. .RE .PP \fB\-F, \-\-batchFilePath {batchFilePath}\fR .RS 4 Path to a batch file containing a set of dsconfig commands to be executed .RE .PP \fB\-n, \-\-no\-prompt\fR .RS 4 Use non\-interactive mode\&. If data in the command is missing, the user is not prompted and the command exits with an error\&. .RE .PP \fB\-\-noPropertiesFile\fR .RS 4 No properties file will be used to get default command line argument values .RE .PP \fB\-\-propertiesFilePath {propertiesFilePath}\fR .RS 4 Path to the file containing default property values used for command line arguments .RE .PP \fB\-Q, \-\-quiet\fR .RS 4 Do not write progress information to standard output .RE .PP \fB\-s, \-\-script\-friendly\fR .RS 4 Use script\-friendly mode .RE .PP \fB\-v, \-\-verbose\fR .RS 4 Use verbose mode .RE .SS "General Options" .PP \fB\-\-version\fR .RS 4 Display version information .RE .PP \fB\-?, \-H, \-\-help\fR .RS 4 Display usage information .RE .SH "DSCONFIG SUBCOMMANDS" .PP This section covers individual \fBdsconfig\fR subcommands\&. .PP 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\&. .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} create\-\fIcomponent\fR .RE .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} list\-\fIcomponent\fRs .RE .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} delete\-\fIcomponent\fR .RE .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} get\-\fIcomponent\fR\-prop .RE .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} set\-\fIcomponent\fR\-prop .RE .SH "EXIT CODES" .PP 0 .RS 4 The command completed successfully\&. .RE .PP > 0 .RS 4 An error occurred\&. .RE .SH "EXAMPLES" .PP Much of the OpenDJ Administration Guide consists of \fBdsconfig\fR examples with text in between\&. This section therefore remains short\&. .PP The following example starts \fBdsconfig\fR in interactive, menu\-driven mode on the default port of the current host\&. .sp .if n \{\ .RS 4 .\} .nf \fBdsconfig\fR \fIsubcommand\fR \fIoptions\fR $ dsconfig \-h `hostname` \-p 4444 \-D "cn=Directory Manager" \-w password >>>> OpenDJ configuration console main menu What do you want to configure? 1) Access Control Handler 23) Log Rotation Policy 2) Account Status Notification Handler 24) Matching Rule 3) Administration Connector 25) Monitor Provider 4) Alert Handler 26) Network Group 5) Attribute Syntax 27) Network Group QOS Policy 6) Backend 28) Password Generator 7) Certificate Mapper 29) Password Policy 8) Connection Handler 30) Password Storage Scheme 9) Crypto Manager 31) Password Validator 10) Debug Target 32) Plugin 11) Entry Cache 33) Plugin Root 12) Extended Operation Handler 34) Replication Domain 13) Extension 35) Replication Server 14) External Changelog Domain 36) Root DN 15) Global Configuration 37) Root DSE Backend 16) Group Implementation 38) SASL Mechanism Handler 17) Identity Mapper 39) Synchronization Provider 18) Key Manager Provider 40) Trust Manager Provider 19) Local DB Index 41) Virtual Attribute 20) Local DB VLV Index 42) Work Queue 21) Log Publisher 43) Workflow 22) Log Retention Policy 44) Workflow Element q) quit Enter choice: .fi .if n \{\ .RE .\} .PP 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\&. .sp .if n \{\ .RS 4 .\} .nf $ 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 .SH DESCRIPTION .sp .LP The \fBdsconfig\fR command enables you to create, manage, and remove the base configuration for a directory server instance. The directory server configuration is organized as a set of components that \fBdsconfig\fR can access by using one or more subcommands. All components have zero or more configurable properties. These properties can be queried and modified to change the behavior of the component. .sp .LP Unless you specify all configuration parameters and the \fB-n\fR (\fB--no-prompt\fR) option, \fBdsconfig\fR runs in interactive mode. Interactive mode works much like a wizard, walking you through every aspect of the server configuration. .sp .LP Run \fBdsconfig --help\fR for more information, or use the dsconfig online documentation at http://docs.opends.org/1.2/page/Dsconfig\&. .SH ATTRIBUTES .sp .LP See \fBattributes\fR(5) for descriptions of the following attributes: .sp # Session operation number: 1 # Operation date: 19/Oct/2011:08:55:06 +0000 dsconfig set\-log\-publisher\-prop \e \-\-publisher\-name File\-Based\e Debug\e Logger \e \-\-set enabled:true \e \-\-hostname opendj\&.example\&.com \e \-\-port 4444 \e \-\-trustStorePath /path/to/OpenDJ/config/admin\-truststore \e \-\-bindDN cn=Directory\e Manager \e \-\-bindPassword ****** \e \-\-no\-prompt .sp .TS tab() box; cw(2.75i) |cw(2.75i) lw(2.75i) |lw(2.75i) . ATTRIBUTE TYPEATTRIBUTE VALUE _ Interface StabilityUncommitted .TE $ cp ~/enable\-debug\-log\&.batch ~/disable\-debug\-log\&.batch $ vi ~/disable\-debug\-log\&.batch $ cat ~/disable\-debug\-log\&.batch set\-log\-publisher\-prop \e \-\-publisher\-name File\-Based\e Debug\e Logger \e \-\-set enabled:false \e \-\-hostname opendj\&.example\&.com \e \-\-port 4444 \e \-\-trustStorePath /path/to/OpenDJ/config/admin\-truststore \e \-\-bindDN cn=Directory\e Manager \e \-\-bindPassword password \e \-\-no\-prompt $ dsconfig \-\-batchFilePath ~/disable\-debug\-log\&.batch \-\-no\-prompt 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 $ .fi .if n \{\ .RE .\} .PP 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 \fBdsconfig\fR, strip dsconfig 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)\&. .SH "AUTHORS" .PP \fBMark Craig\fR .RS 4 Author. .RE .PP \fBNemanja Lukić\fR .RS 4 Author. .RE .SH "COPYRIGHT" .br Copyright \(co 2011 ForgeRock AS .br .sp .RS 4 [IMAGE] .PP This work is licensed under the \m[blue]\fBCreative Commons Attribution-NonCommercial-NoDerivs 3.0 Unported License\fR\m[]. .RE .PP To view a copy of this license, visit http://creativecommons.org/licenses/by-nc-nd/3.0/ or send a letter to Creative Commons, 444 Castro Street, Suite 900, Mountain View, California, 94041, USA. .PP Trademarks are the property of their respective owners. .PP UNLESS OTHERWISE MUTUALLY AGREED BY THE PARTIES IN WRITING, LICENSOR OFFERS THE WORK AS-IS AND MAKES NO REPRESENTATIONS OR WARRANTIES OF ANY KIND CONCERNING THE WORK, EXPRESS, IMPLIED, STATUTORY OR OTHERWISE, INCLUDING, WITHOUT LIMITATION, WARRANTIES OF TITLE, MERCHANTIBILITY, FITNESS FOR A PARTICULAR PURPOSE, NONINFRINGEMENT, OR THE ABSENCE OF LATENT OR OTHER DEFECTS, ACCURACY, OR THE PRESENCE OF ABSENCE OF ERRORS, WHETHER OR NOT DISCOVERABLE. SOME JURISDICTIONS DO NOT ALLOW THE EXCLUSION OF IMPLIED WARRANTIES, SO SUCH EXCLUSION MAY NOT APPLY TO YOU. .PP EXCEPT TO THE EXTENT REQUIRED BY APPLICABLE LAW, IN NO EVENT WILL LICENSOR BE LIABLE TO YOU ON ANY LEGAL THEORY FOR ANY SPECIAL, INCIDENTAL, CONSEQUENTIAL, PUNITIVE OR EXEMPLARY DAMAGES ARISING OUT OF THIS LICENSE OR THE USE OF THE WORK, EVEN IF LICENSOR HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. .sp
