Category: System administration, Databases, Messaging and Security

Implementing Per-Domain DNS Configuration on Linux Ubuntu Using dnsmasq

Reading time: 41 – 68 minutes

In Linux, managing network traffic is essential for a robust and secure IT infrastructure. In this post, we focus on Ubuntu—whether running on a virtual machine, Windows Subsystem for Linux (WSL), or a physical machine running Ubuntu 24.04. We will configure per-domain DNS rules using dnsmasq. This guide also covers additional considerations for WSL and systems using netplan.

Configuring Ubuntu for Local DNS with dnsmasq

When using Ubuntu, you might be using netplan for network configuration. In that case, you need to configure netplan to use the local DNS server provided by dnsmasq. Make sure your netplan configuration (e.g., /etc/netplan/01-netcfg.yaml) sets the DNS to 127.0.0.1, so that all DNS queries are forwarded to your local dnsmasq server.

Disabling systemd-resolved

Ubuntu often uses systemd-resolved by default, which can interfere with your custom DNS setup. To prevent conflicts, disable and stop systemd-resolved using the following commands:

sudo systemctl disable systemd-resolved
sudo systemctl stop systemd-resolved
sudo systemctl daemon-reload

This ensures that systemd-resolved does not override your DNS settings.

Note for WSL Users

If you are running Ubuntu under WSL, you need to prevent WSL from overwriting your DNS settings. Edit or create the file /etc/wsl.conf with the following content:

[network]
generateResolvConf = false

Then, create or edit the /etc/resolv.conf file to include:

nameserver 127.0.0.1

This ensures that your system uses the local dnsmasq server.

Installing and Setting Up dnsmasq

Step 1: Install dnsmasq

First, update your package list and install dnsmasq:

sudo apt update
sudo apt install dnsmasq

Step 2: Enable and Verify the dnsmasq Service

After installing dnsmasq, enable the service and check its status to ensure it is running correctly:

sudo systemctl enable dnsmasq
sudo systemctl daemon-reload
sudo systemctl start dnsmasq
sudo systemctl status dnsmasq

You should see that dnsmasq is active and running. This local DNS server will be used to resolve all DNS queries forwarded from your system.

Step 3: Configure dnsmasq

Edit the /etc/dnsmasq.conf file to set up your DNS rules. Here’s an example configuration:

# Default upstream DNS servers
server=8.8.8.8
server=8.8.4.4

# Domain-specific DNS servers
server=/domain01.tld/172.30.0.1
server=/domain02.tld/172.30.0.2

Explanation:

  • The lines server=8.8.8.8 and server=8.8.4.4 set Google’s public DNS as the default upstream DNS servers. When a query does not match any domain-specific rule, dnsmasq will forward the request to these servers.
  • The lines server=/domain01.tld/172.30.0.1 and server=/domain02.tld/172.30.0.2 specify that queries for any host within domain01.tld and domain02.tld should be resolved by the DNS servers at 172.30.0.1 and 172.30.0.2, respectively.

After making your changes, save the file and restart dnsmasq to apply the new configuration:

sudo systemctl restart dnsmasq

Verifying the DNS Configuration

You can use the dig command to verify that your DNS rules are working as expected. Note that when your system’s resolver is set to use dnsmasq at 127.0.0.1, the dig output will always show SERVER: 127.0.0.1#53. However, dnsmasq will forward the query internally to the appropriate upstream DNS server based on your configuration.

Below are two examples: one for a public domain (google.com) and one for a domain that should be resolved by your custom DNS rule (example01.tld).

Example 1: Verifying a Public Domain (google.com)

Run the following command:

dig google.com

Simulated Output:

; <<>> DiG 9.11.3-1ubuntu1-Ubuntu <<>> google.com
;; global options: +cmd
;; Got answer:
;; ->>HEADER<<- opcode: QUERY, status: NOERROR, id: 12345
;; flags: qr rd ra; QUERY: 1, ANSWER: 2, AUTHORITY: 0, ADDITIONAL: 1
;; QUESTION SECTION:
;google.com.                    IN      A
;; ANSWER SECTION:
google.com.             300     IN      A       172.217.164.110
google.com.             300     IN      A       172.217.164.78
;; Query time: 23 msec
;; SERVER: 127.0.0.1#53(127.0.0.1)
;; WHEN: Wed Feb 20 10:00:00 UTC 2025
;; MSG SIZE  rcvd: 113

Internal Process:

  • Step 1: The query for google.com is sent to the local dnsmasq server at 127.0.0.1.
  • Step 2: dnsmasq examines its configuration and sees that google.com does not match any domain-specific rules.
  • Step 3: It then forwards the query to the default upstream DNS servers (8.8.8.8 and 8.8.4.4).
  • Step 4: The upstream server resolves google.com and returns the result back to dnsmasq, which then passes it back to the client.

Example 2: Verifying a Domain with a Custom DNS Rule (example01.tld)

Run the following command:

dig example01.tld

Simulated Output:

; <<>> DiG 9.11.3-1ubuntu1-Ubuntu <<>> example01.tld
;; global options: +cmd
;; Got answer:
;; ->>HEADER<<- opcode: QUERY, status: NOERROR, id: 67890
;; flags: qr rd ra; QUERY: 1, ANSWER: 1, AUTHORITY: 0, ADDITIONAL: 1
;; QUESTION SECTION:
;example01.tld.               IN      A
;; ANSWER SECTION:
example01.tld.           60      IN      A       172.30.0.1
;; Query time: 25 msec
;; SERVER: 127.0.0.1#53(127.0.0.1)
;; WHEN: Wed Feb 20 10:00:10 UTC 2025
;; MSG SIZE  rcvd: 82

Internal Process:

  • Step 1: The query for example01.tld is sent to dnsmasq at 127.0.0.1.
  • Step 2: dnsmasq checks its configuration and finds a matching domain-specific rule for example01.tld, which directs the query to the DNS server at 172.30.0.1.
  • Step 3: dnsmasq forwards the query internally to 172.30.0.1 without exposing this step in the client’s dig output.
  • Step 4: The upstream server at 172.30.0.1 resolves the query, and dnsmasq returns the answer to the client.

