1. Installation and Configuration Guide
  2. About the Oracle REST Data Services Configuration Files

C About the Oracle REST Data Services Configuration Files

The section describes the Oracle REST Data Services configuration files.

Topics:

C.1 Understanding the Configuration Folder Structure

The configuration folder has the following structure: 

+- global/
    +- settings.xml
    +- credentials
    +- wallet/
    +- standalone/
+- databases/
    +- default/
        +- pool.xml
        +- wallet/
    +- myapp/
         +- hostnames
         +- pool.xml
         +- wallet/
    +- myapp2/
         +- paths
         +- pool.xml
         +- wallet/
The global/ folder contains settings that apply across the entire ORDS instance:
  • settings.xml: Contains settings that are configured across the entire ORDS instance. For example: debug.printToScreen=true
  • credentials: The ORDS user password file
  • wallet/: Contains an Oracle auto login wallet that contains the instance wide encryption and mac keys previously stored in security.crypto.enc.password and security.crypto.mac.password configuration settings in defaults.xml.
  • standalone/: Contains standalone mode related resources such as the HTTPS certificate and key.
The databases/ folder contains database pool configurations.
  • Each pool configuration is located in its own folder. The base path url mapping for a pool is inferred from the folder name. If the folder is named foo/, then requests can be mapped to the pool by accessing https://server/ords/foo/...
  • Folder names must be valid subdomain names, they must start with an alphanumeric character, containing only the characters 0-9,a-z,- (that is, they must only contain digits, lowercase a-z, and the "-" character is the only delimiter allowed).
  • The folder named default/ is reserved and is used to map requests that are not mapped to any other pool. It is equivalent to the apex.xml pool in the old structure.
  • The folder named databases/<pool-name>/wallet/ contains an Oracle auto login wallet that contains the credentials for the database pool. The database username and password must be stored in the wallet. The db.password settings must not be used. The wallet must conform to the requirements for ORDS wallets.
  • Alternatively, the folder may contain a file named hostname or paths, but not both.

C.2 Understanding the Configuration File Format

Configuration files use the standard Java XML properties file format, where each configuration setting contains a key and a corresponding value. The following is an example of settings.xml file: 

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE properties SYSTEM "http://java.sun.com/dtd/properties.dtd">
<properties>
<entry key="db.connectionType">basic</entry>
<entry key="db.hostname">localhost</entry>
<entry key="db.port">1521</entry>
<entry key="db.servicename">orcl</entry>
<entry key="jdbc.DriverType">thin</entry>
<entry key="jdbc.InitialLimit">3</entry>
<entry key="jdbc.MinLimit">1</entry>
<entry key="jdbc.MaxLimit">10</entry>
<entry key="jdbc.MaxStatementsLimit">10</entry>
<entry key="jdbc.InactivityTimeout">1800</entry>
<entry key="jdbc.statementTimeout">900</entry>
<entry key="jdbc.MaxConnectionReuseCount">1000</entry></properties>

C.3 Understanding the Configurable Settings

This section lists the editable configuration settings for the settings.xml and pool.xml configuration files.

Note:

Oracle recommends users to use the Oracle REST Data Services command-line interface to edit the configuration files.

Table C-1 Oracle REST Data Services Configuration Settings

Key Type Description Example Setting Type
apex.security.administrator.roles string Specifies the comma delimited list of additional roles to assign authenticated APEX administrator type users.   Pool specific
apex.security.user.roles string Specifies the comma delimited list of additional roles to assign authenticated regular APEX users.   Pool specific
autoupgrade.api.aulocation string specifies a configuration setting for AutoUpgrade.jar location.   Pool specific
autoupgrade.api.enabled boolean Specifies a configuration setting to enable AutoUpgrade REST API features.   Pool specific
autoupgrade.api.jvmlocation string Specifies a configuration setting for AutoUpgrade REST API JVM location.   Pool specific
autoupgrade.api.loglocation string Specifies a configuration setting for AutoUpgrade REST API log location.   Pool specific
database.api.management.services.disabled boolean Specifies to disable the Database API administration related services. Only applicable when Database API is enabled.   Global
db.adminUser string Specifies the username for the database account that ORDS uses for administration operations in the database.   Pool specific
db.adminUser.password string Specifies the password for the database account that ORDS uses for administration operations in the database.   Pool specific
db.cdb.adminUser string Specifies the username for the database account that ORDS uses for the Pluggable Database Lifecycle Management.   Pool specific
db.cdb.adminUser.password string Specifies the password for the database account that ORDS uses for the Pluggable Database Lifecycle Management.   Pool specific
db.credentialsSource string

Specifies the source for database credentials when creating a direct connection for running SQL statements.

Value can be one of pool or request.

