1. Command Line Interface
  2. Verb Reference
  3. EM CLI Verbs
  4. manage_ra

manage_ra

Used to perform Recovery Appliance administration. There are multiple forms of the command, each using a sub-command to perform different Recovery Appliance management operations. Each form of the command uses a specific set of parameters.

Format

emcli manage_ra -addProtectedDB
    -ra_target_name="<Recovery Appliance target name>"
    -ra_admin_cred ="<Named credential for Recovery Appliance administrator>"
    -ra_vpc_user_cred="<Named credential for Recovery Appliance recovery catalog user> "
    (
      (-target_name="<database or group target name>" -target_type="oracle_database | rac_database | composite")
      | -db_unique_name="<database unique name for a database that is not an Enterprise Manager target>"
      | -input_file="target_list:<full path name of input file>"
    )
    -protection_policy = "<protection policy name>"
    [-reserved_space = "<reserved space for the protected database in G, T, P>"]
    [-grantee_name = "<comma separated list of the Enterprise Manager users>"]
    [-create_ramv_targets]
    [-schedule=
      {
        start_time:yyyy/MM/dd HH:mm;
        tz:{java timezone ID};
        frequency:interval/weekly/monthly/yearly;
        repeat:#m|#h|#d|#w;
        months:#,#,...;
        days:#,#,...;
        end_time:yyyy/MM/dd HH:mm;
    }]

This form of the command is used to enroll one or more databases for protection by one or more Recovery Appliances. A single database can be specified directly on the command line via either an Enterprise Manager target name or a database unique name (for databases not managed by Enterprise Manager). Multiple databases can be specified via an input file or via an Enterprise Manager group target.

Options

A description of all arguments for this command follows. For each parameter, it is noted whether the argument is required (either on the command line or in the input file), what the default is if it's not required, and whether it can be specified for individual targets in an input file (i.e., whether the parameter can be set on a per-database or per-group basis when the command is run against multiple databases and/or groups). Required arguments can be specified either on the command line or on a per-target basis in an input file. When an input file is used, command line argument values globally apply to all targets listed in the input file, while per-target parameter values specified in the input file override the corresponding command line argument values.

The following conventions are used for the attribute values in the argument descriptions:

  • Required: Whether the argument must be specified, either on the command line or on a per-target basis in an input file.
  • Default: For optional arguments, whether there is a default value.
  • Scope:
    • Command Line Only: The argument can be specified only on the command line, not in an input file, and will apply globally to all database targets involved in the command.
    • Both: The argument can be specified on either the command line, in the input file, or both.

  • ra_target_name

    The target name of the Recovery Appliance that the specified databases will be enrolled with.

    Required: Yes

    Scope: Both

  • ra_admin_cred

    The named credential of the Recovery Appliance Administrator for the Recovery Appliance specified by -ra_target_name. If this argument is not specified, preferred credentials will be used.

    Required: Yes

    Default: Preferred credentials for the Recovery Appliance administrator

    Scope: Both

  • ra_vpc_user_cred

    The name of the Recovery Appliance recovery catalog user that will be used for all the databases being enrolled with the Recovery Appliance. This must be a virtual private catalog user, not the Recovery Appliance administrator user.

    Required: Yes

    Scope: Both

  • target_name

    Enterprise Manager target name of a single-instance or cluster database to be enrolled with the Recovery Appliance. Alternatively, a group target can be specified, in which case all the database members of the group will be enrolled.

    Required: Yes, unless -database_unique_name or -input_file are specified. (Either -target_name, -database_unique_name, or -input_file must be specified.)

    Scope: Both

  • target_type

    Target type corresponding to the target specified by -target_name. This can be oracle_database, rac_database or composite.

    Required: Yes if -target_name is specified. Not applicable if -target_name not specified.

    Scope: Both

  • db_unique_name

    Database unique name of the database to be enrolled as a protected database. This argument is used if the database being enrolled has not been discovered as an Enterprise Manager target. If the database is a target, -target_name/-target_type should be used.

    Required: Yes, unless -target_name or -input_file are specified. (Either -target_name, -database_unique_name, or -input_file must be specified.)

    Scope: Both

  • input_file

    A file containing information for multiple databases and/or group targets. This is an alternative to the -target_name and -database_unique_name parameters that can be used when there are multiple databases to be enrolled with one or more Recovery Appliances. The entries in the file mirror the command-line parameters.

    Required: Yes, unless -target_name or -db_unique_name are specified. (Either -target_name, -database_unique_name, or -input_file must be specified.)

    Scope: Command Line Only

    The format is as follows:

    • Either target_name and target_type or db_unique_name entries are required for each database.
    • The following parameters are optional (conditionally if noted, otherwise entirely). They can be specified for some or all of the targets. If an option is not specified for a particular target, values specified on the command line for that option will be used for that target. If an option is present in both the input file and command line, the input file value overrides the command-line value.
      • ra_target_name (optional only if corresponding command line argument is specified)
      • ra_admin_cred
      • ra_vpc_user_cred (optional only if corresponding command line argument is specified)
      • protection_policy (optional only if corresponding command line argument is specified)
      • reserved_space
      • grantee_name
    • Input file format:
      target.0.target_name="<database #1 target name or group target name>"