In both cases, while the client sees the query being handled by 127.0.0.1, dnsmasq intelligently directs the queries to the appropriate upstream servers based on your configuration. This seamless internal forwarding is what allows you to manage per-domain DNS resolution effectively.

Conclusion: Why Use Per-Domain DNS Configuration?

Implementing per-domain DNS configuration on Linux Ubuntu is a powerful way to gain granular control over your network’s behavior. This approach is particularly useful for:

  • Enterprise Environments: Where internal domains require different DNS resolutions from external queries.
  • Development and Testing: Allowing developers to redirect domain requests to local or test servers.
  • Security: Enhancing network security by segregating traffic and reducing reliance on external DNS servers.

By configuring dnsmasq with domain-specific rules and ensuring that your system points to the local DNS (especially important when using netplan or running under WSL), you optimize network performance and security tailored to your specific needs.

Gestión de certificados (PKI) – easy-rsa

Reading time: 51 – 85 minutes

Serie

  1. Gestión de certificados (PKI) – easy-rsa
  2. MQTT Broker (Mosquitto) con certificado servidor (self-signed)
  3. MQTT Broker (Mosquitto) con certificado servidor (self-signed) y certificado en los clientes
  4. MQTT Broker (Mosquitto) con certificado servidor (Let’s Encrypt)
  5. Formatos de Certificados: PEM, DER y PKCS#12 y Manipulación de Claves Privadas

Introducción a la Infraestructura de Clave Pública (PKI)

Una PKI, o Infraestructura de Clave Pública, es un sistema que gestiona certificados digitales y claves para garantizar comunicaciones seguras. Vamos a desglosar los conceptos básicos.

Conceptos Clave

  • PKI: Es el sistema completo que conecta Certificados de Autoridad (CA), claves y certificados para garantizar la confianza entre entidades.
  • CA (Certificate Authority): Es el “jefe” de la PKI. Firma y valida certificados, garantizando que son de confianza.
  • Certificado: Documento digital que incluye una clave pública, información sobre la entidad, y la firma del CA. Es como un pasaporte digital.
  • Solicitud de Certificado: Es un “borrador” del certificado que una entidad envía al CA para que lo firme.
  • Par de Claves (Keypair): Un conjunto de dos claves: una pública (para compartir) y otra privada (secreta). Por ejemplo, la pública es como tu dirección de correo y la privada como la contraseña.

¿Qué es un CA y por qué es importante?

El CA es el núcleo de una PKI y su clave privada es extremadamente sensible porque firma todos los certificados. Para protegerla, se recomienda mantenerla en un entorno seguro, como un sistema dedicado o incluso desconectado de la red.

¿Cómo funciona todo esto?

  1. Creación del CA: Se genera un par de claves y la estructura necesaria para gestionar certificados.
  2. Solicitud de Certificado: Un cliente (por ejemplo, un servidor VPN) crea un par de claves y envía su solicitud al CA.
  3. Firma y Certificado: El CA verifica la solicitud y utiliza su clave privada para firmar el certificado, que luego devuelve al cliente.

¿Cómo se verifica un certificado? Ejemplos prácticos

La verificación de certificados varía según el contexto, y quiero explicarlo con dos ejemplos claros: una conexión a una VPN, donde yo tengo un par de claves y un certificado, y una conexión a un banco, donde no necesito un par de claves, solo la confianza en la CA.

Ejemplo 1: Conexión VPN (yo tengo mi par de claves y certificado)

Cuando me conecto a una VPN, tanto el cliente como el servidor necesitan un par de claves (pública y privada) y certificados firmados por la misma CA. El proceso es el siguiente:

  1. Yo genero mi par de claves y solicito un certificado al CA, que verifica mi identidad y firma mi certificado.
  2. Cuando intento conectar al servidor VPN, este me presenta su certificado.
  3. Yo verifico que el certificado del servidor fue firmado por el CA en el que confío.
  4. Luego, envío mi propio certificado al servidor, que hace la misma verificación con su copia del CA.
  5. Si todo es válido, ambos usamos nuestras claves privadas para intercambiar información cifrada y establecer una conexión segura.

Por ejemplo, si trabajo remotamente y necesito acceder a la red de mi empresa, configuro un cliente VPN con mi certificado y claves. El servidor verifica que yo soy quien digo ser y me deja entrar solo si la verificación es correcta.

Ejemplo 2: Conexión a un banco (sin par de claves, solo confianza en la CA)

Cuando accedo a la web de mi banco desde mi navegador, no necesito un par de claves personal. Simplemente, confío en los certificados emitidos por las CA incluidas en la lista de confianza de mi navegador. Así funciona:

  1. El servidor del banco me envía su certificado.
  2. Mi navegador verifica que el certificado fue firmado por una CA en su lista de confianza y que este no está caducado ni revocado.
  3. Si la verificación es exitosa, se establece una conexión segura mediante TLS/SSL.
  4. Durante la conexión, el banco usa su clave privada para demostrar que es legítimo, firmando datos que mi navegador valida con la clave pública incluida en el certificado del banco.

Por ejemplo, cuando accedo a https://mi-banco.com, mi navegador me muestra un candado en la barra de direcciones. Esto significa que ha validado el certificado del banco y ahora la conexión es segura. Aunque yo no tengo claves en este caso, confío en la autoridad que firmó el certificado del banco.

Vamos a crear nuestra propia PKI y la gestión de certificados usando easy-rsa

Easy-RSA es una herramienta poderosa y sencilla para gestionar una infraestructura PKI (Infraestructura de Clave Pública). Con ella puedo emitir certificados para servidores VPN, páginas web, y clientes que necesiten conexiones seguras. Aquí explicaré cómo utilizar Easy-RSA para construir esta infraestructura y cómo interpretar sus resultados.

Importante mencionar que easy-rsa no son más que unos scripts que simplifican el uso de OpenSSL que es la verdadera herramienta que hay por detrás gestionando los certificados, claves y demás.

Obtener easy-rsa:

git clone https://github.com/OpenVPN/easy-rsa.git

Configuración del archivo vars en Easy-RSA

El archivo vars permite configurar parámetros básicos y avanzados antes de iniciar el PKI con init-pki, ahorrando tiempo y garantizando consistencia. Para empezar, copio vars.example a vars y relleno las partes que me interesen, como:

  • Datos del certificado: País, ciudad, organización, etc.
  • Claves y algoritmos: Tamaño (2048 bits) y tipo (RSA o EC).
  • Duración: Expiración de la CA y certificados.
set_var EASYRSA_REQ_COUNTRY "ES"
set_var EASYRSA_REQ_ORG "MiEmpresa"
set_var EASYRSA_KEY_SIZE 2048
set_var EASYRSA_CA_EXPIRE 3650
set_var EASYRSA_CERT_EXPIRE 825

Paso 1: Preparar Easy-RSA

Primero, descargo Easy-RSA desde su repositorio oficial. Como no requiere instalación, simplemente extraigo el archivo comprimido (.tar.gz para Linux/Unix o .zip para Windows) en el directorio que prefiera.

Para comenzar, inicializo el directorio de PKI con:

./easyrsa init-pki

Esto crea una estructura de directorios básica para gestionar los certificados. El directorio pki incluye:

  • private/: Guarda claves privadas (debe mantenerse muy seguro).
  • reqs/: Contiene solicitudes de certificados.
  • issued/: Almacena certificados emitidos.
  • ca.crt: El certificado de la CA (Autoridad Certificadora).
  • private/ca.key: La clave privada de la CA, crítica para la seguridad de toda la infraestructura.

Paso 2: Crear la Autoridad Certificadora (CA)

La CA es el corazón de mi PKI. Es quien firma los certificados y garantiza su validez. Creo la CA con:

./easyrsa build-ca

Durante este proceso, defino un nombre común (Common Name, CN) para identificar mi CA, y se me pedirá configurar una frase de contraseña fuerte para proteger la clave privada (ca.key). Este archivo es extremadamente sensible, y su seguridad es crítica.

El resultado principal de este paso es:

  • ca.crt: El certificado público de la CA, que compartiré con clientes y servidores para verificar certificados.

Paso 3: Generar claves y solicitudes de certificados

Para que un cliente o servidor VPN funcione, primero genero un par de claves (privada y pública) junto con una solicitud de certificado (CSR). Esto se hace con:

./easyrsa gen-req <nombre-del-certificado|FQDN>
# muy importante usar FQDN (Fully Qualified Domain Names) para evitar
# problemas de matching con los hostnames usados en la conexión.

Por ejemplo, para un servidor VPN:

./easyrsa gen-req vpn-server.example.tld

El comando genera dos archivos:

  1. private/<nombre-del-certificado>.key: La clave privada. Este archivo debe permanecer en el servidor o cliente correspondiente y nunca compartirse.
  2. reqs/<nombre-del-certificado>.req: La solicitud de certificado (CSR). Este archivo se envía al CA para ser firmado.

Paso 4: Firmar solicitudes de certificados

Una vez que tengo la solicitud (.req), la importo en el CA y la firmo. Esto se realiza con:

1. Importar la solicitud

# solo hay que hacer este paso si el certificate request 
# lo hemos copiado de otra máquina. Esto lo coloca en path
# para que todo vaya automático, incluidas futuras 
# renovaciones.
./easyrsa import-req /the-path/vpn-server.example.tld.req vpn-server.example.tld

2. Firmar la solicitud

./easyrsa sign-req server vpn-server.example.tld

Easy-RSA generará un certificado firmado en pki/issued/servidor-vpn.crt. Este archivo es lo que el servidor VPN utiliza para identificarse de forma segura ante sus clientes.

Paso 5: Configuración de un servidor y cliente VPN

Servidor VPN

Para configurar un servidor VPN (como OpenVPN), necesitaré los siguientes archivos generados por Easy-RSA:

  1. Clave privada (private/servidor-vpn.key): Usada por el servidor para encriptar las comunicaciones.
  2. Certificado firmado (issued/servidor-vpn.crt): Garantiza que el servidor es confiable.
  3. Certificado de la CA (ca.crt): certificado y clave pública de nuestra PKI.

Estos archivos se colocan en el directorio de configuración del servidor VPN y se referencian en su configuración.

Cliente VPN

Hay que repetir el paso 4, en este caso una buena práctica es poner como “nombre-del-certificado” el nombre del usuario, o el cliente, que pide el certificado de acceso. En algunos casos de uso, eso permite no tener que pasar por un proceso de autenticación.

Después de generar la petición y haberla importado, como indica la primera parte del paso 5. Hay que ir muy en cuidado con el segundo paso. Al firmar el certificate request hay que hacerlo indicando que su uso será de cliente, no de servidor.

# creamos el certificate request
./easyrsa gen-req mi-nombre-de-usuario

# importamos el certificado si es necesario en la PKI
./easyrsa import-req /the-path/mi-nombre-de-usuario.req mi-nombre-de-usuario

# firmamos el certificate request indicando el uso como cliente
./easyrsa sign-req client mi-nombre-de-usuario

Después de firmar el certificate-request ya tenemos los ficheros que deberá usar el cliente para conectarse al servidor:

  1. Clave privada (private/mi-nombre-de-usuario.key): Usado por el cliente para encriptar las comunicaciones.
  2. Certificado firmado (issued/mi-nombre-de-usuario.crt): Garantiza que el servidor es confiable.
  3. Certificado de la CA (ca.crt): certificado y clave pública de nuestra PKI.

NOTA:

Cuando se firma un certificado las posibles opciones a seleccionar son:

  • client – es para TLS client, típicamente usado para usuarios de VPN, o para navegadores Web
  • server – para TLS server, típicamente servidores Web y servidores VPN.
  • ca – cuando queremos crear CA (Certificate Authorities) en cascada, esto emite un certificado intermedio. Técnicamente, lo llaman chaining certificate.
  • serverClient – certificado que serve tanto para cliente como para servidor TLS.

