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:

  • 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.

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.

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.

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.

4.2.1 System Requirements

Lists the system requirements for OML4R Server.

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

$ORACLE_SID must specify the service identifier (SID) of the database that will support OML4R.

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

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

$LD_LIBRARY_PATH must include $ORACLE_HOME/lib.

$PATH must include $ORACLE_HOME/bin.

Oracle Solaris

$LD_LIBRARY_PATH must include $ORACLE_HOME/lib.

$PATH must include $ORACLE_HOME/bin.

IBM AIX

$LIBPATH must include $ORACLE_HOME/lib.

$PATH must include $ORACLE_HOME/bin.

Microsoft Windows

%PATH% must include %R_HOME%\bin\x64. The default value of %R_HOME% is C:\Program Files\R\R-3.6.1.

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.

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

  • Member of the dba group

  • Has write access to $ORACLE_HOME/lib

Microsoft Windows

  • Administrator access

  • Member of the ora_dba group

  • Has write access to %ORACLE_HOME%\bin

See the following topics for additional information:

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:

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:

  1. Open Windows Control Panel.
  2. Select Users Accounts.
  3. Select Manage User Accounts.
  4. 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.

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.

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.

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/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 execute the following commands:
    $ cd /oml4rserver_install_dir/server
    
    $ ORE CMD INSTALL ORE_version_R_arch-unknown-platform-gnu.tar.gz
    $ ORE CMD INSTALL OREbase_version_R_arch-unknown-platform-gnu.tar.gz
    $ ORE CMD INSTALL OREcommon_version_R_arch-unknown-platform-gnu.tar.gz
    $ ORE CMD INSTALL OREdm_version_R_arch-unknown-platform-gnu.tar.gz
    $ ORE CMD INSTALL OREdplyr_version_R_arch-unknown-platform-gnu.tar.gz
    $ ORE CMD INSTALL OREeda_version_R_arch-unknown-platform-gnu.tar.gz
    $ ORE CMD INSTALL OREembed_version_R_arch-unknown-platform-gnu.tar.gz
    $ ORE CMD INSTALL OREgraphics_version_R_arch-unknown-platform-gnu.tar.gz
    $ ORE CMD INSTALL OREmodels_version_R_arch-unknown-platform-gnu.tar.gz
    $ ORE CMD INSTALL OREpredict_version_R_arch-unknown-platform-gnu.tar.gz
    $ ORE CMD INSTALL OREstats_version_R_arch-unknown-platform-gnu.tar.gz
    $ ORE CMD INSTALL OREserver_version_R_arch-unknown-platform-gnu.tar.gz
    $ ORE CMD INSTALL ORExml_version_R_arch-unknown-platform-gnu.tar.gz
If you are installing OML4R Server for the first time, then run the 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

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

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:

  1. Ensure that your system satisfies the requirements specified in Oracle Machine Learning for R Server Requirements.

  2. Create an installation directory for the OML4R Server components. The directory can have any name. For example:

    /oml4r_server_install_dir
    
  3. Download the OML4R Server installation files and supporting packages from the Oracle Machine Learning for R Downloads page on the Oracle Technology Network.

    1. Accept the license agreement and download the OML4R Server files for your platform to your installation directory.

    2. 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
    
  4. 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
    
  5. For Linux or UNIX, run server.sh. For Windows, run server.bat. The script performs a default, first-time installation of OML4R Server, as described in A Default Interactive Installation. For details about the server 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.

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:

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:

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

-i, --install

Install or upgrade OML4R Server.

An installation or upgrade includes the following by default:

  • Installation of the supporting packages if they are present.

  • Creation or configuration of a database user if one does not exist.

-u, --uninstall

Uninstall OML4R Server:

  • When used with --keep (the default), the script removes the RQSYS metadata and PL/SQL packages from the database but retains the libraries and R packages under Oracle home (partial uninstall).

  • When used with --full, the script removes the libraries and R packages under Oracle home in addition to the RQSYS metadata and PL/SQL packages in the database. (full uninstall).

See Uninstall Oracle Machine Learning for R.

-y

Never prompt.

--ask

Interactive mode (the default).

--keep

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.

See Performing a Partial Uninstall.

--full

When uninstalling OML4R Server, remove the R packages and libraries under Oracle home in addition to the database objects.

See Performing a Full Uninstall.

--no-supp

When combined with --install, prevents installation of the supporting packages. By default the supporting packages are installed if they are available.

--supp

Install supporting packages (the default).

--no-db

no-db do not configure the database; only install the ORE module and libraries associated with Embedded R Execution

--pdb NAME

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.

--perm PERM

Permanent tablespace for RQSYS.

--temp TEMP

Temporary tablespace for RQSYS.

4.4.1.3 Server Script Examples

Example of using the server script.

See the following topics for examples of using the server script:

See Also:

Example A-1 for an example with output

4.4.1.3.1 A Default Interactive Installation

Example of a default installation of OML4R Server.

If your Linux or UNIX system meets the requirements specified in System Requirements, this command performs a default, first-time 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.

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

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 any installation, you can execute some functions to verify a successful installation.

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.

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: