The ifxclone utility

You use the ifxclone utility to create a server clone from a snapshot of an existing database server.

Syntax

>>-ifxclone--+-| Mandatory parameters |--+-------------------------+-+-><
             |                           '-| Optional parameters |-' |   
             '- help ------------------------------------------------'   

Mandatory parameters

|-- --source=source_name --sourceIP=source_IP --sourcePort=source_port-->

>-- --target=target_name --targetIP=target_IP --targetPort=target_port--|

Optional parameters

   .----------------------------------.                    
   V                                  |                    
|----+------------------------------+-+--+-------------+-------->
     '- --configparmparameter=value-'    '- --autoconf-'   

>--+-------------------------+--+-------------+----------------->
   '- --disposition=-+-ER--+-'  '- --useLocal-'   
                     +-HDR-+                      
                     +-RSS-+                      
                     '-SDS-'                      

>--+--------------+--+------------+--+--------------------+-----|
   '- --size=size-'  '- --trusted-'  '- --createchunkfile-'
Element Purpose Key Considerations
disposition Specifies the final disposition of the new server instance. If the --disposition (-d) parameter is not specified, a standard server is created.
ER Specifies that the new server instance is created as a replication server.
HDR Specifies that the new server instance is created as an HDR secondary server.
parameter=value Specifies an optional configuration parameter and value to set on the target server.

Certain configuration parameters on the source server must match those on the target server. See Prerequisites for cloning an RS secondary server.
RSS Specifies that the new server instance is created as an remote stand-alone secondary server.
SDS Specifies that the new server instance is created as a shared-disk secondary server. The ifxclone utility sets the target server's SDS_PAGING, and SDS_TEMPDBS configuration parameters, but full configuration is outside the scope of the ifxclone utility.

If --disposition=SDS is specified in the command, but --useLocal is not, you must set the SD secondary server's ROOTPATH configuration parameter to the same value as the ROOTPATH configuration parameter on the primary server.
size Specifies the size of the target server. Valid values are tiny, small, medium, and large. If the size parameter is not specified, the size parameters from the source instance are used.
source_name Specifies the name of the source instance. The source server must be a primary server and cannot be a secondary server.
source_IP Specifies the source server instance TCP/IP address.
source_port Specifies the TCP/IP port address of the source server instance, or the name of a service associated with the port.
target_name Specifies the name of the target server instance.
target_IP Specifies the target server instance TCP/IP address.
target_port Specifies the TCP/IP port address of the target server instance, or the name of a service associated with the port.

The following table describes the options of the ifxclone utility.

Long Form Short Form Meaning
--autoconf -a Autoconfigures connectivity information between a newly cloned server and the other servers of a high-availability cluster or Enterprise Replication domain. If this option is used to create a replication server, the --autoconf option can autoconfigure replication.
The --autoconf option has the following requirements:
  • The CDR_AUTO_DISCOVER configuration parameter must be set to 1 on the target server, the source server, and all other cluster or replication servers.
  • REMOTE_SERVER_CFG must be set on all cluster or replication servers.
  • The target server's host information must be in the source server's trusted-host file.
  • If used with the --disposition=ER option, and the primary server is part of an Enterprise Replication, all other replication servers in the domain must be active.
--configParm -c Specifies the name and value of a configuration parameter to set on the target server.
--createchunkfile -k Automatically creates the same cooked chunk files on the target server as exist on the source server.

This option does not create raw chunks. However, if you have raw chunks on the source server and you do not create matching raw chunks on the target server before using this option, the ifxclone utility creates cooked chunks on the target server that match the raw chunks on the source server.
--disposition -d Specifies the disposition of the new server instance.
--help -h Displays usage information.
--size -s Specifies the size of the target instance.
--source -S Specifies the name of the source server instance.
--sourceIP -I Specifies the TCP/IP address of the source server instance.
--sourcePort -P Specifies the TCP/IP port address of the source server instance, or the name of a service associated with the port.
--target -t Specifies the name of the target server instance.
--targetIP -i Specifies the TCP/IP address of the target server instance.
--targetPort -p Specifies the TCP/IP port address of the target server instance, or the name of a service associated with the port.
--trusted -T Specifies that the server is trusted and that it is not necessary to obtain a userid and password to access the server.
--useLocal -L Specifies that the configuration information contained in the source server onconfig file should be merged with the target server onconfig file.

Certain configuration parameters on the source server must match those on the target server. See Prerequisites for all servers.

Usage

Use the ifxclone utility to clone a server with minimum setup or configuration, or to quickly add a new node to an existing ER replication domain. When the ifxclone utility is run, the majority of the setup information is obtained from the server node that is being cloned. Successfully cloning a server might still require some post-configuration steps to achieve a better running system.