Paso 6: Configuración para servidores web

El proceso es similar para un servidor web (HTTPS). Genero una solicitud de certificado para el dominio del servidor (por ejemplo, mi-servidor.com) y la firmo con la CA. Los archivos necesarios serán:

  1. Clave privada (private/mi-servidor.key): Exclusiva del servidor web.
  2. Certificado firmado (issued/mi-servidor.crt): Identifica al servidor web.
  3. Certificado de la CA (ca.crt): Permite a los navegadores validar la conexión.

Estos archivos se configuran en el servidor web (como Apache o Nginx) para habilitar HTTPs.

Gestión de certificados emitidos, CRL y Validación en Tiempo Real con OCSP

Easy-RSA no solo permite emitir y revocar certificados, sino que también facilita la gestión de la revocación mediante la generación de listas de certificados revocados (CRL) y la implementación de validación en tiempo real a través de OCSP. Cuando se detecta que una clave privada ha sido comprometida o un certificado ya no es necesario, se procede a su revocación:

  1. Revocar un certificado:
    Utiliza el comando: ./easyrsa revoke <nombre-del-certificado> Esto marca el certificado como revocado dentro de la base de datos de la PKI.
  2. Generar la CRL:
    Una vez revocados los certificados, es necesario generar una nueva lista de revocación. Esto se realiza con: ./easyrsa gen-crl Este comando genera dos ficheros:
    • crl.pem: La CRL en formato Base64.
    • crl.der: La CRL en formato binario.
      Estos archivos deben publicarse en un servidor accesible para que los clientes puedan descargarlos y comprobar el estado de los certificados.

Aunque la CRL es la solución tradicional para gestionar certificados revocados, presenta limitaciones como el tamaño de la lista y la necesidad de descargarla por completo en cada comprobación. Para solventar estas deficiencias, se puede implementar OCSP (Online Certificate Status Protocol).

OCSP es un protocolo definido en el RFC 2560 que permite a un cliente consultar el estado de un certificado de forma puntual y en tiempo real, sin tener que procesar toda la CRL. Entre sus ventajas destacan:

  • Información actualizada: Permite obtener el estado de revocación de un certificado al momento de la consulta.
  • Eficiencia: Reduce el tráfico y la carga de procesamiento en el cliente, ya que se consulta solo el certificado específico.
  • Privacidad: Evita la exposición de información potencialmente sensible contenida en la CRL.
  • Escalabilidad: Emplea mecanismos optimizados (a menudo basados en motores de base de datos) para gestionar consultas incluso en entornos con un gran número de certificados.

Implementación de un Servidor OCSP con OpenSSL:

Para poner en marcha un servidor OCSP, utiliza el siguiente comando:

openssl ocsp -index /ruta/a/tu/index.txt -port 2560 -ignore_err -rsigner /ruta/a/tu/ocsp.crt -rkey /ruta/a/tu/ocsp.key -CA /ruta/a/tu/ca.crt -text -out /ruta/a/tu/log_ocsp.txt &

Donde:

  • -index indica el archivo que contiene el índice de certificados emitidos.
  • -port define el puerto en el que el servidor OCSP escuchará (en este ejemplo, 2560).
  • -ignore_err permite que el servidor continúe operando incluso si recibe peticiones malformadas.
  • -rsigner y -rkey especifican el certificado y la clave privada del OCSP responder.
  • -CA señala el certificado de la CA emisora.
  • -text -out guarda un log detallado de las operaciones.

Para consultar el estado de un certificado (por ejemplo, newcert.pem), ejecuta:

openssl ocsp -CAfile /ruta/a/tu/ca.crt -issuer /ruta/a/tu/ca.crt -cert newcert.pem -url http://tu-dominio:2560 -resp_text

Esta consulta permite verificar de forma inmediata si el certificado está revocado o sigue siendo válido.

Integrar la generación y publicación de CRL con un servidor OCSP proporciona un mecanismo completo para la gestión de certificados emitidos. Mientras que la CRL ofrece una solución tradicional basada en la descarga de una lista completa, OCSP permite a los clientes obtener el estado de un certificado de forma ágil y en tiempo real, optimizando el proceso de validación y reduciendo la carga en la red. Este enfoque combinado asegura que, tanto en entornos de pruebas como en producción, se disponga de mecanismos robustos para mantener la integridad y seguridad de la infraestructura PKI.

Renovar un certificado

Normalmente, poco antes de caducar un certificado se pide su renovación. Esto emitirá otro fichoero de certificado firmado por la CA como el que se emetió la primera vez, pero con una nueva fecha de caducidad:

./easyrsa renew <nombre-del-certificado>

una vez generado el nuevo certificado en:

  • issued/mqtt.example.tld.crt – certificado renovado

es buena idea ejecutar el siguiente comando para asegurarse que el viejo certificado queda obsoleto:

./easyrsa revoke-renewed <nombre-del-certificado>

esto nos acaba forzando a generar una nueva lista de certificados revocados. O sea, hay que ejecutar:

./easyrsa gen-crl

y en consecuencia distribuir el nuevo fichero CRL.

Conclusión

Easy-RSA simplifica la creación y gestión de una infraestructura PKI, lo que me permite emitir y administrar certificados para VPNs y servidores web. Sus outputs, como las claves privadas, certificados firmados, y el certificado de la CA, son los componentes esenciales para garantizar conexiones seguras. Con esta herramienta, puedo construir mi propia red confiable para asegurar tanto servidores como clientes en diferentes escenarios.

Referencias

WireGuard Over TCP Using udp2raw: Securing and Expanding Connectivity – Point-to-Multipoint – CookBook

Reading time: 76 – 126 minutes

Scenario Overview

The architecture for this setup is illustrated below:

Install udp2raw, Wireguard and generate keys

