4.3 Automatically Collecting Diagnostic Data Using the Oracle Trace File Analyzer Collector

Manage Oracle Trace File Analyzer Collector daemon, diagnostic collections, and the collection repository.

In addition, add hosts to the Oracle Trace File Analyzer Collector configuration, modify default communication ports, and configure SSL protocol.

Topics:

• Managing the Oracle Trace File Analyzer Daemon
  Oracle Trace File Analyzer Collector runs out of init  on UNIX systems or init/upstart/systemd  on Linux systems so that Oracle Trace File Analyzer Collector starts automatically whenever a node starts.
• Viewing the Status and Configuration of Oracle Trace File Analyzer
  View the status of Oracle Trace File Analyzer across all the nodes in the cluster using either tfactl print status  or tfactl print config  commands.
• Configuring the Host
  You must have root or sudo access to tfactl to add hosts to Oracle Trace File Analyzer configuration.
• Configuring the Ports
  The Oracle Trace File Analyzer daemons in a cluster communicate securely over ports 5000 to 5005.
• Configuring SSL and SSL Certificates
  View and restrict SSL/TLS protocols. Configure Oracle Trace File Analyzer to use self-signed or CA-signed certificate.
• Managing Collections
  Manage directories configured in Oracle Trace File Analyzer and diagnostic collections.
• Managing the Repository
  Oracle Trace File Analyzer stores all diagnostic collections in the repository.

4.3.1 Managing the Oracle Trace File Analyzer Daemon

Oracle Trace File Analyzer Collector runs out of init  on UNIX systems or init/upstart/systemd  on Linux systems so that Oracle Trace File Analyzer Collector starts automatically whenever a node starts.

To manage Oracle Trace File Analyzer daemon:

The init  control file /etc/init.d/init.tfa  is platform dependant.

1. To manually start or stop Oracle Trace File Analyzer:

   • tfactl start: Starts the Oracle Trace File Analyzer daemon

   • tfactl stop: Stops the Oracle Trace File Analyzer daemon

   If the Oracle Trace File Analyzer daemon fails, then the operating system restarts the daemon automatically.

2. To enable or disable automatic restarting of the Oracle Trace File Analyzer daemon:

   • tfactl disable: Disables automatic restarting of the Oracle Trace File Analyzer daemon.

   • tfactl enable: Enables automatic restarting of the Oracle Trace File Analyzer daemon.

4.3.2 Viewing the Status and Configuration of Oracle Trace File Analyzer

View the status of Oracle Trace File Analyzer across all the nodes in the cluster using either tfactl print status  or tfactl print config  commands.

To view the status and configuration settings of Oracle Trace File Analyzer:

1. To view the status of Oracle Trace File Analyzer all nodes in the cluster:

   tfactl print status

   For example:

   $ tfactl print status
   .---------------------------------------------------------------------------------------------.
   | Host  | Status of TFA | PID   | Port | Version    | Build ID             | Inventory Status |
   +-------+---------------+-------+------+------------+----------------------+------------------+
   | node1 | RUNNING       | 29591 | 5000 | 12.2.1.0.0 | 12210020160810105317 | COMPLETE         |
   | node2 | RUNNING       | 34738 | 5000 | 12.2.1.0.0 | 12210020160810105317 | COMPLETE         |
   '-------+---------------+-------+------+------------+----------------------+------------------'
   

   Displays the status of Oracle Trace File Analyzer across all nodes in the cluster, and also displays the Oracle Trace File Analyzer version and the port on which it is running.

