PingDS 8.0.0

Install DS for evaluation

To set up the server, use the setup command-line tool. The following steps set up a single DS server on your computer for trying examples in the documentation.

When used without options, the setup command is interactive. When performing a non-interactive, silent installation, specify at least all mandatory options.

About mandatory options

The following setup options are mandatory. If you use only these options, the command sets up a server listening only on an administration port. The administration port is protected by a key pair specified or generated at setup time:

  • --adminConnectorPort {port} (The documentation uses 4444.)

  • --deploymentId {deploymentId}

  • --deploymentIdPassword {deploymentIdpassword}

  • --hostname {hostname}

  • --rootUserDN {rootUserDN} (The documentation uses uid=admin.)

  • --rootUserPassword {rootUserPassword}

  1. Before proceeding, install the server files.

    Learn more in Unpack files.

  2. Generate a deployment ID unless you already have one:

    $ /path/to/opendj/bin/dskeymgr create-deployment-id --deploymentIdPassword password
your-deployment-id

    Save the deployment ID and its deployment password. Keep the ID and the password safe, and keep the password secret. Use the same deployment ID and password for all the servers in the same environment.

    About deployment IDs

    A deployment ID is a random string generated using the dskeymgr command. It is a deployment identifier, not a key, but it is used with a password to generate keys.

    A deployment ID password is a secret string at least 8 characters long that you choose.

    The two are a pair. You must have the deployment ID password to use the deployment ID.

    Each deployment requires a single, unique deployment ID and its password. DS uses the pair to:

    • Protect the keys to encrypt and decrypt backup files and directory data.

    • Generate the TLS key pairs to protect secure connections, unless you provide your own.

    Store your deployment ID and password in a safe place, and reuse them when configuring other servers in the same deployment.

    The DS setup and dskeymgr commands use the pair to generate the following:

    • (Required) A shared master key for the deployment.

      DS replicas share secret keys for data encryption and decryption. DS servers encrypt backend data, backup files, and passwords, and each replica must be able to decrypt data encrypted on another peer replica.

      To avoid exposing secret keys, DS servers encrypt secret keys with a shared master key. DS software uses a deployment ID and its password to derive the master key.

    • (Optional) A private PKI for trusted, secure connections.

      A PKI serves to secure network connections from clients and other DS servers. The PKI is a trust network, requiring trust in the CA that signs public key certificates.

      Building a PKI can be complex. You can use self-signed certificates, but you must distribute each certificate to each server and client application. You can pay an existing CA to sign certificates, but that has a cost, and leaves control of trust with a third party. You can set up a CA or certificate management software, but that can be a significant effort and cost. As a shortcut to setting up a private CA, DS software uses deployment IDs and passwords.

      DS software uses the deployment ID and its password to generate key pairs without storing the CA private key.

    Learn more in Deployment IDs.

  3. Set the deployment ID as the value of the environment variable, DEPLOYMENT_ID:

    $ export DEPLOYMENT_ID=your-deployment-id

    Examples in the documentation show this environment variable as a reminder to use your own key. Other options are available, as described by the setup --help command.

  4. Run the setup command to install a directory server replica with the evaluation profile:

    $ /path/to/opendj/setup \
 --serverId evaluation-only \
 --deploymentId $DEPLOYMENT_ID \
 --deploymentIdPassword password \
 --rootUserDN uid=admin \
 --rootUserPassword password \
 --monitorUserPassword password \
 --hostname localhost \
 --adminConnectorPort 4444 \
 --ldapPort 1389 \
 --enableStartTls \
 --ldapsPort 1636 \
 --httpsPort 8443 \
 --replicationPort 8989 \
 --bootstrapReplicationServer localhost:8989 \
 --profile ds-evaluation \
 --start \
 --acceptLicense

    Notice the following about the command:

    • Its location depends on where you installed the files.

    • It requires your generated deployment ID and its password.

    • It prepares a single server for evaluation on your computer.

      This example uses the hostname localhost. When you install servers on multiple computers or need remote access to your server, use fully qualified domain names, such as ds.example.com.

    • It prepares the server to replicate sample data with other servers.

      Because there are no other replicas yet, this server points to itself as a bootstrap replication server (--bootstrapReplicationServer localhost:8989).

      Learn more in Learn replication and Bootstrap replication servers.

    • It sets a password for the default monitoring user account.

      The default DN, which is not shown, is uid=Monitor.

    • It prepares the server to listen for requests on the ports used in examples throughout the documentation.

    • For evaluation purposes, no further configuration is required.

      The --start option starts the server at the end of the setup process.