cd /tmp
wget https://github.com/wangyu-/udp2raw/releases/download/20230206.0/udp2raw_binaries.tar.gz
tar xvfz udp2raw_binaries.tar.gz
cp udp2raw_amd64 /usr/local/bin/udp2raw
rm udp2raw*
# based on Ubuntu
apt install wireguard
# we'll work on /etc/wireguard
cd /etc/wireguard
# generate privatekey
wg genkey | sudo tee /etc/wireguard/private.key
sudo chmod go= /etc/wireguard/private.key
# obtain public key
sudo cat /etc/wireguard/private.key | wg pubkey | sudo tee /etc/wireguard/public.key

When eveything is installend and configured, just run in all endpoints next commands:

sudo wg-quick up wg0
# for status check:
wg
# udp2raw logs at:
tail -f /var/log/udp2raw.log
# enable automatic wireward service in Ubuntu
sudo systemctl enable wg-quick@wg0.service
# start and stop service like always
sudo systemctl start wg-quick@wg0.service
sudo systemctl stop wg-quick@wg0.service
sudo systemctl status wg-quick@wg0.service

Configuration Files

Endpoint A /etc/wireguard/wg0

# local settings for Endpoint A
[Interface]
PrivateKey = WMUerfcUpSxUlOp1UmaS2uwelnk8AxhAFrlIWpjheWM=
Address = 192.168.111.1/24
ListenPort = 51822

# receive wg through udp2raw
MTU = 1342
PreUp = udp2raw -s -l 167.99.130.97:55055 -r 127.0.0.1:51822 -k "The2password." -a >/var/log/udp2raw.log 2>&1 &
PostDown = killall udp2raw || true

# Enable NAT for traffic forwarding (corporate and fallback internet access)
PreUp = echo 1 > /proc/sys/net/ipv4/ip_forward || true
PreUp = iptables -t nat -I POSTROUTING -o eth0 -j MASQUERADE || true
PreDown = iptables -t nat -D POSTROUTING -o eth0 -j MASQUERADE || true

# remote settings for Endpoint B
[Peer]
PublicKey = XWl8HeAinHlAZTvaCXDlmO9n/CQLg5qH8jmtROK4jBg=
AllowedIPs = 192.168.111.2/32
PersistentKeepalive = 120

# remote settings for Endpoint C
[Peer]
PublicKey = I+gi8l9QRe00W8pTpp8CSoIabz/RXXQXwquXj7eKNwU=
AllowedIPs = 192.168.111.3/32
PersistentKeepalive = 120

Endpoint B /etc/wireguard/wg0

# Endpoint B
[Interface]
PrivateKey = +BB3NI2SUYeKcRoPrZE2+Ot5KnLZJBycPzJ17kfbn34=
Address = 192.168.111.2/24

# Route configuration for public IP
PreUp = ip route del default || true
PreUp = ip route add 167.99.130.97 via 10.2.0.1 dev eth0 || true
PostDown = ip route del 167.99.130.97 via 10.2.0.1 dev eth0 || true
PostDown = ip route add default via 10.2.0.1 || true

MTU = 1342
PreUp = udp2raw -c -l 127.0.0.1:50001 -r 167.99.130.97:55055 -k "The2password." -a >/var/log/udp2raw.log 2>&1 &
PostDown = killall udp2raw || true

# Endpoint A
[Peer]
PublicKey = z73wM1b7fhMRA8fmeQw4FntRvgJ9JwTdsQHssXHg3DE=
Endpoint = 127.0.0.1:50001
AllowedIPs = 0.0.0.0/0
PersistentKeepalive = 120

Endpoint C /etc/wireguard/wg0

# Endpoint C
[Interface]
PrivateKey = YCGzsfeed8QumpfE8bdWRheMzBiUsTB7vXj0YVOQQX0=
Address = 192.168.111.3/24

# Route configuration for public IP
PreUp = ip route del default || true
PreUp = ip route add 167.99.130.97 via 10.2.0.1 dev eth0 || true
PostDown = ip route del 167.99.130.97 via 10.2.0.1 dev eth0 || true
PostDown = ip route add default via 10.2.0.1 || true

MTU = 1342
PreUp = udp2raw -c -l 127.0.0.1:50001 -r 167.99.130.97:55055 -k "The2password." -a >/var/log/udp2raw.log 2>&1 &
PostDown = killall udp2raw || true

# Endpoint A
[Peer]
PublicKey = z73wM1b7fhMRA8fmeQw4FntRvgJ9JwTdsQHssXHg3DE=
Endpoint = 127.0.0.1:50001
AllowedIPs = 0.0.0.0/0
PersistentKeepalive = 120

discovering mDNS/DNS-SD

Reading time: 3 - 5 minutes

mdns-scan is a simple tool that scans for mDNS/DNS-SD announcements on the local network and lists discovered services. It doesn’t require the full Avahi daemon; it directly uses multicast DNS queries.

$ sudo mdns-scan
+ nas [44:0e:be:62:58:a5]._workstation._tcp.local
+ nas._http._tcp.local
+ nas._smb._tcp.local
+ nas._qdiscover._tcp.local

In the past I used avahi-browse but it requires dbus, and in some systems I don’t use dbus.

WireGuard Over TCP Using udp2raw: Securing and Expanding Connectivity

Reading time: 30 – 50 minutes

In this post, I’ll share how I set up a WireGuard VPN over TCP using udp2raw, which provides secure access to corporate networks and serves as a fallback for internet access when customer networks impose heavy restrictions. Inspired by Pro Custodibus, this solution enables IoT gateways to seamlessly connect to both the company’s internal services and the broader internet under constrained conditions.

Scenario Overview

The architecture for this setup is illustrated below:

Key Features of the Solution:

  1. Access to Corporate Networks: IoT Gateways securely connect to the corporate network for accessing internal services.
  2. Fallback Internet Access: When the customer’s network restricts internet access but allows TCP connections to the company infrastructure, the IoT Gateway routes its internet traffic through the company’s network.

