Installing and Configuring Customer Managed ORDS on Autonomous Database

This section explains how to install and configure Customer Managed Oracle REST Data Services (ORDS) on Autonomous Database.

• About Customer Managed Oracle REST Data Services on Autonomous Database When you provision an Autonomous Database instance, by default Oracle REST Data Services (ORDS) is preconfigured and available for the instance. With the default ORDS, Oracle performs any required configuration, patching, and maintenance. Additionally, you can also configure Autonomous Database to use ORDS running in a customer managed environment.

• Preinstallation Tasks This section describes the preinstallation tasks.

• ORDS Command-Line Interface for Customer Managed ORDS

About Customer Managed Oracle REST Data Services on Autonomous Database

When you provision an Autonomous Database instance, by default Oracle REST Data Services (ORDS) is preconfigured and available for the instance. With the default ORDS, Oracle performs any required configuration, patching, and maintenance. Additionally, you can also configure Autonomous Database to use ORDS running in a customer managed environment.

When you use the default ORDS on Autonomous Database, you cannot modify any of the ORDS configuration options. Use a customer managed environment if you want manual control of the configuration and management of Oracle REST Data Services. For example, use this option when your applications require larger connection pools or if you need more control over the ORDS configuration options.

When ORDS runs in a customer managed environment, you are responsible for configuration, patching, and maintenance of ORDS in the customer managed environment. After you configure Autonomous Database to use your customer managed ORDS in addition to the existing autonomously managed ORDS, you can route ORDS HTTPS traffic through your environment. The default Autonomous Database web server and ORDS are still running and ORDS traffic goes to the ORDS running in the customer managed environment. This provides an additional and alternative HTTPS solution for Autonomous Database.

Installing and configuring a customer managed environment for ORDS allows you to run ORDS with configuration options that are not possible using the default Oracle managed ORDS available with Autonomous Database.

Installing and configuring a customer managed environment for ORDS is only supported with Autonomous Database.

Note:

• A version of Oracle REST Data Services within one major release of what is running in Autonomous Database (Serverless or Dedicated) is required to use a customer managed environment for ORDS with a version closest to that release.

For example:

If your Autonomous Database is currently hosting ORDS version 22.4, then you must be running the latest possible ORDS version with customer managed environment. Maintain the latest version of ORDS as close as possible, for example 23.1 or 22.3 for the best results.

Note:

The latest version of ORDS can be found in the OCI YUM repository and also at ORDS Downloadable Zip File location.

