Bisq 2 (v2.1.10) ignoring --torControlPort CLI flags on Tails OS

[stingray9]

Environment:

OS: Tails 6.x (Amnesic Incognito Live System)

App Version: Bisq 2.1.10 (Commit: 1e32b0f21d)

Networking: Restricted firewall (only Port 9050/9150/951 allowed)

The Issue:
I am attempting to run Bisq 2 on Tails. Due to the Tails firewall, the application must use the system-provided Tor instance via the filtered control port.

However, despite launching the application with explicit CLI flags, the logs indicate that Bisq 2 is disregarding these settings and attempting to spin up an internal Tor process on random ephemeral ports. Because non-system Tor processes are blocked by the Tails firewall, the app hangs at 5% and eventually times out.

Observed Behavior in Logs:

Flag Ignoring: Launched with --torControlPort=951 (or 9051), but log shows: Successfully connected control socket to Tor port [RANDOM_PORT] (e.g., 36345, 38521, 37105).

Firewall Rejection: The terminal loops: WARN BOOTSTRAP PROGRESS=5 TAG=conn SUMMARY="Connecting to a relay" WARNING="Connection refused".

Final Crash: bisq.network.tor.controller.exceptions.TorBootstrapFailedException: Could not bootstrap Tor in 240 seconds.

CLI Command Attempted:
JAVA_TOOL_OPTIONS="-Djava.net.preferIPv4Stack=true" /opt/bisq2/bin/Bisq2 --torControlPort=951 --torProxyAddress=127.0.0.1:9050 --torControlPassword=

Question:
How can I force Bisq 2 to respect the specified torControlPort on a restricted system like Tails? Is there a way to hardcode these values in a configuration file (like bisq2.yml) since the CLI flags are being ignored?

[stingray9]

Update: Tried a forced configuration file and manual CLI flags, but the app continues to ignore them. Latest logs show it still selecting a random high port:
00:19:26.165 INFO ... Successfully connected control socket to Tor port 45571
This confirms the --torControlPort flag is not being respected by the binary on Tails.

[HenrikJannsen]

The parameters you used are from Bisq 1, they are not present in Bisq 2.

Use -Dapplication.network.configByTransportType.tor.useExternalTor=true. This should tell the app to use the system tor.

Beside that you can pass

