Usage

This document will guide you through GoNetSim’s basic commands.

Prerequisites

• GoNetSim installed standalone on your system. If you haven’t done this yet, please see the installation guide. This tutorial does not directly walk through dockerised setups.

Note

This tutorial assumes you have a basic understanding of the command line and are comfortable navigating your file system.

Baby’s First GoNetSim

To start GoNetSim, you can simply run the gonetsim command (or gonetsim.exe on windows)

Linux

gonetsim

Windows

gonetsim.exe

The output will show what services have started & on what ports.

Configuration

After running gonetsim for the first time, a default config file will be generated at ~/.config/gonetsim/config.toml (or %APPDATA%\gonetsim\config.toml on Windows). Configuration files are the primary way to enable, disable & modify services in GoNetSim.

Let’s try disabling the DNS service:

1. Open the config file at ~/.config/gonetsim/config.toml (or %APPDATA%\gonetsim\config.toml on Windows) in a text editor.

2. Find the [dns] section and set enabled = false.

   ...
   [dns]
    enabled = true
    enabled = false
   listen = ":5354"
   network = "udp"
   ipv4 = "127.0.0.1"
   ipv6 = "::1"
   ...

3. Save the file

4. Run gonetsim (or gonetsim.exe on Windows) again to confirm the changes.

   Linux

   gonetsim

   Windows

   gonetsim.exe

If you’d like to learn more about configuration, please see the configuration guide.

Choosing What Runs

Running gonetsim on its own starts every service enabled in your config. To start only some of them, name them as targets with run:

Linux / MacOS

gonetsim run http

Windows

gonetsim.exe run http

You can name several targets in one go, mixing services & custom listeners freely:

gonetsim run http dns irc

Anything you name is started even when its config says enabled = false.

Note

Targets can also be passed straight to gonetsim without the run keyword, i.e. gonetsim http does the same thing as gonetsim run http.

Inline Listeners

Listeners can also be started straight from the command line with no configuration at all, using handler@address targets:

gonetsim run echo@:7777       # echo everything back, over TCP
gonetsim run sink@:9999/udp   # silently consume UDP traffic
gonetsim run irc.lua@:6667    # serve a local Lua handler

These are perfect for quickly testing a handler, or standing in for a service your sample expects to find. See the listeners reference for the full details.

Flags

Most sessions need small adjustments to override the config, so instead of editing your config, pass the changes as flags:

Flag	Description
-s, --set key=value	Override any config option for this run (repeatable)
--listen <address>	Use a different listen address (with a single target)
--timeout <duration>	Idle connection timeout (default 30s)
--tls	Wrap an inline TCP listener in TLS (self-signed)
--no-capture	Don’t save captured traffic for this run
--artifacts <dir>	Write captures somewhere else (default ./artifacts)

For example, to serve HTTP from a folder on a custom port & status code:

gonetsim run http --listen :8080 -s http.mode=real -s http.root_dir=./sample-site

Or to try a Lua handler with TLS, without leaving capture files behind:

gonetsim run c2.lua@:8443 --tls --no-capture

Testing Handlers

Custom Lua handlers can be developed & tested without opening a single port. The script command pipes traffic through a handler over stdin/stdout:

echo "NICK test" | gonetsim script handlers/irc.lua

For a full walkthrough of writing your own handlers, see the scripting section.

Resources

There are plenty of official resources to help you get started with GoNetSim:

Help

The built-in gonetsim help command shows you all available commands, flags and options for GoNetSim. You can also learn more about specific sub-commands by running gonetsim help <sub-command> (e.g. gonetsim help run)

Linux

gonetsim help

Windows

gonetsim.exe help

GitHub

The GoNetSim GitHub repository contains the source code, issue tracker and discussions for GoNetSim.

See the repo

Documentation

This documentation site contains plenty of guides and references for everything GoNetSim has to offer. If you want to learn more about a specific service, check out the reference section. If you want to learn how to do something specific with GoNetSim, check out the guides section.

Explore the docs