Changes in 12cR1.3.5.2

The following changes were made in Oracle NoSQL Database 12cR1.3.5.2.

New Features

  1. Added support for gathering key distribution statistics. To enable statistics gathering, the statistics tables need to be created first by executing the runadmin script file CreateStatisticTables.kvs, which is located in the lib directory of the release package. [#23422]

  2. Added support for Kerberos user authentication. Users that wish to use this new capability should be aware of the following changes:

    • The makebootconfig utility has a new optional -external-auth command-line argument which is used to enable external authentication mechanisms. Currently, Kerberos is the only supported mechanism. This new flag is only permitted when the value of the -store-security flag is specified as configure or enable.

    • The securityconfig tool has been enhanced to provide the ability to:

      • Add Kerberos configuration information to an existing security configuration

      • Renew a store's Kerberos service principal keytab for security maintenance tasks

    • A new class, KerberosCredentials, which implements LoginCredentials, has been introduced, and its instances can be used in the KVStoreFactory.getStore method to perform a Kerberos login:

      • KVStoreFactory.getStore(KVStoreConfig, LoginCredentials, ReauthenticateHandler)

    • New Kerberos-related security properties have been added that must be specified when using a KVStore command-line utility program against a secure store that has enabled Kerberos authentication.

    There are two approaches that applications can use to authenticate using Kerberos. Client applications that use the Java Authentication and Authorization Service (JAAS) programming framework can specify credentials by using Subject.doAs. Applications that do not use the JAAS framework can use the new security properties to specify parameters needed to acquire user credentials from the Kerberos Key Distribution Center (KDC).

    Kerberos authentication is described in greater depth in the Oracle NoSQL Database Security Guide, as well as in the Administrators Guide and the Javadoc. [#24328]

  3. The off-heap cache is now enabled by default with a systemPercent setting of 10%. Please review Managing the Off-heap Cache for details.

Bug and Performance Fixes

  1. In earlier versions, a LOB read operation with Consistency.NONE_REQUIRED could fail in the absence of a master for the shard hosting the LOB metadata. The read operation will now use a suitable replica when the read consistency allows for it. [#24460]

  2. Fixed a bug where a client calling TableAPI.getTable() while an index is being created and populated (is not yet ready) could result in a ConcurrentModificationException on a RepNode, causing the RepNode to become unavailable. [#24691]

  3. Corrected a problem in the configuration of the external tables example that caused the example to generate errors. The property name for specifying the name of the table in the config.xml file was incorrect — changed from "oracle.kv.table" to "oracle.kv.tableName". [#24650]

  4. Fixed a problem in the implementation of the show admins command in the Administrator CLI that prevented it from authenticating correctly when used with a secure store. [#24648]

  5. Improved the algorithm used to calculate the maximum number of threads used to perform concurrent table requests when the default is requested by specifying TableIteratorOptions.maxConcurrentRequests as 0. This change affects the behavior of table multi-get operations, and table and index iterations. [#24188]

  6. Fixed a security flaw in table-level access checking. Before this fix, it might have been possible for an authenticated client to access a table without permission if the user had permission to access other tables in the store.

Utility Changes

  1. There were several changes made to the ping command to make it easier to use in scripts. [#24407]

    First, modified the java -jar kvstore.jar ping command to add a new flag, -helper-hosts, which is an alternative to the existing -host and -port flags. If multiple helper hosts are provided, the ping utility will have multiple nodes it can use to make an initial point of contact with the store, and will have a greater chance of success if some nodes of the store are unavailable. The new -helper-hosts flag can be specified as a comma-separated list of hosts and ports. For example:

    java -jar kvstore.jar ping -helper-hosts hst1:5000;hst2:5100

    Second, ping now generates an exit code which acts as a quick summary of the results. The exit code is returned both as a process exit code, if ping is called as a standalone utility, and as part of the JSON output. The exit code is meant to direct the caller to perform the appropriate follow-on action. The values, defined in the Ping.ExitCode enum, are:

    • 0 (EXIT_OK)

      All services in the store could be located and are in a known, good state (e.g. RUNNING).

    • 1 (EXIT_OPERATIONAL)

      One or more services in the store could not be reached, or are in an unknown or not usable state. In this case the store should support all data operations across all shards, as well as all administrative operations, but may be in a state of degraded performance. Some action should be taken to find and fix the problem before part of the store becomes unavailable.

    • 2 (EXIT_NO_ADMIN_QUORUM)

      The Admin Service replication group does not have quorum or is not available at all, and it's not possible to execute administrative operations which modify store configuration. The store supports all normal data operations despite the loss of admin quorum, but this state requires immediate attention to restore full store capabilities.

    • 3 (EXIT_NO_SHARD_QUORUM)

      One or more of the shards does not have quorum and either cannot accept write requests, or is completely unavailable. This state requires immediate attention to restore store capabilities. This exit code takes precedence over EXIT_NO_ADMIN_QUORUM, so if this exit code is used it is possible that the admin capabilities are also reduced or unavailable.

    • 100 (EXIT_USAGE)

      A usage error.

    • 101 (EXIT_TOPOLOGY_FAILURE)

      Ping was unable to find a Topology in order to operate. This could be a store problem, a network problem, or it could be a usage problem with the parameters passed to Ping (e.g. the host and port or helper-hosts list are not part of a store).

    • 102 (EXIT_UNEXPECTED)

      The utility has experienced an unexpected error.

    Note that exit codes 1 through 3 may indicate a network connectivity issue that should be checked first before concluding that any services have a problem.

    Finally, the following section has been added to Ping's JSON output, which can be requested using the -json flag, and appears when ping is called as a standalone command or as part of the Admin CLI. For example:

      "operation" : "ping",
      "return_code" : 5000,
      "description" : "No errors found",
      "exit_code" : 0
  2. Some table commands in the Administrative CLI were deprecated in favor of using the execute command to perform DDL statements. The newly deprecated commands are: [#23937]

    • table

    • plan add-index

    • plan add-table

    • plan evolve-table

    • plan remove-index

    • plan remove-table

  3. Some additional Admin CLI commands now support displaying output in JSON format. If -json is specified when starting the Admin CLI using runadmin, or is specified as an argument of a command, the execution result of the command will be displayed in a JSON format string containing standard NoSQL error messages. In addition to the `configure` command, support has been added for the following commands: [#24346]

    • plan deploy-zone

    • plan deploy-sn

    • pool create

    • pool join

    • plan deploy-admin

    • topology create

    • plan deploy-topology

    • show plan

    • verify configuration | upgrade | prerequisite

  4. The admin CLI command `pool add` is now idempotent. Calling the command with a pool that already exists now returns without error. This change is intended to make the command easier to use in scripts. [#24445]

  5. The makebootconfig command was modified to support the new -dns-cachettl flag. This flag specifies the number of seconds that replication nodes should cache host name to IP address mappings. A value of 0 means mappings should not be cached. A value of -1 means mappings should be cached indefinitely, which is the default. The value of the flag is used to set the "networkaddress.cache.ttl" and "networkaddress.cache.negative.ttl" security properties. Note that specifying a non-default value can have security implications. See the Java Networking Properties page for more details. [#24087]