How It Works:

  • Endpoint A (Client): An IoT Gateway connects through the restrictive customer network.
  • Endpoint B (Server): The WireGuard server is accessible via a public IP (134.122.74.29) on TCP port 55055.
  • Traffic flows through a TCP tunnel created with udp2raw, enabling the gateway to securely access the corporate network or relay internet traffic via the company’s infrastructure.

This dual-purpose setup ensures robust connectivity for IoT devices even in challenging environments.

Video Demonstration (in Spanish)

I’ve created a video demonstration in Spanish showcasing the entire setup and functionality of this scenario. The video walks through the following steps:

  1. Explaining the problem and network constraints.
  2. Demonstrating the configuration of both endpoints (client and server).
  3. Showing the connection initiation and testing, including how traffic flows through the VPN tunnel.
  4. Verifying fallback internet access through the company network.

This video is ideal for those who prefer visual explanations or need extra guidance in implementing this solution.

Configuration Files

1. Endpoint B (server, /etc/wireguard/wg0.conf)

This configuration allows Endpoint B to act as a gateway for both corporate access and fallback internet connectivity:

# local settings for Endpoint B
[Interface]
PrivateKey = EMqyADu4Xeu95ZpNZE97FET5eKzN1WSwBkeBWtX1yGg=
Address = 192.168.111.1/32
ListenPort = 51822

# receive wg through udp2raw
MTU = 1342
PreUp = udp2raw -s -l 134.122.74.29:55055 -r 127.0.0.1:51822 -k "The2password." -a >/var/log/udp2raw.log 2>&1 &
PostDown = killall udp2raw || true

# Enable NAT for traffic forwarding (corporate and fallback internet access)
PreUp = echo 1 > /proc/sys/net/ipv4/ip_forward || true
PreUp = iptables -t nat -I POSTROUTING -o eth0 -j MASQUERADE || true
PreDown = iptables -t nat -D POSTROUTING -o eth0 -j MASQUERADE || true

# remote settings for Endpoint A
[Peer]
PublicKey = Xt70DJy8ldPcDNW4YM2Dt94n16pTQKFxhmvpgKvJyng=
AllowedIPs = 192.168.111.2/32
PersistentKeepalive = 120

Key Points:

  • NAT Rules: These rules enable traffic originating from Endpoint A to use Endpoint B for accessing the internet.
  • MTU Adjustment: The MTU is set to 1342 to prevent fragmentation issues over the TCP tunnel.

Assumptions:

  • eth0, is the name of the interface for reaching Internet.
  • 192.168.111.0/24 is available for point-to-point connections in the tunnels.
  • ud2raw is in PATH.
  • Don’t re-use my pub and private keys. Neither the pre-shared key of used by udp2raw.
Endpoint A (client, /etc/wireguard/wg0.conf)

This configuration sets up Endpoint A to route all traffic (corporate and internet) through Endpoint B:

[Interface]
PrivateKey = yAxByb468bAuMdg5S6AlfYkxbeYDOMEKxdaJ7d2p83g=
Address = 192.168.111.2/32

# Route configuration for public IP
PreUp = ip route del default || true
PreUp = ip route add 134.122.74.29 via 10.2.0.1 dev eth0 || true
PostDown = ip route del 134.122.74.29 via 10.2.0.1 dev eth0 || true
PostDown = ip route add default via 10.2.0.1 || true

MTU = 1342
PreUp = udp2raw -c -l 127.0.0.1:50001 -r 134.122.74.29:55055 -k "The2password." -a >/var/log/udp2raw.log 2>&1 &
PostDown = killall udp2raw || true

[Peer]
PublicKey = VUN2JqZiGQ1V46PDoFECw/nMs3/o6n8PvGMV+ad+Hww=
Endpoint = 127.0.0.1:50001
AllowedIPs = 0.0.0.0/0
PersistentKeepalive = 120

Key Points:

  • Fallback Internet Routing: The AllowedIPs = 0.0.0.0/0 directive ensures all traffic is routed through Endpoint B, including internet traffic.
  • Dynamic Route Adjustments: The PreUp and PostDown commands manage routes for efficient fallback connectivity.

Here’s the improved Implementation Steps section based on your feedback and expertise in WireGuard and udp2raw:

Implementation Steps

This section outlines the precise steps required to set up the WireGuard VPN over TCP using udp2raw. Follow these instructions carefully for both Endpoint A (client) and Endpoint B (server).

1. Pre-requisites

  • WireGuard Installation: Ensure WireGuard is installed on both systems. This can usually be done via the package manager of your operating system (e.g., apt install wireguard for Debian-based distributions).
  • udp2raw Binary: Download the appropriate udp2raw binary from its GitHub Releases Page. Binaries are available for various architectures. For simplicity:
    1. Extract the binary from the tarball (e.g., udp2raw_amd64 for most x86_64 systems).
    2. Place the binary in a directory accessible from your PATH (e.g., /usr/local/bin).
    3. Verify the installation: which udp2raw udp2raw -h # Should display the help menu

2. Prepare the Configuration Files

The configuration files should be located at /etc/wireguard/wg0.conf. Each endpoint has its own specific configuration:

  • Endpoint A: Use the wg0.conf provided earlier, replacing placeholders like keys and IPs as needed.
  • Endpoint B: Use the wg0.conf provided earlier.

Ensure both files reflect the IP addresses, MTU settings, and public/private keys accurately.

3. Generate WireGuard Keys

WireGuard requires public-private key pairs for secure communication. Generate them as follows:

  1. Generate the Private Key: wg genkey > privatekey
  2. Generate the Public Key from the private key: cat privatekey | wg pubkey > publickey
  3. Place the private key in the [Interface] section of the respective configuration file (PrivateKey = ...) and the corresponding public key of the peer in the [Peer] section (PublicKey = ...).

Note: Never share your private keys.

4. Start the VPN Tunnel

  1. Start the Server First (Endpoint B):
    • Bring up the WireGuard interface using wg-quick: sudo wg-quick up wg0
    • Verify that the interface is active: wg show
  2. Start the Client (Endpoint A):
    • Bring up the client WireGuard interface: sudo wg-quick up wg0
    • Verify that the interface is active: wg show

