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.

- 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
  - OnionView - Circuit information
  - 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? Reporting issues is easy...

  1. Go to our bug tracker.
  2. Log in. If you'd rather not make an account you can use these credentials to file an issue anonymously...
     - Username: cypherpunks
     - Password: writecode
  3. Fill in the following fields...
     - Summary: Brief description of your issue.
     - Description: Detailed description of your issue. Please provide steps to reproduce your issue, stacktrace if you got one, and screenshot if applicable.
     - Type: defect
     - Component: Core Tor → Nyx
- 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 featurure 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 trac ticket. Only fields you'll need are...
     - Summary: brief description of your change
     - Description: description of your change and a link to your repository for me to pull from
     - Type: 'defect' if this is a bug fix and 'enhancement' otherwise
     - Component: Core Tor → Nyx
  3. I'll review your change and give suggestions. When we're both happy with it I'll push your change to 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 OSX, Linux, and BSD but not Windows. Find your platform below to get started. For what's changed see our change log.

Python Package Index

Signed releases and instructions for both Python 2.x and 3.x. You can easily install from its tarball (sig), or with pip...

    % sudo easy_install pip
    % sudo pip install nyx

Mac OSX

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

    % brew install nyx

Debian

Package maintained by Dererk for Debian. 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 for Fedora using dnf or yum.

    % 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

Source Repository

For those that want to live on the bleeding edge or contribute, Nyx's git repository can be fetched 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.