NAME

rwsiteinfo - Print information from the silk.conf site configuration file

SYNOPSIS

  rwsiteinfo --fields=FIELD[,FIELD...]
        { [--classes=CLASS[,CLASS...]] [--types=TYPE[,TYPE...]]
          | [--flowtypes=CLASS/TYPE[,CLASS/TYPE...]] }
        [--sensors=SENSOR[,SENSOR...]]
        [--data-rootdir=ROOT_DIRECTORY] [--site-config-file=FILENAME]
        [--timestamp-format=FORMAT] [--no-titles]
        [--no-columns] [--column-separator=CHAR]
        [--no-final-delimiter] [{--delimited | --delimited=CHAR}]
        [--list-delimiter=CHAR] [--output-path=PATH]
        [--pager=PAGER_PROG]

  rwsiteinfo --help

  rwsiteinfo --help-fields

  rwsiteinfo --version

DESCRIPTION

rwsiteinfo is a utility to print selected information about the classes, types, flowtypes, and sensors that are defined in the silk.conf(5) site configuration file. The --fields switch is required, and its argument is a comma-separated list of field names selecting the fields to be printed. The output from rwsiteinfo consists of multiple columns and rows, where each column contains one of the FIELDs and where each row has a unique value for one of the FIELDs. rwsiteinfo prints rows until all possible combinations of fields is exhausted. By default, the information is printed in a columnar, bar ("|") delimited format.

As of SiLK 3.11.0, rwsiteinfo can visit the files in the data repository to report the date of the earliest (oldest) file in the repository, the date of the latest (most recent) file in the repository, and the number of files in the repository. These values are reported individually for each row in the output. Note: If your data repository is large, scanning it may take a long time.

The --classes, --types, --flowtypes, and --sensors switches allow the user to limit the amount of information printed. (These switches operate similarly to their namesakes on rwfilter(1) and rwfglob(1).) If none of these switches are given, rwsiteinfo prints information for all values defined in the silk.conf file. If one or more of these switches is specified, rwsiteinfo limits its output to the specified values. To print information about the default class or the default types within a class, use the at-sign ("@") as the name of the class or type, respectively. The --flowtypes switch must be used independently of the --classes and --types switches.

As stated above, rwsiteinfo prints unique rows given a list of FIELDs. As an example, suppose the user entered the command "rwsiteinfo --fields=class,type,sensor". rwsiteinfo will print a row containing the first class defined in the silk.conf file, the first type defined for that class, and the first sensor name defined for that class/type pair. On the next row, the class and type will be the same and the second sensor name will be printed. Once all sensors have been printed, rwsiteinfo repeats the process for the second type defined for the first class, and so on. Once all information for the first class has been printed, the process would repeat for the next class, until all classes have been printed.

The order of the FIELDs determines how rwsiteinfo iterates through the possible values. The last FIELD will change most rapidly, and the first field will change most slowly. Two invocations of rwsiteinfo where the first specifies "--fields=class,sensor" and the second specifies "--fields=sensor,class" produce the same number of rows, and each invocation has an outer and inner iterator. In the first invocation, the outer iterator is over the classes, and the inner iterator is over each sensor defined in that class. In the second invocation, the outer iterator is over the sensors, and the inner is over the classes to which that sensor belongs.

In general, the output will contain some combination of class, type, flowtype, and sensor. For flowtype and sensor, the numeric ID may be printed instead of the name. For class and type, the default values may be printed or they may be identified by a symbol. Most field names support a FIELD:list variant that puts all possible values for that field into a single column. See the description of the --fields switch below for details.

OPTIONS

Option names may be abbreviated if the abbreviation is unique or is an exact match for an option. A parameter to an option may be specified as --arg=param or --arg param, though the first form is required for options that take optional parameters.

--fields=FIELD[,FIELD...]: Specify the fields to print as a comma-separated list of names. The names are case-insensitive. The fields will be displayed in the order the names are specified. The --fields switch is required, and rwsiteinfo will fail when it is not provided.
The list of possible field names is:

class: the class name, e.g., "all"
type: the type name, e.g., "inweb"
flowtype: the flowtype name, e.g., "iw". The flowtype name is a combination of the class name and type name, and it is used to name files in the SiLK data repository.
id-flowtype: the integer identifier for the flowtype, e.g., 2
sensor: the sensor name, e.g., "S3"
id-sensor: the integer identifier for the sensor, e.g., 3
describe-sensor: the sensor description, when present
default-class: the default class name
default-type: the default type name
mark-defaults: a two-character wide column that contains a plus '+' on a row that contains the default class and an asterisk '*' on a row that contains a default type
repo-start-date: the earliest date for a file in the repository that matches the values in this row or empty when no files match Since SiLK 3.11.0
repo-end-date: the latest date for a file in the repository that matches the values in this row or empty when no files match Since SiLK 3.11.0
repo-file-count: the number of files in the repository that match the values in this row or zero when no files match Since SiLK 3.11.0
class:list: instead of printing class names on separate rows, join all the classes in a single row separated using the list-delimiter
type:list: instead of printing type names on separate rows, join all the types in a single row separated using the list-delimiter
flowtype:list: instead of printing flowtype names on separate rows, join all the flowtypes in a single row separated using the list-delimiter
id-flowtype:list: instead of printing flowtype identifiers on separate rows, join all the flowtype identifiers in a single row separated using the list-delimiter
sensor:list: instead of printing sensor names on separate rows, join all the sensors in a single row separated using the list-delimiter
id-sensor:list: instead of printing sensor identifiers on separate rows, join all the sensor identifiers in a single row separated using the list-delimiter
default-class:list: equivalent to default-class, but provided for consistency
default-type:list: instead of printing the default type names on separate rows, join all the default type names in a single row separated using the list-delimiter

--classes=CLASS[,CLASS...]: Restrict the output using the class(es) named in the comma-separated list. The default class may be specified by using an at-sign ("@") as the name of a class.
--types=TYPE[,TYPE...]: Restrict the output using the type(s) named in the comma-separated list. The default types for a class may be specified by using an at-sign ("@") as the name of a type.
--flowtypes=CLASS/TYPE[,CLASS/TYPE...]: Restrict the output using the class/type pairs named in the comma-separated list, where the class name and type name are separated by a slash ("/"). The keyword "all" may be used for the CLASS and/or TYPE to select all classes and/or types.
--sensors=SENSOR[,SENSOR...]: Restrict the output to the sensors(s) named in the comma-separated list of sensor names, sensor IDs (integers), and/or ranges of sensor IDs.
--data-rootdir=ROOT_DIRECTORY: Use ROOT_DIRECTORY as the root of the data repository, which overrides the location given in the SILK_DATA_ROOTDIR environment variable, which in turn overrides the location that was compiled into rwsiteinfo (/data). This directory is one of the locations where rwsiteinfo attempts to find the silk.conf file, and it is the repository that is scanned when the repo-start-date, repo-end-date, or repo-file-count field is specified.
--site-config-file=FILENAME: Read the SiLK site configuration from the named file FILENAME. When this switch is not provided, rwsiteinfo searches for the site configuration file in the locations specified in the "FILES" section.
--timestamp-format=FORMAT: Specify the format and/or timezone to use when printing timestamps. When this switch is not specified, the SILK_TIMESTAMP_FORMAT environment variable is checked for a default format and/or timezone. If it is empty or contains invalid values, timestamps are printed in the default format, and the timezone is UTC unless SiLK was compiled with local timezone support. FORMAT is a comma-separated list of a format and/or a timezone. The format is one of:

default: Print the timestamps as "YYYY/MM/DDThh:mm:ss".
iso: Print the timestamps as "YYYY-MM-DD hh:mm:ss".
m/d/y: Print the timestamps as "MM/DD/YYYY hh:mm:ss".
epoch: Print the timestamps as the number of seconds since 00:00:00 UTC on 1970-01-01.

When a timezone is specified, it is used regardless of the default timezone support compiled into SiLK. The timezone is one of:

utc: Use Coordinated Universal Time to print timestamps.
local: Use the TZ environment variable or the local timezone.

--no-titles: Turn off column titles. By default, titles are printed.
--no-columns: Disable fixed-width columnar output.
--column-separator=C: Use specified character between columns and after the final column. When this switch is not specified, the default of "|" is used.
--no-final-delimiter: Do not print the column separator after the final column. Normally a delimiter is printed.
--delimited
--delimited=C: Run as if --no-columns --no-final-delimiter --column-sep=C had been specified. That is, disable fixed-width columnar output; if character C is provided, it is used as the delimiter between columns instead of the default "|".
--list-delimiter=C: Specify the character to use between items that comprise a FIELD:list column. The default list delimiter is comma ",".
--output-path=PATH: Write the textual output to PATH, where PATH is a filename, a named pipe, the keyword "stderr" to write the output to the standard error, or the keyword "stdout" or "-" to write the output to the standard output (and bypass the paging program). If PATH names an existing file, rwsiteinfo exits with an error unless the SILK_CLOBBER environment variable is set, in which case PATH is overwritten. If this switch is not given, the output is either sent to the pager or written to the standard output. Since SiLK 3.15.0.
--pager=PAGER_PROG: When output is to a terminal, invoke the program PAGER_PROG to view the output one screen full at a time. This switch overrides the SILK_PAGER environment variable, which in turn overrides the PAGER variable. If the --output-path switch is given or if the value of the pager is determined to be the empty string, no paging is performed and all output is written to the terminal.
--help: Print the available options and exit. Options that add fields can be specified before --help so that the new options appear in the output.
--help-fields: Print a description for each field and exit.
--version: Print the version number and information about how SiLK was configured, then exit the application.

