# 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.