Command-Line Tools

ORATRACK (oratrack.jar) is a command-line oriented tool for generating inventories for Oracle database instances. You may target a single database by command-line arguments, target many databases by a connections file, or let it discover and inventory local and remote databases on its own.

The command-line arguments are passed to ORATRACK as name-value pairs. Flags are set by their name.

Usage

java –jar oratrack.jar [-o <argument-name>=<value>]...

Table of Arguments and Flags

Name

Type

Description

asSysDba

BOOLEAN

Connect as SYSDBA.

true	The connection is established with SYS role.

false

The connection is established without giving the SYS role.

auth

BOOLEAN

Specifies whether the set of targets collected is written to OracleConnections.xml. This argument defaults to true.

true Write to OracleConnections.xml.

false Do not write.

authPath

TEXT

Specify the targets filename. By default a the current working directory is searched for a file called OracleConnections.xml. This file will be created when it is not present and argument auth is set to true.

auto

OPTION

Turns on discovery of local configuration files in order to discover targets known to the local machine.

local Ignore remote targets.

all Use all targets found.

checkCertificates

BOOLEAN

Enable / disable checking the host certificate when uploading using HTTPS. Enabled by default.

csv

BOOLEAN

Set output mode.

true Write results as CSV files.

false Write results as NDI file.

dbhost

TEXT

Specifies a target address or a pattern to match target addresses, not specified by command-line.

A concrete hostname.

localhost

Special hostname, indicates using the local machine.

127.0.0.1

Special IP address, indicates using the local machine.

<ip-address>

A concrete IP address.

Use targets with host addresses that match this expression, only.

debug

BOOLEAN

Controls the log level.

true Log debug messages.

false Suppress debug messages.

deviceId

INTEGER

Sets the device ID. This is supposed to be used by Raynet's inventory / discovery agents, only.

discoverySource

OPTION

This argument is used in conjunction with argument auto and controls where to look for the home directory of a database.

The following values for the argument discoverySource may be may be combined in a comma seperated list. For example: discoverySource=oratab,files

environment

Scan the environment variables.

registry

Scan the windows registry or oratab file.

oratab

Look for and process the oratab file.

files

Scan scan the filesystem for configuration files.

domain

TEXT

Gives a value to put in the inventory file as domain.

encryption

OPTION

Specifies the encryption algorithm(s) to use as comma separated list of algorithms enclosed in brackets when specifying a target by command-line. Mind that different versions of ORATRACK support different sets of encryption algorithms. For example: RC4_40, AES128, AES192, 3DES112 etc.

encryption.level

OPTION

Specifies the encryption level, controlling the negotiation between client and server together with the parameter encryption. Valid values are REQUIRED, REQUESTED, REJECTED, or ACCEPTED.

encryptionKey

TEXT

Sets the encryption key that is used for encrypting and decrypting all credentials.

dfusScript

TEXT

Sets the optional Oracle DFUS script filename for running it by sqlplus.

If you set this argument and the file is not present, then this will cause the query to fail with an error.

If you do not set this argument then oratrack looks for a file called oracle.sql and runs it.

failedconnectionbehavior

OPTION

Sets the condition for reporting a failed connection by exit code.

ignore

Ignore failed connections.

all	Returns an error if all connections failed.

any	Returns an error if any connection fails.

help

FLAG

Show the usage hint and command-line argument list.

ignorenames

BOOLEAN

Ignore all service names or SIDs matching the semi-colon-separated regular expressions listed, here, during discovery. Default is CLRExtProc;EXTPROC;PLSExtProc.

ignoreOraDBCertificate

BOOLEAN

Ignores encountered SSL errors. The default value is false.

integrity

OPTION

Specifies the integrity algorithm(s) to use as comma separated list of algorithms enclosed in brackets when specifying a target by command-line. Currently supported: SHA1 or MD5.

integrity.level

OPTION

Specifies the integrity level controlling the negotiation between client and server together with the parameter integrity. Valid values are REQUIRED, REQUESTED, REJECTED, or ACCEPTED.

job

TEXT

Sets the job tag / ID. This is supposed to be used by Raynet's inventory / discovery agents only.

keyStorePath

TEXT

Specifies the file path to the keystore, which typically stores SSL/TLS client certificate and private key pairs. These certificates and keys are used for client authentication when connecting to Oracle databases.

keyStorePassword

TEXT

The password or passphrase required to access and decrypt the keystore.

listenerControl

BOOLEAN

Enable or disable querying the listener control status during discovery. Enabled by default.

mode

OPTION

Sets the program mode. This argument defaults to query.

encryptquery Read query.xml from the current working directory and write an encrypted copy named query.xml.enc to the current working directory.

test	Tries to connect to a target specified by command-line and returns the result as exit code.

query

Run the queries on the targets.

logfile

TEXT

Sets the filename for the log file.

orahome

TEXT

This argument is used in conjunction with the argument auto. When given oratrack will not search for the Oracle instance home directories but scan for configuration files in this directory only.

This argument also overrides the argument discoverySource.

oratab

TEXT

Specifies an oratab filename and overrides the discovery of that file. This argument conflicts with the argument tnsnames.

pass

TEXT

Specifies the password for connecting to a database.

path

TEXT

