1. Installation and Administration Guide
  2. Install Oracle Machine Learning for R Server

4 Install Oracle Machine Learning for R Server

This chapter explains how to install and administer OML4R Server. This chapter includes these 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:

  • OML4R Server

    • The RQSYS schema

    • Metadata and executable code in sys

    • OML4R Server libraries in $ORACLE_HOME/lib

    • OML4R R packages in $ORACLE_HOME/R/library

      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-3 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 ran 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 ran 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.

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.

Related Topics

Parent topic: Install Oracle Machine Learning for R Server

4.2.1 System Requirements

Lists the system requirements for OML4R Server.

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

Linux

$ORACLE_SID must specify the Service Identifier (SID) of the database that supports OML4R.

$ORACLE_HOME must specify the home directory of the database identified by ORACLE_SID.

$LD_LIBRARY_PATH must include $ORACLE_HOME/lib.

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

  • Member of the dba group

  • Has write access to $ORACLE_HOME/lib

See the following topics for additional information:

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:

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.

To determine the group membership of your Linux or UNIX user ID, type this command:

% groups
dba  othergroup

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 on On-Premises Oracle Database.

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.

Parent topic: Install Oracle Machine Learning for R Server

4.3.1 Prepare to Use OML4R Server with R-4.0.5

Instructions for downloading and installing the OML4R Server packages built under R-4.0.5.

The OML4R Server packages are in the $ORACLE_HOME/R/library/ directory. For use with R-4.0.5, 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 R-4.0.5.

These instructions rename the original OML4R server packages and replace them with ones built under R-4.0.5.
  1. Rename the OML4R packages in the $ORACLE_HOME/R/library/ directory.
    $ cd $ORACLE_HOME/R/library

$ mv ORE ORE.orig
$ mv OREbase OREbase.orig
$ mv OREcommon OREcommon.orig
$ mv OREdm OREdm.orig
$ mv OREdplyr OREdplyr.orig
$ mv OREeda OREeda.orig
$ mv OREembed OREembed.orig
$ mv OREgraphics OREgraphics.orig
$ mv OREmodels OREmodels.orig
$ mv OREpredict OREpredict.orig
$ mv OREserver OREserver.orig
$ mv OREstats OREstats.orig
$ mv ORExml ORExml.orig
  2. Go to the Oracle Machine Learning for R Downloads page, accept the license agreement, and download the R-4.0.5 compatible OML4R Server packages to an installation directory, such as /oml4rserver_install_dir/.

    Note:

    Use the same installation directory for all OML4R components.
  3. Go to the installation directory and unzip the downloaded file.
    $ cd /oml4rserver_install_dir/
$ unzip ore-server-platform-arch-version.zip

    When you unzip the file, the /server directory is created and these files are extracted to it: 

    /server/ORE_version_R_arch-unknown-platform-gnu.tar.gz
/server/OREbase_version_R_arch-unknown-platform-gnu.tar.gz
/server/OREcommon_version_R_arch-unknown-platform-gnu.tar.gz
/server/OREdm_version_R_arch-unknown-platform-gnu.tar.gz
/server/OREdplyr_version_R_arch-unknown-platform-gnu.tar.gz
/server/OREds_version_R_arch-unknown-platform-gnu.tar.gz
/server/OREeda_version_R_arch-unknown-platform-gnu.tar.gz
/server/OREembed_version_R_arch-unknown-platform-gnu.tar.gz
/server/OREgraphics_version_R_arch-unknown-platform-gnu.tar.gz
/server/OREmodels_version_R_arch-unknown-platform-gnu.tar.gz
/server/OREpredict_version_R_arch-unknown-platform-gnu.tar.gz
/server/OREserver_version_R_arch-unknown-platform-gnu.tar.gz
/server/OREstats_version_R_arch-unknown-platform-gnu.tar.gz
/server/ORExml_version_R_arch-unknown-platform-gnu.tar.gz
  4. Go to the /oml4rserver_install_dir/server directory and run the following commands to install OML4R server packages and libraries:
    $ cd /oml4rserver_install_dir/server
