Requirements for Db2 hosts and databases

Overview

This page outlines the requirements for establishing connections between the Data Engine and Db2 hosts and instances. Detailed specifications for source, staging, and target environments are provided.

Db2 source host and instance requirements

Every Db2 Source host should:
- Be installed with IBM Db2.
- Have at least one instance created.
Depending on your data ingestion method into the staging server, ensure:
- For HADR Ingestion: Pre-set HADR settings for each database intended for the standby server before initiating the link, as illustrated in Linking a Db2 dSource.
- For Backup and Log Ingestion: No further prerequisites at this moment.

Db2 staging and target host and instance requirements

The Data Engine's staging environment requires:
- A full backup of the source database on disk to make the initial full copy. Using compressed backups is advised for reduced storage and quicker ingestion.
- Subsequent updates can be done through HADR or Archive Logs.
Ensure Db2 instances for staging and target are:
- Already existing on the host.
- Compatible with the source Db2 instance.
It is possible to:
- Use a single instance for both dSource and VDB creation.
- Host multiple VDBs on the same instance.
To check available instances on each host, visit the Databases tab for the corresponding environment.
Configuration values like bufferpool should be managed independently of Delphix.

Db2 DPF configuration requirements for staging and target hosts and instances

Host separation for DPF: For Db2 staging and target environments, configure the Database Partitioning Feature (DPF) on separate hosts. This requirement stems from the DPF environment's high resource consumption.
Consistency with source configuration: Ensure that both the staging and target hosts are set up with an equal number of logical partition nodes as the source.
Logical partition configuration:
- Add the logical partition configuration to the $HOME/sqllib/db2nodes.cfg file. Here, $HOME represents the home directory of the instance user.
- The hostname specified must be a fully qualified domain name (FQDN).
- For an instance with 4 logical partitions, the db2nodes.cfg file should resemble:
  CODE
```
0 <FQDN hostname> 0
1 <FQDN hostname> 1
2 <FQDN hostname> 2
3 <FQDN hostname> 3
```
Port entry for each logical partition:
- Every logical partition requires a matching port entry within the /etc/services file on the hosts.
- For instance, if db2inst1 is the user's instance and ports from 60000 to 60003 are set aside for inter-partition communication, the entries would look like:
  CODE
```
DB2_db2inst1 60000/tcp
DB2_db2inst1_1 60001/tcp
DB2_db2inst1_2 60002/tcp
DB2_db2inst1_END 60003/tcp
```
Updating registry variables:
- Adjust the DB2RSHCMD and DB2COMM registry variables as indicated:
  CODE
```
SSHCMD=$(which ssh)
db2set DB2RSHCMD="$SSHCMD"
db2set DB2COMM=TCPIP
```
Post-configuration check:
- After configuring the environment on both staging and target, run db2_all echo hello on each server. This step registers the host key in the known_hosts file and also verifies any potential ssh issues.
Backup file consistency:
- The backup files, or the log directory (if using Customer Supplied Archive Logs), need to align with the partitions set up on staging.

Additional environmental requirements

Operating system user configuration
- An operating system user, named delphix_os, is required with the following privileges:
  - SSH access to both the staging and target environments.
  - Super-user execution rights for commands: mount, umount, mkdir, and rmdir. On AIX systems, the nfso command is additionally required. Refer to Sudo Privilege Requirements for Db2 Environments for a detailed breakdown of these commands and Sudo File Configuration Examples for Db2 Environments for /etc/sudoers file examples.
Directory requirements
- A directory, e.g., /var/opt/delphix/toolkit, should be present in both the staging and target environments for the Delphix Engine Plugin installation.
- The delphix_os user must own this directory.
- If delphix_os and instance users (who handle operations like linking and provisioning for the Delphix Engine) share a group, this directory should have rwxrwx-- (0770) permissions. Alternatively, more permissive settings can be applied to allow directory creation inside the toolkit path by instance users sharing the delphix_os group.
- If there's no common group between delphix_os and instance users, the directory must have -rwxrwxrwx (0777) permissions.
- The directory needs a minimum of 1.5GB storage space: 400MB for the Plugin and an additional 400MB for logs from each Db2 instance operating on the host.
For the Db2 plugin
- The plugin directory acts as the base location for the mount point.
- With multiple engines accessing a single host environment, allocate a unique Db2 plugin directory for each engine.
- For configurations involving multiple partitions (dpf), the ClientAliveInterval option must be set to 0 or commented out to ensure uninterrupted SSH command executions.
- From version 4.0.0, to modify the toolkit directory, execute the following:
  1. Disable all associated datasets.
  2. The dataset instance must have its DIR_CACHE parameter set to NO, demonstrated as db2 update dbm cfg using DIR_CACHE NO.
  3. Upload the updated vSDK-based plugin. This plugin contains built-in upgrade logic for the existing Lua-based variant.
  4. Refresh the environment, letting the plugin establish paths and files in the scratch path.
  5. Enable all datasets and finalize the migration.
