workingcopy Commands

Use commands with the workingcopy keyword to create, update, extend, and delete working copies.

rhpctl add workingcopy

Creates a working copy on a client cluster.

Syntax

To add a working copy to a client cluster:

rhpctl add workingcopy -workingcopy workingcopy_name
  {-image image_name | -series series_name}
  [-oraclebase oraclebase_path] [-path where_path]
  [-localmount [-location zipped_home_path]] [-storagetype {LOCAL | RHP_MANAGED}]
  [-user user_name] [-gimr | -dbname unique_db_name 
           [-dbtype {RACONENODE | RAC | SINGLE}] [-datafileDestination datafileDestination_path] 
           [-dbtemplate { file_path | image_name:relative_file_path}] 
           {-node node_list |
              -serverpool pool_name [-pqpool pool_name |
              -newpqpool pool_name -pqcardinality cardinality] |
              -newpool pool_name -cardinality cardinality [-pqpool pool_name |
              -newpqpool pool_name -pqcardinality cardinality]} 
             [-cdb] [-pdbName pdb_prefix [-numberOfPDBs pdb_count]]] 
  [-client cluster_name] [-clusternamealias cluster_name_alias] [-ignoreprereq | -fixup]
  [-responsefile response_file_path] [-clusternodes node_list]
  [-groups group_list]
  [-root | -cred cred_name | -sudouser sudo_username
    -sudopath path_to_sudo_binary | -auth plugin_name [-arg1 name1:value1
    [-arg2 name2:value2 ...]]]
  [-notify [-cc users_list]]
  [-asmclientdata data_path]
  [-gnsclientdata data_path] [-clustermanifest data_path] [-softwareonly]
  [-local] [-inventory inventory_path] [-targetnode target_node_name]
  [-agpath read_write_path -aupath gold_image_path] [-setupssh]
  [-useractiondata user_action_data] [-eval] [-schedule {timer_value | NOW}]
  [-checkwcpatches -sourcehome source_home_path] [-scan scan_name]
  [-diskDiscoveryString disk_discovery_string] [-readonly]
  

Parameters

Table A-65 rhpctl add workingcopy Command Parameters

Parameter Description
-workingcopy workingcopy_name

Specify a name for the working copy that you want to create.

{-image image_name | -series series_name}

Specify the name of a configured image from which to create a working copy or the name of an image series from which RHPCTL takes the latest image when adding a working copy.

-oraclebase oracle_base_path

Specify an ORACLE_BASE path for provisioning an Oracle Database or Oracle Grid Infrastructure home. You can specify either an existing directory or a new directory.

Note: This parameter is required only for the ORACLEDBSOFTWARE and ORACLEGISOFTWARE image types.

-inventory inventory_path

Specify the location of the Oracle Inventory directory.

-path absolute_path

Specify the absolute path for provisioning the software home on the client side (this location must be empty). For Oracle Database images, this becomes the ORACLE_HOME.

Note: This parameter is required for LOCAL storage types, and is invalid for RHP_MANAGED.

-localmount

Specify this option to provision the working copy using the locally mounted compressed image file.

-location zipped_home_path

Specify the location of the compressed image file on the target.

-storagetype {LOCAL | RHP_MANAGED}

Specify the type of storage for the software home.

-user user_name

Specify the name of the user that will own the working copy being provisioned.

If you do not specify this parameter, then the working copy is owned by the user running the command. If you are provisioning to a remote cluster, then the user name must be a valid user on the remote cluster. The user ID need not be the same between the two clusters, but the user name must exist on both.

Note: You cannot use -user simultaneously with the -softwareonly parameter.

-gimr

Perform the operations required for a Grid Infrastructure Management Repository (GIMR) database

-dbname unique_db_name

Specify the unique name of the database (DB_UNIQUE_NAME without DB_DOMAIN) that you are adding.

-dbtype {RACONENODE | RAC | SINGLE}

Specify whether the database is Oracle RAC One Node, Oracle RAC, or a nonclustered database.

-datafileDestination datafileDestination_path

Specify the data file destination location or the name of the Oracle Automatic Storage Management (Oracle ASM) disk group.

Note: You cannot specify a disk group for Oracle Database versions before Oracle Database 11g release 2 (11.2).

-dbtemplate file_path | image_name:relative_file_path

Specify the absolute file path to a database template or the relative path to the image home directory on a Fleet Patching and Provisioning Server.

-node node_list

Specify a node or comma-delimited list of several nodes.

Enter a node name for a single-instance Oracle home.

-serverpool server_pool_name

Specify the name of an existing server pool.

-newpqpool server_pool_name

Optionally, you can create a new server pool to be used for parallel queries. Specify a name for the new server pool.

Note: This parameter is only applicable in an Oracle Flex Cluster environment because it refers to server pools running on non-Hub Nodes.