2. To view configuration settings of Oracle Trace File Analyzer:

   tfactl print config

   For example:

   $ tfactl print config
   .------------------------------------------------------------------------------------.
   |                                     node1                                          |
   +-----------------------------------------------------------------------+------------+
   | Configuration Parameter                                               | Value      |
   +-----------------------------------------------------------------------+------------+
   | TFA Version                                                           | 12.2.1.0.0 |
   | Java Version                                                          | 1.8        |
   | Public IP Network                                                     | true       |
   | Automatic Diagnostic Collection                                       | true       |
   | Alert Log Scan                                                        | true       |
   | Disk Usage Monitor                                                    | true       |
   | Managelogs Auto Purge                                                 | false      |
   | Trimming of files during diagcollection                               | true       |
   | Inventory Trace level                                                 | 1          |
   | Collection Trace level                                                | 1          |
   | Scan Trace level                                                      | 1          |
   | Other Trace level                                                     | 1          |
   | Repository current size (MB)                                          | 447        |
   | Repository maximum size (MB)                                          | 10240      |
   | Max Size of TFA Log (MB)                                              | 50         |
   | Max Number of TFA Logs                                                | 10         |
   | Max Size of Core File (MB)                                            | 20         |
   | Max Collection Size of Core Files (MB)                                | 200        |
   | Minimum Free Space to enable Alert Log Scan (MB)                      | 500        |
   | Time interval between consecutive Disk Usage Snapshot(minutes)        | 60         |
   | Time interval between consecutive Managelogs Auto Purge(minutes)      | 60         |
   | Logs older than the time period will be auto purged(days[d]|hours[h]) | 30d        |
   | Automatic Purging                                                     | true       |
   | Age of Purging Collections (Hours)                                    | 12         |
   | TFA IPS Pool Size                                                     | 5          |
   '-----------------------------------------------------------------------+------------'
   

4.3.3 Configuring the Host

You must have root or sudo access to tfactl to add hosts to Oracle Trace File Analyzer configuration.

To add, remove, and replace SSL certificates:

1. To view the list of current hosts in the Oracle Trace File Analyzer configuration:

   tfactl print hosts

2. To add a host to the Oracle Trace File Analyzer configuration for the first time:
   1. If necessary, install and start Oracle Trace File Analyzer on the new host.
   2. From the existing host, synchronize authentication certificates for all hosts by running:

      tfactl syncnodes

      If needed, then Oracle Trace File Analyzer displays the current node list it is aware of and prompts you to update this node list.

   3. Select Y, and then enter the name of the new host.

      Oracle Trace File Analyzer contacts Oracle Trace File Analyzer on the new host to synchronize certificates and add each other to their respective hosts lists.

3. To remove a host:

   tfactl host remove host

4. To add a host and the certificates that are already synchronized:

   tfactl host add host

   Oracle Trace File Analyzer generates self-signed SSL certificates during install. Replace those certificates with one of the following:

   • Personal self-signed certificate

   • CA-signed certificate

4.3.4 Configuring the Ports

The Oracle Trace File Analyzer daemons in a cluster communicate securely over ports 5000 to 5005.

If the port range is not available on your system, then replace it with the ports available on your system.

The $TFA_HOME/internal/usableports.txt  file looks as follows:

$ cat $TFA_HOME/internal/usableports.txt
5000
5001
5002
5003
5004
5005

To change the ports:

1. Stop Oracle Trace File Analyzer on all nodes:

   tfactl stop

2. Edit the usableports.txt file to replace the ports.
3. Replicate the usableports.txt changes to all cluster nodes.
4. Remove the $TFA_HOME/internal/port.txt file on all nodes.
5. Start Oracle Trace File Analyzer on all nodes:

   tfactl start

4.3.5 Configuring SSL and SSL Certificates

View and restrict SSL/TLS protocols. Configure Oracle Trace File Analyzer to use self-signed or CA-signed certificate.

Topics:

• Configuring SSL/TLS Protocols
  The Oracle Trace File Analyzer daemons in a cluster communicate securely using the SSL/TLS protocols.
• Configuring Self-Signed Certificates
  Use Java keytool to replace self-signed SSL certificates with personal self-signed certificates.
• Configuring CA-Signed Certificates
  Use Java keytool and openssl to replace self-signed SSL certificates with the Certificate Authority (CA) signed certificates.

4.3.5.1 Configuring SSL/TLS Protocols

The Oracle Trace File Analyzer daemons in a cluster communicate securely using the SSL/TLS protocols.

The SSL protocols available for use by Oracle Trace File Analyzer are:

• TLSv1.2

• TLCv1.1

• TLSv1

Oracle Trace File Analyzer always restricts use of older the protocols SSLv3 and SSLv2Hello.

To view and restrict protocols:

1. To view the available and restricted protocols:

   tfactl print protocols

   For example:

   $ tfactl print protocols
   .---------------------------------------.
   |                 node1                 |
   +---------------------------------------+
   | Protocols                             |
   +---------------------------------------+
   | Available : [TLSv1, TLSv1.2, TLSv1.1] |
   | Restricted : [SSLv3, SSLv2Hello]      |
   '---------------------------------------'
   

