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

Note:

The Highly Available Grid Naming Service feature of Grid Naming Service (GNS) in Oracle Grid Infrastructure is deprecated in Oracle Database 23ai. 

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] [-zip zipped_home_path] [-transfer_as_zip] [-storagetype {LOCAL | RHP_MANAGED}]
  [-user user_name] [-dbname unique_db_name 
           [-dbtype {RACONENODE | RAC | SINGLE}] [-datafileDestination datafileDestination_path] 
           [-dbtemplate { file_path | image_name:relative_file_path}] 
           {-node node_list |} 
           [-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] [-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 | PAUSE}] [-jobtag tag_name]
  [-tags tags_criteria] [-checkwcpatches -sourcehome source_home_path] [-scan scan_name]
  [-diskDiscoveryString disk_discovery_string] [-readonly]
  

Parameters

Table A-78 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 destination cluster.

-zip zipped_home_path

Specify the absolute path of the compressed software home.

-transfer_as_zip Specify this option to transfer the working copy to the destination host as a zip file. This parameter works with the -image parameter.
-storagetype {LOCAL | RHP_MANAGED}

Specify the type of storage for the software home.

-user user_name

Specify the name of the user who 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.

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

-cdb

Optionally, use this parameter to create a database as a Container Database (CDB).

-pdbName pdb_prefix

If you are creating one or more Pluggable Databases (PDBs), then specify a PDB name prefix.

-numberOfPDBs pdb_count

Specify the number of PDBs 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.

-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 an rhpclient-less target.

-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 | PAUSE}
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 or the option is omitted, then the job is scheduled immediately.

If PAUSE is specified, then the job starts in the paused state and you need to resume the job using the rhpctl resume job -jobid job_id command.

-jobtag tag_name

Optionally, you can associate a user-defined tag with the scheduled jobs.

-tags tags_criteria

Optionally, specify tags criteria to create child jobs internally in the PAUSED state. Use the rhpctl resume job command to continue the operations of all the child jobs.

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

Starting with Oracle Grid Infrastructure 23ai, Domain Services Clusters (DSC), which is part of the Oracle Cluster Domain architecture, are desupported.

Oracle Cluster Domains consist of a Domain Services Cluster (DSC) and Member Clusters. Member Clusters were deprecated in Oracle Grid Infrastructure 19c. The DSC continues to be available to provide services to production clusters. However, with most of those services no longer requiring the DSC for hosting, installation of DSCs are desupported in Oracle Database 23ai. Oracle recommends that you use any cluster or system of your choice for services previously hosted on the DSC, if applicable. Oracle will continue to support the DSC for hosting shared services, until each service can be used on alternative systems.

  • 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]
       [-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 | PAUSE}] [-jobtag tag_name]

Parameters

Table A-79 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 an rhpclient-less target 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 | PAUSE}
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 or the option is omitted, then the job is scheduled immediately.

If PAUSE is specified, then the job starts in the paused state and you need to resume the job using the rhpctl resume job -jobid job_id command.

-jobtag tag_name

Optionally, you can associate a user-defined tag with the scheduled jobs.

Usage Notes

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

  • If the rhpclient-less target 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 an rhpclient-less target 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 -targetnode node_name 
  [-notify [-cc user_list]] [-force] {-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 | PAUSE}] [-jobtag tag_name] [-metadataonly]

Parameters

Table A-80 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

You must specify a target node when you delete an active working copy.

This parameter is optional when you delete a non-active software-only working copy.

Note:

Do not use this parameter in combination with the metadataonly parameter.
-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 | PAUSE}
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 or the option is omitted, then the job is scheduled immediately.

If PAUSE is specified, then the job starts in the paused state and you need to resume the job using the rhpctl resume job -jobid job_id command.

-jobtag tag_name

Optionally, you can associate a user-defined tag with the scheduled jobs.

-metadataonly

Use this parameter to delete only the working copy metadata, which is located in the metadata repository.

Note:

Do not use this parameter in combination with the targetnode parameter.

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 [-details] [-metadataonly] | -image image_name] 
    [-drift] [-rhpserver <rhps_regex>] | [-client cluster_name [-path path | -image image_name]] | 
    [-imagetype image_type [-version image_version] [-client cluster_name]]

Parameters

Table A-81 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.

-details

Provide details of the move operation if the working copy was part of a move operation.

-image image_name

Alternatively, you can specify the name of a configured image you want to query.

Note:

If you specify an image name, then RHPCTL lists all the working copies based on that image.
-drift

List the 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.

-path path

Location of the working copy.

-rhpserver rhps_regex

Regular expression to match the cluster name of the servers where you want to run the command.

-imagetype image_type

Specify the software type. ORACLEDBSOFTWARE (default) for Oracle Database software, ORACLEGISOFTWARE for Oracle Grid Infrastructure software, ORACLEGGSOFTWARE for Oracle GoldenGate software, LINUXOS for Linux operating system ISO, or SOFTWARE for all other software. If you use custom image types, then specify the name of your image type.

-version image_version

Version of the image associated with the working copy.

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

rhpctl register workingcopy

Registers working copy metadata to the Oracle FPP repository.

Syntax

rhpctl register workingcopy {-attrfile attribute_file | -workingcopy workingcopy_name
   {-client cluster_name | -targetnode target_node_name {-root | -cred cred_name | 
   -sudouser sudo_username -sudopath path_to_sudo_binary | -auth plugin_name 
   [-arg1 name1:value1 [-arg2 name2:value2 ...]]} [-sitetype site_type]}
   [-softwareonly]} -image image_name -path home_path [-groups key=value [,key=value...]]
   [-user user_name] [-oraclebase oraclebase_path] [-node node_list]

Parameters

Table A-82 rhpctl register workingcopy Command Parameters

Parameter Description
-attrfile attribute_file

Absolute file name on the Oracle FPP Server which provides information about the working copy.

-workingcopy workingcopy_name

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

-client cluster_name

Specify the name of the client cluster.

Note:

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

Specify the name of an rhpclient-less target.

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

-sitetype {ORACLERESTART | STANDALONE}

Specify the type of a site that has no Oracle FPP client. The default value is STANDALONE.

-softwareonly

Use this parameter to provision only Oracle Grid Infrastructure software.

-image image_name

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

-path absolute_path

Specify the absolute path for provisioning the software home. For Oracle Database images, this becomes the ORACLE_HOME.

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

-user user_name

Specify the name of the user who 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.

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

-node node_list

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

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

Examples

  • To register an Oracle Database working copy:
    $ rhpctl register workingcopy -workingcopy DBWC2304 -client client3 
    -image DB_2304 -path /u01/app/oracle/product/23.0.0/dbhome1 -user oracle
  • To register an Oracle Grid Infrastructure working copy:
    $ rhpctl register workingcopy -workingcopy GIWC2304 -client client3
     -image GI_2304 -path /u01/app/23.0.0/grid
  • To register a software-only Oracle Grid Infrastructure working copy:
    $ rhpctl register workingcopy -workingcopy SFWC2304 -client client4 
    -image GISF2304 -path /u01/app/23.0.0/grid -softwareonly