ethtun control CLI

 

 

ethtun control CLI #

Here’s a walk through the ethtun control CLI on an EtherTunnel tunnel endpoint.

Entering/leaving the CLI and the status line #

Before each prompt the current tunnel status is shown with a status line consisting of the following, from left to right:

  • The local NodeID (the MAC address of interface 0)
  • The tunnel HMAC/encryption parameters either in red or green
  • The remote NodeID (--:--:--:--:--:-- if not yet known)

The tunnel HMAC/encrytion parameter shortcode consists of two parts:

  1. The HMAC Level
  • H0 - default authentication
  • H1 - authentication with a secret (tunnel-hmac-secret is set)
  • H2 - authentication with a 2^32 rotating random secret (tunnel-hmac-material is set)
  • H3 - authentication with both XORed (both, tunnel-hmac-secret and tunnel-hmac-material are set)
  1. The Encryption Level
  • E0 - no encryption
  • E1 - encryption with a preshared key (tunnel-key-secret is set)
  • E2 - encryption with a 2^32 rotating random key (tunnel-key-material is set)
  • E3 - authentication with both XORed (both, tunnel-key-secret and tunnel-key-material are set)

The status line is updated just before each new prompt. EOF (Ctrl-D) leaves the CLI, also there’s an interactive timeout of 10 minutes.

A tunnel not yet established looks like this:

$ sudo ethtun control
connected to PID 7966
ethtun - EtherTunnel 1.119 Debian12-amd64
00:15:17:7e:26:16 << H3E3 >> --:--:--:--:--:--
>

An established tunnel looks like this:

$ sudo ethtun control
connected to PID 7966
ethtun - EtherTunnel 1.119 Debian12-amd64
00:15:17:7e:26:16 << H3E3 >> 00:15:17:77:bc:70
>

h | help - show available CLI commands #

Typing help or just the short form h shows the available help information. All commands except stop have a one letter short form.

$ sudo ethtun control
connected to PID 7966
ethtun - EtherTunnel 1.119 Debian12-amd64
00:15:17:7e:26:16 << H3E3 >> 00:15:17:77:bc:70
> h
  the following commands are available:
    a | aset           show atomic sets ("forwarding tables")
    C | configuration  show configuration as loaded
    c | counters       show atomic counters
    e | ethertypes     show ethertype counters
    f | filters        show active filters
    h | help           show this information
    i | interfaces     show interfaces
    L | license        show licensing information
    l | log            show current log
    r | release        show release
    R | reset          reset yellow atomic counters
    S | startuplog     show startup log
    s | status         show general status
        stop           stop immediately
  type EOF to exit. 
00:15:17:7e:26:16 << H3E3 >> 00:15:17:77:bc:70
>

a | aset - show atomic sets (“forwarding tables”) #

The EtherTunnel forwarding information is implemented as two lockless atomic sets, one for the local side and the other for the remote side. Examining these atomic sets on the other tunnel endpoint shows the reversed information.

On this particular endpoint this looks as follows:

> a
  aset_local
    3e:10:d5:14:22:7e
    b6:95:82:9c:60:39
    00:11:32:d5:11:11
    52:54:00:9c:53:c1
    00:3e:e1:c0:f0:9c
    56:e6:36:5f:17:a8
    00:1d:c1:10:e9:50
    32:3a:fd:84:56:64
    30:05:5c:f2:a9:96
    a4:cf:12:92:c3:64
    a0:52:72:1a:ca:41
    00:23:7d:86:71:ff
    00:1d:c1:07:ac:30
    ce:0e:14:15:67:bc
    52:54:00:a9:4e:fe
    52:54:00:ec:64:22
    52:54:00:77:8f:62
    50:1e:2d:49:c2:24
    ee:0c:92:fe:f1:1c
    dc:39:6f:2b:f2:b6
    32:3a:fd:86:36:3f
    e0:89:7e:6a:41:39
    4e:3a:fd:86:36:41
    3c:2a:f4:07:f0:4b
    18:4a:53:02:ae:67
    00:11:32:d5:11:12
    52:54:00:90:35:ba
    52:54:00:23:b1:1a
    52:54:00:12:88:ef
    a0:78:17:6e:0e:45
    52:54:00:e0:e6:db
    52:54:00:46:b7:3e
  aset_remote
    80:ee:73:e3:6b:0e
    2c:cf:67:00:a0:92
