Skip to main content
Community Hub

Set up IBM Db2 for z/OS

TL;DR

Create a least-privilege Db2 for z/OS authorization ID and grant the catalog access Atlan needs to crawl metadata.

Your AI can read this via Docs MCPcurl -fsSL "https://docs.atlan.com/install-docs-mcp" | bashConnect
Who can do this?

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 12.1 license activated for your subsystem. Remote applications that connect to Db2 for z/OS from a non-mainframe system need a Db2 Connect license. Atlan connects with the IBM Db2 12.1 JDBC driver, which only accepts a Db2 Connect 12.1 license. An activation from an earlier license kit, such as 11.5, is rejected with ERRORCODE=-4230. 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 DDF command, 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​

The license requirement applies to every Db2 for z/OS version that the IBM Db2 12.1 JDBC driver supports, which is Db2 for z/OS 11 or later.

Ask your Db2 administrator to:

  1. Download the Db2 Connect 12.1 license activation kit from IBM Passport Advantage. If your IBM Subscription & Support is active, the 12.1 kit is normally available under your existing Db2 Connect entitlement.
  2. Run the activation program from the kit against your subsystem. For Db2 Connect Unlimited Edition for System z, this is the db2connectactivate utility.

If your subsystem already has an activation from an 11.5 or earlier kit, you still need to repeat the activation with the 12.1 kit. You don't need a new kit for fix pack or mod pack updates within 12.1.

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.

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.

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