9 Configuring XStream In

Configure an XStream Administrator

An XStream administrator configures and manages XStream components in an XStream In environment. This section describes configuring an XStream administrator by granting a user the appropriate privileges. You must configure an XStream administrator in each Oracle database included in the XStream configuration.

If you are configuring XStream In in a multitenant container database (CDB), then configure the XStream administrator in the container that will run the inbound server. This container can be the root or a pluggable database (PDB). See "XStream In and a Multitenant Environment" for information about using XStream In in a CDB.

Prerequisites

Before configuring an XStream administrator, ensure that the following prerequisites are met:

• Ensure that you can log in to each database in the XStream configuration as an administrative user who can create users, grant privileges, and create tablespaces.

• Decide between the trusted user model and untrusted user model for security. See XStream Security Models for more information.

• Identify a user who will be the XStream administrator. Either create a new user with the appropriate privileges or grant these privileges to an existing user.

  Do not use the SYS or SYSTEM user as an XStream administrator, and ensure that the XStream administrator does not use the SYSTEM tablespace as its default tablespace.

• If a new tablespace is required for the XStream administrator, then ensure that there is enough disk space on each computer system in the XStream configuration for the tablespace. The recommended size of the tablespace is 25 MB.

Assumptions

This section makes the following assumptions:

• The username of the XStream administrator is xstrmadmin for a non-CDB. In a CDB, when the XStream administrator is a common user, the username of the XStream administrator is c##xstrmadmin. When the XStream administrator in a CDB is a local user in a PDB, the username of the XStream administrator is xstrmadmin.

• The tablespace used by the XStream administrator is xstream_tbs.

To configure an XStream administrator: 

1. In SQL*Plus, connect as an administrative user who can create users, grant privileges, and create tablespaces. Remain connected as this administrative user for all subsequent steps.

   See Also:

   Oracle Database Administrator's Guide for information about connecting to a database in SQL*Plus

2. Either create a tablespace for the XStream administrator or use an existing tablespace.

   This tablespace stores any objects created in the XStream administrator's schema.

   For example, the following statement creates a new tablespace for the XStream administrator:

   CREATE TABLESPACE xstream_tbs DATAFILE '/usr/oracle/dbs/xstream_tbs.dbf' 
     SIZE 25M REUSE AUTOEXTEND ON MAXSIZE UNLIMITED;
   

   If you are creating an XStream administrator as a common user in a CDB, then you must create the tablespace in the root and in all PDBs. The tablespace is required in all PDBs because a common user must have access to the tablespace in any PDB.

3. Create a new user to act as the XStream administrator or identify an existing user.

   For example, to create a user named xstrmadmin and specify that this user uses the xstream_tbs tablespace, run the following statement:

   CREATE USER xstrmadmin IDENTIFIED BY password 
     DEFAULT TABLESPACE xstream_tbs
     QUOTA UNLIMITED ON xstream_tbs;
   

   If you are creating an XStream administrator in a CDB and the inbound server is in the root, then the XStream administrator must be a common user.

   If you are creating an XStream administrator in a CDB and the inbound server is in a PDB, then the XStream administrator can be a common user or a local user. Oracle recommends configuring a common user as the XStream administrator even when the inbound server is in a PDB.

   To create a common user, include the CONTAINER=ALL clause in the CREATE USER statement when the current container is the root:

   CREATE USER c##xstrmadmin IDENTIFIED BY password 
     DEFAULT TABLESPACE xstream_tbs
     QUOTA UNLIMITED ON xstream_tbs
     CONTAINER=ALL;
   

   Note:

   Enter an appropriate password for the administrative user.

   See Also:

   Oracle Database Security Guide for guidelines about choosing passwords

4. Grant CREATE SESSION privilege to the XStream administrator.

   If you created a new user to act as the XStream administrator, then grant this user CREATE SESSION privilege.

   For example, to grant CREATE SESSION privilege to user xstrmadmin, run the following statement:

   GRANT CREATE SESSION TO xstrmadmin;
   

   If you are creating an XStream administrator as a common user in a CDB, then grant CREATE SESSION privilege and SET CONTAINER privilege to the XStream administrator, and include the CONTAINER=ALL clause in the statement.

   For example, to grant these privileges to user xstrmadmin in a CDB, run the following statement:

   GRANT CREATE SESSION, SET CONTAINER TO c##xstrmadmin CONTAINER=ALL;
   