If the value is pool, then the credentials defined in this pool is used to create a JDBC connection.

If the value request is used, then the credentials in the request is used to create a JDBC connection and if successful, grants the requestor SQL Developer role.

Default value is pool.

   Pool specific
db.invalidPoolTimeout duration

Specifies how long to wait before retrying an invalid pool.

Default: 15m

   Global
db.poolDestroyTimeout duration

Indicates how long to wait to gracefully destroy a pool before moving to forcefully destroy all connections including borrowed ones.

Default: 5m

   Pool specific
db.wallet.zip string Specifies the wallet archive (provided in BASE64 encoding) containing connection details for the pool.   Pool specific
db.wallet.zip.path string Specifies the path to a wallet archive containing connection details for the pool.   Pool specific
db.wallet.zip.service string Specifies the service name in the wallet archive for the pool.   Pool specific
debug.trackResources boolean Specifies to enable tracking of JDBC resources. If not released causes in resource leaks or exhaustion in the database. Tracking imposes a performance overhead.   Pool specific
feature.openservicebroker.exclude boolean Specifies to disable the Open Service Broker services available for the pool.   Pool specific
feature.sdw boolean Specifies to enable the Database Actions feature.   Pool specific
http.cookie.filter string Specifies a comma separated list of HTTP Cookies to exclude when initializing an Oracle Web Agent environment.   Pool specific
jdbc.auth.admin.role string Identifies the database role that indicates that the database user must get the SQL Administrator role.   Pool specific
jdbc.cleanup.mode   Specifies how a pooled JDBC connection and corresponding database session, is released when a request has been processed.

Default value is RECYCLE

   Pool specific
owa.trace.sql boolean Specifies a boolean property. If it is true, then it causes a trace of the SQL statements performed by Oracle Web Agent to be echoed to the log.   Pool specific
plsql.gateway.mode string

Indicates if the PL/SQL Gateway functionality should be available for a pool or not.

Value can be one of disabled, direct, or proxied.

  • If the value is direct, then the pool serves the PL/SQL Gateway requests directly.
  • If the value is PLSQL_GATEWAY_CONFIG, view is used to determine the user to whom to proxy.
proxied Pool specific
request.traceHeaderName string

Specifies the name of the HTTP request header that uniquely identifies the request end to end as it passes through the various layers of the application stack. In Oracle this header is commonly referred to as the ECID (Entity Context ID).

   Global
resource.templates.enabled boolean Deprecated. Configuration property indicating if the legacy resource templates (APEX based REST) should be enabled or not. False by default. The resource-templates code base is not compatible with the single pool (ORDS_PUBLIC_USER) architecture so must be disabled.   Global
security.credentials.attempts numeric Specifies the maximum number of unsuccessful password attempts allowed. Enabled by setting a positive integer value.

Defaults to -1.

 3 Global
security.credentials.file string Specifies the file where credentials are stored.   Global
security.credentials.lock.time duration Specifies the period to lock the account that has exceeded maximum attempts.

Defaults to 10m (10 minutes)

 15m Global
security.validationFunctionType string Indicates the type of security.requestValidationFunction: javascript or plsql.

Defaults to plsql.

   Pool specific
standalone.access.log string Specifies the path to the folder to store HTTP request access logs. If not specified, then no access log is generated.   Global
standalone.binds string Specifies the comma separated list of host names or IP addresses to identify a specific network interface on which to listen.

Default 0.0.0.0.

   Global
standalone.context.path string Specifies the context path where ords is located. Defaults to /ords   Global
standalone.doc.root string Points to the location where static resources tto be served under the / root server path are located.   Global
standalone.http.port numeric Specifies the HTTP listen port.

Default: 8080

 8777 Global
standalone.https.cert string Specifies the SSL certificate path. If you are providing the SSL certificate, then you must specify the certificate location.   Global
standalone.https.cert.key string Specifies the SSL certificate key path. If you are providing the SSL certificate, you must specify the certificate key location.   Global
standalone.https.host string Specifies the SSL certificate hostname.   Global
standalone.https.port numeric Specifies the HTTPS listen port.

Default: 8443

   Global
standalone.static.context.path string Specifies the Context path where Application Express static resources are located.

Default: /i

   Global
standalone.static.path string Specifies the path to the folder containing static resources required by APEX.   Global
standalone.stop.timeout duration Specifies the period for Standalone Mode to wait until it is gracefully shutdown.

Default: 10s (10 seconds)

 15s Global

apex.docTable

string

This parameter is deprecated, instead use owa.docTable parameter.

MYDOCTABLE

 Pool specific
cache.metadata.timeout

string

Specifies the setting to determine for how long a metadata record remains in the cache. Longer duration means, it takes longer to view the applied changes.

