Traffic Sentinel : Help
Help Index Top > Report > Script

The Script page is used to edit and evaluate scripted queries.

Topics:

See Also:

What are scripts used for?

Scripts provide access to the traffic and topology databases. Scripts have many applications, including:

  1. Extracting data into a web-aware application such as Microsoft Excel.
  2. Extracting data into custom scripts written in other languages such as awk or perl.
  3. Creating specialized ad-hoc queries that are not supported by any of the Sentinel:Report>Query forms.
  4. Prototyping queries that will be used in new report templates.
Back to Top

How do I run a script?

To run a script, simply type or paste it into the Script form, then click Submit. If the query executes successfully, you will see the results, with the following options above:

Back to Top

How can I import data into Excel?

To load data into the cells of an Excel spreadsheet, follow these steps:

Note: If a password is required to access the Script page then you will have to provide login information when you run the query in Excel.

Back to Top

Can I run scripts directly from the command line?

For maximum efficiency and reliability, it is possible to execute scripts directly on the server (bypassing the web server). Log in to the server and create a file containing your script (script.js), then run the command:

/usr/local/inmsf/bin/query script.js

If you want to pass variables to the script then one or more -input arguments can be used. For example the the following command sets the variable interval to "last5minutes" and the variable truncate to "10" before invoking the script:

/usr/local/inmsf/bin/query -input "interval=last5minutes" -input "truncate=10" script.js

Back to Top

How can I write scripts of my own?

The scripting language is Javascript (version 1.6 with E4X). Describing the Javascript language is outside the scope of this document. If you need to learn more about Javascript, there are many books and web sites describing the language. There are a number of examples in the tutorial Scripting Queries.

The following extensions have been added to Javascript to support querying and reporting:

Back to Top

What functions does Query support?

The Query class is used to access the traffic database.

Class Methods

Instance Properties

Instance Methods

Usage:

The view property must be one of the database views:

The select property is is a comma separated list of fields defined in the view. Fields marked as Key will be used to group results.

The fields sourceaddress, destinationaddress are polymorphic string fields that will follow the highest protocol layer addresses of each flow. That means they can sometimes be MAC addresses if it was layer-2 traffic, or even IPX, IPv6, Appletalk or DecNet addresses if those protocols are running in your network. The fields sourceport, destinationport have the same polymorphic behavior, as do clientaddress, serveraddress, clientport and serverport.

In contrast, the fields ipsource, ipdestination, ipclient and ipserver are only ever set for IPv4 flows. Otherwise they are equal to null. If you are filtering using subnets (e.g. "ipsource=10.1.1.0/24,10.1.2.0/24") or ranges ("ipsource=10.1.1.1-10.1.1.23") then you should always use these fields rather than the polymorphic ones. Similarly, fields such as tcpsourceport, tcpdestinationport, udpsourceport, udpdestinationport are only set if that protocol layer was present.

The where property is a filter that will be applied during the query to select specific data. You can only filter on attributes that are keys in the selected view.

A basic filter expression consists of the name of an attribute, an operator and a set of comma separated values. The allowed operators are:

Expressions can be combined using brackets and the boolean operators:

The following examples illustrate typical where filters:

Note: The special zone EXTERNAL refers to addresses that aren't contained in any of the CIDRs specified using File > Configure.

WARNING Care should be taken if a value in a filter expression contains any of the following special characters: (, ), &, |, !, =, ~, ",', \, comma or space. If the value contains any of these characters then the whole value string can be enclosed in single or double quotes, or the special characters can be individually escaped with a \. The following examples show different ways of using the value "Research & Development" in filters:

Note: Special characters typically occur because they are used in Zone or Group names when configuring Traffic Sentinel (see File>Configure). Care should be taken when filtering on zone, group or path attributes.

The interval property describes the time period for the query.

There are a number of predefined intervals, including:

