=pod

=head1 NAME

B<rwsetbuild> - Create a binary IPset file from list of IPs

=head1 SYNOPSIS

  rwsetbuild [--compression-method=COMP_METHOD]
        {<input-text-file> | stdin} {<output-set-file> | stdout}

=head1 DESCRIPTION

Creates a binary IPset file at the specified output location from a
textual list of IP addresses read from the specified input location.
Use the string C<stdin> to read IP addresses from the standard input,
and use the string C<stdout> to write the binary IPset file to the
standard output.

The IP addresses should appear one per line.  Comments are
ignored; they begin with the 'B<#>' symbol and continue to the end
of the line.  Whitespace and blank lines are also ignored.  Each
IP address should be expresed in one of these formats:

=over

=item *

Dotted decimal-B<--all> 4 octets are required:

  10.1.2.4

=item *

An unsigned 32-bit integer:

  167838212

=item *

Either of the above with a CIDR designation-B<--for> dotted decimal
all four octets are still required:

  10.1.2.4/31
  167838212/31
  192.168.0.0/16

=item *

SiLK wildcard notation: Four octets separated by periods where each
octet may be a single number, a range of numbers, e.g., 1-10, a comma
separated list of numbers and ranges, or the character 'x' used to
represent all values in an octet, that is 0-255:

  10.x.1-2.4,5

=back

If an IP address cannot be parsed, B<rwsetbuild> will exit with an
error.

B<rwsetbuild> requires two arguments; it will exit with an error if it
does not receive two arguments.

If the first argument is the string C<stdin>, B<rwsetbuild> will read
the list of IP addresses from the standard input; otherwise,
B<rwsetbuild> treats the first argument as the path to the input text
file from which it should read IP addresses.  B<rwsetbuild> will exit
with an error if the input path does not exist or cannot be opened.

When the second argument is the string C<stdout> and the standard
output is not connected to a terminal, B<rwsetbuild> will write the
binary IPset to the standard output. Otherwise, the second argument
should be the path where B<rwsetbuild> will write the binary IPset
file.  B<rwsetbuild> will exit with an error if the output file
already exists or cannot be created.

=head1 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 B<--arg>=I<param> or B<--arg> I<param>, though the first form is
required for options that take optional parameters.

=over 4

=item B<--compression-method>=I<COMP_METHOD>

Set the compression method of the output to I<COMP_METHOD>.  Some SiLK
tools can use an external library to compress their binary output.
The list of available compression methods and the default method are
set when SiLK is compiled (the B<--help> and B<--version> switches
print the available and default compression methods) and depend on
which supported libraries are found.  SiLK can support:

=over 4

=item none

Do not compress the output using an external library

=item zlib

Use the B<zlib(3)> library for compressing the output

=item lzo1x

Use the I<lzo1x> algorithm from the LZO real time compression library
for compression

=item best

Use whichever available method gives the C<best> compression in
general, though not necessarily the C<best> for this particular
output.

=back

=back

=head1 EXAMPLE

Reading from a file:

  $ echo 10.x.x.x > ten.txt
  $ rwsetbuild ten.txt ten.set

Reading from the standard input:

  echo 192.168.x.x | rwsetbuild stdin private.set

Example input to B<rwsetbuild>:

  # A single address
  10.1.2.4
  # Two addresses in the same subnet
  10.1.2.4,5
  # The same two addresses
  10.1.2.4/31
  # The same two addresses
  167838212/31
  # A whole subnet
  10.1.2.0-255
  # The same whole subnet
  10.1.2.x
  # The same whole subnet yet again
  10.1.2.0/24
  # All RFC1918 space
  10.0.0.0/8
  172.16.0.0/12
  192.168.0.0/16
  # All RFC1918 space
  10.x.x.x
  172.16-20,21,22-31.x.x
  192.168.x.x
  # All RFC1918 space
  167772160/8
  2886729728/12
  3232235520/16
  # Everything ending in 255
  x.x.x.255
  # All addresses that end in 1-10
  x.x.x.1-10

=head1 SEE ALSO

B<rwset(1)>, B<rwsetcat(1)>, B<rwsetintersect(1)>, B<rwfilter(1)>

=cut

$SiLK: rwsetbuild.pod 5471 2006-11-01 21:10:02Z mthomas $

Local Variables:
mode:text
indent-tabs-mode:nil
End: