Skip to main content

Configuration file

b4 keeps its configuration in one JSON file, /etc/b4/b4.json by default. The --config flag points it elsewhere.

Where it lives​

PlatformPath
Linux/etc/b4/b4.json
OpenWRT (with extroot or USB storage)/opt/etc/b4/b4.json
OpenWRT (without USB storage)/etc/b4/b4.json
ASUS Merlin/opt/etc/b4/b4.json
Keenetic/opt/etc/b4/b4.json
Docker/etc/b4/b4.json, inside the container

Without --config, b4 looks for b4.json and config.json under /etc/b4 and /opt/etc/b4, and falls back to /etc/b4/b4.json. The log names the path it settled on at startup.

The Download Configuration card under Settings > System > Backup saves the configuration in the form b4 writes to this file. Its safe copy masks credentials and private host names for sharing, and b4 refuses to load or save a configuration that still holds the safe copy's [redacted] placeholders.

Only what differs from the defaults is stored​

The file is sparse. A setting that holds its built-in default is left out, so a fresh installation writes a very short file, and a section whose settings were never changed is absent. A missing key is not a missing setting, and adding it back with its default value changes nothing. Saves from the web interface, the API and MCP write the file the same way.

Structure​

{
"version": 52,
"queue": {
"start_num": 537,
"threads": 4,
"mark": 32768,
"ipv4": true,
"ipv6": false,
"tcp_conn_bytes_limit": 19,
"udp_conn_bytes_limit": 8,
"interfaces": [],
"mss_clamp": { "enabled": false, "size": 88 },
"devices": { "enabled": false, "vendor_lookup": false }
},
"system": {
"tables": {
"skip_setup": false,
"monitor_interval": 10,
"engine": "",
"masquerade": { "enabled": false, "interfaces": [] },
"dscp": { "enabled": false, "value": 0, "interfaces": [] }
},
"logging": {
"level": 1,
"directory": "/var/log/b4",
"instaflush": true,
"syslog": false
},
"web_server": {
"port": 7000,
"bind_address": "0.0.0.0",
"expose": false,
"tls_cert": "",
"tls_key": "",
"username": "",
"password": "",
"language": "en",
"mcp": { "enabled": false, "allow_writes": false }
},
"dns": {
"tcp_disabled": false,
"tcp_port": 5453,
"query_timeout_sec": 5,
"keep_ipv6_answers": false
},
"socks5": {
"enabled": false,
"port": 1080,
"bind_address": "0.0.0.0",
"expose": false,
"allowed_sources": ["192.168.1.0/24", "127.0.0.1/32"]
},
"mtproto": { "enabled": false, "port": 3128, "bind_address": "0.0.0.0", "expose": false },
"checker": {
"discovery_timeout": 5,
"config_propagate_ms": 1500,
"dns_server": ""
},
"geo": { "sitedat_path": "", "ipdat_path": "", "sitedat_url": "", "ipdat_url": "" },
"timezone": ""
},
"sets": []
}

The sample shows some of the sections and some of their keys. A real file holds only the keys that differ from the default.

  • system.mtproto.secrets is a list of named secrets, each with id, name, secret and enabled. A file written before configuration version 50 held a single mtproto.secret string, which the migration moves into the list as an entry named default.
  • system.socks5.allowed_sources is absent while the list is empty, the default, and the proxy then accepts any source. Each entry is an IP address or a CIDR range. 0.0.0.0/0, ::/0 and malformed entries are refused when the file is loaded or saved.

The queue section​

KeyMeaningDefault
start_numThe first NFQUEUE number537
threadsNumber of worker threads4
markThe queue mark, see Packet marks32768
ipv4Process IPv4 traffictrue
ipv6Process IPv6 trafficfalse
tcp_conn_bytes_limitHow many packets at the start of a TCP connection b4 inspects19
udp_conn_bytes_limitThe same for UDP8
interfacesCapture Interfaces, a filter on the interface a packet passes. Empty means all of them[]