The source server is the server that contains the data you wish to clone. The target server is the server that is to be loaded with data from the source server. You must run the ifxclone utility from the target server.

To run the ifxclone utility on a UNIX™ computer, you must run the command on the target server as user root, user informix, or as a member of the informix group. You must also be a DBSA on the source server.

To run the ifxclone utility on a Windows™ computer, you must run the command on the target server as a member of the local administrators group. You must also be a DBSA on the source server and you must belong to the Informix-Admin group on the source server.

The ifxclone utility uses the onconfig and sqlhosts configuration files from the source server to configure the target server. The ifxclone utility also configures some additional configuration settings, but only those required to configure the clone server. The --autoconf option provides the additional ability to configure sqlhosts file records, and then propagate sqlhosts and trusted-host file information to the servers of a high-availability cluster or Enterprise Replication domain. The --createchunkfile options creates the same cooked chunks and cooked mirror chunks on the target system that are on the source server. The ifxclone utility is not meant to configure all of the possible configuration options, but rather to provide enough configuration to clone the source server.

The number of CPU VPs and buffers on the target server can be configured using the size parameter. List of size parameter values lists the number of CPU VPs and buffer pools created on the target server for each size option. Additional refinement of the generated configuration should be performed after the target system is created. If the size configuration is omitted, the parameter configured on the source server is used.

Table 1. List of size parameter values
Size Number of CPU VPs Number of buffers
tiny 1 50,000
small 2 100,000
medium 4 250,000
large 8 500,000

You can use the -c option to specify a configuration parameter and its value on the target server. You can also use an existing configuration file. If the target server contains a configuration file that is different than the source server configuration file, the ifxclone utility does not overwrite the file but modifies those parameters that must match the source server during the cloning process.

The --useLocal parameter is required if the target server is located on the same host machine as the source server.

If the --useLocal parameter is specified, the ifxclone utility merges the source server onconfig file with the target server onconfig file. The configuration parameters listed in Prerequisites for all servers are overwritten by the ifxclone utility and the rest of the parameters are not affected.

If the --useLocal parameter is not specified as an input parameter, the ifxclone utility uses the source server's onconfig file as the target's onconfig file and uses the server name from the input parameters of the ifxclone utility.

If the --useLocal parameter is not specified, the ifxclone utility updates the sqlhosts file on the host server with the target server entry and copies both entries to the target's sqlhosts file.

The order of precedence of options for the ifxclone parameters is as follows:
  • The --configParm parameter takes precedence over the configuration file on the source server.
  • The --size parameter takes precedence over merged configuration parameters or the settings in the local configuration file.
  • The --configParm parameter takes precedence over the --size parameter.
  • Parameters that must be the same on each server take precedence over all other options.

Prerequisites for all servers

Perform the following prerequisites before cloning a server:

  • Hardware and software requirements for the servers are generally the same as those for HDR secondary servers (refer to the machine notes for specific supported platforms).
  • Both the source and target servers must be part of a trusted network environment. See Network security files for information about configuring a trusted environment.
  • If the disposition of the target server is specified as ER or RSS then you must provide users with connection permission to the sysadmin database on the source server. By default, connection permission to the sysadmin database is limited to user informix.
  • Only one server clone process can occur at a time. Do not start cloning a second server until the first clone process has completed running.
  • The source server must have the ENABLE_SNAPSHOT_COPY configuration parameter set to 1 in the onconfig file.
  • The target server must not have any old ROOTPATH pages. If the target server has old ROOTPATH pages, create a zero-length ROOTPATH file or set the FULL_DISK_INIT configuration parameter to 1 in the target server's onconfig file.
  • The target server must not have any existing storage space encryption keystore or stash files. If you receive an error message that the command failed because of existing keystore and stash files, follow the instructions in the message and rerun the ifxclone command.

Archive operations, such as ontape and ON-Bar commands, are not allowed while cloning a server. Perform your data archive activities before starting to clone a server.

The following environment variables must be set on the target server before cloning a server:

  • INFORMIXDIR
  • INFORMIXSERVER
  • INFORMIXSQLHOSTS
  • ONCONFIG

The following configuration parameter values must be identical on both the source and target servers:

  • DISK_ENCRYPTION (if the target server is an SD secondary server)
  • DRAUTO
  • DRINTERVAL
  • DRTIMEOUT
  • LOGBUFF
  • LOGFILES
  • LOGSIZE
  • LTAPEBLK
  • LTAPESIZE
  • ROOTNAME
  • ROOTSIZE
  • PHYSBUFF
  • PHYSFILE
  • STACKSIZE
  • TAPEBLK
  • TAPESIZE

