Skip to content

Latest commit

 

History

History
248 lines (165 loc) · 10.4 KB

README.md

File metadata and controls

248 lines (165 loc) · 10.4 KB
Raw

endlessh-notify

Latest Release License: MIT Docker Pulls

Event notification for endlessh and endlessh-go

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

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.

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

Linux Host

If you are

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