tcp_conn_bytes_limit and udp_conn_bytes_limit apply to every set. A set's own tcp.conn_bytes_limit and udp.conn_bytes_limit have no effect, and the web interface has no field for them.

queue.ipv6 decides whether b4 processes IPv6, not whether the router uses it. Off, the default, b4 processes IPv4 only and writes no IPv6 firewall rules for any set, so a client that reaches a site over IPv6 bypasses the sets. b4 then removes IPv6 addresses from DNS answers for the domains sets match, see DNS. The exception is NFQUEUE mode while an enabled set has dns.strip_ech on. In that mode b4 writes IPv6 rules for DNS answers and DNS over TCP, only to remove their ECH keys. A change takes full effect after a restart. --ipv6 sets the same thing for one run.

The sets section​

Each set is one object in the sets array, carrying its whole configuration. Its keys follow the tabs of the set editor:

  • targets - domains, IPs, GeoSite and GeoIP categories, ASNs, source devices
  • tcp - general TCP settings, the real TCP window, desync, window, incoming, RST protection
  • fragmentation - the fragmentation method and its parameters
  • faking - SNI faking, SYN fakes, mutation
  • udp - the QUIC filter, the port filter, the handling of calls and the UDP action mode
  • dns - the set's resolvers and pins
  • routing - routing mode, output interface, upstream proxy or blocking
  • dscp - the set's own DSCP value
  • discovery - the set's Discovery addresses and its watchdog switch
  • escalate - which set to escalate to when this one stops working

The Import/Export tab of the set editor shows a set as JSON and takes a pasted one back. The exported JSON leaves out values equal to the defaults and the settings of switched-off features. It also leaves out the set's id, source devices, targets.ip_priority, watchdog switch and escalation settings, and, when the set has source devices, its dscp. A JSON imported into a set keeps that set's own targets.ip_priority.

A set's dscp​

KeyMeaningDefault
dscp.enabledEnable per-set DSCP: write the set's own value into the packets to the set's addresses, see DSCPfalse
dscp.valueThe value written into the DSCP field, 0-63. 0 clears the field0

Each key is stored only while it differs from its default: the switch on with the value 0 is saved as "dscp": {"enabled": true}, a value kept with the switch off as "dscp": {"value": 12}. While dscp.enabled is true, a dscp.value outside 0-63 is refused, not clamped: the web interface refuses the save, and a file that holds one stops b4 at start. Neither key is writable over MCP or carried in a shared set.

A set's tcp.wssize​

KeyMeaningDefault
tcp.wssize.enabledRewrite the real TCP window, see Real TCP window (wssize)false
tcp.wssize.windowThe value written into the window field, 0-65535. 0 leaves the window unchanged0
tcp.wssize.scaleThe upper limit for the Window Scale option of the SYN, 0-14. 0 leaves the option unchanged0
tcp.wssize.strip_scaletrue removes the Window Scale option from the SYN, Remove the option in the editor. tcp.wssize.scale is then not used and is reset to 0 on savefalse
tcp.wssize.cutoffWhere the rewrite stops: empty for After the ClientHello, first_data for After the first data packet. Any other value is read as emptyempty

While tcp.wssize.enabled is true, a number outside its range is refused, and so is an enabled set that also has routing.enabled or tcp.duplicate.enabled: the web interface refuses the save, and a file that holds one stops b4 at start. The switch on with both numbers 0 and strip_scale off is saved as "wssize": {"enabled": true} and changes no packet. The keys are writable over MCP. A shared set carries them only while one of the numbers is above 0 or strip_scale is true.

A set's calls: udp.filter_stun and udp.filter_l7​

Calls on a set's UDP tab is stored in two keys, see Sets for calls.

CallsStored as
Pass call setupudp.filter_stun is true, the default
Handle like other UDPudp.filter_stun is false
Handle only callsudp.filter_l7 lists the calls of Which calls: ["discord", "stun"] for Discord app and browsers, ["discord"] for Discord app, ["stun"] for Browsers

