dnshelper/README.md

# dns-helper

A cross-platform CLI tool that resolves hostnames against a specified DNS server and writes the resulting IP-to-hostname mappings into the local hosts file. It manages a clearly delimited block within the hosts file so it can cleanly add and remove only its own entries.

Built as a single static binary with no runtime dependencies.

**Copyright (c) 2024 Emberkom LLC**

## Features

- Resolve one or more hostnames via a specified DNS server and add them to the system hosts file
- Remove individual hostnames or all managed entries from the hosts file
- Managed block markers ensure only dns-helper's entries are modified — the rest of the hosts file is never touched
- Automatic backup of the hosts file before every write (stored alongside the executable)
- File-based lock prevents concurrent modifications
- Cross-platform: Windows, macOS, and Linux

## Requirements

- **Go 1.20** toolchain (this project must not use Go 1.21+ features)
- Administrator / root privileges (required to modify the system hosts file)

## Installation

### Build from source

```powershell
# Clone the repository
git clone <repo-url>
cd dns-helper

# Build for the current platform
.\build.ps1

# Or build optimized release binaries for all platforms
.\build.ps1 -Release -CrossCompile
```

The default build output is `build\dns-helper.exe` (Windows). Cross-compiled binaries are named `build\dns-helper-<os>-<arch>[.exe]`.

### Release packages

```powershell
# Build release binaries and create distributable archives
.\build.ps1 -Release -CrossCompile -Package
```

Archives are written to `releases\dns-helper-<version>-<os>-<arch>.zip` (Windows) or `.tar.gz` (macOS/Linux).

## Usage

> **Note:** dns-helper must be run with elevated privileges (Run as Administrator on Windows, `sudo` on macOS/Linux) because it modifies the system hosts file.

### Add entries

Resolve hostnames via a DNS server and add the resulting IP mappings to the hosts file:

```sh
dns-helper add -host hostname.example.com -server dns.example.com
```

Add multiple hostnames at once (comma-separated):

```sh
dns-helper add -host "host1.example.com,host2.example.com" -server dns.example.com
```

Short alias:

```sh
dns-helper a -host hostname.example.com -server dns.example.com
```

### Delete entries

Remove a specific hostname:

```sh
dns-helper delete -host hostname.example.com
```

Remove multiple hostnames:

```sh
dns-helper delete -host "host1.example.com,host2.example.com"
```

Remove **all** managed entries:

```sh
dns-helper delete all
```

Short aliases: `d`, `del`

### Command reference

| Command | Flag | Required | Description |
|---------|------|----------|-------------|
| `add` | `-host` | Yes | Comma-separated hostnames to resolve and add |
| `add` | `-server` | Yes | DNS resolver to query (e.g. `dns.example.com`) |
| `delete` | `-host` | Yes (unless `all`) | Comma-separated hostnames to remove |
| `delete all` | — | — | Removes every entry dns-helper has written |

### Exit codes

| Code | Meaning |
|------|---------|
| 0 | Success |
| 1 | Error or partial failure (e.g. one hostname failed to resolve) |

## How it works

dns-helper wraps its entries between two marker lines in the hosts file:

```
# DNSHelper <<-> START CONFIG
192.0.2.1	hostname.example.com
# DNSHelper <->> END CONFIG
```

Only lines within this managed block are ever modified or removed. The rest of the hosts file is preserved exactly as-is.

Before every write, a backup of the hosts file is saved to the directory containing the dns-helper executable.

### Hosts file locations

| Platform | Path |
|----------|------|
| Windows | `%SystemRoot%\System32\drivers\etc\hosts` |
| macOS | `/etc/hosts` |
| Linux | `/etc/hosts` |

## Project structure

```
main.go              CLI entry point (add / delete commands, flag parsing)
build.ps1            Build & packaging script
go.mod               Module definition (Go 1.20, golang.org/x/net)
hostfile/
  hostfile.go        Hosts file parsing, DNSEntry type, add/remove helpers
  managed.go         Managed block read/write logic
  filesystem.go      FileSystem interface + OSFileSystem implementation
  hostfile_test.go
  managed_test.go
lockfile/
  lockfile.go        File-based mutex to prevent concurrent modifications
  lockfile_test.go
platform/
  platform.go             Platform interface — GetHostsFilePath()
  platform_windows.go     Windows implementation
  platform_darwin.go      macOS implementation
  platform_linux.go       Linux implementation
  platform_test.go
resolver/
  resolver.go        DNS resolution via golang.org/x/net/dns/dnsmessage
  resolver_test.go
```

## Development

### Running tests

```sh
go1.20 test ./...
```

### Running tests with coverage

```sh
go1.20 test -cover ./...
```

### Vetting code

```sh
go1.20 vet ./...
```

## Dependencies

- [`golang.org/x/net`](https://pkg.go.dev/golang.org/x/net) — DNS message parsing (`golang.org/x/net/dns/dnsmessage`)

No other third-party dependencies. Standard library first.

## License

Copyright (c) 2024 Emberkom LLC. All rights reserved.