setup

The setup command installs and minimally configures a directory server instance.

Synopsis

setup options

Description

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

Options

The setup utility accepts an option in either its short form (for example, -a) or its long form equivalent (for example, --addBaseEntry).

-a, --addBaseEntry

Indicates whether to create the base entry in the Directory Server database.

--adminConnectorPort port

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.0 Administration Guide.

-b, --baseDN base-DN

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.

-d, --sampleData number-of-entries

Populate the database with the specified number of sample user entries. The entries are generated by using the MakeLDIF facility of the import utility 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.

-D, --rootUserDN bindDN

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.

-e, --enableWindowsService

Enable the directory server as a Windows service. For Windows-platforms only.

--generateSelfSignedCertificate

Generate a self-signed certificate that the directory server should use when accepting SSL-based connection or performing StartTLS negotiation.

-i, --cli

Run the setup utility in command-line interactive mode rather than in GUI mode. If setup is run without the --cli option, it cannot accept other options.

-j, --rootUserPasswordFile filename

Specify the file containing the bind password when authenticating to the directory server. This option cannot be used in conjunction with --rootUserPassword.

-l, --ldifFile filename

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.

-N, --certNickname nickname

Use the specified certificate for SSL or StartTLS client authentication.

-O, --doNotStart

Do not start the directory server when the configuration is completed.

-p,--ldapPort port

Contact the directory server at the specified port. If it is not provided, then the default port of 389 will be used.

-q, --enableStartTLS

Enable StartTLS to allow secure communication with the directory server by using the LDAP port.

-R, --rejectFile filename

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.

--skipFile filename

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.

-S, --skipPortCheck

Do not make any attempt to determine whether the specified port is available. Normally, when this option is not present, the setup utility verifies that the port is not in use and that the user running the setup tool can bind to that port. With the --skipPortCheck option, the setup utility skips the port check.

-u, --keyStorePasswordFile filename

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.

--useJavaKeystore path

Specify the path to the Java Keystore (JKS) that contains the server certificate.

--useJCEKS path

Specify the path to the Java Cryptography Extension Keystore (JCEKS) that contains the server certificate.

--usePkcs11Keystore

Specify the path to the PKCS#11 keystore that contains the server certificate.

--usePkcs12Keystore path

Specify the path to the PKCS#12 keystore that contains the server certificate.

-w, --rootUserPassword password

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

-W, --keyStorePassword password

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.

-x, --jmxPort port

Specify the port for a JMX MBeans server connection. The default value for this option is 689.

-Z, --ldapsPort port

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.

Utility Input/Output Options

-n, --no-prompt

Run setup in non-interactive mode. If some data in the command is missing, the user will not be prompted and the tool will fail.

--noPropertiesFile

Indicate that the utility will not use a properties file to get the default command-line options.

--propertiesFilePath path

Specify the path to the properties file that contains the default command-line options.

-Q, --quiet

Run in quiet mode. No output will be generated unless a significant error occurs during the process.

-v, --verbose

Run in verbose mode, displaying diagnostics on standard output.

General Options

-?, -H, --help

Display command-line usage information for the utility and exit without making any attempt to stop or restart the server.

--version

Display the version information for the directory server and exit rather than attempting to run this command.

Examples

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.

Example 17

Running setup in GUI Mode

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.

Example 18

Running setup in Interactive Mode From the Command Line

The setup utility 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.

Example 19

Running setup in Script-Friendly Mode

Script-friendly mode enables you to create installation scripts with the setup utility 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 utility 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

Example 20

Running setup in Script-Friendly Mode With LDIF Import

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"

Example 21

Running setup in Script-Friendly Mode With Sample Entry Generation

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

Example 22

Running setup on Windows

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

Exit Codes

0

Successful completion or successful no-op.

1

Error unexpected. Potential bug.

2

Error user data. Cannot parse options, or data provided by user is not valid.

3

Error server already installed.

4

Error initializing server.

Using a Properties File

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

Log Files

The setup utility 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.

Location

The setup command is located at these paths:

• UNIX and Linux: install-dir/setup

• Windows: install-dir\setup.bat

Related Commands

• uninstall

• create-rc-script