5. Run the GRANT_ADMIN_PRIVILEGE procedure in the DBMS_XSTREAM_AUTH package.

   A user must have explicit EXECUTE privilege on a package to execute a subprogram in the package inside of a user-created subprogram, and a user must have explicit READ or SELECT privilege on a data dictionary view to query the view inside of a user-created subprogram. These privileges cannot be granted through a role. You can run the GRANT_ADMIN_PRIVILEGE procedure to grant such privileges to the XStream administrator, or you can grant them directly.

   Depending on the parameter settings for the GRANT_ADMIN_PRIVILEGE procedure, it can grant the appropriate privileges for a trusted or untrusted XStream administrator, and it can grant privileges in a non-CDB or a CDB. Table 9-1 describes key parameter settings for each case.

   Table 9-1 Key Parameter Settings for GRANT_ADMIN_PRIVILEGE

   Type of XStream Administrator	grant_select_privileges Parameter Setting	container Parameter Setting
   Trusted in a non-CDB	TRUE	CURRENT (default)
   Untrusted in a non-CDB	FALSE (default)	CURRENT (default)
   Trusted in a CDB	TRUE	ALL
   Untrusted in a CDB	FALSE (default)	ALL

   
   

   Example 9-1 Granting Privileges to a Trusted XStream Administrator in a Non-CDB Without Generating a Script

   BEGIN
      DBMS_XSTREAM_AUTH.GRANT_ADMIN_PRIVILEGE(
         grantee                 => 'xstrmadmin',
         privilege_type          => 'APPLY',
         grant_select_privileges => TRUE);
   END;
   /
   

   Example 9-2 Granting Privileges to a Trusted XStream Administrator in a Non-CDB and Generating a Script

   The directory specified in the directory_name parameter must exist and must be accessible to the current user.

   BEGIN
      DBMS_XSTREAM_AUTH.GRANT_ADMIN_PRIVILEGE(
         grantee                 => 'xstrmadmin',
         privilege_type          => 'APPLY',
         grant_select_privileges => TRUE,
         do_grants               => TRUE,
         file_name               => 'grant_xstrm_privs.sql',
         directory_name          => 'xstrm_dir');
   END;
   /
   

   Example 9-3 Granting Privileges to an Untrusted XStream Administrator in a Non-CDB Without Generating a Script

   BEGIN
      DBMS_XSTREAM_AUTH.GRANT_ADMIN_PRIVILEGE(
         grantee                 => 'xstrmadmin',
         privilege_type          => 'APPLY',
         grant_select_privileges => FALSE);
   END;
   /
   

   Example 9-4 Granting Privileges to a Trusted XStream Administrator in a CDB Without Generating a Script

   In this example, the XStream administrator is a common user.

   BEGIN
      DBMS_XSTREAM_AUTH.GRANT_ADMIN_PRIVILEGE(
         grantee                 => 'c##xstrmadmin',
         privilege_type          => 'APPLY',
         grant_select_privileges => TRUE,
         container               => 'ALL');
   END;
   /
   

   Note:

   For any scenario, when the XStream administrator must manage both an XStream Out and an XStream In configuration on the database, specify * for the privilege_type parameter.

   See Also:

   Oracle Database PL/SQL Packages and Types Reference

6. If necessary, grant additional privileges to the XStream administrator.

   See "Granting Additional Privileges to the XStream Administrator".

7. Repeat all of the previous steps at each Oracle database in the environment that will use XStream.

Set the Relevant Initialization Parameters

Some initialization parameters are important for the configuration, operation, reliability, and performance of XStream inbound servers. Set these parameters appropriately.

The following requirements apply to XStream inbound servers:

• Ensure that the PROCESSES initialization parameter is set to a value large enough to accommodate the inbound server background processes and all of the other Oracle Database background processes.

• Ensure that the SESSIONS initialization parameter is set to a value large enough to accommodate the sessions used by the inbound server background processes and all of the other Oracle Database sessions.

Configure the Streams pool

The Streams pool is a portion of memory in the System Global Area (SGA) that is used by both Oracle Streams and XStream components. The Streams pool stores buffered queue LCRs in memory, and it provides memory for inbound servers.

The following are considerations for configuring the Streams pool:

• At least 300 MB of memory is required for the Streams pool.

• The best practice is to set the STREAMS_POOL_SIZE initialization parameter explicitly to the desired Streams pool size.

• After XStream In is configured, you can use the max_sga_size apply parameter to control the amount of SGA memory allocated specifically to an inbound server.

• Ensure that there is enough space in the Streams pool at each database to run XStream components and to store LCRs and run the components properly.

• The Streams pool is initialized the first time an inbound server is started.

The Streams pool size is the value specified by the STREAMS_POOL_SIZE parameter, in bytes, if the following conditions are met:

• The MEMORY_TARGET, MEMORY_MAX_TARGET, and SGA_TARGET initialization parameters are all set to 0 (zero).

• The STREAMS_POOL_SIZE initialization parameter is set to a nonzero value.

The Automatic Shared Memory Management feature automatically manages the size of the Streams pool when the following conditions are met:

• The MEMORY_TARGET and MEMORY_MAX_TARGET initialization parameters are both set to 0 (zero).

• The SGA_TARGET initialization parameter is set to a nonzero value.

If you are using Automatic Shared Memory Management and the STREAMS_POOL_SIZE initialization parameter also is set to a nonzero value, then Automatic Shared Memory Management uses this value as a minimum for the Oracle Streams pool. You can set a minimum size if your environment needs a minimum amount of memory in the Oracle Streams pool to function properly. The current memory allocated to Oracle Streams pool by Automatic Shared Memory Management can be viewed by querying the V$SGA_DYNAMIC_COMPONENTS view.

If Required, Specify Supplemental Logging at the Source Database

In an XStream configuration in which an inbound server applies changes captured by a capture process in an XStream Out configuration, supplemental logging might be required at the source database on columns in the tables for which an inbound server applies changes. The required supplemental logging depends on the configuration of the inbound server you create.