cURL mit Proxy verwenden: HTTP- und SOCKS5-Proxy einrichten

Sie haben von Ihrem Anbieter eine Proxy-Adresse bekommen und möchten wissen, ob sie funktioniert, bevor sie in einem Scraper, einem Cronjob oder einer CI-Pipeline landet. cURL ist dafür der schnellste Test: Ein einziger Befehl schickt eine Anfrage über den Proxy und gibt die IP-Adresse aus, die die Zielseite sieht. Derselbe Befehl passt danach unverändert in ein Shell-Skript.

Dieser Artikel behandelt die Option -x, Zugangsdaten, SOCKS5, Proxy-Einstellungen für alle Befehle, ein Download-Skript mit Wiederholungen und die genauen Fehlermeldungen. Jeder Befehl wurde mit curl 8.21 gegen einen lokalen Test-Proxy ausgeführt; die Optionen sind in der curl-Manpage dokumentiert.

Was ist cURL?#

cURL (gesprochen „körl“) ist ein Kommandozeilenwerkzeug, das Daten über URLs überträgt: Es lädt Seiten und Dateien herunter, sendet Formulare und API-Anfragen und gibt die Antwort aus oder speichert sie. Die eigentliche Arbeit erledigt libcurl, eine Transferbibliothek, die auch PHP und andere Programmiersprachen nutzen.

Jeder Befehl folgt derselben Syntax:

curl [Optionen] [URL]

Es gibt mehr als 250 Optionen. -o page.html speichert die Antwort in einer Datei, -I holt nur die Header, -L folgt Weiterleitungen und -x nutzt einen Proxy. Optionen unterscheiden Groß- und Kleinschreibung: -x setzt einen Proxy, -X die HTTP-Methode. Ebenso bricht -f bei HTTP-Fehlern ohne Ausgabe ab, während -F ein Formularfeld sendet.

cURL ist in macOS enthalten, in Windows 10 und 11 als curl.exe und in den meisten Linux-Distributionen. In schlanken Container-Images müssen Sie es unter Umständen nachinstallieren (apt install curl unter Debian und Ubuntu). Führen Sie curl --version aus: Steht in der Zeile Features: der Eintrag HTTPS-proxy, kann Ihr Build einen Proxy auch über TLS erreichen.

Welche Protokolle unterstützt cURL?#

cURL arbeitet nur mit Protokollen, die sich als URL schreiben lassen. Die aktuelle Version nennt DICT, FILE, FTP, FTPS, GOPHER, GOPHERS, HTTP, HTTPS, IMAP, IMAPS, LDAP, LDAPS, MQTT, MQTTS, POP3, POP3S, RTSP, SCP, SFTP, SMB, SMBS, SMTP, SMTPS, TELNET, TFTP, WS und WSS. curl --version zeigt, was Ihr Build unterstützt; RTMP, das in älteren Listen noch auftaucht, ist entfallen.

Ohne Schema rät cURL das Protokoll anhand des Hostnamens (ftp.example.com bedeutet FTP, die meisten anderen Namen HTTP). Für Proxys zählt das in einem Punkt: Ein HTTP-Proxy transportiert HTTP und HTTPS; andere Protokolle kommen nur durch einen CONNECT-Tunnel (-p) hindurch und nur dann, wenn der Proxy diesen Port zulässt. SOCKS5 transportiert jede TCP-Verbindung. FTP oder SMTP über einen Proxy bedeutet deshalb meist SOCKS5.

Warum cURL mit einem Proxy verwenden?#

• Sichtbare Schritte. -v zeigt die Verbindung zum Proxy, die CONNECT-Anfrage und beide Antworten. Sie sehen also genau, an welcher Stelle eine Anfrage scheitert.
• Jeder Proxy-Typ über eine Option. HTTP, HTTPS, SOCKS4, SOCKS4a, SOCKS5 und SOCKS5h laufen alle über -x.
• Skripte. Exit-Codes, --retry, Zeitlimits und --write-out erlauben einem Shell-Skript, mit Fehlern umzugehen, und die curl_*-Funktionen von PHP nehmen dieselben Optionen.
• Viele URLs in einem Befehl. URL-Globbing wie page[1-20].html oder {a,b,c} erzeugt mehrere Anfragen, alle über denselben Proxy.

Typische Aufgaben: das Land einer Exit-IP vor einem Lauf für Data Scraping prüfen, Ziele für die Preisüberwachung aus einem anderen Markt testen und Downloads in geplanten Jobs. Die Entsprechungen für Node.js finden Sie in cURL in JavaScript, die für PHP in Webscraping mit PHP.

