212 lines
8.2 KiB
Markdown
212 lines
8.2 KiB
Markdown
# 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
|
|
sudo chmod +x /opt/hosts_config/generator-hosts.sh
|
|
sudo ln -s /opt/hosts_config/generator-hosts.sh /usr/local/sbin/generator-hosts
|
|
```
|
|
|
|
- Run it as `root` or with `sudo`:
|
|
|
|
```bash
|
|
sudo generator-hosts -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 generator-hosts -l
|
|
|
|
# Enable a host (interactive index selection)
|
|
sudo generator-hosts -e
|
|
|
|
# Disable a host (interactive index selection)
|
|
sudo generator-hosts -d
|
|
|
|
# Create a new host file interactively
|
|
sudo generator-hosts -c
|
|
|
|
# Regenerate /etc/hosts (writes file and creates backups)
|
|
sudo generator-hosts -r
|
|
|
|
# Print a simulation / preview of what would be written
|
|
sudo generator-hosts -s
|
|
|
|
# List local aliases
|
|
sudo generator-hosts -hl
|
|
|
|
# Add a local alias
|
|
sudo generator-hosts -ha
|
|
|
|
# Remove a local alias (cannot remove 0.lhost)
|
|
sudo generator-hosts -hr
|
|
|
|
# Show main.conf and endfile.conf
|
|
sudo generator-hosts -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.
|
|
|
|
---
|