Small Oracle TNS Service and Connect Test Tool

• connect to a given service using real connect method.
• Uses given credentials or default to raise an ORA-1017 error
• Connect via TCPS using a wallet/sqlnet.ora, the same way sqlplus does
• List and search TNS entries from tnsnames.ora and LDAP
• Check TNS service connectivity via TCP (and optionally a real database login)
• Port check all addresses of a service, including RAC VIPs
• RAC address resolution via DNS SRV records or racinfo.ini
• Service detail queries: address list, JDBC connection string, raw TNS descriptor
• LDAP TNS entry management (read, write, clear) via OpenLDAP with OID schema
• Configurable via YAML config file, environment variables, or CLI flags
• Addon scripts: dbhost, gotodb, tnslookup

• Installation
• Configuration
  • DB test user
  • RAC address info
  • TCPS / Wallet connections
• list — List TNS entries
• service check — Check TNS entries
• service portcheck — Port check
• service info — Service details
  • service info ports
  • service info jdbc
  • service info tns
• ldap — LDAP TNS entries
  • ldap read
  • ldap write
  • ldap clear
• Addon scripts
• Global flags
• version

Download the latest release binaries from Github or install with Go:

go install github.com/tommi2day/tnscli@latest

Settings are resolved in this order (later sources override earlier ones):

1. YAML config file — searched in order, first found wins:
   • ./tnscli.yaml (current directory)
   • $HOME/.config/tnscli.yaml
   • $HOME/etc/tnscli.yaml
   • /etc/tnscli.yaml
   • or set explicitly with --config / -c
2. Environment variables — prefix TNSCLI_, dots replaced by underscores (e.g. TNSCLI_LDAP_HOST)
3. CLI flags

CAUTION: Do not use anonymous checks for permanent monitoring. Some security analysis systems treat frequent anonymous connect attempts as a brute-force attack. Instead, set TNSCLI_USER and TNSCLI_PASSWORD env vars or use --user / --password flags in the service check command. The user only needs a connect privilege.

Replace c##tcheck, tcheck, and <MyCheckPassword> with your own values.

• Common user in CDB$ROOT:

  alter session set container=cdb$root;
  create user c##tcheck identified by "<MyCheckPassword>"
      default tablespace users temporary tablespace temp
      account unlock container=all;
  grant connect to c##tcheck container=all;
  alter user c##tcheck default role all container=all;

• Traditional (non-CDB) user:

  create user tcheck identified by "<MyCheckPassword>"
      default tablespace users temporary tablespace temp
      account unlock;
  grant connect to tcheck;
  alter user tcheck default role all;

• Export credentials to the environment:

  export TNSCLI_USER="c##tcheck"
  export TNSCLI_PASSWORD="<MyCheckPassword>"

RAC address details can be provided via DNS SRV records or a racinfo.ini file placed in $TNS_ADMIN.

• DNS SRV format:

  _myrac._tcp.rac.lan.  IN SRV 10 5 1521 myrac.rac.lan.
  _myrac._tcp.rac.lan.  IN SRV 10 5 1521 vip1.rac.lan.
  _myrac._tcp.rac.lan.  IN SRV 10 5 1521 vip2.rac.lan.
  _myrac._tcp.rac.lan.  IN SRV 10 5 1521 vip3.rac.lan.
  

• racinfo.ini format ($TNS_ADMIN/racinfo.ini):

  [MYRAC.RAC.LAN]
  scan=myrac.rac.lan:1521
  vip1=vip1.rac.lan:1521
  vip2=vip2.rac.lan:1521
  vip3=vip3.rac.lan:1521

tnscli resolves wallet and SSL settings from sqlnet.ora in the directory of the active tnsnames.ora (i.e. via $TNS_ADMIN), the same way sqlplus does. No extra flags are needed for a normal TCPS setup — just a TNS entry using PROTOCOL=TCPS and a WALLET_LOCATION in sqlnet.ora:

# tnsnames.ora
XE.local=(DESCRIPTION=
  (ADDRESS_LIST=(ADDRESS=(PROTOCOL=TCPS)(HOST=dbhost.local)(PORT=2484)))
  (CONNECT_DATA=(SERVER=DEDICATED)(SERVICE_NAME=XEPDB1)))

# sqlnet.ora
WALLET_LOCATION =
  (SOURCE =
    (METHOD = FILE)
    (METHOD_DATA =
      (DIRECTORY = /path/to/wallet)
    )
  )
SSL_SERVER_DN_MATCH = YES

• Auto-login wallets (cwallet.sso, created e.g. with orapki wallet create -auto_login) need no password — matches typical production setups.
• Password-protected PKCS12 wallets (ewallet.p12) need --wallet-password on service check, or set TNSCLI_WALLET_PASSWORD.
• SSL_SERVER_DN_MATCH in sqlnet.ora controls certificate hostname verification, same meaning as in real sqlnet.ora.
• service info jdbc includes WALLET_LOCATION in the printed JDBC URL whenever a wallet is configured.

tnscli list [flags]

Lists all TNS aliases found in the configured tnsnames.ora, or searches for a specific alias.

Examples:

# List all alias names
tnscli list -f test/testdata/connect.ora

# List entries with full descriptor
tnscli list --complete -f test/testdata/connect.ora

# Search for a specific alias
tnscli list --search mydb

tnscli service check [flags]

