Simplifying LDAP-based Oracle Name Service Record Management

As customer's Oracle database estate expands on premises and across all major clouds (Oracle OCI, Microsoft Azure, Amazon AWS, and Google Cloud), they often desire to centralize name service resolution into LDAP-based directory services in order to ensure accuracy of the connect strings used by client applications.  This is particularly important for use cases like database migrations or employing custom connect strings.  This further exponentiated by the adoption of Entra ID integration where additional TLS and Entra ID connect string properties are required.  In order to address this growing need, I wrote a simple script for managing name service records and published it to GitHub at https://github.com/oudlabs/manage_tns.  This blog post just summarizes the use cases that it covers.

Installation

To install, just download from GitHub to a linux host.

curl -so manage_tns.sh https://raw.githubusercontent.com/oudlabs/manage_tns/refs/heads/main/manage_tns.sh

Usage

To see usage, just run the script with help subcommand

manage_tns.sh help

Register Database

Use the "register" subcommand to register a database into the directory service.

manage_tns.sh.sh register -n <db_alias> [options]

Unregister Database

Use the "unregister" subcommand to remove a database entry from the directory service.

manage_tns.sh.sh unregister -n <db_alias> [options]

List Registered Databases

Use the "list" subcommand to list all registered database in the directory service.

manage_tns.sh.sh list [options]

Show Database Registration Details

Use the "show" subcommand to show the details of a specific database from the directory service.

manage_tns.sh.sh show -n <db_alias> [options]

Examples

Register a database with alias name mypdb to the directory service.

$ manage_tns.sh register -n pdb1 -h tns.example.com -p 10636 --dbhost cdb1.example.com --dbport 1521 --dbproto TCP --service pdb1
Directory Server: ldaps://tns.example.com:10636
User: Loging into directory as cn=eusadmin,ou=EUSAdmins,cn=oracleContext
Enter directory service TNS admin user's password: *********
Register database pdb1
Database registration completed successfully

Register a database that includes TLS encryption and Entra ID integration details into the directory service.

manage_tns.sh register -n pdb2 -h tns.example.com -p 10636 --dbhost cdb1.example.com --dbport 2484 --dbproto TCPS --service pdb2.example.com --method interactive --tenantid 7f4c6e3e-a1e0-43fe-14c5-c2f051a0a3a1 --clientid e5124a85-ac3e-14a4-f2ca-1ad635cf781a --serveruri "https://dbauthdemo.com/16736175-ca41-8f33-af0d-4616ade17621"
Directory Server: ldaps://tns.example.com:10636
User: Loging into directory as cn=eusadmin,ou=EUSAdmins,cn=oracleContext
Enter directory service TNS admin user's password: *********
Register database pdb2
Database registration completed successfully

Register a database with a custom connection string into the directory service.

manage_tns.sh register -n rac1 --dbhost rac1.example.com -c "(DESCRIPTION=(CONNECT_TIMEOUT=90)(RETRY_COUNT=50)(RETRY_DELAY=3)(TRANSPORT_CONNECT_TIMEOUT=3)(ADDRESS_LIST=(LOAD_BALANCE=on)(ADDRESS=(PROTOCOL=TCP)(HOST=racnode1.example.com)(PORT=1521)))(ADDRESS_LIST=(LOAD_BALANCE=on)(ADDRESS=(PROTOCOL=TCP)(HOST=racnode2.example.com)(PORT=1521)))(ADDRESS_LIST=(LOAD_BALANCE=on)(ADDRESS=(PROTOCOL=TCP)(HOST=racnode3.example.com)(PORT=1521)))(CONNECT_DATA=(SERVICE_NAME=rac1)))"
Directory Server: ldaps://tns1.example.com:10636
User: Loging into directory as cn=eusadmin,ou=EUSAdmins,cn=oracleContext
Enter directory service TNS admin user's password: *********
Register database rac1
Database registration completed successfully

List all databases registered in the directory service.

$ manage_tns.sh list
Directory Server: ldaps://tns1.example.com:10636
User: Loging into directory service anonymously
List registered databases

cn=pdb1,cn=OracleContext,dc=example,dc=com
orclNetDescString: (DESCRIPTION=(ADDRESS=(PROTOCOL=TCP)(HOST=cdb1.example.com)(PORT=1521))(CONNECT_DATA=(SERVER=DEDICATED)(SERVICE_NAME=pdb1)))

