1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
|
# Proxmox VE Ansible Playbook
This repository contains an Ansible playbook designed to automate the installation, configuration, hardening, and deployment of a Proxmox Virtual Environment (VE) server with enhanced security measures and optional WireGuard VPN integration for secure management.
## Overview
The playbook automates the following tasks:
- **Proxmox VE Installation**: Configures a Debian-based system with Proxmox VE, including necessary repositories, GPG keys, and kernel upgrades.
- **System Hardening**: Applies security best practices, including SSH configuration, firewall setup, and fail2ban for intrusion prevention.
- **Network Configuration**: Sets up network interfaces, including bridged networking for Proxmox VMs and containers.
- **WireGuard VPN**: Optionally deploys a WireGuard VPN server for secure remote management of the Proxmox VE instance.
- **Administrative User Setup**: Creates a secure administrative user for Proxmox management with a randomly generated password.
- **Firewall and NAT**: Configures UFW with NAT masquerading for VM/container networking and restricts access to management interfaces.
## Playbook Structure
The playbook is organized into several task files, templates, and configuration files, as detailed below:
### Task Files
- **tasks/preflight.yaml**: Ensures the playbook runs as root and verifies the system is Debian-based.
- **tasks/pve_setup.yaml**: Installs Proxmox VE, configures APT repositories, downloads and verifies the Proxmox GPG key, upgrades packages, and removes conflicting Debian kernels.
- **tasks/pve_configure.yaml**: Configures network interfaces, sets up NAT rules, enables IP forwarding, deploys a static `/etc/resolv.conf`, and creates a Proxmox administrative user.
- **tasks/harden.yaml**: Hardens the system by:
- Clearing MOTD and issue files.
- Restricting cron/at to root-only.
- Hardening SSH configuration (e.g., disabling root login, limiting authentication attempts).
- Regenerating SSH host keys.
- Enabling unattended upgrades.
- Configuring UFW with a deny-by-default policy.
- Setting up fail2ban with an aggressive SSH jail.
- Disabling IPv6 via GRUB.
- **tasks/wg_setup.yaml**: Installs and configures a WireGuard VPN server for secure management, including peer management scripts and firewall rules.
### Configuration Files (in `files/`)
- **pve-no-subscription.list**: APT source list for the Proxmox VE no-subscription repository.
- **pveproxy**: Configures the Proxmox VE proxy to listen on the WireGuard subnet or localhost.
- **resolv.conf**: Static DNS configuration using Cloudflare's 1.1.1.1 and 1.0.0.1.
- **fail2ban/jail.d/sshd.local**: Fail2ban configuration for SSH with aggressive mode, banning IPs after 3 failed attempts within 10 minutes for 24 hours.
### Templates (in `templates/`)
- **hosts.j2**: Configures `/etc/hosts` with the Proxmox hostname and localhost entries.
- **interfaces.j2**: Sets up network interfaces, including a public interface and bridged networking (vmbr0, vmbr1).
- **wg0.conf.j2**: WireGuard server configuration with iptables rules for NAT and forwarding.
- **manage_wg_peers.sh.j2**: Script for adding/removing WireGuard peers with secure key management.
- **pveproxy**: Configures the Proxmox VE proxy to listen on the WireGuard subnet.
### Variables (in `vars/main.yaml`)
- **apt_packages**: List of essential packages
- **pve_packages**: Proxmox-specific packages
- **wireguard_packages**: WireGuard and related tools
- **fail2ban_jail_dir**: Directory for fail2ban jail configurations.
- **pve_hostname**: Dynamically generated hostname with a random hex suffix.
- **wg_server_home**, **wg_peers_home**, **wg_ip_file**, **wg_subnet_prefix**: WireGuard configuration paths and subnet settings.
## Usage
1. Clone this repository onto your control machine.
2. Install Python dependencies with `pip install -r requirements.txt` (if applicable).
3. Configure your inventory file (`inventory.yaml`) with the target host details.
4. Run the playbook:
```
ansible-playbook -i inventory.yaml playbook.yml
```
## Requirements
- Ansible 2.9+
- Debian-based Linux host (specifically Debian Bookworm) with systemd service manager.
- Root access to the target host.
- Internet access for downloading packages and the Proxmox GPG key.
## Security Considerations
- **SSH Hardening**: The playbook enforces strict SSH settings, including limiting authentication attempts and disabling weak ciphers. However, it permits root login by default (configurable in tasks/harden.yaml).
- **Fail2ban**: Aggressive SSH jail bans IPs after 3 failed attempts within 10 minutes for 24 hours.
- **UFW Firewall**: Deny-by-default policy with explicit allowances for SSH (port 22), Proxmox VE (port 8006), and WireGuard (configurable UDP port).
- **WireGuard**: Provides secure remote access to the Proxmox VE management interface, restricted to the WireGuard subnet.
- **Immutable /etc/resolv.conf**: Prevents DNS configuration changes by setting the immutable attribute.
- **Password Security**: The Proxmox admin user (pveadmin@pve) is assigned a random 32-character password, stored in /root/pveadmin_credentials.txt (accessible only by root).
## Customization
- **Hostname**: Modify pve_hostname in vars/main.yaml or override it in your inventory.
- **WireGuard Subnet**: Adjust wg_subnet and wg_subnet_prefix in vars/main.yaml to match your network.
- **SSH Port**: Change the SSH port in tasks/harden.yaml and update the UFW rule in tasks/harden.yaml and fail2ban configuration in files/fail2ban/jail.d/sshd.local.
- **Proxmox Repository**: The playbook uses the no-subscription repository by default, which is not recommended for production. For production, replace files/pve-no-subscription.list with the enterprise repository and update the GPG key in tasks/pve_setup.yaml.
## License
This project is licensed under the GNU General Public License. See the LICENSE file for details.
## Disclaimer
This repository is provided "as is" without warranty. The author and contributors are not liable for any damages or legal consequences arising from its use. Use responsibly and only in authorized environments.
|