5. Test the Connection

Once both endpoints are active, initiate traffic from Endpoint A to Endpoint B. This step ensures the udp2raw TCP socket is properly established and functioning:

  1. Ping Endpoint B’s WireGuard IP: ping 192.168.111.1
    • If the ping succeeds, the connection is working as expected.
    • If it fails, check the logs for udp2raw and WireGuard on both endpoints for errors: less /var/log/udp2raw.log
  2. Once the initial handshake completes, the tunnel will remain active as long as PersistentKeepalive is configured in the client configuration (e.g., PersistentKeepalive = 120).

6. Validate Fallback Internet Access

To confirm the fallback internet routing through Endpoint B:

  1. On Endpoint A, run a test to confirm external connectivity: curl -I https://www.google.com
    • If the response headers are received, the internet routing through Endpoint B is functioning.
    • Verify that the traffic is routed through the WireGuard tunnel: traceroute google.com
  2. If fallback internet access fails, ensure that NAT is correctly configured on Endpoint B: iptables -t nat -L -n

7. Troubleshooting

  • Log Files:
    • Check the udp2raw logs on both endpoints for issues (e.g., MTU mismatches, handshake failures).
    • Review WireGuard logs for additional details.
  • MTU Issues:
    • If large packets fail but small packets (e.g., ping) succeed, reduce the MTU (e.g., to 1280).

8. Automate Startup

To ensure the VPN starts automatically on boot:

  1. Enable the WireGuard service: sudo systemctl enable wg-quick@wg0
  2. Add udp2raw commands to a systemd service or the PreUp directive in wg0.conf (as shown in the configuration files).

With these steps, you now have a fully operational WireGuard tunnel over TCP, enabling secure communication between endpoints and fallback internet connectivity via the company’s infrastructure.

Conclusion

This configuration provides a robust solution for IoT Gateways operating in restrictive environments. By leveraging udp2raw, WireGuard traffic is tunneled over TCP, enabling:

  1. Seamless Corporate Access.
  2. Fallback Internet Connectivity through the company network when customer environments impose constraints.

This versatile setup ensures uninterrupted operations and secure communications for IoT devices. Explore the Pro Custodibus guide and udp2raw GitHub repository for additional insights.

References

Grafana Alloy, parsing syslog RFC5424

Reading time: 31 – 51 minutes

Parsing syslog fields in a Grafana Alloy configuration file (config.alloy):


  stage.regex {
      expression = "^<(?P<priority>\\d|\\d{2}|1[1-8]\\d|19[01])>(?P<version>\\d{1,2})\\s(?P<timestamp>-|(?P<fullyear>[12]\\d{3})-(?P<month>0\\d|1[0-2])-(?P<mday>[0-2]\\d|3[01])T(?P<hour>[01]\\d|2[0-3]):(?P<minute>[0-5]\\d):(?P<second>[0-5]\\d|60)(?:\\.(?P<secfrac>\\d{1,6}))?(?P<numoffset>Z|[+-]\\d{2}:\\d{2}))\\s(?P<hostname>\\S{1,255})\\s(?P<appname>\\S{1,48})\\s(?P<procid>\\S{1,128})\\s(?P<msgid>\\S{1,32})\\s(?P<structureddata>-|\\[(?:[^\\[\\]]|\\\\.)*\\]) (?:\\s(?P<msg>.+))?$"
  }

  stage.labels  {
    values = {
      application = "appname",
      pid = "procid",
      msgid = "msgid",
      structureddata = "structureddata",
    }
  }

If Grafana Alloy logs are also parsed using this endpoint, it’s good to add next:

  stage.regex {
    expression = "^<(?P<priority>\\d|\\d{2}|1[1-8]\\d|19[01])>(?P<version>\\d{1,2})\\s(?P<timestamp>-|(?P<fullyear>[12]\\d{3})-(?P<month>0\\d|1[0-2])-(?P<mday>[0-2]\\d|3[01])T(?P<hour>[01]\\d|2[0-3]):(?P<minute>[0-5]\\d):(?P<second>[0-5]\\d|60)(?:\\.(?P<secfrac>\\d{1,6}))?(?P<numoffset>Z|[+-]\\d{2}:\\d{2}))\\s(?P<hostname>\\S{1,255})\\s(?P<appname>\\S{1,48})\\s(?P<procid>\\S{1,128})\\s(?P<msg>.*)$"
  }

  stage.output  {
    source = "msg"
  }

  stage.replace {
    expression = "(ts=\\S+\\s+level=\\S+\\s+)"
    source = "msg"
    replace = ""
  }

  stage.output {
    source = "msg"
  }

Accessing Zerotier’s REST API

Reading time: 6 – 10 minutes

Zerotier offers a powerful REST API that allows for seamless integration and management of your network. By default, the API is accessible on TCP port 9993. To securely interact with this API, an authentication token is required.

The authentication token is stored in the following file:

/var/lib/zerotier-one/authtoken.secret

To check if the Zerotier service is running correctly, you can use the curl command with the necessary authentication header. Here’s how to do it:

curl -Lv -H "X-ZT1-Auth: $(cat /var/lib/zerotier-one/authtoken.secret)" http://localhost:9993/status 2>&1|less

Breaking Down the Command:

  • curl -Lv
    • -L: Follows any redirects the server might issue.
    • -v: Enables verbose mode, providing detailed information about the request and response.
  • -H "X-ZT1-Auth: $(cat /var/lib/zerotier-one/authtoken.secret)"
    • Adds a custom header X-ZT1-Auth with the value of your authentication token. This is essential for authorized access to the API.
  • http://localhost:9993/status
    • The endpoint to check the current status of the Zerotier service.
  • 2>&1 | less
    • Redirects both standard output and standard error to less for easy reading and navigation of the output.

I hope you found this guide helpful in navigating Zerotier’s REST API.

Docker Container Status as Prometheus Exporter Metrics

Reading time: 2 – 2 minutes

