db2iupdt - Update instances command

Updates an instance to a higher fix pack level within a release, converts an instance other than a Db2® pureScale® instance to a Db2 pureScale instance, or changes the topology of a Db2 pureScale instance.

When using this command to update a Db2 pureScale instance, the operation that you specify for the member or cluster caching facility determines whether the instance can remain running or not. For details, see the parameter explanation. Otherwise, when using this command to update an instance that is not a Db2 pureScale instance, before running the db2iupdt command, you must first stop the instance and all processes that are running for the instance.

Note: In a Db2 pureScale instance, you cannot make changes to the resource model without having a configurational quorum, meaning that a majority of nodes are online. In a two-host setup, you cannot use the db2iupdt command if one of the hosts is offline.

Authorization

On UNIX and Linux operating systems, you can have either root user or non-root user authority. On Windows operating systems, Local Administrator authority is required.

Command syntax

For UNIX and Linux® operating systems: Basic-instance-configuration-options
DB2-pureScale-topology-change-options
add-m-options
add-cf-options
update-m-options
update-cf-options
Convert-to-DB2-pureScale-instance-options
DB2-pureScale-fix-pack-update-options
DB2-text-search-configuration-options

For a non-root thin server instance on Linux and AIX operating systems

For Windows operating systems: Db2 Text Search options

Command parameters

For root installation on UNIX and Linux operating systems

-h | -?

Displays the usage information.

-a AuthType

Specifies the authentication type (SERVER, SERVER_ENCRYPT or CLIENT) for the instance. The default is SERVER.

-d

Turns on debug mode.

-k

Keeps the current instance type during the update.

-D

Moves an instance from a higher code level on one path to a lower code level that is installed on another path. This parameter is deprecated and might be removed in a future release. This parameter is replaced by the -f level parameter.

-f level

Moves an instance from a higher Db2 version instance type to a lower Db2 version instance type for compatibility.

-add

Specifies the host name and cluster interconnect netname or netnames of the host to be added to the Db2 pureScale Feature instance. The db2iupdt -add command must be run from a host that is already part of the Db2 pureScale instance. The instance can remain online when adding a member or CF.

-m MemberHostName -mnet MemberNetName -mid MemberID: The host with hostname MemberHostName is added to the Db2 pureScale Feature instance with the cluster interconnect netname MemberNetName. If MemberHostName has multiple cluster interconnect network adapter ports, you can supply a comma delimited list for MemberNetName to separate each cluster interconnect netname.
The -mid MemberID parameter indicates the member identifier for a newly added member. Valid values range from 0 to 127. If not specified, a value is generated automatically.
-cf CFHostName -cfnet CFNetName: The host with hostname CFHostName is added to the Db2 pureScale Feature instance as a cluster caching facility with the cluster interconnect netname CFNetName. If CFHostName has multiple cluster interconnect network adapter ports, you can supply a comma delimited list for CFNetName to separate each cluster interconnect netname.
-red_grp_id RedundancyGroupID: Specifies the location where a member, CF or disk resides in a geographically dispersed Db2 pureScale cluster (GDPC) environment. This option is mandatory for adding a member, CF or a disk in a GDPC environment with storage replication setup. The valid values of this option are 1 and 2.
-tbhost Host_name_for_tiebreaker: Specifies the host that will act as a tiebreaker in IBM® Spectrum Scale replicated file systems. This parameter is mandatory for setting up replicated file systems.
Note:
The tiebreaker host can be an existing member or CF only in a single-site pureScale cluster environment.

-update

This parameter is used to update the interconnect netnames used by the CF or member. To update the netname of a member or CF, the instance can be running but the specific target member or specific target CF must be stopped. The db2iupdt -update command must be run from the target CF or target member.

This option can be used with the -m and -mnet parameters, or the -cf and -cfnet parameters.

-m MemberHostName -mnet MemberNetName: The host with hostname MemberHostName is updated to the Db2 pureScale Feature instance with the cluster interconnect netname MemberNetName. If MemberHostName has multiple cluster interconnect network adapter ports, you can supply a comma delimited list forMemberNetName to separate each cluster interconnect netname. If you are adding extra netnames, the comma delimited list of netnames must include the existing netnames. Up to 4 netnames can be used.
-cf CFHostName -cfnet CFNetName: The host with hostname CFHostName is updated to the Db2 pureScale Feature instance as a cluster caching facility with the cluster interconnect netname CFNetName. If CFHostName has multiple cluster interconnect network adapter ports, you can supply a comma delimited list for CFNetName to separate each cluster interconnect netname. If you are adding extra netnames, the comma delimited list of netnames must include the existing netnames. Up to 4 netnames can be used. When you update a CF to add an additional cluster interconnect netname, after the netname is added, each member must be stopped and started.
-red_grp_id RedundancyGroupID: Specifies the location where a member, CF or disk resides in a geographically dispersed Db2 pureScale cluster (GDPC) environment. This option is mandatory for updating a member, CF or a disk in a GDPC environment with storage replication setup. The valid values of this option are 1 and 2.