Note: Web servers should be installed on dedicated systems that are separate from the database servers.

  <div class="infoboxnote" markdown="1">

 

  **See Also:**

 

  - [Oracle REST Data Services (ORDS) best practices](https://www.oracle.com/database/technologies/appdev/rest/best-practices/)

 

  - [Interactive Command-Line Interface Installation](installing-and-configuring-oracle-rest-data-services.html#GUID-B52816FE-58C7-4B5A-8EAA-4BB191288322 "Starting with Oracle REST Data Services (ORDS) release 
  24.1, auto installation feature is introduced.This section explains the interactive command-line interface (CLI) installation prompts for creating a new ORDS configuration. Specify the database port for a basic connection.This section explains how to configure Oracle REST Data Services (ORDS) and run in a standalone mode.") and refer to section *HTTPS Protocol and Use my SSL Certificate* for more information and

 

  - [Adding a Signed SSL Certificate to Oracle REST Data Services](/pls/topic/lookup?ctx=en/database/oracle/oracle-rest-data-services/26.3/ordig&id=signed_ssl)

 

  </div>

Preinstallation Tasks

This section describes the preinstallation tasks.

Before performing a customer-managed ORDS installation, you must:

• Download the wallet from your Oracle Autonomous AI Database instance

• If you are using Oracle APEX, then setup the APEX static resources

• Downloading the Autonomous AI Database Wallet This section describes how to download client credentials (Wallets) from the Oracle Cloud Infrastructure console.

• Oracle APEX Static Resources This section describes how to set up the APEX static resources.

Downloading the Autonomous AI Database Wallet

This section describes how to download client credentials (Wallets) from the Oracle Cloud Infrastructure console.

Customer managed ORDS instances for the Autonomous AI Database requires the Autonomous AI Database wallet for the target database. For detailed instructions, see Download Client Credentials (Wallets).

Oracle APEX Static Resources

This section describes how to set up the APEX static resources.

If you are using ORDS with APEX, then setting up the APEX static resources is mandatory.

See Also: Managing Static Resources (Images)

ORDS Command-Line Interface for Customer Managed ORDS

The ORDS Command-Line Interface (CLI) provides the interactive and silent command install adb to automate configuring a Customer Managed ORDS. This includes creating the ORDS configuration in your environment. If you want to use Autonomous Database with Oracle REST Data Services (ORDS) running in a customer managed environment, execute this command. This creates an ORDS runtime database user. ORDS can connect, and provide the privileges to that runtime user. In addition, it creates and provides privileges to the PL/SQL gateway database user used for APEX, PL/SQL Gateway and OWA, and allow connections through the runtime user. The runtime database user and gateway database user are created in the Autonomous Database.

• Interactive Install for ADB Command Line Interface

• Silent Installation of ADB on Command-Line Interface

Interactive Install for ADB Command Line Interface

Use the ORDS Command-Line Interface (CLI) to interactively prompt you for the following information to setup your Customer Managed ORDS.

• Wallet Path

• Net Service Name from tnsnames.ora contained in the wallet zip file

• Administrator user

• Runtime database user

• PL/SQL gateway user

• Additional Database Features

• Standalone options

Examples:

• ords install adb

• ords install adb --interactive [OPTIONS]

• ords install adb -i [0PTIONS]

• Customer Managed ORDS Command Options

• Interactive Installation Prompts This section describes the interactive installation prompts to setup your Customer Managed ORDS.

Customer Managed ORDS Command Options

Option	Description
admin-user <DATABASE USER>	The administrator database user with privileges to create users and grant privileges to database users in the Autonomous Database.
db-pool <POOL NAME>	The name of the database connection pool.
db-user <DATABASE USER>	The ORDS runtime database user.
gateway-user <DATABASE USER>	The PLSQL gateway database user that has privileges to access the stored procedures.
feature-db-api <BOOLEAN>	Specifies if you want to enable DB API feature. Possible values are true or false. If the value is set to true, then DB API feature is enabled. If the value is set to false, then DB API feature is disabled. Returns an error if the specified options are --feature-sdw true and --feature db-api false.
feature-rest-enabled-sql <BOOLEAN>	Specifies if you want to enable REST-Enabled SQL feature. Possible values are true or false. If the value is set to true, then the REST-Enabled SQL feature is enabled. If the value is set to false, then the REST-Enabled SQL feature is disabled. Returns an error if the specified options are --feature-sdw true and --feature-rest-enabled-sql false.
feature-sdw <BOOLEAN>	Specifies if you want to enable Database Actions feature. Possible values are true or false. If the value is set to true, then the Database Actions feature is enabled. If the value is set to false, then the Database Actions feature is disabled. If the option is set to true, then the following settings are set to true in the configuration file: database.api.enabled restEnabledSql.active Returns an error if --feature-sdw true and any of following options are specified, and are set to false: --feature-db-api --feature-rest-enabled-sql
-h, --help	Shows usage information for a command.
-i, --interactive	Prompts for the required information.
log-folder <FOLDER>	Writes the logs in the folder when creating the users and granting privileges to the user. If this option is omitted, then the output is written to standard output.
password-stdin	Reads the password value from standard input when redirecting input to a file or here document.
wallet <PATH>	The location of the wallet zip file downloaded from Autonomous Database. Returns an error if the wallet is omitted and the db.wallet.zip.path setting does not exist in the ORDS configuration.
wallet-service-name <NET SERVICE NAME>	Specifies the net service name in the tnsnames.ora file located in the wallet zip file. If the --wallet-service-name option is omitted, or if the db.wallet.zip.service property is not detected in the ORDS global configuration settings (that is, in the global.xml file), then ORDS defaults to using the <db>_LOW Consumer Group. This value is retrieved from the tnsnames.ora file.

Interactive Installation Prompts

This section describes the interactive installation prompts to setup your Customer Managed ORDS.

To setup your Customer Managed ORDS, use the ORDS Command-Line Interface (CLI) to interactively prompt you for the information.

Example:

ords install adb --interactive --prompt-password --log-folder <LOG
    FOLDER>

Where:

• --prompt-password: prompt you for the runtime database user’s password and the gateway database user’s passwords

• --prompt-password: If this option is omitted, then the passwords are generated.

  Special care should be considered for database user’s password. If you plan to use ORDS on multiple servers and use the same runtime database user and gateway database user, then specify the --prompt-password option to ensure that the same passwords are being used.

Table 1 Interactive Installation Prompts

Prompt Number	Prompt	Description
1.	Enter a number to select the database pool to update, or create an additional database pool. The selected (or created) database pool will be used to configure a Customer Managed ORDS. [1] default MYADB_MEDIUM /path/to/myadb/wallet.zip [2] Create an additional database pool Choose [1]:	Refer to Entering a Number to Select the Database Pool
2.	Enter the database pool name.	Refer to Entering the Database Pool Name
3.	Enter the Autonomous Database Wallet path: /path/to/wallet.zip	Refer to Entering the Autonomous Database Wallet Path
4.	Enter a number to select the TNS Network alias to use [1] DEMO_LOW ...service_name=g123_demo_low.adb.oraclecloud.... [2] DEMO_MEDIUM ...service_name= g123_demo_medium.adb.oracleclo... [3] DEMO_HIGH ...service_name= g123_demo_high.adb.oraclecloud... Choose [1]:	Refer to Enter a Number to Select the TNS Network Alias
5.	Provide database user name with administrator privileges. Enter the administrator username [ADMIN]:	Enter the Administrator Username
6.	Enter the database password for ADMIN:	Enter the Database Password for ADMIN
7.	Enter the ORDS runtime database username [ORDS_PUBLIC_USER2]:	Entering the ORDS Runtime Database Username
8.	Enter the database password for ORDS_PUBLIC_USER2: Confirm password:	Entering the Database Password for ORDS_PUBLIC_USER2
9.	Enter the PL/SQL Gateway database username:	Entering the PL/SQL Gateway Database Username
10.	Enter the database password for ORDS_PLSQL_GATEWAY2: Confirm password:	Enter the Database Password for ORDS_PLSQL_GATEWAY2
11.	Connecting to Autonomous database user: ADMIN TNS Service: DEMO_MEDIUM Retrieving information
12.	Enter a number to select additional feature(s) to enable: [1] Database Actions (Enables all features) [2] REST Enabled SQL and Database API [3] REST Enabled SQL [4] Database API [5] None Choose [1]:	Entering a Number to Select and Enable Additional Feature
13.	Enter a number to configure and start ORDS in standalone mode [1] Configure and start ORDS in standalone mode [2] Skip Choose [1]:	Enter a Number to Configure and Start ORDS
14.	Enter a number to select the protocol [1] HTTP [2] HTTPS Choose [1]: 2	Entering a Number to Use HTTP or HTTPS Protocol
15.	Enter the APEX static resources location: /path/to/apex/images	Entering the APEX Static Resources Location

• Entering a Number to Select the Database Pool

• Entering the Database Pool Name

• Entering the Autonomous Database Wallet Path

• Enter a Number to Select the TNS Network Alias

• Enter the Administrator Username

• Enter the Database Password for ADMIN

• Entering the ORDS Runtime Database Username

• Entering the Database Password for ORDS_PUBLIC_USER2

• Entering the PL/SQL Gateway Database Username

• Enter the Database Password for ORDS_PLSQL_GATEWAY2

• Entering a Number to Select and Enable Additional Feature

• Enter a Number to Configure and Start ORDS

• Entering a Number to Use HTTP or HTTPS Protocol

• Entering the HTTPS Port

• Entering a Number to Select the Certificate Type

• HTTPS Protocol and Use Self-Signed Certificate

• HTTPS Protocol and Use my SSL Certificate

• Entering the APEX Static Resources Location

Entering a Number to Select the Database Pool

This prompt is displayed, if an ORDS configuration exists and contains database pool(s).

You can select a database pool to update, or create an additional database pool for your Customer Managed ORDS.

If option 2 is selected, then Prompt number 2 is displayed. Otherwise, Prompt number 3 is displayed. Note: If this is the first time you are setting up the Customer Managed ORDS, and the ORDS configuration does not exist, then you are prompted for the wallet location. See Prompt number 3.

Entering the Database Pool Name

Specify the database pool name.

Entering the Autonomous Database Wallet Path

Specify the location and filename of the downloaded Autonomous Database wallet.

Note: If this is the first time you are setting up the Customer Managed ORDS, then you are prompted for the wallet location. Otherwise, if an ORDS configuration already exists, then Prompt number 1 is displayed.

Enter a Number to Select the TNS Network Alias

Select the TNS alias name.

Note: The list of TNS alias names are in the tnsnames.ora file located in the wallet.zip file.

See Also: Local Naming Parameters in the tnsnames.ora File

Enter the Administrator Username

Specify a database user with administrator privileges. Defaults the database user to ADMIN.

Enter the Database Password for ADMIN

Specify the password for administrator database user.

Entering the ORDS Runtime Database Username

Specify the ORDS runtime database user. Defaults the database user to ORDS_PUBLIC_USER2.

Entering the Database Password for ORDS_PUBLIC_USER2

Prompts for the password if --prompt-password option is specified on the command line. Otherwise, the password prompt is not displayed, and the password is generated.

Note: If the runtime database user does not exist in the Autonomous Database, then the runtime database user is created and granted privileges. If the runtime database user already exists in the Autonomous Database, and the runtime user’s password does not match the password in the Autonomous Database, then the runtime database user password is changed.

Entering the PL/SQL Gateway Database Username

Specify the ORDS PL/SQL gateway database user.

Enter the Database Password for ORDS_PLSQL_GATEWAY2

Prompts for the password if --prompt-password option is specified on the command line. Otherwise, the password prompt is not displayed, and the password is generated.

Note: If the PL/SQL gateway database user does not exist in the Autonomous Database, then the gateway database user is created and granted privileges. If the gateway user already exists in the Autonomous Database, and the gateway user’s password does not match the password in the Autonomous Database, then the gateway database user password is changed..

Entering a Number to Select and Enable Additional Feature

Select the additional feature that you want to enable.

See Also:

• About Oracle Database Actions

• REST- Enabled SQL Service

• ORDS Database API

Enter a Number to Configure and Start ORDS

You can configure ORDS to run in standalone mode. In addition, you can start ORDS in standalone mode after setup is completed for Customer Managed ORDS.

Entering a Number to Use HTTP or HTTPS Protocol

Displays the HTTP/HTTPS Protocol prompts. Select the protocol (HTTP or HTTPS) that you want to use. Note: Oracle highly recommends to run ORDS in a standalone mode with HTTPS versus HTTP.

• Entering the HTTP Port

Entering the HTTP Port

Specify the HTTP port. The default HTTP port is 8080.

Entering the HTTPS Port

Specify the HTTPS port. The default HTTPS port is 8443.

Table 2 HTTPS Protocol Prompts

Prompt	Description
Enter a number to select the protocol [1] HTTP [2] HTTPS Choose [1]:	Select the protocol (HTTP or HTTPS) that you want to use.
Enter the HTTPS port [8443]:	Specify the HTTPS port. The default HTTPS port is 8443.
Enter a number to select the certificate type [1] Use self-signed certificate (generates automatically) [2] Use my SSL certificate (requires SSL certificate and SSL certificate private key) Choose [1]: 1	Refer to: Entering a Number to Select the Certificate Type HTTPS Protocol and Use Self-Signed Certificate HTTPS Protocol and Use my SSL Certificate

Entering a Number to Select the Certificate Type

You have the option to select the self-signed certificate that generates automatically when running ORDS in standalone mode, or you provide the SSL certificate which requires both the SSL Certificate and its private key.

HTTPS Protocol and Use Self-Signed Certificate

Selecting the prompt Use self-signed certificate prompts you for the SSL hostname.

Table 3 Example of Use Self-Signed Certificate

Prompt
Enter a number to select the certificate type [1] Use self-signed certificate (generates automatically) [2] Use my SSL certificate (requires SSL certificate and SSL certificate private key) Choose [1]: 1 Enter the SSL hostname: myhost

ORDS generates the Self-Signed Certificate when running ORDS in a standalone mode.

The value entered here is stored in the standalone.https.host configuration setting. The Self-Signed Certificate is generated only once and the Common Name value for that certificate is taken from the standalone.https.host configuration setting. Changing the standalone.https.host after the Self-Signed Certificate is generated does not change the Common Name in that certificate.

Table 4 HTTPS Protocol and Use Self-Signed Certificate Prompts

Prompt	Description
SSL Hostname: myhost	Specify the SSL Hostname.

HTTPS Protocol and Use my SSL Certificate

Selecting Use my SSL Certificate requires you to provide an existing SSL certificate and its private key.

Example of Use my SSL Certificate
	Enter a number to select the certificate type [1] Use self-signed certificate (generates automatically) [2] Use my SSL certificate (requires SSL certificate and SSL certificate private key) Choose [1]: 2 Enter the path for the SSL Certificate: /path/to/mycertificate.crt Enter the path for the SSL Certificates private key: /path/to/mycert.der

Table 5 HTTPS Protocol and Use my SSL Certificate Prompts

Prompt	Description
Path for the SSL Certificate: /path/to/mycert.crt	Refer to Entering the Path for the SSL Certificate
Path for the SSL Certificate private key: /path/to/mycert.der	Refer to Entering the Path for the SSL Certificate’s Private Key

• Entering the Path for the SSL Certificate

• Entering the Path for the SSL Certificate’s Private Key

Entering the Path for the SSL Certificate

Specifying the SSL certificate file location and filename.

Example:

/path/to/mycert.crt

See Also: Converting a Private Key to DER (Linux and Unix)

Entering the Path for the SSL Certificate’s Private Key

Specifying the SSL certificate’s private key file location and filename.

Example

/path/to/mycert.der

Entering the APEX Static Resources Location

This prompt displays only if you are maintaining the APEX static resources. Note: If you are using the Oracle Content Delivery Network for the APEX static resources, then this prompt is not displayed.

See Also: Oracle APEX Static Resources

Silent Installation of ADB on Command-Line Interface

For silent installation, provide the following command options to setup your Customer Managed ORDS:

• Database Pool: If this option is omitted, then the default database pool is used.

• Wallet Path: This is required if this option does not exist in the ORDS configuration database pool.

• Wallet Service Name: The TNS alias name from tnsnames.ora file contained in the wallet zip file. If this option is omitted, and the setting db.wallet.zip.service does not exist in the ORDS configuration database pool, then the wallet service name defaults to <DB>_LOW.

• Administrator username and password (Required)

• Runtime database username and password (Required)

• PL/SQL gateway username and password (Required)

• Additional Database Features

Install ADB Command

ords install adb [OPTIONS]

• Using Input Redirection See Also: Customer Managed ORDS Command Options

Using Input Redirection

This section describes how to redirect the standard input using the Here document or to a file.

Redirect STDIN to a file

Redirect STDIN to a file that contains the password. In the following example, the file must contain three passwords. Each password must be on a separate line.

Example:

ords install adb --admin-user <DATABASE USER> --db-user <DATABASE USER> --gateway-user <DATABASE
      USER> --wallet <PATH> --wallet-service-name <NET SERVICE NAME> --feature-sdw <BOOLEAN> --log-folder
      <FOLDER> --password-stdin < filename.txt

Where the filename.txt contains passwords:

<PASSWORD FOR admin-user>
<PASSWORD FOR db-user>
<PASSWORD FOR gateway-user>

Starting from left to right, the first password belongs to the first user option (--admin-user) on the command line. The second password belongs to the second user option on the command line (--db-user) and the third password belongs to the third user (--gateway-user) option on the command-line.

Redirect Standard Input Using Here Document

Redirect STDIN using the Here document (also known as heredoc) for the password(s). The heredoc consists of the ‘<<’ redirection operator followed by a delimiter token.

Each password must be on a separate line and it is ended by the delimiter token.

Example:

ords install adb --admin-user <DATABASE USER> --db-user <DATABASE USER> --gateway-user <DATABASE USER>
--wallet <PATH> --wallet-service-name <NET SERVICE NAME> --feature-sdw <BOOLEAN> --log-folder <FOLDER>
--password-stdin << EOF
<PASSWORD FOR admin-user>
<PASSWORD FOR db-user>
<PASSWORD FOR gateway-user>
EOF

Starting from left to right, the first password belongs to the first user option (--admin-user) on the command line. The second password belongs to the second user option on the command line (--db-user) and the third password belongs to the third user (--gateway-user) option on the command-line. The Here document is ended by the token EOF.

Note: Once the operation is complete, delete the file or script that contains the passwords.