Connectivity and service requirements
- The Delphix Engine needs SSH connection capabilities for both the staging and target environments.
- NFS client services should be active in both environments.
Db2 specific configurations
- The Db2 instance code page must be consistent across staging, target, and production host instances. The instance owner must have an appropriate value set in LC_ALL or LC_CTYPE corresponding to the Db2 code page, ideally derived from the production host's LC_ALL, LC_CTYPE, or LANG.
- The primary user of the environment, e.g., delphix_os, should have its primary group shared with the instance user. As an illustration, if delphix_os is the main user and its primary group is also delphix_os, instance users performing tasks like linking and provisioning should also have delphix_os as their secondary group.

Db2 plugin custom configurations

Version: DB2 plugin v3.x

Configuration file: advanceConfFlag.conf (located in <Toolkit directory> during discovery or environment refresh)

Key parameters

Common group (notCommonGroupFlag)
- Controls permissions for "mnts", "logs", and "code" directories in <Toolkit dir>/db2.
- Set to:
  - false: If the primary environment user (discovery user) shares a group with the instance user.
  - true: Otherwise.
- Default: Commented out (assumed false).
Allow source database on same instance (allowSourceDBonSameInst)
- Controls VDB provisioning on DB2 instances with a database of the same name as the VDB's source.
- Set to:
  - true: To allow provisioning in such cases.
- Default: Assumes it is restricted.
Restore pipeline limit (restorePipelineLimit)
- Controls parallel restoration of non-catalog partitions.
- Set desired positive integer (default is 10).

Example config file:

TEXT

# Common group setting
# notCommonGroupFlag=true

# Source database provisioning
# allowSourceDBonSameInst=true

# Restore limits
restorePipelineLimit=10

Version: DB2 plugin v4.x and onwards

The DB2 plugin will ignore values for a parameter if the values do not fit the description below and will continue the operation with the default set of values for that particular parameter.

Configuration file: db2_plugin.conf (located in <Toolkit directory>/<Delphix_COMMON>/plugin/DB2_18f4ff11-b758-4bf2-9a37-719a22f5a4b8/>)

It contains two main sections:

plugin_custom_parameters: Handles database-specific configurations.
plugin_logging_parameters: Manages log configurations.

Key parameters

Common group (usersHaveCommonGroup)
- Controls permissions for directories.
- Set to True or False based on group sharing of the primary environment and instance users.
- Default: True.
Allow source database on same instance (allowSourceDbOnSameInstance)
- Set to true to allow VDB provisioning with matching source DB names.
- Default: false.
Restore pipeline limit (restorePipelineLimit)
- Configures parallel restoration limits. Default is 10.
Skip archive log validation (skipArchiveLogValidation)
- Opt to skip validation for quicker processing.
- Default: False.

Logging parameters

Set debug log levels (level): INFO (default) or DEBUG.
Define the maximum log file size (logFileSize): Default is 1 MB.
- Max setting: 10 MB
- When log files reach the size specified by the logFileSize parameter:
  - They may be archived, renamed, or deleted.
  - Any new log data will be directed to a new file in the original location.
Control log retention levels (retention): Default is 2.
- Users have the flexibility to adjust this value anywhere between 2 and 50. As an illustration, if the retention is adjusted to 4, the resulting log files will be organized as follows:
  - <DB Name>.diag.log: This is the active log file.
  - <DB Name>.diag.log.1: This is the most recent archived log file.
  - <DB Name>.diag.log.4: This stands as the oldest archived log file.
- The log sequence continues from the newest to the oldest, with the primary log file being the current one in use.

Example config file:

TEXT

[plugin_custom_parameters]
usersHaveCommonGroup=True
allowSourceDbOnSameInstance=False
restorePipelineLimit=10
skipArchiveLogValidation=False

[plugin_logging_parameters]
level=INFO
logFileSize=1
retention=2

Additional requirements

Instance user requirements

Instance owners must be added as environment users within the Data engine.
For HADR synced dSources, ensure the staging instance owner can read the database content.
- The staging instance owner must have "read" permissions for the ingested database content. This is essential because Delphix validates the database's integrity by querying its tables prior to every dSource snapshot.
When adding or removing a container, resync the dSource.
Database configurations like LOGPRIMARY, LOGSECOND, LOGARCHCOMPR1, and LOGARCHCOMPR2 should remain at their default values.

Database container requirements

All Db2 database container types are supported except for Db2 raw containers.
Avoid special characters in source database container paths to prevent parsing issues and potential failures.