-drop -m MemberHostName | -cf CFHostName

Specifies the host (member or cluster caching facility) to be dropped from a Db2 pureScale instance. When dropping a CF, the instance can remain running. However, before dropping a member, the instance must be stopped.

To specify which type of host to be dropped, use the -m option for a member, or -cf option for a cluster caching facility. This option can be used with either the -m or the -cf parameter, not both.

This parameter cannot be used to drop the last member and the last CF from a Db2 pureScale instance. This parameter should not be used with the -add parameter.

The -mid MemberID parameter can be used with the -m MemberHostName parameter. The -mid MemberID indicates the member identifier for a logical member to be dropped. Valid values range 0 - 127. If not specified, all members of MemberHostName are dropped.

After a member is dropped, its entry is kept in the diagnostic directory.

-instance_shared_dev instanceSharedDev

Specifies a shared disk device path required to set up a Db2 pureScale instance to hold instance shared files and default database path. For example, the device path /dev/hdisk1. The shared directory must be accessible on all the hosts for the Db2 pureScale instance. The value of this parameter cannot have the same value as the -tbdev parameter. This parameter and -instance_shared_dir are mutually exclusive.

This parameter is only required if you are updating an instance other than a Db2 pureScale instance to a Db2 pureScale instance.

-instance_shared_mount sharedMountDir

Specifies the mount point for a new IBM Spectrum Scale file system. The specified path must be a new and empty path that is not nested inside an existing IBM Spectrum Scale file system.

-instance_shared_dir instanceSharedDir

Specifies the directory in a shared file system (IBM Spectrum Scale) required to set up a Db2 pureScale instance to hold instance shared files and default database path. For example, /sharedfs. The disk must be accessible on all the hosts for the Db2 pureScale instance. The value of this parameter cannot have the same value as the -tbdev parameter. This parameter and -instance_shared_dev are mutually exclusive.

This parameter is only required if you are updating an instance other than a Db2 pureScale instance to a Db2 pureScale instance.

-tbdev Shared_device_for_tiebreaker

Specifies a shared device path that will act as a tiebreaker in the Db2 pureScale environment to help ensure that the integrity of the data is maintained. The value of this parameter cannot have the same value as either the -instance_shared_dev parameter or the -instance_shared_dir parameter.

This parameter is required when the Db2 cluster services tiebreaker is created, or if updating an instance other than a Db2 pureScale instance to a Db2 pureScale instance. This parameter is invalid if a Db2 cluster services Peer Domain exists.

-commit_level

Commits the pureScale instance to a new level of code. This parameter is mandatory in Db2 pureScale environments.

-check_commit

Verifies whether the Db2 instance is ready for a commit.

-j "TEXT_SEARCH"

Configures the Db2 Text Search server with generated default values for service name and TCP/IP port number. This parameter cannot be used if the instance type is client or dsf.

-j "TEXT_SEARCH,servicename": Configures the Db2 Text Search server by using the specified service name and an automatically generated port number, unless the service name has a port number that is assigned in the services file. If a port number is assigned in the file, that port number is used with the specified service name.
-j "TEXT_SEARCH,servicename,portnumber": Configures the Db2 Text Search server with the provided service name and port number.
-j "TEXT_SEARCH,portnumber": Configures the Db2 Text Search server with a default service name and the provided port number. Valid port numbers must be within the 1024 - 65535 range.

-u Fenced ID

Specifies the name of the user ID under which fenced user-defined functions and fenced stored procedures will run. This parameter is only needed when converting an instance from a client instance to a non-client instance type. To determine the current instance type, refer to the node type parameter in the output from a GET DBM CFG command. If an instance is already a non-client instance, or if an instance is a client instance and is staying as a client instance (for example, by using the -k parameter), the -u parameter is not needed. The -u parameter can change the fenced user for an existing instance.

-fixtopology

Used to manually correct a failed add or drop operation. For an add operation, this parameter will roll back any changes to return to the previous topology. For a drop operation, this parameter will complete the drop operation. This parameter cannot be used in combination with any other parameters, except -d.

