Reorganize workspace structure with system-specific cert directories and DNS automation
This commit is contained in:
root
301
docs/README.md
Normal file
301
docs/README.md
Normal file
@@ -0,0 +1,301 @@
|
||||
# Certificate Management Tools
|
||||
|
||||
Automated certificate generation and signing tools for UCS CA with intelligent system detection and deployment.
|
||||
|
||||
## Features
|
||||
|
||||
- 🔍 **Automatic System Detection** - Detects target system type (Proxmox, Home Assistant, pfSense, TrueNAS, UCS)
|
||||
- 🤖 **Automated Deployment** - Fully automated certificate installation for supported systems
|
||||
- 🌐 **DNS Integration** - Automatically checks and creates DNS records for certificate hostnames
|
||||
- 💾 **Configuration Persistence** - Remembers your settings between runs
|
||||
- 🔐 **Proper Certificate Extensions** - Generates certificates with correct serverAuth extensions
|
||||
- 🎯 **Interactive & Scriptable** - Works both interactively and in automation scripts
|
||||
|
||||
## Supported Systems
|
||||
|
||||
| System | Detection | Deployment | Status |
|
||||
|--------|-----------|------------|--------|
|
||||
| **Proxmox VE** | ✅ Automatic | ✅ Fully Automated | Production Ready |
|
||||
| **pfSense** | ✅ Automatic | ⚠️ Manual (Web UI) | Detected |
|
||||
| **TrueNAS** | ✅ Automatic | ⚠️ Manual (Web UI) | Detected |
|
||||
| **UCS** | ✅ Automatic | ⚠️ Manual | Detected |
|
||||
| **Other/Unknown** | ⚠️ Generic | ⚠️ Manual | Basic Support |
|
||||
|
||||
### Proxmox VE - Full Automation ✅
|
||||
|
||||
For Proxmox systems, the tool provides complete automation:
|
||||
- Generates CSR on the Proxmox host
|
||||
- Signs with UCS CA
|
||||
- Automatically installs to `/etc/pve/local/pveproxy-ssl.{pem,key}`
|
||||
- Creates timestamped backups of existing certificates
|
||||
- Restarts `pveproxy` service
|
||||
- Fully automated, zero manual steps required
|
||||
|
||||
### Other Systems - Manual Deployment ⚠️
|
||||
|
||||
For pfSense, TrueNAS, and other systems:
|
||||
- System type is detected automatically
|
||||
- CSR is generated on the target host
|
||||
- Certificate is signed with UCS CA
|
||||
- Certificate and key are copied to `/tmp/`
|
||||
- Manual installation required through web interface
|
||||
|
||||
## Tools
|
||||
|
||||
### 1. cert-manager.py (Interactive Mode) - **RECOMMENDED**
|
||||
The main interactive tool that handles the entire certificate lifecycle with system detection.
|
||||
|
||||
**Usage:**
|
||||
```bash
|
||||
./scripts/cert-manager.py
|
||||
```
|
||||
|
||||
**Workflow:**
|
||||
1. Detects target system type automatically
|
||||
2. Prompts for certificate details with smart defaults
|
||||
3. Generates CSR on remote host with proper extensions
|
||||
4. Signs certificate with UCS CA (outputs to `certs/<system-type>/` directory)
|
||||
5. **Checks DNS records and offers to create missing ones** 🌐
|
||||
6. Deploys automatically (Proxmox/Home Assistant) or copies to target (others)
|
||||
|
||||
**Features:**
|
||||
- Interactive prompts with default values from previous runs
|
||||
- Automatic system type detection
|
||||
- **Automatic DNS record creation on UCS DNS server**
|
||||
- Intelligent deployment based on system capabilities
|
||||
- Configurable key length (default: 4096 bits)
|
||||
- Remembers last used values for quick reuse
|
||||
- Organized certificate storage by system type
|
||||
|
||||
### 2. generate-csr.sh (Standalone)
|
||||
Generates a certificate signing request on a remote host.
|
||||
|
||||
**Usage:**
|
||||
```bash
|
||||
./scripts/generate-csr.sh <hostname> <common-name> [country] [state] [locality] [org] [ou] [key-bits]
|
||||
```
|
||||
|
||||
**Example:**
|
||||
```bash
|
||||
./scripts/generate-csr.sh 192.168.1.100 server.example.com DE berlin berlin egonetix it 4096
|
||||
```
|
||||
|
||||
**Features:**
|
||||
- Generates CSR with proper server authentication extensions
|
||||
- Configurable RSA key length (2048, 4096, 8192 bits)
|
||||
- Automatic Subject Alternative Names (SANs)
|
||||
- Private key stays on target host (secure)
|
||||
|
||||
### 3. sign-cert.sh (Standalone)
|
||||
Signs a certificate request with the UCS CA.
|
||||
|
||||
**Usage:**
|
||||
```bash
|
||||
./scripts/sign-cert.sh <req-file> <hostname> [days]
|
||||
```
|
||||
|
||||
**Example:**
|
||||
```bash
|
||||
./scripts/sign-cert.sh certs/proxmox/server.csr server 3650
|
||||
```
|
||||
|
||||
**Output:** Certificate is saved to the same directory as the CSR file.
|
||||
|
||||
### 4. detect-system.sh (Utility)
|
||||
Detects the type of system on a remote host.
|
||||
|
||||
**Usage:**
|
||||
```bash
|
||||
./scripts/detect-system.sh <hostname>
|
||||
```
|
||||
|
||||
**Returns:** `proxmox`, `pfsense`, `truenas`, `ucs`, or `unknown`
|
||||
|
||||
### 5. deploy-proxmox.sh (Proxmox Deployment)
|
||||
Automated certificate deployment for Proxmox VE.
|
||||
|
||||
**Usage:**
|
||||
```bash
|
||||
./deploy-proxmox.sh <hostname> <cert-file> <key-file> <short-name>
|
||||
```
|
||||
|
||||
**What it does:**
|
||||
- Backs up existing certificates with timestamp
|
||||
- Installs new certificate and key
|
||||
- Sets correct permissions (640)
|
||||
- Restarts pveproxy service
|
||||
- Provides access URL
|
||||
|
||||
## Configuration
|
||||
|
||||
The interactive tool stores default values in `~/.cert-manager-config.json`.
|
||||
|
||||
**Default values:**
|
||||
- Country: `DE`
|
||||
- State: `berlin`
|
||||
- Locality: `berlin`
|
||||
- Organization: `egonetix`
|
||||
- Organizational Unit: `it`
|
||||
- CA Server: `10.0.0.21`
|
||||
- Validity: `3650` days (10 years)
|
||||
- Key Length: `4096` bits
|
||||
|
||||
**Modifying defaults:**
|
||||
Run `./cert-manager.py` and answer "yes" when asked to modify default values.
|
||||
|
||||
## Interactive Workflow Example
|
||||
|
||||
```bash
|
||||
$ ./cert-manager.py
|
||||
|
||||
============================================================
|
||||
Interactive Certificate Manager
|
||||
============================================================
|
||||
|
||||
--- Certificate Details ---
|
||||
Target Host (IP or hostname) [srv-wmw-host01]: 10.0.0.50
|
||||
|
||||
Detecting system type on 10.0.0.50...
|
||||
✓ Detected: Proxmox VE
|
||||
|
||||
Common Name (FQDN) [srv-wmw-host01.egonetix.lan]: pve-host02.egonetix.lan
|
||||
|
||||
--- Certificate Subject (press Enter to use defaults) ---
|
||||
Country (C) [DE]:
|
||||
State/Province (ST) [berlin]:
|
||||
Locality (L) [berlin]:
|
||||
Organization (O) [egonetix]:
|
||||
Organizational Unit (OU) [it]:
|
||||
Validity (days) [3650]:
|
||||
Key Length (bits) [4096]:
|
||||
|
||||
============================================================
|
||||
Summary:
|
||||
============================================================
|
||||
System Type: Proxmox VE
|
||||
Target Host: 10.0.0.50
|
||||
Common Name: pve-host02.egonetix.lan
|
||||
Country: DE
|
||||
State: berlin
|
||||
Locality: berlin
|
||||
Organization: egonetix
|
||||
Org Unit: it
|
||||
Key Length: 4096 bits
|
||||
Validity: 3650 days
|
||||
CA Server: 10.0.0.21
|
||||
Output files: pve-host02.req, pve-host02-cert.pem
|
||||
============================================================
|
||||
|
||||
Proceed with certificate generation? [Y/n]:
|
||||
|
||||
[Generates CSR, signs, deploys automatically for Proxmox]
|
||||
|
||||
✓ Access Proxmox at: https://10.0.0.50:8006
|
||||
```
|
||||
|
||||
## Certificate Details
|
||||
|
||||
**Generated certificates include:**
|
||||
- RSA keys (configurable: 2048, 4096, or 8192 bits)
|
||||
- SHA-256 signature algorithm
|
||||
- Subject Alternative Names (SANs) for all hostname variants
|
||||
- Proper key usage extensions:
|
||||
- `digitalSignature`
|
||||
- `keyEncipherment`
|
||||
- Extended key usage:
|
||||
- `serverAuth` (TLS Web Server Authentication)
|
||||
|
||||
## Requirements
|
||||
|
||||
- SSH access to target host as root
|
||||
- SSH access to UCS CA server (10.0.0.21) as root
|
||||
- OpenSSL on target host
|
||||
- Python 3.6+ for interactive tool
|
||||
- Bash for shell scripts
|
||||
|
||||
## Security Notes
|
||||
|
||||
1. **Private keys remain on target hosts** - Never transmitted or stored locally
|
||||
2. **Certificate backups** - Proxmox deployment creates timestamped backups
|
||||
3. **Proper permissions** - Certificates are installed with correct file permissions
|
||||
4. **CA access** - Only the signing operation requires CA access
|
||||
5. **SSH security** - Uses BatchMode and secure connection options
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### System not detected correctly
|
||||
```bash
|
||||
# Manually check what system it is
|
||||
./detect-system.sh <hostname>
|
||||
|
||||
# Verify SSH access
|
||||
ssh root@<hostname> "uname -a"
|
||||
```
|
||||
|
||||
### Certificate not trusted in browser
|
||||
```bash
|
||||
# Verify system CA is installed
|
||||
ls -la /usr/local/share/ca-certificates/ucs-root-ca.crt
|
||||
|
||||
# Update system CA certificates
|
||||
sudo update-ca-certificates
|
||||
|
||||
# For browsers using NSS (Firefox, Brave, Chrome):
|
||||
certutil -d sql:$HOME/.pki/nssdb -L | grep -i ucs
|
||||
```
|
||||
|
||||
### Proxmox deployment failed
|
||||
```bash
|
||||
# Check Proxmox certificate directory
|
||||
ssh root@<proxmox-host> "ls -la /etc/pve/local/pveproxy-ssl.*"
|
||||
|
||||
# View pveproxy logs
|
||||
ssh root@<proxmox-host> "journalctl -u pveproxy -n 50"
|
||||
|
||||
# Manually restart pveproxy
|
||||
ssh root@<proxmox-host> "systemctl restart pveproxy"
|
||||
```
|
||||
|
||||
### Certificate expired
|
||||
Certificates are valid for 10 years by default. To renew:
|
||||
```bash
|
||||
# Simply run the tool again with the same hostname
|
||||
./cert-manager.py
|
||||
# It will generate a new certificate with a fresh validity period
|
||||
```
|
||||
|
||||
## File Locations
|
||||
|
||||
**On local machine:**
|
||||
- Certificate requests: `./<hostname>.req`
|
||||
- Signed certificates: `./<hostname>-cert.pem`
|
||||
- Configuration: `~/.cert-manager-config.json`
|
||||
|
||||
**On target host:**
|
||||
- Private keys: `/tmp/<hostname>.key`
|
||||
- Certificates: `/tmp/<hostname>.crt`
|
||||
|
||||
**On Proxmox hosts:**
|
||||
- Certificate: `/etc/pve/local/pveproxy-ssl.pem`
|
||||
- Private key: `/etc/pve/local/pveproxy-ssl.key`
|
||||
- Backups: `/etc/pve/local/pveproxy-ssl.{pem,key}.bak.YYYYMMDD-HHMMSS`
|
||||
|
||||
## Adding Support for New Systems
|
||||
|
||||
To add automated deployment for a new system type:
|
||||
|
||||
1. Update `detect-system.sh` with detection logic
|
||||
2. Create `deploy-<system>.sh` script
|
||||
3. Add system to `SYSTEM_TYPES` in `cert-manager.py`
|
||||
4. Test thoroughly
|
||||
5. Update this README
|
||||
|
||||
## Additional Resources
|
||||
|
||||
- UCS Manual: https://docs.software-univention.de/
|
||||
- Certificate Management: https://docs.software-univention.de/manual.html#domain:certificates
|
||||
- OpenSSL Documentation: https://www.openssl.org/docs/
|
||||
|
||||
## License
|
||||
|
||||
Internal tool for egonetix infrastructure management.
|
||||
Reference in New Issue
Block a user