A non-empty udp.filter_l7 means Handle only calls whatever udp.filter_stun holds, and udp.filter_stun then has no effect. An empty list is not stored. A set with the list needs a udp.dport_filter, no targets.sni_domains, targets.ip, targets.geosite_categories, targets.geoip_categories or targets.asns, and an empty tcp.dport_filter. A set that breaks this is refused: the web interface refuses the save, and a file that holds one stops b4 at start. An escalate.to that names a set with the list is cleared, with a warning in the log. An unknown entry stays in the list, matches no traffic and is logged as a warning. (auto: STUN request) is "fake_payload_file": "@stun" under udp. udp.filter_l7 is writable over MCP, with discord and stun as its only entries, and is carried in a shared set.

A set's resolvers: dns.doh_url, dns.target_dns and dns.upstreams​

Resolvers on a set's DNS & Routing tab is stored in three keys, see A set with more than one resolver.

ResolversStored as
The first entry, when it is an https:// URLdns.doh_url
The first entry, when it is an IP addressdns.target_dns
The other entries, in the order of the fielddns.upstreams, a list of strings

b4 asks dns.doh_url first when it is filled, otherwise dns.target_dns, then the entries of dns.upstreams in their order: eight resolvers at most, the first one included. A set with dns.enabled and only dns.upstreams filled redirects its domains as well. An empty list is not stored.

dns.target_dns holds an IP address and nothing else. A host name or a URL there gives the set no resolver, and the set's queries pass on unchanged unless dns.upstreams holds a usable entry. An entry of dns.upstreams is an IP address without a port or an https:// URL. While dns.enabled is true, any other entry is refused, and so are 0.0.0.0 and a URL without a host or with a user name: the web interface refuses the save, and a file that holds one stops b4 at start. With dns.enabled off, the list is stored as written and not checked.

While dns.enabled is true, b4 also drops an entry that repeats the first resolver or an earlier entry, and drops the entries past the eighth resolver with a warning in the log. dns.upstreams is writable over MCP as one comma-separated value that replaces the whole list. It is never carried in a shared set, and neither is dns.target_dns.

Settings and their configuration paths​

The tables list the fields of the web interface with the path that stores each one. Paths under the set editor are relative to one set object in the sets array, so dns.strict is sets[].dns.strict.

Settings > Core​

