Refactor of naming + docs

riotkit-org · Oct 4, 2019 · c9d6a97 · c9d6a97
1 parent f050a0a
commit c9d6a97
Show file tree

Hide file tree

Showing 6 changed files with 75 additions and 8 deletions.
diff --git a/README.md b/README.md
@@ -181,6 +181,12 @@ ssh-keygen -t ed25519 -b 4096
 
 See here: [docs/pages](./docs/pages)
 
+### Configuration reference
+
+For list of all possible options to use in configuration file please check example configuration file.
+
+Here: [example/reference.py](./example/reference.py)
+
 ## Developing
 
 - The docker container is built on quay.io and hub.docker com

diff --git a/README.md.j2 b/README.md.j2
@@ -175,6 +175,12 @@ ssh-keygen -t ed25519 -b 4096
 
 See here: [docs/pages](./docs/pages)
 
+### Configuration reference
+
+For list of all possible options to use in configuration file please check example configuration file.
+
+Here: [example/reference.py](./example/reference.py)
+
 ## Developing
 
 - The docker container is built on quay.io and hub.docker com

diff --git a/example/reference.py b/example/reference.py
@@ -0,0 +1,55 @@
+#
+# CONFIGURATION REFERENCE
+# -----------------------
+#
+#  This file should always contain all possible configuration options for documentation
+#  It does not serve to run. The configuration should show possible options, not a well configured setup to run.
+#
+
+
+# ======================================================
+#  Basic SSH connection details, common for all tunnels
+# ======================================================
+REMOTE_USER = 'proxyuser'
+REMOTE_HOST = 'remote-host.org'
+REMOTE_PORT = 22
+REMOTE_KEY = '~/.ssh/id_rsa'
+SSH_OPTS = ''
+
+# ==========================================================================
+#  Defined SSH tunnels that will be forwarded via SSH host specified above
+# ==========================================================================
+FORWARD = [
+    {
+        'local': {
+            'gateway': True,      # If you want to bind to a gateway interface (to publish tunnel to the internet)
+            'host': None,         # In local network an interface IP address or host you would like to bind to
+            'port': 8010          # Port to bind to
+        },
+        'remote': {
+            'gateway': False,     # Bind to a gateway interface (ssh host visible from internet)
+            'host': '127.0.0.1',  # IP address of a service reachable on the remote host
+            'port': 80            # Port reachable on the remote host
+        },
+        'validate': {
+            'method': 'local_port_ping',              # Opts: local_port_ping, remote_port_ping,
+                                                      #        you can place there a callback
+            'interval': 60,                           # Checks tunnel health and status each X seconds
+            'wait_time_before_restart': 60,           # After failure wait this time before doing restart,
+                                                      # maybe the tunnel will be back without doing anything
+            'kill_existing_tunnel_on_failure': True,  # Exit existing tunnel if it is not working,
+            'notify_url': 'http://some-slack-webhook-url'  # Slack/Mattermost integration
+        },
+        'mode': 'local',       # local - forward remote resource to localhost, remote - reverse, to remote
+        'retries': 15,                              # number of retries
+        'wait_time_after_all_retries_failed': 600,  # time to wait, when all retries exhausted
+
+        'use_autossh': False,  # use autossh? (not recommended), may be deprecated and removed in future releases
+
+        'health_check_connect_timeout': 60,   # timeout for the health check
+        'warm_up_time': 5,                    # wait this time before saying that the tunnel was started successfully
+
+        'time_before_restart_at_initialization': 10,  # wait this time before restarting, when the process
+                                                      # does not start from the beginning
+    }
+]
diff --git a/tunman/tunman/factory.py b/tunman/tunman/factory.py
@@ -93,7 +93,7 @@ def _parse_forwarding(raw, configuration: HostTunnelDefinitions) -> List[Forward
                 use_autossh=raw_definition.get('use_autossh', False),
                 health_check_connect_timeout=raw_definition.get('health_check_connect_timeout', 60),
                 warm_up_time=raw_definition.get('warm_up_time', 5),
-                return_to_health_chance_time=raw_definition.get('return_to_health_chance_time', 10),
+                time_before_restart_at_initialization=raw_definition.get('time_before_restart_at_initialization', 10),
                 wait_time_after_all_retries_failed=raw_definition.get('wait_time_after_all_retries_failed', 600)
             ))
 

diff --git a/tunman/tunman/manager.py b/tunman/tunman/manager.py
@@ -138,7 +138,7 @@ def spawn_ssh_process(self, forwarding: Forwarding,
             Logger.error('Cannot spawn %s, stdout=%s, stderr=%s' % (cmd, stdout, stderr))
 
             if not self._recover_from_error(stdout + stderr, configuration):
-                self._carefully_sleep(forwarding.return_to_health_chance_time)
+                self._carefully_sleep(forwarding.time_before_restart_at_initialization)
 
             return SIGNAL_RESTART
 
@@ -252,7 +252,8 @@ def close_all_tunnels(self):
 
             self._kill_proc(proc)
 
-    def _kill_proc(self, proc):
+    @staticmethod
+    def _kill_proc(proc):
         try:
             proc.wait(timeout=1)
         except subprocess.TimeoutExpired:
@@ -293,4 +294,3 @@ def _clean_up(self):
                     self._procs.remove(proc)
                 except ValueError:
                     continue
-
diff --git a/tunman/tunman/model.py b/tunman/tunman/model.py
@@ -40,7 +40,7 @@ class Forwarding(object):
     use_autossh: bool
     health_check_connect_timeout: int
     warm_up_time: int
-    return_to_health_chance_time: int
+    time_before_restart_at_initialization: int
     wait_time_after_all_retries_failed: int
 
     # dynamic state
@@ -56,7 +56,7 @@ def __init__(self, local: LocalPortDefinition,
                  use_autossh: bool,
                  health_check_connect_timeout: int,
                  warm_up_time: int,
-                 return_to_health_chance_time: int,
+                 time_before_restart_at_initialization: int,
                  wait_time_after_all_retries_failed: int):
         self.local = local
         self.remote = remote
@@ -67,7 +67,7 @@ def __init__(self, local: LocalPortDefinition,
         self.use_autossh = use_autossh
         self.health_check_connect_timeout = health_check_connect_timeout
         self.warm_up_time = warm_up_time
-        self.return_to_health_chance_time = return_to_health_chance_time
+        self.time_before_restart_at_initialization = time_before_restart_at_initialization
         self.wait_time_after_all_retries_failed = wait_time_after_all_retries_failed
 
         # dynamic
@@ -150,7 +150,7 @@ def create_ssh_arguments(self, with_forwarding: bool = True) -> str:
         )
 
     def _create_ssh_connection_string(self, with_key: bool = True, with_custom_opts: bool = True,
-                                     append: str = '') -> str:
+                                      append: str = '') -> str:
         return self.configuration.create_ssh_connection_string(
             with_key=with_key,
             with_custom_opts=with_custom_opts,