In addition, time intervals can be specified in the same format as the Unix at(1) command. If necessary the interval can be specified in the form start,stop where the interval runs from the start of the first inteval to the start of the second interval. The following examples demonstrate typical custom time intervals:

The resolution used to compute time intervals is determined by the highest resolution token. For example "midnight + 45 minutes" has a resolution of minute and will generate a 1 minute interval starting at 15 minutes past midnight and "now - 2hours" has a resolution of hour and will generate an interval that falls on an hour boundary and extends for 1 hour.

The optional group property is used when computing time series to specify the size of each time grouping within the overall query interval.

The group size can be specified either as a number of minutes, or using special tokens. The following examples show typical group values:

The optional sort property is used to specify a Value field defined in the view that will be used to sort the result.

The optional truncate property controls the number of result rows.

The optional nullsinkeys property can be set to true to allow null keys to be included in the result.

If a callback function is provided to the query.run() method then the callback will be invoked for each result row instead of adding the row to the table. Using a callback function is useful if you are making a query that would generate a very large number of result rows. Each row can be examined without using the memory required to create the result table. The following example uses a callback function to count the number of rows in the result:

var max = 0; query.run(function() {count++});

Back to Top

What functions does Network support?

The Network class is used to access network configuration data and address mappings.

Class Methods

Instance Properties

Instance Methods

Usage:

The path property is used to scope many of the functions. A path refers to the enterprise>site>zone>group>agent>interface hierarchy specified using File > Configure. Omitting enterprise and site names is allowed. In addition an agent or interface can be specified without providing the full path. The following examples show typical path values:

The functions network.agents() and network.intefaces() return an array of path values. Scripts will often iterate over the array, setting the network.path attribute to each of the paths in order to extract information about all the agents or interfaces in the network.

The *Map functions are typically used to lookup information on all the elements of a column in a Table. These functions take in an array of values and return an array of results. Often the result of a map function will be inserted back into the table as a new column. Some of the map functions (e.g. network.addressMap()) are one to many functions (i.e. they return an array of arrays as a result). Inserting the result of a one to many map function as a table column is likely to cause an error since arrays are not typically allowed as table cells (arrays are are allowed if the column type is string). The utility functions Network.countMap() and Network.uniqueMap() are provided convert an array of arrays into a simple array of values. Network.countMap() counts the number of entries in each sub-array and return an array of numbers. Network.uniqueMap() returns the value if it is unique (i.e. the sub-array only contains one entry) or null otherwise. Finally, the network.addressMap() function is unusual in that it operates in two directions; it will map each layer-2 (MAC) address to one or more layer-3 addresses (e.g. IP, Appletalk, etc.) and it will map each layer-3 address to one or more layer-2 addresses.

Note: interface, address, ipAddress, macAddress, asName, asNumber, cidr, protocol, protocolName, path, vendorName, countryName and countryCode "types" referred to in the function prototypes are all javascript strings, the different names are intended to clarify the form of the strings that needed. For example, a valid ipAddress would be "10.1.4.1".

Back to Top

What functions does SNMP support?

The SNMP class is used to query network devices using the SNMP protocol.

Class Methods

Instance Properties

Instance Methods

Usage:

Set the host and the oid properties for the SNMP object to be retrieved, e.g. snmp.oid = "1.3.6.1.2.1.1.4.0" is the OID for sysContact. The get() function will return the value of the object corresponding to the oid. The getnext() function will retrieve the next object in the SNMP MIB and set the oid, value and type properties correspondingly.

The useconfig property (true by default) determines whether the SNMP settings will be taken from the configuration (see File > Configure) or will be provided directly. If useconfig = true then the SNMP version and credential settings will only applied if there is no configuration value applicable to the host. Setting useconfig = false overrides this behavior and only the values set in the script will be used.

The authorization credentials that need to be provided depend on the version property. If version is set to "1" or "2c" then the community property will be used. If version is set to "3" then the username, authprotocol, authpassword and privpassword properties will be used.

