Configuration

Configuration in GoNetSim is done through TOML files. There are many options for the location of these files, which will be described in the next section.

Each configuration file determines the configuration for the entire tool, but is only applied to tool runs as described below. This means you can have multiple configurations with different options and switch between for different runs.

Configuration File Locations

GoNetSim will look for configuration files in the following locations, in order of precedence:

1. The path specified by the --config flag when running GoNetSim

   gonetsim --config /path/to/config.toml

2. The local configuration file at ./gonetsim.toml (the current directory)

3. The default configuration file at $XDG_CONFIG_HOME/gonetsim/config.toml (or ~/.config/gonetsim/config.toml if XDG_CONFIG_HOME is not set)

4. The system-wide configuration file at /etc/gonetsim/gonetsim.toml

Modifying Configurations

Configuration files are organised in sections, with each section corresponding to a service. For example, the [dns] section corresponds specifically to the DNS service & will not affect configuration for other services.

Under each section, there are one or more options that can be modified to change the behavior of the corresponding service. For example, the enabled option determines whether the service is enabled or not.

To change a configuration option, simply edit the content after the equals sign = for the desired option

Here, we’ll disable the DNS service and change the listen address for the HTTP service:

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

[http]
enabled = false
 listen = ":80"
 listen = ":8080"
status = 200
...

The full list of configuration options can be found in the reference documentation for each service, such as the DNS reference or the HTTP reference.

Note

After modifying a configuration file, make sure to save the file and restart GoNetSim for the changes to take effect

One-Off Overrides

For changes you only need once, you can use the -s (--set) flag which overrides any option for a single run, using the same dotted names as the config file:

gonetsim run http -s http.status=404 -s http.mode=real

Numbers and true/false don’t need quotes as the types are interpreted. You can repeat -s to override as many options as you like, and combine it with any other run flags. See the usage guide for the full set of flags.

Custom Listeners

Alongside the service sections, config files can define [[listeners]] entries. These extend GoNetSim with custom handlers, either with generic handlers on a custom port or for fully custom Lua scripts:

[[listeners]]
name = "irc"
type = "tcp"
listen = ":6667"
handler = "lua:handlers/irc.lua"

Each entry gets its own block, and named listeners can be started on their own with gonetsim run <listener>. See the listeners reference for all options, and the scripting section for writing handlers.

Default Configuration File

The default configuration file / template can be found here from the GitHub repository. This file is also generated on the first run of GoNetSim at the default location described above.

Validating Configuration

The gonetsim check command can be used to validate a configuration file. It automatically chooses the config file based on the same selection mechanism. Each service & custom listener gets a row showing whether it’s enabled, configured correctly & able to bind its port. Lua scripts are compiled in this process as well to check for syntax errors.

To validate configuration, simply run the following:

Linux / MacOS

gonetsim check

Windows

gonetsim.exe check