8i | 9i | 10g | 11g | 12c | 13c | 18c | 19c | 21c | 23c | Misc | PL/SQL | SQL | RAC | WebLogic | Linux
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.
- Installation
- Starting/Stopping ORDS in Standalone Mode
- Auto SSL (HTTPS)
- SSL Configuration (HTTPS)
- APEX Static Images
- Static Resources (Document Root)
- Custom Error Pages
- Access Log
- All Settings
Related articles.
- Oracle REST Data Services (ORDS) : All Articles
- Oracle REST Data Services (ORDS) : Installation on Tomcat (ORDS Version 22.1 Onward)
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:
- Serve Commands for Running in Standalone Mode
- Oracle REST Data Services (ORDS) : All Articles
- Oracle REST Data Services (ORDS) : Installation on Tomcat (ORDS Version 22.1 Onward)
Hope this helps. Regards Tim...