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 1.4.5, released April 28th, 2012. Prior to our upcoming release this application went under the name of 'arm'. Sorry for the confusion!

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.
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!
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 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 do I get started?
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.

Debian

Package maintained by Dererk for Debian.

% sudo apt-get install tor-arm

Ubuntu

Package derived from Debian for Ubuntu.

% sudo apt-get install tor-arm

Fedora

Packages maintained by Juan for Fedora.

% sudo yum install tor-arm

Gentoo

Package maintained by Jesse for Gentoo.

% sudo emerge arm

Slackware

Package maintained by pyllyukko for Slackware.

FreeBSD

Port maintained by Carlo for FreeBSD.

% pkg install security/arm

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'.
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.

Compenent Visability

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.