The formats accepted are based on the ISO-8601 duration format.

 5m Global
cache.metadata.enabled

boolean

Specifies the setting to enable or disable metadata caching.

Supported values:

  • true

  • false (default)

 false Global
database.api.enabled

boolean

 Specifies whether the Database API is enabled.

Supported values:

  • true

  • false (default)

   Global

db.connectionType

string

The type of connection. Supported values:

  • basic

  • tns

  • customurl

basic

 Pool specific

db.customURL

string

Specifies the JDBC URL connection to connect to the database.

jdbc:oracle:thin:@(DESCRIPTION=(ADDRESS=(PROTOCOL=TCP) (HOST=myhost)(PORT=1521))(CONNECT_DATA=(SERVICE_NAME=ora111.example.com)))

 Pool specific

db.hostname

string

Specifies the host system for the Oracle database.

myhostname

 Pool specific

db.password

string

Specifies the password of the specified database user. Include an exclamation at the beginning of the password so that it can be stored encrypted.

!password4user

 Pool specific

db.port

numeric

Specifies the database listener port.

1521

 Pool specific

db.servicename

string

Specifies the network service name of the database.

ora111.example.com

 Pool specific

db.serviceNameSuffix

string

Specifies that the pool points to a CDB, and that the PDBs connected to that CDB should be made addressable by Oracle REST Data Services (see Making All PDBs Addressable by Oracle REST Data Services (Pluggable Mapping)).

apex_pu

 Pool specific

db.sid

string

Specifies the name of the database.

ora111

 Pool specific

db.tnsAliasName

string

Specifies the TNS alias name that matches the name in the tnsnames.ora file.

MY_TNSALIAS

 Pool specific

db.tnsDirectory

string

The directory location of your tnsnames.ora file.

C:\ORACLE\NETWORK\ADMIN

 Pool specific

db.username

string

Specifies the name of the database user for the connection.

APEX_PUBLIC_USER

 Pool specific

debug.printDebugToScreen

boolean

Specifies whether to display error messages on the browser.

Supported values:

  • true

  • false (default)

false

 Global
error.responseFormat string Specifies how the HTTP error responses must be formatted.

Supported values:

  • html - Force all responses to be in HTML format
  • json - Force all responses to be in JSON format
  • auto - Automatically determines most appropriate format for the request (default).
json Global

error.externalPath

string

Specifies the path to a folder that contains the custom error page.

/path/to/error/pages/folder/

 Global

icap.port

numeric

Specifies the Internet Content Adaptation Protocol (ICAP) port to virus scan files.

Either icap.port or icap.secure.port are required to have a value.

1344

 Global
icap.secure.port

numeric

Specifies the Internet Content Adaptation Protocol (ICAP) port to virus scan files.

Either icap.port or icap.secure.port are required to have a value.

If values for both icap.port and icap.secure.port are provided, then the value of icap.port is ignored.

1344 Global

icap.server

string

Specifies the Internet Content Adaptation Protocol (ICAP) server name or IP address to virus scan files.

The icap.server is required to have a value.

servername

 Global

jdbc.DriverType

string

Specifies the JDBC driver type. Supported values:

  • thin

    (Default)

  • oci8

thin

 Pool specific

jdbc.InactivityTimeout

numeric

Specifies how long an available connection can remain idle before it is closed. The inactivity connection timeout is in seconds.

Defaults to 1800.

1800

 Pool specific

jdbc.InitialLimit

numeric

Specifies the initial size for the number of connections that will be created.

Defaults to 10. (The default is low, and should probably be set higher in most production environments.)

10

 Pool specific

jdbc.MaxConnectionReuseCount

numeric

Specifies the maximum number of times to reuse a connection before it is discarded and replaced with a new connection.

Defaults to 1000.

1000

 Pool specific

jdbc.MaxLimit

numeric

Specifies the maximum number of connections.

Defaults to 10. (Might be too low for some production environments.)

20

 Pool specific

jdbc.auth.enabled

boolean

Specifies if the PL/SQL Gateway calls can be authenticated using database users. If the value is true then this feature is enabled. If the value is false, then this feature is disabled. The default value is false. Oracle recommends not to use this feature. This feature used only to facilitate customers migrating from mod_plsql.

false

 Pool specific

jdbc.MaxStatementsLimit

numeric

Specifies the maximum number of statements to cache for each connection.

Defaults to 10.

10

 Pool specific

jdbc.MinLimit

numeric

Specifies the minimum number of connections.

Defaults to 2.

1

 Pool specific

jdbc.statementTimeout

numeric

Specifies a timeout period on a statement.

An abnormally long running query or script, executed by a request, may leave it in a hanging state unless a timeout is set on the statement. Setting a timeout on the statement ensures that all the queries automatically timeout if they are not completed within the specified time period.

