Adding license and description
This commit is contained in:
root
22
LICENSE
Normal file
22
LICENSE
Normal file
@@ -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.
|
||||||
|
|
||||||
214
README.md
Normal file
214
README.md
Normal file
@@ -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:
|
||||||
|
|
||||||
|
```
|
||||||
|
<IP><TAB><space-separated-domains>
|
||||||
|
```
|
||||||
|
|
||||||
|
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.<TIMESTAMP>`.
|
||||||
|
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/<name>.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.
|
||||||
Reference in New Issue
Block a user