About the evaluation setup profile

The evaluation setup profile helps you learn and demonstrate directory services. Unlike other setup profiles, which use secure, production-ready access control settings, the evaluation setup profile provides easy access to sample data with the following features:

  • Sample Example.com data.

    The sample data has the base DN dc=example,dc=com. It includes more than 100 handwritten entries for users, groups, and devices.

    By default, it also includes 100,000 generated users, with DNs from uid=user.0,ou=people,dc=example.dc=com to uid=user.99999,ou=people,dc=example.dc=com.

    Use the --set ds-evaluation/generatedUsers:number option to generate a different number of additional entries. Each generated user has the same password, which is password.

    The handwritten sample Example.com data includes a group of directory administrators, cn=Directory Administrators,ou=Groups,dc=example,dc=com. Members of this group, such as kvaughan, have full access to directory data.

    Examples throughout the documentation demonstrate features using this sample data.

  • Global permission to perform operations over insecure connections.

  • HDAP enabled by default.

  • Additional schema for examples demonstrating class of service and JSON attributes.

  • Custom matching rule providers for JSON attributes.

  • Many permissions, such as anonymous read and search access, listed in the table that follows.

    The evaluation setup profile lets you learn and demonstrate most directory features without adding any ACIs.

Evaluation profile ACIs

Name Description ACI definition

Anonymous extended operation access

Anonymous and authenticated users can request the LDAP extended operations that are specified by OID or alias. Modification or removal may affect applications.

(extop="Cancel||GetSymmetricKey||PasswordModify||StartTls||WhoAmI") (version 3.0; acl "Anonymous extended operation access"; allow(read) userdn="ldap:///anyone";)

Anonymous extended operation access

Anonymous and authenticated users can request the LDAP extended operations that are specified by OID or alias. Modification or removal may affect applications.

(targetcontrol="Assertion||AuthorizationIdentity||MatchedValues||NoOp||PasswordPolicy||PasswordQualityAdvice||PermissiveModify||PostRead||PreRead||RealAttrsOnly||SimplePagedResults||TransactionId||VirtualAttrsOnly||Vlv||W3cTraceContext") (version 3.0; acl "Anonymous extended operation access"; allow(read) userdn="ldap:///anyone";)

Anonymous read and search access

Anonymous and authenticated Example.com users can read the user data attributes that are specified by their names.

(targetattr!="userPassword||authPassword||debugsearchindex") (version 3.0; acl "Anonymous read and search access"; allow (read,search,compare) userdn="ldap:///anyone";)

Authenticated control use

Authenticated Example.com users can proxy and examine CSNs.

(targetcontrol="ProxiedAuth||Csn") (version 3.0; acl "Authenticated control use"; allow(read) userdn="ldap:///all";)

Authenticated users extended operation access

Authenticated users can request the LDAP extended operations that are specified by OID or alias. Modification or removal may affect applications.

(targetcontrol="ManageDsaIt||RelaxRules||ServerSideSort||SubEntries||SubtreeDelete") (version 3.0; acl "Authenticated users extended operation access"; allow(read) userdn="ldap:///all";)

Authenticated users extended operation access

Authenticated users can request the LDAP extended operations that are specified by OID or alias. Modification or removal may affect applications.

(extop="PasswordPolicyState") (version 3.0; acl "Authenticated users extended operation access"; allow(read) userdn="ldap:///all";)

Directory administrator full access

