Control and Monitor Tor

From Whonix

onioncircuits - View Tor Circuits
Nyx Tor Controller


nyx is the primary Tor Controller option that comes pre-installed in Whonix ™.

Note: Vidalia and tor-ctrl have been deprecated and are no longer packaged in Debian.


Info The nyx [archive] Tor controller is a later version of the arm package, so the functionality and appearance are very similar. The Tor Project nyx homepage [archive] states: "Nyx is a command-line monitor for Tor. With this you can get detailed real-time information about your relay such as bandwidth usage, connections, logs, and much more."

Nyx Usage[edit]

Nyx is recommended and is already pre-installed in Whonix-Gateway ™. [1]

If you are using Qubes-Whonix ™, complete the following steps.

Qubes App Launcher (blue/grey "Q")Whonix-Gateway ™ ProxyVM (commonly named sys-whonix)Nyx - Status Monitor for Tor

If you are using a graphical Whonix-Gateway ™, complete the following steps.

Start MenuApplicationsSystemNyx - Status Monitor for Tor

If you are using a terminal Whonix-Gateway ™, type.


To receive a new circuit, press:


To exit nyx, press:


Nyx FAQ[edit]

Message / Question Response
arm vs nyx? The software was previously called arm, but the new name is nyx. [2]
Should any of the following nyx messages concern me? No; see below for reasons why. See also: Indicators of Compromise and Support Request Policy (rationale).
Am I compromised? Does nyx report leaks? Nyx is conceptually not a tool to discover serious issues such as a possible compromise or leaks. [3]
Nyx sometimes shows my public IP address and other times the internal and IPs. Is it normal or dangerous? [4] This is a normal nyx feature. Whonix ™ uses a Tor control port filter proxy (onion-grater) that prevents abuse of the ControlPort, including blocking dangerous commands like GETINFO address. When the real IP address appears, it is only local and nobody else can see it.
Tor is preventing system utilities like netstat and lsof from working. This means that nyx can't provide you with connection information. You can change this by adding 'DisableDebuggerAttachment 0' to your torrc and restarting tor. For more information see... [archive] If you want to learn about the technical details, read [archive].
DisableDebuggerAttachment even when running as root. This bug [archive] in nyx has been resolved.
man page (GENERAL OPTIONS and COMMAND-LINE OPTIONS) This bug [archive] in nyx has been resolved.
[WARN] Socks version 71 not recognized. (Tor is not an http proxy.)

This is caused by the whonixcheck function check_tor_socks_port_reachability. It checks if a Tor SocksPort is reachable by trying to fetch it using curl. [5] It will not report anything if it works, but will complain if it fails.

[WARN] Socks version 71 not recognized. (This port is not an HTTP proxy; did you want to use HTTPTunnelPort?) This occurs for similar reasons to the entry above.
[WARN] Rejecting request for anonymous connection to private address [scrubbed] on a TransPort or NATDPort. Possible loop in your NAT rules? This happens for example if you run "curl". The reason is when you type "curl" in Whonix ™, by default you are not directly using curl, but a uwt-wrapped (stream-isolated) curl instead. It does not try to directly connect to, but rather to connect to through Tor, leading to this Tor message. It really means an operation was attempted that will not work in that way. In this instance, deactivate the curl stream isolation wrapper or use the non-wrapped version - see Stream Isolation [archive].
[NOTICE] You configured a non-loopback address '' for SocksPort. This allows everybody on your local network to use your machine as a proxy. Make sure this is what you wanted. [1 duplicate hidden] (Or another port number or DnsPort or TransPort.) Tor really listens on that IP/port. It is Whonix-Gateway ™ network interface and is only available to Whonix-Workstation ™. This restriction is enforced by an internal network with Whonix-Workstation ™(s) and because Whonix-Gateway ™ is firewalled; see /usr/bin/whonix_firewall or the Whonix ™ source code for more information.
[NOTICE] New control connection opened. [2 duplicates hidden] (Or more duplicates.) This is caused by whonixcheck's Tor Bootstrap Status Test, which uses Tor's ControlPort or CPFP.
[NOTICE][NYX_WARN] The torrc differ from what tor's using. You can issue a sighup to reload the torrc values by pressing x. Configuration value is missing from the torrc: RunAsDaemon Nyx usability bug. [6] [7]
" UNKNOWN 1 / Guard" in circuit information This indicates that you are connecting to the Tor network with a Tor Bridge.

If you are directly connecting to the public Tor network without a Tor Bridge, the real IP and Nickname of the Guard should be visible instead. [8]

Onion Circuits[edit]

Onion Circuits is a GTK+ application to display Tor circuits and streams. It allows the user to inspect the circuits the locally running Tor daemon has built, along with some metadata for each node.


Onion Circuits [archive] is installed by default, but is not a full Tor controller; only Tor circuits are shown. It can be launched from the start menu.


Info Advanced users only.

