Firewall logging

From Opendium Documentation
Revision as of 17:39, 3 August 2026 by Steve (talk | contribs)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to navigation Jump to search

Upon a customer's request, Opendium engineers can configure the firewall component to send logs to a syslog server on the local network.

The firewall is stateful and each log line reflects the establishment of a new flow. The format of the data sent to a remote syslog server is (subject to change): 

<Date> <Host name> firewall<PID>: <Flow ID> <Zone crossing> <User> <User ident source> <Decision> (<Decider>) <Flow source> <Flow destination> <Layer 4 protocol> <Layer 7 protocol> <Packets>/<Octets>

The parameters are:

  • <Date> - The date and time that the event was logged.
  • <Host name> - The host name of the Opendium system (quite possibly, but not always "opendium").
  • <PID> - The process ID of the firewall.
  • <Flow ID> - Each flow is assigned a numeric ID when it is first logged.
  • <Zone crossing> - This is one of the following values to indicate which firewall zones the connection is crossing between:
    • Local_In - The flow was initiated by a device on the internet, destined for the Opendium system itself.
    • Local_Out - The flow was initiated by the Opendium system itself. Note: this is not usually logged.
    • Ingress - The flow was initiated by a device on the internet, destined for an internal network.
    • Egress - The flow was initiated by a device on an internal network, destined for the internet.
    • Internal - The flow is between devices located on different internal firewall zones.
    • External - The flow is between devices located on different external (internet) firewall zones. Note: Opendium systems do not usually have multiple external zones configured, so this would not usually be seen.
    • - - Internal error. This should never be seen.
    • Note that traffic between devices on the same zone is not restricted or logged. Depending on the network configuration, this traffic may not even pass through the firewall.
  • <User> - The user name associated with this traffic flow, if known. May include an "@<Realm>" suffix. If no user is known, this will be "-".
  • <User ident source> - Where the user identification information came from. e.g. "RADIUS", "Proxy: Kerberos", etc. Note that the firewall does not receive user identification from the client for each connection, and the user is inferred from other information, such as RADIUS accounting data, recently authenticated web proxy connections, etc.
  • <Decision> - The decision that the firewall has reached regarding this flow. This may be prefixed by "INFO/" (see below) and is one of:
    • UNDECIDED - The flow is temporarily allowed, but a decision has not yet been made. If the firewall needs to perform deep packet inspection in order to make a decision, it must temporarily allow the flow in order to gather traffic to inspect. A second "INFO/" line will be logged once an outcome has been reached (see below).
    • SHORT - A previously UNDECIDED flow has ended before a decision had been made. In terms of which traffic has been let through the firewall, this is equivalent to ALLOW, but the traffic may not match any allowed firewall bundles. See the notes on the "INFO/" prefix, below.
    • UNKNOWN - The start of the flow has been missed and there is therefore very limited information available. This is most likely caused by a restart of the firewall
    • DENY - Traffic associated with the flow is being dropped. Flows which are not allowed and originate on the internet usually result in DENY if possible, but deep packet inspection decisions may necessitate a REJECT instead.
    • REJECT - Traffic associated with the flow is being rejected with suitable ICMP error responses. Flows which are not allowed and originate from local networks usually result in REJECT.
    • INTERCEPT - Traffic has been redirected to a service running on the Opendium system. This is often web traffic which is being redirected to the transparent proxy and web filter, but may also be some other supported protocols such as DNS and NTP.
    • ALLOW - Traffic associated with the flow is being allowed to pass through the system.
    • INTERNAL_ERROR - Internal error. This should never be seen.
  • <Decider> - Which part of the firewall made the decision:
    • kernel - The decision was made by rules set up within the operating system kernel.
    • user - The decision was made by the userspace process.
    • This may also include the suffix " - destination banned". When deep packet inspection is used to control traffic, the firewall must allow the connection to be temporarily allowed whilst it gathers and inspects the traffic. If the resulting decision is to block the flow, the destination receives a temporary ban. This ensures that future connections are REJECTed / DROPped outright instead of being allowed initially.
  • <Flow source> - This is the IP address the device which initiated the flow, surrounded by square brackets. If the flow's layer 4 protocol has port numbers, the closing square bracket is followed by a colon and the source port. e.g.
    • [192.0.2.1]:123
    • [2001:db8::1]:123
  • <Flow destination> - The destination of the flow. This is in the same format as <Flow source> above.
  • <Layer 4 protocol> - Identifies the layer 4 protocol, such as "tcp", "udp", "sctp", etc. If a textual name is not known, the numeric protocol identifier is used.
  • <Layer 7 protocol> - The layer 7 protocol which deep packet inspection has identified. This will be either a single protocol name, or a pair of names separated by a forward slash. Additionally the following special values are used:
    • - - Deep packet inspection is not being performed on this flow.
    • [Unknown] - Deep packet inspection was not able to identify the protocol being used.
    • [In progress] - Deep packet inspection has not yet determined what protocol is being used. A second "INFO/" line will be logged once deep packet inspection has concluded (see below).
  • <Packets> - How many packets associated with this flow had been seen at the time it was logged.
  • <Octets> - How many octets associated with this flow had been seen at the time it was logged.

The firewall logs each flow as soon as it receives the first packet. However, deep packet inspection may not be able to identify the protocol being used until some time later. Additionally, if a firewalling decision relies on deep packet inspection, it too may need to be deferred until later. In these cases, a second log entry is recorded for the flow, and it will have its decision prefixed with "INFO/". The "INFO/" log can be linked to the original log through the numeric flow ID. Note that the flow ID is NOT unique, and a "INFO/" log should only be linked with the most recent previous entry with a matching flow ID.

Examples: 

Aug  3 15:56:52 opendium firewall[2106397]: 2342398 Ingress - [None] ALLOW (kernel) [2001:db8:1::45f2] [2001:db8:2::6b51] ipv6-icmp ICMPV6 1/144
Aug  3 15:56:52 opendium firewall[2106397]: 2342399 Egress - [None] INTERCEPT (kernel) [192.0.2.1]:59564 [198.51.100.23]:443 tcp [In progress] 1/60
Aug  3 15:56:52 opendium firewall[2106397]: 2342399 Egress - [None] INFO/INTERCEPT (kernel) [192.0.2.1]:59564 [198.51.100.23]:443 tcp SSL 6/2293

Notes for Opendium engineers

Enable syslog output from the firewall by adding a key to its config table: 

INSERT INTO webfront_firewall.config (key, value) VALUES ('global.syslog', 1);

Create a file called /etc/rsyslogd.d/10-firewall.conf containing: 

if $programname == 'firewall' then {
        action(
                type="omfwd"
                target="192.0.2.1"
                port="514"
                protocol="udp"
        )
        stop
}

Replace "192.0.2.1" with the IP address of the target syslog server. Also see the Rsyslog documentation for more options.

Restart both the rsyslog and firewall services.

Retrieved from ‘https://docs.opendium.com/w/index.php?title=Firewall_logging&oldid=524’