Router configuration

emissary-cli can be configured via either command-line arguments or a configuration file (router.toml). Modifying router.toml is just a way of passing command line arguments to the router at boot. For example, running emissary-cli with --allow-local and setting option allow_local = true in the config file will have the same effect.

Options specified on the command line take precedence over those in the config file.

Example router.toml:

allow_local = false
floodfill = false
insecure_tunnels = false

[http-proxy]
port = 4444
host = "127.0.0.1"

# upnp enabled, nat-pmp disabled
[port-forwarding]
upnp = true
nat_pmp = false
name = "emissary"

# host not specified
# upnp is used to resolve external address
[ntcp2]
port = 25515
publish = true

# i2cp disabled
# [i2cp]
# port = 7654

[sam]
tcp_port = 7656
udp_port = 7655

Available options

Run emissary-cli --help to show the built-in help message with all available options.

General options

Option	Config file	CLI	Description
Base path	-	-b, --base-path <PATH>	HTTP proxy port. (default: 4444)
Logging	log	-l, --log <LOG>	Logging targets. By default, INFO is enabled for all logging targets
Floodfill	floodfill	--floodfill	Run the router as a floodfill. (default: false)
Insecure tunnels	insecure_tunnels	--insecure-tunnels	Allow insecure tunnels. Disables /16 subnet and maximum tunnel participation checks. Should only be used for testing. (default: false)
Capabilities	caps	--caps <CAPS>	Router capabilities
Network ID	net_id	--net-id <NET-ID>	Network ID the router belongs to (default: 2)
Overwrite config	-	--ovewrite-config	Overwrite existing configuration file with defaults.

NTCP2

Config file section: [ntcp2]

Option	Config file	CLI	Description
Port	port	-	Port to listen for incoming NTCP2 connections. (default: random port between 9151-30777)
Host	host	-	Public IPv4 address for incoming connections. Can be auto-discovered via UPnP/NAT-PMP if left empty.
Publish	publish	-	Publish the address in router info for incoming connections. (default: true)

Example:

[ntcp2]
port = 25515
host = "203.0.113.50"
publish = true

SSU2

WARNING

SSU2 is still in development and is not recommended for general use

Config file section: [ssu2]

Option	Config file	CLI	Description
Port	port	-	Port to listen for incoming SSU2 connections.
Host	host	-	Public IPv4 address for incoming connections. Can be auto-discovered via UPnP/NAT-PMP if left empty.
Publish	publish	-	Publish the address in router info for incoming connections. (default: false)

Example:

[ssu2]
port = 25516
publish = true

INFO

IPv6 is currently not supported for either transport.

HTTP proxy

Config file section: [http-proxy]

Option	Config file	CLI	Description
Port	port	--http-proxy-port <PORT>	HTTP proxy port. (default: 4444)
Host	host	--http-proxy-host <HOST>	HTTP proxy bind address. (default: 127.0.0.1)
Outproxy	outproxy	--http-outproxy <HOST>	HTTP outproxy for clearnet access.

Example:

[http-proxy]
port = 4444
host = "127.0.0.1"
outproxy = "http://exit.stormycloud.i2p"

INFO

HTTP proxy requires SAM to be enabled.

SOCKS proxy

Config file section: [socks-proxy]

Option	Config file	CLI	Description
Port	port	--socks-proxy-port <PORT>	SOCKS proxy port. (default: 4447)
Host	host	--socks-proxy-host <HOST>	SOCKS proxy bind address. (default: 127.0.0.1)

Example:

[socks-proxy]
port = 4447
host = "127.0.0.1"

INFO

SOCKS proxy requires SAM to be enabled.

SAMv3

Config file section: [sam]

Option	Config file	CLI	Description
TCP Port	tcp_port	-	SAM TCP port. (default: 7656)
UDP Port	udp_port	-	SAM UDP port for datagrams. (default: 7655)
Host	host	-	SAM bind address. (default: 127.0.0.1)

Example:

[sam]
tcp_port = 7656
udp_port = 7655
host = "127.0.0.1"

I2CP

Config file section: [i2cp]

Option	Config file	CLI	Description
Port	port	-	I2CP port. (default: 7654)
Host	host	-	I2CP bind address. (default: 127.0.0.1)

Example:

[i2cp]
port = 7654
host = "127.0.0.1"

Address book

Config file section: [address-book]

Option	Config file	CLI	Description
Default	default	-	Default address book subscription URL for initial bootstrap.
Subscriptions	subscriptions	-	List of additional address book subscription URLs.

Example:

[address-book]
default = "http://udhdrtrcetjm5sxzskjyr5ztpeszydbh4dpl3pl4utgqqw2v4jna.b32.i2p/hosts.txt"
subscriptions = ["http://your-favorite-address-service.i2p/hosts.txt"]

INFO

Address book requires SAM to be enabled. If disabled, .i2p host lookups are not supported and all connections must use .b32.i2p addresses.

Exploratory tunnels

Config file section: [exploratory]

Option	Config file	CLI	Description
Inbound length	inbound_len	--exploratory-inbound-len <NUM>	Length of inbound exploratory tunnels.
Inbound count	inbound_count	--exploratory-inbound-count <NUM>	Number of inbound exploratory tunnels.
Outbound length	outbound_len	--exploratory-outbound-len <NUM>	Length of outbound exploratory tunnels.
Outbound count	outbound_count	--exploratory-outbound-count <NUM>	Number of outbound exploratory tunnels.