Wie leitet cURL eine Anfrage über einen Proxy?#

1. cURL verbindet sich mit dem Proxy, nicht mit dem Ziel.
2. HTTP-Ziel, HTTP-Proxy: cURL sendet die Anfrage mit der vollständigen URL (GET http://example.com/ HTTP/1.1). Der Proxy kann sie lesen.
3. HTTPS-Ziel, HTTP-Proxy: cURL sendet CONNECT example.com:443, mit einem Proxy-Authorization-Header, falls Sie Zugangsdaten angegeben haben. Sobald der Proxy mit 200 antwortet, läuft TLS zum Ziel innerhalb dieses Tunnels; der Proxy sieht nur Host und Port. Die CONNECT-Methode ist in RFC 9110 definiert.
4. SOCKS5-Proxy: cURL meldet sich an (mit Benutzername und Passwort, falls angegeben) und bittet den Proxy, die Verbindung zum Ziel aufzubauen (RFC 1928). Mit socks5:// sendet es eine IP, die es selbst aufgelöst hat, mit socks5h:// den Hostnamen.
5. Das Ziel antwortet an die IP des Proxys. Ihre eigene IP erreicht es nicht, Ihre DNS-Anfragen aber schon, wenn cURL Namen lokal auflöst.

So setzen Sie einen Proxy in cURL: die Option -x#

curl --help proxy listet alle Proxy-Optionen auf. Die wichtigste:

 -x, --proxy <[protocol://]host[:port]>  Use this proxy

-x und --proxy sind dieselbe Option; das x ist klein geschrieben:

curl -x "http://user:pass@pr.proxynet.io:8000" https://httpbin.org/ip

httpbin.org/ip gibt die IP zurück, von der Ihre Anfrage kam. Läuft der Proxy, sehen Sie dort also seine Exit-IP statt Ihrer eigenen Adresse.

• Ohne Schema gilt HTTP. -x "user:pass@pr.proxynet.io:8000" verhält sich wie die Form mit http://.
• Geben Sie immer den Port an. Ohne Port wählt cURL einen Standardwert: in unserem Test mit curl 8.21 Port 80 für http://, 443 für https:// und 1080 für SOCKS (die Manpage nennt weiterhin 1080). Keiner davon ist vermutlich der Port Ihres Anbieters, die Verbindung scheitert also oder läuft in eine Zeitüberschreitung.
• Setzen Sie die Adresse in Anführungszeichen, damit die Shell Zeichen wie &, ? oder ! nicht selbst auswertet. Dasselbe gilt für Ziel-URLs mit Parametern.
• -x gilt pro Befehl und hat Vorrang vor Proxy-Umgebungsvariablen. Der nächste Befehl geht wieder direkt hinaus.

Bei den Residential- und Mobile-Produkten von Proxynet bedient ein Gateway HTTP und SOCKS5 auf getrennten Ports, und der Endpoint-Generator im Panel baut den Benutzernamen mit dem gewählten Land, der Stadt und der Sitzung zusammen.

Wie nutzen Sie cURL mit einem HTTP- oder HTTPS-Proxy?#

Ein HTTP-Proxy transportiert beide Arten von Zielen:

# HTTPS-Ziel: CONNECT-Tunnel, die Seite bleibt verschlüsselt
curl -x "http://user:pass@pr.proxynet.io:8000" https://httpbin.org/ip

# HTTP-Ziel: Der Proxy leitet die unverschlüsselte Anfrage weiter
curl -x "http://user:pass@pr.proxynet.io:8000" http://httpbin.org/ip

Ein HTTPS-Proxy (https://) verschlüsselt zusätzlich die Verbindung zum Proxy selbst. Nutzen Sie ihn nur, wenn der Port TLS spricht. https:// auf einem normalen HTTP-Port scheitert beim Handshake (SEC_E_INVALID_TOKEN unter Windows, mit OpenSSL typischerweise wrong version number).

Die Zertifikatsoptionen sind auf die beiden Verbindungen aufgeteilt:

• -k (--insecure) überspringt die Zertifikatsprüfung nur für die Zielseite. Bei einem http://-Ziel bewirkt es nichts.
• --proxy-insecure überspringt die Prüfung des Zertifikats eines HTTPS-Proxys. Sicherer ist --proxy-cacert file.pem: Damit vertrauen Sie der Zertifizierungsstelle eines Firmen-Proxys, ohne die Prüfung abzuschalten.

Verwenden Sie -k nur für schnelle Tests und nie in Skripten, die Tokens senden. Für Protokolle außer HTTP über einen HTTP-Proxy ergänzen Sie -p (--proxytunnel). Wie verschlüsselter Verkehr einen Proxy passiert, erklärt die Seite zum HTTPS-Proxy.

Wie übergeben Sie Benutzername und Passwort für den Proxy?#

Beide Formen senden denselben Proxy-Authorization-Header:

curl -x "http://user:pass@pr.proxynet.io:8000" https://httpbin.org/ip
curl -x "http://pr.proxynet.io:8000" -U "user:pass" https://httpbin.org/ip

Innerhalb der Adresse müssen Sonderzeichen im Passwort prozentkodiert werden: @ als %40, : als %3A, # als %23. cURL dekodiert sie vor dem Senden; in unserem Test kam p%40ss beim Proxy als p@ss an. Mit -U (--proxy-user) ist keine Kodierung nötig. Standard ist die Basic-Authentifizierung; Firmen-Proxys verlangen unter Umständen --proxy-ntlm, --proxy-digest oder --proxy-anyauth.

Passwörter auf der Kommandozeile landen in der Shell-History. Lesen Sie sie in Skripten aus einer privaten Konfigurationsdatei (-K file) oder nutzen Sie stattdessen eine IP-Whitelist (Proxynet akzeptiert bis zu 10 IPs). Proxy-Authentifizierung: User:Pass oder IP-Whitelist vergleicht beide Verfahren und erklärt den Fehler 407.

Wie nutzen Sie cURL mit einem SOCKS5-Proxy?#

Schreiben Sie die SOCKS-Version als Schema:

curl -x "socks5h://user:pass@pr.proxynet.io:1080" https://httpbin.org/ip

Mit socks5:// sieht Ihr DNS-Server jeden Host, den Sie aufrufen, und standortabhängige Websites antworten für Ihren Standort. socks5h:// vermeidet beides und ist für Scraping meist die bessere Wahl, weil die DNS-Abfrage sonst von Ihrer eigenen Leitung ausgeht (WebRTC- und DNS-Lecks erklärt, warum das wichtig ist). Die ältere Option --socks5-hostname host:port entspricht socks5h://, die Zugangsdaten übergeben Sie dann mit -U. --socks5 entspricht dagegen socks5:// mit lokaler Auflösung.

Die Unterschiede der Protokolle erklären SOCKS und HTTP Proxy im Vergleich und SOCKS5-Proxys: Funktionsweise und Unterschiede. Der SOCKS5-Proxy von Proxynet läuft auf einem eigenen Port neben dem HTTP-Port.

Wie setzen Sie einen Proxy für alle cURL-Befehle?#

Umgebungsvariablen. cURL liest http_proxy für HTTP-Ziele, https_proxy oder HTTPS_PROXY für HTTPS und ALL_PROXY als Rückfallwert. http_proxy wirkt nur in Kleinschreibung (ein Schutz für CGI-Programme), HTTP_PROXY wird unter Linux und macOS also ignoriert. In PowerShell: $env:HTTPS_PROXY = "http://user:pass@host:port". wget, pip und git lesen dieselben Variablen; mehr dazu in Proxy-Nutzung mit wget und auf der Seite von everything curl zu Proxy-Variablen.

Die Konfigurationsdatei. cURL liest vor jedem Aufruf die Datei ~/.curlrc (Windows: %USERPROFILE%\.curlrc oder _curlrc):

proxy = "http://pr.proxynet.io:8000"
proxy-user = "user:pass"

curl -q URL, mit -q an erster Stelle, überspringt sie für einen Aufruf.

Ausnahmen. --noproxy "localhost,.internal.example" oder die Variable NO_PROXY schickt diese Hosts direkt hinaus. Ein Name gilt auch für seine Subdomains, CIDR-Bereiche wie 192.168.0.0/16 funktionieren, und der einzige Platzhalter ist ein alleinstehendes *. NO_PROXY gilt auch dann, wenn Sie -x verwenden.

cURL hat keine JavaScript-Engine und kann deshalb keine PAC-Dateien ausführen. Nutzt Ihr Netzwerk eine, lesen Sie die Datei (Was ist eine PAC-Datei?) und übergeben den Proxy, den sie zurückgibt, mit -x.

Wie prüfen Sie, ob cURL den Proxy nutzt?#

Führen Sie curl https://api.ipify.org einmal ohne und einmal mit -x aus: Eine andere Adresse im erwarteten Land bedeutet, dass der Proxy funktioniert. Eine fehlerfreie HTTPS-Anfrage über einen HTTP-Proxy zeigt in der Ausgabe von -v diese Zeilen:

* Establishing HTTP proxy tunnel to httpbin.org:443
> CONNECT httpbin.org:443 HTTP/1.1
> Proxy-Authorization: Basic dXNlcjpwYXNz
< HTTP/1.1 200 Connection Established
* CONNECT tunnel established, response 200

Der Wert von Proxy-Authorization ist nur Base64-kodiert, nicht verschlüsselt; entfernen Sie ihn, bevor Sie die Ausgabe weitergeben. In Skripten gibt -w das Ergebnis in einer Zeile aus:

curl -s -o /dev/null -x "http://user:pass@pr.proxynet.io:8000" \
  -w "%{http_code} connect=%{http_connect} proxy_used=%{proxy_used}\n" https://httpbin.org/ip

http_connect ist die Antwort des Proxys auf CONNECT; proxy_used (ab curl 8.7) ist 1, wenn ein Proxy verwendet wurde. Wie Sie Standort, Geschwindigkeit und Lecks prüfen, beschreibt Funktioniert mein Proxy? So testen Sie einen Proxy.

Beispiel: eine URL-Liste mit Wiederholungen über einen Proxy herunterladen#

Dieses Skript lädt die URLs aus urls.txt jeweils vier gleichzeitig über den Proxy herunter, wiederholt vorübergehende Fehler und gibt für jede URL Status und Dauer aus. Es braucht cURL und eine POSIX-Shell (Linux, macOS oder Git Bash):

#!/usr/bin/env bash
# fetch.sh: jede URL aus urls.txt über den Proxy laden, 4 gleichzeitig
set -u
PROXY="${PROXY:-http://user:pass@pr.proxynet.io:8000}"

sed 's/^/url = /' urls.txt | curl \
  --parallel --parallel-max 4 \
  --proxy "$PROXY" \
  --connect-timeout 10 --max-time 30 \
  --retry 3 --retry-connrefused \
  --fail --silent --show-error \
  --create-dirs --output-dir pages --remote-name-all \
  --write-out "%{http_code} %{time_total}s %{url}\n" \
  --config -

• --config - liest die Zeilen url = … aus sed und muss am Ende stehen, weil --remote-name-all nur für URLs gilt, die danach hinzukommen.
• --retry 3 wiederholt Zeitüberschreitungen sowie HTTP 408, 429, 500, 502, 503, 504, 522 und 524, wartet dabei 1, 2 und 4 Sekunden und beachtet Retry-After.
• --max-time beendet einen hängenden Transfer; --fail macht aus HTTP-Fehlern den Exit-Code 22.
• Halten Sie --parallel-max niedrig, wenn alle URLs auf derselben Website liegen; zu viele parallele Anfragen können 429-Antworten auslösen.

In unserem Test wurden vier Seiten gespeichert, und eine URL mit Status 503 wurde dreimal wiederholt, bevor das Skript mit Code 22 endete.

Wiederholen Sie eine Anfrage an api.ipify.org, um zu sehen, ob Ihr Gateway rotiert: Ein rotierendes Gateway liefert jedes Mal eine neue IP, eine Sticky-Sitzung hält bei Proxynet eine IP für 1 bis 60 Minuten. Was ist IP-Rotation und wie funktioniert sie? erklärt, wann Sie welche Variante nutzen; der Residential-Proxy von Proxynet unterstützt beides. Für schnelle Massenabrufe bei Zielen ohne strenge Prüfung genügt oft ein Datacenter-Proxy.

Häufige cURL-Proxy-Fehler und ihre Lösung#

Die Meldungen, wie curl 8.21 sie in unseren Tests ausgegeben hat:

• curl: (5) Could not resolve proxy: … Der Hostname des Proxys ist falsch: Prüfen Sie die Schreibweise und überzählige Anführungszeichen.
• curl: (7) Failed to connect to … over proxy … Auf diesem Port antwortet nichts (oder cURL ist auf einen Standardport ausgewichen, weil keiner angegeben war), oder eine Firewall blockiert ihn.
• curl: (7) CONNECT tunnel failed, response 407 Falsche Zugangsdaten, nicht kodierte Sonderzeichen oder eine IP, die nicht auf der Whitelist steht. Ältere Versionen geben curl: (56) Received HTTP code 407 from proxy after CONNECT aus; bei http://-Zielen erhalten Sie einfach den Status 407. Mehr dazu in HTTP-Statuscodes beim Web Scraping.
• curl: (56) Proxy CONNECT aborted Der Proxy hat die Verbindung geschlossen; in unserem Test zeigte eine http://-Adresse auf einen SOCKS5-Port.
• curl: (97) Received invalid version in initial SOCKS5 response. Eine socks5://-Adresse zeigt auf einen HTTP-Port. User was rejected by the SOCKS5 server bedeutet falsche SOCKS-Zugangsdaten.
• curl: (28) Connection timed out after … milliseconds Innerhalb der Frist kam keine Antwort; siehe Was tun, wenn der Proxyserver nicht reagiert?.
• curl: (35) … oder SSL_ERROR_SYSCALL Der TLS-Handshake ist gescheitert: https:// auf einem normalen Proxy-Port oder ein Gerät im Netz, das TLS-Verbindungen kappt.
• curl: (60) SSL certificate problem: unable to get local issuer certificate Oft ein Firmen-Proxy, der TLS inspiziert. Installieren Sie dessen CA-Zertifikat, statt -k zu verwenden.
• Der Proxy wird ignoriert. Suchen Sie nach NO_PROXY, großgeschriebenem HTTP_PROXY oder einer anderen .curlrc; -v zeigt, welche Adresse cURL zuerst versucht. Wie dieselben Fehler in Python aussehen, beschreibt Max Retries Exceeded With URL.

Entscheidungshilfe#

Häufige Fragen#

Nutzt cURL unter Windows oder macOS die Proxy-Einstellungen des Systems?#

Nein. cURL übernimmt einen Proxy nur aus -x, aus Umgebungsvariablen und aus der .curlrc. Ein Proxy, den Sie in den Windows-Einstellungen oder in den Systemeinstellungen von macOS eingetragen haben, wirkt sich nicht darauf aus.

Wie umgehe ich den Proxy in cURL für eine einzelne Anfrage?#

Ergänzen Sie --noproxy "*" oder -x "". Beides schickt diesen Befehl direkt hinaus, auch wenn https_proxy oder die .curlrc einen Proxy vorgibt.

Warum scheitert mein cURL-Proxy-Befehl in PowerShell?#

In Windows PowerShell 5.1 ist curl ein Alias für Invoke-WebRequest, das die Option -x nicht kennt. Tippen Sie curl.exe, um das echte cURL zu starten. PowerShell 7 hat diesen Alias nicht mehr.

Was ist der Unterschied zwischen socks5 und socks5h in cURL?#

Mit socks5:// löst Ihr Rechner den Hostnamen auf, mit socks5h:// der Proxy. Die DNS-Auflösung passt dann zum Standort des Proxys.

Kann ich in PHP einen Proxy mit cURL verwenden?#

Ja. Die cURL-Funktionen von PHP nutzen libcurl: CURLOPT_PROXY setzt die Adresse, CURLOPT_PROXYUSERPWD die Zugangsdaten und CURLOPT_PROXYTYPE den SOCKS-Typ. Beispiele finden Sie in Webscraping mit PHP.

Kann cURL bei jeder Anfrage einen anderen Proxy nutzen?#

cURL verwendet einen Proxy pro Befehl. Ein rotierendes Gateway vergibt pro Verbindung eine neue Exit-IP, eine Schleife aus Befehlen erhält also jedes Mal eine andere IP. Mehrere URLs in einem Befehl nutzen meist dieselbe Verbindung und teilen sich deren IP.

Fazit#

Um cURL mit einem Proxy zu nutzen, ergänzen Sie -x mit der vollständigen Adresse: Schema, Zugangsdaten, Host und Port. Nehmen Sie http:// für die meisten Aufgaben und socks5h:// für SOCKS5 mit DNS-Auflösung beim Proxy, legen Sie den Proxy in https_proxy oder der .curlrc ab, wenn jeder Befehl ihn braucht, und behalten Sie -k für Tests vor. Scheitert ein Befehl, zeigen Exit-Code und die Ausgabe von -v, ob die Adresse, die Zugangsdaten oder das Ziel die Ursache ist. Residential-, Mobile- und SOCKS5-Endpunkte, die mit diesen Befehlen funktionieren, finden Sie unter Proxynet-Proxys.