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's latest version is 2.1.0, released January 12th, 2019.What does Nyx provide?
Bandwidth used by Tor. You can press 'i' to pick the graphing interval, or 's' to show other usage statistics.
Tor logs a wealth of information about itself. We present it, colorized and deduplicated. Press 'e' to select what events are logged and 'f' to filter to just what you want.
Connection data similar to netstat or lsof, but correlated with Tor relay information to make it much richer. Press 'enter' for more details, 's' to sort, and 'd' to see raw descriptor data.
Editor to change Tor's setting on the fly, with usage information from its manual. Press 'enter' to change Tor settings and 'w' to write your changes to disk.
Provides your torrc with line numbers and syntax highlighting. Comments can be stripped by pressing 's'.
That's just the tip of the iceberg. All pages within Nyx provide help information when you press 'h' and menu in response to 'm'. So go explore!
Nyx is a command-line application for monitoring real time Tor status information. This includes bandwidth usage, logs, connections, configuration, and more.
As a curses interface Nyx is particularly well suited for ssh connections, tty terminals, and command-line aficionados.
For a bit of its history see my 2009 interview by Brenno Winter.
Simple - because the Greek goddess of night is short and memorable. Terminal applications are handiest when they're brief and easy to type. Top, ssh, scp - anything longer is just begging to be aliased down.
Yes, Nyx requires Stem 1.5.4 or later.
Nyx works with Python 2.7 and greater, including the Python 3.x series.
Most download options are maintained by their operating system's community. Nyx's author only provides PyPI, File, and Source.
% gpg --keyserver keyserver.ubuntu.com --recv-keys 0x9ABBEEC6 gpg: requesting key 9ABBEEC6 from hkp server keyserver.ubuntu.com gpg: key 9ABBEEC6: public key "Damian Johnson (www.atagar.com)
" imported gpg: no ultimately trusted keys found gpg: Total number processed: 1 gpg: imported: 1 (RSA: 1)
gpg --verify nyx-2.0.4.tar.gz.asc nyx-2.0.4.tar.gz gpg: Signature made Mon 06 Nov 2017 12:28:13 PM PST using RSA key ID 87F30690 gpg: Good signature from "Damian Johnson (www.atagar.com)
" gpg: aka "Damian Johnson " gpg: WARNING: This key is not certified with a trusted signature! gpg: There is no indication that the signature belongs to the owner. Primary key fingerprint: 6827 8CC5 DD2D 1E85 C4E4 5AD9 0445 B7AB 9ABB EEC6 Subkey fingerprint: 2AE2 24F5 C424 990A E520 6C85 8884 04C1 87F3 0690
Yes, though sadly this space doesn't get much attention.
For years Vidalia was the default interface of Tor until it was replaced by Tor Browser in 2013. Vidalia includes a launcher, settings editor, map, and more. TorK is similar, providing connection information as well but never reached the same level of prominence. Both interfaces are now unmaintained.
Smaller widgets include...
If I missed any then please let me know!
Installing with Debian and Ubuntu might fail with...
% sudo apt-get install nyx Reading package lists... Done Building dependency tree Reading state information... Done E: Unable to locate package nyx
In the meantime if you see the above we suggest installing with 'sudo pip install nyx' instead.
Ran into a problem? Please simply inform us of it on ourbug tracker.
Nyx is under the GPLv3.
No. Potential client and exit connections are scrubbed of sensitive information. Be aware that it's highly discouraged (and likely illegal) for relay operators to view other people's traffic, so please don't.
No. As a passive listener Nyx retrieves everything it needs from your local system. Nothing goes over the network.
Some terminals, such as screen sessions on Gentoo, apparently have a bug where highlighted space characters are not shown. Try running...
Bytes. Most tools measure in bytes so for consistency we do the same. Unfortunately hosting providers advertise in bits to inflate their numbers ("5 Mbit connection"). If graphs show just one eighth of what you expect this is why.
To graph in bits rather than bytes add the following to your nyxrc...
When alternate character support (ACS) is unavailable borders become characters like the picture above. This is a terminal bug.
Unfortunately there doesn't seem to be a way for Nyx to automatically detect this. However, when it happens this can be easily corrected. Simply run reset. To tell Nyx not to use ACS borders simply add the following to your nyxrc...
Nyx can provide you with information about tor's active connections. This information is retrieved from your system's /proc content or tools such as netstat and lsof.
Unfortunately Tor inadvertently breaks the tools Nyx falls back to through a feature called DisableDebuggerAttachment, which makes tor's process memory only readable by root.
This leaves you with three options...
Use Nyx without connection data. Nyx does not require connection information, and aside a sparse connection list you probably won't even notice.
Run Nyx as root. This is not recommended.
Don't fret overly much about this decision. Nothing at play here is important - connection data is unimportant and DisableDebuggerAttachment's security benefit is insignificant. Either decision is fine.
Nyx presents your active connections correlated with tor consensus data. This means that in addition to the IP/port we also provide Tor-specific information such as your connection's relay fingerprint, nickname, contact address, and much more.
However, sometimes this extra information is missing and that's fine. Relays publish information about themselves on an hourly basis in documents called descriptors. Tor downloads only the descriptors it needs to run, so Tor may not have information about all the relays you're connecting to. And that's ok.
However, if you need up-to-date information you can add the following to your torrc...
# download new descriptors even if our cache is still valid FetchDirInfoEarly 1 FetchDirInfoExtraEarly 1 FetchUselessDescriptors 1
The best way of getting involved with any project is to jump right in! In particular look for the 'easy' keyword on our bug tracker for a handy spot to start.
git clone https://git.torproject.org/nyx.git
sudo pip install mock pyflakes pycodestyle
git clone https://git.torproject.org/stem.git cd stem sudo python setup.py install
Got something to send my way? It's easy...
Nyx is under the GPLv3 which is a fine license, but poses a bit of a problem for sharing code with our other projects (which are mostly BSD). To share code without needing to hunt down prior contributors we need Tor to have the copyright for the whole Nyx codebase. Presently the copyright of Nyx is jointly held by its main author (Damian) and the Tor Project.
If you submit a substantial patch I'll ask if you're fine with it being in the public domain. This would mean that there are no legal restrictions for using your contribution, and hence won't pose a problem if we reuse Nyx code in other projects.
You can install our latest release from the Python Package Index (PyPI) with pip...
% sudo pip install nyx
On Mac OS you can easily install with both the pip command above and brew...
% brew install nyx
% sudo apt-get install nyx
Package derived from Debian for Ubuntu. Use sudo pip install nyx if this doesn't work.
% sudo apt-get install nyx
Package by Alex for Arch Linux...
% pacman -S nyx
Port maintained by pascal for OpenBSD.
% pkg_add nyx
Port maintained by Riastradh for NetBSD.
% pkg_add nyx
% pip install nyx-2.0.4.tar.gz
For those who want to live on the bleeding edge or contribute, you can download Nyx's git repository with...
% git clone https://git.torproject.org/nyx.git
Like many terminal applications Nyx can be customized through a configuration file. By default ~/.nyx/nyxrc, though you can specify one with nyx --config /path/to/nyxrc.
Configurations are a simple series of key/value pairs. See Stem for details. For example...
acs_support false color_override blue # make our UI predominately blue logged_events BW, NOTICE, WARN, ERR
|data_directory||~/.nyx||Location data is cached to. To avoid caching anything to disk specify 'data_directory disabled'.|
|password||Tor controller password. If unset you will be prompted for a password when one is required to authenticate.
Use of this is discouraged. To authenticate with tor non-interactively please use cookie authentication instead.
|tor_chroot||Chroot jail tor resides within. Most common on FreeBSD, if tor is running within a jail then use this to specify the path prefix we should use when looking for tor files on disk.|
|show_bits||false||Shows bandwidth measurements in bits if true, and bytes if false.|
|confirm_quit||true||Asks the user to confirm when pressing 'q' to quit if true.|
|color_interface||true||Uses colors in Nyx's interface if true. Monochrome is false.|
|color_override||Replaces most color with this hue. Options available are red, green, blue, cyan, magenta, yellow, and black.|
|unicode_support||true||Render text as unicode if true. Only ASCII is rendered if false.|
|acs_support||true||Uses ACS (alternate character set) for nice borders if true. Borders are replaced with ASCII pipe characters if false.|
|redraw_rate||5||Seconds to await user input before redrawing.|
|connection_rate||5||Seconds between querying connections.|
|resource_rate||5||Seconds between querying process resource usage.|
|port_usage_rate||5||Seconds between querying processes using ports.|
|Comma separated list of events to be initially logged, similar to the --log argument.|
|deduplicate_log||true||Hides duplicate log messages.|
|prepopulate_log||true||Populates with events that occure before we started.|
|logging_filter||Regex filter for log messages that are shown.|
|write_logs_to||Writes logs that occure as we run to this path.|
|max_log_size||1000||Maximum number of log messages.|
|graph_stat||bandwidth||Statistic to be graphed. Options are...
|graph_interval||each second||Graph sampling interval. Options are...
|graph_bound||max_local||Bounding for the graph min and max. Options are...
|graph_height||7||Height of the graph.|
|max_graph_width||300||Maximum number of samplings.|
|Order for tor config options. Options are...
|show_private_options||false||Shows configurations with a '__option' prefix.|
|show_virtual_options||false||Shows unsettable tor configurations.|
|Order for connections. Options are...
|resolve_processes||true||Shows processes for SOCKS and CONTROL connections.|
|show_addresses||true||Shows addresses of connections.|
|show_graph||true||Shows the graph.|
|show_accounting||true||Shows accounting stats if AccountingMax is set.|
|show_log||true||Shows the event log.|
|show_connections||true||Shows connection information.|
|show_config||true||Shows tor's configuration.|
|show_torrc||true||Shows the torrc.|
|show_interpreter||true||Shows the control interpreter.|