Defaults to 900.

900

 Pool specific

log.procedure

boolean

Specifies whether procedures are to be logged.

Supported values:

  • true

  • false (default)

false

 Global

misc.defaultPage

string

Specifies the default page to display. The Oracle REST Data Services home page, apex, is commonly used.

apex

 Pool specific

misc.pagination.maxRows

numeric

Specifies the maximum number of rows that will be returned from a query when processing a RESTful service and that will be returned from a nested cursor in a result set. Affects all RESTful services generated through a SQL query, regardless of whether the resource is paginated.

Defaults to 10000.

300

 Pool specific

owa.docTable

string

Specifies the name of the document table used by the file upload.

Defaults to FLOWS_FILES.WWV_FLOW_FILE_OBJECTS$ value.

Note:

For APEX 4.x and above this parameter should not be used.

MYDOCTABLE

 Pool specific

procedure.postProcess

string

Specifies the procedure name(s) to execute after executing the procedure specified on the URL. Multiple procedure names must be separated by commas.

SCHEMA1.SUBMIT.REQUEST,FINISHTASK

 Pool specific

procedure.preProcess

string

Specifies the procedure name(s) to execute prior to executing the procedure specified on the URL. Multiple procedure names must be separated by commas.

SCOTT.PREPROC1, INITIALIZE, PKG1.PROC

 Pool specific

procedure.rest.preHook

string

 Specifies the function to be invoked prior to dispatching each Oracle REST Data Services based REST Service. The function can perform configuration of the database session, perform additional validation or authorization of the request. If the function returns true, then processing of the request continues. If the function returns false, then processing of the request is aborted and an HTTP 403 Forbidden status is returned.

MYAPP.VALIDATE_REST_CALL

 Pool specific

security.disableDefaultExclusionList

boolean

If this value is set to true, then the Oracle REST Data Services internal exclusion list is not enforced.

Note: The Oracle REST Data Services internal exclusion list blocks the users from accessing the following:
  • sys.*
  • dbms_*
  • utl_*
  • owa_*
  • owa.*
  • htp.*
  • htf.*
  • wpg_docload.*

Supported values:

  • true
  • false (default)

Oracle recommends that you do not set this value to true. That is, do not disable the default internal exclusion list. The only possible exception is temporarily disabling the internal exclusion list for debugging purposes.

false

 Global

security.exclusionList

string

Specifies a pattern for procedures, packages, or schema names which are forbidden to be directly executed from a browser.

Procedure names can contain the wildcard characters asterisk (*) or question mark (?). Use an asterisk (*) to substitute zero or more characters and a question mark (?) to substitute for any one character.

Note: Separate multiple patterns using commas.

customer_account,bank*, employe?

 Global

security.inclusionList

string

Specifies a pattern for procedures, packages, or schema names which are allowed to be directly executed from a browser.

Procedure names can contain the wildcard characters asterisk (*) or question mark (?). Use an asterisk (*) to substitute zero or more characters and a question mark (?) to substitute for any one character.

Note: Separate multiple patterns using commas.

apex, p, v, f, wwv_*, y*, c*

 Global

security.maxEntries

numeric

Specifies the maximum number of cached procedure validations. Defaults to 2000. Set this value to 0 to force the validation procedure to be invoked on each request.

2000

 Global

security.requestAuthenticationFunction

string

Specifies an authentication function to determine if the requested procedure in the URL should be allowed or disallowed for processing. The function should return true if the procedure is allowed; otherwise, it should return false. If it returns false, Oracle REST Data Services will return WWW-Authenticate in the response header.

owa_custom.authorize

 Pool specific

security.requestValidationFunction

string

Specifies a validation function to determine if the requested procedure in the URL should be allowed or disallowed for processing. The function should return true if the procedure is allowed; otherwise, return false.

CHECK_VALID_PROCEDURE

 Pool specific

security.verifySSL

boolean

Specifies whether HTTPS is available in your environment.

Supported values:

  • true (default)

  • false

If you change the value to false, see Using OAuth2 in Non-HTTPS Environments.

true

 Global

soda.defaultLimit

string

When using the SODA REST API, specifies the default number of documents returned for a GET request on a collection when a limit is not specified in the URL. Must be a positive integer, or "unlimited" for no limit.

Defaults to 100.

75

 Pool specific

soda.maxLimit

string

When using the SODA REST API, specifies the maximum number of documents that will be returned for a GET request on a collection URL, regardless of any limit specified in the URL. Must be a positive integer, or "unlimited" for no limit.

Defaults to 1000.

700

 Pool specific

restEnabledSql.active

boolean
Specifies whether the REST-Enabled SQL service is active. Supported values:

  • true

  • false (default)

true

 Pool specific