target.0.target_type="oracle_database|rac_database|composite"
target.0.ra_target_name="<target name of Recovery Appliance with which database #1 is to be enrolled (or multiple databases if target_name is group)>"
target.0.ra_admin_cred="<named credential for administrator for Recovery Appliance specified for database #1>"
target.0.ra_vpc_user_cred="<named credential for Recovery Appliance virtual private catalog user that will be used to backup database #1>"
target.0.reserved_space="<reserved space on Recovery Appliance for database #1>"
target.0.protection_policy="<Recovery Appliance protection policy to be used for database #1>"
target.0.grantee_name="<comma separated list of EM users that will be performing backups for database #1 and will be granted access to the above virtual private catalog credentials>"
target.1.target_name="<database #2 target name or group target name>"
target.1.target_type="oracle_database|rac_database|composite"
target.1.ra_target_name="<target name of Recovery Appliance with which database #2 is to be enrolled (or multiple databases if target_name is group)>"
target.1.ra_admin_cred="<named credential for administrator for Recovery Appliance specified for database #2>"
target.1.ra_vpc_user_cred="<named credential for Recovery Appliance virtual private catalog user that will be used to backup database #2>"
target.1.reserved_space="<reserved space on Recovery Appliance for database #2>"
target.1.protection_policy="<Recovery Appliance protection policy to be used for database #2>"
target.1.grantee_name="<comma separated list of EM users that will be performing backups for database #2 and will be granted access to the above virtual private catalog credentials>"

  • protection_policy

    The name of the Recovery Appliance protection policy to be used for the databases being enrolled.

    Required: Yes

    Scope: Both

  • reserved_space

    Reserved space to be allocated on the Recovery Appliance for the protected databases. This can be specified in gigabytes, terabytes, or petabytes.

    Required: Yes if -database_unique_name is specified, no otherwise.

    Default: For any databases for which a value is not specified (either via the command line or an input file), reserved space will be set according to the following formula: ((2 x <size of database in GB>) + 100) GB.

    Scope: Both

  • grantee_name

    A list of Enterprise Manager database administrator users that need access to the Recovery Appliance virtual private catalog user credentials specified by -ra_vpc_user_cred, in order to configure databases to send backups to the Recovery Appliance. (In addition, access is granted to the Recovery Appliance Monitoring View target associated with the virtual private catalog user, if the target has been created.) After being granted access, these users will be able to select the credentials on the Enterprise Manager Backup Settings page or specify them in the EMCLI configure_db_ha -configureRABackup command.

    Required: No

    Default: None

    Scope: Both

  • create_ramv_targets

    Create Recovery Appliance Monitoring View targets for every unique combination of Recovery Appliance and virtual private catalog user specified on the command line or in the input file.

    Required: No

    Default: Do not create Recovery Appliance Monitoring View targets.

    Scope: Command Line Only

  • schedule

    Schedule the deployment procedure. If this argument is not provided, the procedure will run immediately.

    Required: No

    Default: Schedule procedure for immediate execution.

    Scope: Command Line Only

    Sub-arguments:
    • start_time - Time when the procedure has to start execution.

      Format should be "yyyy/MM/dd HH:mm"

    • tz - The timezone ID ( optional )
    • frequency - Valid values are once/interval/weekly/monthly/yearly. (optional)

      If frequency is set to interval then repeat has to be specified.

      If frequency is set to weekly or monthly, days has to specified.

      If frequency is set to yearly, both days and months have to specified.

    • repeat - Frequency with which the procedure has to be repeated. ( Required only if frequency is set to interval )
    • days - Comma separated list of days. ( Required only if frequency is weekly, monthly, or yearly )

      If frequency is weekly, then valid range is 1 to 7

      If frequency is monthly or yearly, then valid range is 1 to 30

    • months - Comma separated list of months. ( Required only if frequency is yearly )

      Valid range is 1 to 12.

    • end_time - End time for procedure executions. ( optional )

      If it is not specified, procedure will run indefinitely.

      Format should be "yyyy/MM/dd HH:mm"

    • grace_period - Grace period in minutes( optional )

