ethtun.conf

 

 

ethtun.conf Reference #

ethtun.conf is the EtherTunnel configuration file. Its default path is /etc/ethtun.conf, which may be altered with the -c command line option.

Syntax and Parsing Rules #

Whitespace #

  • Whitespace is ignored (blanks, tabs, linefeeds and newlines).

Comments #

  • Comments start with a #, any text starting with # until the end of the line is ignored. # characters within quoted parameter values don’t start a comment.

Parameter Names #

  • A parameter name does always start at the very first column of a line and must not be quoted.
  • Any whitespace and also the = character are not part of the parameter name.
  • It’s an error to declare an unknown parameter.

Parameter Values #

  • Parameter values may be enclosed in doublequotes ("").
  • Doblequotes and backslashes within doublequotes need to be escaped as \" and \\.
  • The accepted value format for a specific parameter is controlled by the application.

Parameter Value Pairs #

The following declarations are equivalent:

1

parameter = value


1

parameter = "value"   # quoted


1

parameter value       # the = may be omitted


1
2

parameter =
  value               # value with indentation in next line


1
2

parameter             # also here the = is optional
  value

Parameters with multiple Values #

The following declarations are equivalent:

1

multi-value-parameter = value1 value2 value3


1

multi-value-parameter "value1" "value2" "value3"


1
2
3

multi-value-parameter = value1 
                        value2 
                        value3


1
2
3
4

multi-value-parameter
  value1 
  value2 
  value3

The EtherTunnel configuration parameters are loosely organized in groups, each one associated with a specific operational aspect:

The “license-” parameter group #

license-serial #

This parameter provides the license serial number.

Examples:

  • license-serial = RB0123456789

license-key #

This parameter provides the generated license key for the serial number and the EtherTunnel machine ID.

Example:

  • license-key = e3b0c44298fc1c149afbf4c8996fb924

Recommendations and Summary #

  • an EtherTunnel running in registry mode doesn’t require a license
  • the EtherTunnel CLI command license shows the licensing status

The “tunnel-” parameter group #

tunnel-interfaces #

This configures a set of interfaces connected to separate broadcast domains which will be transported to the other side. The Layer 2 parameters and the number of tunnel-interfaces must match between both sides (a mismatch is indicated by the atomic counter actr_ifcount_mismatch_drops and should be resolved for proper operation).

If tunnel-interfaces is empty, EtherTunnel operates as a registry when started with ethtun start.

Examples:

1

tunnel-interfaces = eth0


1
2
3

tunnel-interfaces = 
  enp1s0f0  # interface 0
  enp1s0f1  # interface 1

tunnel-name #

The parameter tunnel-name identifies the name on the connection towards a EtherTunnel registry (as configured with registry-address).

Example:

1

tunnel-name = "VLAN-Tunnel.22.23"

tunnel-local-address #

This parameter specifies the binding address of the EtherTunnel UDP server. Possible values are numerical IPv4 addresses, numerical IPv6-mapped IPv4 addresses, numerical IPv6 addresses or DNS names resolving either to an A or AAAA record.

When this parameter is unspecified, the UDP tunnel binds to all addresses which has some advantages, e.g. switching between IPv4 and IPv6 becomes possible and a DHCP/ND6 provided previously unknown IP address doesn’t matter.

Examples:

  • tunnel-local-address = 10.1.1.12
  • tunnel-local-address = ::ffff:10.1.1.12
  • tunnel-local-address = 2001:db8::2:4
  • tunnel-local-address = resolving.to.something.example.com

tunnel-local-port #

This parameter changes the local UDP default port 439 to the specified numerical value.

Example:

  • tunnel-local-port = 20000

tunnel-remote-address #

This parameter allows to specify the IP address of a known EtherTunnel peer.

Possible values are numerical IPv4 addresses, numerical IPv6-mapped IPv4 addresses, numerical IPv6 addresses or DNS hostnames resolving either to an A or AAAA record.

Examples:

  • tunnel-remote-address = 10.1.1.13
  • tunnel-remote-address = ::ffff:10.1.1.13
  • tunnel-remote-address = 2001:db8::2:5
  • tunnel-remote-address = resolving.to.something.example.com

tunnel-remote-port #

This parameter changes the remote UDP default port 439 to the specified numerical value.

Example:

  • tunnel-remote-port = 20000

tunnel-hmac-secret #

