This is Info file pm.info, produced by Makeinfo version 1.68 from the input file bigpm.texi.  File: pm.info, Node: Fwctl, Next: Fwctl/AcctReport, Prev: Functional, Up: Module List Perl module to configure the Linux kernel packet filtering firewall. ******************************************************************** NAME ==== Fwctl - Perl module to configure the Linux kernel packet filtering firewall. SYNOPSIS ======== use Fwctl; my $fwctl = new Fwctl( %opts ); $fwctl->dump_acct; $fwctl->reset_fw; $fwctl->configure; DESCRIPTION =========== Fwctl is a module to configure the Linux kernel packet filtering firewall using higher level abstraction than rules on input, output and forward chains. It supports masquerading and accounting as well. Why Fwctl ? Well, say you are the kind of paranoid firewall administrator which likes his firewall's rules tight. Very tight. Say the kind, that likes to distinguish between a SYN and ACK packet when accepting a TCP connection (anybody configuring packet filters should care about that last point), or like to specify the interface name on each rules. (Whether this is really need, or such a stance is relevant, is not the point.) How would such an administrator proceed ? First of all you deny everything on all interfaces and on all chains (input, forward and output) and turn on logging. Now starting from this configuration (in which Fwctl puts the firewall on initialization), say you want to enable ping from the internal network to the internal ip. What rules do you need ? You need a rule on the input chain to accept the echo-request packet and a rule on the output chain to accept the echo-reply request. Right ? Well, what about the loopback. For sure, when we say from local net to local ip, this imply local ip to local ip ? Then you add a rule to the output chain with the loopback interface, and a rule on the input rule to the loopback chain. And we didn't even start forwarding yet ! Add masquerading to the lot and multi connections protocols like FTP and you got something unmanageable. So you start accepting things you shouldn't to get your job done and in the end your filters look like emmenthal. Fwctl handles all the complexity of this, so that when you say accept ftp -src FTP_PROXY -dst INTERNET -noport you don't accept too much of what you didn't intend. (Well you just opened arbitrary TCP connections to unprivileged ports on the Internet from your proxy server, but that's because of the FTP protocol, not because your cheating on the firewall rules.) Fwctl works with entity known as service. A service can be ftp, netbios, ping or anything else. The service abstraction handles all the communication necessary for that application. (The UDP and TCP communication in DNS, or the control, data and passive connections for FTP.) Additionally, to handle all the special case with ANY specification, when the src of dst imply a local IP, or masquerading, in short for Fwctl to be able to deduce the interface implicated by the src and dst portion of a rules you need to provide it with your network topology. Fwctl must guess from your topology the routing decision that will be made in the kernel. In the best of worlds, Fwctl should contains the same routing algorithm as the one in the kernel. Well, it doesn't so if you are using fancy routing feature, Fwctl won't work. In fact, it can only handle something equivalent to simple static routing. You have been warned. So in short, to configure your packet filters with Fwctl you need to 1. Define your network topology using the `interfaces' file. 2. (Optional) Define meaningful aliases for hosts and networks which are part of your configuration. 3. Implement your security policy using high level abstract rules in the rules file. Finally, Fwctl is extensible. You can easily add services modules using the Fwctl::RuleSet module which contains all the primitive you need to handle all the special cases involved in the input, forward and output chain selection. CONFIGURATION ============= Fwctl configures the Linux kernel packet filtering firewall using three files: the `interfaces' file that describes your network topology, the aliases file that can contains meaningful aliases and the rules files that contains the services policy for the firewall. TOPOLOGY -------- The `interfaces' file (default to `/etc/fwctl/interfaces') describes your firewall topology. This is a text file in which comments (starting by a # and continuing until the end of line) and blank lines are ignored. Each non blank, non comment lines is an interface specification. The format of the interfaction specification is NAME INTERFACE IP/MASK [NETWORK]* NAME This is the name of the interface. It can be anyting. (Well please keep to alphanumeric characters plus underscore). There are two reserved names and a magical one. LOCAL refers to the loopback interface and shouldn't be redefined. ANY refers to a interface matching all the defined interfaces. You should defined at least an interface named EXT which corresponds to the interface connected to the default route. This is the interface on which Internet traffic usually come and go. INTERFACE This should be set to the kernel interface name. (eth0, ppp0, tunl0, etc.) You may specifiy here alias interface (eth0:0) but the Fwctl will canonicalize the name to the master interface (eth0) to match the way the kernel 2.2 use them. IP/MASK This is the IP address and Netmask of the interface. The netmask can be specified in either netmask notation (255.255.255.0) or CIDR notation (24). NETWORKS This is an optional space separated list of IP/MASK networks connected to this interface. This is to handle internal network connected to WAN link. The `interfaces' file should correspond to your firewall network configuration. It should adequatly represent its runtime interface and routing configuration or this module is useless. ALIASES ------- The aliases file contains meaningful aliases for use in the rules file. Comments (starts with # and continues untill the end of line) and blank lines are ignored. Alias line are of the form : ALIAS [:=]+ EXPANSION ALIAS This is the mnemonic alias. For example, you could use MAIL_SERVER, CORPORATE_OFFICE, aNotSoUsefulAlias, etc. Please restrict yourself to alphanumeric character plus underscore. And be sure to read the predefined aliases section. EXPANSION This is what the alias expands to. This can be a space separated list of host or network specification or other alias. The host or network expansion can also be tagged with an interface name which specifies which interface is associated with that alias and that will be use for routing logic. If you don't specify an interface Fwctl will figure out which interface is associated to the host or network using conventional routing logic. Be warned though that if you have interfaces that shares the same IP or have the same network attached if won't do probably what you intended. If all interfaces have distinctive IP and networks it will be probably fine tough. Example : VPN_CLIENT1 = 192.168.2.10(VPN1) Aliases are recursively expanded. Please avoid infinite recursion or you will get a complaint at parse time. Here is a list of predefined aliases. (All those aliases are associated with their interface for routing pupose). INTERNET This alias represents any host or network connected through the EXT interface. ANY This alias represents any host or network connected through any interface. _IP The is an alias name IF_IP for each defined interface which corresponds to the IP address of this interface. For example, if you have defined the EXT interface and a INTERNAL interface, the aliases LOCAL_IP, EXT_IP and INTERNAL_IP. (Remenber the automatic LOCAL interface). _NET The is an alias name IF_NET for each defined interface which corresponds to the network attached to this interface. _BCAST The is an alias name IF_IP for each defined interface which corresponds to the broadcast address of this interface. _REM_NETS The is an alias name IF_IP for each defined interface which corresponds to all the networks that are routed through this interface excepted the one directly connected. _NETS The is an alias name IF_IP for each defined interface which corresponds to all the networks attached to this interface, not only the direct one. RULES ----- The rules file contains your firewall policy implementation. It is a text file that describes the policy for each services. As usual, (do I even need to mention it?) comments (starts with # and continues until the end of line) and blanks line are ignored. Rules format is : ACTION SERVICE OPTIONS ACTION What to do with this service can be one of accept, reject, deny or account. See POLICY section for explanation. SERVICE This is the name of the service which is the target of the action. The service is handled by a module called Fwctl::Services::.pm but see AUTOMATIC SERVICES. OPTIONS This is a space separated list of options which further specify what is the actual policy. Option name starts with - or - and can be abbreviated to uniquesess. Some options takes a paremeters some are flags. Read the doc. These options are module specific but see STANDARD OPTIONS section. POLICY ====== There are four possible actions for a service. These are ACCEPT, DENY, REJECT or ACCOUNT. (These are actually case insensitive). ACCEPT This will accept the service. DENY This traffic part of this service will be drop without anyone knowing. (Except probably your logs.) REJECT Traffic part of this service will be dropped with a proper message being sent to the originating party. ACCOUNT Packets part of this service will be counted. This won't accept or deny the service. Use one of the other three actions to define the actual fate of this service. SERVICE ======= A service are module that encapsulates the collection of IP traffic that are part of an application. For example, to accept or account the FTP service, you must accept two or three TCP connections, the rsh service uses two. DNS service need 1 TCP connection and an UDP circuit. The SERVICE abstraction is needed to insulates the administrator from the idiosyncrasies of the service. Needless to say that the adminstrator should be familiar with the idiosyncrasies of the service to be able to make an appropriate security judgement about the service. It's just that it is easier once the judgement has been made to accept or deny the specific service. Each service is a perl module named Fwctl::Services::name which knows the particular IP traffic that is part of this service. AUTOMATIC SERVICES ------------------ As a convenience to the administrator (and programmer) simple one way TCP service are automatically created at runtime. For example, this distribution doesn't contains a telnet service. But since the telnet service is only a tcp connection from client to the server's telnet port. If you use ACCEPT telnet in your rules, a telnet service is automatically generated as a subclass of tcp_service with a destination port of telnet. You could use in this way pop-3, imap or any protocol which has only a client/server TCP connection. OPTIONS ======= Each service can defined a number of options but here are the standard one that each service should implement. -src Specify the client part of the service. This can be a list of IP or network addresses, or aliases. Once the aliases are expanded only IP addresses must remains. When you configure your firewall DNS shouldn't be available. If you need name, that's what the aliases is for. If there are more than one IP address, it is equivalent as if you had specified a different rule with each address. (i.e.: If you have 4 IPs, this is transformed in four rules). If this option is not present. It is the same as -src ANY. -dst Specify the server part of the service. The syntax of this option is identical to the src one. -masq or -nomasq If this option is set, the firewall will masquerade this service on behalf of the client. This option is only meaningful with the ACCEPT or ACCOUNT action. With the ACCOUNT action it properly account for masqueraded traffic. That is to say that if you want to accept masqueraded telnet and want to turn on accounting for this service, you should also use the masq option to the ACCOUNT action. (Or simply use the account option). -log or -nolog This option turn on or off packet header logging for this service. Default to log for DENY or REJECT action and nolog for ACCEPT and ACCOUNT. -copy or -nocopy This option turn on or off packet copying to the `/dev/fwmonitor' device for reading by a user space program. -account This adds an ACCOUNT rule for this service with the exact same options. -mark Marks the packet with the specified integer. -name Sets the accounting name for this rule. This is easier to read than the unique name generated internally. -portfw [local_ip] The service will be interpreted as being redirected from a local address to another host on a network attached to one of the firewall interface. The optional argument is one of the IP of a defined interface. If the local_ip from which the service will redirected is unspecified, the one attached to the incoming interface will be used. When using portfw, the dst parameter can only contains hosts and all src must be compatible with the local_ip. ACCOUNTING ========== Accounting data is dump to the file `/var/log/fwctl_acct'. You should run periodically the *fwctl* program to dump the accumulated accounted data. The format of the file is: timestamp chain packets bytes name timestamp chain The unique internal name identifying this chain. (If you want to know, it is acct plus four digit number starting from 0 and incremented for each ACCOUNT chain added.) If you need to translate this anything meaningful, please use the name option. packets The number of packets related to that service. bytes The number of bytes relating to that service. name The value of the name option. BUGS AND LIMITATIONS ==================== Please report bugs, suggestions, patches and thanks to . This package is probably useless if you have something a topology that cannot be described adequatly in a simple static routing scheme. Documentation on writing services is lacking. But see the standard services for details. AUTHOR ====== Francis J. Lacoste COPYRIGHT ========= Copyright (c) 1999,2000 iNsu Innovations Inc. All rights reserved. This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with this program; if not, you can get one at http://www.gnu.org/copyleft/gpl.html SEE ALSO ======== fwctl(8) Fwctl::RuleSet(3) IPChains(3) Net::IPv4Addr(3) Fwctl::Services::all(3) Fwctl::Services::dhcp(3) Fwctl::Services::ftp(3) Fwctl::Services::http(3) Fwctl::Services::hylafax(3) Fwctl::Services::netbios(3) Fwctl::Services::ntp(3) Fwctl::Services::ping(3) Fwctl::Services::portmap(3) Fwctl::Services::rsh(3) Fwctl::Services::snmp(3) Fwctl::Services::tcp_service(3) Fwctl::Services::syslog(3) Fwctl::Services::tftp(3) Fwctl::Services::timed(3) Fwctl::Services::traceroute(3) Fwctl::Services::traffic_control(3) Fwctl::Services::udp_service(3)  File: pm.info, Node: Fwctl/AcctReport, Next: Fwctl/Report, Prev: Fwctl, Up: Module List Generates reports from `fwctl dump-acct' command. ************************************************* NAME ==== Fwctl::AcctReport - Generates reports from `fwctl dump-acct' command. SYNOPSIS ======== use Fwctl::AcctReport; my $report = new Fwctl::Report( options ... ); my $r = $report->summary_report; foreach my $r ( @$src_alias_sum ) { print $r->{name}, " = ", $r->{bytes_sum}, "\n"; } DESCRIPTION =========== The Fwctl::AcctReport(3) module can be used to generate packet and bandwith report from the data generated by the `fwctl dump-acct' command. This module can be used as backend for two kinds of report. Summary which compiles the total number of packets and bytes received by each accounting chains over the report's period or histogram type report where you have the packets and bytes total for each sample (hour, day, etc) over the report's period. CAVEATS ======= The `fwctl dump-acct' commands dumps the packets and bytes total since the time of the last invocation. If the last invocation wasn't wholly comprised in the current sample, the total will be interpolated. This means that you should run the `fwctl dump-acct' command at least as frequently as the smallest sample period you want to use. CREATING A NEW REPORT OBJECT ============================ Ex. my $report = new Fwctl::AcctReport( start => 'yesterday', period => '1 day', sample => '1d', files => [ 'log' ] ); PARAMETERS ---------- The new method accepts the following parameter : files Specifies the file from which to read the dumped acctounting informations. It is an array of file handle or file names. If this parameter is not specified the records will be read from STDIN. start Sets the start of the report's period. If the Date::Manip(3) module is installed, you can use any format that this module can parse. If that module isn't installed you must use the following format YYYY-MM-DD HH:MM:SS or any meaningful subset of that format. If this option is not used, the report will start with the first record. end Sets the end of the report's period. If the Date::Manip(3) module is installed, you can use any format that this module can parse. If that module isn't installed you must use the following format YYYY-MM-DD HH:MM:SS or any meaningful subset of that format. If this option is not used, the report will end with the last record. period Sets the length of the report's period. This length is interpreted relative to the report's start. This option has priority over the end option. If you have the Date::Manip module installed, you can use any format that this module can parse. If that module isn't available, you can use a subset of the following format X weeks X days X hours X mins X secs. sample Sets the length the sample's for the report. The sample_report will returns results aggregated over that length. For example, if you use 1d as sample's length, you will get the stats for every day from the beginning of the report until the end. If you have the Date::Manip module installed, you can use any format that this module can parse. If that module isn't available, you can use a subset of the following format X weeks X days X hours X mins X secs. names Restrict records to those whose name matches names. You can use this parameter multiple times to specify multiple possibility. The record will be included if it matches any of those. METHODS ======= start() ======= Return the start of the report in seconds since epoch. end() ===== Returns the end of the report in seconds since epoch. period() ======== Returns the length of the report's period ( $report->end() - $report->start() ) sample() ======== Returns the length of the sample period. records() ========= Returns an array reference to all the records read and which makes the report's samples. RECORD FIELDS ------------- Each record is an array ref. You can accessed the individual fields of the record by using the following constants. (Those can be imported by using the `:fields' import tag.) TIME The epoch start time of the sample. NAME The name of the accounting chain. PACKETS The number of packets received. BYTES The total number of bytes. REPORTS ======= The following report generation methods are available : summary_report() ---------------- my $r = $report->summary_report(); Generates a report that shows the compiled statistics for every accounting chain. The resulting report is an array ref of hash reference. Each report record's has the following fields. name The name of the chains. packets_sum The total number of packets over the report's period. This number is a Math::BigInt(3) object. bytes_sum The total number of bytes received over the report's period. This number is a Math::BigInt(3) object. packets_avg The average number of packets received by that chain by sample. This number is a Math::BigInt(3) object. bytes_avg The average number of packets bytes by that chain by sample. This number is a Math::BigInt(3) object. sample_report() --------------- my $r = $report->sample_report(); Generates a report that compiles the stats for each sample for each chains. The resulting report is an hash reference. Each key is a chain and each value is an array ref to the chain compiled statistics. Each element of the array is an hash reference comprises of the following elements : start The start time in seconds since epoch for that sample. packets The total number of packets received in that sample. This number is a Math::BigInt(3) object. bytes The total number of bytes received in that sample. This number is a Math::BigInt(3) object. AUTHOR ====== Francis J. Lacoste COPYRIGHT ========= Copyright (c) 2000 iNsu Innovations Inc. All rights reserved. This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. SEE ALSO ======== Fwctl(3) Fwctl::RuleSet(3) fwctl(8) fwctllog(8) fwctacctreport(8) Fwctl::Report(3) Date::Manip(3).  File: pm.info, Node: Fwctl/Report, Next: Fwctl/RuleSet, Prev: Fwctl/AcctReport, Up: Module List Generates reports from fwctllog output. *************************************** NAME ==== Fwctl::Report - Generates reports from fwctllog output. SYNOPSIS ======== use Fwctl::Report; my $report = new Fwctl::Report( options ... ); my $src_alias_sum = $report->src_alias_summary_report; foreach my $r ( @$src_alias_sum ) { print $r->{host_ip}, " = ", $r->{count}, "\n"; } DESCRIPTION =========== The Fwctl::Report(3) module can be used to generate various reports from the output of the *fwctllog* program. This module generates two kinds of report summary and . The summary compiles the number of occurence for an item (source, destination, service, etc.). The report methods will returns all the log entry that shares the same key ( source, destination, service, etc.) CREATING A NEW REPORT OBJECT ============================ Ex. my $report = new Fwctl::Report( start => 'yesterday', period => '1 day', files => [ 'log' ] ); PARAMETERS ---------- The new method accepts the following parameter : files Specifies the file from which to read the `fwctllog' output. It is an array of file handle or file names. If this parameter is not specified the records will be read from STDIN. start Sets the start of the report's period. If the Date::Manip(3) module is installed, you can use any format that this module can parse. If that module is'nt installed you must use the following format YYYY-MM-DD HH:MM:SS or any meaningful subset of that format. If this option is not used, the report will start with the first record. end Sets the end of the report's period. If the Date::Manip(3) module is installed, you can use any format that this module can parse. If that module is'nt installed you must use the following format YYYY-MM-DD HH:MM:SS or any meaningful subset of that format. If this option is not used, the report will end with the last record. period Sets the length of the report's period. This length is interpreted relative to the report's start. This option has priority over the end option. If you have the Date::Manip module installed, you can use any format that this module can parse. If that module isn't available, you can use a subset of the following format X weeks X days X hours X mins X secs. threshold This option will removed records identical in protocol, destination ports, source addresses and destination addressesses that appears in the time window specified by the threshold parameters. Defaults is 120 (2 minutes). Use 0 to generates reports for all the packets. limit This parameter can be used to restrict the records over which the report is generated. It is an expression which will be used to select a subset of all the records. You can use the following fields : src_ip, dst_ip, src_host, dst_host, action, device, src_port, dst_port, src_serv, dst_serv, proto, proto_name, and the following operator =, !=, <, >, <=, >=, /regex/, /regex/i. Those operators have the same meaning as in perl. You can also use parentheses and the following logic operator : or, and, not . METHODS ======= start() ======= Return the start of the report in seconds since epoch. end() ===== Returns the end of the report in seconds since epoch. period() ======== Returns the length of the report's period ( $report->end() - $report->start() ) records() ========= Returns an array reference to all the records read and which makes the report's sample. RECORD FIELDS ------------- Each record is an array ref. You can accessed the individual fields of the record by using the following constants. (Those can be imported by using the `:fields' import tag.) TIME The epoch time of the log entry. ACTION The resulting action (ACCEPT,DENY,REJECT). DEVICE The physical device on which the packet was logged. IF The Fwctl(3) interface to which this device is related. CHAIN The kernel chain on which that packet was logged. PROTO The protocol number. PROTO_NAME The name of the protocol. SRC_IP The source address of the packet. SRC_HOST The source hostname. SRC_IF The Fwct(3) interface related to the source address. SRC_ALIAS The Fwctl(3) alias associated to the source address. SRC_PORT The source port of the logged packet. SRC_SERV The service name associated to the logged packet. DST_IP The destination IP of the packet. DST_HOST The destination hostname. DST_IF The Fwctl(3) interface associated with the destination address. DST_ALIAS The Fwctl(3) alias related to the destination address. DST_PORT The destination port number. DST_SERV The service name of the the destination port. REPORTS ======= The following report generation methods are available : service_summary_report() ------------------------ my $r = $report->service_summary_report(); Generates a report that shows the number of log entries for each services. The resulting report is an array ref of hash reference. Each report record's has the following fields. proto The protocol number. proto_name The protocol name. dst_port The destination port. dst_serv The destination service's name. src_port If the protocol *is not* UDP or TCP, the source port. src_serv If the protocol *is not* UDP or TCP, the service name associated to the source port. count The number of log entries matching the service. first The epoch time of the first occurence. last The epoch time of the last occurence. service_report() ---------------- my $r = $report->service_report(); Generates a report that sort the log entries by service. The report is an array of arrays. Each elements of the report is an array of records which shares the same service. service_alias_summary_report() ------------------------------ my $r = $report->service_alias_summary_report(); Generates a report that shows the number of log entries for each destination aliases / service. The resulting report is an array ref of hash reference. Each report record's has the following fields. proto The protocol number. proto_name The protocol name. host_alias The alias of the destination hosts. dst_port The destination port. dst_serv The destination's service name. src_port If the protocol *is not* UDP or TCP, the source port. src_serv If the protocol *is not* UDP or TCP, the service name associated to the source port. count The number of log entries. first The epoch time of the first occurence. last The epoch time of the last occurence. service_alias_report() ---------------------- my $r = $report->service_alias_report(); Generates a report that sort the log entries by destination alias and service. The report is an array of arrays. Each elements of the report is an array of records which shares the same destination alias and service. service_host_summary_report() ----------------------------- my $r = $report->service_host_summary_report(); Generates a report that shows the number of log entries for each destination aliases / service. The resulting report is an array ref of hash reference. Each report record's has the following fields. proto The protocol number. proto_name The protocol name. host_ip The destination host ip address. host_name The destination host name. host_alias The alias of that host. dst_port The destination port. dst_serv The destination service's name. src_port If the protocol *is not* UDP or TCP, the source port. src_serv If the protocol *is not* UDP or TCP, the service name associated to the source port. count The number of log entries. first The epoch time of the first occurence. last The epoch time of the last occurence. service_host_report() --------------------- my $r = $report->service_host_report(); Generates a report that sort the log entries by destination host and service. The report is an array of arrays. Each elements of the report is an array of records which shares the same destination host and service. src_alias_summary_report() -------------------------- my $r = $report->service_alias_summary_report(); Generates a report that shows the number of log entries for each source aliases. The resulting report is an array ref of hash reference. Each report record's has the following fields. host_alias The source alias. count The number of log entries. first The epoch time of the first occurence. last The epoch time of the last occurence. src_alias_report() ------------------ my $r = $report->src_alias_report(); Generates a report that sort the log entries by source alias. The report is an array of arrays. Each elements of the report is an array of records which shares the same source alias. src_host_summary_report() ------------------------- my $r = $report->src_host_summary_report(); Generates a report that shows the number of log entries for each source host. The resulting report is an array ref of hash reference. Each report record's has the following fields. host_ip The source host ip address. host_name The source host name. host_alias The alias of the source host. count The number of log entries. first The epoch time of the first occurence. last The epoch time of the last occurence. src_host_report() ----------------- my $r = $report->src_host_report(); Generates a report that sort the log entries by source host. The report is an array of arrays. Each elements of the report is an array of records which shares the same source host. dst_alias_summary_report() -------------------------- my $r = $report->dst_alias_summary_report(); Generates a report that shows the number of log entries for each destination aliases. The resulting report is an array ref of hash reference. Each report record's has the following fields. host_alias The destination alias. count The number of log entries. first The epoch time of the first occurence. last The epoch time of the last occurence. dst_alias_report() ------------------ my $r = $report->dst_alias_report(); Generates a report that sort the log entries by destination alias. The report is an array of arrays. Each elements of the report is an array of records which shares the same destination alias. src_host_summary_report() ------------------------- my $r = $report->src_host_summary_report(); Generates a report that shows the number of log entries for each destination hosts. The resulting report is an array ref of hash reference. Each report record's has the following fields. host_ip The destination host ip address. host_name The destination host name. host_alias The alias of the destination hosts. count The number of log entries. first The epoch time of the first occurence. last The epoch time of the last occurence. dst_host_report() ----------------- my $r = $report->dst_host_report(); Generates a report that sort the log entries by destination host. The report is an array of arrays. Each elements of the report is an array of records which shares the same destination host. AUTHOR ====== Francis J. Lacoste COPYRIGHT ========= Copyright (c) 2000 iNsu Innovations Inc. All rights reserved. This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. SEE ALSO ======== Fwctl(3) Fwctl::RuleSet(3) fwctl(8) fwctllog(8) Fwctl::Report(3) Date::Manip(3).  File: pm.info, Node: Fwctl/RuleSet, Next: Fwctl/Services/all, Prev: Fwctl/Report, Up: Module List Module to add sets of rules to the linux firewall. ************************************************** NAME ==== Fwctl::RuleSet - Module to add sets of rules to the linux firewall. SYNOPSIS ======== use IPChains; use Fwctl::RuleSet qw(:masq :tcp_rulesets :ports); my $chain = new IPChains( Prot => 'tcp', SourcePort => UNPRIVILEGED_PORTS, DestPort => 23, ) accept_tcp_ruleset( $chain, $src, $src_if, $dst, $dst_if, NOMASQ ); DESCRIPTION =========== This module contains primitives to add sets of rules to the Linux packet filtering firewall implementing a particular policy. It is used primarly by service modules. The module handle all the special cases for when the src or dst interface is ANY, when masquerading is involved, when a local ip is implied by the src or dst address. All this logic has not to be implemented by the service modules, which only have to specify the kind of packets and the direction of traffic (using the src and dst paremeter). There are 5 tags that can be imported from the modules. :masq Constant used to specify how to handle masquerade. :ports Constants that refers to range of ports. :tcp_rulesets Functions that implements policy rulesets for TCP connection. :udp_rulesets Functions that implements policy rulesets for bidirectional UDP traffic. :ip_rulesets Funtions that implements policy rulesets for IP traffic. This are the primitives on which the tcp and udp rulesets are built. :masq ===== NOMASQ Constant used to represent that the traffic shouldn't be masqueraded. MASQ Constant use to denote that this traffic will be masqueraded when going throught the forward chain. UNMASQ Constant use to denote that traffic should be unmasqueraded when passing the input chain. To better understand the way the MASQ and UNMASQ constants works together lets look at how they would be use to handle a TCP connection. accept_ip_rulesets( $chain, $src, $src_if, $dst, $dst_if, MASQ ); $chain->attribute( SYN => '!' ); accept_ip_rulesets( $chain, $dst, $dst_if, $src, $src_if, UNMASQ); :ports ====== RESERVED_PORTS Constant that represents the ports 1 through 1023. UNPRIVILEGED_PORTS Constant that represents the ports 1024 through 65535. MASQ_PORTS Constant that represents the ports used when masquerading a connection : 61000 through 65096. :ip_rulesets ============ This tags imports three functions that are the primitives on which the others are built. All src or dst can be classified in one of four category. =over ANY Source or destination is any address on any interface. LOCAL_IP Source or destination is a local interface LOCAL_IMPLIED Source or destination implied a local interface. Example of those includes a broadcast address of a local interface or network address of a local interface. REMOTE Source or destination doesn't imply a local IP. So this means a total of 16 combination of source and destination address. Add the parameter MASQ,UNMASQ and NOMASQ and you got 48 possibilities. Those usually can be reduced to between 7 and 16 cases depending on the policy you want to handle. (REJECT, DENY, ACCEPT or ACCOUNT). The following functions handle all those possibilities for you, and adds the appropriate rules with address and interface specification to the appropriate chains. accept_ip_ruleset($chain,$src,$src_if,$dst,$dst_if,$masq) Adds the necessary rules to accept the kind of traffic specified by the $chain parameter. $chain IPChains objects that contains the prototypes of the rules to add to the firewall. Source, Dest and Interface parameter are overwritten by the function. $src The source address of the packet. $src_if The interface associated to the $src address. $dst The destination address of the packet. $dst_if The interface associated to the $dst address. $masq How the packet should be masqueraded. Usually the $src, $src_if, $dst and $dst_if packets are not modified by the service modules and are those passed by the Fwctl module. Or the module will switch them (dst becomes src), or change them because the protocol uses broadcast or other stuff. block_ip_ruleset( $chain, $src, $src_if, $dst, $dst_if ) This primitive handles both REJECT and DENY policies. The parameter have the same meaning as in the accept_ip_ruleset() function. account_ip_ruleset( $chain, $src, $src_if, $dst, $dst_if ) This primitive handles the ACCOUNT policy. The parameter have the same meaning as in the accept_ip_ruleset() function. :tcp_rulesets ============= This tags imports three functions: accept_tcp_ruleset(), block_tcp_ruleset() and account_tcp_ruleset() which have the same parameters and semantics as their *_ip_ruleset() counterpart. They are indeed implemented in terms of these. The difference is that the $chain parameter can only be used to represent a TCP connection. The functions will add rules for the client and server side of the connection with the SYN and ACK flags handled properly. :udp_rulesets ============= This tags imports three functions: accept_udp_ruleset(), block_udp_ruleset() and account_udp_ruleset() which have the same parameters and semantics as their *_ip_ruleset() counterpart. They are indeed implemented in terms of these. These functions will add rules to handle client / server UDP connection. It like calling the *_ip_ruleset() functions two times with the src and dst inversed (the SourcePort and DestPort are naturally also inversed). AUTHOR ====== Francis J. Lacoste COPYRIGHT ========= Copyright (c) 1999,2000 iNsu Innovations Inc. All rights reserved. This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. SEE ALSO ======== fwctl(8) Fwctl(3) IPChains(3)  File: pm.info, Node: Fwctl/Services/all, Next: Fwctl/Services/dhcp, Prev: Fwctl/RuleSet, Up: Module List Fwctl module to handle any IP traffic. ************************************** NAME ==== Fwctl::Services::all - Fwctl module to handle any IP traffic. SYNOPSIS ======== accept all -src INTERNAL_NET -dst INTERNET -masq deny all -src BAD_GUYS_NET --account account all -src PERIM_NET -dst INTERNET DESCRIPTION =========== The all module is used to match any IP traffic. It can be used for accounting all traffic between nets or to create bazooka sized hole in our filters. Needless to say that accept all is not a really secure use of this module. AUTHOR ====== Francis J. Lacoste COPYRIGHT ========= Copyright (c) 1999,2000 iNsu Innovations Inc. All rights reserved. This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. SEE ALSO ======== fwctl(8) Fwctl(3) Fwctl::RuleSet(3)  File: pm.info, Node: Fwctl/Services/dhcp, Next: Fwctl/Services/ftp, Prev: Fwctl/Services/all, Up: Module List Fwctl module to handle the dhcp protocol. ***************************************** NAME ==== Fwctl::Services::dhcp - Fwctl module to handle the dhcp protocol. SYNOPSIS ======== accept dhcp -src INTERNAL_NET -dst DHCP_SERVER deny dhcp -src INTERNAL_NET -nolog account dhcp -src INTERNAL_NET DESCRIPTION =========== This module is used to handle the DHCP protocol. It adds rules to handle the special addresses used by the DHCP protocol. Since DHCP is a broadcast based protocol restricted to local segment, so which by definition doesn't cross a firewall, who would want to use such a module ? Two use, first to prevent clutter of log files which denied dhcp broadcast packets when you are using DHCP on the internal network. Second, when your firewall is acting as a DHCP server to the internal network. ??? Who would want to do that ??? Someone trying to replace all WinGate installations with linux based solutions ;-). AUTHOR ====== Francis J. Lacoste COPYRIGHT ========= Copyright (c) 1999,2000 iNsu Innovations Inc. All rights reserved. This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. SEE ALSO ======== fwctl(8) Fwctl(3) Fwctl::RuleSet(3)  File: pm.info, Node: Fwctl/Services/ftp, Next: Fwctl/Services/http, Prev: Fwctl/Services/dhcp, Up: Module List Fwctl module to handle the FTP service. *************************************** NAME ==== Fwctl::Services::ftp - Fwctl module to handle the FTP service. SYNOPSIS ======== accept ftp -src INTERNAL_NET -dst INTERNET -noport -masq accept ftp -src PROXY_SERVER -dst INTERNET -noport --account accept ftp -src INTERNET -d FTP_SERVER -noport accept ftp -src INTERNAL_NET -dst INT_IP --ctrl_port hylafax DESCRIPTION =========== The ftp module is used to handle the FTP protocol. By default it handles both PORT and PASV based protocol. If maquerading is asked for, it also loads the proper kernel module. OPTIONS ======= In additions to the standard options it takes the following ones : -port or -noport Sets whether rules for the PORT part of the FTP protocol will be added. -pasv or -nopasv Sets whether rules for the PASV part of the FTP protocol will be added. -pasv_ports Sets the port accepted for PASV connections. Defaults to UNPRIVILEGED_PORTS. -ctrl_port Sets the port used for the control connection. This is the port on which the ftp server listens. Defaults to ftp. -data_port Sets the port for the data connection. This is the port from which PORT connections of the server originates. AUTHOR ====== Francis J. Lacoste COPYRIGHT ========= Copyright (c) 1999,2000 iNsu Innovations Inc. All rights reserved. This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. SEE ALSO ======== fwctl(8) Fwctl(3) Fwctl::RuleSet(3)  File: pm.info, Node: Fwctl/Services/http, Next: Fwctl/Services/hylafax, Prev: Fwctl/Services/ftp, Up: Module List Fwctl module to handle HTTP protocol. ************************************* NAME ==== Fwctl::Services::http - Fwctl module to handle HTTP protocol. SYNOPSIS ======== accept http -src INTERNAL_NET -dst PROXY deny http -dst MICROSOFT --nolog --account account http -src PROXY -dst INTERNET DESCRIPTION =========== The http module is used to control traffic which should be part of an HTTP connection. It use the option port which should contains a comma separated list of port which are open for TCP connections. Defaults to 80. THIS IS NOT A PROXY. It only open a bunch of TCP port to which connection can be attempted. You have been warned. AUTHOR ====== Francis J. Lacoste COPYRIGHT ========= Copyright (c) 1999,2000 iNsu Innovations Inc. All rights reserved. This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. SEE ALSO ======== fwctl(8) Fwctl(3) Fwctl::RuleSet(3)  File: pm.info, Node: Fwctl/Services/hylafax, Next: Fwctl/Services/icmp_pkt, Prev: Fwctl/Services/http, Up: Module List Fwctl module to handle the HylaFax protocol. ******************************************** NAME ==== Fwctl::Services::hylafax - Fwctl module to handle the HylaFax protocol. SYNOPSIS ======== accept hylafax -src INTERNAL_NET -dst INT_IP DESCRIPTION =========== The hylafax module is used to handle the HylaFAX protocol which is a variant of the FTP protocol. OPTIONS ======= No service specific options. AUTHOR ====== Francis J. Lacoste COPYRIGHT ========= Copyright (c) 1999,2000 iNsu Innovations Inc. All rights reserved. This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. SEE ALSO ======== fwctl(8) Fwctl(3) Fwctl::RuleSet(3)  File: pm.info, Node: Fwctl/Services/icmp_pkt, Next: Fwctl/Services/ip_pkt, Prev: Fwctl/Services/hylafax, Up: Module List Fwctl module to handle arbitrary ICMP packet. ********************************************* NAME ==== Fwctl::Services::icmp_pkt - Fwctl module to handle arbitrary ICMP packet. SYNOPSIS ======== accept icmp_pkt -src INT_IP -dst INT_NET --code redirect DESCRIPTION =========== This module can be use to add rules for arbitrary ICMP packets. Use the -code option to specify the ICMP code of the packet to build the rules for. AUTHOR ====== Francis J. Lacoste COPYRIGHT ========= Copyright (c) 1999,2000 iNsu Innovations Inc. All rights reserved. This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. SEE ALSO ======== fwctl(8) Fwctl(3) Fwctl::RuleSet(3)  File: pm.info, Node: Fwctl/Services/ip_pkt, Next: Fwctl/Services/ipsec, Prev: Fwctl/Services/icmp_pkt, Up: Module List Fwctl module to handle non UDP/TCP/ICMP packets. ************************************************ NAME ==== Fwctl::Services::ip_pkt - Fwctl module to handle non UDP/TCP/ICMP packets. SYNOPSIS ======== accept ip_pkt -src LOCAL_NET -dst REMOTE_IPIP --protocol ipip DESCRIPTION =========== This module can be use to add rules for other IP protocols than UDP, TCP or ICMP. Use the -protocol option to specify the protocol. AUTHOR ====== Francis J. Lacoste COPYRIGHT ========= Copyright (c) 1999,2000 iNsu Innovations Inc. All rights reserved. This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. SEE ALSO ======== fwctl(8) Fwctl(3) Fwctl::RuleSet(3)