
11.. UUssiinngg iippffww22ddsshhiieelldd

iippffww22ddsshhiieelldd searches for ipfw log messages and mails a report ready for
submission to _d_s_h_i_e_l_d_._o_r_g. See _h_t_t_p_:_/_/_w_w_w_._d_s_h_i_e_l_d_._o_r_g_/_h_o_w_t_o_._p_h_p for more
information on the dshield output format and how to submit reports.

The iippffww22ddsshhiieelldd software is free and can be redistributed and/or modified
under the terms of the GNU General Public License. A copy of the GPL should
have been received along with this program (see COPYING).

The script is written for FreeBSD and Darwin (MacOS X). Installation and
execution require root permission. To install run

  	make install

This will install the following files:

      /usr/local/sbin/ipfw2dshield
      /usr/local/bin/strpdate
      /usr/local/bin/ipaddr
      ~/.ipfw2dshield.rc.sample

Copy or rename the sample configuration file to ~~//..iippffww22ddsshhiieelldd..rrcc and edit
this latter file to fit your local demands. Please read section 2 below for an
explanation of the configuration entries.

The script creates a stampfile in //vvaarr//ttmmpp where it stores date and time
information which will be accessed on a subsequent run to prevent multiple
submission of log records. Hence this file should remain untouched for correct
operation.

The executables and the sample configuration file can be removed by

  	make uninstall

The config file ~~//..iippffww22ddhhiieelldd..rrcc and the stampfile in //vvaarr//ttmmpp are not deleted
by this command.

Usually iippffww22ddsshhiieelldd is invoked without arguments. However, it recognizes a
number of options which might be convenient for special purposes, e.g., for
testing the configuration. Run 'iippffww22ddsshhiieelldd  --hh' to get some usage
instructions.
-------------------------------------------------------------------------------

22.. TThhee ccoonnffiigguurraattiioonn vvaarriiaabblleess



  uusseerriidd
      Your DShield user ID if you have any, set to 0 otherwise.



  mmaaiillttoo,, mmaaiillcccc,, mmaaiillbbcccc
      The 'To:', 'Cc:', and 'Bcc:' headers for mailing the report.



  sseennddeerr
      Sets the 'From:' and 'Return-Path:' mail headers for the report. This is
      particularly useful if iippffww22ddsshhiieelldd is run by cron and your reports are
      directly submitted to dshield.org.



  ddrroopp__ssoouurrccee,, ddrroopp__ssoouurrccee__TTCCPP,, ddrroopp__ssoouurrccee__UUDDPP,, ddrroopp__ssoouurrccee__IICCMMPP
      Lists of host or subnet IP addresses that are to be ignored for the
      report if they occur as the source of logged IP packets. Entries in the
      ddrroopp__ssoouurrccee list are assumed to match any protocol, the others are
      protocol specific according to the list suffix.

      An optional 'ports' modifier can be supplied for each list entry. The
      general form thus is

            ip_address[:ports]

      where 'ip_address' stands for

      * a single host described by a dotted quad (e.g. 172.16.47.11) or
      * a subnet characterized in the CIDR notation (e.g. 172.16.0.0/12),

      and where 'ports' is a comma-separated list of port numbers or ranges.
      For example, an entry

            192.168.50.0/24:53,137-139,49152-

      would cause the script to ignore all logs of packets from 192.168.50.*
      sent on port 53, 137-139, or 49152-65535. If given in combination with
      the unspecific subnet 0.0.0.0/0 a 'ports' modifier applies to any IP
      address. ICMP packets do not use ports. However, if a 'ports' modifier is
      issued, logs of ICMP packets will be processed in the same manner as
      those of TCP/UDP packets where the source and destination port numbers
      are identified with ICMP types and codes, respectively.



  ddrroopp__ttaarrggeett,, ddrroopp__ttaarrggeett__TTCCPP,, ddrroopp__ttaarrggeett__UUDDPP,, ddrroopp__ttaarrggeett__IICCMMPP
      Exclusion lists corresponding to the previously described ddrroopp__ssoouurrccee**
      lists, but specifying ignorable destinations of logged IP packets.



  uuttcc__ttiimmeessttaammppss
      The time zone specification used for the output. Note that this variable
      does nnoott imply assumptions for the timestamps of the input data read from
      the logs -- these are automatically understood in local time. Setting
      this value to "YES" will convert the timestamps to UTC, otherwise local
      time is preserved.



  sseeaarrcchh
      The expression that is searched for in the log lines.



  llooggddiirr
      The directory containing the logfiles, usually //vvaarr//lloogg.



  llooggbbaassee
      The basename of the logfiles to be inspected. For example, the value
      sseeccuurriittyy is expanded to $${{llooggddiirr}}//sseeccuurriittyy** and the files matching that
      pattern will be processed in their chronological order. Logs older than
      the current stampfile will be skipped. Logs whose modification time is
      more than 6 months in the past will be skipped.



  ssttaammppffiillee
      The name of the stampfile in //vvaarr//ttmmpp, usually iippffww22ddsshhiieelldd.

-------------------------------------------------------------------------------

33.. CCaavveeaattss

The timestamp of a log entry does not describe a unique point of time in that
the information on the year and the timezone is not provided. For the dshield
report format these data have to be substituted. The timezone is chosen
according to //eettcc//llooccaallttiimmee so that no problems are to be expected for machines
that never change their timezone. For the year the current year is inserted
unless the result corresponds to a future date or time, in which case the
previous year is assumed.
-------------------------------------------------------------------------------

44.. CCoonnttaacctt

For bug reports, suggestions, comments, and stuff like that send mail to Frank
W. Josellis _<_f_r_a_n_k_ _a_t_ _d_y_n_a_m_i_c_a_l_-_s_y_s_t_e_m_s_._o_r_g_>
-------------------------------------------------------------------------------
