NAME

rwpmapbuild - Create a prefixmap from a text file

SYNOPSIS

  rwpmapbuild [--input-file=FILENAME] [--output-file=FILENAME]
        [--note-add=TEXT] [--note-file-add=FILENAME]

DESCRIPTION

Prefixmaps provide a way to map field values to string labels based on a user-defined map file. Using the prefixmap plug-in, pmapfilter(3), you can you can partition, count, sort and display records based on arbitrary labels. rwpmapbuild reads textual input to create a binary pmap file that the plug-in can use; the syntax of this input is described below.

The textual input is read from the specified input file, or from the standard input when the --input-file switch is not provided. The binary output is read to the named output file, or to the standard output when the --output-file switch is not provided and the standard output is not connected to a terminal.

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.

--input-file=FILENAME: Read the textual input from FILENAME. You may use stdin to represent the standard input. When this switch is not provided, the input is read from the standard input. The input file format is described below.
--output-file=FILENAME: Write the binary prefixmap to FILENAME. You may use stdout to represent the standard output. When this switch is not provided, the prefixmap is written to the standard output unless stdout is connected to a terminal.
--note-add=TEXT: Add the specified TEXT to the header of the output file as an annotation. This switch may be repeated to add multiple annotations to a file. To view the annotations, use the rwfileinfo(1) tool.
--note-file-add=FILENAME: Open FILENAME and add the contents of that file to the header of the output file as an annotation. This switch may be repeated to add multiple annotations. Currently the application makes no effort to ensure that FILENAME contains text; be careful that you do not attempt to add a SiLK data file as an annotation.

INPUT FILE FORMAT

The input file format consists of any number of input lines of the forms described below. Note that there is form that accepts a single IP address and a label; therefore, to provide a label for a single IP address you must append /32 to the IP address.

default label name or ID to end of line: Make the given label ID or label text the default value for any ranges not covered by this input file. Note that when given a label name for a not-yet-defined label, this will allocate an ID for that label, which could result in conflicts. You may not provide a numeric label that has not yet been defined.

label num label name to end of line: Associate the given label ID with the given label text. Note that any label text used in the rest of the file will be automatically assigned a number. It is an error to give the same label to multiple names, or the same name to multiple label numbers.

mode { ip | proto-port }: Process this file in IP address or protocol/port mode. By default, processing is done in IP address mode.

IP Address Mode

cidr-block label name or ID to end of line: Associate the given label ID or label text with this CIDR block.

low-ip-or-int high-ip-or-int label name or ID to end of line: Associate the given label ID or label text with this IP range (IPs both given as either integers or IPv4 addresses.)

Protocol/Port Mode

proto/port proto/port label name or ID to end of line: Associate the given label name or ID with all protocols and port numbers between these two values. Note that while port is not meaningful for all protocols (specifically, it is meaningful for TCP and UDP and may contain type/code information for ICMP), this file allows port numbers to be given for any protocol.

proto proto label name or ID to end of line: Associate the given label name or ID with all protcols between these two values.

NOTES

The IP Adddress input file can contain nested CIDR blocks. They should be ordered with the more general blocks first, and the more specific blocks last. That is, use:

  10.0.0.0/8     My-space
  10.1.0.0/16    Special-Subnet-1
  10.1.2.0/24    Special-Subnet-2

EXAMPLE

Reading and writing to a file:

  $ echo "10.1.2.3/32 my favorite host" > fav.txt
  $ rwpmapbuild -i fav.txt -o fav.pmap

Reading and writing to stdin and stdout:

  $ echo "10.9.8.7/32 suspicious subnet" \
      | rwpmapbuild --input=stdin --output=stdout > suspicious.pmap

Example of a complex input file:

  #    Default to "external" for all un-defined ranges.

  default             external

  #    Numerical mappings of labels

  label 0             non-routable
  label 1             internal
  label 2             external

  #    Force IP-mode

  mode                ip

  ## Reserved and non-routable blocks ###########################

  #    Addresses in this block refer to source hosts on "this"
  #    network.  Address 0.0.0.0/32 may be used as a source
  #    address for this host on this network; other addresses
  #    within 0.0.0.0/8 may be used to refer to specified hosts
  #    on this network [RFC1700, page 4].

  0.0.0.0/8           non-routable

  #    This block is set aside for use in private networks.  Its
  #    intended use is documented in [RFC1918].  Addresses within
  #    this block should not appear on the public Internet.

  10.0.0.0/8          non-routable

  #    This block is assigned for use as the Internet host
  #    loopback address.  A datagram sent by a higher level
  #    protocol to an address anywhere within this block should
  #    loop back inside the host.  This is ordinarily
  #    implemented using only 127.0.0.1/32 for loopback, but no
  #    addresses within this block should ever appear on any
  #    network anywhere [RFC1700, page 5].

  127.0.0.0/8         non-routable

  #    This is the "link local" block.  It is allocated for
  #    communication between hosts on a single link.  Hosts
  #    obtain these addresses by auto-configuration, such as when
  #    a DHCP server may not be found.

  169.254.0.0/16      non-routable

  #    This block is set aside for use in private networks.  Its
  #    intended use is documented in [RFC1918].  Addresses within
  #    this block should not appear on the public Internet.

  172.16.0.0/12       non-routable

  #    This block is assigned as "TEST-NET" for use in
  #    documentation and example code.  It is often used in
  #    conjunction with domain names example.com or example.net
  #    in vendor and protocol documentation.  Addresses within
  #    this block should not appear on the public Internet.

  192.0.2.0/24        non-routable

  #    This block is set aside for use in private networks.
  #    Its intended use is documented in [RFC1918].  Addresses
  #    within this block should not appear on the public Internet.

  192.168.0.0/16      non-routable

  #    240.0.0.0/4 - This block, formerly known as the Class E
  #    address space, is reserved.  The "limited broadcast"
  #    destination address 255.255.255.255 should never be
  #    forwarded outside the (sub-)net of the source.  The
  #    remainder of this space is reserved for future use.
  #    [RFC1700, page 4]

  255.255.255.255/32  non-routable

  # -- Below this line, would add any mappings appropriate to
  # -- the local network.

BUGS

Prefix map files do not support IPv6 addresses. Any IPv6 addresses in the input will be ignored.