Sub-tabFieldPath
Packet EngineIngestion modequeue.mode
Packet EngineUplink interfacequeue.tun.out_interface
Packet EngineUplink gatewayqueue.tun.out_gateway
Packet EngineTUN addressqueue.tun.address
Packet EngineTUN device namequeue.tun.device_name
Packet EngineCapture Interfacesqueue.interfaces
Packet EngineRetest interval (seconds)system.ip_health.retest_interval_sec
Packet EngineRemember blocked addressessystem.ip_health.bans_off, inverted: the switch on is false
Packet EngineFirst ban (hours)system.ip_health.ban_ttl_sec, in seconds
Packet EngineRepeat ban (days)system.ip_health.repeat_ban_ttl_sec, in seconds
Packet EngineEnable IPv4 Supportqueue.ipv4
Packet EngineEnable IPv6 Supportqueue.ipv6
Packet EngineForce IPv4 for matched domainssystem.dns.keep_ipv6_answers, inverted: the switch on is false
Packet EngineQueue Start Numberqueue.start_num
Packet EnginePacket Markqueue.mark
Packet EngineWorker Threadsqueue.threads
Packet EngineTCP Connection Packets Limitqueue.tcp_conn_bytes_limit
Packet EngineUDP Connection Packets Limitqueue.udp_conn_bytes_limit
DevicesEnable Device Filteringqueue.devices.enabled
DevicesExclude Selected Devices (Blacklist)queue.devices.wisb
DevicesVendor Lookupqueue.devices.vendor_lookup
DevicesThe devices selected in Available Devices and added in Manual Devicesqueue.devices.devices
FirewallSkip IPTables/NFTables Setupsystem.tables.skip_setup
FirewallFirewall Enginesystem.tables.engine
FirewallFirewall Monitor Interval (seconds)system.tables.monitor_interval
FirewallEnable Global MSS Clampingqueue.mss_clamp.enabled
FirewallMSS Sizequeue.mss_clamp.size
FirewallEnable NAT Masqueradesystem.tables.masquerade.enabled
FirewallThe interface tags of NAT Masqueradesystem.tables.masquerade.interfaces
FirewallSet DSCPsystem.tables.dscp.enabled
FirewallDSCP valuesystem.tables.dscp.value
FirewallThe interface tags of DSCPsystem.tables.dscp.interfaces
DNSIntercept DNS over TCPsystem.dns.tcp_disabled, inverted: the switch on is false
DNSListener portsystem.dns.tcp_port
DNSQuery timeoutsystem.dns.query_timeout_sec
DNSIdle timeoutsystem.dns.tcp_idle_sec
DNSRead/write timeoutsystem.dns.tcp_io_sec
DNSForward timeoutsystem.dns.tcp_dial_sec
SOCKS5Enable SOCKS5 Proxysystem.socks5.enabled
SOCKS5Bind Addresssystem.socks5.bind_address
SOCKS5Portsystem.socks5.port
SOCKS5Expose to internetsystem.socks5.expose
SOCKS5Usernamesystem.socks5.username
SOCKS5Passwordsystem.socks5.password
SOCKS5Allowed Sourcessystem.socks5.allowed_sources

Settings > System​

Sub-tabFieldPath
ServiceLanguagesystem.web_server.language
ServiceTime Zonesystem.timezone
ServiceMemory Limitsystem.memory_limit
ServiceUpdate mirrorssystem.update.mirrors
ServiceLog Levelsystem.logging.level
ServiceLog Directorysystem.logging.directory
ServiceInstant Flushsystem.logging.instaflush
ServiceSyslogsystem.logging.syslog
Web ServerBind Addresssystem.web_server.bind_address
Web ServerPortsystem.web_server.port
Web ServerExpose to internetsystem.web_server.expose
Web ServerTLS Certificatesystem.web_server.tls_cert
Web ServerTLS Keysystem.web_server.tls_key
Web ServerUsernamesystem.web_server.username
Web ServerPasswordsystem.web_server.password, stored as a hash

Settings > Geodat Settings​

CardFieldPath
Geosite DatabaseThe file that Update or Upload writessystem.geo.sitedat_path
Geosite DatabaseSourcesystem.geo.sitedat_url
GeoIP DatabaseThe file that Update or Upload writessystem.geo.ipdat_path
GeoIP DatabaseSourcesystem.geo.ipdat_url
Auto-updateRefresh on startupsystem.geo.auto_update.on_startup
Auto-updateSchedulesystem.geo.auto_update.interval: daily, weekly or monthly
Auto-updateLast runsystem.geo.auto_update.last_run, written by b4

Settings > Discovery​

CardFieldPath
Testing ConfigurationDiscovery Timeoutsystem.checker.discovery_timeout
Testing ConfigurationConfig Propagation Delaysystem.checker.config_propagate_ms
Testing ConfigurationTrusted DNS serversystem.checker.dns_server
WatchdogEnable Watchdogsystem.checker.watchdog.enabled
WatchdogCheck Intervalsystem.checker.watchdog.interval_sec
WatchdogFailure Re-check Intervalsystem.checker.watchdog.failure_interval
WatchdogHealing Cooldownsystem.checker.watchdog.cooldown_sec
WatchdogCheck Timeoutsystem.checker.watchdog.timeout_sec
WatchdogMax Retriessystem.checker.watchdog.max_retries
WatchdogOlder per-domain listsystem.checker.watchdog.domains

