db2icrt - Create instance command

Create a Db2® instance, including a Db2 pureScale® instance. This command can also be used to create up to 8 Db2 member and 2 cluster caching facility as part of the creation of the Db2 pureScale instance.

On Linux® and UNIX operating systems, db2icrt is located in DB2DIR/instance , where DB2DIR represents the installation directory in which the Db2 database system is installed. On Windows operating systems, db2icrt is located in DB2PATH\bin, where DB2PATH is the directory where the Db2 copy is installed.

The db2icrt command creates a Db2 instance in the home directory of the instance owner. You can create only one Db2 pureScale instance per Db2 pureScale environment.

Authorization

Root user or non-root user authority is required on Linux and UNIX operating systems. Local Administrator authority is required on Windows operating systems.

Command syntax

For root installation on Linux and UNIX operating systems

InstType

Db2 pureScale options

Db2 Text Search options

Notes:

¹ If the instance type is not specified with -s, the default instance type that is created for the server image is the Db2 Advanced Edition (ese) instance type. The default instance type for Db2 Connect Server Edition is (wse) instance type.
² When you create client instances, -u FencedID is not a valid option.
³ The MemberHostName:MemberNetname format was deprecated for the -m option, and might be discontinued in the future. The new format, with both -m and -mnet options, is required for IPv6 support with Db2 pureScale Feature.
⁴ The CFHostName:CFNetames format was deprecated for the -cf option, and might be discontinued in the future. The new format, with both -cf and -cfnet options, is required for IPv6 support with Db2 pureScale Feature.
⁵ On Linux/Unix, InstName must belong to primary group name which does not exceed 8 characters and cannot contain spaces.

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

For root installation on Windows operating systems

InstType

Db2 Text Search options

Notes:

¹ If the instance type is not specified with -s, the default instance type is the Db2 Advanced Edition (ese) instance type regardless of the product editions.

Command parameters

For root installation on Linux and UNIX operating systems

-?: Displays the usage information.

-h

Displays the usage information.

-d

Turns on debug mode. Saves the trace file with default name in /tmp as db2icrt.trc.ProcessID. Use this option only when instructed by Db2 database support

-a AuthType

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

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

-p <TCP/IP PortName>

Specifies the TCP/IP port name or number that is used by the instance. This option also configures the database manager configuration parameter SVCENAME for the Db2 instance.

-m MemberHostName:NetName1

Specifies the host to set up as a Db2 member during instance creation. This parameter is mandatory in a Db2 pureScale environment.

Up to 8 Db2 member can be set up by the db2icrt command. Additional Db2 members can be added with the db2iupdt -add command.The NetName1 syntax is deprecated and might be discontinued in a future release. Use the -mnet parameter instead.

The MemberHostName must be the canonical host name (for example, the output of 'host name' command run on a local host). The NetName1 value that is specified here must belong to the same subnet as specified in the -cf parameter.

-mnet MemberNetName

This parameter replaces the deprecated :NetName1 syntax of the -m MemberHostName:NetName1 parameter. Specifies the cluster interconnect netname, which is the host name of the interconnect that is used for high-speed communication between members and cluster caching facilities (also referred to as CF) in a Db2 pureScale instance.

The MemberNetName must belong to one of the same subnets that are specified in the -cf parameter, and must correspond to a cluster interconnect netname (for example, db2_<hostname_ib0).

-cf CFHostName:NetName2

Specifies the host to set up as a cluster caching facility (also referred to as CF) during instance creation. This parameter is mandatory in a Db2 pureScale environment.

Two CF can be set up by the db2icrt command. CFs can also be added by using the db2iupdt -add command. The NetName2 syntax is deprecated and might be discontinued in a future release. Use the -cfnet parameter instead.

-cfnet CFNetName

This parameter replaces the deprecated :NetName2 syntax of the -cf CFHostName:NetName2 parameter. Specifies the cluster interconnect netname, which is the host name of the interconnect that is used for high-speed communication between members and CFs in a Db2 pureScale instance.

The CFNetName must belong to the same subnet as specified in the -m parameter, and must correspond to a cluster interconnect netname (for example, db2_<hostname_ib0>).

-instance_shared_dev Shared_Device_Path_for_Instance

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

When the -instance_shared_dev parameter is specified, the Db2 installer creates a Db2 cluster file system.

