docs: Added All FreeBSD Manuals

1 files changed, 313 insertions, 0 deletions

diff --git a/static/freebsd/man5/ippool.5 b/static/freebsd/man5/ippool.5
new file mode 100644
index 00000000..1ab8681b
--- /dev/null
+++ b/static/freebsd/man5/ippool.5
@@ -0,0 +1,313 @@
+.\"
+.TH IPPOOL 5
+.SH NAME
+ippool, ippool.conf \- IP Pool file format
+.SH DESCRIPTION
+The file ippool.conf is used with ippool(8) to configure address pools for
+use with ipnat(8) and ipf(8).
+.PP
+There are four different types of address pools that can be configured
+through ippool.conf. The various types are presented below with a brief
+description of how they are used:
+.HP
+dstlist
+.IP
+destination list - is a collection of IP addresses with an optional
+network interface name that can be used with either redirect (rdr) rules
+in ipnat.conf(5) or as the destination in ipf.conf(5) for policy based
+routing.
+.HP
+group-map
+.IP
+group maps - support the srcgrpmap and dstgrpmap call functions in
+ipf.conf(5) by providing a list of addresses or networks rule group
+numbers to start processing them with.
+.HP
+hash
+.IP
+hash tables - provide the means for performing a very efficient
+lookup address or network when there is expected to be only one
+exact match. These are best used with more static sets of addresses
+so they can be sized optimally.
+.HP
+pool
+.IP
+address pools - are an alternative to hash tables that can perform just
+as well in most circumstances. In addition, the address pools allow for
+heirarchical matching, so it is possible to define a subnet as matching
+but then exclude specific addresses from it.
+.SS
+Evolving Configuration
+Over time the configuration syntax used by ippool.conf(5) has evolved.
+Originally the syntax used was more verbose about what a particular
+value was being used for, for example:
+.PP
+.nf
+table role = ipf type = tree number = 100
+        { 1.1.1.1/32; !2.2.0.0/16; 2.2.2.0/24; ef00::5/128; };
+.fi
+.PP
+This is rather long winded. The evolution of the configuration syntax
+has also replaced the use of numbers with names, although numbers can
+still be used as can be seen here:
+.PP
+.nf
+pool ipf/tree (name "100";)
+	{ 1.1.1.1/32; !2.2.0.0/16; 2.2.2.0/24; ef00::5/128; };
+.fi
+.PP
+Both of the above examples produce the same configuration in the kernel
+for use with ipf.conf(5).
+.PP
+Newer options for use in ippool.conf(5) will only be offered in the new
+configuration syntax and all output using "ippool -l" will also be in the
+new configuration syntax.
+.SS
+IPFilter devices and pools
+To cater to different administration styles, ipool.conf(5) allows you to
+tie a pool to a specific role in IPFilter. The recognised role names are:
+.HP
+ipf
+.IP
+pools defined for role "ipf" are available for use with all rules that are
+found in ipf.conf(5) except for auth rules.
+.HP
+nat
+.IP
+pools defined for role "nat" are available for use with all rules that are
+found in ipnat.conf(5).
+.HP
+auth
+.IP
+pools defined for role "auth" are available only for use with "auth" rules
+that are found in ipf.conf(5)
+.HP
+all
+.IP
+pools that are defined for the "all" role are available to all types of
+rules, be they NAT rules in ipnat.conf(5) or firewall rules in ipf.conf(5).
+.SH Address Pools
+An address pool can be used in ipf.conf(5) and ipnat.conf(5) for matching
+the source or destination address of packets. They can be referred to either
+by name or number and can hold an arbitrary number of address patterns to
+match.
+.PP
+An address pool is considered to be a "tree type". In the older configuration
+style, it was necessary to have "type=tree" in ippool.conf(5). In the new
+style configuration, it follows the IPFilter device with which the pool
+is being configured.
+Now it is the default if left out.
+.PP
+For convenience, both IPv4 and IPv6 addresses can be stored in the same
+address pool. It should go without saying that either type of packet can
+only ever match an entry in a pool that is of the same address family.
+.PP
+The address pool searches the list of addresses configured for the best
+match. The "best match" is considered to be the match that has the highest
+number of bits set in the mask. Thus if both 2.2.0.0/16 and 2.2.2.0/24 are
+present in an address pool, the address 2.2.2.1 will match 2.2.2.0/24 and
+2.2.1.1 will match 2.2.0.0/16. The reason for this is to allow exceptions
+to be added through the use of negative matching. In the following example,
+the pool contains "2.2.0.0/16" and "!2.2.2.0/24", meaning that all packets
+that match 2.2.0.0/16, except those that match 2.2.2.0/24, will be considered
+as a match for this pool.
+.PP
+table role = ipf type = tree number = 100
+        { 1.1.1.1/32; 2.2.0.0/16; !2.2.2.0/24; ef00::5/128; };
+.PP
+For the sake of clarity and to aid in managing large numbers of addresses
+inside address pools, it is possible to specify a location to load the
+addresses from. To do this simply use a "file://" URL where you would
+specify an actual IP address.
+.PP
+.nf
+pool ipf/tree (name rfc1918;) { "file:///etc/ipf/rfc1918"; };
+.fi
+.PP
+The contents of the file might look something like this:
+.PP
+.nf
+# RFC 1918 networks
+10.0.0.0/8
+!127.0.0.0/8
+172.16.0.0/12
+192.168.0.0/24
+.fi
+.PP
+In this example, the inclusion of the line "!127.0.0.0/8" is, strictly
+speaking not correct and serves only as an example to show that negative
+matching is also supported in this file.
+.PP
+Another format that ippool(8) recognises for input from a file is that
+from whois servers. In the following example, output from a query to a
+WHOIS server for information about which networks are associated with
+the name "microsoft" has been saved in a file named "ms-networks".
+There is no need to modify the output from the whois server, so using
+either the whois command or dumping data directly from it over a TCP
+connection works perfectly file as input.
+.PP
+.nf
+pool ipf/tree (name microsoft;) { whois file "/etc/ipf/ms-networks"; };
+.fi
+.PP
+And to then block all packets to/from networks defined in that file,
+a rule like this might be used:
+.PP
+.nf
+block in from pool/microsoft to any
+.fi
+.PP
+Note that there are limitations on the output returned by whois servers
+so be aware that their output may not be 100% perfect for your goal.
+.SH Destination Lists
+Destination lists are provided for use primarily with NAT redirect rules
+(rdr). Their purpose is to allow more sophisticated methods of selecting
+which host to send traffic to next than the simple round-robin technique
+that is present with with "round-robin" rules in ipnat.conf(5).
+.PP
+When building a list of hosts to use as a redirection list, it is
+necessary to list each host to be used explicitly. Expressing a
+collection of hosts as a range or a subnet is not supported. With each
+address it is also possible to specify a network interface name. The
+network interface name is ignored by NAT when using destination lists.
+The network itnerface name is currently only used with policy based
+routing (use of "to"/"dup-to" in ipf.conf(5)).
+.PP
+Unlike the other directives that can be expressed in this file, destination
+lists must be written using the new configuration syntax. Each destination
+list must have a name associated with it and a next hop selection policy.
+Some policies have further options. The currently available selection
+policies are:
+.HP
+round-robin
+.IP
+steps through the list of hosts configured with the destination list
+one by one
+.HP
+random
+.IP
+the next hop is chosen by random selection from the list available
+.HP
+src-hash
+.IP
+a hash is made of the source address components of the packet
+(address and port number) and this is used to select which
+next hop address is used
+.HP
+dst-hash
+.IP
+a hash is made of the destination address components of the packet
+(address and port number) and this is used to select which
+next hop address is used
+.HP
+hash
+.IP
+a hash is made of all the address components in the packet
+(addresses and port numbers) and this is used to select which
+next hop address is used
+.HP
+weighted
+.IP
+selecting a weighted policy for destination selection needs further
+clarification as to what type of weighted selection will be used.
+The sub-options to a weighted policy are:
+.RS
+.HP
+connection
+.IP
+the host that has received the least number of connections is selected
+to be the next hop. When all hosts have the same connection count,
+the last one used will be the next address selected.
+.RE
+.PP
+The first example here shows 4 destinations that are used with a
+round-robin selection policy.
+.PP
+.nf
+pool nat/dstlist (name servers; policy round-robin;)
+        { 1.1.1.2; 1.1.1.4; 1.1.1.5; 1.1.1.9; };
+.fi
+.PP
+In the following example, the destination is chosen by whichever has
+had the least number of connections. By placing the interface name
+with each address and saying "all/dstlist", the destination list can
+be used with both ipnat.conf(5) and ipf.conf(5).
+.PP
+.nf
+pool all/dstlist (name servers; policy weighted connection;)
+        { bge0:1.1.1.2; bge0:1.1.1.4; bge1:1.1.1.5; bge1:1.1.1.9; };
+.fi
+.SH Group maps
+Group maps are provided to allow more efficient processing of packets
+where there are a larger number of subnets and groups of rules for those
+subnets. Group maps are used with "call" rules in ipf.conf(5) that
+use the "srcgrpmap" and "dstgrpmap" functions.
+.PP
+A group map declaration must mention which group is the default group
+for all matching addresses to be applied to. Then inside the list of
+addresses and networks for the group, each one may optionally have
+a group number associated with it. A simple example like this, where
+the first two entries would map to group 2020 but 5.0.0.0/8 sends
+rule processing to group 2040.
+.PP
+.nf
+group-map out role = ipf number = 2010 group = 2020
+        { 2.2.2.2/32; 4.4.0.0/16; 5.0.0.0/8, group = 2040; };
+.fi
+.PP
+An example that outlines the real purpose of group maps is below,
+where each one of the 12 subnets is mapped to a different group
+number. This might be because each subnet has its own policy and
+rather than write a list of twelve rules in ipf.conf(5) that match
+the subnet and branch off with a head statement, a single rule can
+be used with this group map to achieve the same result.
+.PP
+.nf
+group-map ( name "2010"; in; )
+    { 192.168.1.0/24, group = 10010; 192.168.2.0/24, group = 10020;
+      192.168.3.0/24, group = 10030; 192.168.4.0/24, group = 10040;
+      192.168.5.0/24, group = 10050; 192.168.6.0/24, group = 10060;
+      192.168.7.0/24, group = 10070; 192.168.8.0/24, group = 10080;
+      192.168.9.0/24, group = 10090; 192.168.10.0/24, group = 10100;
+      192.168.11.0/24, group = 10110; 192.168.12.0/24, group = 10120;
+    };
+.fi
+.PP
+The limitation with group maps is that only the source address or the
+destination address can be used to map the packet to the starting group,
+not both, in your ipf.conf(5) file.
+.SH Hash Tables
+The hash table is operationally similar to the address pool. It is
+used as a store for a collection of address to match on, saving the
+need to write a lengthy list of rules. As with address pools, searching
+will attempt to find the best match - an address specification with the
+largest contiguous netmask.
+.PP
+Hash tables are best used where the list of addresses, subnets and
+networks is relatively static, which is something of a contrast to
+the address pool that can work with either static or changing
+address list sizes.
+.PP
+Further work is still needed to have IPFilter correctly size and tune
+the hash table to optimise searching. The goal is to allow for small to
+medium sized tables to achieve close to O(1) for either a positive or
+negative match, in contrast to the address pool, which is O(logn).
+.PP
+The following two examples build the same table in the kernel, using
+the old configuration format (first) and the new one (second).
+.PP
+.nf
+table role=all type=hash name=servers size=5
+        { 1.1.1.2/32; 1.1.1.3/32; 11.23.44.66/32; };
+
+pool all/hash (name servers; size 5;)
+	{ 1.1.1.2; 1.1.1.3; 11.23.44.66; };
+.fi
+.SH FILES
+/dev/iplookup
+.br
+/etc/ippool.conf
+.br
+/etc/hosts
+.SH SEE ALSO
+ippool(8), hosts(5), ipf(5), ipf(8), ipnat(8)