Settings > Telegram​

CardFieldPath
MTProto ProxyEnable MTProto Proxysystem.mtproto.enabled
MTProto ProxyBind Addresssystem.mtproto.bind_address
MTProto ProxyPortsystem.mtproto.port
MTProto ProxyExpose to internetsystem.mtproto.expose
MTProto ProxyFake SNI Domainsystem.mtproto.fake_sni
MTProto ProxyMax Connectionssystem.mtproto.max_connections
MTProto ProxyTCP User Timeout (sec)system.mtproto.tcp_user_timeout_sec
MTProto ProxyIdle Timeout (sec)system.mtproto.idle_timeout_sec
SecretsThe list of secretssystem.mtproto.secrets
Telegram upstream (shared)Transport modesystem.mtproto.upstream_mode
Telegram upstream (shared)DC Relaysystem.mtproto.dc_relay
Telegram upstream (shared)Telegram setsystem.mtproto.upstream_set
Telegram upstream (shared)Cloudflare Worker domainsystem.mtproto.cfworker_domain
Telegram upstream (shared)Custom WebSocket domainsystem.mtproto.ws_custom_domain
Telegram upstream (shared)Telegram WS edge IPsystem.mtproto.ws_endpoint_host
Telegram upstream (shared)Fronting name for Telegram's WS edgesystem.mtproto.ws_front_sni
Telegram upstream (shared)CF proxy fallbacksystem.mtproto.cfproxy_enabled
Telegram upstream (shared)CF proxy domain list URLsystem.mtproto.cfproxy_url
Telegram upstream (shared)DC list fallback mirrorsystem.mtproto.dc_fallback_enabled
Telegram upstream (shared)DC list mirror URLsystem.mtproto.dc_fallback_url
Telegram upstream (shared)Bridge Handshake Wait (sec)system.mtproto.bridge_wait_sec
Telegram over WebSocketEnable Telegram over WebSocketsystem.mtproto.bridge.enabled
Telegram Desktop WEB proxyEnable the WEB carriersystem.mtproto.web_proxy.enabled
Telegram Desktop WEB proxyRelay hostnamesystem.mtproto.web_proxy.hostname
Telegram Desktop WEB proxyRelay portsystem.mtproto.web_proxy.port
Telegram Desktop WEB proxyExpose to internetsystem.mtproto.web_proxy.expose
Telegram Desktop WEB proxyCertificate filesystem.mtproto.web_proxy.tls_cert
Telegram Desktop WEB proxyPrivate key filesystem.mtproto.web_proxy.tls_key

Settings > Integrations​

CardFieldPath
IPinfoAccess tokensystem.api.ipinfo_token
AI AssistantEnable AI assistancesystem.ai.enabled
AI AssistantThe provider tabssystem.ai.provider
AI AssistantModelsystem.ai.model
AI AssistantEndpointsystem.ai.endpoint
AI AssistantMax tokenssystem.ai.max_tokens
AI AssistantTemperaturesystem.ai.temperature
AI AssistantTimeout (s)system.ai.timeout_sec
MCP serverEnable MCP serversystem.web_server.mcp.enabled
MCP serverAccess tokensystem.web_server.mcp.token
MCP serverAllow configuration changessystem.web_server.mcp.allow_writes
MCP serverAllow active probessystem.web_server.mcp.allow_active_probes
Community HubEnable Community Hubsystem.hub.enabled
Community HubHub mirrorssystem.hub.urls
Community HubHub public keysystem.hub.public_key

The AI API key is not part of this file. b4 keeps it in ai_secrets.json.

Set editor​