InstName

Specifies the name of the instance.

For a non-root thin server instance on Linux and AIX operating systems

-d: Turns debug mode on for use by Db2 database support.
-h | -?: Displays the usage information.

For root installation on Windows operating systems

InstName

Specifies the name of the instance.

/u:username,password

Specifies the account name and password for the Db2 service.

/p:instance-profile-path

Specifies the new instance profile path for the updated instance.

/r:baseport,endport

Specifies the range of TCP/IP ports to be used by the partitioned database instance when running in MPP mode. When this option is specified, the services file on the local machine will be updated with the following entries:

DB2_InstName       baseport/tcp
DB2_InstName_END   endport/tcp

/h:hostname

Overrides the default TCP/IP host name if there are more than one TCP/IP host names for the current machine.

/s

Updates the instance to a partitioned instance.

/q

Issues the db2iupdt command in quiet mode.

/a:authType

Specifies authType, the authentication type (SERVER, CLIENT, or SERVER_ENCRYPT) for the instance.

/j "TEXT_SEARCH"

Configures the Db2 Text Search server with generated default values for service name and TCP/IP port number. This parameter cannot be used if the instance type is client.

/j "TEXT_SEARCH, servicename": Configures the Db2 Text Search server with the provided service name and an automatically generated port number. If the service name has a port number assigned in the services file, it uses the assigned port number.
/j "TEXT_SEARCH, servicename, portnumber": Configures the Db2 Text Search server with the provided service name and port number.
/j "TEXT_SEARCH, portnumber": Configures the Db2 Text Search server with a default service name and the provided port number. Valid port numbers must be within the 1024 - 65535 range.

/?

Displays usage information for the db2iupdt command.

Examples

Reverting an instance to a lower mod pack or fix pack level within a release

To revert a Db2 instance to a lower level, enter the following command:

<DB2DIR>/instance/db2iupdt -f level <instanceName>

Where DB2DIR is the location of the previous mod pack or fix pack.

For UNIX and Linux operating systems

A db2inst2 instance is associated with a Db2 copy of Db2 database product installed at DB2DIR1. You have another copy of a Db2 database product on the same computer at DB2DIR2 for the same version of the Db2 database product that is installed in the DB2DIR1 directory.

To update the instance to run from the Db2 copy installed at DB2DIR1 to the Db2 copy installed at DB2DIR2, issue the following command:

DB2DIR2/instance/db2iupdt db2inst2

If the Db2 copy installed in the DB2DIR2 directory is at level lower than the Db2 copy installed in the DB2DIR1 directory, issue the following command:

DB2DIR2/instance/db2iupdt -D db2inst2

Update an instance to a higher level within a release

To update a Db2 instance to a higher level or from one Db2 installation path to another, enter a command such as the following:

DB2DIR/instance/db2iupdt db2inst1

where DB2DIR represents the installation location of your Db2 copy. If this command is run from a Db2 pureScale Feature copy, the existing db2inst1 must have an instance type of dsf.

If the db2inst1 instance is a Db2 pureScale instance, this example can update it from one level to a different level of Db2 Enterprise Server Edition with the Db2 pureScale Feature. This example does not apply to updating an ese type instance to aDb2 pureScale instance. The next example outlines this procedure.

Update for an instance other than a Db2 pureScale instance to a Db2 pureScale instance

To update an instance to a Db2 pureScale instance:

DB2DIR/instance/db2iupdt 
   -cf host2
   -cfnet host2-ib0
   -m host1
   -mnet host1-ib0
   -instance_shared_dev /dev/hdisk1
   -tbdev /dev/hdisk2
   -u db2fenc1
    db2inst1

where DB2DIR represents the installation location of your Db2 copy.

This command also uses /dev/hdisk1 to create a shared file system to store instance shared files and sets up /dev/hdisk2 as the shared device path that will act as a tiebreaker. The value of the -tbdev parameter must be different from the value of the -instance_shared_dev parameter.

Scale a Db2 pureScale instance (by using db2iupdt -add or db2iupdt -drop)

The following examples apply to a Db2 pureScale environment:

Update a Db2 pureScale instance to add a member.
To add a member called host1 with a netname of host1-ib0 to the Db2 pureScale instancedb2sdin1 enter a command such as the following:
```
DB2DIR/instance/db2iupdt -d -add -m host1 -mnet host1-ib0 db2sdin1 
```
where DB2DIR represents the installation location of your Db2 copy.
Update a Db2 pureScale instance to add a second cluster caching facility.
To add a cluster caching facility called host2 with a netname of host2-ib0 to the Db2 pureScale instance db2sdin1 enter a command such as the following:
```
DB2DIR/instance/db2iupdt -d -add -cf host2 -cfnet host2-ib0 db2sdin1 
```
where DB2DIR represents the installation location of your Db2 copy.
Drop a member from a Db2 pureScale instance.
To drop a member called host1 from the Db2 pureScale instance db2sdin1 enter a command such as the following:
```
DB2DIR/instance/db2iupdt -d -drop -m host1 db2sdin1
```
where DB2DIR represents the installation location of your Db2 copy. If host1 does not have a CF role in the same instance, the command must be run from a host other than host1.

Note:

If you add or drop a CF, the NTP configurations on the existing Db2 pureScale instances will not reflect this change. The ntp.conf on each pureScale instance will have to be updated manually to reflect the new CF.
When adding or dropping CFs (not members), all other members and CFs in the cluster need to reconfigure their NTP configuration file to reflect the new CFs (added or deleted), and then restart the NTP service.

Updating a CF to use an additional cluster interconnect network adapter port on an InfiniBand network

Before updating the CF, db2nodes.cfg contains:

0   memberhost0    0   memberhost0-ib0
128 cfhost0        0   cfhost0-ib0

Note: Do not modify db2nodes.cfg directly.

Run the following command:

db2iupdt -update -cf cfhost0:cfhost0-ib0,cfhost0-ib1,cfhost0-ib2,cfhost0-ib3

The db2nodes.cfg now contains:

0   memberhost0    0   memberhost0-ib0
128 cfhost0        0   cfhost0-ib0,cfhost0-ib1,cfhost0-ib2,cfhost0-ib3

Usage notes

For all supported operating systems

You can use the db2iupdt command to update a Db2 instance from one Db2 copy to another Db2 copy of the same Db2 version. However, the Db2 global profile variables that are defined in the old Db2 copy installation path will not be updated over to the new installation location. The Db2 instance profile variables that are specific to the instance will be carried over after you update the instance.
For a partitioned database environment instance, you must install the fix pack on all the nodes, but the instance update is needed only on the instance-owning node.

For UNIX and Linux operating systems

If you change the member topology, for example by dropping a member, you must take an offline backup before you can access the database. If you attempt to access the database before taking an offline backup, the database is placed in a backup pending state.
You can add multiple members or drop multiple members without having to take a backup after each change. For example, if you add three members, you can then drop one or more members before you must take a backup. Once a backup is taken, you are free to start another add operation
The db2iupdt command is located in the DB2DIR/instance directory, where DB2DIR is the location where the current version of the Db2 database product is installed.
If you want to update a non-root instance, refer to the db2nrupdt non-root-installed instance update command. The db2iupdt does not support updating of non-root instances.
If you are using the su command instead of the login command to become the root user, you must issue the su command with the - option to indicate that the process environment is to be set as if you had logged in to the system with the login command.
You must not source the Db2 instance environment for the root user. Running db2iupdt when you sourced the Db2 instance environment is not supported.
On AIX® 7.1 (or higher), when running this command from a shared Db2 copy in a system workload partition (WPAR) global environment, this command must be run as the root user. WPAR is not supported in a Db2 pureScale environment.
When you run the db2iupdt command to update an instance to a higher level within a release, routines and libraries are copied from each member to a shared location. If a library has the same name but different content on each host, the library content in the shared location is that of the last host that ran the db2iupdt command.
In a Db2 pureScale environment, to allow the addition of members to member hosts, the db2iupdt command reserves six ports in the /etc/services file with the prefix DB2_instname. You can have up to three members on the same host, with the other three ports reserved for the idle processes. A best practice is to have up to three members on the same host. However, if you want to have more than three members on a host, you can extend the number of ports in this range to be more than six. If you want to make changes to the /etc/services file, the instance must be fully offline, and you must change the /etc/services file on all hosts in the cluster.
When you run the db2iupdt command to modify a Db2 pureScale instance, the path <root_home>/db2log is used as a temporary working space for the remote validation of nodes that are part of the Db2 pureScale cluster. All files under this path are subject to modification.

For Windows operating systems

The db2iupdt command is located in the DB2PATH\bin directory, where DB2PATH is the location where the current version of the Db2 database product is installed.
The instance is updated to the Db2 copy from which you issued the db2iupdt command. To move your instance profile from its current location to another location, use the /p parameter, and specify the instance profile path. Otherwise, the instance profile stays in its original location after the instance update. Use the db2iupgrade command instead to upgrade to the current release from a previous release.