cn=pdb2,cn=OracleContext,dc=example,dc=com
orclNetDescString: (DESCRIPTION=(ADDRESS=(PROTOCOL=TCPS)(HOST=cdb1.example.com)(PORT=2484))(SECURITY=(SSL_SERVER_DN_MATCH=TRUE)(WALLET_LOCATION=SYSTEM)(TOKEN_AUTH=AZURE_INTERACTIVE)(TENANT_ID=7f4c6e3e-a1e0-43fe-14c5-c2f051a0a3a1)(AZURE_DB_APP_ID_URI=https://dbauthdemo.com/16736175-ca41-8f33-af0d-4616ade17621)(CLIENT_ID=e5124a85-ac3e-14a4-f2ca-1ad635cf781a))(CONNECT_DATA=(SERVER=DEDICATED)(SERVICE_NAME=pdb2)))

cn=rac1,cn=OracleContext,dc=example,dc=com
orclNetDescString: (DESCRIPTION=(CONNECT_TIMEOUT=90)(RETRY_COUNT=50)(RETRY_DELAY=3)(TRANSPORT_CONNECT_TIMEOUT=3)(ADDRESS_LIST=(LOAD_BALANCE=on)(ADDRESS=(PROTOCOL=TCP)(HOST=racnode1.example.com)(PORT=1521)))(ADDRESS_LIST=(LOAD_BALANCE=on)(ADDRESS=(PROTOCOL=TCP)(HOST=racnode2.example.com)(PORT=1521)))(ADDRESS_LIST=(LOAD_BALANCE=on)(ADDRESS=(PROTOCOL=TCP)(HOST=racnode3.example.com)(PORT=1521)))(CONNECT_DATA=(SERVICE_NAME=rac1)))

Show the details of one of the registered databases.

$ manage_tns.sh show -n pdb1
Directory Server: ldaps://tns1.example.com:10636
User: Loging into directory service anonymously
Show database pdb1
dn: cn=pdb1,cn=OracleContext,dc=example,dc=com
cn: pdb1
objectClass: orclApplicationEntity
objectClass: orclDBServer
objectClass: orclService
objectClass: top
objectClass: orclDBServer_92
orclDBGlobalName: pdb1
orclNetDescName: 000:cn=DESCRIPTION_0
orclNetDescString: (DESCRIPTION=(ADDRESS=(PROTOCOL=TCP)(HOST=cdb1.example.com)(PORT=1521))(CONNECT_DATA=(SERVER=DEDICATED)(SERVICE_NAME=pdb1)))
orclOracleHome: /dbhome_1
orclServiceType: DB
orclSid: pdb1
orclSystemName: cdb1.example.com
orclVersion: 121000

Show the connect string of a database entry.

$ manage_tns.sh showcs -n pdb2
Directory Server: ldaps://tns1.example.com:10636
User: Loging into directory service anonymously
Show connect string of database pdb2
(DESCRIPTION=
         (ADDRESS=(PROTOCOL=TCPS)(HOST=cdb1.example.com)(PORT=2484))
         (SECURITY=
            (SSL_SERVER_DN_MATCH=TRUE)
            (WALLET_LOCATION=SYSTEM)
            (TOKEN_AUTH=AZURE_INTERACTIVE)
            (TENANT_ID=7f4c6e3e-a1e0-43fe-14c5-c2f051a0a3a1)
            (AZURE_DB_APP_ID_URI=https://dbauthdemo.com/16736175-ca41-8f33-af0d-4616ade17621)
            (CLIENT_ID=e5124a85-ac3e-14a4-f2ca-1ad635cf781a))
      (CONNECT_DATA=
         (SERVER=DEDICATED)
         (SERVICE_NAME=pdb2)))

Unregister a database entry from the directory service.

$ manage_tns.sh unregister -n pdb1
Directory Server: ldaps://tns1.example.com:10636
User: Loging into directory as cn=eusadmin,ou=EUSAdmins,cn=oracleContext
Enter directory service TNS admin user's password: *********
Unregister database pdb1
Database unregistration completed successfully

That concludes this blog post. 

I hope that you found it useful and informative.

Blessings!