update-ldap-config
Updates LDAP configurations.
update-ldap-config
[-c value | --configuration=value]
[-b value | --bootstrap-config=value]
<--id=value>
[-t value | --type=value]
[-s value | --servers=value]
[--clear-context-names]
[-n value | --context-names=value]
[-u value | --username=value]
[-p value | --password=value]
[--schedules=value]
[--clear-schedules]
[--user-search-filter=value]
[--user-name-attribute=value]
[--authentication-attribute=value]
[--security-authentication=value]
[--referral-mode=value]
[--referral-mode-root-dse=value]
[--request-control=value]
[--page-size=value]
[--import-limit=value]
[--user-display-name-attribute=value]
[--group-display-name-attribute=value]
{-Ckey=value}
{-Rvalue}
{-Svalue}
[--connection-timeout=value]
[--read-timeout=value]Overview
Use this command to update LDAP configurations.
Options
| Option | Optional or Required | Default Value | Description |
|---|---|---|---|
|
Optional | configuration.xml | The path to the server configuration file. |
|
Optional | none | The path to the bootstrap configuration file. See Bootstrap.xml file for more information about this file. |
|
Required | none | Specifies the identifier for the LDAP configuration to be updated. |
|
Optional | none | The type of LDAP server. The following names are valid types:
When you specify any of the first three types, a type-specific configuration template is automatically applied in runtime so that the most fundamental configuration options are configured automatically. When you specify a Custom LDAP server type, there is no such configuration template and all those configuration options must be specified explicitly. When a custom LDAP configuration is to be used for authentication or with the user directory LDAP provider, the
|
|
Optional | none | Specifies a whitespace-separated list of LDAP server URLs. An LDAP server URL has the format
<protocol>://<server>[:<port>]:
|
|
Optional | none | Clears context names from the LDAP configuration. This argument can be used together with the ‐‐context‐names argument to remove all old context names before adding the new. |
|
Optional | none | A list of distinguished names (DNs) of containers holding LDAP accounts to be visible within
Spotfire Server. When specifying more than one DN, the DNs must be separated by pipe-characters (|). The specified context names are added to the context names that are already configured. To set the context names from scratch, use the
--clear-context-names argument with the
--context-names.
If the specified containers contain a large number of users, of which only a few should be visible in
Spotfire Server, a custom user search filter can be specified to include only the designated users (see the
Examples:
|
|
Optional | none | The name of the LDAP service account to be used when searching for users (and optionally also groups) in the LDAP server. This service account does not need to have any write permissions, but it needs to have read permissions for all configured context names (LDAP containers). For most LDAP servers, the account name is the account’s distinguished name (DN). For Active Directory, the account name can also be specified in the forms
ntdomain\name and
name@dnsdomain.
Examples: CN=spotsvc,OU=services,DC=research,DC=example,dc=COM RESEARCH\spotsvc (Active Directory only) spotsvc@research.example.com (Active Directory only) |
|
Optional | none | The password for the LDAP service account. |
|
Optional | none | A comma-separated list of schedules for when the LDAP synchronization should be performed. The schedules are given in a cron-compatible format, where each schedule consists of either five fields or one shorthand label. Make sure to enclose the value in double quotes. The specified schedules are added to the schedules that are already configured. To set the schedules from scratch, use the
--clear-schedules argument with the
--schedules.
The five fields are, from left to right, with their valid ranges: minute (0-59), hour (0-23), day of month (1-31), month (1-12) and day of week (0-7, where both 0 and 7 indicate Sunday). A field can also be configured with the wildcard character *, indicating that any moment in time matches this field. A group synchronization is triggered when all fields match the current time. If both day of month and day of week have non-wildcard values, then only one of them has to match. There are also the following shorthand labels that can be used instead of the full cron expressions:
Refer to the Wikipedia overview article on the cron scheduler. |
|
Optional | none | Clears from the LDAP configuration the LDAP synchronization schedules. This argument can be used together with the
--schedules argument to remove all old schedules before adding the new.
|
|
Optional; must be specified for custom LDAP configurations, either when running this command or the create-ldap-config command. (The parameter is required for all custom configurations.) | For Active Directory servers, the parameter value defaults to '(&(objectClass=user)(!(objectClass=computer)))'
For any version of the Sun Directory Servers, it defaults to
|
Specifies an LDAP search expression filter to be used when searching for users.
If only a subset of all the users in the specified LDAP containers should be allowed access to
Spotfire Server, a more detailed user search filter can be used. The search expression can, for example, be expanded so that it also puts restrictions on which groups the users belong to, or which roles they have.
Active Directory example:
&(objectClass=person)(isMemberOf=cn=project-x,dc=example,dc=com)
Sun Java System Directory Server example:
&(objectClass=person)(isMemberOf=cn=project-x,dc=example,dc=com)
Sun ONE Directory Servers example:
The syntax of LDAP search expression filters is specified by the RFC 4515 document. Consult this documentation for information about more advanced filters. |
|
Optional; must be specified for custom LDAP configurations, either when running this command or the create-ldap-config command. | For Active Directory servers the value defaults to sAMAccountName.
For a Sun Java System Directory Server (or any older Sun ONE Directory Server or iPlanet Directory Server) with a default configuration, it defaults to UID. |
Specifies the name of the LDAP attribute containing the user account names. |
|
Optional; should be used only for advanced setups. It is not set by default. | none | Specifies the name of the LDAP attribute containing a user identity that can be used for binding (authenticating) to the LDAP server. This attribute fills no purpose in most common LDAP configurations, but can be useful in more advanced setups, where the distinguished name (DN) does not work for authentication, or where users should be able to log in using a username that does not map directly to an actual LDAP account.
When setting up SASL with DIGEST-MD5 in an Active Directory environment, the DN does not work for authentication and the userPrincipalName attribute must be used instead. The
When setting up SASL with GSSAPI in an Active Directory environment, the DN does not work for authentication and the sAMAccountName or userPrincipalName attribute must be used instead. The
Example: By setting the
|
|
Optional; should be used only in advanced setups. | simple | This parameter specifies the security level to use when binding to the LDAP server.
--authentication-attribute argument must also be used to specify the userPrincipalName attribute for the actual authentication to work correctly.
When setting up SASL with GSSAPI in an Active Directory environment, the
|
|
Optional | follow | Specifies how LDAP referrals should be handled. Valid arguments are
follow (automatically follow any referrals),
ignore (ignore referrals), and
throw (fail with an error).
|
|
Optional | If not explicitly set, the value for
--referral-mode is used.
|
Specifies how LDAP referrals should be handled when looking up the RootDSE. Valid arguments are:
|
|
Optional | probe | Determines the type of LDAP controls to be used when executing search queries to the LDAP server. The default behavior is to probe the LDAP server for the best supported request control. The paged results control is always preferred, because it provides the most efficient way of retrieving the query result set. The virtual list view control can also be used for the same purpose if the paged results control is not supported. The virtual list view control is automatically used together with a sort control. Both the paged results control and the virtual list view control supports a configurable page size, set by the
--page-size argument.
|
|
Optional | The page size value defaults to 2000 for both the paged results control and the virtual list view control. | Specifies the page size to be used with the paged results control or the virtual list view control when performing search queries to the LDAP server |
|
Optional | unlimited | Specifies a threshold that limits the number of users that can be imported from an LDAP server to Spotfire Server in one query. This can be used to prevent accidental flooding of the Spotfire Server user directory when integrating with an LDAP server with tens or even hundreds of thousands of users. By setting an import limit, the administrator can be sure that an unexpected high number of users does not affect the server performance. By default, there is no import limit. To explicitly request unlimited import, set the parameter value to ‐1. All positive numbers are treated as an import limit. In most cases, it is recommended to leave this parameter untouched. |
|
Optional | none | Specifies the name of the LDAP attribute containing the user display names. |
|
Optional | none | Specifies the name of the LDAP attribute containing the group display names. |
|
Optional | none | Specifies additional JNDI environment properties to be used when connecting to the LDAP server. Note that it does not add to the previously configured custom properties; it replaces them completely. If you want to keep any of the old custom properties, make sure to specify them once again when adding new ones. This option can be specified multiple times with different keys.
Example: The equivalent of specifying the
Example: Updating the context names
|
|
Optional and may be specified multiple times with different values. | If this argument is not specified, the Java defaults are used. | Specifies the protocols to be used for LDAPS when connecting to the LDAP server.
Example: To enable only TLSv1.2
|
|
Optional and may be specified multiple times with different values. | If this argument is not specified, the Java defaults are used. | Specifies the cipher suites to be used for LDAPS when connecting to the LDAP server.
Example: To enable only these two cipher suites
|
|
Optional | no timeout (see description) | Specifies the connection timeout. The value must be a non-negative integer representing the timeout in milliseconds. A value less than or equal to zero results in no timeout, effectively waiting until the connection times out on TCP network level. |
|
Optional | no timeout (see description) | Specifies the read timeout. The value must be a non-negative integer representing the timeout in milliseconds. A value less than or equal to zero results in no timeout, effectively waiting until the connection times out on TCP network level. |