aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorThomas "Cakeisalie5" Touhey <thomas@touhey.fr>2019-04-20 21:23:41 +0200
committerThomas "Cakeisalie5" Touhey <thomas@touhey.fr>2019-04-20 21:23:41 +0200
commitb9b1ac627dfc18c89de5a678bdee218718800783 (patch)
tree876ed9aed796bad8e3ed64013d837dfd9bce89fb
parentc12fab47cc1db0f943b951cd91a807669c2d333d (diff)
README -> docs
-rw-r--r--README.rst222
-rw-r--r--docs/Makefile4
-rw-r--r--docs/index.rst2
-rw-r--r--docs/running.rst225
-rwxr-xr-xfingerd/__init__.py2
5 files changed, 232 insertions, 223 deletions
diff --git a/README.rst b/README.rst
index 42665bb..2dd6578 100644
--- a/README.rst
+++ b/README.rst
@@ -10,226 +10,7 @@ to implement this protocol for fun, but didn't want to present the
real information about the users on my server, so I made this to present some
fictional information in order to be able to tell a story through finger.
-The finger server should be available through the TCP port 79, which can only
-be opened by ``root`` on UNIX-like machines. Instead of using this port
-directly, which forces the use of the ``root`` user to manage the service,
-you can redirect the incoming transmissions from an interface on TCP port 79
-to another TCP port which you can open as a user (port number over 1024)
-by appending a rule in ``iptables``:
-
-.. code-block:: sh
-
- iptables -t nat -A OUTPUT -p tcp [-s <source ip>] [-d <destination ip>] \
- --dport 79 -j DNAT --to '<ip:port>'
-
-Where ``<source ip>`` is the source IP address or network that are redirected,
-``<destination ip>`` is the destination IP address or network for which the
-requests are redirected and ``<ip:port>`` is the IP and port
-you want to forward the packets to, e.g. ``127.0.0.1:4000``.
-
-For example, for running the server locally on port 3999 and only accepting
-requests from the same machine (on IPv4 and IPv6):
-
-.. code-block:: sh
-
- iptables -t nat -A OUTPUT -p tcp -s 127.0.0.1 -d 127.0.0.1 \
- --dport 79 -j DNAT --to 127.0.0.1:3999
- ip6tables -t nat -A OUTPUT -p tcp -s ::1 -d ::1 \
- --dport 79 -j DNAT --to '[::1]:3999'
-
-Run the application
--------------------
-
-To run the application, use the following command:
-
-.. code-block:: sh
-
- python3 -m fingerd <command line options>
-
-Configuration
--------------
-
-``fingerd`` stores its configuration in the environment. For commodity,
-a ``.env`` configuration is proposed, install the ``python-dotenv`` module
-and copy the ``.env.template`` file into ``.env`` and edit it following
-its comments.
-
-``BIND``
- This variable is mandatory and contains the endpoints to bind on,
- separated with commas (``,``). Each endpoint can have the following
- format:
-
- ``example.com``
- Bind on all addresses that ``example.com`` resolve as (IPv4 and IPv6),
- port 79.
-
- ``example.com:1234``
- Bind on all addresses that ``example.com`` resolve as (IPv4 and IPv6),
- port 1234.
-
- ``1.2.3.4`` or ``[1.2.3.4]``
- Bind on ``1.2.3.4`` (IPv4), port 79.
-
- ``1.2.3.4:1234`` or ``[1.2.3.4]:1234``
- Bind on ``1.2.3.4`` (IPv4), port 1234.
-
- ``::1:2:3:4`` or ``[::1:2:3:4]``
- Bind on ``::1:2:3:4`` (IPv6) port 79.
-
- ``[::1:2:3:4]:1234``
- Bind on ``::1:2:3:4`` (IPv6) port 1234.
-
- For example, ``localhost`` usually binds on ``127.0.0.1:79`` (IPv4) and
- ``[::1]:79`` (IPv6).
-
-``FINGER_HOST``
- The host as which fingerd identifies itself (domain name), ``LOCALHOST``
- by default.
-
-``FINGER_TYPE``
- The interface type, or where the displayed data comes from. There are
- several interface types:
-
- ``DUMMY``
- There is no data (no users, no sessions).
-
- ``NATIVE``
- The data is gathered from the system.
-
- ``SCENARIO``
- The data is gathered from a scenario (see :ref:`actions` below).
-
- ``LIVE``
- The data is gathered from actions given in an IPC endpoint (see
- :ref:`live`).
-
- By default, the interface type is ``NATIVE``.
-
-If the interface type is ``SCENARIO``, then the following variable is
-required:
-
-``FINGER_SCENARIO``
- The scenario path (see :ref:`actions` for the format).
-
-``FINGER_INCOMING``
- The finger live action source (see :ref:`live`).
-
-.. _actions:
-
-Scenarios
-~~~~~~~~~
-
-Scenarios are TOML documents describing actions, which are points in time
-where something happens. Every action has a time offset, using a TOML
-array section (``[[something]]``), and properties describing what's
-happening. Time offsets are represented the following way:
-
-::
-
- -?(<weeks>w)?(<days>[jd])?(<hours>h)?(<minutes>m)?(<seconds>s)?
-
-Where negative times, starting with a dash (``-``), are the initial situation,
-what is supposed to have happened before the beginning.
-
-For example, ``-1w5d2h`` means “1 week, 5 days and 2 hours before the
-origin” and ``2j`` means “2 days after the origin”. So if we want to make
-an action that takes place 5 seconds after the origin, the first line of the
-action will be the following one:
-
-.. code-block::
-
- [[5s]]
-
-All actions have a type represented by the ``type`` property, and other
-properties depending on the type. Types and related properties are
-described in the sections below.
-
-Flow-related actions
-~~~~~~~~~~~~~~~~~~~~
-
-The following are related to the action flow:
-
-``interrupt``
- The server freezes on the latest situation.
-
-``stop``
- The server stops on the event.
-
-All the actions after the time of any of these will be ignored.
-
-User-related actions
-~~~~~~~~~~~~~~~~~~~~
-
-User-related actions' types can be of the following:
-
-``create``
- A user has been created.
-
-``update``
- A user has been updated.
-
-``delete``
- A user has been deleted.
-
-As all of these actions are about users, they all take an additional
-``login`` argument which is the affected user's name, e.g. ``rinehart``.
-
-The ``create`` and ``update`` event takes some more arguments:
-
-``name``
- The user full name, e.g. “Mark J. Rinehart”.
-
-``shell``
- The selected login shell.
-
-``home``
- The home directory.
-
-``office``
- The user's office name, e.g. “B121 on second floor”.
-
-``plan``
- The plan path.
-
-For an ``update`` action, setting properties to ``false`` will erase their
-previous value without setting a new one.
-
-Session-related actions
-~~~~~~~~~~~~~~~~~~~~~~~
-
-Session-related actions' types can be of the following:
-
-``login``
- A user has logged in and is active.
-
-``logout``
- A user has logged out.
-
-``idle``
- A user is now idle (not typing on the keyboard anymore).
-
-``active``
- A user is now active (typing every now and then).
-
-These actions take an additional argument ``login`` which is the user to
-which the session belongs, and an optional other ``session`` argument to
-identify the session for which the event is in the case of multiple sessions
-for the user.
-
-The ``login`` operation takes the information about the originating shell:
-
-``line``
- The physical line on which the user is connected.
-
-``host``
- The remote host from which the physical line is opened, if any.
-
-.. _live:
-
-Live actions
-~~~~~~~~~~~~
-
-TODO
+Find out more on `the fingerd homepage <https://fingerd.touhey.pro/>`_.
What is left to do
------------------
@@ -239,6 +20,7 @@ For v0.2:
- correct the idle simulation function with a better one.
- correct error-handling in configuration files decoding.
- add tests.
+- add documentation for the programming interface.
For further versions:
diff --git a/docs/Makefile b/docs/Makefile
index 42fc02a..08157af 100644
--- a/docs/Makefile
+++ b/docs/Makefile
@@ -24,8 +24,8 @@ help:
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
# Send the website content (Linux-only).
-send: html
+show: html
find _build/html -type f -exec chmod 644 {} \;
rsync -Prlt --delete _build/html/ "$(WEBROOT)"
-.PHONY: send
+.PHONY: show \ No newline at end of file
diff --git a/docs/index.rst b/docs/index.rst
index 3003c49..789ba2b 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -12,5 +12,7 @@ project homepage at `fingerd.touhey.pro <https://fingerd.touhey.pro/>`_!
:maxdepth: 2
:caption: Contents:
+ running
+
.. _RFC 742: https://tools.ietf.org/html/rfc742
.. _RFC 1288: https://tools.ietf.org/html/rfc1288
diff --git a/docs/running.rst b/docs/running.rst
new file mode 100644
index 0000000..be6cbce
--- /dev/null
+++ b/docs/running.rst
@@ -0,0 +1,225 @@
+Configuring and running fingerd
+===============================
+
+``fingerd`` can be run directly and without configuration (while taking its
+default option values) with the following command:
+
+.. code-block:: sh
+
+ python3 -m fingerd <command line options>
+
+The server will run while giving native information on TCP port 79 on both
+IPv4 and IPv6 (if available). However, you can tweak this behaviour by
+configuring it.
+
+Configuration
+-------------
+
+``fingerd`` stores its configuration in the environment. For commodity,
+a ``.env`` configuration is proposed, install the ``python-dotenv`` module
+and copy the ``.env.template`` file into ``.env`` and edit it following
+its comments.
+
+``BIND``
+ This variable is mandatory and contains the endpoints to bind on,
+ separated with commas (``,``). Each endpoint can have the following
+ format:
+
+ ``example.com``
+ Bind on all addresses that ``example.com`` resolve as (IPv4 and IPv6),
+ port 79.
+
+ ``example.com:1234``
+ Bind on all addresses that ``example.com`` resolve as (IPv4 and IPv6),
+ port 1234.
+
+ ``1.2.3.4`` or ``[1.2.3.4]``
+ Bind on ``1.2.3.4`` (IPv4), port 79.
+
+ ``1.2.3.4:1234`` or ``[1.2.3.4]:1234``
+ Bind on ``1.2.3.4`` (IPv4), port 1234.
+
+ ``::1:2:3:4`` or ``[::1:2:3:4]``
+ Bind on ``::1:2:3:4`` (IPv6) port 79.
+
+ ``[::1:2:3:4]:1234``
+ Bind on ``::1:2:3:4`` (IPv6) port 1234.
+
+ For example, ``localhost`` usually binds on ``127.0.0.1:79`` (IPv4) and
+ ``[::1]:79`` (IPv6).
+
+``FINGER_HOST``
+ The host as which fingerd identifies itself (domain name), ``LOCALHOST``
+ by default.
+
+``FINGER_TYPE``
+ The interface type, or where the displayed data comes from. There are
+ several interface types:
+
+ ``DUMMY``
+ There is no data (no users, no sessions).
+
+ ``NATIVE``
+ The data is gathered from the system.
+
+ ``SCENARIO``
+ The data is gathered from a scenario (see :ref:`actions` below).
+
+ ``LIVE``
+ The data is gathered from actions given in an IPC endpoint (see
+ :ref:`live`).
+
+ By default, the interface type is ``NATIVE``.
+
+If the interface type is ``SCENARIO``, then the following variable is
+required:
+
+``FINGER_SCENARIO``
+ The scenario path (see :ref:`actions` for the format).
+
+``FINGER_INCOMING``
+ The finger live action source (see :ref:`live`).
+
+The finger server should be available through the TCP port 79, which can only
+be opened by ``root`` on UNIX-like machines. Instead of using this port
+directly, which forces the use of the ``root`` user to manage the service,
+you can redirect the incoming transmissions from an interface on TCP port 79
+to another TCP port which you can open as a user (port number over 1024)
+by appending a rule in ``iptables``:
+
+.. code-block:: sh
+
+ iptables -t nat -A OUTPUT -p tcp [-s <source ip>] [-d <destination ip>] \
+ --dport 79 -j DNAT --to '<ip:port>'
+
+Where ``<source ip>`` is the source IP address or network that are redirected,
+``<destination ip>`` is the destination IP address or network for which the
+requests are redirected and ``<ip:port>`` is the IP and port
+you want to forward the packets to, e.g. ``127.0.0.1:4000``.
+
+For example, for running the server locally on port 3999 and only accepting
+requests from the same machine (on IPv4 and IPv6):
+
+.. code-block:: sh
+
+ iptables -t nat -A OUTPUT -p tcp -s 127.0.0.1 -d 127.0.0.1 \
+ --dport 79 -j DNAT --to 127.0.0.1:3999
+ ip6tables -t nat -A OUTPUT -p tcp -s ::1 -d ::1 \
+ --dport 79 -j DNAT --to '[::1]:3999'
+
+.. _actions:
+
+Scenarios
+~~~~~~~~~
+
+Scenarios are TOML documents describing actions, which are points in time
+where something happens. Every action has a time offset, using a TOML
+array section (``[[something]]``), and properties describing what's
+happening. Time offsets are represented the following way:
+
+::
+
+ -?(<weeks>w)?(<days>[jd])?(<hours>h)?(<minutes>m)?(<seconds>s)?
+
+Where negative times, starting with a dash (``-``), are the initial situation,
+what is supposed to have happened before the beginning.
+
+For example, ``-1w5d2h`` means “1 week, 5 days and 2 hours before the
+origin” and ``2j`` means “2 days after the origin”. So if we want to make
+an action that takes place 5 seconds after the origin, the first line of the
+action will be the following one:
+
+.. code-block::
+
+ [[5s]]
+
+All actions have a type represented by the ``type`` property, and other
+properties depending on the type. Types and related properties are
+described in the sections below.
+
+Flow-related actions
+~~~~~~~~~~~~~~~~~~~~
+
+The following are related to the action flow:
+
+``interrupt``
+ The server freezes on the latest situation.
+
+``stop``
+ The server stops on the event.
+
+All the actions after the time of any of these will be ignored.
+
+User-related actions
+~~~~~~~~~~~~~~~~~~~~
+
+User-related actions' types can be of the following:
+
+``create``
+ A user has been created.
+
+``update``
+ A user has been updated.
+
+``delete``
+ A user has been deleted.
+
+As all of these actions are about users, they all take an additional
+``login`` argument which is the affected user's name, e.g. ``rinehart``.
+
+The ``create`` and ``update`` event takes some more arguments:
+
+``name``
+ The user full name, e.g. “Mark J. Rinehart”.
+
+``shell``
+ The selected login shell.
+
+``home``
+ The home directory.
+
+``office``
+ The user's office name, e.g. “B121 on second floor”.
+
+``plan``
+ The plan path.
+
+For an ``update`` action, setting properties to ``false`` will erase their
+previous value without setting a new one.
+
+Session-related actions
+~~~~~~~~~~~~~~~~~~~~~~~
+
+Session-related actions' types can be of the following:
+
+``login``
+ A user has logged in and is active.
+
+``logout``
+ A user has logged out.
+
+``idle``
+ A user is now idle (not typing on the keyboard anymore).
+
+``active``
+ A user is now active (typing every now and then).
+
+These actions take an additional argument ``login`` which is the user to
+which the session belongs, and an optional other ``session`` argument to
+identify the session for which the event is in the case of multiple sessions
+for the user.
+
+The ``login`` operation takes the information about the originating shell:
+
+``line``
+ The physical line on which the user is connected.
+
+``host``
+ The remote host from which the physical line is opened, if any.
+
+.. _live:
+
+Live actions
+~~~~~~~~~~~~
+
+TODO
diff --git a/fingerd/__init__.py b/fingerd/__init__.py
index 74e7288..dc7dd17 100755
--- a/fingerd/__init__.py
+++ b/fingerd/__init__.py
@@ -66,7 +66,7 @@ def _get_server():
if _path.exists('.env'):
print("Warning: a `.env` file was found but `python-dotenv`",
file = _stderr)
- print("didn't exist, consider installing it.",
+ print("isn't installed; consider installing it.",
file = _stderr)
# Load the environment variables.