Event notification for endlessh and endlessh-go
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.
- 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
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
(Optionally) Set the timezone for the container using the environmental variable TZ
(docker) (docker-compose)
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
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
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 UIDid -g
-- prints GID
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
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 configENDLESS_DIR
=> Default./endlessData
=> Directory location of endlessh logs
endlessh-notify parses events using log files generated by endlessh. You must enable file logging on your instance for endlessh-notify to work.
- 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 withLogLevel 1
Add these arguments to your run command (make sure log_dir
is a viable directory):
-alsologtostderr -v=1 -log_dir=/config
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:
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 IEDEBOUNCE_INTERVAL="6 hours"
- Per notifier using a config file => sSee
config.yaml
example
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
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 thisminTotalConnections
- Notify if total connections by IP is more than this
- Close
maxTotalConnections
- Notify if total connections by IP is less than thisminTotalConnections
- Notify if total connections by IP is more than thismaxTrappedTime
- Notify if event trapped time was less thisminTrappedTime
- Notify if event trapped time was more than thismaxTotalTrappedTime
- Notify if total trapped time for IP was less than thisminTotalTrappedTime
- Notify if total trapped time for IP was more than this
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
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
Name | Required | Default | Description |
---|---|---|---|
GOTIFY_URL |
Yes | ||
GOTIFY_TOKEN |
Yes | ||
DEBOUNCE_INTERVAL |
No | 1 hour |
Or see config.yaml
example