Tracking Docker container status in real time is a common challenge in DevOps. Popular tools like cAdvisor and the default Docker exporter for Prometheus often lack direct metrics for container states, meaning key insights—such as the number of containers that are running, stopped, or inactive—require complex workarounds. This limitation can complicate monitoring and lead to unreliable data.

Before creating docker_container_exporter, I relied on complex Prometheus queries to retrieve container statuses. This often involved calculations based on the last time a container was seen as active, but this approach had a major flaw: if the query time range didn’t match the last activity timestamp precisely, the data could be inaccurate or incomplete. Monitoring container states shouldn’t be this difficult.

With docker_container_exporter, this problem is solved. My tool captures real-time Docker container statuses, providing data on the number of running, stopped, and other container states, all in a Prometheus-compatible format. You can collect these metrics through a standard Prometheus polling process, or use agents like Grafana Alloy to push the data to Prometheus storage or compatible DB servers like Grafana Mimir or Thanos.

You can find my project in this GitHub repository: docker_container_exporter

In the README file, you’ll find details on how to use it, as well as instructions for integrating it with Grafana Alloy.

How to Manage Environment Variables for Production and Development with Docker Compose

Reading time: 34 – 56 minutes

Managing environment variables for different environments, such as production and development, is crucial for deploying applications effectively. In this post, I’ll demonstrate how to use Docker Compose with .env files to easily switch between these environments, using the example of setting a DEBUG_LEVEL variable to control application logging.

To start, you’ll need different .env files for each environment:

1. .env (Common configuration)

ENVIRONMENT=prod
UBUNTU_VERSION=24.04

This common .env file sets the default ENVIRONMENT to prod (production) and specifies the Ubuntu version. These variables are used across all environments.

2. .env.prod (Production-specific configuration)

DEBUG_LEVEL=ERROR

In the production environment, DEBUG_LEVEL is set to ERROR to minimize logging output and avoid exposing sensitive information.

3. .env.dev (Development-specific configuration)

DEBUG_LEVEL=DEBUG

In the development environment, DEBUG_LEVEL is set to DEBUG to provide detailed logs for troubleshooting and development purposes.

The compose.yaml file is set up to dynamically load the appropriate environment file based on the ENVIRONMENT variable, which can be set either in the shell or in the .env file:

services:
  test:
    image: ubuntu:${UBUNTU_VERSION}
    command: ["sh", "-c", "env"]
    env_file:
      - .env.${ENVIRONMENT}

This configuration uses the env_file directive to load the environment-specific file (.env.prod or .env.dev) based on the value of the ENVIRONMENT variable.

If the ENVIRONMENT variable is set in both the .env file and the shell, the value set in the shell will take precedence. This is useful for temporarily overriding the environment setting without modifying the .env file. For example:

Setting the ENVIRONMENT variable in the shell:

export ENVIRONMENT=dev

If you also have ENVIRONMENT=prod set in the .env file, the shell setting will overwrite it, and the development environment settings will be used:

$ docker compose up
[+] Running 2/1
  Network tmp_default   Created                                                                          0.1s
  Container tmp-test-1  Created                                                                          0.1s
Attaching to test-1
test-1  | DEBUG_LEVEL=DEBUG
test-1  | HOSTNAME=f9002b77bc79
test-1  | HOME=/root
test-1  | PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
test-1 exited with code 0

If you want to use the production settings instead, you can unset the shell variable and rely on the value in the .env file:

unset ENVIRONMENT

Then, when you run docker compose up again, the output will reflect the production environment:

$ docker compose up
[+] Running 2/1
  Network tmp_default   Created                                                                          0.1s
  Container tmp-test-1  Created                                                                          0.1s
Attaching to test-1
test-1  | DEBUG_LEVEL=ERROR
test-1  | HOSTNAME=f9002b77bc79
test-1  | HOME=/root
test-1  | PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
test-1 exited with code 0

By using .env files and setting the ENVIRONMENT variable in the shell, you have the flexibility to manage environment variables dynamically. This approach simplifies switching between environments and ensures consistent deployment settings, minimizing the risk of configuration errors and improving application reliability.

The Power of the .env File in Docker Compose

Reading time: 30 – 50 minutes

In this post, I’ll demonstrate how powerful and flexible the .env file can be when setting up a compose.yaml for Docker Compose. This approach allows for easy management of environment variables, making your Docker configurations more dynamic and manageable.

Let’s start with a simple .env file:

UBUNTU_VERSION=24.04

And a corresponding compose.yaml file:

services:
  test:
    image: ubuntu:${UBUNTU_VERSION}
    command: ["sh", "-c", "env"]

When you run the Docker Compose stack with the command docker compose up, you’ll see an output like this:

$ docker compose up
[+] Running 2/1
  Network tmp_default   Created                                                                          0.1s
  Container tmp-test-1  Created                                                                          0.1s
Attaching to test-1
test-1  | HOSTNAME=f9002b77bc79
test-1  | HOME=/root
test-1  | PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
test-1  | PWD=/
test-1 exited with code 0

However, to make the variables defined in the .env file available within the Docker container, you need to add a couple of lines to your compose.yaml file:

services:
  test:
    image: ubuntu:${UBUNTU_VERSION}
    command: ["sh", "-c", "env"]
    env_file:
      - .env

After updating the compose.yaml file, run the docker compose up command again. This time, you’ll notice that the UBUNTU_VERSION environment variable is now included in the container’s environment:

$ docker compose up
[+] Running 1/0
  Container tmp-test-1  Recreated                                                                        0.1s
Attaching to test-1
test-1  | HOSTNAME=069e3c4a4413
test-1  | HOME=/root
test-1  | PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
test-1  | UBUNTU_VERSION=24.04
test-1  | PWD=/
test-1 exited with code 0

This is incredibly convenient because maintaining the .env file allows you to easily manage environment variables across different services without modifying the compose.yaml file each time. This example clearly illustrates how powerful and useful it is to use .env files in Docker Compose configurations.

Scroll to Top