00:15:17:7e:26:16 << H3E3 >> 00:15:17:77:bc:70
>

C | configuration - show configuration as loaded #

This command shows the configuration as it has been internalized from its input configuration, per default /etc/ethtun.conf.

On this particular endpoint this looks as follows:

> C
###
license-serial          = ET0000000000
license-key             = dc2bea074d59010c6f26920f17002761
tunnel-interfaces       = enp1s0f0
tunnel-remote-address   = u31
filter-nic-etype-allow  = 0x0800
                          0x0806
                          0x86dd
filter-udp-etype-allow  = 0x0800
                          0x0806
                          0x86dd
###
00:15:17:7e:26:16 << H3E3 >> 00:15:17:77:bc:70
>

c | counters - show atomic counters #

The vast of atomic counters may look overwhelming, but there’s a simple coloring scheme that is very useful:

  • A counter shown in the default color is normal.
  • A counter appearing in yellow is usually a configuration problem (like authentication/encryption mismatches, time synchronization problems and so on).
  • A counter appearing in red is an implementation issue that we would like to have a look at, please contact us at support@inlab.net in that case.

With that in mind it’s immediately visible that everything is in a healthy state on this testing tunnel endpoint:

> c
  actr_counter                         = 0x2dc93c29
  actr_nic_packets_received            = 462548
  actr_nic_bytes_received              = 32757298
  actr_nic_packets_sent                = 5386978
  actr_nic_bytes_sent                  = 8098987670
  actr_udp_packets_received            = 10737546
  actr_udp_bytes_received              = 8903888160
  actr_udp_packets_sent                = 462472
  actr_udp_bytes_sent                  = 61202368
  actr_udp_sendto_failed               = 0
  actr_udp_packets_fragmented          = 8
  actr_udp_packets_reassembled         = 5350243
  actr_udp_fragmented_packet_id        = 0xc1261e5fcda8d167
  actr_udp_reassembly_time_exceeded    = 130
  actr_udp_fragments_lost_on_store     = 0
  fragments_left->acount               = 0
  fragments_right->acount              = 0
  aset_local->nelements                = 1
  aset_local->collisions               = 0
  aset_local->failures                 = 0
  aset_remote->nelements               = 12
  aset_remote->collisions              = 0
  aset_remote->failures                = 0
  actr_udp_packet_too_short            = 0
  actr_udp_packet_auth_failed          = 0
  actr_udp_packet_timestamp_failed     = 0
  actr_udp_packet_invalid_length       = 0
  actr_udp_packet_encrypted_but_no_key = 0
  actr_udp_packet_unencryped_drops     = 0
  actr_dhcp4_drops                     = 0
  actr_dhcp6_drops                     = 0
  actr_icmp6_drops                     = 0
  actr_filter_nic_mac_drops            = 0
  actr_filter_nic_oui_drops            = 0
  actr_filter_nic_etype_drops          = 83
  actr_filter_udp_mac_drops            = 0
  actr_filter_udp_oui_drops            = 0
  actr_filter_udp_etype_drops          = 183
  actr_reflection_self_drops           = 0
  actr_reflection_remote_drops         = 0
  actr_nic_to_self_drops               = 0
  actr_ifcount_mismatch_drops          = 0
  actr_invalid_keepalive               = 0
  actr_unexpected_write_result         = 0
  actr_unexpected_inject_result        = 0
00:15:17:7e:26:16 << H3E3 >> 00:15:17:77:bc:70
>

e | ethertypes - show ethertype counters #

This Ethertype statistic is applied “post filter” and summarizes the number of packets per Ethertype. The second column records just the very last MAC address that has been sending a packet with that particular Ethertype. When no Ethertype filters are in place, this helps to identify machines that are consistently sending unusual, unwanted or unregistered Ethertypes.

On this testing tunnel endpoint only the allowed Ethertypes are appearing in this list (because everything else has been dropped):

> e
  nic-etype
    0x0800 80:ee:73:e3:6b:0e 972299
  udp-etype
    0x0800 00:3e:e1:c0:f0:9c 11319099
    0x0806 dc:39:6f:2b:f2:b6 167
    0x86dd 00:3e:e1:c0:f0:9c 127
