8i | 9i | 10g | 11g | 12c | 13c | 18c | 19c | 21c | Misc | PL/SQL | SQL | RAC | WebLogic | Linux

Home » Articles » Misc » Here

Oracle REST Data Services (ORDS) : Standalone Mode (ORDS Version 22.1 Onward)

These instructions work for ORDS version 22.1 onward. If you want to use a version prior to ORDS 22.1, use the instructions here.

Oracle supports Oracle REST Data Services (ORDS) running in standalone mode using the built-in Jetty web server, so there is no need to worry about installing Tomcat or WebLogic unless you have a compelling reason to do so. Removing this extra layer means one less layer to learn and one less layer to patch.

Related articles.

Installation

The ORDS installation process is similar regardless of the application server being used, so you should follow the installation described here

We will use the following environment variables when referencing the paths in this article. Notice we are adding the ORDS_HOME/bin directory to our PATH, so we don't have to explicitly state the path each time we use the ords command.

export JAVA_HOME=/u01/java/latest
export ORDS_HOME=/u01/ords
export ORDS_CONFIG=/u01/config/ords
export PATH=${ORDS_HOME}/bin:${PATH}

Setting the ORDS_CONFIG environment variable means we don't need to explicitly use the --config argument in the ords commands below, but we will still include it anyway.

Starting/Stopping ORDS in Standalone Mode

The default Java heap size will result in failures, so we need to set the heap size using the _JAVA_OPTIONS environment variable. We can then use the serve command to start ORDS in standalone mode.

export _JAVA_OPTIONS="-Xms1126M -Xmx1126M"

ords --config ${ORDS_CONFIG} serve

Resources will now be available from the following URL, adjusting your hostname as applicable.

http://localhost:8080/ords/

Standalone mode will capture the console and push all log information to it. We can stop ORDS using CTRL+C.

For a production deployment we should start ORDS as a background process and push the output to a log file. For example, we could create a file called "~/scripts/start_ords.sh" with the following contents. Remember to adjust paths as required.

#!/bin/bash
export PATH=/usr/sbin:/usr/local/bin:/usr/bin:/usr/local/sbin:$PATH
export JAVA_HOME=/u01/java/latest
export ORDS_HOME=/u01/ords
export ORDS_CONFIG=/u01/config/ords
LOGFILE=/home/oracle/scripts/logs/ords-`date +"%Y""%m""%d"`.log
export _JAVA_OPTIONS="-Xms1126M -Xmx1126M"
nohup ${ORDS_HOME}/bin/ords --config ${ORDS_CONFIG} serve >> $LOGFILE 2>&1 &
echo "View log file with : tail -f $LOGFILE"

We can kill ORDS by killing the background process. We create a scripts called "~/scripts/stop_ords.sh" with the following contents.

#!/bin/bash
export PATH=/usr/sbin:/usr/local/bin:/usr/bin:/usr/local/sbin:$PATH
kill `ps -ef | grep [o]rds.war | awk '{print $2}'`

We create the log directory and make the scripts executable.

