mash-playbook/docs/services/endlessh.md

Endlessh

Endlessh-go is a Golang implementation of endlessh, an SSH tarpit. Installing it is powered by the mother-of-all-self-hosting/ansible-role-endlessh Ansible role.

Dependencies

This service requires the following other services:

• (optionally) Traefik - a reverse-proxy server for exposing endlessh publicly
• (optionally) Prometheus - a database for storing metrics
• (optionally) Grafana - 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 or write your own.

Configuration

To enable this service, add the following configuration to your vars.yml file and re-run the installation process:

########################################################################
#                                                                      #
# 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:

endlessh_container_host_bind_port: 22

See the full list of options in the default/main.yml file

Integrating with Prometheus

Endlessh can natively expose metrics to Prometheus.

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
• If Endlessh is on the same host than prometheus, refer to section Ensure Prometheus is on the same container network as endlessh.

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:

prometheus_container_additional_networks:
  - "{{ endlessh_container_network }}"

Set container extra flag:

The bare minimum is to set container extra flag -enable_prometheus

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.

Exposing metrics publicly

Unless you're scraping the endlessh metrics from a local Prometheus instance, as described in Integrating with Prometheus, 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 or anyone would be able to read your metrics.

# 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, refer to the documentation of endlessh-go.