README.ipv6

                    Sanewall IPv6 Support

Introduction
============
This version of sanewall has experimental IPv6 support. It will attempt
to load both iptables and ip6tables entries for all rules, with the
following exceptions:

1. Explicitly stated version e.g.:

   interface wlan0 internet
      ipv4 masquerade
      ipv6 server ssh allow

   Will only enable masquerading on IPv4 and ssh access via IPv6.

2. Implicit by protocol or address e.g.:

   interface eth0 lan
      server telnet accept src "192.168.0.0/24"
      server ftp accept src "fe80::/64"
      server ssh accept src "fe80::/64 192.168.0.0/24"

   All should do the "right thing" and allow mix and match of addresses.

   Note that "src" can confuse complex rules at present and "src not" can
   confuse even simple rules so to avoid errors, rather than:
      server ping accept src "${ip_mix}"

      server ssh accept src not "${ip_mix}"

   write intead:
      ivp4 server ping accept src "${ip_v4}"
      ivp6 server ping accept src "${ip_v6}"

      ipv4 server ssh accept src not "${ip_v4}"
      ipv6 server ssh accept src not "${ip_v6}"

3. ICMP and ICMPv6 are not identical. You will get warnings and/or errors
   if you try to include rules for an ICMP packet type for ICMPv6 and
   vice-versa e.g.:

   interface eth0 lan
      client timestamp accept

   will issue a warning, but:

   interface eth0 lan
      ipv4 timestamp client accept

   will not, the reason being that the icmp packets timestamp-request and
   timestamp-reply have no equivalent in icmpv6.

   New ipv6-only marked protocols (e.g. ipv6router, ipv6neigh) will not
   warn in "both" mode, only in "ipv4" mode.

4. Automatic configuration is used via icmpv6. There is no ARP and no
   need to manually configure routers. To enable this functionality
   the network neighbour and router solicitation/advertisement messages
   should be enabled on each interface. These rules are stateless
   since advertisement can happen automatically as well as on solicitation.

   Neigbour discovery (incoming) should always be enabled:
      server ipv6neigh accept

   Neigbour advertisement (outgoing) should always be enabled:
      client ipv6neigh accept

   Router discovery (incoming) should always be enabled:
      client ipv6router accept

   Router advertisement (outgoing) should be enabled on a host that routes:
      server ipv6router accept

   The rules should not be used to pass packets accross a firewall
   unless it is a bridge.

5. Various icmpv6 error messages need to be allowed for correct operation
   of IPv6.

   These following are handled by the ipv6error complex rule:
       destination-unreachable
       packet-too-big
       ttl-zero-during-transit
       ttl-zero-during-reassembly
       unknown-header-type
       unknown-option

   Which should be adequate for most purposes. See "The ipv6error Complex Rule"
   below for usage information.

6. The RESERVED_IPS, PRIVATE_IPS and MULTICAST_IPS files have been replaced
   with:
      RESERVED_IPV4, PRIVATE_IPV4 and MULTICAST_IPV4 for IPv4
      RESERVED_IPV6, PRIVATE_IPV6 and MULTICAST_IPV6 for IPv6

There is a really basic example in examples/ipv6.conf.


The ipv6error Complex Rule
==========================
A number of icmpv6 error types are not treated equally inbound and outbound.
The ipv6error rule wraps all of them in the following way:

 - allow incoming messages only for existing sessions
 - allow outgoing messages always

Firehol sets up both rules the same way. In a router with inface being
internal and outface being external the following will meet the
recommendations:
  server ipv6error accept

Interfaces should always have:
  server ipv6error accept
set.

Do not use:
  client ipv6error accept
unless you are controlling traffic on an router interface where outface
is the internal destination.

Known Issues
============
1. There are a variety of icmpv6 packet types without helpers and
   not described here yet which are needed for full handling of IPv6.

   The ipv6error packet rules have not been thoroughly tested.

   A full set of icmpv6 recommendations that ought to be implemented are
   here:
     http://tools.ietf.org/html/rfc4890

   The recommendations, and how to achieve them (and where there is
   still work to do) are listed in:
     doc/rfc4890-noted.txt

2. There is no Linux kernel NAT support for IPv6, you will get errors
   if you try to use it.

   The masquerade command automatically defaults to ipv4 only.

   A kernel module may be available from somewhere in which case you might
   be able to get it to work. You probably don't want to NAT for nearly as
   much as with ipv4 though.

3. No way to mark a block of commands as ipv4 or ipv6 only

   Allowing a mode switch leads the possibility of accidentally not
   switching back and possible security implications.

   There hopefully aren't too many situations where one would want
   to issue many rules for just one or the other which can't be
   dealt with by the automatic address detection routines.

4. Private / Unroutable IPv6 lists are woefully incomplete.

5. IPv4/IPv6 detection in iptables() could probably be improved

6. The following commands have not received any testing and may not
   work as expected:
	restart
	condrestart
	status
	panic
	save
	explain
	helpme/wizard

7. Creating a rule which applies only to one ip type will lead to
   empty chains e.g.:
      server ssh accept src "10.0.0.0/8"

   will create two chains, one using iptables and the other using
   ip6tables; only the iptables chain has any rules added to it. This
   should not cause any problems, but can look odd when inspecting
   the tables directly.

Troubleshooting Autoconfiguration
=================================
I believe that with correct setup of interfaces (i.e. allowing NA/NS, RA/RS
as appropriate) there will no longer be problems with autoconfigutation of
ipv6.

If you do experience problems though, the following can be added to the top of
your configuration to enable all icmpv6 to the firewall interfaces which
may help until there is a proper resolution.

There is some additional risk and any problems related to the forwarding
of packets through a firewall will not be addressed by the workaround:

   icmpv6_allow() {
      for iface in "$@"
      do
         iptables -j ACCEPT -I INPUT 1 -i "$iface" -p icmpv6
         iptables -j ACCEPT -I OUTPUT 1 -o "$iface" -p icmpv6
      done
   }

You call the function for the various interfaces before setting
them up e.g.:

   icmpv6_allow $wanif $lanif

   interface "$wanif" wan
      protection strong
      policy deny

Note that iptables is called: this is a function provided by firehol, not
the external command so it gets correctly turned into an ip6tables command
due to the use of protocol icmpv6.