TabFieldPath
TargetsIP Version Filtertargets.ip_version
TargetsDomain-only matchingtargets.domain_only
TargetsIP prioritytargets.ip_priority
TCP > GeneralPort Filtertcp.dport_filter
TCP > GeneralRewrite the real TCP windowtcp.wssize.enabled
TCP > GeneralWindowtcp.wssize.window
TCP > GeneralWindow Scale optionLeave unchanged: tcp.wssize.scale 0 and tcp.wssize.strip_scale false. Lower to a value: tcp.wssize.scale above 0. Remove the option: tcp.wssize.strip_scale true
TCP > GeneralWindow Scaletcp.wssize.scale
TCP > GeneralStop rewritingtcp.wssize.cutoff, empty for After the ClientHello and first_data for After the first data packet
TCP > FakingGenerated Payloadfaking.payload_file, a path such as captures/tls_youtube_com.bin
UDPQUIC Matchingudp.filter_quic
UDPPort Filterudp.dport_filter
UDPCallsudp.filter_stun, true for Pass call setup and false for Handle like other UDP. Handle only calls is a non-empty udp.filter_l7, see A set's calls
UDPWhich callsudp.filter_l7, discord and stun for Discord app and browsers, discord for Discord app, stun for Browsers
UDPAction Modeudp.mode
UDPFake Packet Payloadudp.fake_payload_file, @stun for (auto: STUN request)
DNS & RoutingEnable DNS Redirectdns.enabled
DNS & RoutingResolversdns.doh_url or dns.target_dns for the first resolver and dns.upstreams for the others, see A set's resolvers
DNS & RoutingFragment DNS Queriesdns.fragment_query
DNS & RoutingFail closed when no resolver is reachabledns.strict
DNS & RoutingRemove ECH keys from DNS answersdns.strip_ech
DNS & RoutingPinned addressesdns.pins, each name mapped to its addresses
DNS & RoutingEnable per-set DSCPdscp.enabled
DNS & RoutingDSCP valuedscp.value
DiscoveryThe list of addressesdiscovery.urls
DiscoveryKeep this set working with the watchdogdiscovery.watchdog

Dashboard​

ControlPath
The layout saved by Customizeui.dashboard

Settings without a field​

These settings exist only in the file.

PathWhat it doesDefault
system.web_server.mcp.allowed_originsBrowser origins the MCP endpoint accepts besides b4's own address. A single * accepts any originEmpty
system.checker.watchdog.heal_validation_triesThe number of fetches in a row a strategy has to pass during a heal's search3
system.checker.watchdog.verify_triesThe number of tries each address gets in the check after a heal writes a strategy2
system.checker.discovery_flow_mark, system.checker.discovery_injected_markThe marks of Discovery's test traffic, see Packet marksThe queue mark plus 1 and plus 2
queue.tun.route_tableA fixed routing table for the TUN engine instead of a free one b4 picks, see Packet marksPicked by b4
sets[].routing.fwmark, sets[].routing.tableA pinned mark and table for a set that routes traffic, used only when both are set, see Packet marksPicked by b4

Editing it by hand​

version at the top is the configuration format version. b4 reads it to decide what needs migrating, so it stays unchanged when anything else is edited.

warning

The values in the file are checked only when b4 starts, and a file that fails the check stops b4 with an invalid configuration error. b4 reads the file only at start, so a manual edit takes effect after a restart. Any save before then writes the running configuration over the file, and the manual edit is lost. Saves come from the web interface, MCP, a watchdog heal, a geodata download and an ASN prefix update.

Migrations​

When the format changes between releases, b4 migrates the file at startup: new fields arrive with their defaults, and renamed ones are carried over. Before it changes anything, it writes a backup next to the file, named after the version it migrates from, for example b4.json.v51.bak.

A file that cannot be read at startup, for example one cut short by a power loss or left with a JSON syntax error, is copied next to itself as b4.json.corrupt. When an earlier copy with different content is there, the name is b4.json.corrupt.1 and onward. The log names the copy. b4 then starts on the defaults, and the next save replaces the original file, so the unreadable settings remain only in that copy.

A file whose version is higher than the running binary understands is loaded as it is, with a warning. Settings that binary does not know are dropped at the next save.