Overview of TIM Command Line Interfaces (CLI).

Document ID : KB000010436
Last Modified Date : 14/02/2018
Show Technical Document Details
Introduction:

  The information about the TIM Command Line Interface is under-documented and in multiple sources. This presents this information for the first time in one place.

Environment:
All supported APM TIM or MTP-TIM releases.
Instructions:

Introduction

Configuring the TIM through the command line may become necessary when Web-UI access is not possible, or the TIM has been installed using the Command Line Installer on a vMTP. Note that the information below can also be used on regular and legacy TIM installations, however the installation path may be different.

The good thing about the TIM, is that almost everything can be visualized through command-line tools, and even configured through command line tools.

 

TIM CLI file locations

The TIM installer installs all required files for the TIM to work in one only common directory. By default, when using the Web-UI, some configuration files of the local HTTP Server will also be updated (see /etc/httpd/conf.d/ca-apm-tim.conf) - but this will be ignored here.

The main directories to look for are inside the installation path. Default on APM 10.x is: /opt/CA/APM/tim

The directories relevant for CLI manipulation are as below:

  • /bin: This directory will hold most binaries to manipulate the TIM configuration
  • /config: The configuration files will be in here.
  • /scripts: Script file to handle SSL Private keys (Upload)
  • /logs: Log directory. Usually used to check the logs and make sure everything runs fine.

TIM CLI Status view

To have a view on what the TIM is currently doing, use the "timmon" program located in the [TIM-INSTALL-DIR]/bin directory. This is basically the same output as the TIM Status menu option.

Run it without arguments to have real-time statistics on what the TIM is currently doing.

[caadmin@vmtp bin]$ pwd 
/opt/CA/APM/tim/bin
[caadmin@vmtp bin]$ ./timmon

Output will refresh every second showing current status.

Pid 1904                                hub 
Updated: May 29 14:52:07                Memory: 20.94 MB (21954560 B) 
Tim CPU usage: 0.0%                     Workers: 2
CPU usage: 74.3% 57.0%
TranSets: 0                             TranUnits: 0
TranComps: 0                            SSL sessions: 0574
Queued login info items: 0              Queued raw events: 0
Out-of-order TCP bytes: 208,784         Login/session entries: 0
Statistics records: 0                   Stats records written: 0
Total packets: 1,108,341                Total short packets: 0
Total transets: 0                       Total tranunits: 0
Total trancomps: 0                      Total components: 9,051
Total SSL sessions: 0                   Java plug-in id: 0