If the MIRROR configuration parameter is enabled on the target server, the following configuration parameters also must match between the source and target servers:

  • MIRRORPATH
  • MIRROROFFSET

The following table shows the valid combinations of the MIRROR configuration parameter on the source and target servers.

Table 2. Valid settings of the MIRROR configuration parameter on source and target servers
MIRROR configuration parameter set on the source server MIRROR configuration parameter set on the target server Permitted or not permitted
No No Permitted
Yes Yes Permitted
Yes No Permitted
No Yes Not permitted. If this setting is configured, the server issues a warning and disables the MIRROR parameter in the target server onconfig file.

Prerequisites for cloning an RS secondary server

  1. Set the following environment variables on the target server:
    • INFORMIXDIR
    • INFORMIXSERVER
    • ONCONFIG
    • INFORMIXSQLHOSTS
  2. On the target server, create all of the chunks and mirror chunks that exist on the source server. If the target server is using mirroring, the mirror chunk paths must match those of the source server and the chunks must exist. You can use the --createchunkfile option (-k) to automatically create cooked chunks on the target server. Follow these steps to create the chunks and (if necessary) mirror chunks for the target server:
    1. On the source server, run the onstat -d command to display a list of chunks and mirror chunks:
      onstat -d
    2. On the target server, log in as user informix and use the touch, chown, and chmod commands to create the set of chunks and mirror chunks reported by the onstat -d command. For example, to create a chunk named /usr/informix/chunks/rootdbs.chunk, follow these steps:
      $ su informix
Password:
$ touch /usr/informix/chunks/rootdbs.chunk
$ chown informix:informix /usr/informix/chunks/rootdbs.chunk
$ chmod 660 /usr/informix/chunks/rootdbs.chunk
    3. Repeat all of the commands in the previous step for each chunk reported by the onstat -d command.
  3. Run the ifxclone utility with the appropriate parameters on the target system.
  4. Optionally, create onconfig and sqlhosts files on the target server.

Example 1, Cloning an RS secondary server using the source server configuration

This example shows how to clone a server by using the onconfig and sqlhosts configuration files from the source server.

In this example, omitting the -L option causes the ifxclone utility to retrieve the necessary configuration information from the source server. The configuration files are used as a template to create the target server configuration. Having the ifxclone utility create the configuration files for you saves time and reduces the chance of introducing errors into the configuration files.

The -k option creates the necessary cooked chunks on the target server.

For this example, assume that the source server (Amsterdam) has an sqlhosts file configured as follows:

#Server   Protocol HostName        Service Group
Amsterdam onsoctcp 192.168.0.1 123     -

You also need the name, IP address, and port number of the target server. The following values are used for this example:

  • Source server name: Amsterdam
  • Source IP address: 192.168.0.1
  • Source port: 123
  • Target server name: Berlin
  • Target IP address: 192.168.0.2
  • Target port: 456
  1. On the target server, create all of the chunks that exist on the source server. You can use the --createchunkfile option (-k) to automatically create cooked chunks on the target server. Log-in as user informix and use the commands touch, chown, and chmod to create the chunks.
  2. On the target server, run the ifxclone utility:
    ifxclone -T -S Amsterdam -I 192.168.0.1 -P 123 -t Berlin 
         -i 192.168.0.2 -p 456 -d RSS -k
    ifxclone -T -S Amsterdam -I 192.168.0.1 -P 123 -t Berlin 
         -i 192.168.0.2 -p 456 -d RSS

    The ifxclone utility modifies the sqlhosts file on the source server and creates a copy of the file on the new target server. The sqlhosts file on the target server is the same as the source server:

    #Server   Protocol HostName        Service Group
Amsterdam onsoctcp 192.168.0.1 123     -   
Berlin    onsoctcp 192.168.0.2 456

Example 2, Cloning an RS secondary server by merging the source server configuration

Use the --useLocal option to create a clone of a server on a remote host computer: The --useLocal option is used to merge the source onconfig file configuration information with the target onconfig file. This option also copies the source sqlhosts file to the target server. The following values are used for this example:

  • Source server name: Amsterdam
  • Source IP address: 192.168.0.1
  • Source port: 123
  • Target server name: Berlin
  • Target IP address: 192.168.0.2
  • Target port: 456
  1. Create the onconfig and sqlhosts files and set the environment variables on the target computer.
  2. On the target server, create all of the chunks that exist on the source server. You can use the --createchunkfile option (-k) to automatically create cooked chunks on the target server. Log-in as user informix and use the commands touch, chown, and chmod to create the chunks.
  3. On the target server, run the ifxclone utility:
    ifxclone -T -L -S Amsterdam -I 192.168.0.1 -P 123 -t Berlin 
         -i 192.168.0.2 -p 456 -d RSS -k
    ifxclone -T -L -S Amsterdam -I 192.168.0.1 -P 123 -t Berlin 
         -i 192.168.0.2 -p 456 -d RSS

