rwsiteinfo(1) SiLK Tool Suite rwsiteinfo(1)NAMErwsiteinfo - Print information from the silk.conf site configuration
file
SYNOPSISrwsiteinfo --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] [--pager=PAGER_PROG]
rwsiteinfo--help
rwsiteinfo--help-fields
rwsiteinfo--version
DESCRIPTIONrwsiteinfo 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 ",".
--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 value of the pager is determined to be the empty
string, no paging will be performed and all output will be printed
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_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.
SEE ALSOsilk.conf(5), mapsid(1), rwfilter(1), rwfglob(1), packlogic-twoway(3),
silk(7), tzset(3), environ(7)SiLK 3.11.0.1 2016-02-19 rwsiteinfo(1)
