Nyx

Nyx
Changelog
Configuration
Bug Tracker
Contact
What Is It?
FAQ
Configuration
Contact
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
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!
Install Nyx.
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
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 our
bug 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...
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.
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...
Clone our
git
repository...
git clone https://git.torproject.org/nyx.git
Install our test dependencies
sudo pip install mock pyflakes pycodestyle
Install the development version of
Stem
...
git clone https://git.torproject.org/stem.git
cd stem
sudo python setup.py install
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...
Make a publicly accessible repository for me to pull from. If you don't already have one
GitHub
is great for this.
File a ticket
or pull request.
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.
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
Seconds to await user input before redrawing.
connection_rate
Seconds between querying connections.
resource_rate
Seconds between querying process resource usage.
port_usage_rate
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
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