=pod

=head1 NAME

B<rwrandomizeip> - Randomize the IP addresses in a SiLK Flow file

=head1 SYNOPSIS

  rwrandomizeip [--seed=NUMBER] [--only-change-set=CHANGE_IPSET]
        [--dont-change-set=KEEP_IPSET]
        [--consistent] [--save-table=FILE] [--load-table=FILE]
        [--site-config-file=FILENAME] INPUT_FILE OUTPUT_FILE

=head1 DESCRIPTION

Substitute a pseudo-random IP address for the source and destination
IP addresses of I<INPUT_FILE> and write the result to I<OUTPUT_FILE>.
You may use C<stdin> for I<INPUT_FILE> to have B<rwrandomizeip> to
read from the standard input; the I<OUTPUT_FILE> value of C<stdout>
will cause B<rwrandomizeip> to write to the standard output unless it
is connected to a terminal.  B<rwrandomizeip> knows how to read and
write compressed (B<gzip>pid) files.

To only change a subset of the IP addresses, the optional switches
B<--only-change-set> or B<--dont-change-set> can be used; each switch
takes an IPset file as its required argument.  When the
B<--only-change-set>=I<CHANGE_IPSET> switch is given, B<rwrandomizeip>
only modifies the IP addresses listed in the I<CHANGE_IPSET> file.  To
change all addresses I<except> a specified set, use B<rwsetbuild(1)>
to create an IPset file containing those IPs and pass the name of the
file to the B<--dont-change-set> switch.  An address listed in both
the B<only-change-set> and the B<dont-change-set> will not be
modified.

The B<--seed> switch can be used to initialize the pseudo-random
number generator to a known state.

When the B<--consistent>, B<--load-table>, and B<--save-table>
switches are I<not> provided, B<rwrandomizeip> uses a pseudo-random,
non-routable IP address for each source and destination IP address it
sees; an IP address that appears multiple times in the input will be
mapped to different output address each time, and no structural
information in the input will be maintained.

The B<--consistent>, B<--load-table>, or B<--save-table> switches
enable consistent IP mapping, so that an input IP is consistently
mapped to the same output IP.  In addition, the structural information
of the input IPs is maintained.  Unfortunately, this comes at a cost
of less randomness in the output.


=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<--seed>=I<NUMBER>

Use I<NUMBER> to seed the pseudo-random number generator.  This can be
used to put the random number generator into a known state, which is
useful for testing.

=item B<--only-change-set>=I<CHANGE_IPSET>

Only modify the source or destination IP address if it appears in the
given IPset file I<CHANGE_IPSET>.  The B<rwsetbuild> command can be
used to create an IPset file.  When the
B<--dont-change-set>=I<KEEP_IPSET> switch is also given, the IPs it
contains will override those in the I<CHANGE_IPSET> file.

=item B<--dont-change-set>=I<KEEP_IPSET>

Do not modify the source or destination IP address if the address
appears in the given IPset file I<KEEP_IPSET>.  The B<rwsetbuild>
command can be used to create an IPset file.  The interaction of this
switch with the B<--only-change-set> switch is described immediately
above.

=item B<--consistent>

Randomize the IP addresses consistently, so that an input IP address
is always mapped to the same value.  The default behavior is to use a
random IP address for each IP, even if the IP has been seen before.

=item B<--save-table>=I<FILE>

Randomize the IP addresses consistently and save this run's
randomization table for future use.  The table is written to the
specified I<FILE>, which must not not exist.  This switch is
incompatible with the B<--load-table> switch.

=item B<--load-table>=I<FILE>

Randomize the IP addresses consistently using the randomization table
contained in <FILE> that was created by a previous invocation of
B<rwrandomizeip>.  This switch is incompatible with the
B<--save-table> switch.

=item B<--site-config-file>=I<FILENAME>

Read the SiLK site configuration from the named file I<FILENAME>.
When this switch is not provided, the location specified by the
C<$SILK_CONFIG_FILE> environment variable is used if that variable is
not empty.  The value of C<$SILK_CONFIG_FILE> should include the name
of the file.  Otherwise, the application looks for a file named
F<silk.conf> in the following directories: the directory specified in
the F<$SILK_DATA_ROOTDIR> environment variable; the data root
directory that is compliled into SiLK (use the B<--version> switch to
view this value); the directories F<$SILK_PATH/share/silk/>,
F<$SILK_PATH/share/>, or F<$SILK_PATH>; or in the F<share/silk/> and
F<share/> directories parallel to the application's directory.

=back


=head1 SEE ALSO

B<rwset(1)>, B<rwsetbuild(1)>


=head1 BUGS

Only the source and destination IP fields are modified; additional
fields in the SiLK Flow records may leak sensitive information.

The B<--consistent> switch uses a method of randomization that is
fairly easy to decipher.  Specifically, 4 tables are created with each
having 256 entries containing the values 0-255 that have been ramdomly
shuffled.  Each table is used to map the values for a specific octet
in an IP address.  For example, when modifying the IP address
C<10.10.10.10>, the value at position C<10> from each table will be
substituted into the IP.

When the same IPset is passed to the B<--only-change-set> and
B<--dont-change-set> switches, the output is identical to the input.

=cut

$SiLK: rwrandomizeip.pod 7334 2007-05-30 15:42:13Z mthomas $

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