[tor-commits] [nyx/master] Merge readme into FAQ
atagar at torproject.org
atagar at torproject.org
Mon Nov 7 19:23:09 UTC 2016
commit f240bbf4278251c651701c04c245b51102dcf85f
Author: Damian Johnson <atagar at 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 at 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
===========
More information about the tor-commits
mailing list