The -instance_shared_dev parameter and the -instance_shared_dir parameter are mutually exclusive.

-instance_shared_mount Shared_Mounting_Dir

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 Shared_Directory_for_Instance

Specifies a 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 option cannot have the same value as the -tbdev option or the installation path.

When the -instance_shared_dir parameter is specified, the Db2 installer uses a user-managed file system. The user-managed file system must available on all hosts, and must be a IBM Spectrum Scale file system.

The -instance_shared_dir parameter and the -instance_shared_dev parameter are mutually exclusive.

-tbdev Shared_device_for_tiebreaker

Specifies a shared device path for a device that acts as a tiebreaker in the Db2 pureScale environment to ensure that the integrity of the data is maintained. The value of this option cannot have the same value as either the -instance_shared_dev option or the -instance_shared_dir option. This option is required when the Db2 cluster services tiebreaker is created for the first time. The disk device must not associate with any file system. This option is invalid if a Db2 cluster services Peer Domain exists.

Note: When running in a VMware environment, you can not use a virtual disk or RDM disk as a tie-breaker disk because SCSI-3 Persistent Reserve (PR) is not supported on these disks. In this case you need to specify inputas for the tiebreaker disk option to by pass this limitation.

-i db2sshidName

Specifies the non-root user ID required to use a Secure Shell (SSH) network protocol between hosts. The user ID specified must be a user without special privileges. Valid only for a Db2 managed IBM Spectrum Scale file system.

-s InstType

Specifies the type of instance to create. Use the -s option only when you are creating an instance other than the default associated with the installed product from which you are running db2icrt. Valid values are:

dsf: Used to create a Db2 pureScale instance for a Db2 database server with local and remote clients. This option is the default instance type for the IBM Db2 pureScale Feature.
ese: Used to create an instance for a database server with local and remote clients. This option is the default instance type for Db2 Advanced Enterprise Server Edition, Db2 Enterprise Server Edition, or Db2 Workgroup Server Edition.

wse: Used to create an instance for a database server with local and remote clients. This option is the default instance type for Db2 Connect Server Edition.

standalone: Used to create an instance for a database server with local clients.
client: Used to create an instance for a client. This option is the default instance type for IBM Data Server Client, and IBM Data Server Runtime Client.

Db2 database products support their default instance types and the instance types lower than their default ones. For instance, Db2 Advanced Editionsupports the instance types of ese, wse, standalone, and client.

-u Fenced ID

Specifies the name of the user ID under which fenced user-defined functions and fenced stored procedures run. The -u option is required if you are not creating a client instance.

InstName

Specifies the name of the instance that is also the name of an existing user in the operating system. The instance name must be the last argument of the db2icrt command.

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

-d: Enters debug mode, 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.

-s InstType

Specifies the type of instance to create. Currently, there are four kinds of Db2 instance types. Valid values are:

client: Used to create an instance for a client. This option is the default instance type for IBM Data Server Client, and IBM Data Server Runtime Client.
standalone: Used to create an instance for a database server with local clients.
ese: Used to create an instance for a database server with local and remote clients. This option is the default instance type for Db2 Community Edition, Db2 Advanced Edition and Db2 Standard Edition.

-u Username, Password

Specifies the account name and password for the Db2 service. This option is required when you create a partitioned database instance.

-p InstProfPath

Specifies the instance profile path.

-h HostName

Overrides the default TCP/IP host name if there is more than one for the current machine. The TCP/IP host name is used when you create the default database partition (database partition 0). This option is only valid for partitioned database instances.

-r PortRange

Specifies a range of TCP/IP ports to be used by the partitioned database instance when running in MPP mode. For example, -r 50000,50007. The services file of the local machine is updated with the following entries if this option is specified:

DB2_InstName          baseport/tcp
DB2_InstName_END      endport/tcp

/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 that is 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.

Examples

