.\" Copyright (c) 2003 Andrey Simonenko .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" @(#)$Id: ipa_ip6fw.8,v 1.2 2006/03/22 23:44:47 simon Exp $ .\" .TH IPA_IP6FW 8 "March 14, 2004" .SH NAME ipa_ip6fw\ \-\ IPA accounting module for FreeBSD IPv6 Firewall .SH DESCRIPTION \fBipa_ip6fw\fP is an IPA accounting module with following features: .IP - The module is designed for traffic accounting from FreeBSD IPv6 Firewall rules byte counters; .IP - The module understands IPv6 Firewall rules byte counters overflow; .IP - It is possible to summarize and subtract statistics from IPv6 Firewall rules byte counters; .IP - It is possible to distinguish IPv6 Firewall rules with the same numbers; .IP - IPv6 Firewall rules can be dynamically added to and deleted from the system, the module correctly works in such situations. .PP Before reading next paragraphs you should read documentation for IPv6 Firewall for information how to setup IPv6 Firewall rules for accounting. .PP Usually binary code of the \fBipa_ip6fw\fP module is saved in the \fIipa_ip6fw.so\fP file. The name of the accounting system is \fBip6fw\fP. .SH CONFIGURATION FILE FORMAT Configuration for the module is integrated to the ipa.conf(5). The configuration prefix of this module is \fBip6fw\fP. .PP To get statistics from IPv6 Firewall for some rule you should use the \fBrules\fP parameter: .PP .nf ip6fw:rules = [-]number[.subnumber]; .fi .PP In the original format of an IPv6 Firewall rule there is only one rule number. Extra subnumber can be added to distinguish rules with the same number, first rule with some number has a subnumber equal to 0, second rule with the same number has a subnumber equal to 1 and so om. If a subnumber is omitted, then it is treated as 0. A subnumber in an IPv6 Firewall rule is something new and is not mentioned in the ip6fw(8) manual page. .PP The `\fB-\fP' sign can be placed before IPv6 Firewall rule number, in this case the module will subtract statistics of this IPv6 Firewall rule. .PP Several IPv6 Firewall rules can be placed in the \fBrules\fP parameter separated by spaces and their statistics will be added or subtracted according to signs before rules' numbers. .PP The \fBmaxchunk\fP parameter allows to safely flush IPv6 Firewall rules or delete and add the same rules when ipa(8) is running: .PP .nf ip6fw:maxchunk = ; .fi .PP This parameter can be placed in ipa.conf(5)'s \fBglobal\fP and \fBrule\fP sections. .PP If the difference between old value of a byte counter and current one of some IPv6 Firewall rule is greater than the \fBmaxchunk\fP parameter's value, then the module takes absolute value of the byte counter as current chunk for this rule. .PP Too little value for the \fBmaxchunk\fP parameter can give wrong results. A value of the \fBmaxchunk\fP parameter should be greater than difference of byte counters of any of IPv6 Firewall used in a ipa.conf(5)'s rule during database update time interval. .PP It will be better to check some variables of IPv6 Firewall kernel structures and determine if some IPv6 Firewall rule has been changed. But there are no such variables in IPv6 Firewall kernel structures (at the moment when this manual page was being written), so you need to use the \fBmaxchunk\fP parameter. .PP Since it is very important to get correct statistics, the \fBmaxchunk\fP parameter must be always specified. .PP The module always send log messages when some IPv6 Firewall rule overflowed or probably was changed (this is checked with the help from the \fBmaxchunk\fP parameter) and when some IPv6 Firewall rule is added to or deleted from the IPv6 Firewall kernel table. It is possible to suppress these warning messages by the \fBquiet\fP parameter: .PP .nf ip6fw:quiet = ; .fi .PP This parameter can be placed in ipa.conf(5)'s \fBglobal\fP and \fBrule\fP sections. .PP By default value of this parameter is equal to zero, which means that all warning messages are sent to the log. If the value of this parameter has 0x1 bit on, then no log message is sent, when a byte counter of some of IPv6 Firewall rules listed in ipa.conf(5)'s rule overflows. If the value of this parameter has 0x2 bit on, then no log message is sent, when some IPv6 Firewall rule is added or deleted. .PP Parameter \fBdebug_ip6fw\fP helps to debug the module if something goes wrong: .PP .nf ip6fw:debug_ip6fw = ; .fi .PP Only two values are allowed for the debug level: 0 and 1. This parameter should not be placed in any section. By default the value of this parameter is 0, and debugging is off. .PP \fIExample:\fP .PP .nf ac_mod "ipa_ip6fw.so"; global { /* ... */ ac_list ip6fw; ip6fw:quiet = 3; ip6fw:maxchunk = 1G; } rule 1 { /* ... */ ip6fw:rules = 100 200.1 300; } rule 2 { /* ... */ ip6fw:rules = 100 -200 300.0 300.1; ip6fw:maxchunk = 500M; } .fi .PP The first rule inherits \fBmaxchunk\fP from the \fBglobal\fP section, both rules inherit \fBquiet\fP parameter from the \fBglobal\fP section. .SH SEE ALSO ip6fw(8) .SH HISTORY IPv6 Firewall first appeared in FreeBSD 4.0-RELEASE. .SH AUTHOR Andrey\ Simonenko\ .SH BUGS If you use FreeBSD system prior to 4.2-RELEASE, then \fBipa_ip6fw\fP module will work if you have no more than 1024 rules in IPv6 Firewall table, on such systems ip6fw(8) also is not able to output whole IPv6 Firewall rules table if it has more than 1024 rules. .PP Due to not perfect interface between userland and IPv6 Firewall part of the kernel, \fBipa_ip6fw\fP module will not work correctly if IPv6 Firewall is not enabled in the kernel. .PP If you install new FreeBSD kernel with new IPv6 Firewall API, you need to rebuild this module. .PP If you find any bug, please send email me.