Examples

Example 01: Enroll one single-instance database ("finance_db") that is an Enterprise Manager target with Recovery Appliance target "Montreal ZDLRA", using protection policy "MY_POLICY" and 50 GB of reserved space. 

emcli manage_ra -addProtectedDB
   -ra_target_name="Montreal ZDLRA"
   -ra_admin_cred="NC_RASYS"
   -ra_vpc_user_cred="NC_VPC_USER"
   -target_name="finance_db"
   -target_type="oracle_database"
   -protection_policy="MY_POLICY"
   -reserved_space="50G"

Example 02: Enroll multiple databases that are members of an Enterprise Manager group target with Recovery Appliance target "Montreal ZDLRA", using protection policy "MY_POLICY". In addition, grant access to the virtual private catalog user credentials to EM users EMUSER_ADMIN and EM_CLOUD_ADMIN. (Note that the reserved space values for each database in the group will be determined using the formula described in the -reserved_space description above.) 

emcli manage_ra -addProtectedDB
  -ra_target_name="Montreal ZDLRA"
  -ra_admin_cred="NC_RASYS"
  -ra_vpc_user_cred="NC_VPC_USER"
  -target_name="finance_group"
  -target_type="composite"
  -protection_policy="MY_POLICY"
  -grantee_name="EMUSER_ADMIN,EM_CLOUD_ADMIN"
  -create_ramv_targets

Example 03: Enroll one single-instance database that is not an Enterprise Manager target with Recovery Appliance target "Montreal ZDLRA", using protection policy "MY_POLICY" and 50 GB of reserved space. 

emcli manage_ra -addProtectedDB
   -ra_target_name="Montreal ZDLRA"
   -ra_admin_cred="NC_RASYS"
   -ra_vpc_user_cred="NC_VPC_USER"
   -db_unique_name="FINDB"
   -protection_policy="MY_POLICY"
   -reserved_space="50G"

Example 04: Enroll multiple databases with multiple Recovery Appliances using an input file. 

emcli manage_ra -addProtectedDB
 -input_file="target_list:/tmp/dblist"

/tmp/dblist input file

The input file used in this example illustrates the ability to specify target (via database and group target types) and non-target databases, and how to specify different Recovery Appliances and different parameter values (credentials, protection policy, reserved space, etc.) for different databases. In this example, individual target and non-target databases are to be enrolled with Recovery Appliance "Montreal ZDLRA", with different virtual private catalog users, protection policies, and reserved space amount. An additional set of databases that are members of group "finance_group" are to be enrolled with Recovery Appliance "Boston ZDLRA", with specific virtual private catalog user, protection policy, and reserved space values to be used for all databases in the group.