-newpool server_pool_name

Optionally, you can create a new server pool. Specify a name for the new server pool.

-pqcardinality cardinality

If you create a new server pool, then you must specify a cardinality value for the server pool.

Note: This parameter is only applicable in an Oracle Flex Cluster environment.

-cardinality cardinality

If you create a new server pool, then you must specify a cardinality value for the server pool.

-cdb

Optionally, use this parameter to create a database as a container database.

-pdbName pdb_prefix

If you are creating one or more pluggable databases, then specify a pluggable database name prefix.

-numberOfPDBs pdb_count

Specify the number of pluggable databases you want to create.

-client cluster_name

Specify the name of the client cluster.

Note:

Oracle recommends that you specify a unique name for the client cluster.
-clusternamealias

Optionally, you can specify the client cluster alias if the client cluster name is not unique.

-ignoreprereq | -fixup

You can choose to ignore the Clusterware Verification Utility (CVU) checks or you can choose to run the recommended fixup script.

Note: These parameters are valid only when you are provisioning Oracle Grid Infrastructure.

-responsefile response_file_path

Specify a response file to use when you provision Oracle Grid Infrastructure.

-clusternodes node_name:node_vip[:node_role][,node_name:node_vip[:node_role]...]

Specify a comma-delimited list of cluster node information on which to provision Oracle Clusterware.

-groups "OSDBA|OSOPER|OSASM|OSBACKUP|OSDG|OSKM|OSRAC=group_name[,...]"

Specify a comma-delimited list of Oracle groups, enclosed in double quotation marks (""), that you want to configure in the working copy.

For example:

-groups "OSDBA=dba,OSOPER=oper"

When you create a gold image from a source home or working copy, the gold image inherits the groups configured in the source. When you create a working copy from that gold image using rhpctl add workingcopy, by default, the new working copy inherits the same groups as the gold image.

If you use the -groups parameter on the command line, then:

  • Groups configured in the gold image that you do not specify on the command line are inherited by the working copy.

  • Groups configured in the gold image that you also specify on the command line are set to the value that you specify on the command line (command line parameters override the gold image).

  • Groups that you specify on the command line that are not in the gold image are added to the configured groups in the gold image (the command line adds new groups).

Notes:
  • When you move or upgrade a source home (unmanaged or working copy), the groups in the destination working copy must match those of the source home.

  • You cannot use -groups simultaneously with the -softwareonly parameter.

-root | -cred cred_name | -sudouser sudo_user_name -sudopath sudo_binary_location | -auth plugin_name plugin_args

If you choose to use the -targetnode parameter, then you must choose either root, a credential name, sudo, or an authentication plugin to access the remote node.

Choose -root to perform super user operations as root. Alternatively, you can choose either to specify a credential name to associate the user name and password credentials to access a remote node, to perform super user operations as a sudo user by specifying a sudo user name and the path to the sudo binary, or to use an authentication plugin to access the remote node.

-notify [-cc user_list]

Specify this parameter to have email notifications sent to the owner of the working copy. Optionally, you can include a list of additional users who will receive notifications.

-asmclientdata data_path

Specify the path to a file that contains Oracle ASM client data.

-gnsclientdata data_path

Specify the path to a file that contains the Grid Naming Service (GNS) data.

-clustermanifest data_path

Optionally, you can specify the location of cluster manifest file. You can use this parameter when the Fleet Patching and Provisioning Server is on a domain services cluster and you are creating a member cluster.

-local

Use this parameter to provision only Oracle Grid Infrastructure software on the local node.

Note: You can only use this parameter in conjunction with the -softwareonly parameter, and only when running the rhpctl add workingcopy command on a Fleet Patching and Provisioning Server.

-softwareonly

Use this parameter to provision only Oracle Grid Infrastructure software.

-targetnode target_node_name

Specify the name of a node in a remote cluster with no Fleet Patching and Provisioning Client on which you want to provision a working copy.

-agpath read_write_path -aupath gold_image_path

Use –agpath to specify the path to the read-write, site-specific configuration changes to set the persistent home path, and use –aupath to specify the path for the read-only gold image to set the persistent home path.

-setupssh

Use this parameter to set up passwordless SSH user equivalence on the remote nodes for the provisioning user.

-useractiondata user_action_data

Optionally, you can pass a value to the useractiondata parameter of the user action script.

–eval

Optionally, you can use this parameter to evaluate the impact of this command on the system without actually running the command.

-schedule {timer_value | NOW}
Optionally, you can use this parameter to schedule a time to run this operation, in ISO-8601 format, as in the following example:
2018-07-25T19:13:17+05

If NOW is specified, then the job is scheduled immediately.

-checkwcpatches -sourcehome source_home_path

Optionally, you can use the -checkwcpatches and -sourcehome parameters to compare patches in a specific source home path with the patches in the working copy you want to add.

