From owner-svn-doc-all@freebsd.org Mon Feb 17 18:35:57 2020 Return-Path: Delivered-To: svn-doc-all@mailman.nyi.freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2610:1c1:1:606c::19:1]) by mailman.nyi.freebsd.org (Postfix) with ESMTP id B5A9C242355; Mon, 17 Feb 2020 18:35:57 +0000 (UTC) (envelope-from bcr@FreeBSD.org) Received: from mxrelay.nyi.freebsd.org (mxrelay.nyi.freebsd.org [IPv6:2610:1c1:1:606c::19:3]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) server-signature RSA-PSS (4096 bits) client-signature RSA-PSS (4096 bits) client-digest SHA256) (Client CN "mxrelay.nyi.freebsd.org", Issuer "Let's Encrypt Authority X3" (verified OK)) by mx1.freebsd.org (Postfix) with ESMTPS id 48Lt3K5681z4f6b; Mon, 17 Feb 2020 18:35:57 +0000 (UTC) (envelope-from bcr@FreeBSD.org) Received: from repo.freebsd.org (repo.freebsd.org [IPv6:2610:1c1:1:6068::e6a:0]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (Client did not present a certificate) by mxrelay.nyi.freebsd.org (Postfix) with ESMTPS id 557FBB381; Mon, 17 Feb 2020 18:35:57 +0000 (UTC) (envelope-from bcr@FreeBSD.org) Received: from repo.freebsd.org ([127.0.1.37]) by repo.freebsd.org (8.15.2/8.15.2) with ESMTP id 01HIZv6C005084; Mon, 17 Feb 2020 18:35:57 GMT (envelope-from bcr@FreeBSD.org) Received: (from bcr@localhost) by repo.freebsd.org (8.15.2/8.15.2/Submit) id 01HIZvbB005083; Mon, 17 Feb 2020 18:35:57 GMT (envelope-from bcr@FreeBSD.org) Message-Id: <202002171835.01HIZvbB005083@repo.freebsd.org> X-Authentication-Warning: repo.freebsd.org: bcr set sender to bcr@FreeBSD.org using -f From: Benedict Reuschling Date: Mon, 17 Feb 2020 18:35:57 +0000 (UTC) To: doc-committers@freebsd.org, svn-doc-all@freebsd.org, svn-doc-head@freebsd.org Subject: svn commit: r53911 - head/en_US.ISO8859-1/books/handbook/firewalls X-SVN-Group: doc-head X-SVN-Commit-Author: bcr X-SVN-Commit-Paths: head/en_US.ISO8859-1/books/handbook/firewalls X-SVN-Commit-Revision: 53911 X-SVN-Commit-Repository: doc MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit X-BeenThere: svn-doc-all@freebsd.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: "SVN commit messages for the entire doc trees \(except for " user" , " projects" , and " translations" \)" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Mon, 17 Feb 2020 18:35:57 -0000 Author: bcr Date: Mon Feb 17 18:35:56 2020 New Revision: 53911 URL: https://svnweb.freebsd.org/changeset/doc/53911 Log: - Simplify multiple sentences to remove the words: furthermore, also, ... - Fix typo's, IP address is redirect_port example & visible double space after sentence stop - Restructure TSO comment together with the in-kernel NAT instance paragraph - Add kernel option for libalias full functionality - Unify engine/facility/... to facility Submitted by: Dries Michiels (driesm.michiels_gmail.com) Approved by: bcr@ Differential Revision: https://reviews.freebsd.org/D23426 Modified: head/en_US.ISO8859-1/books/handbook/firewalls/chapter.xml Modified: head/en_US.ISO8859-1/books/handbook/firewalls/chapter.xml ============================================================================== --- head/en_US.ISO8859-1/books/handbook/firewalls/chapter.xml Mon Feb 17 17:40:47 2020 (r53910) +++ head/en_US.ISO8859-1/books/handbook/firewalls/chapter.xml Mon Feb 17 18:35:56 2020 (r53911) @@ -2153,15 +2153,13 @@ pif="dc0" # interface name of NIC attached to Inte &os;'s IPFW firewall has two - implementations of NAT: one being the - userland &man.natd.8; daemon, and the more recent - IPFW's built-in - NAT facility also known as in-kernel - NAT. Both work in conjunction with - IPFW to provide network address - translation. This can be used to provide an Internet - Connection Sharing solution so that several internal computers - can connect to the Internet using a single public + implementations of NAT: the userland + implementation &man.natd.8;, and the more recent in-kernel + NAT implementation. Both work in + conjunction with IPFW to provide + network address translation. This can be used to provide an + Internet Connection Sharing solution so that several internal + computers can connect to the Internet using a single public IP address. To do this, the &os; machine connected to the Internet @@ -2176,7 +2174,7 @@ pif="dc0" # interface name of NIC attached to Inte 1918. Some additional configuration is needed in order to enable - the in-kernel NAT function of + the in-kernel NAT facility of IPFW. To enable in-kernel NAT support at boot time, the following must be set in /etc/rc.conf: @@ -2186,9 +2184,9 @@ firewall_enable="YES" firewall_nat_enable="YES" - When firewall_enable is not set, - but firewall_nat_enable is, it will have - no effect and do nothing, because the in-kernel + When firewall_nat_enable is set but + firewall_enable is not, it will have no + effect and do nothing. This is because the in-kernel NAT implementation is only compatible with IPFW. @@ -2196,30 +2194,16 @@ firewall_nat_enable="YES" of the NAT rule is critical and the skipto action is used. The skipto action requires a rule number so - that it knows which rule to jump to. Furthermore, because - of the architecture of &man.libalias.3;, a library implemented - as a kernel module used for the in-kernel - NAT facility of - IPFW, it is necessary to disable - TCP segmentation offloading, or in short - TSO. TSO can be - disabled on a per network interface basis by using - &man.ifconfig.8; or on a system wide basis using - &man.sysctl.8;. To disable TSO system - wide, the following must be set in - /etc/sysctl.conf: + that it knows which rule to jump to. The example below builds + upon the firewall ruleset shown in the previous section. It + adds some additional entries and modifies some existing rules + in order to configure the firewall for in-kernel + NAT. It starts by adding some additional + variables which represent the rule number to skip to, the + keep-state option, and a list of + TCP ports which will be used to reduce the + number of rules. - net.inet.tcp.tso="0" - - The example below builds upon the firewall ruleset - shown in the previous section. It adds some additional - entries and modifies some existing rules in order to configure - the firewall for in-kernel NAT. It starts - by adding some additional variables which represent the rule - number to skip to, the keep-state option, - and a list of TCP ports which will be used - to reduce the number of rules. - #!/bin/sh ipfw -q -f flush cmd="ipfw -q add" @@ -2228,28 +2212,41 @@ pif=dc0 ks="keep-state" good_tcpo="22,25,37,53,80,443,110" - A NAT instance will also be - configured. With in-kernel NAT it is - possible to have multiple NAT instances - each with their own configuration. Although, for this example - only one NAT instance is needed; + With in-kernel NAT it is + necessary to disable TCP segmentation offloading + (TSO) due to the architecture of + &man.libalias.3;, a library implemented as a kernel module to + provide the in-kernel NAT facility of + IPFW. TSO can + be disabled on a per network interface basis using + &man.ifconfig.8; or on a system wide basis using + &man.sysctl.8;. To disable TSO system + wide, the following must be set it + /etc/sysctl.conf: + + net.inet.tcp.tso="0" + + A NAT instance will also be configured. + It is possible to have multiple NAT + instances each with their own configuration. For this example + only one NAT instance is needed, NAT instance number 1. The configuration - takes a few arguments and flags such as: - which indicates the public interface, - which takes care that alliased - ports and local port numbers are mapped the same, - will result in only unregistered - (private) address spaces to be processed by the - NAT instance, and - which will help to keep a functioning NAT - instance even when the public IP address of - the IPFW machine changes. For all + can take a few options such as: which + indicates the public interface, + which takes care that alliased ports and local port numbers + are mapped the same, will result + in only unregistered (private) address spaces to be processed + by the NAT instance, and + which will help to keep a functioning + NAT instance even when the public + IP address of the + IPFW machine changes. For all possible options that can be passed to a single NAT instance configuration consult - &man.ipfw.8;. Furthermore, because of the nature of a - stateful NATing firewall, it is neseccary - to allow translated packets to be reinjected in the firewall - for further processing, this can be achieved by disabling + &man.ipfw.8;. When configuring a stateful + NATing firewall, it is neseccary to allow + translated packets to be reinjected in the firewall for + further processing. This can be achieved by disabling behavior at the start of the firewall script. @@ -2272,21 +2269,21 @@ ipfw -q nat 1 config if $pif same_ports unreg_o happen, but when dealing with IPSEC/ESP/GRE tunneling traffic it might and the reassmabling of fragments is necessary before handing the complete packet over to the - in-kernel NAT engine. + in-kernel NAT facility. The reassemble rule was not needed with userland &man.natd.8; because the internal workings of the IPFW divert - action already takes care of this automatically as also - stated in &man.ipfw.8;. + action already takes care of reassambling packets before + delivery to the socket as also stated in &man.ipfw.8;. - The current NAT instance number and - NAT rule number does not match with the - default NAT instance number and rule - number created by rc.firewall which is - a script to set up the baked-in default firewall rulesets - present in &os;. + The NAT instance and rule number used + in this example does not match with the default + NAT instance and rule number created by + rc.firewall. + rc.firewall is a script that sets up + the default firewall rules present in &os;. $cmd 005 allow all from any to any via xl0 # exclude LAN traffic $cmd 010 allow all from any to any via lo0 # exclude loopback traffic @@ -2306,8 +2303,8 @@ ipfw -q nat 1 config if $pif same_ports unreg_o Remember that IPFW's - firewall performance is largely determined by the number of - rules present in the ruleset. + performance is largely determined by the number of rules + present in the ruleset. # Authorized outbound packets $cmd 120 $skip udp from any to x.x.x.x 53 out via $pif $ks @@ -2375,17 +2372,18 @@ ipfw -q nat 1 config if $pif same_ports unreg_o interface. - Transition from userland &man.natd.8; to in-kernel + Transitioning from userland &man.natd.8; to in-kernel NAT might seem seamless at first but there is small catch. When using the GENERIC kernel, IPFW will load the - libalias.ko - kernel module, when firewall_nat_enable - is enabled in rc.conf. Although, the - loaded module only provides basic NAT - functionality, whereas the userland implementation - &man.natd.8; has all functionality available without any - extra configuration from its userland library. All + libalias.ko kernel module, when + firewall_nat_enable is enabled in + rc.conf. The + libalias.ko kernel module only provides + basic NAT functionality, whereas the + userland implementation &man.natd.8; has all + NAT functionality available in its + userland library without any extra configuration. All functionality refers to the following kernel modules that can additionally be loaded when needed besides the standard libalias.ko kernel module: @@ -2396,10 +2394,9 @@ ipfw -q nat 1 config if $pif same_ports unreg_o alias_pptp.ko and alias_smedia.ko using the kld_list directive in - rc.conf to mimic the full functionality - of the userland implementation. If a custom kernel is used, + rc.conf. If a custom kernel is used, the full functionality of the userland library can be - compiled in, in the kernel, using the . @@ -2450,7 +2447,7 @@ redirect_port tcp 192.168.0.3:80 80 ipfw -q nat 1 config if $pif same_ports unreg_only reset \ redirect_port tcp 192.168.0.2:6667 6667 \ - redirect_port tcp 192.1683.0.3:80 80 + redirect_port tcp 192.168.0.3:80 80 Port ranges over individual ports can be indicated with . For example, @@ -2518,7 +2515,7 @@ redirect_address 192.168.0.3 128.1.1.3Let us start with a statement: the userspace NAT implementation: &man.natd.8;, has - more overhead than in-kernel NAT. For + more overhead than in-kernel NAT. For &man.natd.8; to translate packets, the packets have to be copied from the kernel to userspace and back which brings in extra overhead that is not present with in-kernel @@ -2539,13 +2536,13 @@ natd_interface="rl0" In general, the above ruleset as explained for in-kernel NAT can also be used together with - &man.natd.8;. The only exceptions are the configuration of - the in-kernel NAT instance (ipfw - -q nat 1 config ...) not being applicable any - more, rule number 100 and 1000 will have to change sligthly - as below, and reassemble rule 99 is not needed anymore - as the action is used which covers - fragmentation. + &man.natd.8;. The exceptions are the configuration of the + in-kernel NAT instance (ipfw -q + nat 1 config ...) which is not needed together + with reassemble rule 99 because its functionality is + included in the action. Rule number + 100 and 1000 will have to change sligthly as shown + below. $cmd 100 divert natd ip from any to any in via $pif $cmd 1000 divert natd ip from any to any out via $pif @@ -2777,7 +2774,8 @@ ks="keep-state" # just too lazy to key this eac options IPFIREWALL_VERBOSE # enables logging for rules with log keyword to syslogd(8) options IPFIREWALL_VERBOSE_LIMIT=5 # limits number of logged packets per-entry options IPFIREWALL_DEFAULT_TO_ACCEPT # sets default policy to pass what is not explicitly denied -options IPFIREWALL_NAT # enables in-kernel NAT support +options IPFIREWALL_NAT # enables basic in-kernel NAT support +options LIBALIAS # enables full in-kernel NAT support options IPFIREWALL_NAT64 # enables in-kernel NAT64 support options IPFIREWALL_NPTV6 # enables in-kernel IPv6 NPT support options IPFIREWALL_PMOD # enables protocols modification module support