Perform the initial setup for a server instance.
This tool features both interactive and non-interactive modes for accepting the product license terms and initially configuring a server instance.
Install the Directory Server using interactive mode, which prompts for any required information:
setup --licenseKeyFile /path/to/PingDirectory.lic
Install the Directory Server non-interactively, accepting the license and providing a minimal set of options for getting the server running:
setup --licenseKeyFile /path/to/PingDirectory.lic --no-prompt --acceptLicense \
--location Austin --instanceName "Austin Directory 1" --ldapPort 389 \
--rootUserPasswordFile root-password-file \
--encryptDataWithPassphraseFromFile encryption-key-password-file
-V
--version
| Description | Display Directory Server version information |
-H
--help
| Description | Display general usage information |
--help-debug
| Description | Display help for using debug options |
| Advanced | Yes |
-n
--no-prompt
| Description | Perform an installation in non-interactive mode. When this mode is used, this tool will require additional options. See the examples below |
--acceptLicense
| Description | Indicate that you accept the terms of the product license defined in |
--licenseKeyFile {file}
| Description | The PingDirectory license key file authorizing use of this product. The license file may be specified by this argument or copied to /home/centos/workspace/Core-Release-Pipeline/build/package/PingDirectory/PingDirectory.lic in which case it will be imported automatically |
| Default Value | PingDirectory.lic |
| Required | No |
| Multi-Valued | No |
-Q
--quiet
| Description | Run setup in quiet mode. Quiet mode will not output progress information to standard output |
-v
--verbose
| Description | Use verbose mode |
--propertiesFilePath {propertiesFilePath}
| Description | Path to the file that contains default property values used for command-line arguments |
| Required | No |
| Multi-Valued | No |
--noPropertiesFile
| Description | Specify that no properties file will be used to get default command-line argument values |
--populateToolPropertiesFile {connect|bind-dn|bind-password}
| Description | Populate the config/tools.properties file with information provided during setup. If provided, the value for this argument must be one of 'connect', 'bind-dn', or 'bind-password'. If the argument is provided with a value of 'connect', then the properties file will be populated with the values that can be used to establish a connection to the local instance, but without a default bind DN or password. If the argument is provided with a value of 'bind-dn', then the properties file will be populated with values needed to connect to the local instance, and the initial root user DN will be set as the default bind DN (but without setting a bind password). If the argument is provided with a value of 'bind-password', then the properties file will be populated with the values needed to connect to the local instance, and the DN and password for the initial root user will be used as the default bind DN and password. If the argument is not provided, then the properties file will not be populated with default values for any properties |
| Required | No |
| Multi-Valued | No |
--script-friendly
| Description | Use script-friendly mode |
-b {baseDN}
--baseDN {baseDN}
| Description | Base DN for user information in the Directory Server |
| Default Value | dc=example,dc=com |
| Required | No |
| Multi-Valued | No |
-a
--addBaseEntry
| Description | Indicates whether to create the base entry in the Directory Server database |
-l {ldifFile}
--ldifFile {ldifFile}
| Description | Path to an LDIF file containing data that should be added to the Directory Server database |
| Required | No |
| Multi-Valued | Yes |
-R {rejectFile}
--rejectFile {rejectFile}
| Description | Write rejected entries to the specified file |
| Required | No |
| Multi-Valued | No |
--skipFile {skipFile}
| Description | Write skipped entries to the specified file |
| Required | No |
| Multi-Valued | No |
-d {numEntries}
--sampleData {numEntries}
| Description | Specifies that the database should be populated with the specified number of sample entries |
| Lower Bound | 0 |
| Default Value | 0 |
| Required | No |
| Multi-Valued | No |
-h {host}
--localHostName {host}
| Description | Fully qualified host name or IP address of the local host |
| Required | No |
| Multi-Valued | No |
--listenAddress {host}
| Description | Address of a network interface on which the Directory Server will listen. If not specified the server listens on all available interfaces |
| Default Value | 0.0.0.0 |
| Required | No |
| Multi-Valued | Yes |
-p {port}
--ldapPort {port}
| Description | Port on which the Directory Server should listen for LDAP communication |
| Lower Bound | 1 |
| Upper Bound | 65535 |
| Required | No |
| Multi-Valued | No |
-x {jmxPort}
--jmxPort {jmxPort}
| Description | Port on which the Directory Server should listen for JMX communication |
| Lower Bound | 1 |
| Upper Bound | 65535 |
| Default Value | 1689 |
| Required | No |
| Multi-Valued | No |
-S
--skipPortCheck
| Description | Skip the check to determine whether the specified ports are usable |
--skipHostnameCheck
| Description | Skip the check to determine whether the specified hostname is usable |
-D {rootUserDN}
--rootUserDN {rootUserDN}
| Description | DN for the initial root user for the Directory Server |
| Default Value | cn=Directory Manager |
| Required | No |
| Multi-Valued | No |
-w {rootUserPassword}
--rootUserPassword {rootUserPassword}
| Description | Password for the initial root user for the Directory Server |
| Required | No |
| Multi-Valued | No |
-j {rootUserPasswordFile}
--rootUserPasswordFile {rootUserPasswordFile}
| Description | Path to a file containing the password for the initial root user for the Directory Server |
| Required | No |
| Multi-Valued | No |
--allowWeakRootUserPassword
| Description | Skip validation for the root user password, which will allow a weak password to be chosen |
--jvmTuningParameter {parameter}
| Description | JVM tuning parameters to use for configuring the JVM for this server. Must be one of NONE, AGGRESSIVE, SEMI_AGGRESSIVE. See bin/dsjavaproperties --help for information about these parameters |
| Required | No |
| Multi-Valued | Yes |
--maxHeapSize {memory}
| Description | Explicitly specify the maximum amount of memory to be configured for this system. If omitted the value will be computed based on the presence of either the AGGRESSIVE or SEMI_AGGRESSIVE parameter specified by the --jvmTuningParameter option. Providing a value that is below a tool's minimum heap size requirement will have no effect, i.e. the tool's minimum required heap size will be used instead. The format for this value is the same as the -Xmx JVM option which is a number followed by a unit m or g |
| Required | No |
| Multi-Valued | No |
-L
--primeDB
| Description | Automatically prime the database on startup |
-O
--doNotStart
| Description | Do not start the server when the configuration is completed |
--fips-provider {provider}
| Description | Set up the server in a FIPS 140-2-compliant manner using the specified provider. At present, only the 'BCFIPS' provider, which uses the Bouncy Castle FIPS-compliant library, is supported. Note that servers running in FIPS-compliant mode cannot be installed in the same topology as servers running in non-FIPS-compliant mode, and that a server installed in non-FIPS-compliant mode cannot be updated to run in FIPS-compliant mode |
| Required | No |
| Multi-Valued | No |
-q
--enableStartTLS
| Description | Enable StartTLS to allow secure communication with the server using the LDAP port |
-Z {port}
--ldapsPort {port}
| Description | Port on which the Directory Server should listen for LDAPS communication |
| Lower Bound | 1 |
| Upper Bound | 65535 |
| Required | No |
| Multi-Valued | No |
--generateSelfSignedCertificate
| Description | Generate a self-signed certificate that the server should use when accepting SSL-based connections or performing StartTLS negotiation |
--certificateChainPEMFile {path}
| Description | The path to a file containing the PEM-formatted representations of one or more X.509 certificates to use in the server's listener certificate chain. The chain should include the listener certificate itself and (for non-self-signed certificates) all issuer certificates. The entire chain may be provided in one file, or with a separate file per certificate. In either case, the listener certificate should be provided first, and every subsequent certificate should be the issuer for the previous certificate in the chain |
| Required | No |
| Multi-Valued | Yes |
--certificatePrivateKeyPEMFile {path}
| Description | The path to a file containing the unencrypted PEM-formatted representation of the PKCS #8 private key for the server's listener certificate |
| Required | No |
| Multi-Valued | No |
--certificatePrivateKeyEncryptionPasswordFile {path}
| Description | The path to a file containing the password used to encrypt the PEM-formatted private key. This may be omitted if no private key PEM file is specified or if the private key is not encrypted |
| Required | No |
| Multi-Valued | No |
--trustedCertificatePEMFile {path}
| Description | The path to a file containing the PEM-formatted representations of one or more X.509 certificates to be imported into the server's certificate trust store. This argument may be provided multiple times to specify multiple PEM files to process, and each PEM file may contain information about one or more certificates |
| Required | No |
| Multi-Valued | Yes |
--usePkcs11Keystore
| Description | Use a certificate in a PKCS11 token that the server should use when accepting SSL-based connections or performing StartTLS negotiation |
--pkcs11ProviderConfigFile {path}
| Description | The path to a file with the configuration that the JVM should use when interacting with the PKCS #11 token |
| Required | No |
| Multi-Valued | No |
--useJavaKeystore {keystorePath}
| Description | Path of a Java Keystore (JKS) containing a certificate to be used as the server certificate |
| Required | No |
| Multi-Valued | No |
--usePkcs12Keystore {keystorePath}
| Description | Path of a PKCS12 keystore containing the certificate that the server should use when accepting SSL-based connections or performing StartTLS negotiation |
| Required | No |
| Multi-Valued | No |
--useBCFKSKeystore {keystorePath}
| Description | Path to a BCFKS keystore containing the certificate that the server should use when accepting SSL-based connections or performing StartTLS negotiation |
| Required | No |
| Multi-Valued | No |
-W {keystorePassword}
--keyStorePassword {keystorePassword}
| Description | Certificate keystore password. A password is required when you want to use an existing certificate (JKS, PKCS12 or PKCS11) as server certificate |
| Required | No |
| Multi-Valued | No |
-u {keystorePasswordFile}
--keyStorePasswordFile {keystorePasswordFile}
| Description | Certificate keystore password file. A password is required when you want to use an existing certificate (JKS, PKCS12 or PKCS11) as server certificate |
| Required | No |
| Multi-Valued | No |
-N {nickname}
--certNickname {nickname}
| Description | Nickname of the certificate that the server should use when accepting SSL-based connections or performing StartTLS negotiation |
| Required | No |
| Multi-Valued | No |
--useJavaTruststore {truststorePath}
| Description | Path to a Java keystore to use for establishing trust |
| Required | No |
| Multi-Valued | No |
--usePkcs12Truststore {truststorePath}
| Description | Path to a PKCS12 keystore to use for establishing trust |
| Required | No |
| Multi-Valued | No |
--useBCFKSTruststore {truststorePath}
| Description | Path to a BCFKS keystore to use for establishing trust |
| Required | No |
| Multi-Valued | No |
-U {path}
--trustStorePasswordFile {path}
| Description | Truststore password file |
| Required | No |
| Multi-Valued | No |
-T {truststorePassword}
--trustStorePassword {truststorePassword}
| Description | Truststore password |
| Required | No |
| Multi-Valued | No |
--httpsPort {port}
| Description | Port on which the Directory Server should listen for HTTPS communication |
| Lower Bound | 1 |
| Upper Bound | 65535 |
| Required | No |
| Multi-Valued | No |
--encryptDataWithPassphraseFromFile {path}
| Description | Encrypt server data using a key generated from a passphrase in the specified file. This file only needs to be present during installation; the generated key will be stored in the server's encryption settings database. When installing multiple servers, providing the same passphrase to each server will ensure that they all use the same encryption key |
| Required | No |
| Multi-Valued | No |
--encryptDataWithRandomPassphrase
| Description | Encrypt server data using a randomly generated key. Using this option on multiple servers will result in each server having a different key. When installing multiple servers, it is recommended that you either generate the encryption key with a passphrase and use the same passphrase across all servers, or that you use a random passphrase for the first server and then export the resulting encryption settings so that they can be imported into the remaining instances |
--encryptDataWithSettingsImportedFromFile {path}
| Description | Encrypt server data with encryption settings definitions imported from the specified file, which must have been exported from another server's encryption settings database |
| Required | No |
| Multi-Valued | No |
--encryptionSettingsExportPassphraseFile {path}
| Description | The path to a file containing the passphrase needed to access the contents of the encryption settings database export file. If the --encryptDataWithSettingsImportedFromFile argument is present, then this argument must also be provided; otherwise, it must not be given |
| Required | No |
| Multi-Valued | No |
--encryptDataWithPreExistingEncryptionSettingsDatabase
| Description | Encrypt server data with a key contained in a pre-existing encryption settings database. The encryption-settings-db database file must already exist in the server's config/encryption-settings directory, along with any additional metadata files that may be needed by the associated cipher stream provider. In addition, the configuration must have already been updated with any changes necessary to configure the cipher stream provider |
--rejectInsecureRequests
| Description | Configure the server to reject requests received over connections that are not secured with SSL or StartTLS |
--rejectUnauthenticatedRequests
| Description | Configure the server to reject requests received from unauthenticated clients |
--instanceName {name}
| Description | A name for uniquely identifying this Directory Server among other instances in the environment |
| Required | No |
| Multi-Valued | No |
--location {location}
| Description | The name of the location for this Directory Server |
| Required | No |
| Multi-Valued | No |
--optionCacheDirectory {path}
| Description | The directory for the option cache. The option cache stores the result of previously tested options. This allows future installs to be faster when a common option cache directory is used |
| Default Value | /home/centos/workspace/Core-Release-Pipeline/build/package/PingDirectory/logs/option-cache |
| Required | No |
| Multi-Valued | No |