gistfile1.txt

firewall
========
This type provides the capability to manage firewall rules within
puppet.

**Autorequires:**

If Puppet is managing the iptables or ip6tables chains specified in the
`chain` or `jump` parameters, the firewall resource will autorequire
those firewallchain resources.

If Puppet is managing the iptables or iptables-persistent packages, and
the provider is iptables or ip6tables, the firewall resource will
autorequire those packages to ensure that any required binaries are
installed.



Parameters
----------

- **action**
    This is the action to perform on a match. Can be one of:
    
    * accept - the packet is accepted
    * reject - the packet is rejected with a suitable ICMP response
    * drop - the packet is dropped
    
    If you specify no value it will simply match the rule but perform no
    action unless you provide a provider specific parameter (such as
    *jump*).
  Valid values are `accept`, `reject`, `drop`.

- **burst**
    Rate limiting burst value (per second) before limit checks apply.
      Values can match `/^\d+$/`.  Requires features rate_limiting.

- **chain**
    Name of the chain to use. Can be one of the built-ins:
    
    * INPUT
    * FORWARD
    * OUTPUT
    * PREROUTING
    * POSTROUTING
    
    Or you can provide a user-based chain.
    
    The default value is 'INPUT'.
      Values can match `/^[a-zA-Z0-9\-_]+$/`.  Requires features iptables.

- **destination**
    The destination address to match. For example:
    
        destination => '192.168.1.0/24'
    
    The destination can also be an IPv6 address if your provider supports
    it.

- **dport**
    The destination port to match for this filter (if the protocol supports
    ports). Will accept a single element or an array.
    
    For some firewall providers you can pass a range of ports in the format:
    
        <start_number>-<ending_number>
    
For example:

    1-1024

This would cover ports 1 to 1024.

- **dst_range**
    The destination IP range. For example:
    
        dst_range => '192.168.1.1-192.168.1.10'
    
    The destination IP range is must in 'IP1-IP2' format.
      Values can match
    `/^((25[0-5]|2[0-4]\d|1\d\d|[1-9]\d|\d)\.){3}(25[0-5]|2[0-4]\d|1\d\d|[1-
    9]\d|\d)-((25[0-5]|2[0-4]\d|1\d\d|[1-9]\d|\d)\.){3}(25[0-5]|2[0-4]\d|1\d
    \d|[1-9]\d|\d)/`.  Requires features iprange.

- **dst_type**
    The destination address type. For example:
    
        dst_type => 'LOCAL'
    
    Can be one of:
    
    * UNSPEC - an unspecified address
    * UNICAST - a unicast address
    * LOCAL - a local address
    * BROADCAST - a broadcast address
    * ANYCAST - an anycast packet
    * MULTICAST - a multicast address
    * BLACKHOLE - a blackhole address
    * UNREACHABLE - an unreachable address
    * PROHIBIT - a prohibited address
    * THROW - undocumented
    * NAT - undocumented
    * XRESOLVE - undocumented
      Valid values are `UNSPEC`, `UNICAST`, `LOCAL`, `BROADCAST`, `ANYCAST`,
    `MULTICAST`, `BLACKHOLE`, `UNREACHABLE`, `PROHIBIT`, `THROW`, `NAT`,
    `XRESOLVE`.  Requires features address_type.

- **ensure**
    Manage the state of this rule. The default action is *present*.
      Valid values are `present`, `absent`.

- **gid**
    GID or Group owner matching rule.  Accepts a string argument
    only, as iptables does not accept multiple gid in a single
    statement.
  Requires features owner.

- **icmp**
    When matching ICMP packets, this is the type of ICMP packet to match.
    
    A value of "any" is not supported. To achieve this behaviour the
    parameter should simply be omitted or undefined.
      Requires features icmp_match.

- **iniface**
    Input interface to filter on.
      Values can match `/^[a-zA-Z0-9\-\._\+]+$/`.  Requires features
    interface_match.

- **isfragment**
    Set to true to match tcp fragments (requires type to be set to tcp)
      Valid values are `true`, `false`.  Requires features isfragment.

- **jump**
    The value for the iptables --jump parameter. Normal values are:
    
    * QUEUE
    * RETURN
    * DNAT
    * SNAT
    * LOG
    * MASQUERADE
    * REDIRECT
    * MARK
    
    But any valid chain name is allowed.
    
    For the values ACCEPT, DROP and REJECT you must use the generic
    'action' parameter. This is to enfore the use of generic parameters
    where
    possible for maximum cross-platform modelling.
    
    If you set both 'accept' and 'jump' parameters, you will get an error as
    only one of the options should be set.
  Requires features iptables.

- **limit**
    Rate limiting value for matched packets. The format is:
    rate/[/second/|/minute|/hour|/day].
    
    Example values are: '50/sec', '40/min', '30/hour', '10/day'."
      Requires features rate_limiting.

- **line**
    Read-only property for caching the rule line.

- **log_level**
    When combined with jump => "LOG" specifies the system log level to log
    to.
  Requires features log_level.

- **log_prefix**
    When combined with jump => "LOG" specifies the log prefix to use when
    logging.
  Requires features log_prefix.