This will tell us if the TIM actually, runs, what the overall CPU load is, and if it receives packets (and if configured, what transactions are detected, how many SSL Sessions are exist etc.

TIM Settings from the CLI

Tim settings are held in a small Berkeley db-file (setting-value pair) that can be accessed and modified using the  "configtool" program located in the [TIM-INSTALL-DIR]/bin directory. 
Once invoked, this program will notify the TIM that something has changed, so it re-reads the settings.

If a value is to be changed, the admin needs to be able to write the .db file, so when TIM is running as root, the configtool binary needs to be invoked by user root (sudo will also work).

configtool arguments

The "--help" option gives us an overview on what capabilities it has.

[caadmin@vmtp bin]$ ./configtool 
usage: ./configtool -f file -n                  # create a new database
      ./configtool -f file -g name             # get value
      ./configtool -f file [-F] -s name value  # set value
      ./configtool -f file [-F] -u name        # unset value
      ./configtool -f file -l                  # list all values
        -F (fast) says not to notify Tim of the change
          (has no effect unless the file is timsettings.db)

The TIM config-files are located in the [TIM-INSTALL-DIR]/config directory. Currently the following 3 files can be read and modified.

  • config/timmtpcommsettings.db:  TIM/MTP communication configuration values
  • config/timsettings.db: The actual TIM configuration file
  • config/timtesscommsettings.db: Tim Tess communication/timeout values

 

configtool read value

Read a value with: "./configtool -f config-file -g [Value]"

[caadmin@vmtp tim]$ pwd 
/opt/CA/APM/tim
[caadmin@vmtp tim]$ ./bin/configtool -f ./config/timsettings.db -g MaxLogSizeInMB
50

 

configtool list all values of a .db file

List all values default values as per a fresh installation.

[caadmin@vmtp tim]$ ./bin/configtool -f ./config/timsettings.db -l 
CaptureBufferSizeInMB = 60
DiskSpace/AgeOutFrequencyInSeconds = 600
DiskSpace/MinFreeDataSpaceInPercent = 25
DiskSpace/ReclaimDataSpaceInPercent = 10
MaxDefectRequestBodySize = 1024
MaxDefectResponseBodySize = 10000
MaxLogSizeInMB = 50
MaxMetaTagResponseBodySize = 2000
MaxTagResponseBodySize = 2000
MaxTranTimeSeconds = 1000
MonitorAlreadyOpenedConnections = 0
Parallel/UseWorkers = 1
ProxyForwardHeader =  
SetTimTime/.LastTimeMismatchEventTime = 1494604297
SetTimTime/MaxDiffInSeconds = 7
SetTimTime/TimeMismatchEventFrequencyInSeconds = 300
SiteMinder/AgentMinLifetimeInSeconds = 60
SiteMinder/AgentRestartDelayInSeconds = 60
SiteMinder/ProbeTimeoutInSeconds = 30
SiteMinder/RetryInSeconds = 60
SiteMinder/TimeoutInSeconds = 5
SiteMinder/TimeoutOffsetInMs = 100
SiteMinder/Trace = 0
SslSessionAgeOutCount = 100
SslSessionAgeOutSeconds = 300
TessCollectorIpAddr = 130.119.4.119
TessIpAddr = 130.119.4.119
TraceFilters/ClientIpAddr =  
TraceFilters/ClientIpAddrEnabled = 0
TraceFilters/LanguageTag = en-us,af*
TraceFilters/LanguageTagEnabled = 0
TraceFilters/ParamEnabled = 0
TraceFilters/ParamName = JSESSIONID
TraceFilters/ParamPattern = *
TraceFilters/ParamType = C
TransactionInspection/LanguageTag = en-us,af*
TransactionInspection/LanguageTagEnabled = 1
TransactionInspection/MaxFiles = 30
TransactionInspection/RefreshPeriod = 3
loginNameStripCharacters = \t \r\n

 

configtool change value in .db file

Changing a value can be done using the "-s" option followed by the variable name and the new value.

[caadmin@vmtp tim]$ pwd 
/opt/CA/APM/tim
[caadmin@vmtp tim]$ sudo ./bin/configtool -f ./config/timsettings.db -s MaxLogSizeInMB 50  
[caadmin@vmtp tim]$ ./bin/configtool -f ./config/timsettings.db -g MaxLogSizeInMB 
25

Note that after any configtool utilization using the "-s" option, the TIM is being told that a change has occurred so it loads the configuration again.

TIM Interface setup from the CLI

When using an MTP/vMTP - the vMTP/MTP UI will handle the TIM interface configuration.

For the Standalone TIM, apmpacket will be the application collecting data from a dedicated interface. However it will get its interface configuration from the TIM.

The  [TIM-INSTALL-DIR]/config/interfacefilter.xml will hold the information on the interface to collect data from. 
By default, the TIM will use eth1 as interface after installation, and this interface usually needs to be modified by the TIM Web-UI.
If the Web-UI is not used, change it manually in the interfacefilter.xml file.

 <?xml version="1.0" encoding="UTF-8"?>  
<!-- This file is generated automatically.  Do not edit. -->
<InterfaceFilterFile>
 <File>
   <FileName>Timestock Interface Filter File</FileName>
   <FileVersion>1.0</FileVersion>
 </File>
 <Interfaces>
   <Interface>
     <Name>eth0</Name>
   </Interface>
 </Interfaces>
</InterfaceFilterFile>

Changed the entry eth1 to whatever interface is required, and restart the TIM.

Note: After an upgrade, sometimes the interface settings are left blank. Please refere to the Knowledge base article for more details.

For example - changing the TIM to use eth1 and restarting it afterwards.

[caadmin@vmtp config]$ sudo service tim restart 
Restarting tim:                                            [  OK  ]
[caadmin@vmtp config]$
 

and check the apmpacket that it has been triggered by the TIM to change the interface.

File to check: /opt/CA/APM/apmpacket/logs/apmpacketlog.txt

Mon May 29 16:30:10 2017 89053   CommServer: received config request from client tim 
Mon May 29 16:30:10 2017 89053   ClientManager: adding client "tim"
Mon May 29 16:30:10 2017 89053   ClientManager: creating packet directory /opt/CA/APM/apmpacket/data/pcap/clients/tim
Mon May 29 16:30:10 2017 89053   ClientManager: client: tim
Mon May 29 16:30:10 2017 89053   ClientManager:  packet directory: /opt/CA/APM/apmpacket/data/pcap/clients/tim
Mon May 29 16:30:10 2017 89053   ClientManager:  configuration:
Mon May 29 16:30:10 2017 89053   ClientManager:  interfaces:
Mon May 29 16:30:10 2017 89053   ClientManager:   eth1
Mon May 29 16:30:10 2017 89053   ClientManager:  no server filters
Mon May 29 16:30:10 2017 89053   ClientManager:  no client filters
Mon May 29 16:30:10 2017 89053   ClientManager:  end of configuration
Mon May 29 16:30:10 2017 89053   ClientManager: #clients: 1
Mon May 29 16:30:10 2017 89053   ClientManager: writing client config file /opt/CA/APM/apmpacket/config/clients/tim.data
Mon May 29 16:30:10 2017 89053   NetworkManager: updating configuration
Mon May 29 16:30:10 2017 89053   DeviceCtl: "eth1": setting device status to "down"
Mon May 29 16:30:10 2017 89053   DeviceCtl: "eth1": setting device status to "up"
Mon May 29 16:30:10 2017 89053   DeviceCtl: ifup eth1:

 

CLI TIM Trace options / Filters

The TIM Trace options are usually required for troubleshooting the traffic and what the TIM does with it.

Trace options

The trace options are used to increase the verbosity of the TIM logs on specific things. Easiest is to invoke the TIM through the command port. The following table shows the possible trace options:

Argument
Description
tracestatsTrace statistics
tracedefectsTrace defects
tracesessionsandloginsTrace sessions and logins
tracetransetsTrace Business Transactions
tracetranunitsTrace Transactions
tracematchedtrancompsTrace Transaction Components
traceallcomponentsTrace HTTP components
traceparametersTrace HTTP parameters
traceflexcomponentsTrace Flex Components
traceconnectionsTrace connections
tracessldebugTrace SSL errors

These need to be put into the [TIM-INSTALL-DIR]/config/tim.options file, one per line as argument with a "-" in front.
A full trace file would look like this:

-tracestats 
-tracedefects
-tracesessionsandlogins
-tracetransets
-tracetranunits
-tracematchedtrancomps
-traceallcomponents
-traceparameters
-traceflexcomponents
-traceconnections
-tracessldebug

Once the trace options are selected, trigger TIM to reread the configuration.

Trace filters

The trace filters are stored in the regular [TIM-INSTALL-DIR]/config/timsettings.db file. This means that we can use the configtool (as previously described) to configure various filters.

For the examples, invoque the config-tool and append the example line: configtool -f timsettings.db -s TraceFilters/ClientIpaddr 10.0.3.2

Filter Type
Filters
configtool call (example)
Comment
by Client IP addressTraceFilters/ClientIpAddr = 10.0.3.2 
TraceFilters/ClientIpAddrEnabled = 0
-s TraceFilters/ClientIpAddr 10.0.3.2
-s TraceFilters/ClientIpAddrEnabled 1
It is required to explicitly enable the filter with the second line. 
1 enables the filter, 0 disables it
by Browser Language settingTraceFilters/LanguageTag = en-us,af* 
TraceFilters/LanguageTagEnabled = 0
-s TraceFilters/LanguageTag en-us,af* 
-s TraceFilters/LanguageTagEnabled 1
No need to escape the language tag etc. 
1 enables the filter, 0 disables it
by HTTP ParameterTraceFilters/ParamEnabled = 0 
TraceFilters/ParamName = JSESSIONID 
TraceFilters/ParamPattern = 1234567889 
TraceFilters/ParamType = C
-s TraceFilters/ParamName JSESSIONID
-s TraceFilters/ParamPattern 1234567889*
-s TraceFilters/ParamType C
-s TraceFilters/ParamEnabled 1
 
Parameter type is:
  • C = Cookie
  • Q = Query
  • P = Post
  • U = URL - the ParamName must be either Host, Path, or Port

In case an error shows up (Invalid configuration), it will be shown in in a line with tagged with Error.

[caadmin@localhost config]$ ../bin/configtool -f timsettings.db -l | grep Error
TraceFilters/ParamUrlNameError = Invalid URL parameter name "JSESSIONID".

 

Upload SSL PEM Private Keys from the CLI

Uploading a private key requires the following:

  • the IP Address of the WebServer this key is running/used on and visible from the TIM through the mirror traffic
  • the TIM connected to a TESS (Configured)

 

[root@localhost scripts]# pwd 
/opt/CA/APM/tim/scripts
[root@localhost scripts]# ./sslkey_upload.sh -iprange 10.135.47.55-10.135.47.55 -port 443 -keyfile ~caadmin/wilycemeu.ca.com.key.pem  
Enter Passphrase:*******


Input details:
##############
Webserver ip range:10.135.47.55-10.135.47.55
Webserver ip port:443
PEM key absolute path:/home/caadmin/wilycemeu.ca.com.key.pem
Delete PEM key after sucessfull upload?:no

Please verify the above input details. Press "y" to continue and "n" to exist? (y/n):y
/home/caadmin/wilycemeu.ca.com.key.pem uploading...
/home/caadmin/wilycemeu.ca.com.key.pem successfully uploaded!!!.

For options, call the script without any argument.

TIM Webserver Filters

WebServer filters are configured through the CEM/TESS Web-UI. Creating these manually through the CLI is possible, however each invocation of the CEM/TESS Web-UI related to filters would overwrite the local copy.

Java Plugins configuration

Java Plugins are uploaded and configured through the CEM/TESS Web-UI. Creating these manually through the CLI is possible, however each invocation of the CEM/TESS Web-UI related to JAVA Plugins would overwrite the local copy.

Additional Information:

Links to other relevant information