To create a Db2 pureScale instance for the instance owner db2sdin1 and fenced user db2sdfe1, run the following command:
```
DB2DIR/instance/db2icrt 
   -cf host1.domain.com -cfnet host1.domain.com-ib0 
   -m host2.domain.com -mnet host2.domain.com-ib0
   -instance_shared_dev /dev/hdisk1 
   -tbdev /dev/hdisk2 
   -u db2sdfe1 
   db2sdin1
```
where DB2DIR represents the installation location of your Db2 copy. The Db2 pureScale instance db2sdin1 has a CF on host1, and a member on host2. 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 for the tiebreaker.
To create a Db2 Enterprise Server Edition instance for the user ID db2inst1, run the following command:
```
DB2DIR/instance/db2icrt -s ese -u db2fenc1 db2inst1
```
where DB2DIR represents the installation location of your Db2 copy.
To create a Db2 pureScale instance that uses an existing file system (IBM Spectrum Scale) managed by the Db2 product for the instance owner db2sdin1 and the fenced user db2sdfe1, run the following command:
```
DB2DIR/instance/db2icrt 
   -cf host1.domain.com -cfnet host1.domain.com-ib0 
   -m host2.domain.com -mnet host2.domain.com-ib0
   -tbdev /dev/hdisk2 
   -u db2sdfe1 
   db2sdin1
```
where DB2DIR represents the installation location of your Db2 copy.
To create a Db2 pureScale instance with an existing user-managed IBM Spectrum Scale file system (/gpfs_shared_dir) for the instance owner db2sdin1 and the fenced user db2sdfe1, run the following command:
```
DB2DIR/instance/db2icrt 
   -cf host1.domain.com -cfnet host1.domain.com-ib0 
   -m host2.domain.com -mnet host2.domain.com-ib0
   -instance_shared_dir /gpfs_shared_dir
   -tbdev /dev/hdisk2 
   -u db2sdfe1 
   db2sdin1
```
where DB2DIR represents the installation location of your Db2 copy.
On an AIX machine, to create an instance for the user ID db2inst1, issue the following command:
On a client machine:
```
DB2DIR/instance/db2icrt db2inst1
```
On a server machine:
```
DB2DIR/instance/db2icrt -u db2fenc1 db2inst1
```
where db2fenc1 is the user ID under which fenced user-defined functions and fenced stored procedures run.

To create a Db2 pureScale instance on more than one member or CF, run the following command:

DB2DIR/instance/db2icrt
-m coralmem1 -mnet coralmem1-ib0
-m coralmem2 -mnet coralmem2-ib0	
-m coralmem3 -mnet coralmem3-ib0	
-m coralmem4 -mnet coralmem4-ib0	
–m coralmem5 -mnet coralmem5-ib0
-m coralmem6 -mnet coralmem6-ib0
-m coralmem7 -mnet coralmem7-ib0	
-m coralmem8 -mnet coralmem8-ib0
-cf coralcf1 -cfnet coralcf1-ib0	
-cf coralcf2 -cfnet coralcf2-ib0
-instance_shared_dev /dev/hdisk1
-tbdev /dev/hdisk10 -u db2sdin1 db2sdin1

where DB2DIR represents the installation location of your Db2 copy.

Note: The db2icrt command supports Db2 pureScale instance creation on multiple members and CFs up to a maximum of eight members and 2 CFs only. Also, when more than one member or CF is specified, the deprecated format -m MemberHostname:Netname or -cf CFHostName:NetName is not supported.

Usage notes

The instance user must exist on all hosts with the same UID, GID, group name, and home directory path. The same rule applies for the fenced user. After the db2icrt command is successfully run, the Db2 installer will set up SSH for the instance user across hosts.
When you use the db2icrt command, the name of the instance must match the name of an existing user.
You can have only one instance per Db2 pureScale environment.
When you create Db2 instances, consider the following restrictions:
- If existing IDs are used to create Db2 instances, make sure that the IDs are not locked and passwords are not expired.
You can also use the db2isetup command to create and update Db2 instances and add multiple hosts with a graphical interface.
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 logged in to the system with the login command.
You must not source the Db2 instance environment for the root user. Running db2icrt when you sourced the Db2 instance environment is not supported.
If you previously created a Db2 pureScale instance and dropped it, you cannot re-create it using the -instance_shared_dev parameter specification since the Db2 cluster file system might already be created. To specify the previously created shared file system:
- If the existing IBM Spectrum Scale shared file system was created and managed by Db2 pureScale Feature, the -instance_shared_dev parameter and the -instance_shared_dir parameter must not be used.
- If the existing IBM Spectrum Scale shared file system was not created and managed by Db2 pureScale Feature, use the -instance_shared_dir parameter.
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.
For the /var directory memory requirements, see topic "Disk and memory requirements".
In a Db2 pureScale environment, the db2icrt command does not support a Lightweight Directory Access Protocol (LDAP) environment.