2. To restrict the use of certain protocols:

   tfactl restrictprotocol [-force] protocol

   For example:

   $ tfactl restrictprotocol TLSv1

4.3.5.2 Configuring Self-Signed Certificates

Use Java keytool to replace self-signed SSL certificates with personal self-signed certificates.

To configure Oracle Trace File Analyzer to use self-signed certificates:

1. Create a private key and keystore file containing the self-signed certificate for the server:

   $ keytool -genkey -alias server_full -keyalg RSA -keysize 2048 -validity 18263 -keystore myserver.jks

2. Create a private key and keystore file containing the private key and self signed-certificate for the client:

   $ keytool -genkey -alias client_full -keyalg RSA -keysize 2048 -validity 18263 -keystore myclient.jks

3. Export the server public key certificate from the server keystore:

   $ keytool -export -alias server_full -file myserver_pub.crt -keystore myserver.jks -storepass password

4. Export the client public key certificate from the server keystore:

   $ keytool -export -alias client_full -file myclient_pub.crt -keystore myclient.jks -storepass password

5. Import the server public key certificate into the client keystore:

   $ keytool -import -alias server_pub -file myserver_pub.crt -keystore myclient.jks -storepass password

6. Import the client public key certificate into the server keystore:

   $ keytool -import -alias client_pub -file myclient_pub.crt  -keystore myserver.jks -storepass password

7. Restrict the permissions on the keystores to root  read-only.

   $ chmod 400 myclient.jks myserver.jks

8. Copy the keystores (jks files) to each node.
9. Configure Oracle Trace File Analyzer to use the new certificates:

   $ tfactl set sslconfig

10. Restart the Oracle Trace File Analyzer process to start using new certificates:

    $ tfactl stop 
    $ tfactl start

4.3.5.3 Configuring CA-Signed Certificates

Use Java keytool and openssl to replace self-signed SSL certificates with the Certificate Authority (CA) signed certificates.

To configure Oracle Trace File Analyzer to use CA-signed certificates:

1. Create a private key for the server request:

   $ openssl genrsa -aes256 -out myserver.key 2048

2. Create a private key for the client request:

   $ openssl genrsa -aes256 -out myclient.key 2048

3. Create a Certificate Signing Request (CSR) for the server:

   $ openssl req -key myserver.key -new -sha256 -out myserver.csr

4. Create a Certificate Signing Request (CSR) for the client:

   $ openssl req -key myclient.key -new -sha256 -out myclient.csr

5. Send the resulting CSR for the client and the server to the relevant signing authority.

   The signing authority sends back the signed certificates:

   • myserver.cert

   • myclient.cert

   • CA root certificate

6. Convert the certificates to JKS format for the server and the client:

   $ openssl pkcs12 -export -out serverCert.pkcs12 -in myserver.cert -inkey myserver.key

   $ keytool -v -importkeystore -srckeystore serverCert.pkcs12 -srcstoretype PKCS12 -destkeystore myserver.jks -deststoretype JKS

   $ openssl pkcs12 -export -out clientCert.pkcs12 -in myclient.cert -inkey myclient.key

   $ keytool -v -importkeystore -srckeystore clientCert.pkcs12 -srcstoretype PKCS12 -destkeystore myclient.jks -deststoretype JKS

7. Import the server public key into to the client jks file:

   $ keytool -import -v -alias server-ca -file myserver.cert -keystore myclient.jks

8. Import the client public key to the server jks file:

   $ keytool -import -v -alias client-ca -file myclient.cert -keystore myserver.jks

9. Import the CA root certificate from the signing authority into the Oracle Trace File Analyzer server certificate:

   $ keytool -importcert -trustcacerts -alias inter -file caroot.cert -keystore myserver.jks

10. Restrict the permissions on the keystores to root  read-only:

    $ chmod 400 myclient.jks myserver.jks

11. Copy the keystores (jks files) to each node.
12. Configure Oracle Trace File Analyzer to use the new certificates:

    $ tfactl set sslconfig

