From c549ff331948b6bb4b1cfd97510a0801570a4a24 Mon Sep 17 00:00:00 2001 From: Tiz <72883092+sudo-Tiz@users.noreply.github.com> Date: Tue, 9 Jul 2024 18:19:23 +0000 Subject: [PATCH] Add Endlessh-go (#228) * add templates files * add documentation * upgrade endlessh documentation * Fix some typos, improve indentation --------- Co-authored-by: sudo-Tiz Co-authored-by: Slavi Pantaleev --- docs/services/endlessh.md | 111 ++++++++++++++++++++++++++++++ docs/supported-services.md | 1 + templates/group_vars_mash_servers | 42 +++++++++++ templates/requirements.yml | 4 ++ templates/setup.yml | 4 ++ 5 files changed, 162 insertions(+) create mode 100644 docs/services/endlessh.md diff --git a/docs/services/endlessh.md b/docs/services/endlessh.md new file mode 100644 index 0000000..114e324 --- /dev/null +++ b/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). diff --git a/docs/supported-services.md b/docs/supported-services.md index 9de5def..eaedc89 100644 --- a/docs/supported-services.md +++ b/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) | diff --git a/templates/group_vars_mash_servers b/templates/group_vars_mash_servers index cbde2fd..df03991 100644 --- a/templates/group_vars_mash_servers +++ b/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 ######################################################################## # # diff --git a/templates/requirements.yml b/templates/requirements.yml index 9ef2a51..6a938a8 100644 --- a/templates/requirements.yml +++ b/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 diff --git a/templates/setup.yml b/templates/setup.yml index e1da3f1..5a92413 100644 --- a/templates/setup.yml +++ b/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