Adding license and description
This commit is contained in:
root
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