Example 3, Adding an RS secondary server to a cluster

This example shows how to add an RS secondary server to the existing HCL OneDB™ high-availability cluster. The following values are used for this example:

  • Source server name: Amsterdam
  • Source IP address: 192.168.0.1
  • Source port: 123
  • Target server name: Berlin
  • Target IP address: 192.168.0.2
  • Target port: 456
  1. Create the onconfig and sqlhosts files and set the environment variables on the target computer.
  2. On the target server, create all of the chunks that exist on the source server. You can use the --createchunkfile option (-k) to automatically create cooked chunks on the target server. Log-in as user informix and use the commands touch, chown, and chmod to create the chunks.
  3. On the target server, run the ifxclone utility:
    ifxclone -T -L -S Amsterdam -I 192.168.0.1 -P 123 -t Berlin 
         -i 192.168.0.2 -p 456 -s medium -d RSS -k
    ifxclone -T -L -S Amsterdam -I 192.168.0.1 -P 123 -t Berlin 
         -i 192.168.0.2 -p 456 -s medium -d RSS

Prerequisites for cloning an ER server

Complete the following prerequisites before attempting to clone an ER server.

  1. The source server (that is, the server that is being cloned) must have ER configured and active.
  2. For configuration parameters that specify directory names, the directory names must exist on the target server. For example, if the CDR_LOG_STAGING_DIR configuration parameter is set to a directory name on the source server then the directory must also exist on the target server.
  3. If ATS or RIS is enabled on the source server then the appropriate ATS or RIS directories must exist on the target server. See Enabling ATS and RIS File Generation and Creating ATS and RIS directories. If the directories do not exist then ATS/RIS spooling will fail.
  4. If the source server has the CDR_SERIAL configuration parameter set then you must set the value for CDR_SERIAL to a different value on the server to be cloned. The value of CDR_SERIAL must be different on all replication servers. You can specify a unique value for the CDR_SERIAL configuration parameter by using the --configParm (-c) parameter in the ifxclone command line.
  5. The clock on the new ER clone must be appropriately synchronized. See Time synchronization.
  6. The source server (that is, the server being cloned) must not have any stopped or suspended replicates, nor can it have any shadow replicates defined.

Avoid performing ER administrative tasks that change the set of replicates on which the target server participates while the ifxclone utility is running.

Example: Creating a clone of an ER server

Suppose you have five ER servers named S1, S2, S3, S4, and S5 currently configured as root servers in an ER domain. You would like to add a new server, S6, on a new computer named machine6, and you want it to have the same data as server S3.
  1. Install and configure HCL OneDB database software on machine6. You can use the deployment utility to deploy a pre-configured database server instance.
  2. Copy the sqlhosts file from server S3 to server S6 and modify it to add entries for the new server. For example, assuming the ER group name for the new server is g_S6 and the ID is 60, the sqlhosts file lines would look like the following.
    g_S6    group     -           -         i=60
S6      onsoctcp  machine6    service6  g=g_S6
  3. Add the two lines from the previous step in the sqlhosts files on all of the other five servers (S1 through S5).
  4. Copy the onconfig file from server S3 to server S6 and change the DBSERVERNAME configuration parameter to S6. Do not modify any storage or chunk parameters except for path information.
  5. On server S6 (machine6) provision chunk paths and other storage to the same sizes as server S3. Ensure that S6 has adequate memory and disk space resources. You can use the --createchunkfile option (-k) to automatically create cooked chunks on the target server.
  6. Run the following command as user informix:
    ifxclone -L -S S3 -I machine3 -P service3 -t S6 -i machine6 -p service6 -d ER -k
    ifxclone -L -S S3 -I machine3 -P service3 -t S6 -i machine6 -p service6 -d ER

    When prompted, enter the user name informix and then enter the password for user informix.

  7. Monitor the server logs of servers S6 and S3. When the cloning process is complete you can check the status of servers by running the following command on servers S3 and S6:
    cdr list server
You should see the new ER server g_S6 connected to all of the other five servers. In addition, ER node g_S6 will now participate in all replicates in which ER node g_S3 participates.