Update README.md

2025-12-29 16:14:59 +00:00 · 2025-06-26 21:45:26 +01:00
parent 4acc98bf4c
commit 2b882dc774
1 changed files with 88 additions and 99 deletions
--- a/README.md
+++ b/README.md
@@ -1,124 +1,113 @@
-# Debian/Ubuntu Server Setup and Hardening Script
+# Debian & Ubuntu Server Hardening Script

-**Version**: 4.1 | **Date**: 2025-06-26  
-**Compatible with**: Debian 12 (Bookworm), Ubuntu 20.04 LTS, 22.04 LTS, 24.04 LTS, 24.10 (experimental)
+**Version:** 3.8  
+**Last Updated:** 2025-06-26  
+**Compatible With:**  
+- Debian 12 (Bookworm)  
+- Ubuntu 20.04 LTS, 22.04 LTS, 24.04 LTS  

-## Overview
+---

-This Bash script automates the provisioning and hardening of a Debian 12 or Ubuntu server (20.04, 22.04, 24.04 LTS, or 24.10). It configures essential security settings, user management, SSH hardening, firewall rules, and optional features like Docker, Tailscale (with Headscale support), and system monitoring (SMTP and ntfy). The script is idempotent, supports configuration files for automation, and provides flexibility for missing or partial configurations.
+## 📌 Overview

-## Features
+This script automates the secure provisioning and hardening of a fresh Debian or Ubuntu server. It covers essential system settings, user management, SSH hardening, firewall configuration, and optional installation of Docker and Tailscale.

- **System Checks**: Validates root privileges, internet connectivity, and OS compatibility.
- **User Management**: Creates a new admin user with sudo privileges and optional SSH key setup.
- **SSH Hardening**: Configures a custom SSH port, disables root login, and enforces key-based authentication.
- **Firewall (UFW)**: Sets up restrictive firewall rules with customizable ports.
- **Fail2Ban**: Protects against brute-force attacks on SSH and other ports.
- **Automatic Updates**: Enables unattended security updates (optional).
- **System Monitoring**: Configures disk space and backup alerts via SMTP and/or ntfy (optional).
- **Docker**: Installs Docker Engine and adds the user to the docker group (optional).
- **Tailscale**: Sets up Tailscale VPN with Headscale support (optional).
- **Swap**: Configures or resizes swap space (skipped in containers).
- **Time Sync**: Ensures chrony is active for time synchronization.
- **Logging & Backups**: Logs all actions to `/var/log/setup_harden_debian_ubuntu_*.log` and backs up critical files to `/root/setup_harden_backup_*`.
+It is designed to be **idempotent**, **safe**, and suitable for **production environments**.

-## Prerequisites
+---

- Run as root (`sudo ./setup_harden_debian_ubuntu.sh`).
- Internet connectivity for package installation.
- At least 2GB free disk space for swap (if enabled).
- Compatible OS: Debian 12 or Ubuntu 20.04/22.04/24.04 LTS (24.10 experimental).
+## ⚙️ Features

-## Usage
+- Root login disabled, new admin user creation  
+- SSH key-based login support and key detection  
+- UFW firewall configuration with custom port support  
+- SSH and system configuration backup and rollback safety  
+- Timezone and swap file setup  
+- Optional installation of:
+  - Docker & Docker Compose
+  - Tailscale (Mesh VPN)
+- Logging to `/var/log/`
+- Optional quiet mode for automated scripts

-1. **Download the Script**:
-   ```bash
-   wget https://raw.githubusercontent.com/buildplan/setup_harden_server/refs/heads/main/setup_harden_debian_ubuntu.sh
-   chmod +x setup_harden_debian_ubuntu.sh
-   ```
+---

-2. **Run Interactively**:
-   ```bash
-   sudo ./setup_harden_debian_ubuntu.sh
-   ```
+## 📥 Installation & Usage

-3. **Run with Config File**:
-   ```bash
-   sudo ./setup_harden_debian_ubuntu.sh --config /etc/setup_harden.conf
-   ```
+### 1. Download the script