Examples:

  • tunnel-hmac-secret = OJHJ$%&aha(HHHOA
  • tunnel-hmac-secret = "A MAC Secret with blanks"
  • tunnel-hmac-secret = 17272888010111

tunnel-hmac-material #

This parameter references a random material file which must contain at least 32KB of true or cryptocraphically secure random bytes. A basic chi squared test ist performed on the data in order to check if the result remains below a critical value. This entropy is feeded for authetication during runtime into a combinatorical random number generator with a relatively short period of 2^32 and a result of a 256bit secret which is included in the SHA256 HMAC calculation for each packet. (using the atomic counter actr_counter as its input).

This file can be generated with a true random generator or as well cryptographically secure with dd and /dev/urandom as follows:

$ dd if=/dev/urandom bs=32768 count=1 > material.random
1+0 records in
1+0 records out
32768 bytes (33 kB, 32 KiB) copied, 0.000121559 s, 270 MB/s
If this parameter is specified, it needs also be present in the other EtherTunnel endpoint referencing exactly the same contents for mutual successful authentication.

Example:

  • tunnel-hmac-material = /home/test/hmac-material.random

tunnel-key-secret #

Example:

  • tunnel-key-secret = KKASJIUASUZUETGUFWKLIIWDLL

tunnel-key-material #

This parameter works the same way as tunnel-hmac-material, but the 256bit result becomes the ChaCha20 256bit key for encryption (and decryption on the other EtherTunnel endpoint).

Example:

  • tunnel-hmac-material = /home/test/key-material.random

Recommendations and Summary #

  • Bridging WLAN interfaces is not supported.

The “registry-” parameter group #

registry-address #

For a tunnel endpoint this specifies the registry to contact when needed, for a registry this is the bind()-address the UDP server is using.

registry-port #

This parameter changes the registry UDP default port to the specified numerical value.

registry-hmac-secret #

This specifies the HMAC-secret for communication between a registry and a tunnel endpoint.

registry-key-secret #

This specifies the encryption secret for communication between a registry and a tunnel endpoint. If not set, encryption is disabled.

The “filter-” parameter group #

The deny filter is examined first (if present), everything that doesnt match is allowed to pass. Then an allow filter is examined (if present), everything that does not match is denied to pass.

The order of the filters is from most to least specific:

  1. MAC addresses
  2. OUIs
  3. Ethertypes

The ethtun control CLI command ethertypes provides a simple statistic after all configured filters have been applied.

filter-nic- #

All filter-nic- settings examine the packets on ingress from all NICs together (all tunnel-interfaces). MAC addresses and OUIs are from the originating (sender) MAC address.

filter-nic-mac-allow #

Example:

1
2

filter-nic-mac-allow = 
  2c:cf:67:00:a0:92

filter-nic-mac-deny #

Example:

1
2
3
4

filter-nic-mac-deny = 
  9a:88:c6:d1:3d:4a
  b6:95:82:9c:60:39
  dc:39:6f:2b:f2:b6

filter-nic-oui-allow #

Example:

1
2
3

filter-nic-oui-allow = 
  2c:cf:67
  00:3e:e1

filter-nic-oui-deny #

Example:

1
2
3

filter-nic-oui-deny = 
  9a:88:c6
  dc:39:6f

filter-nic-etype-allow #

Example:

1
2
3
4
5

filter-nic-etype-allow = 
  0x0800    # IPv4
  0x0806    # ARP
  0x86dd    # IPv6
  0x88cc    # Link Layer Discovery Protocol (LLDP)

filter-nic-etype-deny #

Example:

1
2
3

filter-nic-etype-deny = 
  0x88e1    # AVM "Powerline"
  0x8912    # AVM unregistered

filter-udp- #

The filter-udp- settings work the same ways as the filter-nic- settings, but are effective on ingress from the tunnel instead. This may look unnecessary at first, because packets that are not injected on the other side simply never appear in the tunnel. However, there are situations where access to the remote endpoint configuration is temporarily limited and some restrictions need to be configured locally.

filter-udp-mac-allow #

filter-udp-mac-deny #

filter-udp-oui-allow #

filter-udp-oui-deny #

filter-udp-etype-allow #

filter-udp-etype-deny #

The “flag-” parameter group #

flag-noinject #

This parameter allows to configure a testing mode: If set to 1 (enabled) EtherTunnel will never inject any packets into the local LAN. Everything else is processed normally (forwarding and receiving of packets through the UDP tunnel and updating the forwarding information in the atomic sets). This parameter defaults to 0 (disabled).

Examples:

  • flag-noinject = 1 # injection suppressed
  • flag-noinject = 0 # default

flag-host-fragmentation #

When this parameter is set to 1, the EtherTunnel fragmentation/reassembly is disabled and the operating system (host) IP/UDP fragmentation/reassembly is used instead. It’s recommended to leave this at its default 0.

flag-drop-dhcp #

This parameter controls whether DHCP packet types are being forwarded or not. If set to 1 (enabled) the following packet types will not be forwarded in either direction:

  • IPv4 DHCP packets
  • IPv6 DHCP packets

flag-drop-ndp #

This parameter controls whether IPv6 router specific NDP (Neighbor Discovery Protocol) packet types are being forwarded or not. If set to 1 (enabled) the following ICMPv6 packet types will not be forwarded in either direction:

  • ICMPv6 Router Solicitations (type 133)
  • ICMPv6 Router Advertisements (type 134)
  • ICMPv6 Redirect (Type 137)

The following ICMPv6 packet types are not dropped when this flag is enabled thus still allowing neighbour discovery for IPv6 link-local addresses:

  • ICMPv6 Neighbor Solicitation (Type 135)
  • ICMPv6 Neighbor Advertisement (Type 136)

The “dasp-” parameter group #

dasp-registry-ival #

This parameter specifies the interval at which a known registry is contacted to find a currently unknown matching peer. The default of this parameter is 10 seconds. It’s configurable in the range from 1 to 60 seconds.

dasp-timestamp-tol #

This parameter specifies within wich tolerance a packets timestamp is accepted. The default of this parameter is 300 seconds (5 minutes). It’s configurable in the range from 5 to 600 seconds.

dasp-keepalive-ival #

This parameter specifies the interval in seconds a keepalive packet is sent to the peer tunnel endpoint. The default of this parameter is 10 seconds. It’s configurable in the range from 1 to 60 seconds.

dasp-keepalive-tout #

This parameter specifies the time period in seconds during a valid keepalive packet has to be received to keep the tunnel state in state ESTABLISHED. The default of this parameter is 30 seconds. It’s configurable in the range from 1 to 60 seconds.