commit f240bbf4278251c651701c04c245b51102dcf85f Author: Damian Johnson atagar@torproject.org Date: Mon Nov 7 11:21:45 2016 -0800
Merge readme into FAQ
Adding the questions we had in our readme to the FAQ, rewriting ones that were due with being revised. --- README | 222 --------------------- .../section/screenshots/acs_display_failure.png | Bin 0 -> 161127 bytes .../screenshots/acs_display_failure_full.png | Bin 0 -> 405426 bytes docs/faq.rst | 115 ++++++++++- 4 files changed, 113 insertions(+), 224 deletions(-)
diff --git a/README b/README deleted file mode 100644 index ea3997f..0000000 --- a/README +++ /dev/null @@ -1,222 +0,0 @@ -nyx - Terminal status monitor for Tor relays. -Developed by Damian Johnson (www.atagar.com - atagar@torproject.org) -All code under the GPL v3 (http://www.gnu.org/licenses/gpl.html) -Project page: www.atagar.com/arm - -Description: -Command line application for monitoring Tor, providing real time status -information such as the current configuration, bandwidth usage, message log, -connections, etc. This uses a curses interface much like 'top' does for system -usage. The application is intended for command-line aficionados, ssh -connections, and anyone with a tty terminal for checking their relay's status. -Releases should be stable so if you manage to make it crash (or have a feature -request) then please let me know! - -The project was originally proposed in 2008 by Jacob and Karsten: - http://archives.seul.org/or/dev/Jan-2008/msg00005.html - -An interview by Brenno Winter discussing the project is available at: - https://www.atagar.com/arm/resources/HFM_INT_0001.mp3 - -Requirements: -Python 2.5 -Stem -Tor is running with an available control port. This means either... - ... starting Tor with '--controlport <PORT>' - ... or including 'ControlPort <PORT>' in your torrc - -It's also highly suggested for the control port to require authentication. -This can be done either with a cookie or password: - * Cookie Authentication - Controllers authenticate to Tor by providing the - contents of the control_auth_cookie file. To set this up... - - add "CookieAuthentication 1" to your torrc - - either restart Tor or run "pkill -sighup tor" - - this method of authentication is automatically handled by nyx, so you - can still start nyx as you normally would - - * Password Authentication - Attaching to the control port requires a - password. To set this up... - - run "tor --hash-password <your password>" - - add "HashedControlPassword <hashed password>" to your torrc - - either restart Tor or run "pkill -sighup tor" - - when starting up nyx will prompt you for this password - -For full functionality this also needs: -- To be ran with the same user as tor to avoid permission issues with - connection resolution and reading the torrc. - -- Common *nix commands including: - * ps - * a method of connection resolution (any of the following): - * sockstat - * netstat - * ss - * lsof - * procstat - * tail - * pwdx - * ulimit - * pgrep or pidof - * host (if dns lookups are enabled) - -This is started via 'nyx' (use the '--help' argument for usage). - -------------------------------------------------------------------------------- - -FAQ: -> Why is it called 'nyx'? - -Simple - because it makes the command short and memorable. Terminal -applications need to be easy to type (like 'top', 'ssh', etc), and anything -longer is just begging command-line aficionados to alias it down. - -> If you're listing connections then what about exit nodes? Won't this include -people's traffic? - -No. Potential client and exit connections are specifically scrubbed of -identifying information. Be aware that it's highly discouraged for relay -operators to fetch this data, so please don't. - -> Is it harmful to share the information provided by nyx? - -Not really, but it's discouraged. The original plan for nyx included a special -emphasis that it wouldn't log any data. The reason is that if a large number of -relay operators published the details of their connections then correlation -attacks could break Tor user's anonymity. Just show some moderation in what you -share and it should be fine. - -> Is there any chance that nyx will leak data? - -No. Nyx is a completely passive listener, fetching all information from either -Tor or the local system. - -> When nyx starts it gives "Unable to resolve tor pid, abandoning connection -listing"... why? - -If you're running multiple instances of Tor then nyx needs to figure out which -pid belongs to the open control port. If it's running as a different user (such -as being in a chroot jail) then it's probably failing due to permission issues. -Nyx still runs, just no connection listing or ps stats. - -> The bandwidth graph isn't showing up - -Some terminals, most notably screen sessions on Gentoo, appear to have a bug -where highlighted spaces aren't rendered. A reported workaround is to set: - TERM="rxvt-unicode" - -> There's borders like 'mwqqqqqqqqj' - -If you're getting something that looks like... -http://www.atagar.com/arm/images/acs_display_failure.png - -then you're encountering a bug between ncurses and your terminal where -alternate character support (ACS) is unavailable. For more information see... -http://invisible-island.net/ncurses/ncurses.faq.html#no_line_drawing - -Unfortunately there doesn't seem to be a way for nyx to automatically detect -and correct this. To work around some of the issues set this in your nyxrc... -features.acsSupport false - -> When I press enter in the connection panel to get details some of the -information is either missing or outdated. Why is this? - -There are two sources of information about Tor relays: their consensus and -descriptor entries. - -The consensus entry is provided on an hourly basis by the Tor directory -authorities (special relays that keep track of all the relays in the network). -The consensus has information like the nickname, flags, and in newer Tor -versions a summarized exit policy. - -The descriptor entry, however, is published by the relays themselves and has -information like their platform, contact information, family, public keys, -exit policy, etc. These are much larger than the consensus entries and don't -change unless the relay changes their configuration. - -Everyone in the Tor network (both relays and users) need the consensus entries -to operate. However, only users (not relays) need the descriptor entries. - -Tor will fetch both the consensus and descriptors for all of the currently -active relays when it first starts. But to save bandwidth only the consensus -entries are updated after this unless... -a. 'FetchUselessDescriptors 1' is set in your torrc -b. the directory service is provided ('DirPort' defined) -c. you use Tor as a client - -This means that some of the information on the connection page (like the -platform and contact information) might be missing or stale due to missing -descriptors. This isn't important to most users, but if you need this -information then this is simple to fix with the above. - -------------------------------------------------------------------------------- - -Layout: - -./ - nyx - startup script - install - installation script - - nyx.1 - man page - nyxrc.sample - example nyx configuration file with defaults - ChangeLog - revision history - LICENSE - copy of the gpl v3 - README - um... guess you figured this one out - setup.py - distutils installation script for nyx - - src/ - __init__.py - starter.py - parses and validates commandline parameters - prereq.py - checks python version and for required packages - version.py - version and last modified information - test.py - method for starting tests and demos - settings.cfg - attributes loaded for parsing tor related data - uninstall - removal script - - cli/ - graphing/ - __init__.py - graphPanel.py - (page 1) presents graphs for data instances - bandwidthStats.py - tracks tor bandwidth usage - psStats.py - tracks system information (such as cpu/memory usage) - connStats.py - tracks number of tor connections - - connections/ - __init__.py - connPanel.py - (page 2) lists the active tor connections - circEntry.py - circuit entries in the connection panel - connEntry.py - individual connections to or from the system - countPopup.py - displays client locale or exit port counts - descriptorPopup.py - displays raw descriptor and consensus entries - entries.py - common parent for connPanel display entries - - menu/ - __init__.py - menu.py - provides an interactive menu - item.py - individual items within the menu - actions.py - handlers for menu selections - - __init__.py - controller.py - main display loop, handling input and layout - headerPanel.py - top of all pages, providing general information - popups.py - toolkit providing display popups - - logPanel.py - (page 1) displays tor, nyx, and stem events - configPanel.py - (page 3) editor panel for the tor configuration - torrcPanel.py - (page 4) displays torrc and validation - - util/ - __init__.py - conf.py - loading and persistence for user configuration - connections.py - service providing periodic connection lookups - enum.py - enumerations for ordered collections - hostnames.py - service providing nonblocking reverse dns lookups - log.py - aggregator for application events - panel.py - wrapper for safely working with curses subwindows - procTools.py - queries process & system information from /proc contents - procName.py - renames our process to a friendlier name - sysTools.py - helper for system calls, providing client side caching - textInput.py - expands the capabilities of text input fields - torConfig.py - functions for working with the torrc and config options - torTools.py - Stem wrapper, providing caching and derived information - uiTools.py - helper functions for presenting the user interface - diff --git a/docs/_static/section/screenshots/acs_display_failure.png b/docs/_static/section/screenshots/acs_display_failure.png new file mode 100644 index 0000000..cd44aa8 Binary files /dev/null and b/docs/_static/section/screenshots/acs_display_failure.png differ diff --git a/docs/_static/section/screenshots/acs_display_failure_full.png b/docs/_static/section/screenshots/acs_display_failure_full.png new file mode 100644 index 0000000..48aff76 Binary files /dev/null and b/docs/_static/section/screenshots/acs_display_failure_full.png differ diff --git a/docs/faq.rst b/docs/faq.rst index d601fdf..9bf2dd5 100644 --- a/docs/faq.rst +++ b/docs/faq.rst @@ -4,11 +4,21 @@ Frequently Asked Questions * **General Information**
* :ref:`what_is_nyx` + * :ref:`why_is_it_called_nyx` * :ref:`does_nyx_have_any_dependencies` * :ref:`what_python_versions_is_nyx_compatible_with` * :ref:`are_there_any_other_tor_uis` * :ref:`what_license_is_nyx_under`
+* **Usage** + + * :ref:`will_exits_include_user_traffic` + * :ref:`is_it_harmful_to_share_data` + * :ref:`can_nyx_leak_data` + * :ref:`why_dont_i_see_the_bandwith_graph` + * :ref:`why_are_borders_broken` + * :ref:`why_are_relay_details_missing` + * **Development**
* :ref:`how_do_i_get_started` @@ -34,6 +44,18 @@ usage, logs, connections, configuration, `and more <screenshots.html>`_. As a curses interface Nyx is particularly well suited for ssh connections, tty terminals, and command-line aficionados.
+.. _why_is_it_called_nyx: + +Why is it called Nyx? +--------------------- + +Simple - because it's short and memorable. Terminal applications are handiest +when they're easy to remember and type, such as *top*, *ssh*, etc. Anything +longer is just asking to be aliased down. + +Besides, Nyx is the `Greek goddess of night +https://en.wikipedia.org/wiki/Nyx`_. + .. _does_nyx_have_any_dependencies:
Does Nyx have any dependencies? @@ -50,7 +72,7 @@ Nyx works with **Python 2.6 and greater**, including the Python 3.x series.
.. _are_there_any_other_tor_uis:
-Are there any other user interfaces for tor? +Are there any other user interfaces for Tor? --------------------------------------------
.. image:: /_static/section/screenshots/vidalia.png @@ -66,7 +88,7 @@ launcher, settings editor, map, and more. `TorK information as well but never reached the same level of prominence. Both interfaces are now unmaintained.
-Smaller widgits include... +Smaller widgets include...
* `Syboa https://gitorious.org/syboa/syboa`_ - General interface * `OnionLauncher https://github.com/neelchauhan/OnionLauncher`_ - Tor launcher @@ -86,6 +108,95 @@ Nyx is under the `GPLv3 https://www.gnu.org/licenses/gpl`_.
.. _where_can_i_get_help:
+Usage +===== + +.. _will_exits_include_user_traffic: + +When running an exit will I see people's traffic? +------------------------------------------------- + +**No**. Potential client and exit connections are scrubbed of sensitive +information. Be aware that it's highly discouraged (and possibly illegal) for +relay operators to view this data, so please don't. + +.. _is_it_harmful_to_share_data: + +Is it harmful to share the information provided by Nyx? +------------------------------------------------------- + +**Not really**, but show some moderation. Screenshots of Nyx are unlikely to do +any harm but try to avoid exposing data en mass. + +.. _can_nyx_leak_data: + +Is there any chance that nyx will leak data? +-------------------------------------------- + +**No**. Nyx is a completely passive listener, fetching all information from +either Tor or the local system. + +.. _why_dont_i_see_the_bandwith_graph: + +Why don't I see the bandwidth graph? +------------------------------------ + +On some terminals such as Gentoo screen sessions appear to have a bug where +highlighted spaces aren't shown. Try running... + +:: + + export TERM="rxvt-unicode" + +.. _why_are_borders_broken: + +Why are there borders like 'mwqqqqqqqqj'? +----------------------------------------- + + +If you're getting something that looks like... + +.. image:: /_static/section/screenshots/acs_display_failure.png + :target: _static/section/screenshots/acs_display_failure_full.png + +... you are encountering a terminal bug where alternate character support (ACS) +`is unavailable +http://invisible-island.net/ncurses/ncurses.faq.html#no_line_drawing`_. + +Unfortunately there doesn't seem to be a way for Nyx to automatically detect +or correct this. To work around this you can set the following in your nyxrc +to not use ACS borders... + +:: + + features.acsSupport false + +.. _why_are_relay_details_missing: + +Why are relay details for connections missing? +---------------------------------------------- + +Relays publish information about themselves in documents called *descriptors*. +These documents are downloaded by Tor. New documents available on an hourly +basis but Tor will only download them if it needs them, so the descriptors you +have may be older. + +Nyx's connections page use these descriptors to enrich connection information +with data about the relay you're connected with. If Tor doesn't have this +information the data may be stale or missing. + +**This is fine.** Descriptor information we use changes infrequently so even if +they're a few hours old it won't matter. However, if you really 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 ===========