UnboundID Metrics Engine Release Notes
UnboundID Metrics Engine Release Notes |
|
| Return to Documentation Index |
Notes for the following versions of the UnboundID Metrics Engine are available in this document:
Updating to the latest version of the Metrics Engine addresses the following critical issues from previous versions. Affected servers should be updated.
No critical issues have been identified
Following are notes for version 4.5.1.12 of the Metrics Engine.
The following issues have been resolved with this release of the Metrics Engine:
Enabled support for the SSLv2Hello TLS protocol by default in JVMs that support it. This does not enable support for the insecure SSLv2 protocol, but it can improve compatibility with clients running older versions of Java that may start TLS negotiation with an SSLv2 client hello packet before negotiating to a higher version of the TLS protocol. Support for SSLv2Hello in the initial phase of negotiation does not in any way compromise the strength of the integrity and/or confidentiality protection that is ultimately negotiated between the client and the server. Issue:DS-12041
The server can now detect an "out of file handles" situation on the operating system, and shut down to prevent running in an unreliable state. Issue:DS-12579 SF#:2655
These issues were resolved with version 4.5.1.4 of the Metrics Engine:
Fixed an issue so that collect-support-data now generates filename entries correctly. Previously, the tool would hang if the archiving of files following a symbolic link required generating a non-duplicating filename entry. Issue:DS-10582
These issues were resolved with version 4.5.1.2 of the Metrics Engine:
Updated the metrics schema to allow for longer alert notification messages. Error handling was improved to handle unexpectedly long messages added to the database. Issue:DS-10268 SF#:2149
Fixed an issue in the Periodic Stats Logger, where no logging would occur when suppress-if-idle=true was configured, even when the server was not idle. Issue:DS-10387 SF#:2170
Added a new sanitize-log tool that can be used to remove sensitive information from server log files, including the file-based access log, the operation timing access log, the file-based error log, the file-based sync log, the file-based resync log, and the detailed HTTP operation log.
The sanitization process operates on fields that consist of name-value pairs. The field name and equal sign will always be retained, but in cases where the value may contain sensitive data, that value may either be replaced with the string "---REDACTED---", or it may be tokenized. If the tokenized value is a DN or filter, then attribute names in that DN or filter will be preserved while the values will be replaced with a string consisting of a number inside curly braces. If the tokenized value is not a DN or filter, then the entire value will be replaced with a number inside curly braces. If a string to be tokenized appears multiple times in the log, the same replacement token will be used for each occurrence of that string to make it possible to correlate occurrences of that string without revealing the actual content.
The sanitize-log tool has a default configuration that should be sufficient for many environments, allowing it to tokenize or redact sensitive information while preserving non-sensitive content for use in diagnosing problems or understanding usage patterns. However, this behavior can be customized using command-line arguments by indicating whether to preserve, tokenize, or redact a given log field. Issue:DS-10472
Fixed issues with the JDBC Access Logger that were related to Oracle Thin Client, where column values were "null" and disabling the logger resulted in losing a connection to the server when using the dsconfig command. Issue:DS-10485
These issues were resolved with version 4.5.1.11 of the Metrics Engine:
Disabled support for SSLv3 by default in the LDAP, HTTP, and JMX connection handlers, and for replication communication. The recently-discovered POODLE vulnerability could potentially allow a network attacker to determine the plaintext behind an SSLv3-encrypted session, which would effectively negate the primary benefit of the encryption.
SSLv3 was initially defined in 1996, but was supplanted by the release of the TLSv1 definition in 1999 (and subsequently by TLSv1.1 in 2006 and TLSv1.2 in 2008). These newer TLS protocols are not susceptible to the POODLE vulnerability, and the server has supported them (and preferred them over SSLv3) for many years. The act of disabling SSLv3 by default should not have any adverse effect on clients that support any of the newer TLS protocols. However, if there are any legacy client applications that attempt to communicate securely but do not support the newer TLS protocols, they should be updated to support the newer protocols. In the event that there are known clients that do not support any security protocol newer than SSLv3 and that cannot be immediately updated to support a newer protocol, SSLv3 support can be re-enabled using the newly-introduced allowed-insecure-tls-protocol global configuration property. However, since communication using SSLv3 can no longer be considered secure, it is strongly recommended that every effort be made to update all known clients still using SSLv3.
It is possible to use the server access log to identify LDAP clients that use SSLv3 to communicate with the server. Whenever an LDAP client establishes a secure connection to the server, or whenever a client uses the StartTLS extended operation to secure an existing plaintext connection, the server will generate a SECURITY-NEGOTIATION access log message. The "protocol" element of a SECURITY-NEGOTIATION access log message specifies the name of the security protocol that has been negotiated between the client and the server, and any SECURITY-NEGOTIATION messages with a protocol of "SSLv3" suggest that the associated client is vulnerable to the POODLE attack. In addition, if any connections are terminated for attempting to use the disallowed SSLv3 protocol, the access log message for that disconnect should include a message stating the reason for the termination. Issue:DS-11782
These issues were resolved with version 4.5.1.1 of the Metrics Engine:
Fix an issue to enable the "monitored-servers add-servers" command to work with servers that do not allow unauthenticated access to the root DSE or reject unauthenticated operations. Issue:DS-10181 SF#:2138
These features were added for version 4.5.1.0 of the Metrics Engine:
The collect-support-data tool now refers to tools.properties for default command-line options.
The collect-support-data tool now supports an option to encrypt the data archive, to ensure protection of customer data while in transit, and an option to reduce the amount of potentially sensitive data that is collected.
Cross-origin Resource sharing (CORS) support is now included for HTTP Servlet Extensions, including the SCIM RESTful APIs.
These were known issues at the time of the release of version 4.5.1.0 of the Metrics Engine:
When the Velocity servlet receives CORS-enabled requests and has a cross-origin policy in effect, it will return multiple Access-Control-* headers with duplicate values. This will cause cross-origin requests issued by web browsers to fail. Issue:DS-10205
These issues were resolved with version 4.5.1.0 of the Metrics Engine:
The setup tool's --aggressiveJVMTuning and --verboseGC command-line options have been deprecated. Instead, use --jvmTuningParameter AGGRESSIVE and --jvmTuningParameter VERBOSE_GC respectively. Issue:DS-9079
Update the server configuration to use a new default limit for duplicate alert suppression. The previous default imposed a maximum of 100 alerts of the same type per hour. The new default imposes a maximum of 10 alerts of the same type every ten minutes. This is more likely to suppress bursts in which the same alert is repeatedly generated over a short time without interfering with multiple occurrences of alerts of the same type over a longer period of time. Issue:DS-9259
Update the Velocity framework to better support customization out of the box. In order to customize Velocity templates or static content (CSS, Javascript files etc.) you should copy the original file from the config/velocity directory to the root velocity directory and modify the copied file. Files in the root velocity directory will override those in config/velocity. Issue:DS-9273
Update the server to improve the caching behavior for PIN files as used by key and trust manager providers. In the case that the keystore or truststore file has been updated to require a new PIN and the existing PIN file is updated without a configuration change to the associated key or trust manager provider, the server would previously keep trying to use the old PIN. It will now look for and use an updated PIN if a failure is encountered while using the old PIN. Issue:DS-10113 SF#:2123
Update the collect-support-data tool so that it can encrypt the data that is captured to protect it from unauthorized third parties. The encryption key is generated from a passphrase which may be read from a file, interactively provided by the user, or dynamically generated by the tool. This passphrase must be provided to support personnel (ideally over a different communication channel than the encrypted support data archive itself) for them to be able to access the information it contains.
There is also a new option to decrypt an encrypted collect-support-data archive when provided with the encryption passphrase. Issue:DS-10129
Update the collect-support-data tool so that it is possible to configure default values for most arguments in the tools.properties file. Issue:DS-10178
Update the collect-support-data tool to further reduce the possibility of gathering sensitive information. Potentially sensitive data will be replaced with ---REDACTED--- in the output. A new "--securityLevel maximum" option can also be specified that redacts DNs and search filters, which might include personally identifiable information. Issue:DS-10115
These features were added for version 4.5.0.0 of the Metrics Engine:
The Metrics Engine now collects Identity Broker metrics and can report on data that is of interest to the business, such as consent rates, most active clients, or most requested data. Sample dashboards are included in the Identity Broker Console and as separate configuration files.
The Metrics Engine package now includes the embedded PostgreSQL distribution to simplify deployment and support.
A new config-diff command line utility can compare two server configurations and produce the difference as a dsconfig batch file. The file can then be used to bring the source configuration in line with the target. Comparisons can be done between live servers or configuration files, and between current or legacy configurations. Run 'config-diff --help' to get more information including example use cases.
These were known issues at the time of the release of version 4.5.0.0 of the Metrics Engine:
Java 1.7 has a synchronization bottleneck in HashMap that severely impacts performance. Use update 1.7u40, if possible, to avoid this issue. Issue:DS-9477
Installing the Metrics Engine as root is not supported. Issue:DS-9374
These issues were resolved with version 4.5.0.0 of the Metrics Engine:
Fix a bug in the JDBC Access Logger that could cause incompatibility with some database versions and display a "Cannot commit when autoCommit is enabled" error message. Issue:DS-8750
Update the server startup process so that if no messages have been logged for at least five minutes, the server will generate and log a message about the current phase of startup processing. This can help reassure administrators that the server is still starting and provide information about what phase of startup may be taking so long. Issue:DS-7450
Update java.properties generation so that comments related to alternative JVM tunings are no longer present in the file. In most cases, rather than updating java.properties by hand you should use the dsjavaproperties tool to generate JVM options. Issue:DS-8339
Add an allow-insecure-local-jmx-access option to the global config that will expose JMX data via insecure local JVM connection Issue:DS-4300
Add a new alert handler that can use the Twilio service to deliver administrative alerts via SMS. Long alerts may be either truncated or split into multiple SMS messages. Issue:DS-5587
Update the configuration schema to make the ds-cfg-inherit-default-root-privileges attribute mandatory for object class ds-cfg-root-dn-user which is used to define Root User DNs. When this attribute is not present on Root DN User entries, the effect is for the root user to inherit default privileges. It has been made mandatory to make this behavior more explicit. During an update of the server, root DN user entries that do not explicitly declare a value for this attribute will be updated with a value of 'true'. Issue:DS-8450
Add a WebLogic specific descriptor file for the web console to help with deployment compatibility. Issue:DS-8925 SF#:1915
The trust store password options have been deprecated for most tools that do not require read-write access to a trust store. Issue:DS-8789
Make a number of criteria-related improvements:
- Add Server SDK support for creating custom connection, request, result, search entry, and search reference criteria implementations.
- Update the simple request criteria type to make it possible to consider the search scope in determining whether a search operation matches the criteria.
- Update the simple result criteria type to make it possible to consider the indexed/unindexed status in determining whether a search operation matches the criteria.
- Add a new type of request criteria that may be used to more easily identify operations that target the server root DSE.
- Add a new type of result criteria that may be used to classify operations based on replication assurance requirements and/or whether those requirements were satisfied.
- Add a new allowed-insecure-request-criteria global configuration property that may be used to identify requests that the server should allow even if they are received over an insecure connection and the server is configured to reject insecure requests.
- Add a new allowed-unauthenticated-request-criteria global configuration property that may be used to identify requests that the server should allow even if they are received over an unauthenticated connection and the server is configured to reject unauthenticated requests. Issues:DS-5079,DS-8168,DS-8770
Add a new sign-log configuration property to file-based loggers that may be used to cause the server to digitally sign messages written by that logger. A new validate-file-signature tool may be used to verify signature information in signed log files, as well as LDIF files generated by signed LDIF exports. Issue:DS-8662
Add support for two new extended operations. A list configurations extended operation may be used to obtain information about the configurations that are available within to the server, including the currently-active configuration, the baseline configuration (i.e., the base configuration for an out-of-the-box installation of the current version), and all archived configurations that reflect configuration changes over time. A get configuration extended operation may be used to retrieve a specific configuration from the server. Issue:DS-9149
Update setup to fix a bug in which file path options specified as relative to the current directory may cause the server to be configured incorrectly or cause setup failure. Issue:DS-8389
Update the HTTP Connection handler to support configuration for tracking sessions either through HTTP cookies or by URL rewriting. Issues:DS-8639,DS-9128
Expose the Plugin type in the Server SDK, which is primarily useful for this server to have custom code run at server startup or shutdown using the 'startup' and 'shutdown' plugin types. Issue:DS-9165
Update the server to provide a degree of sandboxing around Server SDK extensions so that an unexpected exception thrown by an extension will be caught and result in an administrative alert rather than being caught further up in the stack and potentially causing other problems. Issue:DS-9247
In the rare cases where it is necessary to forcefully terminate the JVM from within the server itself, ensure that any files marked for deletion when the JVM shuts down are manually deleted before the JVM is terminated. This can help avoid problems like server shutdown not being detected properly because the server PID file hasn't been removed. Issue:DS-9267
Provide improved schema validation to detect additional cases in which certain misspelled tokens in the definition for a schema token could be silently interpreted as an extra property for that schema element. The server will now log a warning message about these unexpected tokens so that administrators can either correct them or prefix them with "X-" to indicate that they are an extra property provided for informational purposes. Issue:DS-9236
Reduce the time it takes the server to shut down in certain situations. Background threads sometimes missed a signal to wake up and had to wait for their next polling interval to see that a shut down had been requested. Issue:DS-9334
Update the default behavior of all file-based loggers to have include-thread-id=true. This will include a compact thread ID in all log messages. This can make it easier to correlate log messages generated by the same thread within a single log file or across different types of log files. Issue:DS-9352
Remove -XX:+UseMembar from the default set of generated JVM properties except on early JVM versions where this setting was required to work around a threading bug in the JVM.
Update the server JVM arguments generated by setup and dsjavaproperties to explicitly define -XX:MaxNewSize and -XX:NewSize for JVM's 1GB in size and larger. Also, add a comment to the generated java.properties file directing the administrator to use dsjavaproperties for making memory-related changes to this file rather than editing it directly. Issue:DS-9227
Add password file arguments to the scripts used to prepare external servers. Issue:DS-9406
Update the setup and dsjavaproperties tools to permit maximum heap size values for memory that is not currently available on the host, though the value must still be less than the total amount of memory present on the host. Issue:DS-9111
Update the setup and dsjavapropeties tools to permit JVM heap size values to be as large as the amount of memory present on the system would permit. Issue:DS-9494
Update the Server SDK to provide the ability to run command line utilities within the server process. A ToolExecutor can be retrieved from the ServerContext. Currently, only the config-diff command is supported, but additional commands might be supported in the future. Issue:DS-9537 SF#:00001858
Enhance dsconfig to write to the config audit log when in offline mode. Issue:DS-1495
On Linux, issue a warning on startup and after a JVM pause if the kernel setting vm.swappiness is not 0 as this can cause the server to become unresponsive for several seconds when memory is paged back from disk during a garbage collection. Issue:DS-9070
Automatically record server monitor data at shutdown, as it may be useful for debugging purposes in cases where a problem was experienced within the server that was resolved by a restart. Issue:DS-9777
Improve the performance of certain monitor entry searches that target specific monitor entries by object class. In particular, this includes searches with AND or OR filters, as well as filters that target object classes not defined in the server schema. Issue:DS-9772
Fix an issue where the Metrics Engine was not correctly parsing the query API's start and end time parameters when no time zone offset was included. The time had been interpreted as GMT, but it should have been interpreted as the local time zone (from the server's point of view). Issue:DS-9765
These features were added for version 4.1.0.0 of the Metrics Engine:
The UnboundID Identity Broker is the first of a new class of components for consumer and subscriber identity management architectures.
As a stand-alone server, it provides authorization decisions for client applications, provisioning systems, API gateways, and analytical tools in any architecture involving personal, account, or sensitive identity data.
Working together with the UnboundID Identity Data Store and Identity Proxy, the Identity Broker is designed to make high-volume and high-speed authorization decisions based on ever-changing consumer profile and consent data. Functionally, the Identity Broker is both the Policy Decision Point and the OAuth2 provider for externalized authorization. Performance-wise, the Identity Broker can support the request volumes driven by the complex, real-time interactions necessary to support today's consumer-facing mobile, social, and cloud ecosystems.
These were known issues at the time of the release of version 4.1.0.0 of the Metrics Engine:
These issues were resolved with version 4.1.0.0 of the Metrics Engine:
Update the names of the UnboundID-branded products which are now: - Identity Data Store (formerly Directory Server) - Identity Proxy (formerly Proxy Server) - Identity Data Sync Server (formerly Synchronization Server) - Metrics Engine (name unchanged) Issues:DS-7514,DS-7515,DS-7516,DS-7518
Fix a bug where under certain error conditions the start server scripts could prompt user to overwrite existing file. Issue:DS-7268
Introduce an "include-thread-id" configuration property on many of the file-based loggers that when enabled adds a threadID field to logging output. This makes it possible to know exactly which thread logged a message, which can simplify correlating errors between log messages and separate logs. This ID can be correlated to a thread name using the cn=JVM Stack Trace,cn=monitor entry. Issue:DS-8212
Change stop-*.bat to attempt a soft server shutdown before terminating the process. Issue:DS-408
Addressed an issue in the monitoring pages of the web console where they incorrectly listed directory server replication related information. Issue:DS-7289
Update the JMX connection handler to infer an appropriate Java type (e.g. Boolean, Long, Float, Date, or String) for JMX attributes from the underlying LDAP attribute type and value. The legacy behavior to return all JMX attributes as String values can be set if desired through the advanced global configuration property 'jmx-value-behavior'. Issue:DS-7635
Add the --noPropertiesFile option to the status command so that it does not fail when the option is provided to collect-support-data. Issue:DS-8390
These features were added for version 4.0.0.0 of the Metrics Engine:
Update the names of the UnboundID-branded products, which are now:
The Metrics Engine can now be configured to monitor and alert on Service Level Agreements. For information about Service Level Agreements and how to configure them, please refer to the "Monitoring Service Level Agreements" section of the UnboundID Metrics Engine Administration Guide.
Provide API for accessing Metrics Engine SLAs and Threshold Alerts. For API documentation, please refer to the "Accessing the Metrics Engine Data" chapter of the UnboundID Metrics Engine Administration Guide.
These were known issues at the time of the release of version 4.0.0.0 of the Metrics Engine:
Version 3.6.x Metrics Engine cannot monitor version 4.x servers. To monitor a version 4.x server you must first upgrade the Metrics Engine to version 4.0. Issue:7743
These issues were resolved with version 4.0.0.0 of the Metrics Engine:
File Server HTTP Servlet Extensions now allow a default MIME type to be set with the default-mime-type property. Issue:DS-6959
Change the stop-* tools to behave like other task based tools. These tools require the use of the --task argument to ensure that user knows they are using a server task. These tools also will not use properties files unless you provide the --usePropertiesFile or --propertiesFilePath arguments.
Fix a bug that prevented viewing hidden and complex configuration properties using dsconfig in a non-interactive mode. Issue:DS-7245
Fix a bug in the manage-extension tool that would cause an error when attempting to install an extension if that extension's getExtensionDescription method returned null (which is allowed as per the documentation). Issue:DS-7367
Fix a bug in the LDAPConnectionHandler where it did not close the NIO Selector on shutdown. On some platforms this caused the underlying socket channel to remain bound, which prevented the server from being able to restart. Issue:DS-7373
These features were added for version 3.6.0.0 of the Metrics Engine:
IPv6 is now a supported deployment option.
64-bit JDK 7 is now a supported deployment option, but 32-bit JDKs are no longer supported.
Provide API for accessing monitored server Alerts.
These were known issues at the time of the release of version 3.6.0.0 of the Metrics Engine:
Version 3.6.x Metrics Engine cannot monitor version 4.x servers. To monitor a version 4.x server you must first upgrade the Metrics Engine to version 4.0. Issue:7743
These issues were resolved with version 3.6.0.0 of the Metrics Engine:
Fix a typo in the output of "query-metrics explore". It had indicated that "&dimensions=application-name:value1,value2" could be used to restrict the query output, but it should just be "&dimension=application-name:value1,value2" (not plural). Issue:DS-7226
Added HTML response to the chart resource using the URL /api/v1/metrics/{metricId}/chart.html. The title of the HTML document will be the same as that of the chart title. Issue:DS-7071
Fix a problem in the manage-extension tool where it would fail on Windows because it tried to delete some temp files that were currently in use. Issue:DS-6770
The default behavior of the API is changed to address how incomplete sample intervals close to the current real time are returned when performing a multi-time interval query:
- The datatable and chart resources now truncates incomplete time intervals from the data by default but only up to 5 min worth of intervals or 20% of the total number of intervals, which ever is less. - Introduced the lastCompleteIndex property to the data series objects in a dataset response. This is used to indicate the index of most current 'complete' sample where a complete sample is a sample that contains values for all aggregates. No data is truncated by default. - The default trimming behaviors of all resources may be overridden using the new maxTruncatedIntervals query parameter. This allows the client to specify the maximum number of incomplete sample intervals that may be truncated from the resulting response. Issue:DS-7068
Added a new includeEmptySeries query param to the datatable and chart resources that may be used to control whether the results should contain series with no data. The default is false. Issues:DS-7071,DS-7077
Fix a bug in dsconfig that prevented going back when adding a new configuration object inside of an existing one. Issue:DS-7263 SF#:1793
Prevent disk space monitoring for metrics db for environments where file permissions disallow reading. Issue:DS-7266 SF#:1794
Add a few query parameters to the chart resource (/api/v1/{metricId}/chart) to allow customizations:
- title: The input is now treated as a Velocity template and the $metric context may be used to reference anything in the Metric object. - subTitle: Allows adding one or more sub-titles to the chart. Velocity templates may be used. - tz: Specifies the time zone used for all date/times on the chart. Default is GMT. - dateFormat: Specifies the format of the all date/times on the chart. It uses the standard Java SimpleDateFormat strings. - useLogScale: Use a logarithmic scale for the range axis. - style: Allows customizations of various stylistic elements in the chart in a psudo CSS format (semi-colon separated list of rules where the key and value separated by a colon). The following rules are implemented: -- series-color: A space separated list of colors to use for the different series in the order specified. The standard 17 CSS named colors are supported along with the hex (ie.#445566) and rgb (ie. rgb(45, 100, 255)) notations. (ie. series-color: blue red #221122 rgb(234,255,255);) -- series-width: The width of the series lines in px notation (ie. series-width: 5px;) -- background-color: The background color of the chart (ie. background-color: white;) -- grid-line-width: The width of the gridlines. If only one value is present, both the domain and range gridlines will use the same width. Otherwise, the first value is for the domain and the second for the range gridlines. (ie. grid-line-width: 4px 6px;) -- grid-line-color: The color of the gridlines. (ie. grid-line-color: red blue;) -- legend-position: The position of the legend, if present. (ie. legend-position: right;) Issue:DS-7076
These features were added for version 3.5.1.0 of the Metrics Engine:
The Metrics Engine is a core server product that collects and aggregates key diagnostic, capacity, and usage information from an UnboundID server topology consisting of instrumented Directory Server, Directory Proxy Server, and Synchronization Servers running release 3.5.0.0 and above. Metrics data can be explored and graphed using the included query-metric tool, and the Metrics Engine REST API makes this information available to custom applications and third-party systems. To learn more about the Metrics Engine, please refer to the UnboundID Metrics Engine Administration Guide.
These were known issues at the time of the release of version 3.5.1.0 of the Metrics Engine:
These issues were resolved with version 3.5.1.0 of the Metrics Engine:
No information is available