Sets the output directory.

plainQueries

TEXT

Format: <filename>[,<query name>][;...]

Specify additional text files with queries and an optional name for the result, where the last result is written to the output file.

Filename for the text file.

Optional name for the result (default is PlainQuery)

port

INTEGER

Specifies a target port number or a pattern to match target port numbers, which were not specified by command-line.

protocol

OPTION

The protocol to use. Supported values are tcp (default) and tcps

queryPath

TEXT

Specify the queries filename. By default the current working directory is searched for a file called query.xml.enc with fallback to query.xml

reportQueryError

BOOLEAN

Enabled to create an error report instead of a regular inventory on a failed query that is considered an error. Disabled by default.

true	Enable error report.

false

Disable error report.

reportStatus

BOOLEAN

Controls the connection status reporting.

true	On a failure / error creates an NDI file that reports this failure / error.

false Does not output an NDI for a failed connection.

reportStandbyDB

BOOLEAN

Controls the standby database reporting enabled by default.

true	Looking for indicators for a standby database for the target database.

false

Do not look for indicators for standby databases.

silent

BOOLEAN

Controls the output to the standard output channel.

true	Suppress logging to the standard output channel.

false

Allow logging to the standard output channel.

sname

TEXT

Format: <service name>|<SID>|<pattern>

Specifies a target service name or SID or a pattern to match target services, not specified by command-line.

<service name> A concrete service name.

<SID>

A concrete SID.

Use targets with service names that match this expression only.

sqlnet

TEXT

Specifies a sqlnet configuration filename and overrides discovery of that file.

tnsnames

TEXT

Specifies a tnsnames filename and overrides discovery of that file. This argument conflicts with argument oratab.

tnslistener

TEXT

Specifies a tnslistener configuration filename and overrides the discovery of that file. Discovery or explicit specification of this file is implied when argument auto is set to local.

trustStorePath

TEXT

Specifies the file path to the truststore, which contains trusted root certificates or public keys used to validate the authenticity of SSL/TLS server certificates during secure connections to Oracle databases.

trustStorePassword

TEXT

The password or passphrase required to access and decrypt the truststore,

upload

TEXT

Specifies the upload location’s URL for the output files. This contradicts argument csv with value true and argument path.

user

TEXT

Specifies the username for connecting to a database.

<username> The username

?	Indicates that the username is read from standard input during execution

Tip:

You cannot use the arguments path and upload together.The arguments tnsnames, tnslistener, sqlnet, and oratab are allowed in conjuction with argument auto, only.The argument csv=true will only produce output for query files with queries with attribute LMS="true".

Examples

1.Query single target by RVP

This is how the RayVentory Scan Engine UserUI will call oratrack in order to scan a single target.

-o dbhost=<host address> -o sname=<service name> -o port=<port number> -o authPath=<RVP UserUI path to OracleConnections.xml> -o user=<username> -o pass=<password> -o path=<RVP UserUI path to Oracle query results folder>

2. Test single target by RVP

This is how the RayVentory Scan Engine UserUI will call oratrack in order to test connection to a single target.

-o dbhost=<host address> -o sname=<service name> -o port=<port number> -o authPath=<RVP UserUI path to OracleConnections.xml> -o user=<username> -o pass=<password> -o mode=test

3. Query all target from a targets file given by RVP

This is how the RayVentory Scan Engine UserUI will call oratrack in order to scan all targets from RVP's targets file.

-o authPath=<RVP UserUI path to OracleConnections.xml> -o path=<RVP UserUI path to Oracle query results folder>

4. Scan all local targets found in the local configuration files using OS Authentication

Oratrack is installed on every machine that hosts Oracle databases and setup to be frequently run by a scheduler.

The user that runs oratrack is setup for OS Authentication with the targets. Instead of the argument path you can provide the argument upload

-o path=<output path> -o auto=local -o auth=false

5. Scan all targets found in the local configuration files using OS Authentication

This is an alternative to use case 4.

Oratrack is installed on a machine that knows several Oracle DBs and setups to be frequently run by a scheduler.

The user that runs oratrack is setup for OS Authentication with the targets.

-o path=<output path> -o auto=all -o auth=false

6. Scan all targets specified in a given tnsnames file with encryption and integrity options specified in a given sqlnet configuration file.

This is an alternative to use case 4.

Oratrack is installed on a machine that holds a tnsnames file and a sqlnet configuration file.

The user that runs oratrack is setup for OS Authentication with the targets.

-o path=<output path> -o auto=all -o auth=false -o tnsnames=<path to tnsnames file> -o sqlnet=<path to sqlnet configuration file>

Privileges

What privileges are needed depends on how ORATRACK is operated. For running queries against a database instance, the user that is passed to ORATRACK needs permissions to read certain system tables and views. What exactly is needed may change. The Raynet consultants can explain what permissions are needed and give you scripts for creating a user with the needed permissions. You may always use a privileged user like sys.

To make use of ORATRACK‘s database discovery capabilities, you need to run it as a user with permission to read certain configuration files like oratab, tnsnames.ora, listener.ora, and sqlnet.ora. Further, to run lsnrctl and read the Oracle databases‘ home directories.

Ports in Use

•1521 (default) for communication with an Oracle database via a TNS listener.