The setup command installs and minimally configures a directory server instance.
This command installs OpenDS directory servers. For Sun OpenDS Standard Edition proxy installation, see vdp-setup.
setup [options]
The setup command installs and configure a directory server instance, including specifying the ports on which it will listen, the DN and password for the initial root user, the base DN for the directory data, and the manner in which the database should be populated. It can be run in one of three modes:
Graphical user interface (GUI) mode. GUI mode is the default and recommended installation option. Using Java Web Start, the setup GUI provides an easy interface for installing and configuring standalone directory servers or replication servers in replicated multi-network environments. GUI mode also allows for easy server setup using SSL or StartTLS if desired.
Interactive command-line mode. Interactive command-line mode is used with the --cli option, or if no GUI is available.
Script-friendly mode. Script-friendly mode can be used in scripts where all appropriate values are provided in the form of command-line options. Use the --no-prompt and the --quiet options to suppress interactivity and output information, respectively.
When the setup command is run without any options, it starts in GUI mode but falls back to interactive command-line mode if no GUI is available. To run setup in command-line mode, use the --cli option. The options that can be provided are listed below. Note that no options are allowed if the command is run in GUI mode. Only the --cli option is used for interactive command-line mode. The remainder of the options listed are intended for silent configuration mode, which directory administrators can use in their installation scripts.
The setup command accepts an option in either its short form (for example, -a) or its long form equivalent (for example, --addBaseEntry).
Indicates whether to create the base entry in the Directory Server database.
Specifies the port on which the administration connector should listen for administration traffic. For information about the administration connector, see Managing Administration Traffic to the Server in Sun OpenDS Standard Edition 2.2 Administration Guide.
Use the base DN as the suffix for the database that contains user data. The default value for this option is dc=example,dc=com. Multiple base DNs can be specified by providing this option multiple times.
Populate the database with the specified number of sample user entries. The entries are generated by using the MakeLDIF facility of the import command and are based on the default example.template template. This option must not be used in conjunction with either --addBaseEntry or --ldifFile. If this option is not provided, then the database will be left empty.
Use the specified bind DN to authenticate to the directory server. This option is used when performing simple authentication and is not required if SASL authentication is to be used. The default value for this option is cn=Directory Manager.
Enable the directory server as a Windows service. For Windows-platforms only.
Generate a self-signed certificate that the directory server should use when accepting SSL-based connection or performing StartTLS negotiation.
Run the setup command in command-line interactive mode rather than in GUI mode. If setup is run without the --cli option, it cannot accept other options.
Specify the file containing the bind password when authenticating to the directory server. This option cannot be used in conjunction with --rootUserPassword.
Use the specified LDIF file to populate the database. Data can be imported from multiple files by providing this option multiple times, in which case the files are processed in the order they are provided in the option list. This option must not be used in conjunction with either the --addBaseEntry or --sampleData option. If this option is not provided, then the database will be left empty.
Use the specified certificate for SSL or StartTLS client authentication.
Do not start the directory server when the configuration is completed.
Contact the directory server at the specified port. If it is not provided, then the default port of 389 will be used.
Enable StartTLS to allow secure communication with the directory server by using the LDAP port.
Write rejected entries to the specified file. Rejected entries occur if they do are not comply with the default schema during an import using the -l or --ldifFile option.
Write skipped entries to the specified file. Skipped entries occur if entries cannot be placed under any specified base DN during an import using the -l or --ldifFile option.
Do not make any attempt to determine whether the specified port is available. Normally, when this option is not present, the setup command verifies that the port is not in use and that the user running the setup command can bind to that port. With the --skipPortCheck option, the setup command skips the port check.
Use the password in the specified file to access the certificate keystore. A password is required when you specify an existing certificate (JKS, JCEKS, PKCS#11, or PKCS#12) as a server certificate.
Specify the path to the Java Keystore (JKS) that contains the server certificate.
Specify the path to the Java Cryptography Extension Keystore (JCEKS) that contains the server certificate.
Specify the path to the PKCS#11 keystore that contains the server certificate.
Specify the path to the PKCS#12 keystore that contains the server certificate.
Use the root user password when authenticating to the directory server. This password can be used for simple authentication as well as password-based SASL mechanisms. This option must not be used in conjunction with --rootUserPasswordFile. To prompt for the password, type -w -.
Use the password to the certificate keystore. A password is required when you specify an existing certificate (JKS, JCEKS, PKCS#11, or PKCS#12) as a server certificate.
Specify the port for a JMX MBeans server connection. The default value for this option is 689.
Contact the directory server at the specified port for LDAP SSL (LDAPS) communication. The LDAPS port will be configured and SSL will be enabled only if this option is explicitly specified.
Run setup in non-interactive mode. If some data in the command is missing, the user will not be prompted and the command will fail.
Indicate that the command will not use a properties file to get the default command-line options.
Specify the path to the properties file that contains the default command-line options.
Run in quiet mode. No output will be generated unless a significant error occurs during the process.
Run in verbose mode, displaying diagnostics on standard output.
Display command-line usage information for the command and exit without making any attempt to stop or restart the server.
Display the version information for the directory server and exit rather than attempting to run this command.
The following examples show how to use the directory server commands. You can use the commands on any UNIX, Linux, or Windows system that has at least the Java SE 5 (at least Sun version 1.5.0_08, preferably the latest version of Java SE 6) runtime environment installed on its target system.
The following command runs an installation in GUI mode:
$ setup
The GUI is launched and provides several screens that walk you through setting up your directory server in standalone or replicated environments. You also have the option to set up SSL or StartTLS certificates.
The setup command can be run in interactive mode, where you are prompted for installation options. To run setup in interactive mode, type the following command:
$ setup --cli
The command prompts you for the required setup values. Press Enter or Return to accept the default, or enter a value at the prompt.
Script-friendly mode enables you to create installation scripts with the setup command when many directory server instances must be configured for large replicated environments. Script-friendly mode requires the --no-prompt and --quiet options to be provided. If no option is present, the setup command defaults to interactive mode.
The following command runs the installation in non-interactive (--no-prompt) and quiet (-Q) modes. It sets the LDAP port (-p), the administration connector port (--adminConnectorPort), the root DN (-D), the root DN password (-w), and adds a base entry (-a) with the specified base DN (-b),
$ setup --cli --no-prompt -Q -p 1389 --adminConnectorPort 4444 \ -D "cn=Directory Manager" -w password -a -b dc=example,dc=com
The following command runs the installation in non-interactive (--no-prompt) and quiet (-Q) modes. It sets the LDAP port (-p), the administration connector port (--adminConnectorPort), the root DN (-D), the root DN password (-w), and adds the baseDN (-b) with data imported from an LDIF file (-l).
$ setup --cli --no-prompt -Q -p 1389 --adminConnectorPort 4444 \ -D "cn=Directory Manager" -w password -b dc=example,dc=com \ -l "/home/ldif/company.ldif"
The following command runs the installation in non-interactive (--no-prompt) and quiet (-Q) modes. It sets the LDAP port (-p), the administration connector port (--adminConnectorPort), the root DN (-D), the root DN password (-w), the baseDN (-b) and generates 2000 sample entries (-d).
$ setup --cli --no-prompt -Q -p 1389 --adminConnectorPort 4444 \ -D "cn=Directory Manager" -w password -b dc=example,dc=com -d 2000
The following command enables the directory server to run as a Windows service (-e). It sets the LDAP port (-p), the administration connector port (--adminConnectorPort), the JMX port (-x), the rootDN (-D), the rootDN password (-w), and the baseDN (-b), and generates 10000 sample entries.
C:\> setup.bat --cli -e -p 1389 --adminConnectorPort 4444 -x 1689 \ -D "cn=Directory Manager" -w password -b dc=example,dc=com -d 10000
Successful completion or successful no-op.
Error unexpected. Potential bug.
Error user data. Cannot parse options, or data provided by user is not valid.
Error server already installed.
Error initializing server.
The directory server supports the use of a properties file that passes in any default option values used with the setup command. The properties file is convenient when working in different configuration environments, especially in scripted or embedded applications. For more information, see Using a Properties File With Server Commands.
All of the setup options can be stored in a properties file. Entries in the properties file have the following format:
toolname.propertyname=propertyvalue
For example:
setup.ldapport=12345
The setup command writes a log file named opendsIDnumber where IDnumber is a decimal number. The log files are located at these paths:
UNIX (Solaris): /var/tmp/
Linux: /tmp/
Windows: %TEMP%
By default, this folder is C:\Documents and Settings\User\Local Settings\Temp.
The setup command is located at these paths:
UNIX and Linux: install-dir/setup
Windows: install-dir\setup.bat