HTTP, HTTPS y TLS: Parte 9 — Depuración de HTTP con curl: suplantación de DNS, redirecciones, tiempos y trazado

curl — cliente HTTP de consola que está en Linux, macOS y Windows 10 o superior. Para depuración es más cómodo que un navegador: muestra la solicitud y la respuesta completas, permite establecer cualquier cabecera y método, enviar la solicitud a una IP concreta evitando DNS y medir en qué etapa se gasta el tiempo. Abajo — técnicas de depuración: desde ver cabeceras hasta diagnosticar un sitio lento detrás de un balanceador. Si estás empezando con curl, comienza por el artículo «curl para principiantes»: allí se explican las claves principales, peticiones a APIs y subida de archivos.

La versión de curl en el sistema puede ser antigua; parte de las opciones apareció recientemente (se indica la versión para cada una). Tu versión y las capacidades de la compilación las mostrará curl --version.

Ver la respuesta y las cabeceras

curl https://example.ru/                 # solo el cuerpo de la respuesta
curl -i https://example.ru/              # cabeceras de respuesta + cuerpo
curl -I https://example.ru/              # solo cabeceras (método HEAD)
curl -v https://example.ru/              # todo: DNS, TCP, TLS, solicitud, respuesta
curl -sv -o /dev/null https://example.ru/ 2>&1   # todo, excepto el cuerpo
curl -s -D - -o /dev/null https://example.ru/    # solo cabeceras, pero con método GET

Qué significan las opciones:

• -v (verbose) — salida detallada en stderr: líneas * — mensajes de servicio (dirección, TLS, certificado), > — solicitud enviada, < — cabeceras recibidas;
• -s — sin indicador de progreso; junto con -S los errores igualmente se muestran;
• -o /dev/null — desechar el cuerpo; -o file — guardar en archivo, -O — guardar con el nombre del recurso;
• -D - — escribir las cabeceras de respuesta en stdout.

Cuidado con -I. Envía HEAD, no GET. Algunas aplicaciones responden a HEAD de forma distinta — 405, 404 o sin las cabeceras necesarias. Si la respuesta a -I se ve extraña, comprueba la misma URL con -s -D - -o /dev/null.

Enviar cabeceras

La cabecera se especifica con la opción -H, la opción se puede repetir:

curl -H 'Accept: application/json' \
     -H 'Authorization: Bearer eyJhbGciOi...' \
     -H 'X-Request-ID: debug-42' \
     https://api.example.ru/v1/orders

Formas especiales:

curl -H 'User-Agent:' https://example.ru/      # eliminar la cabecera que curl añade por sí mismo
curl -H 'X-Empty;' https://example.ru/         # enviar una cabecera con valor vacío
curl -H @headers.txt https://example.ru/       # tomar las cabeceras de un archivo, una por línea (7.55+)

Para cabeceras habituales hay opciones separadas:

curl -A 'Mozilla/5.0 ...' https://example.ru/     # User-Agent
curl -e https://example.ru/ https://example.ru/x  # Referer
curl -u admin:secret https://example.ru/admin/    # autorización Basic
curl --oauth2-bearer TOKEN https://api.example.ru/ # Authorization: Bearer
curl --compressed https://example.ru/             # Accept-Encoding + descompresión de la respuesta

No conviene indicar -H 'Accept-Encoding: gzip' manualmente: curl recibirá la respuesta comprimida y la mostrará en el terminal tal cual. --compressed solicita compresión y además descomprime.

Contraseñas y tokens en la línea de comandos son visibles en ps y quedan en el historial del shell. En scripts pásalos desde un archivo: -H @auth-header.txt, o usa ~/.netrc con la opción --netrc.

Cookies

curl -b 'session=abc123; lang=ru' https://example.ru/account   # enviar cookie
curl -c cookies.txt https://example.ru/login                   # guardar las recibidas
curl -b cookies.txt -c cookies.txt https://example.ru/account  # leer y actualizar el archivo

Escenario típico — iniciar sesión mediante un formulario y luego navegar con la sesión obtenida:

curl -c jar.txt -d 'login=ivanov&password=secret' https://example.ru/login
curl -b jar.txt https://example.ru/account

Métodos y cuerpo de la solicitud