Talking to the real Tor Control Port[edit]

On Whonix-Gateway ™, see Talking to the real Tor Control Port.


netcat provides an easy way to send Tor protocol commands to Tor's ControlPort form inside Whonix-Workstation ™. Actually for security reasons to onion-grater, the Tor Control Protocol Filter Proxy.

Inside Whonix-Workstation ™.

1. Install netcat.

sudo apt-get install netcat-openbsd

2. Connect to Tor's ControlPort. [10]

nc 9051

3. Example command to change the Tor circuit.

signal newnym

The output should be.

250 OK


On Whonix-Gateway ™, run. [11]

python3 tor-prompt

Will be greeted with the following or similar introduction message.

Welcome to Stem's interpreter prompt. This provides you with direct access to
Tor's control interface.

This acts like a standard python interpreter with a Tor connection available
via your 'controller' variable...

  >>> controller.get_info('version')
  ' (git-245ecfff36c0cecc)'

You can also issue requests directly to Tor...

  >>> GETINFO version
  250-version= (git-245ecfff36c0cecc)
  250 OK

For more information run '/help'.


Run any Tor control protocol command. For example GETINFO version. Replace GETINFO version with the actual command intended to run.

GETINFO version

Should show something similar to.

  250-version= (git-245ecfff36c0cecc)
  250 OK

New Identity and Tor Circuits[edit]

The behavior of "New Identity" in the context of Tor Browser and nyx is often misunderstood. First of all, there are various ways to issue a "New Identity" (this list is not exhaustive):

In all cases, the "New Identity" function sends the protocol command SIGNAL newnym to Tor's ControlPort.

Tor Browser's new identity function clears the browser state, closes tabs and obtains a fresh Tor circuit for future requests. [12]

Other Tor controllers such as nyx run only SIGNAL newnym.

Ambox warning pn.svg.png Warning: The New Identity feature will likely create a new circuit with a different Tor exit relay and IP address, but this is not guaranteed.

The impact of "signal newnym" on Tor circuit lifetimes is often misunderstood. "signal newnym" uses a fresh circuit for new connections. Sometimes Tor only replaces the middle relay while using the same Tor exit relay. This is by design and the Tor default. Further, "signal newnym" does not interfere with long-lived connections like an IRC connection.

Interested readers can verify the effect of "signal newnym" as follows:

  1. Open [archive] in Tor Browser.
  2. Issue "signal newnym" using nyx.
  3. Reload [archive].
  4. In some cases it will still show the same IP address, probably because the browser did not close the connection to [archive] in the first place.

Now repeat this experiment with a small modification which should result in a new Tor exit IP address:

  1. Open [archive] in Tor Browser.
  2. Issue "signal newnym" using nyx.
  3. Close Tor Browser, then restart it.
  4. Open [archive] again and a new Tor exit relay IP address is (likely) visible.

New Identity is not yet perfect and there are open bugs; this is not a Whonix ™-specific issue. "signal newnym" is not a guaranteed method of unlinking various protocol states (like the browser) so the user absolutely appears to be a different identity. [13] Tor Browser's New Identity feature attempts this, but it is not yet perfect.

In general for greater security, it is better to completely close Tor Browser and restart it. In Qubes-Whonix ™, the safest option is using a Whonix-Workstation ™ DisposableVM and closing it and recreating a new one after critical activities.



Info tor-ctrl has been deprecated because it is not supported upstream. See: tor-ctrl - Tor control port command line tool [archive]. [14]

On Whonix-Gateway ™[edit]

tor-ctrl [15] was formerly bundled in Whonix ™ by default.

To get a new circuit, run.

tor-ctrl -a /var/run/tor/control.authcookie -c "signal newnym"

tor-ctrl -v -a /var/run/tor/control.authcookie -c "signal newnym"

See also.

man tor-ctrl

On Whonix-Workstation ™[edit]

Interactive Tor Control Connection[edit]

Connect to the Tor control socket.

socat - UNIX-CONNECT:/var/run/tor/control

Run the following command. [16]

signal NEWNYM

The output should show.

250 OK

Command Line Tor Control Command[edit]

Run the following command. [16]

cmd="signal NEWNYM" && ( echo "$cmd" && sleep 1 ) | socat - UNIX-CONNECT:/var/run/tor/control

The output should show.

250 OK

New Circuits[edit]

Repeat this command every time a new circuit is desired.

Run tor-ctrl (installed by default) with signal NEWNYM. [16]

bash -x tor-ctrl -p notrequired -c "signal NEWNYM"

If the following output appears at the bottom.

