Skip to main content

Lokales DNS einrichten (*.localhost Domains)

Auf Linux-Systemen funktionieren Subdomain von 'localhost' out-of-the box. Nicht so auf MacOS oder Windows.
Dies liegt daran, dass auf den meisten Linux-Distributionen ein kompakter lokaler DNS-Server als DNS-Cache dient.

Auf den anderen Plattformen kann dies nachgerüstet oder anders gelöst werden werden.

DNS auf OSX

Fertiges Bash script am Ende des Abschnittes

Auf MacOS bietet sich an, dnsmasq via brew nachinstallieren.

Installieren:

dnsmasq kann ganz einfach über brew installiert werden:
brew install dnsmasq

Konfigurieren

Nach der Installation muss dnsmasq noch konfiguriert werden.

Dazu öffnen wir die Config-Datei mit vim /opt/homebrew/etc/dnsmasq.conf
Wir suchen die Zeile #conf-dir=/opt/homebrew/etc/dnsmasq.d,
entfernen die Raute und speichern.
Damit werden configs auch aus dem sub-directory geladen.

Dann legen wir die Datei /opt/homebrew/etc/dnsmasq.d/localhost.conf an und füllen diese mit folgendem Inhalt:

address=/.localhost/127.0.0.1

Der Punkt vor 'localhost' sorgt dafür, dass auch alle Subdomains unter localhost mit beachtet werden.

Als letzten Schritt müssen wir MacOS noch anweisen für die localhost-Domain unseren neuen, lokalen DNS-Server zu nutzen.
Dazu legen wir mit sudo mkdir /etc/resolver das Verzeichnis an, indem der mDNSResponder von MacOS diese erwartet.
Dann legen wir die Datei /etc/resolver/localhost mit Content nameserver 127.0.0.1 an.
Dies sorgt dafür, dass der mDNSResponder von macOS für diese Domain den neuen lokalen DNS-Server beachtet.

Starten

Als Letztes müssen wir nur noch Dnsmasq starten mit sudo brew services start dnsmasq

Jetzt können wir die lokale DNS-Auflösung testen, indem wir testweise einen Query absetzen:
dscacheutil -q host -a name test.docker.localhost

Aufräumen

Final können wir nun alle Zeilen mit docker.localhost aus der /etc/hosts entfernen.

Das Ganze als Bash-Script:

#!/usr/bin/env bash
set -euo pipefail

# setup-local-dns.sh
# Configure dnsmasq on macOS to resolve *.localhost -> 127.0.0.1

HB_PREFIX="/opt/homebrew"
if command -v brew >/dev/null 2>&1; then
  HB_PREFIX=$(brew --prefix)
fi

DNSMASQ_CONF="$HB_PREFIX/etc/dnsmasq.conf"
DNSMASQ_DIR="$HB_PREFIX/etc/dnsmasq.d"
LOCAL_CONF="$DNSMASQ_DIR/localhost.conf"
RESOLVER_DIR="/etc/resolver"
RESOLVER_FILE="$RESOLVER_DIR/localhost"

echo "Homebrew prefix: $HB_PREFIX"

if ! command -v dnsmasq >/dev/null 2>&1; then
  if ! command -v brew >/dev/null 2>&1; then
    echo "Homebrew not found. Please install Homebrew first: https://brew.sh" >&2
    exit 1
  fi
  echo "Installing dnsmasq via brew..."
  brew install dnsmasq
else
  echo "dnsmasq already installed"
fi

echo "Ensuring dnsmasq conf-dir is enabled in $DNSMASQ_CONF"
if [ -f "$DNSMASQ_CONF" ]; then
  if grep -qE '^\s*#\s*conf-dir=.*dnsmasq\.d' "$DNSMASQ_CONF"; then
    sudo sed -i.bak -E 's|^\s*#\s*(conf-dir=.*dnsmasq\.d.*)|\1|' "$DNSMASQ_CONF"
    echo "Uncommented conf-dir line (backup at $DNSMASQ_CONF.bak)"
  elif ! grep -qE '^\s*conf-dir=.*dnsmasq\.d' "$DNSMASQ_CONF"; then
    echo "conf-dir=$DNSMASQ_DIR" | sudo tee -a "$DNSMASQ_CONF" >/dev/null
    echo "Appended conf-dir line to $DNSMASQ_CONF"
  else
    echo "conf-dir already enabled"
  fi
else
  echo "$DNSMASQ_CONF not found — creating with conf-dir"
  sudo mkdir -p "$(dirname "$DNSMASQ_CONF")"
  echo "conf-dir=$DNSMASQ_DIR" | sudo tee "$DNSMASQ_CONF" >/dev/null
fi

echo "Creating $DNSMASQ_DIR and writing $LOCAL_CONF"
sudo mkdir -p "$DNSMASQ_DIR"
echo "address=/.localhost/127.0.0.1" | sudo tee "$LOCAL_CONF" >/dev/null

echo "Ensuring $RESOLVER_DIR exists and writing $RESOLVER_FILE"
if [ ! -d "$RESOLVER_DIR" ]; then
  sudo mkdir -p "$RESOLVER_DIR"
fi
echo "nameserver 127.0.0.1" | sudo tee "$RESOLVER_FILE" >/dev/null

echo "Starting dnsmasq via brew services (may prompt for sudo)..."
sudo brew services start dnsmasq

echo "Testing DNS resolution for test.docker.localhost"
if dscacheutil -q host -a name test.docker.localhost >/dev/null 2>&1; then
  dscacheutil -q host -a name test.docker.localhost
else
  echo "Test query failed or returned no answer. You can still try: dscacheutil -q host -a name test.docker.localhost"
fi

echo "Backing up /etc/hosts and removing lines containing 'docker.localhost'"
sudo cp /etc/hosts "/etc/hosts.backup.dns-$(date +%s)"
sudo sed -i.bak '/docker\.localhost/d' /etc/hosts || true
echo "Done. If you want to revert hosts, restore the backup file created above."

echo "All done. If DNS resolution isn't working, try restarting the mDNSResponder: sudo killall -HUP mDNSResponder"
No Comments
Back to top