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
Read syntax diagramSkip visual syntax diagram db2icrt -h-? -d DefaultType1-sInstType -aAuthType-pPortName-uFencedID2Db2 pureScale options Db2 Text Search options InstName
InstType
Read syntax diagramSkip visual syntax diagramdsfesestandaloneclient
Db2 pureScale options
Read syntax diagramSkip visual syntax diagram -m3 MemberHostName(1),MemberHostName(n) -mnet MemberNetname(1),MemberNetname(i),MemberNetname(n) -cf4 CFHostName(1),CFHostName(n) -cfnet CFNetname(1),CFNetname(i),CFNetname(n) -instance_shared_devShared_Device_Path_for_Instance-instance_shared_mountShared_Mounting_Dir-instance_shared_dirShared_Directory_for_Instance-tbdevShared_device_for_tiebreaker -i db2sshidName
Db2 Text Search options
Read syntax diagramSkip visual syntax diagram -j "TEXT_SEARCH, ServiceName, ServiceName, PortNumber, PortNumber"
Read syntax diagramSkip visual syntax diagram5
Notes:
  • 1 If the instance type is not specified with -s, the default instance type that is created for the server image is the Db2 Enterprise Server Edition (ese) instance type.
  • 2 When you create client instances, -u FencedID is not a valid option.
  • 3 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.
  • 4 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.
  • 5 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
Read syntax diagramSkip visual syntax diagramdb2icrt -d -h -?
For root installation on Windows operating systems
Read syntax diagramSkip visual syntax diagramdb2icrt-? InstName DefaultType1-sInstType -uUserName,  Password-pInstProfPath-hHostNameDb2 Text Search options-rFirstPort, LastPort
InstType
Read syntax diagramSkip visual syntax diagramdsfesestandaloneclient
Db2 Text Search options
Read syntax diagramSkip visual syntax diagram -j "TEXT_SEARCH, ServiceName, ServiceName, PortNumber, PortNumber"
Read syntax diagramSkip visual syntax diagram
Notes:
  • 1 If the instance type is not specified with -s, the default instance type is the Db2 Standard 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.
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 Enterprise Server Edition supports the instance types of ese, 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 with partitioned database environment support. The
-s ese -u Username, Password
options must be used with db2icrt to create the ESE instance type and a partitioned database environment instance.

Db2 Advanced Enterprise Server Edition, Db2 Enterprise Server Edition, Db2 Workgroup Server Edition support ese instance types, and the instance types lower than ese.

For instance, Db2 Enterprise Server Edition supports the instance types of ese, standalone, and client.

-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

  1. 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.
  2. 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.
  3. 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.
  4. 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.
  5. 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.
  6. 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.