+ TOR_COOKIE=/var/run/tor/control.authcookie
+ getopts :a:c:s:p:P:f:vh Option
+ case $Option in
+ PASSWORD=notrequired
+ getopts :a:c:s:p:P:f:vh Option
+ case $Option in
+ CMD='signal NEWNYM'
+ getopts :a:c:s:p:P:f:vh Option
+ '[' -e '' ']'
+ '[' 'signal NEWNYM' '!=' '' ']'
+ checkprogs
+ programs=telnet
+ '[' notrequired = '' ']'
+ for p in $programs
+ command -v telnet
+ '[' 0 '!=' 0 ']'
+ cmdpipe signal NEWNYM
+ login
+ '[' notrequired = '' ']'
+ sendcmd 'AUTHENTICATE "notrequired"'
+ echo 'AUTHENTICATE "notrequired"'
+ sleep 1
+ telnet 9051
+ myecho
++ cat
+ sendcmd signal NEWNYM
+ echo signal NEWNYM
+ sleep 1
+ sendcmd QUIT
+ echo QUIT
+ sleep 1
+ STR='Trying
Connected to
Escape character is '\''^]'\''.
250 OK
250 OK
250 closing connection'
+ vecho 'Trying
Connected to
Escape character is '\''^]'\''.
250 OK
250 OK
250 closing connection'
+ '[' 0 -ge 1 ']'
+ echo 'Trying
Connected to
Escape character is '\''^]'\''.
250 OK
250 OK
250 closing connection'
++ grep -c '^250 '
+ '[' 3 = 3 ']'
+ exit 0

Then the process succeeded. (exit 1 is a bug in tor-ctrl, because it does not understand the double 250 OK.)


Ambox warning pn.svg.png Vidalia is no longer maintained.

Vidalia is recommended against because development has ceased, leading to it being removed from all Debian variants (stretch, sid etc.) as well as from Tor Browser Bundle v3.5 by The Tor Project. [17] [18] Vidalia had a number of limitations, such as an inability to fully control Tor -- it could not stop Tor which came with the Debian package because it is started as user "debian-tor". It also could not edit /usr/local/etc/torrc.d/50_user.conf [19] and did not understand obfuscated bridges. Since Vidalia has been deprecated and provides a pretty bad and confusing user experience, it is simply better to use nyx. [20]


  1. Since Vidalia is recommended against.
  2. [archive]
  3. Nyx works on a different level -- it is a Tor Controller. Nyx talks to Tor using Tor's ControlPort and is an interface to show what Tor thinks. Neither Tor nor nyx implement anything like virus detection, compromise detection, leak detection and so on. Nyx messages are generally interesting and useful, but there is rarely any cause for concern. For leak testing, see leak tests.
  4. [archive]

  6. [archive]
  7. The issue was closed as 'not a bug' several years ago.
  8. [archive]
  9. [archive]
  10. This works in Whonix-Workstation ™, because the anon-ws-disable-stacked-tor [archive] package has set up listening for connections on localhost and forwards them to Whonix-Gateway ™, where the Control Port Filter Proxy is listening.
  11. Prepending python3 is required due to a bug /usr/bin/tor-prompt still using a python2 instead of a python3 shebang.
  12. [archive]
  13. See tbb-linkability [archive] and tbb-fingerprinting [archive].
  14. [archive]
  15. [archive]
  16. 16.0 16.1 16.2 No login required due to Control Port Filter Proxy filtered access.
  17. [archive]
  18. As noted by Tor developer Roger Dingledine:

    Cammy is right -- we've removed the bridge/relay/exit bundles from the download page too, since Vidalia has been unmaintained for years and pointing people to unmaintained software is dangerous. I'd love to have enough developers to do everything at once, but we don't.

  19. It is unclear whether control commands such as New Identity were correctly processed either.
  20. Unless the reader is interested in Vidalia's nice network map.

Fosshost is sponsors Kicksecure ™ stage server Whonix old logo.png
Fosshost About Advertisements

Search engines: YaCy | Qwant | ecosia | MetaGer | peekier | Whonix ™ Wiki

Follow: 1024px-Telegram 2019 Logo.svg.png Iconfinder Apple Mail 2697658.png Twitter.png Facebook.png Rss.png Reddit.jpg 200px-Mastodon Logotype (Simple).svg.png

Support: Discourse logo.png

Donate: Donate Bank Wire Paypal Bitcoin accepted here Monero accepted here Contriute

Whonix donate bitcoin.png Monero donate Whonix.png United Federation of Planets 1000px.png

Twitter-share-button.png Facebook-share-button.png Telegram-share.png link=mailto:?subject=Tor Controller&body= link= Controller link= Controller link= Controller%20 Controller

LIVE MODE: Host operating system or VM can be booted into Live Mode, using Host Live Mode or VM Live Mode.

https link onion link Priority Support | Investors | Professional Support

Whonix | © ENCRYPTED SUPPORT LP | Heckert gnu.big.png Freedom Software / Osi standard logo 0.png Open Source (Why?)

The personal opinions of moderators or contributors to the Whonix ™ project do not represent the project as a whole.

By using our website, you acknowledge that you have read, understood and agreed to our Privacy Policy, Cookie Policy, Terms of Service, and E-Sign Consent.