$ export R_LIBS_USER=$ORACLE_HOME/R/library
$ R --vanilla CMD INSTALL --library="$R_LIBS_USER" ORE_version_R_arch-unknown-platform-gnu.tar.gz
$ R --vanilla CMD INSTALL --library="$R_LIBS_USER" OREbase_version_R_arch-unknown-platform-gnu.tar.gz
$ R --vanilla CMD INSTALL --library="$R_LIBS_USER" OREcommon_version_R_arch-unknown-platform-gnu.tar.gz
$ R --vanilla CMD INSTALL --library="$R_LIBS_USER" OREdm_version_R_arch-unknown-platform-gnu.tar.gz
$ R --vanilla CMD INSTALL --library="$R_LIBS_USER" OREdplyr_version_R_arch-unknown-platform-gnu.tar.gz
$ R --vanilla CMD INSTALL --library="$R_LIBS_USER" OREds_version_R_arch-unknown-platform-gnu.tar.gz
$ R --vanilla CMD INSTALL --library="$R_LIBS_USER" OREeda_version_R_arch-unknown-platform-gnu.tar.gz
$ R --vanilla CMD INSTALL --library="$R_LIBS_USER" OREembed_version_R_arch-unknown-platform-gnu.tar.gz
$ R --vanilla CMD INSTALL --library="$R_LIBS_USER" OREgraphics_version_R_arch-unknown-platform-gnu.tar.gz
$ R --vanilla CMD INSTALL --library="$R_LIBS_USER" OREmodels_version_R_arch-unknown-platform-gnu.tar.gz
$ R --vanilla CMD INSTALL --library="$R_LIBS_USER" OREpredict_version_R_arch-unknown-platform-gnu.tar.gz
$ R --vanilla CMD INSTALL --library="$R_LIBS_USER" OREstats_version_R_arch-unknown-platform-gnu.tar.gz
$ R --vanilla CMD INSTALL --library="$R_LIBS_USER" OREserver_version_R_arch-unknown-platform-gnu.tar.gz
$ R --vanilla CMD INSTALL --library="$R_LIBS_USER" ORExml_version_R_arch-unknown-platform-gnu.tar.gz
$ cp -f ore.so $ORACLE_HOME/lib/
$ cp -f librqe.so $ORACLE_HOME/lib/
If you are installing OML4R Server for the first time, then run the rqcfg.sql script. If you already have installed OML4R Server and are upgrading your R version, then you do not need to, and should not, run the rqcfg.sql script.

Parent topic: Install Oracle Machine Learning for R Server for Oracle Database 19c or later

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

define permtbl

Specify a permanent tablespace for the RQSYS schema.

define temptbl

Specify a temporary tablespace.

define orahome

Specify the ORACLE_HOME directory.

define rhome

Specify the R_HOME directory.

  1. At your operating system prompt, start SQL*Plus, log in to your PDB directly and run the rqcfg.sql script. To capture the log, spool the installation steps to an external file. The following example uses the PDB PDB1 and gives example values for the script arguments.
    $ sqlplus / as sysdba 
SQL> spool install.txt 
SQL> alter session set container=PDB1; 
...for your system and R version...
SQL> define permtbl = SYSAUX
SQL> define temptbl = TEMP
SQL> define orahome = /u01/app/oracle/product/21.3.0.0/dbhome_1/R/server/rqcfg.sql
SQL> define rhome = /usr/lib64/R
SQL> @/oml4rserver_install_dir/server/rqcfg.sql &permtbl &temptbl &orahome
    &rhome

    Open the install.txt file to see if any errors occurred.

  2. At your operating system prompt, create the ORE script under the ORACLE_HOME/bin directory and make it executable. You need to make sure the environment variables ORACLE_HOME and R_HOME are correctly set before running below command.
    $ cat >$ORACLE_HOME/bin/ORE <<EOF
#!/bin/sh
R_LIBS_USER="$ORACLE_HOME/R/library"
export R_LIBS_USER
$R_HOME/bin/R \$@
EOF
$ chmod +x $ORACLE_HOME/bin/ORE
  3. Download and install the OML4R 2.0 supporting packages for your system as described in Install the OML4R Supporting Packages

Parent topic: Install Oracle Machine Learning for R Server for Oracle Database 19c or later

4.4 Verify the OML4R Server Installation

To verify the success of an OML4R Server installation for Oracle Database using the server.sh script, you can view the log files.

For any installation, you can run some functions to verify a successful installation.

Example 4-1 Run Examples to Verify the Server Installation

First run these commands from an R instance directly on the database server and then run 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 OMLUSER.

ore.connect("OMLUSER", password="OMLUSERpsw", conn_string="", all=TRUE)

Run 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.
## The examples should not return any errors.
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.

Parent topic: Install Oracle Machine Learning for R Server

4.5 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:

Parent topic: Install Oracle Machine Learning for R Server