[Author Prev][Author Next][Thread Prev][Thread Next][Author Index][Thread Index]

[tor-commits] [nyx/master] Merge readme into FAQ



commit f240bbf4278251c651701c04c245b51102dcf85f
Author: Damian Johnson <atagar@xxxxxxxxxxxxxx>
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@xxxxxxxxxxxxxx)
-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
 ===========
 

_______________________________________________
tor-commits mailing list
tor-commits@xxxxxxxxxxxxxxxxxxxx
https://lists.torproject.org/cgi-bin/mailman/listinfo/tor-commits