target.0.ra_target_name="Montreal ZDLRA"
target.0.ra_admin_cred="NC_RASYS"
target.0.ra_vpc_user_cred="VPC_USER1"
target.0.target_name="hr_db"
target.0.target_type="oracle_database"
target.0.reserved_space="500G"
target.0.grantee_name="EMUSER_ADMIN,EM_CLOUD_ADMIN"
target.0.protection_policy="GOLD"
target.1.ra_target_name="Montreal ZDLRA"
target.1.ra_admin_cred="NC_RASYS"
target.1.ra_vpc_user_cred="VPC_USER2"
target.1.db_unique_name="FINDB"
target.1.grantee_name="EMUSER_ADMIN"
target.1.reserved_space="200G"
target.1.protection_policy="SILVER"
target.2.ra_target_name="Boston ZDLRA"
target.2.ra_admin_cred="BC_RASYS"
target.2.ra_vpc_user_cred="BC_VPC_USER"
target.2.target_name="finance_group"
target.2.target_type="composite"
target.2.reserved_space="100G"
target.2.grantee_name="EMUSER_ADMIN,EM_CLOUD_ADMIN"
target.2.protection_policy="BRONZE"

Example 05: Enroll multiple databases with multiple Recovery Appliances using an input file that contains multiple group targets. Schedule the procedure to execute on a daily recurring schedule. By default, since all the targets in the input file are group targets, only databases that have joined the groups since the last procedure execution are processed. 

emcli manage_ra -addProtectedDB
  -input_file="target_list:/tmp/dblist"
  -schedule="start_time:2020/2/10 01:00;tz:PST;frequency:interval;repeat:1d"

/tmp/dblist input file

The input file used in this example specifies three groups, two associated with one Recovery Appliance and one associated with a different Recovery Appliance. Each group is also associated with a specific set of parameter values. (Note that a single reserved space value is specified for group "Montreal Group Gold", meaning all databases in that group will be enrolled with that amount of reserved space. No reserved space value is specified for the other groups, meaning reserved space for each database in those groups will be determined using the formula above.) On each recurring execution, the procedure will dynamically distill the list of database members of each group and process that list, automatically picking up any new group members.

target.0.ra_target_name="Montreal ZDLRA"
target.0.ra_admin_cred="NC_RASYS"
target.0.ra_vpc_user_cred="NC_VPC_USER1"
target.0.target_name="Montreal Group Gold"
target.0.target_type="composite"
target.0.reserved_space="500G"
target.0.grantee_name="EMUSER_ADMIN,EM_CLOUD_ADMIN"
target.0.protection_policy="GOLD"
target.1.ra_target_name="Montreal ZDLRA"
target.1.ra_admin_cred="NC_RASYS"
target.1.ra_vpc_user_cred="NC_VPC_USER2"
target.1.target_name="Montreal Group Silver"
target.1.target_type="composite"
target.1.grantee_name="EMUSER_ADMIN"
target.1.protection_policy="SILVER"
target.2.ra_target_name="Boston ZDLRA"
target.2.ra_admin_cred="BC_RASYS"
target.2.ra_vpc_user_cred="BC_VPC_USER2"
target.2.target_name="Boston Group"
target.2.target_type="composite"
target.2.grantee_name="EMUSER_ADMIN"
target.2.protection_policy="GOLD"

Example 06: Enroll multiple databases with one Recovery Appliance using an input file. Provide command line values for Recovery Appliance, administrator credentials, virtual private catalog user, and protection policy that apply globally to all databases and groups listed in the input file. Provide per-database values in the input file for reserved space. 

emcli manage_ra -addProtectedDB
  -input_file="target_list:/tmp/dblist"
  -ra_target_name="Montreal ZDLRA"
  -ra_admin_cred="NC_RASYS"
  -ra_vpc_user_cred="NC_VPC_USER"
  -protection_policy="GOLD"

The input file used in this example is as follows. Note the "SILVER" protection policy specified for database "finance_db" overrides the "GOLD" command line value.

/tmp/dblist input file

target.0.target_name="finance_db"
target.0.target_type="oracle_database"
target.0.protection_policy="SILVER"
target.0.reserved_space="500G"
target.0.grantee_name="EMUSER_ADMIN,EM_CLOUD_ADMIN"
target.1.target_name="hr_db"
target.1.target_type="rac_database"
target.1.reserved_space="600G"
target.1.grantee_name="EMUSER_ADMIN"
target.2.target_name="test_group"
target.2.target_type="composite"
target.2.reserved_space="400G"
target.2.grantee_name="EMUSER_ADMIN,EM_CLOUD_ADMIN"