-Dapplication.network.configByTransportType.tor.torrcOverrides={
  key1: "value1",
  key2: "value2"
}```
to override the default torrc values.

[HenrikJannsen]

To run Bisq with jvm args is usually done by:

JAVA_OPTS="-Dapplication.network.configByTransportType.tor.useExternalTor=true" \
    apps/desktop/desktop-app/build/install/desktop-app/bin/desktop-app

[stingray9]

@HenrikJannsen Thank you for the suggestion! I applied those exact JVM arguments, but unfortunately, Bisq 2 is still ignoring the external Tor directive and attempting to spin up its own internal Tor on a random port.

Because I am on Tails OS, the system firewall instantly blocks these unauthorized internal Tor connections, resulting in the same Connection refused loop.

The command I ran:
Bash

JAVA_OPTS="-Dapplication.network.configByTransportType.tor.useExternalTor=true -Dapplication.network.configByTransportType.tor.torrcOverrides={ControlPort:951,SocksPort:9050}" /opt/bisq2/bin/Bisq2

The resulting logs (showing it still assigns a random port):
Plaintext

02:06:10.377 INFO [TOR-DefaultNode.initialize] b.n.t.c.TorControlProtocol: Successfully connected control socket to Tor port 43895 after 1 attempts
...
02:06:11.575 INFO [TorControlReader.start] b.n.t.c.TorControlReader: Received reply from Tor control server: 650 STATUS_CLIENT WARN BOOTSTRAP PROGRESS=5 TAG=conn SUMMARY="Connecting to a relay" WARNING="Connection refused" REASON=CONNECTREFUSED COUNT=1 RECOMMENDATION=ignore HOSTID="889EDCB19B237F20ADB525960C39E0B00398D6B1" HOSTADDR="37.46.199.86:4500"

It seems the useExternalTor=true flag is either being overwritten later in the startup sequence, or the torrcOverrides aren't successfully pointing it to the Tails system proxy. Is there another layer where this needs to be disabled, or is this a bug in the flag parsing?

[HenrikJannsen]

I guess the jvm args syntax has issues.

try:

JAVA_OPTS="-Dapplication.network.configByTransportType.tor.useExternalTor=true \
-Dapplication.network.configByTransportType.tor.torrcOverrides='{ControlPort:951,SocksPort:9050}'" \
/opt/bisq2/bin/Bisq2

or:

/opt/bisq2/bin/Bisq2 \
-Dapplication.network.configByTransportType.tor.useExternalTor=true \
-Dapplication.network.configByTransportType.tor.torrcOverrides='{ControlPort:951,SocksPort:9050}'

I am not sure if the binary takes the JAVA_OPTS. If you can run from source use:

JAVA_OPTS="-Dapplication.network.configByTransportType.tor.useExternalTor=true" \
    apps/desktop/desktop-app/build/install/desktop-app/bin/desktop-app

This should work for sure.

@alvasw Any idea?

[stingray9]

@HenrikJannsen Thanks for sticking with me on this! I have some fantastic debugging data for you. We managed to bypass the terminal crashes and get the GUI to launch, but we uncovered three distinct bugs in how Bisq 2 handles the useExternalTor configuration on Linux/Tails.

Bug 1: torrcOverrides Type Parsing Errors
Passing the JSON object string (torrcOverrides='{...}') caused a WrongType ConfigException (torrcOverrides has type STRING rather than OBJECT).

I bypassed that by passing the keys individually, but immediately hit a ClassCastException because the Typesafe Config library infers the ports as Integers, and TorTransportConfig.java strictly expects Strings:
java.lang.ClassCastException: class java.lang.Integer cannot be cast to class java.lang.String

The Workaround: I successfully bypassed both crashes by forcing the arguments as strings with escaped quotes:

Bash
/opt/bisq2/bin/Bisq2
-Dapplication.network.configByTransportType.tor.useExternalTor=true
-Dapplication.network.configByTransportType.tor.torrcOverrides.ControlPort="951"
-Dapplication.network.configByTransportType.tor.torrcOverrides.SocksPort="9050"
Bug 2: Hardcoded Control Socket Path Timeout
With the string override above, the GUI finally launched! However, it immediately crashed with a 5000ms timeout popup:
An error occurred at initializing Bisq: File did not exist after 5000 ms: /home/amnesia/.local/share/Bisq2/tor/control/control

It appears that even when useExternalTor=true is active, the startup sequence still hardcodes the control socket lookup to its internal directory rather than checking standard system defaults (like /var/run/tor/control on Tails/Debian) or skipping the file check entirely.

Bug 3: external_tor.config Connection Failure
To test a bypass for Bug 2, I created a symlink from Bisq's internal folder directly to the actual Tails Tor control socket (ln -s /var/run/tor/control ~/.local/share/Bisq2/tor/control/control).

While this tricked the file check, the connection still failed with this warning in the logs:
WARN [TOR-DefaultNode.initialize] b.n.t.TorService: Couldn't connect to external Tor control server. This could happen if the control port is not correctly set up in 'external_tor.config' file.

Relevant Logs:

Plaintext
09:51:27.898 INFO [TOR-DefaultNode.initialize] b.n.p.n.t.TorTransportService: Initialize Tor
09:51:27.904 WARN [TOR-DefaultNode.initialize] b.n.t.TorService: Couldn't connect to external Tor control server. This could happen if the control port is not correctly set up in 'external_tor.config' file.
...
09:51:33.068 ERROR [TOR-DefaultNode.initialize] b.d.DesktopApplicationService: Initializing applicationService failed java.util.concurrent.CompletionException: java.lang.RuntimeException: Error while waiting for tor control port file to exist
Caused by: java.lang.RuntimeException: Error while waiting for tor control port file to exist
at bisq.network.tor.TorService.initialize(TorService.java:161)
It seems TorService is failing to authenticate or properly bridge to the external Tor control server, potentially due to how it handles (or fails to generate) the external_tor.config logic when overrides are used.

Let me know if there is a different syntax or another flag I can test to get past the external_tor.config block!

[HenrikJannsen]

Thanks for the debugging and details report.
I think the useExternalTor case is used on Bisq Easy mobile app. @wodoro can you confirm? I lost a bit track...

I have myself not time atm to dig into that and would be better if a dev with Tails OS could work on that.
@alvasw Would you be available to look into that?

[wodoro]

On mobile client app we support using external tor, which uses different lib from bisq2 repo
I don't think we support external tor on node app

[wodoro]

As a side note though, i had problem setting overrides on bisq2 one time I tried, my use case was adding bridges, but couldn't add multiple ones due to keys being used in map rather than list, so i could only use one, and even then it wasn't working for some reason I think

[wodoro]

@stingray9 I think the problem you are having is easily solved by configuring the file tor/external_tor.config in the application data directory (while keeping the -Dapplication.network.configByTransportType.tor.useExternalTor=true flag)

[stingray9]

@wodoro Thank you for looking into this! I tested your bypass on Tails OS by creating the ~/.local/share/Bisq2/tor/external_tor.config file and launching with the useExternalTor=true flag.

It successfully bypassed the previous path check, but the application crashed with a NullPointerException at TorService.java:352. It appears it is trying to run String.split() on a missing config value:

Plaintext
03:35:34.666 ERROR [TOR-DefaultNode.initialize] b.d.DesktopApplicationService: Initializing applicationService failed java.util.concurrent.CompletionException: java.lang.NullPointerException: Cannot invoke "String.split(String)" because "controlPortString" is null
Caused by: java.lang.NullPointerException: Cannot invoke "String.split(String)" because "controlPortString" is null
at bisq.network.tor.TorService.getControlHostAndPort(TorService.java:352)
at bisq.network.tor.TorService.connectedToExternalTor(TorService.java:284)
at bisq.network.tor.TorService.initialize(TorService.java:109)
Could you provide the exact formatting/schema expected inside external_tor.config? I used standard key-value pairs (controlPort=951, socksPort=9050, host=127.0.0.1), but it seems the parser is looking for a specific key or a combined string format (like ControlPort="127.0.0.1:951") to split.