-4. **Run in Quiet Mode**:
-   ```bash
-   sudo ./setup_harden_debian_ubuntu.sh --quiet
-   ```
-
-## Configuration File
-
-You can provide a configuration file (e.g., `/etc/setup_harden.conf`) to automate setup. If variables are missing or invalid, the script will prompt interactively (unless in `--quiet` mode, where it skips optional settings).
-
-**Example Config**:
 ```bash
-USERNAME=admin
-HOSTNAME=myVM1
-SSH_PORT=2222
-TIMEZONE=Etc/UTC
-SWAP_SIZE=2G
-UFW_PORTS=2222/tcp
-AUTO_UPDATES=yes
-INSTALL_DOCKER=yes
-INSTALL_TAILSCALE=yes
-TAILSCALE_LOGIN_SERVER=https://hs.mydomain.com
-TAILSCALE_AUTH_KEY=tskey-xxxxxxxxxxxxxxxxxxxxxxxxxxxx
-TAILSCALE_OPERATOR=admin
-TAILSCALE_ACCEPT_DNS=yes
-TAILSCALE_ACCEPT_ROUTES=yes
-SMTP_SERVER=mail.smtp2go.com
-SMTP_PORT=587
-SMTP_USER=smtp2go_username
-SMTP_PASS=smtp2go_password
-SMTP_FROM=alerts@mydomain.com
-SMTP_TO=admin@mydomain.com
-NTFY_SERVER=https://ntfy.mydomain.com/ovps
-NTFY_TOKEN=tk_xxxxxxxxxxxxxxxxxxxxxxxx
+wget https://raw.githubusercontent.com/buildplan/learning/refs/heads/main/setup_harden_debian_ubuntu.sh
+chmod +x setup_harden_debian_ubuntu.sh
+````
+
+### 2. Run the script as root
+
+```bash
+sudo ./setup_harden_debian_ubuntu.sh
 ```

-**Configuration Notes**:
- **Required Variables**: `USERNAME`, `HOSTNAME`, `SSH_PORT`. If missing, the script will prompt (non-quiet mode) or fail (quiet mode).
- **Optional Variables**: All others (e.g., `UFW_PORTS`, `SMTP_*`, `NTFY_*`, `TAILSCALE_*`). If partially provided, the script prompts for missing values or skips the feature in quiet mode.
- **SMTP Credentials**: `SMTP_USER` and `SMTP_PASS` are required for SMTP authentication when `SMTP_SERVER` is specified. In non-quiet mode, the script prompts for these if missing. In quiet mode, SMTP configuration is skipped if these are not provided.
- **Validation**: The script validates all inputs (e.g., username format, port numbers, URLs). Invalid values trigger prompts or skipping.
+### 3. Optional: Run in quiet mode

-## Flexible Configuration Handling
+```bash
+sudo ./setup_harden_debian_ubuntu.sh --quiet
+```

- **Missing Variables**: If a config file lacks variables, the script prompts interactively (non-quiet mode) or skips optional features (quiet mode).
- **Partial Configurations**: For features like Tailscale, SMTP, or ntfy, if some variables are missing, the script prompts for them or skips the feature in quiet mode.
- **No Config File**: Falls back to full interactive mode (non-quiet) or minimal setup with optional features skipped (quiet).
- **Summary**: The final summary lists applied, skipped, or prompted settings.
+> 🔒 The script must be run as root (or with sudo privileges).

-## Output
+---

- **Log File**: `/var/log/setup_harden_debian_ubuntu_YYYYMMDD_HHMMSS.log`
- **Backups**: `/root/setup_harden_backup_YYYYMMDD_HHMMSS/`
- **Summary**: Displays configured settings, skipped features, and verification steps.
+## 📂 What It Does

-## Troubleshooting
+| Task                          | Description                                    |
+| ----------------------------- | ---------------------------------------------- |
+| Admin User Creation           | Creates new sudo user with password or SSH key |
+| SSH Hardening                 | Disables root login, adjusts secure options    |
+| Firewall                      | UFW setup with customisable ports              |
+| Package Installation          | Essential tools (curl, fail2ban, etc.)         |
+| System Config Backup          | Creates backups before making changes          |
+| Swap File Setup               | Creates a swap file with size selection        |
+| Timezone Selection            | Interactive timezone configuration             |
+| Docker & Tailscale (optional) | Only installed when prompted                   |

- **SSH Lockout**: Restore SSH config from `/root/setup_harden_backup_*/sshd_config.backup_*`.
- **Errors**: Check the log file for details.
- **Firewall**: Ensure your VPS provider's edge firewall allows opened ports (e.g., SSH, HTTP).
- **Disk Space**: Verify >2GB free for swap (if enabled).
- **Testing**: Run in a VM before production use.
+---

-## Post-Setup Steps
+## 🪵 Logs & Backups

-1. **Verify SSH**: `ssh -p <SSH_PORT> <USERNAME>@<SERVER_IP>`
-2. **Check Firewall**: `sudo ufw status verbose`
-3. **Check Services**: `systemctl status ssh fail2ban chrony docker tailscaled postfix`
-4. **Reboot**: Recommended to apply all changes (`sudo reboot`).
+* **Logs:** `/var/log/setup_harden_debian_ubuntu_*.log`
+* **Config Backups:** `/root/setup_harden_backup_*`
+* **SSHD Backup:** Restorable from the backup directory in case of issues

-## Notes
+---

- Tested on Debian 12, Ubuntu 20.04/22.04/24.04 LTS. Ubuntu 24.10 is experimental and may require manual adjustments.
- In quiet mode, missing optional settings are skipped, and required settings must be valid, or the script fails.
- A reboot is required to ensure all changes take effect.
- For DigitalOcean, configure the edge firewall in the Control Panel to allow custom SSH ports and other opened ports.
+## 🧪 Tested On
+
+* Debian 12 (Bookworm)
+* Ubuntu 20.04, 22.04, and 24.04 (LTS only)
+* VirtualBox, KVM, and common VPS providers (Hetzner, DigitalOcean, etc.)
+
+---
+
+## ❗ Important Notes
+
+* Always test in a VM or staging VPS before using in production.
+* Ensure you have console or out-of-band access in case SSH becomes inaccessible.
+* A system **reboot is recommended** after running the script.
+
+---
+
+## 🛠 Troubleshooting
+
+* **SSH Locked Out?** Use the server console and restore:
+
+  ```bash
+  cp /root/setup_harden_backup_*/sshd_config /etc/ssh/sshd_config
+  systemctl restart ssh
+  ```
+* **No internet?** The script requires internet access to install packages.
+
+---
+
+## 📝 License
+
+This script is open-source and provided "as is" without warranty.
+Use at your own risk.