Example:

[exploratory]
inbound_len = 2
inbound_count = 3
outbound_len = 2
outbound_count = 3

Transit tunnels

Transit tunnels allow your router to participate in the I2P network by relaying traffic for other routers.

Config file section: [transit]

Option	Config file	CLI	Description
Max tunnels	max_tunnels	--max-transit-tunnels <NUM>	Maximum number of transit tunnels. (default: 1000)
Disable	-	--disable-transit-tunnels	Disable transit tunnel participation entirely. Router will publish G caps.

Example:

[transit]
max_tunnels = 10_000

INFO

Disabling transit means the router is started with G caps, i.e., "rejecting all tunnels" and all inbound tunnel build requests are rejected.

Port forwarding (UPnP/NAT-PMP)

Automatic port forwarding and external address discovery.

Config file section: [port-forwarding]

Option	Config file	CLI	Description
UPnP	upnp = true	-	Enable UPnP. (default: true)
NAT-PMP	nat_pmp = true	-	Enable NAT-PMP. (default: true)
Name	name	--upnp-name <NAME>
Disable UPnP	upnp = false	--disable-upnp	Disable UPnP via CLI.
Disable NAT-PMP	nat_pmp = false	--disable-nat-pmp	Disable NAT-PMP via CLI.

Example:

[port-forwarding]
name = "emissary"
nat_pmp = true
upnp = false

INFO

NAT-PMP is tried first and if it's not available, UPnP is used as a fallback. If neither protocol is available, ports must be forwarded manually.

Reseeding

Config file section: [reseed]

Option	Config file	CLI	Description
Hosts	hosts	--reseed-hosts <HOST>...	Comma-separated list of reseed host URLs.
Threshold	reseed_threshold	--reseed-threshold <NUM>	Minimum number of known routers before requesting reseed. (default: 25)
Disable	-	--disable-reseed	Don't reseed even if there aren't enough routers.
Force	-	--force-reseed	Forcibly reseed even if there are enough routers.
Disable force IPv4	-	--disable-force-ipv4	Disable forcing IPv4 when connecting to reseed hosts.

Example:

[reseed]
reseed_threshold = 25
hosts = ["https://specific-reseed-host.com/"]

Metrics

Prometheus-compatible metrics server.

See the debugging guide for more information on metrics.

Config file section: [metrics]

Option	Config file	CLI	Description
Port	port	--metrics-server-port <PORT>...	Metrics server port. (default: 7788)
Disable	-	--disable-metrics	Disable metrics server

Example:

[metrics]
port = 7788

Client tunnels

Client tunnels forward local ports to remote I2P destinations.

Config file section: [[client-tunnels]]

Option	Config file	Description
Name	name	Unique name for the tunnel.
Address	address	Local bind address.
Port	port	Local port to listen on.
Destination	destination	Remote I2P destination (.i2p or .b32.i2p).
Destination port	destination_port	Remote destination port.

Example:

[[client-tunnels]]
name = "irc"
address = "127.0.0.1"
port = 6668
destination = "irc.postman.i2p"
destination_port = 6667

INFO

Client tunnels require SAM to be enabled. Each tunnel must have a unique name and port.

Server tunnels

Server tunnels expose local services to the I2P network.

Config file section: [[server-tunnels]]

Option	Config file	Description
Name	name	Unique name for the tunnel.
Port	port	Local port where the service is running.
Destination path	destination_path	Path to the destination keys file.

Example:

[[server-tunnels]]
name = "my-website"
port = 8080
destination_path = "/path/to/base64-destination.keys"

INFO

Server tunnels require SAM to be enabled. Each tunnel must have a unique name, port, and destination path.

Enabling and disabling subsystems

To disable a subsystem, remove or comment out its section in router.toml. To re-enable it, uncomment the section and restart the router.

For most subsystems (I2CP, SAM, transports), disabling them means the service is not started and routers/applications cannot connect to those endpoints.

Examples

Transit tunnels disabled, address book enabled:

# [transit]
# max_tunnels = 10000

[address-book]
default = "http://udhdrtrcetjm5sxzskjyr5ztpeszydbh4dpl3pl4utgqqw2v4jna.b32.i2p/hosts.txt"
subscriptions = ["http://your-favorite-address-service.i2p/hosts.txt"]

Address book, SAM and HTTP proxy disabled, I2CP enabled:

# [address-book]
# default = "http://udhdrtrcetjm5sxzskjyr5ztpeszydbh4dpl3pl4utgqqw2v4jna.b32.i2p/hosts.txt"
# subscriptions = []

# [http-proxy]
# port = 4444
# host = "127.0.0.1"

# [sam]
# tcp_port = 7656
# udp_port = 7655

[i2cp]
port = 7654

SAM and address book enabled but no hosts.txt downloaded:

[address-book]
# default = "http://udhdrtrcetjm5sxzskjyr5ztpeszydbh4dpl3pl4utgqqw2v4jna.b32.i2p/hosts.txt"
# subscriptions = []

[sam]
tcp_port = 7656
udp_port = 7655