mkdir -p ~/scripts/logs
chmod u+x ~/scripts/*.sh

We can then easily stop and start ORDS using the scripts.

~/scripts/stop_ords.sh
~/scripts/start_ords.sh

Auto SSL (HTTPS)

By default ORDS uses HTTP on port 8080. We can alter the port using the --port argument. We can make ORDS use HTTPS by adding the --secure argument, which will default the port to 8443, but we can alter that using the --port argument. In this example we explicitly set the port to the default HTTPS value.

export _JAVA_OPTIONS="-Xms1126M -Xmx1126M"

ords --config ${ORDS_CONFIG} serve --secure --port 8443

ORDS will automatically create a self-signed certificate for use with SSL if you don't specify a valid certificate and key. The certificate and key are stored in the "$ORDS_CONFIG/global/standalone" directory. Resources will now be available from the following URL, adjusting your hostname as applicable.

https://localhost:8443/ords/

We can set this as the default action using the following command. The presence of the HTTPS port implies ORDS is running in secure mode.

ords --config ${ORDS_CONFIG} config set standalone.https.port 8443

The settings are added to the "$ORDS_CONFIG/global/settings.xml" file.

We can now run ORDS using HTTPS with the following command.

export _JAVA_OPTIONS="-Xms1126M -Xmx1126M"

ords --config ${ORDS_CONFIG} serve

If you are using the command line arguments, remember to amend your "start_ords.sh" script.

SSL Configuration (HTTPS)

You should probably be fronting ORDS with a reverse proxy or a load balancer, which is where your Certificate Authority (CA) certificates should live. Even so, you will probably want your internal traffic to use HTTPS also, so you will need to configure Jetty to use HTTPS. If you have a proper CA certificate and key, make sure they are in DER format. In this case we will manually create a new self-signed certificate and use that for the HTTPS configuration. Remember to adjust the "dname" and passwords as required.

mkdir ~/keystore
cd ~/keystore

# Create a self-signed certificate in a JKS keystore.
$JAVA_HOME/bin/keytool -genkey -keyalg RSA -alias selfsigned -keystore keystore.jks \
   -dname "CN=`hostname`, OU=Example Department, O=Example Company, L=Birmingham, ST=West Midlands, C=GB" \
   -storepass password1 -validity 3600 -keysize 2048 -keypass password1

# Create a PKCS12 keystore from the JKS keystore.
$JAVA_HOME/bin/keytool -importkeystore -srckeystore keystore.jks -srcalias selfsigned -srcstorepass password1 \
   -destkeystore keystore.p12 -deststoretype PKCS12 -deststorepass password1 -destkeypass password1 

# Extract the key and certificate in PEM format.
openssl pkcs12 -in keystore.p12 -nodes -nocerts -out `hostname`-key.pem
openssl pkcs12 -in keystore.p12 -nokeys -out `hostname`.pem

# Convert them to DER format.
openssl pkcs8 -topk8 -inform PEM -outform DER -in `hostname`-key.pem -out `hostname`-key.der -nocrypt
openssl x509 -inform PEM -outform DER -in `hostname`.pem -out `hostname`.der

If everything has gone OK you now have key and certificate in DER format. That file names are based on your hostname, so they will probably look different.

$ ls *.der
localhost.localdomain.der  localhost.localdomain-key.der
$

We can now start ORDS using this certificate and key as follows.

export _JAVA_OPTIONS="-Xms1126M -Xmx1126M"

ords --config ${ORDS_CONFIG} serve --certificate ~/keystore/localhost.localdomain.der --key ~/keystore/localhost.localdomain-key.der

The --secure and --port settings are implied because we are using a certificate, but we could set them explicitly and get the same result.

export _JAVA_OPTIONS="-Xms1126M -Xmx1126M"

ords --config ${ORDS_CONFIG} serve --secure --port 8443 --certificate ~/keystore/localhost.localdomain.der --key ~/keystore/localhost.localdomain-key.der

Resources will now be available from the following URL, adjusting your hostname as applicable.

https://localhost:8443/ords/

We can set this as the default using the following commands. The presence of the HTTPS port implies ORDS is running in secure mode.

ords --config ${ORDS_CONFIG} config set standalone.https.port 8443
ords --config ${ORDS_CONFIG} config set standalone.https.cert ~/keystore/localhost.localdomain.der
ords --config ${ORDS_CONFIG} config set standalone.https.cert.key ~/keystore/localhost.localdomain-key.der

The settings are added to the "$ORDS_CONFIG/global/settings.xml" file.

We can now run ORDS using HTTPS and our certificate with the following command.

export _JAVA_OPTIONS="-Xms1126M -Xmx1126M"

ords --config ${ORDS_CONFIG} serve

If you are using the command line arguments, remember to amend your "start_ords.sh" script.

APEX Static Images

When using ORDS to front APEX applications, ORDS should be configured to serve the APEX static files.

export APEX_IMAGES=/u01/software/apex/images

ords --config ${ORDS_CONFIG} config set standalone.static.path ${APEX_IMAGES}

The settings are added to the "$ORDS_CONFIG/global/settings.xml" file.

We must restart ORDS for the changes to take effect.

~/scripts/stop_ords.sh
~/scripts/start_ords.sh

Static Resources (Document Root)

ORDS can be used to serve static content like a regular web server. The default location requires the following path.

mkdir -p ${ORDS_CONFIG}/global/doc_root

The default location can be altered using the --document-root argument on the command line, or by amending the following default setting.

ords --config ${ORDS_CONFIG} config set standalone.doc.root ${ORDS_CONFIG}/global/doc_root

If you have altered the default setting, ORDS will need to be restarted for it to take effect.

~/scripts/stop_ords.sh
~/scripts/start_ords.sh

Custom Error Pages

ORDS will automatically handle the typical HTTP errors. If you are fronting ORDS with a load balancer, you may wish to use that to handle custom error messages, rather than altering the ORDS configuration. If you need it, ORDS can handle custom error pages. Amend the error.externalPath setting with the location of your custom error pages.

ords --config ${ORDS_CONFIG} config set error.externalPath ~/error-pages

Create the required custom error files. I've just created some simple ones to test with.

mkdir -p ~/error-pages
echo "404 Error: Whoops" > ~/error-pages/404.html
echo "500 Error: Whoops" > ~/error-pages/500.html

Restart ORDS.

~/scripts/stop_ords.sh
~/scripts/start_ords.sh

Access Log

Access logs are really important if you want to know who is accessing your web server. We use the standalone.access.log setting to determine where ORDS writes the access logs.

ords --config ${ORDS_CONFIG} config set standalone.access.log ${ORDS_CONFIG}/logs

Restart ORDS for the setting to take effect.

~/scripts/stop_ords.sh
~/scripts/start_ords.sh

Once we access ORDS we will see an access log created in the directory we specified. The access logs have the "ords_YYYY_MM_DD.log" name format.

All Settings

The full list of settings can be displayed using the following command.

$ ords config info

ORDS: Release 22.1 Production on Fri Apr 22 10:16:02 2022

Copyright (c) 2010, 2022, Oracle.

Configuration:
  /u01/config/ords/

Settings:

apex.security.administrator.rolesComma de-limited list of
                                 additional roles to assign
                                 authenticated APEX
                                 administrator type users.

apex.security.developer.roles    Comma de-limited list of
                                 additional roles to assign
                                 authenticated APEX developer
                                 type users.

apex.security.user.roles         Comma de-limited list of
                                 additional roles to assign
                                 authenticated regular APEX
                                 users.

autoupgrade.api.aulocation       A configuration setting for
                                 AutoUpgrade.jar location.

autoupgrade.api.enabled          A configuration setting to
                                 enable AutoUpgrade REST API
                                 features.

autoupgrade.api.jvmlocation      A configuration setting for
                                 AutoUpgrade REST API JVM
                                 location.

autoupgrade.api.loglocation      A configuration setting for
                                 AutoUpgrade REST API log
                                 location.

cache.metadata.enabled           Specifies the setting to
                                 enable or disable metadata
                                 caching.

cache.metadata.timeout           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.

database.api.enabled             Enable Database API feature.

database.api.management.services.disabledDisable the Database API
                                 administration related
                                 services. Only applicable
                                 when Database API is enabled.

db.adminUser                     The username for the database
                                 account that ORDS will use
                                 for administration operations
                                 in the database.

db.adminUser.password            The password for the database
                                 account that ORDS will use
                                 for administration operations
                                 in the database.

db.cdb.adminUser                 The username for the database
                                 account that ORDS will use
                                 for Pluggable Database
                                 Lifecycle Management.

db.cdb.adminUser.password        The password for the database
                                 account that ORDS will use
                                 for Pluggable Database
                                 Lifecycle Management.

db.connectionType                The database connection type.
                                 Specify one of the values:
                                 basic, tns, customurl.

db.credentialsSource             Specifies the source for
                                 database credentials when
                                 creating a direct connection
                                 for running SQL statements.
                                 Value can be one of: pool or
                                 request. If pool is used, the
                                 credentials defined in this
                                 pool will be used to create a
                                 JDBC connection. If request
                                 is used, the credentials in
                                 the request will be used to
                                 create a JDBC connection and
                                 if successful grant the
                                 requestor SQL Developer role.
                                 The default value is pool.

db.customURL                     The JDBC URL connection to
                                 connect to the database.

db.hostname                      The host name of the database
                                 server.

db.invalidPoolTimeout            Specifies how long to wait
                                 before retrying an invalid
                                 pool.

db.password                      The database password.

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

db.port                          The port of the database
                                 server listener.

db.serviceNameSuffix             The service name suffix for
                                 PDBs connected to the CDB.

db.servicename                   The database service name.

db.tnsAliasName                  The TNS alias name that
                                 matches the name in the
                                 tnsnames.ora file.

db.tnsDirectory                  The directory location of
                                 your tnsnames.ora file.

db.username                      The database user name.

db.wallet.zip                    The wallet archive (provided
                                 in BASE64 encoding)
                                 containing connection details
                                 for the pool.

db.wallet.zip.path               The path to a wallet archive
                                 containing connection details
                                 for the pool.

db.wallet.zip.service            Specifies the service name in
                                 the wallet archive for the
                                 pool.

debug.printDebugToScreen         Specifies whether to display
                                 error messages in the browser.

debug.trackResources             Enable tracking of JDBC
                                 resources that if not
                                 released will cause resource
                                 leaks/exhaustion in the
                                 database. Tracking imposes a
                                 performance overhead.

error.externalPath               The path to the external
                                 error pages.

error.responseFormat             Specifies in what format
                                 error responses should be
                                 rendered. Possible values:
                                 HTTP, JSON, AUTO. Defaults to
                                 AUTO.

feature.openservicebroker.excludeTo disable the Open Service
                                 Broker services available for
                                 the pool.

feature.sdw                      Enable Database Actions
                                 feature.

http.cookie.filter               A comma separated list of
                                 HTTP Cookies to exclude when
                                 initializing an Oracle Web
                                 Agent environment.

icap.port                        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 when
                                 icap.server is set.

icap.secure.port                 Specifies the Internet
                                 Content Adaptation Protocol
                                 (ICAP) secure port to virus
                                 scan files. Either icap.port
                                 or icap.secure.port are
                                 required to have a value when
                                 icap.server is set.

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

jdbc.DriverType                  The Oracle JDBC URL subtype
                                 that can have one of the
                                 values: thin, oci8. Defaults
                                 to thin.

jdbc.InactivityTimeout           Specify how long an available
                                 connection can remain idle
                                 before it is closed. The
                                 inactivity connection timeout
                                 is in seconds. Defaults to
                                 1800.

jdbc.InitialLimit                The initial size for the
                                 number of connections that
                                 will be created. Defaults to
                                 10.

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

jdbc.MaxLimit                    The maximum number of
                                 connections. Defaults to 10.

jdbc.MaxStatementsLimit          The maximum number of
                                 statements to cache for each
                                 connection. Defaults to 10.

jdbc.MinLimit                    The minimum number of
                                 connections. Defaults to 2.

jdbc.auth.admin.role             Identifies the database role
                                 that signifies the database
                                 user should get the SQL
                                 Administrator role.

jdbc.auth.enabled                Specifies if the PL/SQL
                                 Gateway calls can be
                                 authenticated using database
                                 users. Defaults to false. Set
                                 to true to enable feature.
                                 Oracle recommends not to use
                                 this feature. This feature
                                 used only to facilitate
                                 customers migrating from
                                 mod_plsql.

jdbc.cleanup.mode                Specifies how a pooled JDBC
                                 connection, and corresponding
                                 database session, is released
                                 when a request has been
                                 processed.

jdbc.driverName                  The name of the JDBC driver
                                 to use.

jdbc.statementTimeout            Specify how long a borrowed
                                 (in use) connection can
                                 remain unused before it is
                                 considered as abandoned and
                                 reclaimed. The abandoned
                                 connection timeout is in
                                 seconds.

json.sdo.geometry.output.geojson Specify that SDO Geometry
                                 data should be returned in
                                 GeoJSON format.

misc.defaultPage                 Default page (PL/SQL
                                 procedure) to invoke if the
                                 URL points to the context
                                 root of a database pool.
                                 Default value is apex.

misc.pagination.maxRows          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.

owa.trace.sql                    Boolean property that if true
                                 causes a trace of the SQL
                                 statements performed by
                                 Oracle Web Agent to be echoed
                                 to the log.

plsql.gateway.mode               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 direct is used, the pool
                                 will serve PL/SQL Gateway
                                 requests directly. If proxied
                                 is used, PLSQL_GATEWAY_CONFIG
                                 view is used to determine the
                                 user to proxy to.

procedure.rest.preHook           Name of a stored PL/SQL
                                 function that should be
                                 invoked prior to dispatching
                                 any REST request.

request.traceHeaderName          Denotes 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).

resource.templates.enabled       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.

restEnabledSql.active            Enable REST-Enabled SQL
                                 feature.

security.credentials.attempts    The maximum number of
                                 unsuccessful password
                                 attempts allowed. Enabled by
                                 setting a positive integer
                                 value. Defaults to -1.

security.credentials.file        The file where credentials
                                 are stored.

security.credentials.lock.time   The period to lock account
                                 that has exceeded maximum
                                 attempts. Defaults to 10
                                 minutes.

security.requestValidationFunctionSpecifies 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.

security.validationFunctionType  Indicate what type the
                                 security.requestValidationFunc
                                 ion is: javascript or plsql.
                                 Defaults to plsql.

security.verifySSL               Indicate whether HTTPS is
                                 available in your environment.

standalone.access.log            Path to the folder to store
                                 HTTP request access logs. If
                                 not specified then no access
                                 log will be generated.

standalone.binds                 Comma separated list of host
                                 names or IP addresses to
                                 identify a specific network
                                 interface on which to listen,
                                 default 0.0.0.0.

standalone.context.path          The context path where {0} is
                                 located, defaults to /ords

standalone.doc.root              Points to the location where
                                 static resources, to be
                                 served under the / root
                                 server path are located.

standalone.http.port             HTTP listen port, default 8080

standalone.https.cert            SSL certificate path. If you
                                 are providing the SSL
                                 certificate, you must specify
                                 the certificate location.

standalone.https.cert.key        SSL certificate key path. If
                                 you are providing the SSL
                                 certificate, you must specify
                                 the certificate key location.

standalone.https.host            SSL certificate hostname

standalone.https.port            HTTPS listen port, default
                                 8443

standalone.static.context.path   The Context path where
                                 Application Express static
                                 resources are located,
                                 defaults to /i

standalone.static.path           Path to the folder containing
                                 static resources required by
                                 APEX

standalone.stop.timeout          The period for Standalone
                                 Mode to wait to gracefully
                                 shutdown.
$

For more information see:

Hope this helps. Regards Tim...

Back to the Top.