00:15:17:7e:26:16 << H3E3 >> 00:15:17:77:bc:70
>

f | filters - show active filters # 

> f
  filter-nic-mac-allow
  filter-nic-mac-deny
  filter-nic-oui-allow
  filter-nic-oui-deny
  filter-nic-etype-allow
    0x0800
    0x0806
    0x86dd
  filter-nic-etype-deny
  filter-udp-mac-allow
  filter-udp-mac-deny
  filter-udp-oui-allow
  filter-udp-oui-deny
  filter-udp-etype-allow
    0x0800
    0x0806
    0x86dd
  filter-udp-etype-deny
00:15:17:7e:26:16 << H3E3 >> 00:15:17:77:bc:70
>

i | interfaces - show interfaces # 

> i
  0 enp1s0f0
    00:15:17:7e:26:16
    fd: 4 krcvd: 19249331 kdrops: 0
00:15:17:7e:26:16 << H3E3 >> 00:15:17:77:bc:70
>

L | license - show licensing information # 

> L
  valid license - serial number: ET0000000000
00:15:17:7e:26:16 << H3E3 >> 00:15:17:77:bc:70
>

l | log - show current log # 

> l
  2024/04/18 11:32:10 5 EtherTunnel 1.119 Debian12-amd64 started
  2024/04/18 11:32:10 5 MachineID: 39822500ad1cf11457c5768780025a44
  2024/04/18 11:32:11 6 NodeID: 00:15:17:7e:26:16 (enp1s0f0) H3E3
  2024/04/18 11:32:11 6 ethtool offload disable for enp1s0f0 SUCCESS
  2024/04/18 11:32:11 6 nic_thread 0 enp1s0f0 00:15:17:7e:26:16 fd=4 running
  2024/04/18 11:32:15 5 tunnel ESTABLISHED to 00:15:17:77:bc:70
00:15:17:7e:26:16 << H3E3 >> 00:15:17:77:bc:70
>

r | release - show release # 

> r
+----------------------------------------------------------------------+
|            ethtun - EtherTunnel 1.119 BETA Debian12-amd64            |
|          Copyright (c) 2024 by Inlab Networks GmbH, Germany          |
|            All rights reserved / Alle Rechte vorbehalten             |
|                        ethertunnel.inlab.net                         |
+----------------------------------------------------------------------+
00:15:17:7e:26:16 << H3E3 >> 00:15:17:77:bc:70
>

R | reset - reset yellow atomic counters #

This resets all counters, that may have indicated a configuration problem by becoming non zero and yellow back to 0. This is useful to apply after the issue has been cleared and it would be inconvenient to restart the tunnel endpoint just for that purpose.

Here’s a list of atomic counters that are in this set:

  • actr_udp_sendto_failed
  • actr_udp_packet_auth_failed
  • actr_udp_packet_timestamp_failed
  • actr_udp_packet_encrypted_but_no_key
  • actr_udp_packet_unencryped_drops
  • actr_ifcount_mismatch_drops
  • actr_invalid_keepalive

S | startuplog - show startup log # 

> S
  2024/04/18 11:32:10 5 EtherTunnel 1.86 Debian12-amd64 started
  2024/04/18 11:32:10 5 MachineID: 39822500ad1cf11457c5768780025a44
  2024/04/18 11:32:11 6 NodeID: 00:15:17:7e:26:16 (enp1s0f0) H3E3
  2024/04/18 11:32:11 6 ethtool offload disable for enp1s0f0 SUCCESS
  2024/04/18 11:32:11 6 nic_thread 0 enp1s0f0 00:15:17:7e:26:16 fd=4 running
  2024/04/18 11:32:15 5 tunnel ESTABLISHED to 00:15:17:77:bc:70
00:15:17:7e:26:16 << H3E3 >> 00:15:17:77:bc:70
>

s | status - show general status # 

> s
  uptime is 3848 seconds
  NodeID (enp1s0f0 MAC) is 00:15:17:7e:26:16
  tunnel ESTABLISHED to 00:15:17:77:bc:70
  current peer address: ::ffff:172.17.3.31,439
00:15:17:7e:26:16 << H3E3 >> 00:15:17:77:bc:70
>

stop - stop immediately #

This command stops the background process with all its threads immediately and has no short form:

> stop
ethtun: no peer available
$