Curl elige el método: sin cuerpo — GET, con -d — POST, con -I — HEAD. El método se puede especificar explícitamente con -X:

curl -X DELETE https://api.example.ru/v1/orders/42
curl -X PUT -H 'Content-Type: application/json' -d '{"status":"paid"}' https://api.example.ru/v1/orders/42

-X POST junto con -d no es necesario — POST ya se usará. Y -X con -L es peligroso: curl aplicará el método indicado a todas las solicitudes tras los redireccionamientos, incluso donde por estándar debería usarse GET.

Forma (application/x-www-form-urlencoded):

curl -d 'name=Иван&city=Москва' https://example.ru/form
curl --data-urlencode 'comment=Цена 100% & доставка' https://example.ru/form   # con codificación

-d envía los datos tal cual y elimina saltos de línea del archivo (-d @file). Para archivos sin cambios — --data-binary @file, para cadenas que empiezan con @ — --data-raw.

JSON:

curl --json '{"name":"Иван","qty":2}' https://api.example.ru/v1/orders    # curl 7.82+
curl --json @order.json https://api.example.ru/v1/orders

--json añade Content-Type: application/json y Accept: application/json automáticamente. En versiones antiguas lo mismo:

curl -H 'Content-Type: application/json' -d '{"name":"Иван"}' https://api.example.ru/v1/orders

Subir archivo (multipart/form-data, como un formulario con campo “file”):

curl -F 'title=Отчёт' -F 'file=@report.pdf;type=application/pdf' https://example.ru/upload

Parámetros GET desde datos: -G convierte -d en cadena de consulta:

curl -G -d 'q=nginx' -d 'page=2' https://example.ru/search   # GET /search?q=nginx&page=2

Redirecciones

Por defecto curl no sigue redirecciones y muestra la propia respuesta 301/302. Rastrear toda la cadena:

curl -sIL https://example.ru/old-page | grep -iE '^(HTTP|location)'

HTTP/1.1 301 Moved Permanently
Location: https://example.ru/old-page
HTTP/2 301
location: https://www.example.ru/new-page
HTTP/2 200

• -L — seguir redirecciones;
• --max-redirs 5 — limitar el número de saltos (por defecto 50);
• -w '%{num_redirects} %{url_effective}\n' — cuántos saltos hubo y dónde terminó.

Al pasar a otro host curl no reenvía la cabecera Authorization ni los datos -u — esto protege contra fugas. Si realmente lo necesitas, existe --location-trusted.

Solicitud a un servidor concreto evitando DNS

El truco más útil al migrar, configurar un balanceador o comprobar un nodo entre varios.

--resolve — sustituir la dirección IP para un nombre:

curl --resolve example.ru:443:192.0.2.10 https://example.ru/

curl se conectará a 192.0.2.10, pero Host, SNI y la verificación del certificado serán para example.ru — exactamente como lo haría un navegador después de cambiar el DNS. Así se comprueba el nuevo servidor antes de cambiar el registro.

--connect-to — reemplazar el host y puerto de conexión:

curl --connect-to example.ru:443:backend-2.internal:8443 https://example.ru/

Útil para saltarse el balanceador y conectar directamente a uno de los servidores.

Por qué no -H 'Host: …'. La instrucción curl -H 'Host: example.ru' https://192.0.2.10/ solo cambia la cabecera Host, pero SNI y la verificación del certificado irán para 192.0.2.10: el servidor devolverá el certificado por defecto y curl dará error de nombre no coincidente. Para HTTPS usa --resolve o --connect-to. Para HTTP -H 'Host: …' funciona.

Medición de tiempos

La opción -w (write-out) imprime variables al final de la solicitud. Desglose por etapas:

curl -s -o /dev/null -w '
dns:       %{time_namelookup}
tcp:       %{time_connect}
tls:       %{time_appconnect}
ttfb:      %{time_starttransfer}
total:     %{time_total}
code:      %{http_code}
http:      %{http_version}
ip:        %{remote_ip}
size:      %{size_download}
' https://example.ru/

Todos los tiempos — en segundos desde el inicio de la petición, acumulativos:

• time_namelookup — DNS; más de 0,1 s — problema con el resolvedor;
• time_connect − time_namelookup — establecimiento de TCP, aproximadamente una ida y vuelta hasta el servidor (RTT);
• time_appconnect − time_connect — apretón de manos TLS;
• time_starttransfer − time_appconnect — tiempo que el servidor tardó en preparar la respuesta (TTFB sin red). Si es grande — problema en la aplicación o la base, no en la red;
• time_total − time_starttransfer — descarga del cuerpo.

Es práctico guardar la plantilla en un archivo y usar -w @curl-format.txt. Con curl 7.70 hay -w '%{json}' — todas las variables en JSON, y con 7.83 — %{header_json} para las cabeceras de respuesta.

Comprobación de estabilidad — serie de peticiones:

for i in $(seq 1 20); do
  curl -s -o /dev/null -w '%{http_code} %{time_total}\n' https://example.ru/
done

Selección de versión y protocolo

curl --http1.1 https://example.ru/
curl --http2 https://example.ru/
curl --http3 https://example.ru/          # si la compilación soporta HTTP/3
curl -4 https://example.ru/               # solo IPv4
curl -6 https://example.ru/               # solo IPv6

Si el sitio abre por IPv4 y no abre para parte de los usuarios, verifica con -6: una causa frecuente es un registro AAAA apuntando a una IP donde el sitio no está escuchando.

Proxy

curl -x http://proxy.example.ru:3128 https://example.ru/
curl -x socks5h://127.0.0.1:1080 https://example.ru/    # h — DNS también a través del proxy
curl --noproxy '*' https://example.ru/                  # ignorar variables de entorno

curl respeta las variables http_proxy, https_proxy, no_proxy. Si una petición funciona en un entorno y en otro no, comprueba env | grep -i proxy — quizá el proxy se haya tomado sin darse cuenta.

Códigos de retorno y scripts

Por defecto curl termina con éxito (código 0) y considera error solo la caída de la conexión; respuestas 404 o 500 no hacen fallar. Para scripts y comprobaciones:

curl -fsS https://example.ru/health || echo 'servicio no disponible'
curl --fail-with-body -sS https://api.example.ru/v1/check   # 7.76+: código de error y cuerpo de la respuesta

• -f (--fail) — ante respuestas 400 o superiores devuelve código 22;
• --retry 3 --retry-delay 2 — reintentar en errores temporales (timeout, 408, 429, 5xx);
• --connect-timeout 5 --max-time 20 — limitar el tiempo de conexión y de la petición entera. Sin ellos curl puede esperar mucho tiempo a un servidor colgado.

Códigos de error frecuentes de curl: 6 — no se pudo resolver el nombre; 7 — no se pudo conectar; 28 — timeout; 35 — error en el apretón de manos TLS; 60 — el certificado no pasó la verificación.

Trazado completo

Cuando -v no es suficiente — por ejemplo, necesitas ver los bytes exactos del cuerpo de la solicitud o el orden de los eventos:

curl --trace-ascii trace.txt --trace-time https://example.ru/

En el archivo — cada bloque de datos enviado y recibido con marca temporal. --trace escribe lo mismo con volcado hexadecimal.

Copiar la solicitud desde el navegador

En las herramientas de desarrollador (F12) en la pestaña Network haz clic derecho sobre la solicitud → Copy → Copy as cURL. Obtendrás un comando con todas las cabeceras y cookies del navegador. Es la forma más rápida de repetir en la consola una solicitud que se comporta de forma extraña y luego ir retirando cabeceras una por una para encontrar la causa.

Ten en cuenta: esa petición repetirá las cabeceras, pero no la huella TLS del navegador. Si un sitio protegido contra bots responde 200 al navegador y 403 al mismo request desde curl, lo más probable es que el causante sea la huella.

Errores típicos

• Usar -I para comprobar una aplicación que no soporta HEAD — falsos 404 y 405.
• -H 'Host: …' para HTTPS en vez de --resolve — error de certificado y sitio incorrecto por defecto.
• -k en scripts de comprobación — un certificado expirado o de otro dominio queda sin ser detectado.
• Comprobar disponibilidad sin -f — el script considera 502 como éxito.
• JSON con -d sin Content-Type — curl envía application/x-www-form-urlencoded y la aplicación no ve los datos.
• No poner --max-time en tareas cron — los procesos curl colgados se acumulan.