hoster

Hoster

A lightweight Go utility that automatically manages /etc/hosts entries for Docker containers. It monitors Docker events and dynamically updates the hosts file with container network information, making it easy to access containers by hostname.

Features

• 🔄 Automatic Updates: Monitors Docker container start/stop events in real-time
• 🌐 Network Awareness: Supports multiple Docker networks and aliases
• 🧹 Clean Shutdown: Removes all entries on graceful exit
• ⚡ Atomic Operations: Uses atomic file writes to prevent corruption
• 🐳 Bridge & Custom Networks: Handles both default bridge and user-defined networks

How It Works

Docker Hoster watches for container lifecycle events and automatically:

1. Extracts container IP addresses from all connected networks
2. Collects container names, hostnames, and network aliases
3. Updates /etc/hosts with mappings in a dedicated section
4. Cleans up entries when containers stop or the service exits

Installation

Prerequisites

• Go 1.16 or higher
• Docker running on the system
• Root/sudo access (required to modify /etc/hosts)

Build from Source

git clone <repository-url>
cd hoster
go mod download
go build -o hoster main.go

Usage

Basic Usage

Run with default settings (requires root):

sudo ./hoster

Command Line Options

View all available options:

./hoster --help

Available flags:

• --help - Display help message and exit
• --hosts <path> - Path to the hosts file (default: /etc/hosts)
• --socket <path> - Path to the Docker socket (default: /var/run/docker.sock)

Example with custom paths:

sudo ./hoster --hosts /custom/hosts --socket /var/run/docker.sock

Running as a Service

The utility runs continuously, monitoring Docker events. It's designed to run as a background service or daemon.

Stopping

Press Ctrl+C or send SIGTERM to gracefully shut down. The service will automatically clean up all hosts file entries before exiting.

Configuration

The utility uses the following defaults:

• Hosts File: /etc/hosts
• Docker Socket: /var/run/docker.sock

You can override these defaults using command line flags:

sudo ./hoster --hosts /custom/hosts --socket /custom/docker.sock

Alternatively, modify the constants in main.go to change the defaults:

const (
    defaultHostsPath = "/etc/hosts"
    defaultSocket    = "/var/run/docker.sock"
)

Hosts File Format

Docker Hoster manages entries in a dedicated section:

# Your existing hosts entries
127.0.0.1    localhost

#-----------Docker-Hoster-Domains----------
172.17.0.2    mycontainer   webapp   abc123
172.18.0.3    database   db   postgres
#-----Do-not-add-hosts-after-this-line-----

⚠️ Warning: Do not manually add entries after the Docker Hoster section marker, as they will be removed.

Example

Start a container with network aliases:

docker network create mynetwork
docker run -d --name webapp --network mynetwork --network-alias api nginx

Docker Hoster will automatically add entries like:

172.18.0.2    webapp   api   abc123def456

You can now access the container:

curl http://webapp
curl http://api

Container Information Collected

For each running container, Docker Hoster extracts:

• Container name (without leading /)
• Container hostname
• Network-specific IP addresses
• Network aliases from all connected networks

Permissions

This utility requires:

• Read/Write access to /etc/hosts
• Read access to Docker socket (/var/run/docker.sock)

Run with sudo or as root to ensure proper permissions.

Signal Handling

• SIGINT (Ctrl+C): Graceful shutdown with cleanup
• SIGTERM: Graceful shutdown with cleanup

On shutdown, all Docker Hoster entries are removed from /etc/hosts.

Architecture

• Docker Client: Uses official Docker Go SDK
• Event Monitoring: Subscribes to Docker events API
• Atomic Writes: Uses auxiliary file + rename for safe updates
• Context Management: Proper cancellation and cleanup

Troubleshooting

Permission Denied

Error: failed to read hosts file: permission denied

Solution: Run with sudo or as root user.

Cannot Connect to Docker

Error: failed to create docker client

Solution: Ensure Docker is running and the socket path is correct.

Entries Not Appearing

Check that:

1. Containers are actually running (docker ps)
2. Containers have network aliases or are on custom networks
3. The utility is running with proper permissions

Development

Project Structure

.
├── main.go       # Main application code
├── go.mod        # Go module dependencies
└── README.md     # This file

Dependencies

• github.com/docker/docker - Docker Engine API client

Building

go build -o hoster main.go

Testing

Test with a simple container:

# Terminal 1: Run hoster
sudo ./hoster

# Terminal 2: Start a container
docker run -d --name test nginx

# Check /etc/hosts
grep test /etc/hosts

License

[Add your license here]

Contributing

Contributions are welcome! Please feel free to submit issues or pull requests.

Author

[Add your name/contact here]