From e63e8e790daf8b747d087cd36956477bea1ff66b Mon Sep 17 00:00:00 2001 From: root Date: Fri, 7 Nov 2025 12:58:45 +0000 Subject: [PATCH] Adding license and description --- LICENSE | 22 ++++++ README.md | 214 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 236 insertions(+) create mode 100644 LICENSE create mode 100644 README.md diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..bfa1ec7 --- /dev/null +++ b/LICENSE @@ -0,0 +1,22 @@ +MIT License + +Copyright (c) 2025 sld-server.org + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. + diff --git a/README.md b/README.md new file mode 100644 index 0000000..337b4e5 --- /dev/null +++ b/README.md @@ -0,0 +1,214 @@ +# Host Generator Manager + +> A small Bash utility to manage local `/etc/hosts` entries using an "available / enabled" pattern, local alias management and automatic regeneration with backups. + +--- + +## Table of contents + +1. [What this does](#what-this-does) +2. [Quick start / prerequisites](#quick-start--prerequisites) +3. [Repository / folder layout](#repository--folder-layout) +4. [How it works — concepts](#how-it-works---concepts) +5. [Script usage & examples](#script-usage--examples) +6. [Creating a host file](#creating-a-host-file) +7. [Local aliases](#local-aliases) +8. [Regenerating `/etc/hosts` & backups](#regenerating-etchosts--backups) +9. [Implementation notes](#implementation-notes) +10. [Troubleshooting](#troubleshooting) +11. [Contributing & License](#contributing--license) + +--- + +## What this does + +`generator-hosts.sh` helps you manage `/etc/hosts` entries by keeping individual host definitions in an `hosts-available/` directory and enabling them by creating symlinks in `hosts-enabled/`. The script can regenerate `/etc/hosts` from enabled entries, keeps automatic backups, and supports a small set of "local aliases" (a simple list of alternate names that are added to the `127.0.0.1` line). + +This approach is similar to how some services manage configuration (`sites-available` / `sites-enabled`) and is convenient for toggling different host groups on/off without manually editing `/etc/hosts`. + +## Quick start / prerequisites + +- Tested on systems with Bash (script uses Bash features like arrays and `shopt`). +- You **must run as root** (the script writes `/etc/hosts`). +- Place the script and supporting folders under a single root, the default is: + +``` +/opt/hosts_config/ +``` + +- Make the script executable: + +```bash +chmod +x /opt/hosts_config/generator-hosts.sh +``` + +- Run it as `root` or with `sudo`: + +```bash +sudo /opt/hosts_config/generator-hosts.sh -l +``` + +## Repository / folder layout + +By default the script expects the following layout (variables at the top of the script): + +``` +/opt/hosts_config/ +├─ backups/ # automatic backups of /etc/hosts (hosts.bkp.TIMESTAMP) +├─ hosts-available/ # .conf host definition files (one per host group) +├─ hosts-enabled/ # symlinks to hosts-available to enable them +├─ hosts-main/ # optional: main.conf and endfile.conf (inserted before/after entries) +├─ localhost-aliases/ # .lhost files (first line = alias to add to 127.0.0.1) +└─ generator-hosts.sh # the script +``` + +> Important variables (top of `generator-hosts.sh`) — can be adjusted if you keep the config elsewhere: + +- `ROOTFOLD` — root folder of the configuration (default `/opt/hosts_config`). +- `BKPFOLD` — backups directory. +- `AVFOLD` — hosts-available directory. +- `ENFOLD` — hosts-enabled directory. +- `MAINFOLD` — hosts-main directory (contains `main.conf` and `endfile.conf`). +- `ALIASFOLD` — local aliases directory. + +## How it works — concepts + +- **Hosts available**: Single-file `.conf` entries stored in `hosts-available/`. Each file typically contains a line like: + +``` +192.168.1.10 example.local example.com +``` + +- **Hosts enabled**: Enabling a host creates a symlink in `hosts-enabled/` pointing to the available file. The regeneration reads enabled files in order and appends their contents to `/etc/hosts`. + +- **Local aliases**: Files `*.lhost` inside `localhost-aliases/` are read; the first line of each file is appended as a name to the `127.0.0.1` line (so you can add `myapp.local`, `app.test`, etc.). 0.lhost is used for the base `localhost` entry and the script prevents removing `0.lhost`. + +- **Main and end files**: Optional `main.conf` (inserted after the `127.0.0.1` line) and `endfile.conf` (appended at the end) live in `hosts-main/`. + +- **Backups**: Before writing `/etc/hosts` the script copies the current `/etc/hosts` to `backups/hosts.bkp.TIMESTAMP`. + +## Script usage & examples + +Run the script with one of the supported options (example path adjusted to where the script lives): + +```bash +# List enabled / disabled hosts +sudo /opt/hosts_config/generator-hosts.sh -l + +# Enable a host (interactive index selection) +sudo /opt/hosts_config/generator-hosts.sh -e + +# Disable a host (interactive index selection) +sudo /opt/hosts_config/generator-hosts.sh -d + +# Create a new host file interactively +sudo /opt/hosts_config/generator-hosts.sh -c + +# Regenerate /etc/hosts (writes file and creates backups) +sudo /opt/hosts_config/generator-hosts.sh -r + +# Print a simulation / preview of what would be written +sudo /opt/hosts_config/generator-hosts.sh -s + +# List local aliases +sudo /opt/hosts_config/generator-hosts.sh -hl + +# Add a local alias +sudo /opt/hosts_config/generator-hosts.sh -ha + +# Remove a local alias (cannot remove 0.lhost) +sudo /opt/hosts_config/generator-hosts.sh -hr + +# Show main.conf and endfile.conf +sudo /opt/hosts_config/generator-hosts.sh -sw +``` + +### Non-interactive / scripting notes + +The script is primarily interactive (it reads user input when enabling/disabling or creating entries). If you plan to script interactions, consider calling the underlying file operations yourself (for example creating `.conf` files in `hosts-available/` and symlinking into `hosts-enabled/`), then call the `-r` option to regenerate `/etc/hosts`. + +## Creating a host file (format) + +Each host file in `hosts-available/` is a simple textual `.conf` file. The script writes files created with the `-c` option in the following single-line format: + +``` + +``` + +Examples: + +``` +192.168.1.10 myapp.local myapp.example.com +127.0.0.1 local.test another.local +``` + +The script will use the filename (without `.conf`) as a fallback name if no domains were added during interactive creation. + +## Local aliases + +Place small `.lhost` files inside `localhost-aliases/`. The script reads the first line of each file and appends those names to the `127.0.0.1` hosts entry. Example: + +``` +# file: localhost-aliases/1.lhost +myproject.local +``` + +When regenerating, the first (base) line for loopback becomes: + +``` +127.0.0.1 localhost myproject.local anotheralias +``` + +The script prevents deleting `0.lhost` (index 0) via the remove operation because that file is treated as the system localhost line. + +## Regenerating `/etc/hosts` & backups + +- `-r` or `regenerate_hosts` will: + 1. Build a temporary hosts file from `127.0.0.1` line + `hosts-main/main.conf` (if present) + enabled hosts + `hosts-main/endfile.conf`. + 2. Copy the current `/etc/hosts` into `backups/hosts.bkp.`. + 3. Move the generated temporary file to `/etc/hosts` and set `chmod 644`. + +Backups are stored in the `backups/` directory under the configured `ROOTFOLD`. + +## Implementation notes & internals + +- The script uses arrays and `shopt -s nullglob` for safe globbing. +- `refresh_arrays()` re-populates all arrays used by the interactive commands (available/enabled/aliases). +- The `create_host()` function validates filename characters and IP string presence but does not validate IP syntax strictly — if you want strict validation you may add an IP regex check or use `ipcalc`. +- Host enable/disable operations are implemented by creating and removing symlinks inside `hosts-enabled/`. + +## Troubleshooting + +- **/etc/hosts not updated**: Ensure you run the script as root. Check that backups exist under `backups/` and inspect the temporary file created by `_build_hosts_file` using the `-s` (simulate) option. + +- **Host file not applied**: Check the enabled symlink exists in `hosts-enabled/` and points to the correct `hosts-available/.conf` file. + +- **Aliases not appearing**: Ensure each `.lhost` file contains the alias on the first line. Run `-s` to preview results. + +- **Permissions**: `/etc/hosts` is set to `644` after writing; adjust if your environment requires different permissions. + +## Contributing + +If you want to add features or fix bugs: + +1. Fork the repository (or copy the folder). +2. Make changes and test carefully — the script writes system `hosts` so test in a safe environment or VM. +3. Send pull requests or patches with a clear description of the change. + +Suggested improvements: + +- Add strict IP validation when creating host files. +- Add a non-interactive mode for bulk enabling/disabling. +- Add an option to preview diffs between current `/etc/hosts` and the generated file prior to writing. + +## License + +This README and the accompanying `generator-hosts.sh` are provided under the MIT license. + +--- + +If you'd like, I can also: + +- generate a compact `CONTRIBUTING.md` or `CHANGELOG.md`, +- add inline comments inside `generator-hosts.sh` to explain each function, +- or convert this README to Italian.