// Tutorial //

How To Set Up an Endlessh Tarpit on Ubuntu 22.04

Published on June 7, 2022
Default avatar
By Reuben Tier
Developer and author at DigitalOcean.
How To Set Up an Endlessh Tarpit on Ubuntu 22.04

The author selected the Free and Open Source Fund to receive a donation as part of the Write for DOnations program.

Introduction

When you look at authentication logs, you might see several failed login attempts from various IP addresses. These failed login attempts often come from a node on a botnet that scans the entire web for vulnerable servers with default credentials. While most people will have a secure password or SSH keys preventing attackers from logging into their server, some servers will be vulnerable to this scan. Although you may not be able to stop these attacks, you can slow them down with tarpits.

In this tutorial, you will install and configure Endlessh, a tarpit that slowly sends an infinitely long banner to any user attempting login. You will also configure the SSH service to run on a different port, which will make your authentication logs more readable.

After completing this tutorial, you will be able to connect to your server on a non-standard port, while any bots scanning your server will find their time is wasted by knocking on a door that will never open.

Prerequisites

To complete this tutorial, you will need the following:

Step 1 – Moving SSH to a Non-Standard Port

In this step, you will move SSH to a non-standard port in order to free up a port for Endlessh. Because botnets don’t have endless resources, they typically scan just the default SSH port (22). By moving your SSH to a non-standard port, you can trap the bot in the Endlessh tarpit.

To begin, make a backup of your SSH config file from your server with the following command:

  1. sudo cp /etc/ssh/sshd_config /etc/ssh/sshd_config.bak

This file can be used to restore the original settings if something doesn’t work or if you decide to move SSH back to the default port.

Open the SSH configuration file /etc/ssh/sshd_config using nano or your favorite text editor:

  1. sudo nano /etc/ssh/sshd_config

Locate the line #Port 22. Uncomment this line by removing the #, and then change the port to an unused port on your server:

/etc/ssh/sshd_config
...
Port 2222
...

An example of a normally unused port is 2222. You can select whichever port you want to use for your recurring SSH connections. Save and close the file.

If your server is using a firewall, such as ufw, you will need to allow traffic to the new port:

  1. sudo ufw allow 2222/tcp

Next, restart the SSH service:

  1. sudo systemctl restart sshd

In a separate terminal session, attempt to connect to your server using the new port:

  1. ssh sammy@your_server_ip -p 2222

Warning: Do not close your active SSH session unless you have confirmed you can use SSH on the new port. If you can’t connect through the new port, you risk losing access to your server by closing the session. If you cannot connect to your server in a separate terminal session, you can restore your original SSH settings by running the following commands:

  1. sudo cp /etc/ssh/sshd_config.bak /etc/ssh/sshd_config
  2. sudo systemctl restart sshd

If you encounter further issues, check that sshd restarted successfully and review your firewall settings to ensure port 2222 accepts tcp traffic.

Once you have verified you can make a new connection to port 2222, you can close your original terminal safely. When connecting to your server in the future, you will always need to specify the new port, like so:

  1. ssh sammy@your_server_ip -p 2222

Now that you have successfully moved SSH to a non-standard port, it’s time to set up Endlessh.

Step 2 – Installing Endlessh

Endlessh doesn’t have an official package, so you will clone the repository to build it manually. You will use Git to clone the repository, the build-essential package (to compile the project), and the libc6-dev package.

Install the required packages using the apt package manager:

  1. sudo apt install build-essential libc6-dev

Confirm the installation with y when prompted.

Then clone the Endlessh repository from GitHub to your home directory:

  1. git clone https://github.com/do-community/endlessh

Move into the project directory and use the make command to compile Endlessh:

  1. cd endlessh
  2. make

You can now start Endlessh with the following command:

  1. sudo ./endlessh -v -p 22

To test that Endlessh is working, you can attempt to make an SSH connection to port 22 with the -v verbose flag, which will show the endless banner being transmitted. In a new terminal window, make an SSH connection to the port 22 with either of the following commands:

  1. ssh sammy@your_server_ip -v
  1. ssh sammy@your_server_ip -p 22 -v

When your new SSH session attempts to connect to port 22, you will see a string of random characters appear in the connection terminal every 10 seconds until the session is closed, like the output below:

Output
debug1: kex_exchange_identification: banner line 0: NvnHF>]&W4p+tg*"+ debug1: kex_exchange_identification: banner line 1: n< debug1: kex_exchange_identification: banner line 2: @/O5c0/;>1b{qd(M,vK debug1: kex_exchange_identification: banner line 3: i+ OZ debug1: kex_exchange_identification: banner line 4: yn debug1: kex_exchange_identification: banner line 5: T[V\\[HUg

Once you have confirmed it is working by attempting to connect with a new session, you can close the new terminal and stop Endlessh using Ctrl+C in your original terminal session.

In this step, you downloaded and built Endlessh from the source. Next, you will configure it and deploy it as a service to make it persistent when logging out and restarting your server.

Step 3 – Configuring Endlessh

In this step, you will set up Endlessh as a service that will persist after your session ends and through system restarts.

Move the compiled binary into the /usr/local/bin directory:

  1. sudo mv ./endlessh /usr/local/bin/

Enter your password if prompted.

Copy the service file from the project into the /etc/systemd/system directory:

  1. sudo cp util/endlessh.service /etc/systemd/system/

You will change the service file slightly to run Endlessh on ports under 1024. Open the service file in nano or your favourite text editor:

  1. sudo nano /etc/systemd/system/endlessh.service

Find the section about running Endlessh on ports under 1024.

Update the file by removing # at the beginning of the line with AmbientCapabilities=CAP_NET_BIND_SERVICE and adding # to the beginning of the line PrivateUsers=true, like so:

/etc/systemd/system/endlessh.service
...
## If you want Endlessh to bind on ports < 1024
## 1) run: 
##     setcap 'cap_net_bind_service=+ep' /usr/local/bin/endlessh
## 2) uncomment following line
AmbientCapabilities=CAP_NET_BIND_SERVICE
## 3) comment following line
#PrivateUsers=true
...

Save and exit the file.

Next, you will allow Endlessh to run on ports lower than 1024, also referred to as internet domain privileged ports. Set this capability for the Endlessh binary with the setcap command:

  1. sudo setcap 'cap_net_bind_service=+ep' /usr/local/bin/endlessh

You will need to define a config file for Endlessh to tell it which port to use. Create and open a config file named /etc/endlessh/config:

  1. sudo mkdir /etc/endlessh
  2. sudo nano /etc/endlessh/config

In the config file, define the port to use as 22:

/etc/endlessh/config
Port 22

Save and close the file.

Now you can start the Endlessh service persistently:

  1. sudo systemctl --now enable endlessh

Including --now enable will make the service persist after rebooting your server.

To check that the service started successfully, you can use the systemctl status command:

  1. sudo systemctl status endlessh

If started successfully, you will see an output like this:

Output
● endlessh.service - Endlessh SSH Tarpit Loaded: loaded (/etc/systemd/system/endlessh.service; enabled; vendor preset: enabled) Active: active (running) since Fri 2022-04-22 11:20:39 UTC; 1 months 11 days ago Docs: man:endlessh(1) Main PID: 34007 (endlessh) Tasks: 1 (limit: 1081) Memory: 380.0K CGroup: /system.slice/endlessh.service └─34007 /usr/local/bin/endlessh

If it is running, you can attempt to connect on port 22 in a new terminal session:

  1. ssh sammy@your_server_ip

Because your tarpit is running, the new terminal session will not be able to connect and will run in perpetuity until stopped manually with Ctrl+C in the connecting terminal.

If you wish to stop the service from running, you can use the following command:

  1. sudo systemctl --now disable endlessh

After stopping the service, you can use the SSH restoration instructions in the Step 1 warning to restore your original server configuration. You can re-enable the service with sudo systemctl --now enable endlessh without going through the setup process again, but make sure SSH is not running on port 22 when you do.

Conclusion

You have successfully installed and configured Endlessh, helped clear up your authentication logs, and prepared to waste the time of random SSH bots.

After setting up your Endlessh tarpit, review other Recommended Security Measures to Protect Your Servers.

If you’ve enjoyed this tutorial and our broader community, consider checking out our DigitalOcean products which can also help you achieve your development goals.

Learn more here


About the authors
Default avatar
Developer and author at DigitalOcean.

Default avatar
Technical Editor

Still looking for an answer?

Was this helpful?
Leave a comment

This textbox defaults to using Markdown to format your answer.

You can type !ref in this text area to quickly search our full set of tutorials, documentation & marketplace offerings and insert the link!