4 Install Oracle Machine Learning for R Server
This chapter explains how to install and administer OML4R Server. This chapter includes these topics:
- About Oracle Machine Learning for R Server
OML4R includes components on the Oracle Database server that enable an OML4R client to interact with OML4R Server. - Oracle Machine Learning for R Server Requirements
Before installing OML4R Server, verify your system environment, and ensure that your user ID has the proper permissions. - Install Oracle Machine Learning for R Server for Oracle Database 19c or later
Instructions for installing OML4R Server for Oracle Database 19c or later. - Install Oracle Machine Learning for R Server for Oracle Database 12c and Earlier
Instructions for installing OML4R Server for Oracle Database 12c or earlier. - Verify the OML4R Server Installation
To verify the success of an OML4R Server installation for Oracle Database 12c and earlier using theserver.sh
script, you can view the log files. For an Oracle Database 18c and later installation, the SQL scriptrqcfg.sql
returns any errors encountered. - Install OML4R Server in a Multitenant Environment
Information about installing OML4R Server in a Multitenant Environment.
Related Topics
4.1 About Oracle Machine Learning for R Server
OML4R includes components on the Oracle Database server that enable an OML4R client to interact with OML4R Server.
Note:
The version of OML4R must be the same on the server and on each client computer. Also, the version of R must be the same on the server and on each client computer.The components are:
-
Oracle R Distribution or open source R
-
OML4R Server
-
The RQSYS schema
-
Metadata and executable code in
sys
-
OML4R Server libraries in
$ORACLE_HOME/lib
(Linux and UNIX) or%ORACLE_HOME%\bin
(Windows) -
OML4R R packages in
$ORACLE_HOME/R/library
(%ORACLE_HOME%\R\library
on Windows)The OML4R packages and supporting packages on the server support embedded R execution. These same packages must be installed separately on each client computer. (See About the OML4R Packages).
-
See the following topics for additional information:
See Also:
- Table 1-4 for a list of supported R and OML4R versions.
- Figure 1-2 for an illustration of the server and client components of OML4R.
- About the RQSYS Schema
The RQSYS schema is the system account for Oracle Machine Learning for R in Oracle Database. - Security Best Practices for OML4R
To minimize the risk of compromising the security of an OML4R Server in Oracle Database, Oracle recommends the following security best practices.
Parent topic: Install Oracle Machine Learning for R Server
4.1.1 About the RQSYS Schema
The RQSYS schema is the system account for Oracle Machine Learning for R in Oracle Database.
It contains metadata, PL/SQL packages, and other executable code that is used internally by OML4R Server.
The OML4R Server installation process creates RQSYS as a locked account with an expired password. The rqsys
user does not have the CREATE SESSION
privilege.
Parent topic: About Oracle Machine Learning for R Server
4.1.2 Security Best Practices for OML4R
To minimize the risk of compromising the security of an OML4R Server in Oracle Database, Oracle recommends the following security best practices.
OML4R Server components in an Oracle Database instance include the locked and password-expired RQSYS schema, which contains and manages OML4R metadata. Users connect to OML4R Server through their database connection credentials. The RQADMIN role grants a user the privilege of creating R functions as scripts in the OML4R R script repository; those scripts can be executed using OML4R embedded R execution.
Oracle recommends the following security best practices.
-
Do not unlock the RQSYS schema or enable its login.
-
Grant the RQADMIN role only to database users who are responsible for creating and managing the R script repository.
-
Create private R scripts and grant access to other users as needed. Global R scripts are visible to and can be executed by any OML4R user.
-
Use parameters or the OML4R datastore to transfer data between embedded R execution scripts and Oracle Database. R scripts should not interact with the server file system or the network.
-
Set the OML4R embedded R execution memory limit properly based upon the Oracle Database server resources and usage patterns. The default value is 2 GB per connection.
-
Use the auto-connect feature (
connect=TRUE
) instead of providing explicit database credentials when connecting back to the Oracle Database server in an R script that uses embedded R execution. -
Do not allow unauthorized R packages or C libraries to be loaded on the Oracle Database server for use in embedded R execution.
-
Load dependent shared libraries from the
$ORACLE_HOME/lib
directory to prevent the use of unauthorized libraries.
Related Topics
Parent topic: About Oracle Machine Learning for R Server
4.2 Oracle Machine Learning for R Server Requirements
Before installing OML4R Server, verify your system environment, and ensure that your user ID has the proper permissions.
You should also have installed the OML4R Server prerequisites: Oracle Database and Oracle R Distribution or open source R.
- System Requirements
Lists the system requirements for OML4R Server. - Environment Variables
Lists the environment variables required by OML4R Server. - User Requirements
Lists the requirements for the operating system user who installs OML4R Server.
Related Topics
Parent topic: Install Oracle Machine Learning for R Server
4.2.1 System Requirements
Lists the system requirements for OML4R Server.
-
The operating system must conform to the requirements specified in Oracle Machine Learning for R System Requirements for On-Premises Database.
-
Oracle Database must be installed and configured as described in Install and Configure the Database for Oracle Machine Learning for R.
Note:
You can install OML4R Server in a pluggable database (PDB) in a multitenant environment. See Oracle Database Administrator's Guide.
-
R must be installed as described in Install R for Oracle Machine Learning for R.
Parent topic: Oracle Machine Learning for R Server Requirements
4.2.2 Environment Variables
Lists the environment variables required by OML4R Server.
Table 4-1 Environment Variable Requirements for Oracle Machine Learning for R Server
Platform | Environment Variable Requirement |
---|---|
all |
On Windows, you can find the value of Oracle home and the Oracle instance identifier in the Windows Registry. If more than one Oracle home or Oracle instance exist on this computer, then you can specify the required values in environment variables. See Create and Modify Environment Variables on Windows. |
Linux |
|
|
|
|
|
Microsoft Windows |
You can find the value of the R home directory in the Windows Registry. If more than one R home exist on this computer, then you can specify the required value in an environment variable. See Create and Modify Environment Variables on Windows. |
Parent topic: Oracle Machine Learning for R Server Requirements
4.2.3 User Requirements
Lists the requirements for the operating system user who installs OML4R Server.
Table 4-2 User Requirements for OML4R Server Installer
Platform | User Requirement |
---|---|
Linux and UNIX |
|
Microsoft Windows |
|
See the following topics for additional information:
- About Operating System Authentication
Describes the operating system authentication used by OML4R Server. - Verify the Group Membership of Your User ID
Describes how to determine the group memberships required by OML4R Server.
Parent topic: Oracle Machine Learning for R Server Requirements
4.2.3.1 About Operating System Authentication
Describes the operating system authentication used by OML4R Server.
The OML4R Server installation script uses system authentication to connect to the database identified by ORACLE_HOME
and ORACLE_SID
. System authentication is based on the operating system credentials of the user instead of the database credentials.
For example, on a Linux system, the OML4R installation script uses this statement to start SQL*Plus without a password:
$ORACLE_HOME/bin/sqlplus / as sysdba
Membership in a special operating system group enables system authentication for Oracle Database. The operating system group is created during installation of the database, and the identity of the installer is automatically assigned to the group. The generic name for the group is OSDBA. On Linux and UNIX, the name for OSDBA is dba
. On Windows, the name for OSDBA is ora_dba
.
The user that installs OML4R Server must belong to OSDBA.
See Also:
-
"Using Operating System Authentication" in Oracle Database Administrator's Guide
-
"Overview of Operating System Authentication Enabled at Installation" in Oracle Database Platform Guide for Microsoft Windows
Parent topic: User Requirements
4.2.3.2 Verify the Group Membership of Your User ID
Describes how to determine the group memberships required by OML4R Server.
As described in "About Operating System Authentication", the Linux or UNIX user ID that runs the OML4R Server installation script must belong to the dba
group. Membership in the dba
group is also required for running other OML4R scripts on the server. On Windows, the dba
group is called ora_dba
.
To determine the group membership of your Linux or UNIX user ID, type this command:
% groups
dba othergroup
To determine the group membership of your Windows user ID:
- Open Windows Control Panel.
- Select Users Accounts.
- Select Manage User Accounts.
- On the Users tab of the User Accounts dialog, the name, domain, and group of each user account are listed. Verify that your user ID belongs to the group
ora_dba
.
Parent topic: User Requirements
4.3 Install Oracle Machine Learning for R Server for Oracle Database 19c or later
Instructions for installing OML4R Server for Oracle Database 19c or later.
The rqcfg.sql
script enables the OML4R Server components that are part of the database, configures some aspects of the server, and installs some OML4R database objects.
Before installing OML4R Server, install R, as described in Install R for Oracle Machine Learning for R.
For use with R-4.0.5, the OML4R Server packages are built under each distinct R version. To use OML4R with R-4.0.5, you must download and install those OML4R Server packages.
- Prepare to Use OML4R Server with R-3.6.1 or Later
Instructions for downloading and installing the OML4R Server packages built under R-3.6.1. - Install OML4R Server Using rqcfg.sql
Instructions for installing OML4R Server for Oracle Database 19c and later.
Parent topic: Install Oracle Machine Learning for R Server
4.3.1 Prepare to Use OML4R Server with R-3.6.1 or Later
Instructions for downloading and installing the OML4R Server packages built under R-3.6.1.
In Oracle Database 18c and 19c, the OML4R Server packages
are in the $ORACLE_HOME/R/library/
directory. For use with R-3.6.1
or later, you can either rename the OML4R packages in that
directory or you can delete them. You then download and install the OML4R Server packages that are compatible with the R version
you are using.
rqcfg.sql
script.If you have already installed OML4R Server and are upgrading R, then you do not need to, and
should not, run the rqcfg.sql
script.
4.3.2 Install OML4R Server Using rqcfg.sql
Instructions for installing OML4R Server for Oracle Database 19c and later.
After installing R, install OML4R Server by running the /oml4rserver_install_dir/server/rqcfg.sql
script and providing values for the arguments in the following table.
Table 4-3 Arguments to the rqcfg.sql Installation Script
Argument | Description |
---|---|
|
Specify a permanent tablespace for the RQSYS schema. |
|
Specify a temporary tablespace. |
|
Specify the |
|
Specify the |
4.4 Install Oracle Machine Learning for R Server for Oracle Database 12c and Earlier
Instructions for installing OML4R Server for Oracle Database 12c or earlier.
Note:
To install OML4R Server without needing to respond to visual prompts, use a batch mode installation such as that described in A Default Batch Installation.
To install OML4R Server:
-
Ensure that your system satisfies the requirements specified in Oracle Machine Learning for R Server Requirements.
-
Create an installation directory for the OML4R Server components. The directory can have any name. For example:
/oml4r_server_install_dir
-
Download the OML4R Server installation files and supporting packages from the Oracle Machine Learning for R Downloads page on the Oracle Technology Network.
-
Accept the license agreement and download the OML4R Server files for your platform to your installation directory.
-
Accept the license agreement and download the OML4R Supporting packages for your platform to your installation directory.
The installation directory now contains two zip files.
ore-server-platform-arch-version.zip ore-supporting-platform-arch-version.zip
-
-
Unzip the files.
unzip ore-server-platform-arch-version.zip unzip ore-supporting-platform-arch-version.zip
The installation directory looks like this after you unzip both files:
For Linux or UNIX:
/oml4r_server_install_dir ore-server-platform-arch-version.zip ore-supporting-platform-arch-version.zip server.sh /server /supporting
For Windows:
\oml4r_server_install_dir ore-server-platform-arch-version.zip ore-supporting-platform-arch-version.zip server.bat \server \supporting
-
For Linux or UNIX, run
server.sh
. For Windows, runserver.bat
. The script performs a default, first-time installation of OML4R Server, as described in A Default Interactive Installation. For details about theserver
script, see About the Server Script.For Linux or UNIX:
./server.sh
For Windows:
server.bat
Note:
Beginning in R-3.3.0, on an Oracle Linux 6 system, it is necessary to set LD_LIBRARY_PATH
in $ORACLE_HOME/hs/admin/extproc.ora
to the location of the R-core-extra RPM so that these libraries are found by the Oracle process running extproc
. On Linux systems, the default location of the R-core-extra RPM is /usr/lib64/R/port/Linux-X64/lib
. In extproc.ora
, enter:
SET LD_LIBRARY_PATH=/usr/lib64/R/port/Linux-X64/lib
For changes in extproc.ora
to take effect, you must stop and restart the database.
This procedure is not necessary on a Linux 7 system, as the required versions of the libraries provided by the R-core-extra RPM are available natively..
See Also:
Example A-1 for an example with output
About the R-core-extra RPM
R has always depended on several third
party libraries, specifically, zlib
, bzip2
,
xz
, pcre
, and curl
. Prior to
R-3.3.0, R depended on older versions of these libraries, but, if they were not found on
the system, bundled copies were included that were built on the fly.
R-3.3.0 depends on newer versions of these libraries and no longer contains the bundled copies. This means that R-3.3.0 won't build against Linux 6 as is, because the native versions of these libraries are older than those that R-3.3.0 requires.
The R-core-extra RPM contains the required versions of these libraries and is provided as a convenience for users of Oracle Linux 6. Adding the location of the libraries in R-core-extra to LD_LIBRARY_PATH
removes the need to built these libraries separately. Oracle Linux 7 and later contain the required versions of these libraries, so the R-core-extra RPM is not required.
The following topic describes the OML4R Server script for Oracle Database 12c and earlier.
- About the Server Script
A single script calledserver
manages the installation and administration of OML4R Server for Oracle Database 12c and earlier releases.
Parent topic: Install Oracle Machine Learning for R Server
4.4.1 About the Server Script
A single script called server
manages the installation and administration of OML4R Server for Oracle Database 12c and earlier releases.
You can rerun the server
script whenever you need to install, uninstall, upgrade, or configure server-side components of OML4R.
The following topics provide details about the script:
- Overview of Server Script Operations
Describes the operations you can perform with theserver.sh(.bat)
script. - Server Script Syntax
Theserver.sh(.bat)
script supports a set of command-line arguments that direct its activities. - Server Script Examples
Example of using theserver
script.
4.4.1.1 Overview of Server Script Operations
Describes the operations you can perform with the server.sh(.bat)
script.
The server.sh(.bat)
script supports the following operations:
-
Installs OML4R Server
-
Uninstalls OML4R Server
-
Upgrades OML4R Server and migrates data from the earlier installation
-
Installs the supporting packages, if they are available
-
Creates or configures a database user, if one does not exist
Note:
You can use the server.sh(.bat)
script to install the supporting packages, or you can choose to perform these tasks separately, as described in the following sections:
Parent topic: About the Server Script
4.4.1.2 Server Script Syntax
The server.sh(.bat)
script supports a set of command-line arguments that direct its activities.
The script can be run in interactive mode, in batch mode, or in hybrid mode. If you run the script without arguments, it installs or upgrades OML4R Server in interactive mode; it attempts to install the supporting packages; and it creates or configures a database user.
The command-line arguments for the server.sh(.bat)
script are described in the following table. The arguments for the script are the same for Linux, UNIX, and Windows. You can obtain a listing of the arguments with brief descriptions by executing the following on a Linux or UNIX system:
./server.sh -h
or
./server.sh --help
On a Windows system, you can obtain a listing of the arguments with brief descriptions by executing the following:
server.bat -h
or
server.bat --help
Table 4-4 Server Script Command-Line Arguments
Argument | Description |
---|---|
|
Install or upgrade OML4R Server. An installation or upgrade includes the following by default:
|
|
Uninstall OML4R Server:
|
|
Never prompt. |
|
Interactive mode (the default). |
|
When uninstalling OML4R Server, keep the R packages and libraries under Oracle home but remove the database objects. Allows OML4R support to be removed from a single database instance or pluggable database (PDB) without affecting other databases in Oracle home. |
|
When uninstalling OML4R Server, remove the R packages and libraries under Oracle home in addition to the database objects. |
|
When combined with |
|
Install supporting packages (the default). |
|
|
|
The name of a pluggable database (PDB) in a multitenant container database (CDB). Multitenant architecture enables an Oracle database to function as a container database that includes zero, one, or many pluggable databases. For information about multitenant architecture, see Oracle Database Concepts. |
|
Permanent tablespace for RQSYS. |
|
Temporary tablespace for RQSYS. |
Parent topic: About the Server Script
4.4.1.3 Server Script Examples
Example of using the server
script.
See the following topics for examples of using the server
script:
- A Default Interactive Installation
Example of a default installation of OML4R Server. - A Default Batch Installation
Example of installing OML4R Server in batch mode.
See Also:
Example A-1 for an example with output
Parent topic: About the Server Script
4.4.1.3.1 A Default Interactive Installation
Example of a default installation of OML4R Server.
For Linux or UNIX:
./server.sh
As shown in Example A-1, a default, interactive installation performs the following:
-
Prints out information about the environment
-
Prompts for the password and permanent and temporary tablespaces for
rqsys
-
Prompts whether to install the supporting packages. (Installs the supporting packages by default if they are available.)
-
Prompts whether to create a user account for OML4R. (Creates a user by default if one does not exist.) When creating a user, prompts for the permanent and temporary tablespaces.
Parent topic: Server Script Examples
4.4.1.3.2 A Default Batch Installation
Example of installing OML4R Server in batch mode.
This example shows an installation like the one in A Default Interactive Installation, but specified to run in batch mode.
For Linux or UNIX:
./server.sh -y --install --setup-user --perm SYSAUX --temp TEMP --user-perm USERS --user-temp TEMP --user OML_USER
Parent topic: Server Script Examples
4.5 Verify the OML4R Server Installation
To verify the success of an OML4R Server installation for Oracle Database 12c and earlier using the server.sh
script, you can view the log files. For an Oracle Database 18c and later installation, the SQL script rqcfg.sql
returns any errors encountered.
For 12c and Earlier, View Log Files
The OML4R Server installation script server.sh
creates log files in the server subdirectory of the installation directory. Examine the log files to verify the success of the installation process.
The following commands on a Linux or UNIX system list the log files:
cd ./oml4r_server_install_dir/server
ls *.log
outcdb.log rqconfig.log rqdrop.log rqgrant.log rqinst.log rqpdrp.log rqproc.log rquser.log
If there are problems with the installation and you are unable to resolve them, you can request help from My Oracle Support or from the R Technologies in Data Warehousing.
Example 4-1 Run Examples to Verify the Server Installation
First execute these commands from an R instance directly on the database server and then execute them from the OML4R client.
Start R using the ORE
script and load the ORE
library.
% ORE
> library(ORE)
Connect to the server. This example connects as the user OML_USER.
ore.connect("OML_USER", password="OML_USERpsw", conn_string="", all=TRUE)
Execute some functions.
## Is the OML4R client connected to the OML4R server?
## The output of this function should be TRUE.
ore.is.connected()
## List the available database tables.
ore.ls()
## Push an R dataframe to a database table.
df <- data.frame(a="abc",
b=1.456,
c=TRUE,
d=as.integer(1))
of <- ore.push(df)
## Run the self-contained example code in the help files associated with
## the following functions.
example("ore.glm") ## Builds an OML4R generalized linear model.
example("ore.stepwise") ## Builds an OML4R stepwise least squares regression model.
example("ore.odmAI") ## Builds an OML4SQL attribute importance model.
example("ore.doEval") ## Runs an embedded R execution function.
Related Topics
Parent topic: Install Oracle Machine Learning for R Server
4.6 Install OML4R Server in a Multitenant Environment
Information about installing OML4R Server in a Multitenant Environment.
You can install OML4R Server in one or more pluggable databases (PDBs) within a multitenant environment. OML4R Server must be installed in a pluggable database, not in the root database.
If you have more than one instance of OML4R Server installed in a Multitenant Container Database (CDB) and you want to uninstall one instance but retain the others, you can perform a partial uninstall as described in Performing a Partial Uninstall.
See Also:
-
Oracle Machine Learning for R User’s Guide for information about connecting to a pluggable database.
-
Oracle Database Concepts for an introduction to multitenant architecture.
-
Oracle Database Administrator's Guide for information about managing a multitenant environment.
Parent topic: Install Oracle Machine Learning for R Server