-scan scan_name

Optionally, you can use this parameter to specify a SCAN name.

-diskDiscoveryString disk_discovery_string

Optionally, you can use this parameter to specify a disk discovery string.

-readonly

Optionally, you can use this parameter to add the database working copy as a read-only home.

Usage Notes

Note:

Member Clusters, which are part of the Oracle Cluster Domain architecture, are desupported in Oracle Grid Infrastructure 21c.

Note:

Domain Services Cluster (DSC), which is part of the Oracle Cluster Domain architecture, is deprecated in Oracle Grid Infrastructure 21c and can be desupported in a future release.

  • You can obtain context sensitive help for specific use cases for the rhpctl add workingcopy command, as follows:

    $ rhpctl add workingcopy -help [REMOTEPROVISIONING | STORAGETYPE | ADMINDB
      | GRIDHOMEPROV | SWONLYGRIDHOMEPROV  | STANDALONEPROVISIONING | GGHOMEPROVISIONING]
  • If you choose to use the -schedule parameter, then you must run this command on the Fleet Patching and Provisioning Server.

Examples

  • To create a working copy on a client cluster for yourself or another user:

    rhpctl add workingcopy -workingcopy workingcopy_name {-image image_name |
       -series series_name} -oraclebase oracle_base_path -client cluster_name 
      [-user user_name]
  • To create a working copy on storage that you specify:

    rhpctl add workingcopy -workingcopy workingcopy_name {-image image_name |
       -series series_name} -oraclebase oracle_base_path -storagetype 
      {LOCAL | RHP_MANAGED} [-path absolute_path]
  • To create and configure a working copy of Oracle Grid Infrastructure:

    rhpctl add workingcopy -workingcopy workingcopy_name {-image image_name |
       -series series_name} {-root | -cred cred_name | -sudouser sudo_user_name
       -sudopath sudo_binary_path} -responsefile response_file_path
       [-clusternodes node_information] [-user user_name] [-oraclebase oracle_base_path]
       [-path absolute_path] [-asmclientdata data_path] [-gnsclientdata data_path]
       [-ignoreprereq | -fixup]
  • To provision a software-only working copy of Oracle Grid Infrastructure:

    rhpctl add workingcopy -workingcopy workingcopy_name {-image image_name |
       -series series_name} -softwareonly -path Grid_home_path -oraclebase
       oracle_base_path [-local | -client cluster_name
       [-groups "Oracle_group=user_group[,...]"] [-node client_node_name] |
       {-root | -cred cred_name | -sudouser sudo_user_name -sudopath sudo_binary_path}
        -targetnode node_name]
  • To provision a working copy on a node or a cluster where Oracle Fleet Patching and Provisioning does not exist:

    rhpctl add workingcopy -workingcopy workingcopy_name {-image image_name |
       -series series_name} -oraclebase oracle_base_path -user user_name
        -node node_name [-path absolute_path] 
        {-root | -cred cred_name | -sudouser sudo_user_name -sudopath sudo_binary_path}

Note:

If you are provisioning Oracle database software to a Fleet Patching and Provisioning Client that has been configured with an Oracle ASM disk group, then do not specify the -path parameter, so as to enable the Fleet Patching and Provisioning Client to use storage provided by Fleet Patching and Provisioning.

If the Fleet Patching and Provisioning Client is not configured with an Oracle ASM disk group, then specify the -storagetype parameter with LOCAL, in addition to specifying the -path parameter.

rhpctl addnode workingcopy

Extends an Oracle RAC database to another node or nodes in a cluster.

Syntax

rhpctl addnode workingcopy -workingcopy workingcopy_name -node node_list
  [-targetnode node_name {-root | -sudouser sudo_username -sudopath sudo_binary_path
   | -cred cred_name | -auth plugin_name [-arg1 name1:value1...]} -setupssh]
  [-ignoreprereq] [-useractiondata user_action_data] [-eval] [-schedule {timer_value | NOW}]

Parameters

Table A-66 rhpctl addnode workingcopy Command Parameters

Parameter Description
-workingcopy workingcopy_name

Specify the name of a working copy that contains the Oracle database you want to extend.

-node node_list

Specify a node or a comma-delimited list of nodes to which you want to extend the database.

-targetnode node_name

Optionally, you can specify a node on which to run this command.

-root | -sudouser sudo_username -sudopath sudo_binary_path | -cred cred_name | -auth plugin_name [-arg1 name1:value1...]

If you choose to use the -targetnode parameter, then you must choose either sudo or root to access the remote nodes.

If you choose sudo, then you must specify a user name to run super-user operations, and a path to the location of the sudo binary.

Optionally, you can choose to specify a credential name to associate the user and password credentials to access a remote node.

Alternative to –sudouser, –root, or –cred, you can use –auth to specify an authentication plugin to access a remote node.

