Settings on Documentation

Settings Overview

Mon, 01 Jan 0001 00:00:00 +0000

Settings Overview#

bgscan keeps all configuration in plain TOML files inside settings/. The app also exposes these same options through the in-app Settings inspector, which writes changes back to disk automatically.

Setting files#

File	Purpose
`settings/general_settings.toml`	Global scan control and pipeline mode
`settings/writer_settings.toml`	Result buffering and disk writes
`settings/icmp_settings.toml`	ICMP probe tuning
`settings/tcp_settings.toml`	TCP connect tuning
`settings/http_settings.toml`	HTTP/HTTPS/HTTP3 probe tuning
`settings/xray_settings.toml`	Xray test tuning
`settings/dns_settings.toml`	DNS resolver and tunnel scan orchestration

Two ways to edit settings#

TOML files — open any settings/*.toml file in a text editor, change values, save, and restart bgscan. This works well under version control.
In-app inspector — open bgscan, navigate to Settings in the main menu, pick a category, press Enter on any field to edit it. Changes are saved immediately to disk.

Some fields are dynamic. For example, TLS-related options only show when HTTPS is selected, and DNSTT/Slipstream fields only show when those probes are enabled.

Settings Inspector

Mon, 01 Jan 0001 00:00:00 +0000

Settings Inspector#

When you open any settings section from the in-app Settings menu, you see the inspector. It is a tabbed field list with labels, current values, and edit affordances.

select fields and press Enter to change them
press d to view the description/help text for the selected field
booleans show as toggles
some protocols expose extra fields only when the mode is selected

Changes are saved immediately to disk without restarting the scanner.

General Settings

Mon, 01 Jan 0001 00:00:00 +0000

General Settings#

💡 Tip: You can change these settings directly in the bgscan application instead of editing the TOML file manually.

Navigate to Settings → General Settings in the main menu to configure these options interactively using the TUI inspector.

Configuration file: settings/general_settings.toml

Global scan limits, probe rate limiting, pipeline execution mode, and buffer sizing.

Quick Reference#

Setting	Default	Description
`status_interval`	`1000`	Progress update interval in milliseconds
`max_successful_ips`	`0`	Stop after N successful results (0 = scan all)
`max_ips_to_test`	`0`	Cap on IPs read from the input source
`pipeline_mode`	`"streaming"`	Execution mode for multi-stage scans
`max_ips_per_stage`	platform-dependent	Channel buffer size between streaming stages
`batch_size`	platform-dependent	Batch size for batch mode
`shuffled`	`true`	Randomize target order
`min_probe_duration`	platform-dependent	Minimum time spent per probe (ms)
`probe_per_sec`	platform-dependent	Sustained probe rate ceiling (token-bucket refill)
`probe_burst`	platform-dependent	Max probes in a burst (token-bucket capacity)

Status Interval#

status_interval = 1000

How often each stage emits a progress snapshot to the UI, in milliseconds. Valid range is 100 ms to 60 s. Lower values give smoother feedback and cost more CPU on very large scans.

Result Writer Settings

Mon, 01 Jan 0001 00:00:00 +0000

Result Writer Settings#

💡 Tip: You can change these settings directly in the bgscan application instead of editing the TOML file manually.

Navigate to Settings → General Settings tab 2 in the main menu to configure these options interactively using the TUI inspector.

Configuration file: settings/writer_settings.toml

Buffering and flush behavior of the result writer, plus where result files are stored.

Each scan stage owns one writer. Workers push results into a channel, the writer accumulates them into a batch, and each flush merge-sorts that batch into the stage’s CSV file.

ICMP Settings

Mon, 01 Jan 0001 00:00:00 +0000

ICMP Settings#

💡 Tip: You can change these settings directly in the bgscan application instead of editing the TOML file manually.

Navigate to Settings → ICMP Settings in the main menu to configure these options interactively using the TUI inspector.

Configuration file: settings/icmp_settings.toml

The ICMP probe sends echo requests and records the round-trip time. It opens one shared IPv4 socket and, when the system allows it, one shared IPv6 socket, then demultiplexes replies to the waiting workers.

TCP Settings

Mon, 01 Jan 0001 00:00:00 +0000

TCP Settings#

💡 Tip: You can change these settings directly in the bgscan application instead of editing the TOML file manually.

Navigate to Settings → TCP Settings in the main menu to configure these options interactively using the TUI inspector.

Configuration file: settings/tcp_settings.toml

The TCP probe opens a connection to one port on each target and records the handshake latency. It does not speak any application protocol.

Quick Reference#

Setting	Default	Range	Description
`port`	`443`	1-65535	Target TCP port
`timeout`	`2000`	100-30000	Connection timeout in milliseconds
`workers`	platform-dependent	1-5000	Concurrent connection attempts
`tries`	`1`	1-10	Connection attempts per target
`output_prefix`	`"tcp_"`		Result filename prefix

Port#

port = 80

The TCP port probed on every target. Common choices are 80, 443, and 22.

HTTP Settings

Mon, 01 Jan 0001 00:00:00 +0000

HTTP Settings#

💡 Tip: You can change these settings directly in the bgscan application instead of editing the TOML file manually.

Navigate to Settings → HTTP Settings in the main menu to configure these options interactively using the TUI inspector.

Configuration file: settings/http_settings.toml

The HTTP probe sends one request per target and records status code, negotiated protocol version, and whether TLS was used. HTTP/1.1 and HTTP/2 go over TCP, HTTP/3 over QUIC.

DNS Settings

Mon, 01 Jan 0001 00:00:00 +0000

DNS Settings#

Tip: You can change these settings directly in the bgscan application instead of editing the TOML file manually.

Navigate to Settings → DNS Settings in the main menu to configure these options interactively using the TUI inspector.

Configuration file: settings/dns_settings.toml

This file has two sections. The resolver section controls plain DNS resolver testing. The dns_tunneling section controls how DNS tunnel scans are orchestrated — tunnel protocol-specific settings (DNSTT, VayDNS, Slipstream, MasterDNS, StormDNS, TheFeed) are stored in separate config files under assets/dns-tunneling/.

Xray Settings

Mon, 01 Jan 0001 00:00:00 +0000

Xray Settings#

💡 Tip: You can change these settings directly in the bgscan application instead of editing the TOML file manually.

Navigate to Settings → Xray Settings in the main menu to configure these options interactively using the TUI inspector.

Configuration file: settings/xray_settings.toml

This file controls the Xray outbound validation module, which tests connectivity and bandwidth to remote servers.

Quick Reference#

Setting	Default	Description
`timeout`	platform-dependent	Maximum duration (in milliseconds) to wait for the Xray connectivity test to complete.
`speed_test_timeout`	platform-dependent	Maximum duration (in milliseconds) to wait for each download/upload speed test.
`workers`	platform-dependent	Number of concurrent workers performing Xray connectivity tests.
`connectivity_test_type`	`3`	Type of connectivity test: 0 = connectivity only, 1 = download only, 2 = upload only, 3 = both download and upload.
`download_speed`	platform-dependent	Minimum acceptable download speed in Kbps (used when the test type includes download).
`upload_speed`	platform-dependent	Minimum acceptable upload speed in Kbps (used when the test type includes upload).
`output_prefix`	`"xray_"`	Filename prefix applied to all output files generated by this module.
`pre_scan_type`	`"tcp"`	Pre-scan connectivity test to perform before running Xray: `none`, `icmp`, `tcp`, or `http`.
`max_concurrent_dials`	platform-dependent	Max concurrent outbound dials process-wide (`0` = unlimited).
`dial_max_attempts`	platform-dependent	Dial attempts per outbound dispatch.

Timeout#

timeout = 6000

Maximum duration (in milliseconds) to wait for an Xray connectivity test to complete. Tests failing to respond within this window are considered failed.