13. Restart the Oracle Trace File Analyzer process to start using the new certificates.

    $ tfactl stop 
    $ tfactl start

4.3.6 Managing Collections

Manage directories configured in Oracle Trace File Analyzer and diagnostic collections.

Topics:

• Including Directories
  Add directories to the Oracle Trace File Analyzer configuration to include the directories in diagnostic collections.
• Managing the Size of Collections
  Use the Oracle Trace File Analyzer configuration options trimfiles, maxcorefilesize, maxcorecollectionsize, and diagcollect -nocores to reduce the size of collections.

4.3.6.1 Including Directories

Add directories to the Oracle Trace File Analyzer configuration to include the directories in diagnostic collections.

Oracle Trace File Analyzer then stores diagnostic collection metadata about the:

• Directory

• Subdirectories

• Files in the directory and all sub directories

All Oracle Trace File Analyzer users can add directories they have read access to.

To manage directories:

1. To view the current directories configured in Oracle Trace File Analyzer

   tfactl print directories [ -node all | local | n1,n2,... ] 
   [ -comp component_name1,component_name2,.. ] 
   [ -policy  exclusions | noexclusions ] 
   [ -permission public | private ]

2. To add directories:

   tfactl directory add dir 
   [ -public ] 
   [ -exclusions | -noexclusions | -collectall ] 
   [ -node all | n1,n2,... ]

3. To remove a directory from being collected:

   tfactl directory remove dir [ -node all | n1,n2,... ]

4.3.6.2 Managing the Size of Collections

Use the Oracle Trace File Analyzer configuration options trimfiles, maxcorefilesize, maxcorecollectionsize, and diagcollect -nocores to reduce the size of collections.

To manage the size of collections:

1. To trim files during diagnostic collection:

   tfactl set trimfiles=ON|OFF

   • When set to ON (default), Oracle Trace File Analyzer trims files to include data around the time of the event

   • When set to OFF, any file that was written to at the time of the event is collected in its entirety

2. To set the maximum size of core file to n MB (default 20 MB):

   tfactl set maxcorefilesize=n

   Oracle Trace File Analyzer skips core files that are greater than maxcorefilesize.

3. To set the maximum collection size of core files to n MB (default 200 MB):

   tfactl set maxcorecollectionsize=n

   Oracle Trace File Analyzer skips collecting core files after maxcorecollectionsize is reached.

4. To prevent the collection of core files with diagnostic collections:

   tfactl diagcollect -nocores

4.3.7 Managing the Repository

Oracle Trace File Analyzer stores all diagnostic collections in the repository.

The repository size is the maximum space Oracle Trace File Analyzer is able to use on disk to store collections.

Topics:

• Purging the Repository Automatically
  
• Purging the Repository Manually
  

4.3.7.1 Purging the Repository Automatically

Oracle Trace File Analyzer closes the repository, if:

• Free space in TFA_HOME  is less than 100 MB, also stops indexing

• Free space in ORACLE_BASE  is less than 100 MB, also stops indexing

• Free space in the repository is less than 1 GB

• Current size of the repository is greater than the repository max size (reposizeMB)

The Oracle Trace File Analyzer daemon monitors and automatically purges the repository when the free space falls below 1 GB or before closing the repository. Purging removes collections from largest size through to smallest until the repository has enough space to open.

Oracle Trace File Analyzer automatically purges only the collections that are older than minagetopurge. By default, minagetopurge  is 12 hours.

To purge the repository automatically

1. To change the minimum age to purge:

   set minagetopurge=number of hours

   For example:

   $ tfactl set minagetopurge=48

   Purging the repository automatically is enabled by default.

2. To disable or enable automatic purging:

   set autopurge=ON|OFF

   For example:

   $ tfactl set autopurge=ON

3. To change the location of the repository:

   set repositorydir=dir

   For example:

   $ tfactl set repositorydir=/opt/mypath

4. To change the size of the repository:

   set reposizeMB

   For example:

   $ tfactl set reposizeMB=20480

4.3.7.2 Purging the Repository Manually

To purge the repository manually:

1. To view the status of the Oracle Trace File Analyzer repository:

   tfactl print repository

2. To view statistics about collections:

   tfactl print collections

3. To manually purge collections that are older than a specific time:

   tfactl purge -older number[h|d] [-force]