-ignoreprereq

Use this parameter to ignore the CVU prerequisite checks.

-setupssh

Sets up passwordless SSH user equivalence on the remote nodes for the provisioning user.

-useractiondata user_action_data

Optionally, you can pass a value to the useractiondata parameter of the user action script.

–eval

Optionally, you can use this parameter to evaluate the impact of this command on the system without actually running the command.

-schedule {timer_value | NOW}

Optionally, you can schedule a time to run this command in ISO-8601 format. For example: 2018-01-21T19:13:17+05.

If NOW is specified, then the job is scheduled immediately.

Usage Notes

  • If you are extending a policy-managed database, then the database automatically starts on the new nodes.

  • If you are extending an administrator-managed database, then you must also run the rhpctl addnode database command to start the instance.

  • If the target cluster is an Oracle Clusterware 11g release 2 (11.2) or 12c release 1 (12.1) cluster, then you must provide either root credentials or provide a sudo user. You must also specify a target node that must be the node name of one of the cluster nodes.

rhpctl delete workingcopy

Deletes an existing working copy.

Syntax

rhpctl delete workingcopy -workingcopy workingcopy_name [-notify [-cc user_list]] [-force]
  [[-targetnode node_name] {-root | -sudouser sudo_user_name -sudopath
   sudo_binary_path -cred cred_name | -auth plugin_name [-arg1 name1:value1...]}
  [-useractiondata user_action_data] [-schedule {timer_value | NOW}]

Parameters

Table A-67 rhpctl delete workingcopy Command Parameters

Parameter Description
-workingcopy workingcopy_name

Specify the name of a working copy that you want to delete.

-notify [-cc user_list]

Name of a node in a remote cluster with no Fleet Patching and Provisioning Client.

-targetnode node_name

Optionally, you can specify a particular node from which you want to delete a working copy.

-force

Use this parameter to forcibly delete the database working copy.

-root | -sudouser sudo_username -sudopath sudo_binary_path | -cred cred_name

If you choose to use the -targetnode parameter, then you must choose either sudo or root to access the remote node.

If you choose sudo, then you must specify a user name to run super-user operations, and a path to the location of the sudo binary.

Optionally, you can choose to specify a credential name to associate the user and password credentials to access a remote node.

Alternative to –sudouser, –root, or –cred, you can use –auth to specify an authentication plugin to access a remote node.

-useractiondata user_action_data

Optionally, you can pass a value to the useractiondata parameter of the user action script.

-schedule {timer_value | NOW}
Optionally, you can use this parameter to schedule a time to run this operation, in ISO-8601 format, as in the following example:
2018-07-25T19:13:17+05

If NOW is specified, then the job is scheduled immediately.

Usage Notes

  • This command will not delete the working copy if there are any databases configured on it. Use the -force option to override this.

  • This command will not not delete the working copy if there are any running databases on it. The -force option will not override this.

  • This command does not delete the Oracle base that was created when you ran rhpctl add workingcopy.

  • If you choose to use the -schedule parameter, then you must run this command on the Fleet Patching and Provisioning Server.

Examples

To delete a working copy:

$ rhpctl delete workingcopy -workingcopy wc1

rhpctl query workingcopy

Displays the configuration information of an existing working copy.

Syntax

rhpctl query workingcopy [-workingcopy workingcopy_name  [-metadataonly] | [-image image_name [-drift]] [-client cluster_name]]
  [-rhpserver rhps_regex]

Parameters

Table A-68 rhpctl query workingcopy Command Parameters

Parameter Description
-workingcopy workingcopy_name

Specify the name of a working copy for which you want to display the configuration information.

-metadataonly

Use this paramter only when you use the -workingcopyy parameter to query only the metadata of the working copy, which is located in the repository and not run OPatch or connect to the target to query for extra information.

-image image_name [-drift]

Use this paramter to specify the name of a configured image that you want to query. If you specify an image name, then RHPCTL lists all the working copies based on that image.

The -drift optipn lists the bug fixes not included in the golden image.

-client cluster_name

Optionally, you can specify a client cluster on which to query working copies.

-rhpserver rhps_regex

Specify a regular expression to match the cluster name of the servers where the operation must be executed.

Usage Notes

When issuing a command for a peer server using the -rhpserver option, the user running the command must be an existing user of the peer server and the user must have a required role. To enable a user from a peer server to run commands on the local server, run the rhpctl grant role command to grant a required role to the peer server user and to specify the cluster name of the peer server to which the user belongs. For example:

$ rhpctl grant role -role role_name -user user_name -client cluster_name

To add multiple users, run the following command:

$ rhpctl grant role -client cluster_name -maproles role=user_name[+user_name...][,role=user_name[+user_name...]...]

For information about granting roles with RHPCTL, refer to rhpctl grant role