The retryintervals property can be set to an array of retry delays (expressed in milliseconds). A value of [20,40,100] would allow an initial request, one retry if a reply was not received within 20ms of the initial request, a second retry if no reply was received within 40ms of the second request and the query would fail completely if no reply was received within 100ms of the third request.

Back to Top

What functions does Table support?

The Table class is used to represent Query results and is also used to add tabular data to a Report

Class Methods

Instance Properties

Instance Methods

Usage:

The following column types are defined:

The table print functions can optionally accept dateFormat and numberFormat arguments. The dateFormat string is described in formatdate and the numberFormat string is described in formatnumber. The width[] array in printFixed contains column widths in number of characters. Negative numbers indicate right justified columns.

Back to Top

What functions does Chart support?

The Chart class is used to represent data that will be displayed as a chart in a report or widget. Typically a chart is created by running a Query and selecting columns from the resulting Table.

Class Methods

Instance Properties

Usage:

Supported values for type are:

The following color values are defined: "red", "black", "blue", "cyan", "dark_gray", "gray", "green", "light_gray", "magenta", "orange", "pink", "yellow", "white", "dark_blue", "dark_cyan", "dark_green", "dark_magenta", "dark_red", "dark_yellow", "light_blue", "light_cyan", "light_green", "light_magenta", "light_red", "light_yellow", "very_dark_blue", "very_dark_cyan", "very_dark_green", "very_dark_magenta", "very_dark_red", "very_dark_yellow", "very_light_blue", "very_light_cyan", "very_light_green", "very_light_magenta", "very_light_red", "very_light_yellow".

Custom colors can be defined using the notation "RRR,GGG,BBB" where RRR, GGG and BBB are values between 0 and 255.

Note: Default chart settings can be specified in the global.prefs file.

Back to Top

What functions does Report support?

The Report class is used to add headings, paragraphs, tables and charts to reports.

Class Methods

Instance Methods

Usage:

Valid event types are threshold, security and status. Valid event severities are inform, warn and severe.

Note: the report.sendEvent(), report.storeTable() and report.retrieveTable() methods only have an effect when the script is run as part of a scheduled report.

Back to Top

How do I output text in a script?

The print and println functions are used to output text from a script.

The print function does not start a new line, so successive calls to print will result in text being concatenated into one long line. The println function starts a new line after each call.

Note: Print functions have no effect if the script is being run as part of a report template, the report.paragraph() function should be used instead.

Back to Top

How do I format a number as text?

The formatnumber function is used to convert a number into formatted text.

The formatString follows the Java DecimalFormat syntax. The country and language codes follow the Java Locale specification.

Back to Top

How do I format a date as text?

The formatdate function is used to covert a date into formatted text.

The formatString follows the Java SimpleDateFormat syntax. The country and language codes follow the Java Locale specification.

Back to Top

How do I import external data into a script?

The readurl function is used to import data.

Note By default only http and https protocols are allowed in the URLs. Reading of files is only allowed when scripts are run from the command line or when explicitly enabled by setting the report.readurl.protocol.file variable in the global.prefs file.

Back to Top

How do I write data to files from a script?

The write function is used to write data to a file.

The filename determines the format of a chart file. If the filename ends in ".gif" then a GIF image will be written, if the filename ends in ".jpg" then a JPEG image will be written, otherwise the image will be stored in PNG format.

Tables will be written as html tables and strings are written as simple text files.

Note: The write function can only be used when scripts are run from the command line or when explicitly enabled by setting the report.write.allow variable in the global.prefs file.

Back to Top

How do a run a shell command from a script?

The runcmd function is used to execute a shell command.

All the arguments are strings. Entries in the envp array are environment variables of the form "name=value". The dir argument is a string specifying the working directory for the command. The runcmd functions follow the syntax of the Java Runtime.exec methods.

The runcmd function returns an object with three attributes:

Note: The runcmd function can only be used when scripts are run from the command line or when explicitly enabled by setting the report.runcmd.allow variable in the global.prefs file.

Back to Top