Example.com directory administrators have access to read and write Example.com directory data, rename and move entries, and use proxied authorization.

(targetattr="* || +") (version 3.0; acl "Directory administrator full access"; allow (all,export,import,proxy) groupdn="ldap:///cn=Directory Administrators,ou=Groups,dc=example,dc=com";)

Proxied authorization for apps

Example.com applications can make requests on behalf of other users.

(targetattr="*") (version 3.0; acl "Proxied authorization for apps"; allow (all,proxy) (userdn="ldap:///cn=*,ou=Apps,dc=example,dc=com");)

Self entry modification

Authenticated users can modify the specified attributes on their own entries.

(targetattr=" audio || authPassword || description || displayName || givenName || homePhone || homePostalAddress || initials || jpegPhoto || labeledURI || mobile || pager || postalAddress || postalCode || preferredLanguage || telephoneNumber || userPassword") (version 3.0; acl "Self entry modification"; allow (write) userdn="ldap:///self";)

Self entry read for passwords

Authenticated users can read the password values on their own entries. By default, the server applies a one-way hash algorithm to the password value before writing it to the entry, so it is computationally difficult to recover the plaintext version of the password from the stored value.

(targetattr="userPassword||authPassword") (version 3.0; acl "Self entry read for passwords"; allow (read,search,compare) userdn="ldap:///self";)

Self service group creation

Authenticated Example.com users can create self service groups.

(targattrfilters="add=objectClass:(objectClass=groupOfNames)")(version 3.0; acl "Self service group creation";allow (add) (userdn="ldap:///uid=*,ou=People,dc=example,dc=com");)

Self service group deletion

The authenticated owner of a self service group can delete the group.

(version 3.0; acl "Self service group deletion";allow (delete) (userattr="owner#USERDN");)

Self service group registration

Authenticated Example.com users can sign themselves up as members of self service groups.

(targetattr="member") (version 3.0; acl "Self service group registration"; allow (selfwrite) (userdn="ldap:///uid=*,ou=People,dc=example,dc=com");)

User-Visible Monitor Attributes

Authenticated users can read monitoring information if they have the monitor read privilege. Modification or removal may affect applications.

(target="ldap:///cn=monitor")(targetattr="*||+") (version 3.0; acl "User-Visible Monitor Attributes"; allow (read,search,compare) userdn="ldap:///all";)

User-visible operational attributes

Anonymous and authenticated users can read attributes that identify entries and that contain information about modifications to entries.

(targetattr=" createTimestamp || creatorsName || modifiersName || modifyTimestamp || entryDN || entryUUID || subschemaSubentry || etag || governingStructureRule || structuralObjectClass || hasSubordinates || numSubordinates || isMemberOf") (version 3.0; acl "User-visible operational attributes"; allow (read,search,compare) userdn="ldap:///anyone";)

User-Visible Root DSE Operational Attributes

Anonymous and authenticated users can read attributes that describe what the server supports. Modification or removal may affect applications.

(target="ldap:///")(targetscope="base") (targetattr="objectClass||namingContexts||subSchemaSubEntry||supportedAuthPasswordSchemes||supportedControl||supportedExtension||supportedFeatures||supportedLDAPVersion||supportedSASLMechanisms||supportedTLSCiphers||supportedTLSProtocols||vendorName||vendorVersion||fullVendorVersion||alive||healthy")(version 3.0; acl "User-Visible Root DSE Operational Attributes"; allow (read,search,compare) userdn="ldap:///anyone";)

User-Visible Schema Operational Attributes

Authenticated users can read LDAP schema definitions. Modification or removal may affect applications.

(target="ldap:///cn=schema")(targetscope="base") (targetattr="objectClass||attributeTypes||dITContentRules||dITStructureRules ||ldapSyntaxes||matchingRules||matchingRuleUse||nameForms||objectClasses||etag||modifiersName||modifyTimestamp") (version 3.0; acl "User-Visible Schema Operational Attributes"; allow (read,search,compare) userdn="ldap:///all";)