Eine kurze Anmerkung vor den Befehlen: Wir sind Geonode und verkaufen Proxys. Daher ist es nur fair, gleich zu Beginn zu sagen, dass ein Curl-Timeout so gut wie nie auf ein Proxy-Problem zurückzuführen ist. Wenn deine Anfragen bei einem Server, der einfach nur langsam ist, bei einem ausgefallenen Host oder bei einer Firewall, die Pakete stillschweigend verwirft, in eine Zeitüberschreitung münden, ändert die Weiterleitung über uns nichts außer der Rechnung. Proxys helfen, wenn es darum geht, woher Ihre Anfrage scheinbar stammt – bei geografisch eingeschränkten Inhalten, an Ihre Adresse gebundenen Ratenbeschränkungen oder einer gesperrten IP-Adresse. Sie machen einen langsamen Server nicht schneller. Stellen Sie zunächst Ihre Timeouts richtig ein; vielleicht stellen Sie fest, dass Sie gar nichts anderes gebraucht hätten.
Richtig. Hier ist die Sache, die die meisten Leute auf die harte Tour lernen: „curl“ hat kein standardmäßiges Gesamt-Timeout. Es gibt zwar ein Standard-Verbindungs-Timeout von 300 Sekunden, aber sobald eine Verbindung hergestellt ist, wartet curl fröhlich unbegrenzt auf eine Antwort, die nie vollständig eintrifft. In einem Shell-Skript, das über cron ausgeführt wird, ist das ein Job, der niemals endet, und eine Sperrdatei, die niemand löscht.
Die beiden entscheidenden Timeouts
Alles andere ist lediglich eine Weiterentwicklung dieser beiden.
--max-time
(Kurzform: -m
) begrenzt den gesamten Vorgang. Aus dem curl-Handbuch: „Maximale Zeit in Sekunden, die der Übertragungsvorgang dauern darf.“ Verbindung, Handshake, Anfrage, Antwort – einfach alles. Wenn das Limit erreicht ist, bricht curl den Vorgang ab und beendet sich mit dem Code 28.
curl -m 10 https://example.com
Insgesamt zehn Sekunden – danach gibt curl auf, unabhängig davon, in welcher Phase es sich gerade befindet.
--connect-timeout
begrenzt nur die Einrichtungsphase. Das Handbuch beschreibt genau, was dies umfasst: „Die Verbindungsphase gilt als abgeschlossen, wenn die DNS-Auflösung und die angeforderten TCP-, TLS- oder QUIC-Handshakes abgeschlossen sind.“ Sobald die Verbindung besteht, findet diese Option keine Anwendung mehr.
curl --connect-timeout 3 https://example.com
Drei Sekunden, um den Namen aufzulösen und die Handshakes abzuschließen. Danach wartet curl so lange, wie die Übertragung dauert.
In der Praxis benötigt man beides, da sie unterschiedliche Fragen beantworten:
| Option | Gilt für | Typischer Wert | Wovor schützt sie? |
|---|
--connect-timeout | | | |
| DNS + TCP/TLS/QUIC-Handshake | 3–10 s | Ausgefallene Hosts, verlorene Pakete, DNS-Fehler |
| --max-time
| Der gesamte Vorgang | 10–60 s, abhängig von der Auslastung | Langsame Antworten, ins Stocken geratene Übertragungen, endlose Datenströme |
Insgesamt:
curl --connect-timeout 5 -m 30 https://example.com
Fünf Sekunden, um eine Verbindung herzustellen, dreißig Sekunden für den gesamten Vorgang. Ist der Host nicht erreichbar, scheitert der Vorgang bereits nach fünf statt nach dreißig Sekunden – was eine große Rolle spielt, wenn man eine Liste mit tausend URLs durchläuft.
Werte wählen, die keine Schätzungen sind
Der übliche Ansatz besteht darin, eine runde Zahl zu wählen und diese nach oben anzupassen, wann immer etwas fehlschlägt. Das führt zu einem Wert, der so groß ist, dass das Timeout keinen sinnvollen Zweck mehr erfüllt.
Eine bessere Methode erfordert einen zusätzlichen Befehl. Mit curl lässt sich feststellen, wohin die Zeit tatsächlich geflossen ist: `
curl -o /dev/null -s -w "dns: %{time_namelookup}\nconnect: %{time_connect}\ntls: %{time_appconnect}\nttfb: %{time_starttransfer}\ntotal: %{time_total}\n" https://example.com
Führen Sie diesen Befehl zwanzig oder dreißig Mal für Ihr tatsächliches Ziel aus, und Sie erhalten eine Verteilung statt einer Schätzung. Dann:
Legen Sie „--connect-timeout“ gemäß time_appconnect fest. Nehmen Sie den p95-Wert und verdoppeln Sie ihn grob. Die Verbindungszeit wird hauptsächlich durch Netzwerk-Roundtrips bestimmt und ist relativ stabil; wenn sie doppelt so lange dauert wie üblich, liegt ein echtes Problem vor und nicht nur eine Verlangsamung.
Legen Sie „--max-time“ unter time_total fest. Hier sollte der Multiplikator großzügiger gewählt werden – das Drei- bis Fünffache des p95-Werts –, da die Gesamtzeit von der Antwortgröße und der Serverauslastung abhängt, die beide legitim schwanken können. Ein zu strenger „--max-time“-Wert führt zu unzuverlässigen Skripten, die schon an normalen „schlechten Tagen“ fehlschlagen.
Zwei arbeitslastspezifische Anpassungen: Wenn Sie große Dateien herunterladen, ist „--max-time“ völlig ungeeignet, da ein legitimer Download jedes vernünftige feste Limit überschreiten kann – verwenden Sie stattdessen die unten beschriebene geschwindigkeitsbasierte Option. Und wenn Sie eine API aufrufen, die serverseitig echte Arbeit leistet, erkundigen Sie sich nach deren eigenem Timeout und legen Sie Ihren etwas höher fest; ein Timeout von 10 Sekunden bei einem Dienst, der erst nach 12 Sekunden antwortet, bedeutet, dass Sie für die Arbeit bezahlen und das Ergebnis verwerfen.
Bruchteile von Sekunden und Millisekundengenauigkeit
Beide Optionen akzeptieren Dezimalzahlen, wobei unabhängig von Ihrer Ländereinstellung ein Punkt als Trennzeichen verwendet wird. Diese Funktion wird seit curl 7.32.0 unterstützt.
curl --connect-timeout 0.5 -m 2.5 https://example.com
Eine halbe Sekunde für die Verbindung, insgesamt zweieinhalb Sekunden. Nützlich für Zustandsprüfungen und für alle Schleifen, bei denen sich eine volle Sekunde Wartezeit pro Fehler summiert.
Ein wichtiger Hinweis: Die Genauigkeit nimmt mit steigendem Wert ab. In der curl-Dokumentation wird darauf hingewiesen, dass die tatsächliche Zeitüberschreitung an Genauigkeit verliert, je höher die Dezimalgenauigkeit der angegebenen Zeitüberschreitung ist. Die Schreibweise „--max-time 30.001“ unterscheidet sich nicht wesentlich von „--max-time 30“. Dezimalzahlen sind für Werte unter einer Sekunde gedacht; bei Werten über einigen Sekunden sollten ganze Zahlen verwendet werden.
Die zugehörige Option --expect100-timeout akzeptiert ebenfalls Dezimalwerte. Sie steuert, wie lange curl auf eine Antwort von „100 Continue“ wartet, bevor der Request-Body gesendet wird; der Standardwert beträgt eine Sekunde. Wenn Sie große Request-Bodies per POST an einen Server senden, der niemals „100 Continue“ zurücksendet, zahlen Sie bei jeder Anfrage diese Sekunde – verringern Sie den Wert entweder oder deaktivieren Sie die Erwartung mit -H "Expect:".
Erkennen von ins Stocken geratenen Übertragungen, bei denen es nie zu einem Timeout kommt
Hier liegt die Lücke. Eine Übertragung, bei der alle paar Sekunden ein Byte gesendet wird, gilt nie als inaktiv, sodass kein Timeout auf Verbindungsebene ausgelöst wird. Ist zudem der Wert für „--max-time
“ hoch genug für legitime große Downloads eingestellt, wird auch dieser nicht ausgelöst. Die Anfrage kriecht einfach nur so dahin.
Die Optionen „--speed-limit
“ und „--speed-time
“ kümmern sich darum. Aus dem Handbuch: „Wenn ein Download während eines Zeitraums von --speed-time
langsamer als --speed-limit
Bytes pro Sekunde ist, wird die Übertragung abgebrochen.“
curl --speed-limit 1000 --speed-time 30 -O https://example.com/large-file.zip
Bleibt der Durchsatz 30 Sekunden lang ununterbrochen unter 1.000 Byte pro Sekunde, bricht curl den Vorgang ab – wiederum mit dem Exit-Code 28. Ein Download, der sechs Stunden lang mit einer soliden Geschwindigkeit läuft, bleibt davon unberührt. Ein Download, der ins Stocken gerät, wird nach 30 Sekunden abgebrochen.
Dies ist das richtige Timeout für alles, dessen Größe nicht vorhersehbar ist, und es lässt sich gut kombinieren:
curl --connect-timeout 5 --speed-limit 1000 --speed-time 30 -O https://example.com/large-file.zip
Schnelles Abbrechen bei einem ausgefallenen Host, keine allgemeine Obergrenze, aber durchgängige Erkennung von Stillständen. Speziell für Dateidownloads gehört dieses Muster in jedes Skript – siehe unseren Leitfaden zum Herunterladen von Dateien mit curl für die dazugehörigen Optionen.
Timeouts und Wiederholungsversuche wirken sich standardmäßig negativ aufeinander aus
Das ist der Punkt, an dem viele Leute ins Straucheln geraten. Mit „
--retry N
“ lässt curl vorübergehende Fehler bis zu N-mal erneut versuchen. Was dabei leicht übersehen wird, ist, dass „--max-time
“ für jeden einzelnen Versuch gilt, nicht für den Befehl als Ganzes, und dass curl zwischen den Versuchen mit einem exponentiellen Backoff wartet, der bei einer Sekunde beginnt und sich jeweils verdoppelt.
Das hier:
curl -m 10 --retry 5 https://example.com
kann durchaus weit über eine Minute dauern: fünf Versuche von jeweils bis zu zehn Sekunden plus Backoff-Wartezeiten von 1, 2, 4, 8 und 16 Sekunden. Wenn Sie den Befehl in der Erwartung einer Obergrenze von zehn Sekunden geschrieben haben, lagen Sie um den Faktor sechs daneben.
--retry-max-time
ist die Lösung. Damit wird die Gesamtzeit für Wiederholungsversuche begrenzt:
curl -m 10 --retry 5 --retry-max-time 40 https://example.com
Nun startet curl keine neuen Versuche mehr, sobald 40 Sekunden verstrichen sind. Beachten Sie die Formulierung – nach Ablauf des Limits wird kein neuer Wiederholungsversuch gestartet, aber ein bereits laufender Versuch läuft bis zu seinem eigenen „--max-time
“ weiter. Der echte Worst-Case-Fall ist --retry-max-time
plus ein „--max-time
“.
--retry-delay
ersetzt das exponentielle Backoff durch eine feste Wartezeit, wodurch die Gesamtlaufzeit vorhersehbar wird:
curl -m 10 --retry 3 --retry-delay 2 --retry-max-time 40 https://example.com
Ein weiteres Flag, das man kennen sollte: Standardmäßig wird „--retry
“ nur bei einer begrenzten Anzahl vorübergehender Zustände ausgelöst. „--retry-all-errors
“ erweitert diesen Bereich erheblich – im Handbuch wird beschrieben, dass „alle vorübergehenden Fehler, einschließlich FTP-4xx- und 5xx-Antwortcodes“, erneut versucht werden. Dies ist bei Skripten mit instabiler Netzwerkverbindung äußerst nützlich, bei einem nicht-idempotenten POST-Aufruf jedoch äußerst gefährlich. Überlegen Sie es sich gut, bevor Sie es hinzufügen.
Timeouts bei der Nutzung eines Proxys
Fügen Sie „-x
“ hinzu, und das Zeitverhalten ändert sich, da nun zwei statt nur einer Verbindung bestehen: Ihre Verbindung zum Proxy und die Verbindung des Proxys zum Ziel.
curl -x http://user:pass@proxy.example.com:9000 --connect-timeout 10 -m 45 https://example.com
Drei Dinge verhalten sich anders als im Fall einer direkten Verbindung.
** „--connect-timeout
“ misst Ihre Verbindung zum Proxy, nicht die Verbindung des Proxys zum Ziel.** Bei HTTPS gibt curl einen ``CONNECT`
aus, und der Proxy baut die Weiterverbindung auf; die dafür benötigte Zeit wird bei ``--max-time
gezählt, nicht bei ``--connect-timeout
`. Ein kurzes Verbindungszeitlimit schützt Sie daher nicht vor einem Proxy, der Ihre Verbindung zwar umgehend annimmt, dann aber zwanzig Sekunden benötigt, um das Ziel zu erreichen.
Privathaushalts-Proxys sind zu Recht langsamer. Der Datenverkehr wird über eine echte Privatkundenverbindung geleitet, daher sind ein paar hundert Millisekunden Verzögerung eher normal als ein Fehler. Timeout-Werte, die für eine direkte Verbindung abgestimmt sind, führen zu Fehlern, die wie defekte Proxys aussehen, aber eigentlich nur physikalisch bedingt sind. Messen Sie den Durchlauf durch den Proxy mit dem oben genannten Befehl „-w
“ und legen Sie die Werte anhand dieser Messung fest, nicht anhand Ihrer Werte für direkte Verbindungen.
Fehler sind mehrdeutig. Ein Exit-Code 28 über einen Proxy könnte bedeuten, dass der Proxy langsam ist, das Ziel langsam ist oder das Ziel Ihre Anfrage absichtlich verzögert. Um dies zu unterscheiden, müssen die Komponenten separat getestet werden – ein Thema, das so umfangreich ist, dass wir einen separaten Leitfaden zum Testen von Proxys verfasst haben.
Ein praktisches Muster für Anfragen über einen Proxy: eine großzügige Zeitüberschreitung „--connect-timeout
“ (10 s), eine Zeitüberschreitung „--max-time
“, die auf der Grundlage des gemessenen Verhaltens und nicht auf der Grundlage von Vermutungen festgelegt wird, sowie kein „--retry-all-errors
“, da ein 5xx-Fehler über einen Proxy häufig bedeutet, dass das Ziel Sie ablehnt und nicht nur einen Moment lang nicht erreichbar ist – und ein erneuter Versuch verschlimmert die Situation nur noch.
Auswerten des Exit-Codes
Der Exit-Code von curl gibt Auskunft darüber, in welcher Phase ein Fehler aufgetreten ist – das sind mehr Informationen, als die meisten Skripte nutzen.
| Code | Name | Bedeutung |
|---|
| 6 | CURLE_COULDNT_RESOLVE_HOST | DNS-Fehler – kein Timeout |
| 7 | CURLE_COULDNT_CONNECT | „Verbindung zum Host oder Proxy fehlgeschlagen“ |
| 28 | CURLE_OPERATION_TIMEDOUT | „Die angegebene Timeout-Zeit wurde erreicht“ |
| 56 | CURLE_RECV_ERROR | Fehler beim Empfang von Netzwerkdaten – Verbindung wurde während der Übertragung unterbrochen |
Die Beschreibungen stammen aus der libcurl-Fehlerreferenz.
Die Unterscheidung zwischen 7 und 28 ist besonders nützlich. Code 7 bedeutet, dass die Verbindung aktiv abgelehnt wurde – es kam eine Antwort, die schnell „Nein“ sagte. Code 28 bedeutet, dass nicht rechtzeitig geantwortet wurde. Ersteres deutet in der Regel auf einen falschen Port oder einen geschlossenen Dienst hin; Letzteres deutet auf ein verlorenes Paket, eine Firewall mit stiller Filterung oder einen tatsächlich überlasteten Host hin. Ein erneuter Versuch ist bei Code 28 sinnvoll, bei Code 7 hingegen meist sinnlos.
In einem Skript: `
curl --connect-timeout 5 -m 30 -sS https://example.com > out.txt
case $? in
0) echo "ok" ;;
6) echo "dns failure" ;;
7) echo "connection refused" ;;
28) echo "timed out" ;;
*) echo "other failure" ;;
esac
Beachte, dass alle drei Timeout-Mechanismen – --max-time, --connect-timeout und das Geschwindigkeitsbegrenzungs-Paar – den Code 28 zurückgeben. Der Exit-Code gibt an, dass ein Limit erreicht wurde, nicht jedoch, welches. Wenn du dies wissen musst, verwende -w "%{time_total}" und vergleiche die Ergebnisse mit deinen konfigurierten Werten.
Wann man kein Timeout festlegen sollte
Entgegen der allgemeinen Empfehlung gibt es Fälle, in denen ein Timeout das falsche Mittel ist.
Interaktive Downloads. Wenn Sie an einem Terminal einen curl-Befehl eingeben, um eine große Datei abzurufen, sind Sie selbst das Timeout. Sie können den Fortschrittsbalken sehen und Strg+C drücken. Das Hinzufügen von -m führt hier nur zu der Ärgerlichkeit, dass der Download bei 90 % abbricht.
Lang andauernde Streams. Vom Server gesendete Ereignisse, das Verfolgen von Logs, in Chunks gesendete Antworten, die von Natur aus offen bleiben – --max-time beendet diese genau im falschen Moment. Verwenden Sie --speed-limit und --speed-time, wenn Sie einen Stillstandsdetektor benötigen, oder gar nichts.
Alles, was bereits durch eine externe Begrenzung umschlossen ist. Wenn curl unter timeout(1), einer systemd-Einheit mit RuntimeMaxSec oder einem CI-Schritt mit eigenem Budget läuft, fügt eine zweite Ebene nichts als eine zweite Zahl hinzu, die synchronisiert werden muss. Wählen Sie die Ebene, die die Fehlermeldung ausgibt, die Sie lesen möchten, und legen Sie den Wert dort fest.
Als Abhilfe bei einem langsamen Ziel. Ein Timeout sorgt dafür, dass eine langsame Anfrage schneller fehlschlägt. Es sorgt nicht dafür, dass sie erfolgreich ist. Wenn Ihr eigentliches Problem darin besteht, dass ein Server 40 Sekunden für die Antwort benötigt, sind die Optionen Caching, Paginierung, ein anderer Endpunkt oder ein Gespräch mit dem Betreiber – und an dieser Stelle wiederholen wir den Haftungsausschluss vom Anfang, da dies das häufigste Problem ist, für dessen Lösung Proxys gekauft werden, und eines der wenigen Probleme, die Proxys überhaupt nicht lösen können. Unsere Preise beginnen bei 0,79 $/GB für Privatverkehr und 0,14 $/GB für Rechenzentrumsverkehr (Stand: September 2026), und nichts davon wird einen langsamen Ursprungsserver beschleunigen.
Häufig gestellte Fragen
Wie lautet das Standard-Timeout bei curl?
Es gibt kein allgemeines Standard-Timeout – curl wartet nach dem Verbindungsaufbau unbegrenzt auf eine Antwort. Für die Verbindungsphase gilt jedoch ein Standardwert von 300 Sekunden. Aus diesem Grund ist die Option „-m“ in Skripten wichtig: Ohne sie führt eine hängende Anfrage dazu, dass das Skript hängen bleibt.
Was ist der Unterschied zwischen --max-time und --connect-timeout?
„--connect-timeout“ gilt nur für die DNS-Auflösung und die TCP/TLS/QUIC-Handshakes und wird nicht mehr angewendet, sobald die Verbindung hergestellt ist. „--max-time“ deckt den gesamten Vorgang von Anfang bis Ende ab, einschließlich der Übertragung der Antwort. Verwenden Sie beides – ein kurzes Verbindungszeitlimit für eine schnelle Fehlererkennung bei nicht erreichbaren Hosts und eine längere maximale Zeit als Obergrenze für den gesamten Vorgang.
Warum dauert mein curl-Befehl länger als das von mir festgelegte Zeitlimit?
Fast immer wegen Wiederholungsversuchen. „--max-time“ gilt pro Versuch, und „--retry“ fügt sowohl zusätzliche Versuche als auch einen exponentiellen Backoff zwischen diesen hinzu. Fügen Sie „--retry-max-time“ hinzu, um die Gesamtanzahl zu begrenzen, und denken Sie daran, dass der schlimmste Fall dieser Wert plus ein weiterer „--max-time“ ist.
Wie stelle ich ein curl-Timeout in Millisekunden ein?
Verwende einen Dezimalwert: --connect-timeout 0.25 entspricht 250 Millisekunden. Sowohl --max-time als auch --connect-timeout akzeptieren Dezimalzahlen mit einem Punkt als Trennzeichen; dies wird seit curl 7.32.0 unterstützt. Die Genauigkeit ist am besten bei Werten unter einigen Sekunden; bei größeren Werten verschlechtert sich die Genauigkeit des Bruchteils.
Welchen Exit-Code gibt curl bei einem Timeout zurück?
28, CURLE_OPERATION_TIMEDOUT. Alle drei Timeout-Mechanismen geben diesen Code zurück; er zeigt also an, dass ein Limit erreicht wurde, sagt aber nicht, welches. Vergleichen Sie dies mit 7 (Verbindung abgelehnt) und 6 (DNS-Fehler), die etwas anderes bedeuten und bei denen in der Regel kein erneuter Versuch unternommen werden sollte.
Wie kann ich einen langsamen Download abbrechen, ohne große Dateien zu beschädigen?
Verwenden Sie --speed-limit und --speed-time anstelle von --max-time. Diese brechen den Download nur ab, wenn der Durchsatz über einen längeren Zeitraum unter einem Schwellenwert bleibt; somit bleibt ein legitimer, mehrere Stunden dauernder Download unberührt, während ein ins Stocken geratener Download schnell abgebrochen wird.
Funktionieren Timeouts über einen Proxy anders?
Ja. --connect-timeout misst ausschließlich Ihre Verbindung zum Proxy; die Weiterleitung des Proxys zum Ziel wird über --max-time gemessen. Private Proxys verursachen zudem echte Latenz, sodass Werte, die für direkte Verbindungen optimiert sind, zu falschen Fehlern führen. Führen Sie die Messung über den Proxy durch und legen Sie die Werte auf dieser Grundlage fest.
Kann ich ein Timeout nur für die DNS-Auflösung festlegen?
Nicht als separate Option – DNS ist in „--connect-timeout“ enthalten. Wenn Sie die DNS-Auflösung speziell begrenzen möchten, führen Sie die Auflösung separat durch und übergeben Sie das Ergebnis mit „--resolve“, wodurch die eigene Suche von curl vollständig übersprungen wird.
Zusammenfassung
Zwei Optionen decken fast jeden Fall ab: „--connect-timeout“ für einen schnellen Abbruch, wenn ein Host nicht erreichbar ist, und „--max-time“ für die allgemeine Obergrenze. Legen Sie beide Werte in jedem Skript fest – und zwar immer. Die Standardeinstellung, unendlich lange zu warten, ist eine vernünftige Wahl für ein interaktives Tool, für die Automatisierung jedoch eine schlechte.
Die beiden Punkte, an denen viele Nutzer scheitern, sind es wert, noch einmal wiederholt zu werden. „--max-time“ gilt pro Versuch; daher muss bei jeder Verwendung von „--retry“ zusätzlich „--retry-max-time“ angegeben werden, sonst wird aus Ihrem 10-Sekunden-Befehl ein 1-Minuten-Befehl. Und ein festes Zeitlimit ist das falsche Mittel für Übertragungen mit unvorhersehbarer Größe – verwenden Sie „--speed-limit“ zusammen mit „--speed-time“, und Sie erhalten einen Stillstandsdetektor, der legitime, lang andauernde Downloads unberührt lässt.
Legen Sie die Werte anhand von Messungen fest und nicht anhand einer runden Zahl, die Ihnen richtig erschien. Ein Durchlauf von curl -w für Ihr tatsächliches Ziel liefert Ihnen eine Verteilung, und ein aus dieser Verteilung abgeleitetes Timeout schlägt erst dann fehl, wenn tatsächlich etwas nicht stimmt – und nicht schon, wenn das Netzwerk mal einen schlechten Nachmittag hat.
