Add Endlessh-go (#228)

* add templates files

* add documentation

* upgrade endlessh documentation

* Fix some typos, improve indentation

---------

Co-authored-by: sudo-Tiz <mathis.worksome@simplelogin.fr>
Co-authored-by: Slavi Pantaleev <slavi@devture.com>

docs/services/endlessh.md

@@ -0,0 +1,111 @@
+# Endlessh
+
+[Endlessh-go](https://github.com/shizunge/endlessh-go) is a Golang implementation of [endlessh](https://github.com/skeeto/endlessh), an [SSH tarpit](https://nullprogram.com/blog/2019/03/22). Installing it is powered by the [mother-of-all-self-hosting/ansible-role-endlessh](https://github.com/mother-of-all-self-hosting/ansible-role-endlessh) Ansible role.
+
+## Dependencies
+
+This service requires the following other services:
+
+- (optionally) [Traefik](traefik.md) - a reverse-proxy server for exposing endlessh publicly
+- (optionally) [Prometheus](./prometheus.md) - a database for storing metrics
+- (optionally) [Grafana](./grafana.md) - a web UI that can query the prometheus datasource (connection) and display the logs
+
+## Prerequisites
+
+An SSH tarpit server needs a port to mimic the SSH server. Port 22 is therefore a good choice.
+If you already have your SSH server on this port, you'll have to relocate it.
+I recommend using a random port for the ssh server (eg: 14567) and port 22 for the tarpit.
+
+## Installing
+
+To configure and install endlessh on your own server(s), you should use a playbook like [Mother of all self-hosting](https://github.com/mother-of-all-self-hosting/mash-playbook) or write your own.
+
+## Configuration
+
+To enable this service, add the following configuration to your `vars.yml` file and re-run the [installation](../installing.md) process:
+
+```yaml
+########################################################################
+#                                                                      #
+# endlessh                                                             #
+#                                                                      #
+########################################################################
+
+endlessh_enabled: true
+
+########################################################################
+#                                                                      #
+# /endlessh                                                            #
+#                                                                      #
+########################################################################
+```
+
+By default, endlessh will try to bind to port 22 on all network interfaces.
+You could change this behavior by setting `endlessh_container_host_bind_port`:
+
+```yaml
+endlessh_container_host_bind_port: 22
+```
+
+See the full list of options in the [default/main.yml](default/main.yml) file
+
+## Integrating with Prometheus
+
+Endlessh can natively expose metrics to [Prometheus](./prometheus.md).
+
+### Prerequesites
+
+The bare minimium is to ensure Prometheus can reach endlessh.
+
+- If Endlessh is on a different host than Prometheus, refer to section [Expose metrics publicly](endlessh.md#)
+- If Endlessh is on the same host than prometheus, refer to section [Ensure Prometheus is on the same container network as endlessh.](endlessh.md#)
+
+### Ensure Prometheus is on the same container network as endlessh.
+
+If endlessh and prometheus do not share a network (like traefik), you will have to
+
+- Either connect Prometheus container network to Endlessh by editing `prometheus_container_additional_networks_auto`
+- Either connect Endlessh container network to Prometheus by editing `endlessh_container_additional_networks_custom`
+
+Exemple:
+
+```yaml
+prometheus_container_additional_networks:
+  - "{{ endlessh_container_network }}"
+```
+
+### Set container extra flag:
+
+The bare minimum is to set container extra flag `-enable_prometheus`
+
+```yaml
+endlessh_container_extra_arguments_custom:
+  - "-enable_prometheus"
+```
+
+Default endlessh port for metrics is `2112`. It can be changed via container extra flag `-prometheus_port=8085`.
+
+Default endlessh listening for metrics adress is `0.0.0.0.` (so endlessh will listing on all adresses). This parrameter can be changed via container extra flag `-prometheus_host=10.10.10.10`.
+
+Default endlessh entrypoint for metrics is `/metrics`. It can be changed via container extra flag `-prometheus_entry=/endlessh`.
+
+For more container extra flag, refer to the documentation of [endlessh-go](https://github.com/shizunge/endlessh-go).
+
+### Exposing metrics publicly
+
+Unless you're scraping the endlessh metrics from a local [Prometheus](prometheus.md) instance, as described in [Integrating with Prometheus](endlessh.md#), you will probably wish to expose the metrics publicly so that a remote Prometheus instance can fetch them. When exposing publicly, it's natural to set up [HTTP Basic Authentication](https://developer.mozilla.org/en-US/docs/Web/HTTP/Authentication) **or anyone would be able to read your metrics**.
+
+```yaml
+# To expose the metrics publicly, enable and configure the lines below:
+endlessh_hostname: mash.example.com
+endlessh_path_prefix: /metrics/mash-endlessh
+
+# To protect the metrics with HTTP Basic Auth, enable and configure the lines below.
+# See: https://doc.traefik.io/traefik/middlewares/http/basicauth/#users
+endlessh_container_labels_metrics_middleware_basic_auth_enabled: true
+endlessh_container_labels_metrics_middleware_basic_auth_users: ""
+```
+
+## Usage
+
+After [installing](../installing.md), refer to the documentation of [endlessh-go](https://github.com/shizunge/endlessh-go).

docs/supported-services.md

@@ -21,6 +21,7 @@
 | [Docker Registry Proxy](https://gitlab.com/etke.cc/docker-registry-proxy/) | Pass-through docker registry (distribution) proxy with metadata caching, docker-compatible errors, prometheus metrics, etc. | [Link](services/docker-registry-proxy.md) |
 | [Docker Registry Purger](https://github.com/devture/docker-registry-purger) | A small tool used for purging a private Docker Registry's old tags | [Link](services/docker-registry-purger.md) |
 | [Echo IP](https://github.com/mpolden/echoip) | A simple service for looking up your IP address | [Link](services/echoip.md) |
+| [Endlessh-go](https://github.com/shizunge/endlessh-go) | A golang implementation of endlessh, a ssh trapit | [Link](services/endlessh.md) |
 | [etcd](https://etcd.io/) | A distributed, reliable key-value store for the most critical data of a distributed system | [Link](services/etcd.md) |
 | [exim-relay](https://github.com/devture/exim-relay) | A lightweight [Exim](https://www.exim.org/) SMTP mail relay server | [Link](services/exim-relay.md) |
 | [Focalboard](https://www.focalboard.com/) | An open source, self-hosted alternative to [Trello](https://trello.com/), [Notion](https://www.notion.so/), and [Asana](https://asana.com/). | [Link](services/focalboard.md) |

templates/group_vars_mash_servers

@@ -275,6 +275,11 @@ mash_playbook_devture_systemd_service_manager_services_list_auto_itemized:
     {{ ({'name': (echoip_identifier + '.service'), 'priority': 2000, 'groups': ['mash', 'echoip']} if echoip_enabled else omit) }}
   # /role-specific:echoip
 
+  # role-specific:endlessh
+  - |-
+    {{ ({'name': (endlessh_identifier + '.service'), 'priority': 2000, 'groups': ['mash', 'endlessh']} if endlessh_enabled else omit) }}
+  # /role-specific:endlessh
+
   # role-specific:etcd
   - |-
     {{ ({'name': (etcd_identifier + '.service'), 'priority': 500, 'groups': ['mash', 'etcd']} if etcd_enabled else omit) }}
@@ -1943,6 +1948,43 @@ echoip_container_labels_traefik_tls_certResolver: "{{ devture_traefik_certResolv
 # /role-specific:echoip
 
 
+# role-specific:endlessh
+########################################################################
+#                                                                      #
+# endlessh                                                             #
+#                                                                      #
+########################################################################
+
+endlessh_enabled: false
+endlessh_hostname: "{{ mash_playbook_metrics_exposure_hostname }}"
+endlessh_path_prefix: "{{ mash_playbook_metrics_exposure_path_prefix }}/{{ endlessh_identifier }}"
+endlessh_identifier: "{{ mash_playbook_service_identifier_prefix }}endlessh"
+endlessh_base_path: "{{ mash_playbook_base_path }}/{{ mash_playbook_service_base_directory_name_prefix }}endlessh"
+endlessh_uid: "{{ mash_playbook_uid }}"
+endlessh_gid: "{{ mash_playbook_gid }}"
+
+endlessh_container_additional_networks_auto: |
+  {{
+    ([mash_playbook_reverse_proxyable_services_additional_network] if mash_playbook_reverse_proxyable_services_additional_network else [])
+  }}
+
+
+# Only enable Traefik labels if a hostname is set (indicating that this will be exposed publicly)
+endlessh_container_labels_traefik_enabled: "{{ mash_playbook_traefik_labels_enabled and endlessh_hostname }}"
+endlessh_container_labels_traefik_docker_network: "{{ mash_playbook_reverse_proxyable_services_additional_network }}"
+endlessh_container_labels_traefik_entrypoints: "{{ devture_traefik_entrypoint_primary }}"
+endlessh_container_labels_traefik_tls_certResolver: "{{ devture_traefik_certResolver_primary }}"
+
+endlessh_container_labels_metrics_middleware_basic_auth_enabled: "{{ mash_playbook_metrics_exposure_http_basic_auth_enabled }}"
+endlessh_container_labels_metrics_middleware_basic_auth_users: "{{ mash_playbook_metrics_exposure_http_basic_auth_users }}"
+
+########################################################################
+#                                                                      #
+# /endlessh                                                            #
+#                                                                      #
+########################################################################
+# /role-specific:endlessh
+
 # role-specific:etcd
 ########################################################################
 #                                                                      #

templates/requirements.yml

@@ -88,6 +88,10 @@
   version: v0.0.0-0
   name: echoip
   activation_prefix: echoip_
+- src: git+https://github.com/sudo-Tiz/ansible-role-endlessh.git
+  version: main
+  name: endlessh
+  activation_prefix: endlessh_
 - src: git+https://github.com/mother-of-all-self-hosting/ansible-role-etcd.git
   version: v3.5.11-0
   name: etcd

templates/setup.yml

@@ -163,6 +163,10 @@
     - role: galaxy/echoip
     # /role-specific:echoip
 
+    # role-specific:endlessh
+    - role: galaxy/endlessh
+    # /role-specific:endlessh
+
     # role-specific:etcd
     - role: galaxy/etcd
     # /role-specific:etcd