Performs a real TCP connect (and optionally a database login) to verify a TNS entry is reachable. Without --user/--password, connects with the built-in dummy credentials and expects an ORA-01017 login error — confirming the port is open without requiring a real account.

Examples:

# Check with dummy credentials — confirms port is open, expects ORA-01017
tnscli service check -s xe.local -f test/testdata/connect.ora --info

# Check with real credentials
tnscli service check -s xe.local -f test/testdata/connect.ora \
  --user system --password supersecret

# Use env vars for credentials
export TNSCLI_USER="c##tcheck"
export TNSCLI_PASSWORD="<MyCheckPassword>"
tnscli service check -s xe.local

# Print connected host:CDB:PDB (requires valid login)
tnscli service check -s XEPDB1.local -H -A test/testdata

# Check all entries in a file
tnscli service check --all -f test/testdata/connect.ora

# Check a TCPS entry using WALLET_LOCATION from sqlnet.ora
# (see "TCPS / Wallet connections" above)
tnscli service check -s xe.local -A /path/to/tns_admin

# Check a TCPS entry using a password-protected PKCS12 wallet
tnscli service check -s xe.local -A /path/to/tns_admin \
  --wallet-password "<WalletPassword>"

tnscli service portcheck [flags]

Performs a TCP connect test on all host:port addresses for a service. If RAC info is available (DNS SRV or racinfo.ini), all RAC addresses are checked as well.

Examples:

# Check if all ports for a service are open
tnscli service portcheck -s xe.local -A test/testdata

# Check with an alternative nameserver
tnscli service portcheck -s myrac -f test/testdata/rac.ora \
  --nameserver 127.0.0.1:53

tnscli service info <subcommand> [flags]

Parent command for service detail subcommands. All subcommands share these flags:

tnscli service info ports [flags]

Lists all host:port addresses for a service. Resolves RAC addresses from DNS SRV records or racinfo.ini when available.

Examples:

# List all addresses (with DNS SRV resolution)
tnscli service info ports -s myrac -f test/testdata/rac.ora --nameserver 127.0.0.1

# List addresses from racinfo.ini without DNS resolution
tnscli service info ports -s myrac -f test/testdata/rac.ora \
  -r test/testdata/racinfo.ini --nodns

tnscli service info jdbc [flags]

Prints the JDBC thin connection string for a service.

Examples:

tnscli service info jdbc -s xe -A test/testdata/
# jdbc:oracle:thin:@(DESCRIPTION=(...))

# with a WALLET_LOCATION configured in sqlnet.ora, it is appended automatically
tnscli service info jdbc -s xe.local -A /path/to/tns_admin
# jdbc:oracle:thin:@(DESCRIPTION=(...))?WALLET_LOCATION=/path/to/wallet

tnscli service info tns [flags]

Prints the raw TNS descriptor for a service alias.

Examples:

tnscli service info tns -s xe -A test/testdata/

tnscli ldap <subcommand> [flags]

Reads and writes TNS entries stored in an OpenLDAP server with OID schema extensions. All ldap subcommands share these connection flags:

tnscli ldap read [flags]

Reads TNS entries from the LDAP server and prints them to stdout or writes them to a file.

Examples:

# Read with config file and password from env
export TNSCLI_LDAP_BINDPASSWORD=admin
tnscli ldap read -T -I -c test/tnscli.yaml -A test/testdata

tnscli ldap write [flags]

Reads a tnsnames.ora file and writes the entries to the LDAP server.

Examples:

tnscli ldap write \
  --ldap.host=127.0.0.1 --ldap.port=1636 -T -I \
  --ldap.base="dc=oracle,dc=local" \
  --ldap.oraclectx="dc=oracle,dc=local" \
  --ldap.binddn="cn=admin,dc=oracle,dc=local" \
  --ldap.bindpassword=admin \
  --ldap.timeout=20 \
  --ldap.tnssource test/testdata/ldap_file_write.ora

tnscli ldap clear [flags]

Removes all TNS entries from the LDAP Oracle Context.

Examples:

tnscli ldap clear \
  --ldap.host=127.0.0.1 --ldap.port=1636 -T -I \
  --ldap.base="dc=oracle,dc=local" \
  --ldap.oraclectx="dc=oracle,dc=local" \
  --ldap.binddn="cn=admin,dc=oracle,dc=local" \
  --ldap.bindpassword=admin

Helper scripts are available in the /scripts directory.

Shortcut for tnscli service check <service> --dbhost. Connects to the given service and prints host:CDB:PDB from sys_context.

export TNSCLI_USER="c##tcheck"
export TNSCLI_PASSWORD="<MyCheckPassword>"
dbhost MYPDB1
# racnode1:MYCDB:PDB1

Uses dbhost to extract the server hostname and opens an SSH session to that host. Requires both tnscli and dbhost in PATH. Use ~/.ssh/config if the returned hostname is not directly resolvable:

Host racnode1
    HostName racnode1.rac.lan
    User oracle
    IdentityFile ~/.ssh/id_ora

gotodb MYPDB1
# oracle@racnode1 ~>

Shortcut for tnscli list --search <service> --complete.

tnslookup mypdb1
# Location: /etc/oracle/tnsnames.ora Line: 6
# MYPDB1.LOCAL=  (DESCRIPTION = ...)

These flags apply to every command:

tnscli version

Prints the build version, commit hash, and build date injected at release time.