Nyx

Welcome to Nyx

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 Graph

Bandwidth used by Tor. You can press 'i' to pick the graphing interval, or 's' to show other usage statistics.

«Event Log

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.

«Connections

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.

«Configuration Editor

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.

«Torrc

Provides your torrc with line numbers and syntax highlighting. Comments can be stripped by pressing 's'.

«Interpreter

Integration with Stem's interpreter, providing raw controller access, irc-style commands like /help, tab completion, history scrollback, and a python prompt.

«... and more!

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!

Fact & Question

What is Nyx?

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.
How do I get started?
Getting started with Nyx is easy!
1. Install Nyx.
2. Open a Tor ControlPort for Nyx to connect with.
  
  Tor Browser provides this out of the box. Otherwise, add the following lines to your torrc and restart tor...
```
ControlPort 9051
CookieAuthentication 1
```
3. Run "nyx" on your commandline. That's it!
Why is it called Nyx?

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.
Does Nyx have any dependencies?

Yes, Nyx requires Stem 1.5.4 or later.
What Python versions is Nyx compatible with?

Nyx works with Python 2.7 and greater, including the Python 3.x series.

How do I validate the PGP signature?

Most download options are maintained by their operating system's community. Nyx's author only provides PyPI, File, and Source.

Releases are PGP signed and can be validated with the author's key...

Install GPG if you don't already have it.
Download Nyx's latest release and signature.

Get the key of Nyx's author...

% 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)

Validate the downloaded file with the signature...

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

Are there any other user interfaces for Tor?
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...
- Syboa - General interface
- OnionLauncher - Tor launcher
- TorNova - Tor launcher
- OnionCircuits - Circuit information
- or-applet - Circuit information
If I missed any then please let me know!
Why can't I install with apt-get?
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
```
If so, Nyx is not yet available in your distribution's repositories. Nyx is present in Debian Sid and Ubuntu 2.0.4 (Bionic), but it will take time before it's available elsewhere.

In the meantime if you see the above we suggest installing with 'sudo pip install nyx' instead.
How can I report a bug?

Ran into a problem? Please simply inform us of it on ourbug tracker.
What license is Nyx under?

Nyx is under the GPLv3.

Usage

Will I see other people's traffic?

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.
Is it harmful to share information I see?

Not really, but show some moderation. Screenshots of Nyx are unlikely to do any harm but try to avoid exposing data en mass.
Can running Nyx leak data?

No. As a passive listener Nyx retrieves everything it needs from your local system. Nothing goes over the network.
Why can't I see the bandwidth graph?
Some terminals, such as screen sessions on Gentoo, apparently have a bug where highlighted space characters are not shown. Try running...
```
export TERM="rxvt-unicode"
```
Is bandwidth graphed in bits or bytes?
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...
```
show_bits true
```
Why are there borders like 'mwqqqqqqqqj'?
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...
```
acs_support false
```
Why can't I see Tor's connections?
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...
1. Use Nyx without connection data. Nyx does not require connection information, and aside a sparse connection list you probably won't even notice.
2. Run Nyx as root. This is not recommended.
3. Turn off DisableDebuggerAttachment by adding the following to your torrc and restarting tor...
```
DisableDebuggerAttachment 0
```
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.
Why are connections missing relay details?
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
```

Development

How can I get involved?
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.

Got questions? I'm atagar on oftc and available via email. To get started...
1. Clone our git repository...
```
git clone https://git.torproject.org/nyx.git
```
2. Install our test dependencies
```
sudo pip install mock pyflakes pycodestyle
```
3. Install the development version of Stem...
```
git clone https://git.torproject.org/stem.git
cd stem
sudo python setup.py install
```
4. Find a bug or feature that sounds fun and dig in!
How do I run the tests?
Nyx has unit tests that exercise our curses functionality. When you run the tests you'll probably notice your console flicker as these tests are exercised. This is normal. Testing also runs pyflakes and pycodestyle in the background.

Running our tests is simple...
```
% run_tests.py
```
How do I file a pull request?
Got something to send my way? It's easy...
1. Make a publicly accessible repository for me to pull from. If you don't already have one GitHub is great for this.
2. File a ticket or pull request.
3. I'll review your change and give suggestions. When we're both happy with it I'll push your change into the official repository.
What is the copyright for patches?

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.

Download

Nyx is available Mac OS, Linux, and BSD but not Windows. Find your platform below to get started. For what's changed see our change log.

Python Package Index

You can install our latest release from the Python Package Index (PyPI) with pip...

% sudo pip install nyx

Mac OS

On Mac OS you can easily install with both the pip command above and brew...

% brew install nyx

Debian

Package maintained by Dererk. Use sudo pip install nyx if this doesn't work.

% sudo apt-get install nyx

Ubuntu

Package derived from Debian for Ubuntu. Use sudo pip install nyx if this doesn't work.

% sudo apt-get install nyx

Fedora

Package maintained by Juan.

% sudo dnf install nyx

Gentoo

Package by Anthony Basile for Gentoo.

% sudo emerge nyx

Arch Linux

Package by Alex for Arch Linux...

% pacman -S nyx

Slackware

Package maintained by Markus for Slackware.

FreeBSD

Port maintained by Carlo for FreeBSD.

% pkg install security/nyx

OpenBSD

Port maintained by pascal for OpenBSD.

% pkg_add nyx

NetBSD

Port maintained by Riastradh for NetBSD.

% pkg_add nyx

File

File and signature upon which the above packages are based (instructions). You can directly install from this with...

% pip install nyx-2.0.4.tar.gz

Source Repository

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

Configuration

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

General Options

Option	Default	Description
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.

Update Rates

Option	Default	Description
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.

Logging

Option	Default	Description
logged_events	NOTICE, WARN, ERR, NYX_NOTICE, NYX_WARNING, NYX_ERROR	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.

Graphing

Option	Default	Description
graph_stat	bandwidth	Statistic to be graphed. Options are... none - hide the graph bandwidth - downloaded/uploaded connections - inbound/outbound connections resources - cpu/memory usage
graph_interval	each second	Graph sampling interval. Options are... each second 5 seconds 30 seconds minutely 15 minute 30 minute hourly daily
graph_bound	max_local	Bounding for the graph min and max. Options are... global_max - global maximum local_max - local maximum tight - local maximum/minimum
graph_height	7	Height of the graph.
max_graph_width	300	Maximum number of samplings.

Tor Configuration

Option	Default	Description
config_order	MAN_PAGE_ENTRY, NAME, IS_SET	Order for tor config options. Options are... NAME VALUE VALUE_TYPE CATEGORY USAGE SUMMARY DESCRIPTION MAN_PAGE_ENTRY IS_SET
show_private_options	false	Shows configurations with a '__option' prefix.
show_virtual_options	false	Shows unsettable tor configurations.

Connections

Option	Default	Description
connection_order	CATEGORY, IP_ADDRESS, UPTIME	Order for connections. Options are... CATEGORY UPTIME IP_ADDRESS PORT FINGERPRINT NICKNAME COUNTRY
resolve_processes	true	Shows processes for SOCKS and CONTROL connections.
show_addresses	true	Shows addresses of connections.

Component Visibility

Option	Default	Description
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.

Contact

	Relay tips? System administration question? tor-relays@ is a list of relay operators for relay operators. You can also contact Nyx's author.
	Want real-time help? Give OFTC's #tor channel a try.
	Running into a bug? To report technical problems drop us a line on our bug tracker.