EXAMPLES

In the following examples, the dollar sign ("$") represents the shell prompt. The text after the dollar sign represents the command line. Lines have been wrapped for improved readability, and the back slash ("\") is used to indicate a wrapped line. The output from these examples is based on the sample silk.conf as distributed for the twoway site (c.f. packlogic-twoway(3)).

The following prints all known sensor names, one name per line:

 $ rwsiteinfo --fields=sensor --no-titles --delimited
 S0
 S1
 S2
 S3
 S4
 S5
 S6
 S7
 S8
 S9
 S10
 S11
 S12
 S13
 S14

The following prints all known sensor names on a single line (the names will be separated by comma):

 $ rwsiteinfo --fields=sensor:list --no-titles --delimited
 S0,S1,S2,S3,S4,S5,S6,S7,S8,S9,S10,S11,S12,S13,S14

This changes the output from the previous example to use a space as the separator:

 $ rwsiteinfo --fields=sensor:list --no-titles --delimited \
        --list-delimiter=' '
 S0 S1 S2 S3 S4 S5 S6 S7 S8 S9 S10 S11 S12 S13 S14

The following prints the sensor names for the default class on a single line:

 $ rwsiteinfo --fields=sensor:list --class=@ --no-titles --delimited
 S0,S1,S2,S3,S4,S5,S6,S7,S8,S9,S10,S11,S12,S13,S14

This shows the numeric sensor IDs:

 $ rwsiteinfo --fields=id-sensor:list
                     Sensor-ID:list|
 0,1,2,3,4,5,6,7,8,9,10,11,12,13,14|

The following prints four columns: (1) the sensor identifier, (2) the sensor name, (3) the list of classes for that sensor, and (4) a description of the sensor. This output mimics the output of the deprecated mapsid(1) tool.

 $ rwsiteinfo --fields=id-sensor,sensor,class:list,describe-sensor
 Sensor-ID|Sensor|Class:list|                Sensor-Description|
         0|    S0|       all|         Description for sensor S0|
         1|    S1|       all|                                  |
         2|    S2|       all|Optional description for sensor S2|
         3|    S3|       all|                                  |
         4|    S4|       all|                                  |
         5|    S5|       all|                                  |
         6|    S6|       all|                                  |
         7|    S7|       all|                                  |
         8|    S8|       all|                                  |
         9|    S9|       all|                                  |
        10|   S10|       all|                                  |
        11|   S11|       all|                                  |
        12|   S12|       all|                                  |
        13|   S13|       all|                                  |
        14|   S14|       all|                                  |

This prints three columns: the first contains the class, the second contains the type, and the third uses a "+" to mark rows for the default class and a "*" to mark rows for a default type.

 $ rwsiteinfo --fields=class,type,mark-default
 Class|   Type|Defaults|
   all|     in|      +*|
   all|    out|      + |
   all|  inweb|      +*|
   all| outweb|      + |
   all| innull|      + |
   all|outnull|      + |
   all|int2int|      + |
   all|ext2ext|      + |
   all| inicmp|      +*|
   all|outicmp|      + |
   all|  other|      + |

The following prints two columns, the first containing a class name and the second the list of default types for that class:

 $ rwsiteinfo --fields=class,default-type:list
 Class|Default-Type:list|
   all|  in,inweb,inicmp|

The following prints the default types. (The output contains the default type for each class, but twoway site has a single class.)

 $ rwsiteinfo --fields=default-type --no-titles --delimited
 in
 inweb
 inicmp

This does the same (by limiting the output the default types).

 $ rwsiteinfo --fields=type --types=@ --no-titles --delimited
 all

The following prints the class, the sensor, and the type. The number of rows of output (excluding the title) is the product of the number of classes, number of types, and number of sensors.

 $ rwsiteinfo --fields=class,sensor,type
 Class|Sensor|   Type|
   all|    S0|     in|
   all|    S0|    out|
   all|    S0|  inweb|
   all|    S0| outweb|
   all|    S0| innull|
   all|    S0|outnull|
   all|    S0|int2int|
   all|    S0|ext2ext|
   all|    S0| inicmp|
   all|    S0|outicmp|
   all|    S0|  other|
   all|    S1|     in|
   all|    S1|    out|
 ...
   all|   S14|outicmp|
   all|   S14|  other|

The repo-start-date, repo-end-date, and repo-file-count fields print the range of available dates for the files in the repository. The following shows information about files in the repository for the repository as a whole:

 $ rwsiteinfo --fields=repo-start-date,repo-end-date,repo-file-count
          Start-Date|           End-Date|File-Count|
 2009/02/12T00:00:00|2009/02/14T23:00:00|      2880|

This breaks down the file information per type:

 $ rwsiteinfo --fields=type,repo-start-date,repo-end-date,repo-file-count
    Type|         Start-Date|           End-Date|File-Count|
      in|2009/02/12T00:00:00|2009/02/14T23:00:00|       720|
     out|2009/02/12T00:00:00|2009/02/14T23:00:00|       720|
   inweb|2009/02/12T00:00:00|2009/02/14T23:00:00|       720|
  outweb|2009/02/12T00:00:00|2009/02/14T23:00:00|       720|
  innull|                   |                   |         0|
 outnull|                   |                   |         0|
 int2int|                   |                   |         0|
 ext2ext|                   |                   |         0|
  inicmp|                   |                   |         0|
 outicmp|                   |                   |         0|
   other|                   |                   |         0|

This shows the information for each sensor:

 $ rwsiteinfo --fields=type,repo-start-date,repo-end-date,repo-file-count
 Sensor|         Start-Date|           End-Date|File-Count|
     S0|2009/02/12T00:00:00|2009/02/14T23:00:00|       288|
     S1|2009/02/12T00:00:00|2009/02/14T23:00:00|       288|
     S2|2009/02/12T00:00:00|2009/02/14T23:00:00|       288|
     S3|2009/02/12T00:00:00|2009/02/14T23:00:00|       288|
     S4|2009/02/12T00:00:00|2009/02/14T23:00:00|       288|
     S5|2009/02/12T00:00:00|2009/02/14T23:00:00|       288|
     S6|2009/02/12T00:00:00|2009/02/14T23:00:00|       288|
     S7|2009/02/12T00:00:00|2009/02/14T23:00:00|       288|
     S8|2009/02/12T00:00:00|2009/02/14T23:00:00|       288|
     S9|2009/02/12T00:00:00|2009/02/14T23:00:00|       288|
    S10|                   |                   |         0|
    S11|                   |                   |         0|
    S12|                   |                   |         0|
    S13|                   |                   |         0|
    S14|                   |                   |         0|

ENVIRONMENT

SILK_TIMESTAMP_FORMAT: This environment variable is used as the value for --timestamp-format when that switch is not provided. Since SiLK 3.11.0.
SILK_PAGER: When set to a non-empty string, rwsiteinfo automatically invokes this program to display its output a screen at a time. If set to an empty string, rwsiteinfo does not automatically page its output.
PAGER: When set and SILK_PAGER is not set, rwsiteinfo automatically invokes this program to display its output a screen at a time.
SILK_CLOBBER: The SiLK tools normally refuse to overwrite existing files. Setting SILK_CLOBBER to a non-empty value removes this restriction.
SILK_CONFIG_FILE: This environment variable is used as the value for the --site-config-file when that switch is not provided.
SILK_DATA_ROOTDIR: This environment variable specifies the root directory of data repository. As described in the "FILES" section, rwsiteinfo may use this environment variable when searching for the SiLK site configuration file. In addition, rwsiteinfo visits all the files in this directory when the repo-start-date, repo-end-date, or repo-file-count fields are specified in the --fields switch.
SILK_PATH: This environment variable gives the root of the install tree. When searching for configuration files and plug-ins, rwsiteinfo may use this environment variable. See the "FILES" section for details.
TZ: When the argument to the --timestamp-format switch includes "local" or when a SiLK installation is built to use the local timezone, the value of the TZ environment variable determines the timezone in which rwsiteinfo displays timestamps. (If both of those are false, the TZ environment variable is ignored.) If the TZ environment variable is not set, the machine's default timezone is used. Setting TZ to the empty string or 0 causes timestamps to be displayed in UTC. For system information on the TZ variable, see tzset(3) or environ(7). (To determine if SiLK was built with support for the local timezone, check the "Timezone support" value in the output of rwsiteinfo --version.)

FILES

${SILK_CONFIG_FILE}
${SILK_DATA_ROOTDIR}/silk.conf
/data/silk.conf
${SILK_PATH}/share/silk/silk.conf
${SILK_PATH}/share/silk.conf
/usr/local/share/silk/silk.conf
/usr/local/share/silk.conf: Possible locations for the SiLK site configuration file which are checked when the --site-config-file switch is not provided. The location of the SILK_DATA_ROOTDIR may be specified using the --root-directory switch.
${SILK_DATA_ROOTDIR}/
/data/: Locations for the root directory of the data repository when the --data-rootdir switch is not specified.

NOTES

The repo-start-date, repo-end-date, and repo-file-count fields were added in SiLK 3.11.0.

rwsiteinfo was added in SiLK 3.0.

rwsiteinfo duplicates the functionality found in mapsid(1). mapsid is deprecated, and it will be removed in the SiLK 4.0 release. Examples of using rwsiteinfo in place of mapsid are provided in the latter's manual page.