From a8c96a7e2b9a34e4c39803b2079687f7a4a37393 Mon Sep 17 00:00:00 2001 From: Phil Date: Sun, 10 May 2026 12:36:31 +0100 Subject: [PATCH] Updated README.md --- README.md | 193 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 193 insertions(+) diff --git a/README.md b/README.md index 4973f3a..b575f85 100644 --- a/README.md +++ b/README.md @@ -1,2 +1,195 @@ # KeepAliveD-Generator +This project is a **Bash-based automation tool** for generating a complete High Availability (HA) setup using Keepalived VRRP. It supports multiple backup nodes, multiple VIP instances, Systemd service creation, and automatic topology diagram generation. + +--- + +# Overview + +The script interactively builds a full HA stack for a generic service (DNS, API, load balancer, etc.) by generating: + +- Keepalived configuration files (MASTER + multiple BACKUP nodes) +- Systemd service unit file +- A Mermaid-based HA topology diagram + +It is designed to reduce manual configuration errors and speed up HA deployments. + +--- + +# Features + +## Keepalived Configuration Generator +- Generates VRRP instances for multiple VIPs/services +- Supports 1 MASTER + N BACKUP nodes +- Uses unicast VRRP for compatibility across routed networks +- Optional health-check script integration +- Automatic priority assignment for backups + +--- + +## Systemd Integration +- Creates a ready-to-use `keepalived.service` +- Enables auto-start on boot +- Ensures service restart on failure + +--- + +## Architecture Diagram Generator +- Produces a Mermaid diagram (`.md`) +- Visualizes: + - MASTER node + - BACKUP nodes + - VIP failover flow +- Compatible with GitHub, Obsidian, and Mermaid Live Editor + +--- + +# Supported Use Cases + +This generator is **service-agnostic** and can be used for: + +- DNS failover (AdGuard, Unbound, Bind) +- Reverse proxies (Nginx, HAProxy) +- APIs and microservices +- Database VIP failover (MySQL, PostgreSQL) +- Any Linux-based floating IP service + +--- + +# Requirements + +- Linux system (Debian/Ubuntu recommended) +- Bash shell +- Keepalived installed (`keepalived`) +- Root or sudo access + +Install Keepalived: + +``` +sudo apt update +sudo apt install keepalived -y +``` + +# Usage + +* 1. Make script executable +``` +chmod +x generate-keepalived.sh +``` +* 2. Run the generator +``` +./generate-keepalived.sh +``` +What You Will Be Asked + +The script interactively prompts for: + +- Service name +- MASTER node details +- Number of BACKUP nodes +- BACKUP node IPs and IDs +- Number of VIP instances +- Interface names +- VIP addresses +- VRRP IDs +- Authentication passwords +- Optional health-check script + +# Output Files + +After execution, the script generates: + +Keepalived configs +* keepalived--.conf +* keepalived--backupX.conf + +Systemd service +* systemd-/keepalived.service + +Diagram +* -ha-diagram.md + +# Example Architecture + +Clients + │ + ▼ +Virtual IP (VIP) + │ + ┌───────────────┐ + │ MASTER NODE │ + │ BACKUP NODE 1 │ + │ BACKUP NODE 2 │ + └───────────────┘ +# Health Check (Optional) + +If enabled, the script integrates a custom health check: + +Used to detect service failure +* Automatically reduces VRRP priority +Triggers failover to backup nodes + +# Notes +* VRRP uses unicast mode (no multicast dependency) +* Each VIP instance must have a unique VRID +* BACKUP priorities are automatically reduced per node +* Designed for simplicity, scalability, and repeatability + +Limitations +* Does not automatically install Keepalived +* Does not configure network interfaces (VLANs must exist beforehand) +* Requires manual deployment of generated files + +# Future Enhancements + +Planned or possible upgrades: + +* YAML-based configuration input +* Ansible automation support +* Firewall rule generation (VRRP + unicast) +* Prometheus monitoring integration +* Kubernetes-style VIP abstraction layer + +# License + +This script is intended for internal infrastructure automation and can be adapted freely. + +# Disclaimer + +This tool is provided for **infrastructure automation and educational purposes only**. + +It generates configuration files for Keepalived VRRP, Systemd services, and network high-availability setups based on user input. While it is designed to reduce manual configuration errors, it does not guarantee correctness, security, or suitability for any specific production environment. + +## Responsibility + +- You are solely responsible for reviewing, testing, and validating all generated configurations before deployment. +- Incorrect network or VRRP configurations may result in service downtime, split-brain scenarios, or network instability. +- Always test in a **staging or lab environment** before applying to production systems. + +## No Warranty + +This software is provided **“as is”**, without warranty of any kind, express or implied, including but not limited to: + +- Fitness for a particular purpose +- Merchantability +- Non-infringement +- Availability or reliability in production environments + +## Network & Security Considerations + +- VRRP configurations affect network routing and failover behavior. +- Misconfigured priorities, IPs, or authentication values may lead to unintended failovers. +- Health-check scripts executed via Keepalived run with elevated privileges and should be carefully reviewed. + +## Liability + +The author(s) of this tool are not liable for any damages, outages, data loss, or security incidents resulting from its use or misuse. + +## Recommended Practice + +- Always review generated configuration files before deployment. +- Use version control (e.g., Git) to track changes. +- Validate configurations in a controlled environment before production rollout. +- Monitor systems after deployment to ensure expected failover behavior. + +