Set up IBM Db2 for z/OS
Create a least-privilege Db2 for z/OS authorization ID and grant the catalog access Atlan needs to crawl metadata.
Setting up Db2 for z/OS involves your RACF security administrator, your Db2 administrator, and your z/OS systems programmer. You probably can't complete these steps yourself.
Atlan supports basic username and password authentication for fetching metadata from IBM Db2 for z/OS. Atlan only runs read-only SELECT queries against the Db2 system catalog - it never reads or modifies the data in your tables.
Prerequisites
Before you begin, make sure you have:
- A Db2 Connect license activated for your subsystem. Remote applications that connect to Db2 for z/OS from a non-mainframe system need a Db2 Connect license. Note the license version, such as 12.1 or 11.5.7: you select it when configuring the crawler. For details, see Activate license on your subsystem.
- An active Distributed Data Facility (DDF). DDF accepts the remote DRDA connections Atlan uses. Your Db2 operator can confirm it's started with the
-DISPLAY DDFcommand, which also reports the DRDA location name and listener port. - Network access from Atlan to the DDF listener port, which is 446 by default. Your site may use a different port for AT-TLS secured traffic.
- The DRDA location name of the subsystem you want to crawl. You provide this as the Location when configuring the crawler.
Activate license on your subsystem
Atlan supports Db2 Connect licenses of any version. When you configure the crawler, you select the license version activated on your subsystem in Db2 Connect license version on the z/OS subsystem, and Atlan connects with the matching IBM Db2 JDBC driver:
| Activated license | Select | JDBC driver Atlan uses |
|---|---|---|
| 12.1, any 12.1.x | 12.1 (any 12.1.x) (default) | IBM Db2 12.1 JDBC driver |
| 11.5.x, 11.1.x, 10.5.x, 10.1.x, or earlier | 11.5 or earlier (11.5.x, 11.1.x, 10.5.x, 10.1.x and older) | IBM Db2 11.5 JDBC driver |
Only the license version matters. Fix packs and mod packs within a version don't change the choice, and neither does the Db2 for z/OS version: both drivers connect to Db2 for z/OS 12 and 13.
If your subsystem doesn't have an activated Db2 Connect license yet, ask your Db2 administrator to:
- Download the Db2 Connect license activation kit from IBM Passport Advantage.
- Run the activation program from the kit against your subsystem. For Db2 Connect Unlimited Edition for System z, this is the
db2connectactivateutility.
Create authorization ID
Ask your RACF security administrator to create a dedicated user ID for Atlan. On z/OS, identities live in RACF rather than in Db2, so there's no SQL CREATE USER equivalent:
ADDUSER ATLANID PASSWORD(<password>) NAME('ATLAN METADATA CRAWLER')
- Replace
<password>with a strong password for the user ID. - Keep the user ID to eight characters or fewer, which is the RACF limit.
Authorize distributed access
Db2 for z/OS controls distributed DRDA access through RACF rather than through SQL. Ask your security administrator to permit the new user ID to the subsystem's distributed access profile in the DSNR resource class:
PERMIT <ssid>.DIST CLASS(DSNR) ID(ATLANID) ACCESS(READ)
SETROPTS RACLIST(DSNR) REFRESH
- Replace
<ssid>with your Db2 subsystem identifier.
Without this access, the subsystem rejects the connection before authentication completes.
Grant catalog privileges
Atlan reads database, schema, table, view, column, and routine metadata from the Db2 system catalog. Ask your Db2 administrator to run the following grants. No system authority such as SYSADM or DBADM is needed:
GRANT SELECT ON SYSIBM.SYSDUMMY1 TO ATLANID;
GRANT SELECT ON SYSIBM.SYSDATABASE TO ATLANID;
GRANT SELECT ON SYSIBM.SYSTABLES TO ATLANID;
GRANT SELECT ON SYSIBM.SYSCOLUMNS TO ATLANID;
GRANT SELECT ON SYSIBM.SYSFOREIGNKEYS TO ATLANID;
GRANT SELECT ON SYSIBM.SYSVIEWS TO ATLANID;
GRANT SELECT ON SYSIBM.SYSROUTINES TO ATLANID;
If a grant is missing, the crawl fails with SQLCODE -551 naming the object the authorization ID can't read.
If your site runs the RACF access control module, catalog access is managed through RACF profiles instead of Db2 GRANT statements. Ask your Db2 administrator which security model is active before you run these commands.
Prepare SSL truststore
If your subsystem requires SSL/TLS connections, you can either upload the server or CA certificate directly as an .arm or .pem file, or prepare a JKS or PKCS12 truststore that contains the CA certificate that signed your server's certificate:
keytool -import -alias db2zos -file <ca-certificate>.arm -keystore truststore.p12 -storetype PKCS12
- Replace
<ca-certificate>with the path to your CA certificate file.
If you select the 12.1 license version, the server certificate must include the hostname or IP address you enter when configuring the crawler. The IBM Db2 12.1 JDBC driver validates the hostname by default, so a certificate without it fails the SSL handshake. The IBM Db2 11.5 JDBC driver doesn't validate the hostname.
You provide the certificate or the truststore when configuring the crawler.
Next steps
Crawl IBM Db2 for z/OS assets: Configure and run the crawler to extract metadata from Db2 for z/OS