- **name**
    The canonical name of the rule. This name is also used for ordering
    so make sure you prefix the rule with a number:
    
        000 this runs first
        999 this runs last
    
    Depending on the provider, the name of the rule can be stored using
    the comment feature of the underlying firewall subsystem.
      Values can match `/^\d+[[:alpha:][:digit:][:punct:][:space:]]+$/`.

- **outiface**
    Output interface to filter on.
      Values can match `/^[a-zA-Z0-9\-\._\+]+$/`.  Requires features
    interface_match.

- **pkttype**
    Sets the packet type to match.
      Valid values are `unicast`, `broadcast`, `multicast`.  Requires
    features pkttype.

- **port**
    The destination or source port to match for this filter (if the protocol
    supports ports). Will accept a single element or an array.
    
    For some firewall providers you can pass a range of ports in the format:
    
        <start_number>-<ending_number>
    
For example:

    1-1024

This would cover ports 1 to 1024.

- **proto**
    The specific protocol to match for this rule. By default this is
    *tcp*.
      Valid values are `tcp`, `udp`, `icmp`, `ipv6-icmp`, `esp`, `ah`,
    `vrrp`, `igmp`, `ipencap`, `ospf`, `gre`, `all`.

- **reject**
    When combined with jump => "REJECT" you can specify a different icmp
    response to be sent back to the packet sender.
      Requires features reject_type.

- **set_mark**
    Set the Netfilter mark value associated with the packet.  Accepts either
    of:
    mark/mask or mark.  These will be converted to hex if they are not
    already.
  Requires features mark.

- **socket**
    If true, matches if an open socket can be found by doing a coket lookup
    on the packet.
      Valid values are `true`, `false`.  Requires features socket.

- **source**
    The source address. For example:
    
        source => '192.168.2.0/24'
    
The source can also be an IPv6 address if your provider supports it.

- **sport**
    The source port to match for this filter (if the protocol supports
    ports). Will accept a single element or an array.
    
    For some firewall providers you can pass a range of ports in the format:
    
        <start_number>-<ending_number>
    
For example:

    1-1024

This would cover ports 1 to 1024.

- **src_range**
    The source IP range. For example:
    
        src_range => '192.168.1.1-192.168.1.10'
    
    The source IP range is must in 'IP1-IP2' format.
      Values can match
    `/^((25[0-5]|2[0-4]\d|1\d\d|[1-9]\d|\d)\.){3}(25[0-5]|2[0-4]\d|1\d\d|[1-
    9]\d|\d)-((25[0-5]|2[0-4]\d|1\d\d|[1-9]\d|\d)\.){3}(25[0-5]|2[0-4]\d|1\d
    \d|[1-9]\d|\d)/`.  Requires features iprange.

- **src_type**
    The source address type. For example:
    
        src_type => 'LOCAL'
    
    Can be one of:
    
    * UNSPEC - an unspecified address
    * UNICAST - a unicast address
    * LOCAL - a local address
    * BROADCAST - a broadcast address
    * ANYCAST - an anycast packet
    * MULTICAST - a multicast address
    * BLACKHOLE - a blackhole address
    * UNREACHABLE - an unreachable address
    * PROHIBIT - a prohibited address
    * THROW - undocumented
    * NAT - undocumented
    * XRESOLVE - undocumented
      Valid values are `UNSPEC`, `UNICAST`, `LOCAL`, `BROADCAST`, `ANYCAST`,
    `MULTICAST`, `BLACKHOLE`, `UNREACHABLE`, `PROHIBIT`, `THROW`, `NAT`,
    `XRESOLVE`.  Requires features address_type.

- **state**
    Matches a packet based on its state in the firewall stateful inspection
    table. Values can be:
    
    * INVALID
    * ESTABLISHED
    * NEW
    * RELATED
      Valid values are `INVALID`, `ESTABLISHED`, `NEW`, `RELATED`.  Requires
    features state_match.

- **table**
    Table to use. Can be one of:
    
    * nat
    * mangle
    * filter
    * raw
    * rawpost
    
    By default the setting is 'filter'.
      Valid values are `nat`, `mangle`, `filter`, `raw`, `rawpost`. 
    Requires features iptables.

- **tcp_flags**
    Match when the TCP flags are as specified.
    Is a string with a list of comma-separated flag names for the mask,
    then a space, then a comma-separated list of flags that should be set.
    The flags are: SYN ACK FIN RST URG PSH ALL NONE
    Note that you specify them in the order that iptables --list-rules
    would list them to avoid having puppet think you changed the flags.
    Example: FIN,SYN,RST,ACK SYN matches packets with the SYN bit set and
    the
    	       ACK,RST and FIN bits cleared.  Such packets are used to request
             TCP  connection initiation.
  Requires features tcp_flags.

- **todest**
    When using jump => "DNAT" you can specify the new destination address
    using this paramter.
  Requires features dnat.

- **toports**
    For DNAT this is the port that will replace the destination port.
      Requires features dnat.

- **tosource**
    When using jump => "SNAT" you can specify the new source address using
    this parameter.
  Requires features snat.

- **uid**
    UID or Username owner matching rule.  Accepts a string argument
    only, as iptables does not accept multiple uid in a single
    statement.
  Requires features owner.

Providers
---------
    ip6tables, iptables