FoxxMD/endlessh-notify

Event notification for endlessh and endlessh-go

endlessh-notify

Event notification for endlessh and endlessh-go

• What Does It Do?
• Prerequisites
• Quick Start
• Install
  • Docker
    • Logs Mount
    • Config Mount
    • Linux Host
    • Full Example
  • Local (Node)
• Configuring Endlessh
  • endlessh
  • endlessh-go
• Configuring Notifiers
  • Debounce Interval
  • Event Types
    • Event Filters
  • Specific Notifiers
    • Discord
    • Ntfy
    • Gotify

What Does It Do?

endlessh-notify tails the logs from your endlessh instance and will send notifications using Discord webhooks, ntfy, and gotify when any of these events occurs:

• New* IP tries to connect
• New* IP disconnect

*You can control how an IP is considered "new" based on when it was last seen.

Prerequisites

• A running endlessh or endlessh-go instance with file logging enabled.
  • Access to log files
• A Discord webhook, running ntfy instance, or running gotify instance

Quick Start

Assuming:

• Using docker
• Endlessh log files are located at /home/user/endlessLogs on your host system
• A discord webhook https://discord.com/api/webhooks/MY_WEBHOOK
• Notify if IP from event hasn't been seen before or was last seen more than 24 hours ago

docker run -d -e DISCORD_WEBHOOK="https://discord.com/api/webhooks/MY_WEBHOOK" -e DEBOUNCE_INTERVAL="1 day" -v /home/user/endlessLogs:/endlessh foxxmd/endlessh-notify

Install

Docker

• Dockerhub - docker.io/foxxmd/endlessh-notify
• GHCR - ghcr.io/foxxmd/endlessh-notify

(Optionally) Set the timezone for the container using the environmental variable TZ (docker) (docker-compose)

Logs Mount

You must bind the directory on the host containing the endlessh log files to /endless in the container.

• Using -v method for docker: -v /path/on/host/logs:/endlessh
• Using docker-compose: - /path/on/host/logs:/endlessh

Config Mount

If you use a Config file you must bind the directory on the host containing the config file to /config in the container

• Using -v method for docker: -v /path/on/host/config:/config
• Using docker-compose: - /path/on/host/config:/config

Linux Host

If you are

• using rootless containers with Podman
• running docker on MacOS or Windows

this DOES NOT apply to you.

If you are running Docker on a Linux Host you must specify user:group permissions of the user who owns the configuration directory on the host to avoid docker file permission problems. These can be specified using the environmental variables PUID and PGID.

To get the UID and GID for the current user run these commands from a terminal:

• id -u -- prints UID
• id -g -- prints GID

Full Example

Assuming

• Host UID is 99
• Host GID is 100
• Config using ENV
• Discord with Mapquest
• Logs at /home/myUser/endlessLogs

docker run -d -e PUID=99 PGID=100 -e DISCORD_WEBHOOK="https://discord.com/api/webhooks/MY_WEBHOOK" -e MAPQUEST_KEY="V3CPFmir2JEnj" -v /home/myUser/endlessLogs:/endlessh foxxmd/endlessh-notify

• Using config-file instead of ENVs

docker run -d -e PUID=99 PGID=100 -v /home/myUser/endlessh-notify-config:/config  -v /home/myUser/endlessLogs:/endlessh foxxmd/endlessh-notify

Local (Node)

clone https://github.com/FoxxMD/endlessh-notify.git .
cd endlessh-notify
npm install
npm run start

Local install may also use ENVs instead of config files. Directory locations are controlled with ENVs:

• CONFIG_DIR => Default ./config => Directory location of endlessh-notify config
• ENDLESS_DIR => Default ./endlessData => Directory location of endlessh logs

Configuring Endlessh

endlessh-notify parses events using log files generated by endlessh. You must enable file logging on your instance for endlessh-notify to work.

endlessh

• If using Linuxserver.io version add ENV LOGFILE=true to your run command
• Using endlessh directly -- add -s to command output and setup a config file with LogLevel 1

endlessh-go

Add these arguments to your run command (make sure log_dir is a viable directory):

-alsologtostderr -v=1 -log_dir=/config

Configuring Notifiers

endlessh-notify can have one or many Notifiers. Each Notifier has its own defined behavior on how to handle events parsed from endlessh.

Notifiers can be configured with

• environmental variables outlined in the sections below
• using a config file, see config.yaml for a kitchensink example

Common behavior that can be defined for all notifiers:

Debounce Interval

This duration determines how "old" a previously seen IP must be before it is considered "new". If an IP has not been seen before it is always new. The default is 1 day.

The syntax for a duration is [Value] [Unit] where unit is any available unit from Dayjs, examples:

• 18 minutes
• 1 hour
• 4 days

Debounce can be configured:

• For all notifiers using ENV => Set with DEBOUNCE_INTERVAL env IE DEBOUNCE_INTERVAL="6 hours"
• Per notifier using a config file => sSee config.yaml example

Event Types

Each notifier can be configured to notify on one or many Events. An Event can be:

• Accept -- When an IP establishes a connection with endlessh
• Close -- When an IP disconnects from endlessh

For notifiers that do not have any events configured via a config file the type of events that are notified can be configured through ENV:

NOTIFY_EVENTS=accept,close

To control behavior for individual notifiers or event behavior use a file config, see config.yaml example

Event Filters

Additionally, Events can be filtered based on stats for the individual Event or overall for the running session of endless-notify.

• Accept
  • maxTotalConnections - Notify if total connections by IP is less than this
  • minTotalConnections - Notify if total connections by IP is more than this
• Close
  • maxTotalConnections - Notify if total connections by IP is less than this
  • minTotalConnections - Notify if total connections by IP is more than this
  • maxTrappedTime - Notify if event trapped time was less this
  • minTrappedTime - Notify if event trapped time was more than this
  • maxTotalTrappedTime - Notify if total trapped time for IP was less than this
  • minTotalTrappedTime - Notify if total trapped time for IP was more than this

Specific Notifiers

Discord

Create a webhook for a Discord server you have proper permissions for.

Optionally, get a Mapquest Key for endless-notify to generate map images of approximate IP locations in the Discord message.

Name	Required	Default	Description
DISCORD_WEBHOOK	Yes
MAPQUEST_KEY	No		Used to generate map image of IP location
DEBOUNCE_INTERVAL	No	1 hour

Or see config.yaml example

Ntfy

Name	Required	Default	Description
NTFY_URL	Yes
NTFY_TOPIC	Yes
NTFY_USER	No
NTFY_PASS	No
DEBOUNCE_INTERVAL	No	1 hour

Or see config.yaml example

Gotify

Name	Required	Default	Description
GOTIFY_URL	Yes
GOTIFY_TOKEN	Yes
DEBOUNCE_INTERVAL	No	1 hour

Or see config.yaml example