gont

README

Gont: A Go testing framework for distributed applications

Gont is a Go package to support the development networked and distributed applications.

It can construct a virtual network using Linux network spaces, to simulate switches, routers, NAT and endpoints, on a single machine (VM, cloud or native). In addition, it supports developers with tooling for tracing and debugger tooling for investigating distributed applications.

Gont is heavily inspired by Mininet. It allows the user to build virtual network topologies defined Go code. Under the hood the network is then constructed using Linux virtual bridges and network namespaces.

Gont runs on all moderatly recent Linux versions and requires NET_ADMIN capabilities (or root access).

Using Gont, developers can test complex distributed peer-to-peer and federated applications like routing daemons or social networks and messaging. Integration tests can be automated and executed in CI environments like GitHub actions (which are in fact used to test Gont itself).

Getting started

Have a look at our slide set to get you started.

Features

• Various common network nodes:

  • Standard host
  • Layer-3 Routers
  • Layer-2 Switches
  • Layer-3 NAT Routers
  • Layer-3 NAT to host networks

• Hostname resolution for test nodes (/etc/hosts overlay)

• Execution of sub-processes, Go code & functions in the network namespace of test nodes

• Simultaneous setup of multiple isolated networks

• Ideal for Golang unit tests

• Can run in workflows powered by GitHub's runners

• Lean code thanks to functional options

• Full IPv6 support

• Per link network emulation and bandwidth limiting via for Netem and TBF queuing disciplines

• Use of existing network namespaces as nodes

• Configuration of per-host nftables firewall rules

• Built-in Ping & Traceroute diagnostic tools

• Built-in packet tracing with PCAPng output

  • Real-time streaming of PCAPng data to WireShark via TCP sockets or named-pipes
  • Automatic decryption of captured trafic using Wireshark/thark by including session secrets in PCAPng file
  • Automatic instrumentation of sub-processes using SSLKEYLOGFILE environment variable

• Distributed tracing of events

  • A slog.Handler to emit structured log records as trace events
  • A zapcore.Core to emit zap log messages as trace events
  • Dedicated gont/trace package for emitting trace events
  • Capturing of trace events in PCAPng files
  • WireShark Lua dissector for decoding events

• Built-in Delve debugger

  • Simultaneous attachment to multiple processes
  • Tracing via HW watch- & breakpoints to emit tracer events (see above)
    • Capture and investigate tracepoints in WireShark
  • Remote debugging via DAP
  • Generation of VS Code compound launch configurations
    • Start Gont test and attach to all processes at once

Examples

Have a look at the unit tests for usage examples:

• Ping
• Run
• NAT
• Switch
• Links
• Firewall Rules
• Packet tracing
  • With TLS decryption
• Event tracing
• Debugging

Prerequisites

• Go version 1.19 or later
• traceroute (for testing)
• libpcap (for compiling BPF filter expressions of packet tracing feature)

Architecture

Authors

• Steffen Vogel (@stv0g)

Funding acknowledment

The development of Gont has been supported by the ERIGrid 2.0 project
of the H2020 Programme under Grant Agreement No. 870620

License

Gont is licensed under the Apache 2.0 license.

• SPDX-FileCopyrightText: 2023 Steffen Vogel <post@steffenvogel.de>
• SPDX-License-Identifier: Apache-2.0