curl ile Zaman Aşımı Nasıl Ayarlanır: Seçenekler, Örnekler, Hatalar

Komutlara geçmeden önce kısa bir açıklama: Biz Geonode olarak proxy satışı yapıyoruz; bu nedenle şunu baştan dürüstçe belirtmek gerekir ki, curl zaman aşımı neredeyse hiçbir zaman bir proxy sorunu değildir. İstekleriniz sadece yavaş çalışan bir sunucuya, hizmet dışı kalan bir ana bilgisayara veya paketleri sessizce düşüren bir güvenlik duvarına karşı zaman aşımına uğruyorsa, bunları bizim üzerinden yönlendirmek faturadan başka hiçbir şeyi değiştirmez. Proxy'ler, sorunun isteğinizin nereden geldiği gibi göründüğü durumlarda yardımcı olur — coğrafi kısıtlamalı içerik, adresinize göre belirlenen hız sınırlamaları, engellenmiş bir IP gibi. Yavaş bir sunucuyu hızlı hale getirmezler. Önce zaman aşımlarınızı doğru ayarlayın; belki de başka hiçbir şeye ihtiyacınız olmadığını fark edeceksiniz.

Doğru. İşte çoğu kişinin zor yoldan öğrendiği bir gerçek: curl'da varsayılan genel zaman aşımı yoktur. Varsayılan bağlantı zaman aşımı 300 saniyedir, ancak bağlantı kurulduktan sonra curl, asla tam olarak gelmeyecek bir yanıtı sonsuza kadar beklemeye devam eder. Cron'da çalışan bir kabuk betiğinde bu, asla bitmeyen bir iş ve kimsenin temizlemediği bir kilit dosyası anlamına gelir.

Önemli Olan İki Zaman Aşımı

Diğer her şey bu ikisinin birer detaylandırmasıdır.

--max-time

(kısaltılmış hali -m

) tüm işlemi sınırlar. curl kılavuzundan: “Aktarım işleminin sürmesine izin verdiğiniz maksimum süre (saniye cinsinden).” Bağlantı, el sıkışma, istek, yanıt; hepsi dahil. Sınır aşıldığında, curl işlemi yarıda keser ve 28 koduyla sonlanır.

curl -m 10 https://example.com

Toplam on saniye; bu süre dolduğunda, curl hangi aşamada olursa olsun işlemi sonlandırır.

--connect-timeout

yalnızca kurulum aşamasını sınırlar. Kılavuz, bunun neleri içerdiği konusunda nettir: "Bağlantı aşaması, DNS araması ve istenen TCP, TLS veya QUIC el sıkışmaları tamamlandığında tamamlanmış sayılır." Bağlantı kurulduktan sonra bu seçenek geçerliliğini yitirir.

curl --connect-timeout 3 https://example.com

Adın çözümlenmesi ve el sıkışmalarının tamamlanması için üç saniye. Bundan sonra curl, aktarımın sürmesi kadar bekler.

Uygulamada her ikisine de ihtiyaç duyarsınız ve bunlar farklı sorulara yanıt verir:

Seçenek	Kapsadığı alan	Tipik değer	Neye karşı koruma sağlar
`--connect-timeout`

| Tüm işlem | 10–60 saniye, iş yüküne bağlı | Yavaş yanıtlar, durmuş aktarımlar, bitmeyen akışlar |

Toplam:

curl --connect-timeout 5 -m 30 https://example.com

Bağlanmak beş saniye, tüm işlem otuz saniye sürer. Ana bilgisayara ulaşılamıyorsa, otuz saniye yerine beş saniyede hata alırsınız; bu, bin URL'den oluşan bir listeyi tek tek tararken çok büyük önem taşır.

Tahmin Değil, Gerçek Değerleri Seçmek

Genel olarak izlenen yaklaşım, yuvarlak bir sayı seçip bir şey ters gittiğinde bu sayıyı yukarı doğru ayarlamaktır. Bu yaklaşım, zaman aşımı süresinin artık hiçbir işe yaramayacağı kadar büyük bir değere doğru ilerler.

Daha iyi bir yöntem ise tek bir ek komut gerektirir. curl, sürenin gerçekte nereye harcandığını bildirebilir:

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

Bunu gerçek hedefinize karşı yirmi veya otuz kez çalıştırdığınızda, bir tahmin yerine bir dağılım elde edersiniz. Ardından:

time_appconnect adresinden --connect-timeout değerini ayarlayın. p95 değerini alın ve kabaca ikiye katlayın. Bağlantı süresi, ağ gidiş-dönüş süreleri tarafından belirlenir ve oldukça sabittir; normalden iki kat daha uzun sürüyorsa, bu sadece yavaşlıktan ziyade gerçekten bir sorun olduğu anlamına gelir.

--max-time değerini time_total adresinden ayarlayın. Burada çarpan daha cömert olmalıdır — p95 değerinin üç ila beş katı — çünkü toplam süre, yanıt boyutuna ve sunucu yüküne bağlıdır ve her ikisi de doğal olarak değişkenlik gösterir. Sıkı bir --max-time değeri, sıradan kötü günlerde bile başarısız olan dengesiz komut dosyaları üretir.

İş yüküne özgü iki ayar. Büyük dosyalar indiriyorsanız, --max-time tamamen yanlış bir araçtır; çünkü meşru bir indirme işlemi makul herhangi bir sabit sınırı aşabilir — bunun yerine aşağıdaki hıza dayalı seçeneği kullanın. Sunucu tarafında gerçek işler yapan bir API'yi çağırıyorsanız, API'nin kendi zaman aşımı süresini öğrenin ve kendi zaman aşımı sürenizi biraz daha yüksek ayarlayın; 12 saniyede yanıt veren bir hizmet için 10 saniyelik zaman aşımı ayarlamak, işin bedelini ödeyip sonucu çöpe atmak anlamına gelir.

Kesirli Saniye ve Milisaniye Hassasiyeti

Her iki seçenek de, yerel ayarınızdan bağımsız olarak ayırıcı olarak nokta kullanılarak ondalık sayıları kabul eder. Bu özellik, curl 7.32.0 sürümünden itibaren desteklenmektedir.

curl --connect-timeout 0.5 -m 2.5 https://example.com

Bağlanmak için yarım saniye, toplamda iki buçuk saniye. Durum kontrolleri ve her hata için tam bir saniye bekleme süresinin birikmesi söz konusu olan döngüler için kullanışlıdır.

Bilmeniz gereken bir uyarı: değer arttıkça hassasiyet azalır. curl belgelerinde, belirtilen zaman aşımı süresinin ondalık hassasiyeti arttıkça gerçek zaman aşımı süresinin doğruluğunun azaldığı belirtilmektedir. --max-time 30.001 yazmak, --max-time 30 yazmaktan anlamlı bir fark yaratmaz. Ondalık sayılar saniyenin altındaki değerler içindir; birkaç saniyenin üzerindeki değerler için tam sayılar kullanın.

İlgili --expect100-timeout seçeneği de ondalık sayıları kabul eder. Bu seçenek, curl’un istek gövdesini göndermeden önce bir 100 Continue yanıtını ne kadar süre bekleyeceğini kontrol eder; varsayılan değer bir saniyedir. Hiçbir zaman 100 Continue yanıtı göndermeyen bir sunucuya büyük istek gövdeleri POST ediyorsanız, her istek için bu bir saniyeyi harcarsınız — bu süreyi kısaltın ya da -H "Expect:" seçeneğiyle bu beklentiyi devre dışı bırakın.

Zaman Aşımı Olmayan Takılan Aktarımları Yakalamak

İşte sorun burada. Birkaç saniyede bir bayt ileten bir aktarım asla boşta kalmaz, dolayısıyla bağlantı düzeyinde zaman aşımı tetiklenmez; ayrıca, --max-time

değeri meşru büyük indirmeler için yeterince yüksek ayarlanmışsa, bu da tetiklenmez. İstek sadece çok yavaş ilerler.

``--speed-limit`

ve ``--speed-time

bu durumu ele alır. Kılavuzdan alıntı: "Bir indirme işlemi, ``--speed-time

süresi boyunca saniyede ``--speed-limit

` bayttan daha yavaşsa, aktarım iptal edilir."

curl --speed-limit 1000 --speed-time 30 -O https://example.com/large-file.zip

Verim, 30 saniye boyunca kesintisiz olarak saniyede 1000 baytın altında kalırsa, curl işlemi sonlandırır — yine 28 çıkış koduyla. Sağlıklı bir hızda altı saat süren bir indirme işlemine dokunulmaz. Tıkanan bir indirme işlemi ise otuz saniye içinde sonlandırılır.

Bu, boyutu öngörülemeyen her şey için doğru zaman aşımı süresidir ve iyi bir denge sağlar:

curl --connect-timeout 5 --speed-limit 1000 --speed-time 30 -O https://example.com/large-file.zip

Çalışmayan bir sunucuda hızlı hata, genel bir sınırlama yok, ancak baştan sona bir durma algılayıcısı. Özellikle dosya indirmeleri için bu model her komut dosyasına dahil edilmelidir — ilgili seçenekler için curl ile dosya indirme kılavuzumuza bakın.

Zaman Aşımları ve Yeniden Denemeler Varsayılan Olarak Uyumsuz Çalışır

Bu, kullanıcıların kafasını karıştıran kısımdır.

--retry N

, curl'un geçici hataları N defaya kadar yeniden denemesini sağlar. Gözden kaçması kolay olan nokta, --max-time

'un komutun tamamına değil, her denemeye uygulanması ve curl'un denemeler arasında bir saniyeden başlayıp ikiye katlanan üstel bir geri çekilme süresiyle beklemesidir.

Dolayısıyla şunu:

curl -m 10 --retry 5 https://example.com

işlemi meşru olarak bir dakikadan çok daha uzun sürebilir: her biri en fazla on saniye süren beş deneme, artı 1, 2, 4, 8 ve 16 saniyelik geri çekilme bekleme süreleri. Eğer bunu on saniyelik bir üst sınır bekleyerek yazdıysanız, altı kat yanılmış olursunuz.

--retry-max-time

komutu bu sorunu çözer. Bu komut, yeniden deneme için harcanan toplam süreyi sınırlar:

curl -m 10 --retry 5 --retry-max-time 40 https://example.com

Artık curl, 40 saniye geçtikten sonra yeni denemeler başlatmaz. İfadeye dikkat edin — sınır aşıldıktan sonra yeni bir yeniden deneme başlatmaz, ancak halihazırda devam eden bir deneme kendi --max-time

'una kadar devam eder. Gerçek en kötü durum, --retry-max-time

artı bir --max-time

'dir.

--retry-delay

, üstel geri çekilmeyi sabit bir bekleme süresiyle değiştirir; bu da toplam çalışma süresini öngörülebilir hale getirir:

curl -m 10 --retry 3 --retry-delay 2 --retry-max-time 40 https://example.com

Bilmeniz gereken bir bayrak daha var: varsayılan olarak --retry

yalnızca dar bir geçici durumlar kümesinde tetiklenir. --retry-all-errors

bunu önemli ölçüde genişletir — kılavuzda bu, "FTP 4xx ve 5xx yanıt kodları dahil tüm geçici hataları" yeniden deneme olarak tanımlanır. Bu, ağ bağlantısının dengesiz olduğu komut dosyalarında gerçekten yararlıdır; ancak idempotent olmayan bir POST isteği söz konusu olduğunda gerçekten tehlikelidir. Eklemeden önce iyice düşünün.

Proxy Üzerinden Bağlandığınızda Zaman Aşımları

-x

adresini eklediğinizde zamanlama farklılık gösterir; çünkü artık tek bir bağlantı yerine iki bağlantı vardır: sizden proxy’ye ve proxy’den hedefe.

curl -x http://user:pass@proxy.example.com:9000 --connect-timeout 10 -m 45 https://example.com

Doğrudan bağlantı durumuna kıyasla üç husus farklı şekilde davranır.

**--connect-timeout

, proxy’den hedefe olan atlamayı değil, sizden proxy’ye olan atlamayı ölçer.** HTTPS için, curl bir CONNECT

komutu verir ve proxy ileriye dönük bağlantıyı kurar; bunun sürmesi, --max-time

'a eklenir, --connect-timeout

'a değil. Dolayısıyla, kısa bir bağlantı zaman aşımı, bağlantınızı hemen kabul eden ancak hedefe ulaşmak için yirmi saniye süren bir proxy'ye karşı sizi korumayacaktır.

Ev tipi proxy'ler, doğal olarak daha yavaştır. Trafik gerçek bir tüketici bağlantısı üzerinden çıktığı için, birkaç yüz milisaniyelik ek gecikme bir hata değil, normaldir. Doğrudan bağlantı için ayarlanmış zaman aşımı değerleri, bozuk proxy'ler gibi görünen ancak aslında sadece fiziksel nedenlerden kaynaklanan hatalara yol açacaktır. Yukarıdaki -w

komutuyla proxy üzerinden ölçüm yapın ve değerleri doğrudan bağlantı rakamlarınıza göre değil, bu ölçüme göre ayarlayın.

Hata durumları belirsizdir. Bir proxy üzerinden alınan 28 çıkış kodu, proxy'nin yavaş olduğu, hedefin yavaş olduğu veya hedefin isteğinizi kasıtlı olarak geciktirdiği anlamına gelebilir. Bunları ayırt etmek için bileşenleri ayrı ayrı test etmek gerekir; bu konu o kadar kapsamlıdır ki, proxy testlerine ilişkin ayrı bir kılavuz hazırladık.

Proxy üzerinden yapılan istekler için pratik bir yaklaşım şöyledir: cömert bir --connect-timeout

(10 saniye), umuttan ziyade ölçülen davranışa göre ayarlanmış bir --max-time

ve --retry-all-errors

kullanmamak; çünkü proxy üzerinden 5xx hatası genellikle hedefin geçici bir sorun yaşaması değil, sizi reddettiği anlamına gelir ve yeniden denemek durumu daha da kötüleştirir.

Çıkış Kodunu Okuma

curl'un çıkış kodu, hangi aşamada hata oluştuğunu gösterir; bu, çoğu komut dosyasının kullanmaya zahmet etmediği kadar fazla bilgi sağlar.

Kod	Adı	Anlamı
6	`CURLE_COULDNT_RESOLVE_HOST`	DNS hatası — zaman aşımı söz konusu değil
7	`CURLE_COULDNT_CONNECT`	"Host veya proxy'ye connect() işlemi başarısız"
28	`CURLE_OPERATION_TIMEDOUT`	"Belirtilen zaman aşımı süresine ulaşıldı"
56	`CURLE_RECV_ERROR`	Ağ verilerinin alınmasında hata — aktarım sırasında bağlantı kesildi

Açıklamalar libcurl hata referansından alınmıştır.

7 ve 28 kodları arasındaki ayrım önemlidir. Kod 7, bağlantının aktif olarak reddedildiğini gösterir — bir yanıt geldi ve hızlı bir şekilde "hayır" denildi. Kod 28 ise zamanında yanıt gelmediğini gösterir. İlki genellikle yanlış bir bağlantı noktası veya kapalı bir hizmeti işaret eder; ikincisi ise düşen bir paket, sessizce filtreleme yapan bir güvenlik duvarı veya gerçekten aşırı yüklenmiş bir ana bilgisayarı işaret eder. 28 kodu için yeniden denemek mantıklıdır, ancak 7 kodu için genellikle anlamsızdır.

Bir betik içinde:

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

--max-time, --connect-timeout ve hız sınırı çifti olmak üzere üç zaman aşımı mekanizmasının da 28 kodunu döndürdüğüne dikkat edin. Çıkış kodu, bir sınıra ulaşıldığını gösterir, hangisine ulaşıldığını değil. Bunu öğrenmeniz gerekiyorsa, -w "%{time_total}" komutunu kullanın ve yapılandırdığınız değerlerle karşılaştırın.

Ne Zaman Zaman Aşımı Ayarlanmamalı

Genel tavsiyenin aksine, zaman aşımının yanlış bir araç olduğu durumlar da vardır.

Etkileşimli indirmeler. Büyük bir dosyayı almak için terminalde bir curl komutu yazıyorsanız, zaman aşımı sizsiniz. İlerleme çubuğunu görebilir ve Ctrl-C tuşlarına basabilirsiniz. Burad-m'i eklemek, indirmenin %90'da kesilmesinden kaynaklanan bir sıkıntı yaratmaktan başka bir işe yaramaz.

Uzun süreli akışlar. Sunucu tarafından gönderilen olaylar, günlük izleme, tasarım gereği açık kalan parçalı yanıtlar — --max-time, bunları tam da yanlış anda sonlandıracaktır. Bekleme algılayıcısına ihtiyacınız varsa --speed-limit ve --speed-time kullanın ya da hiç bir şey kullanmayın.

Zaten harici bir sınırla sınırlandırılmış her şey. curl, timeout(1) altında, RuntimeMaxSec içeren bir systemd biriminde veya kendi bütçesi olan bir CI adımında çalışıyorsa, ikinci bir katman senkronizasyonu sağlamak için sadece ikinci bir sayı ekler. Okumak istediğiniz hata mesajını üreten katmanı seçin ve ayarı orada yapın.

Yavaş bir hedef için çözüm olarak. Zaman aşımı, yavaş bir isteğin daha hızlı başarısız olmasına neden olur. Başarılı olmasını sağlamaz. Asıl sorununuz bir sunucunun yanıt vermesinin 40 saniye sürmesi ise, seçenekleriniz önbellekleme, sayfalandırma, farklı bir uç nokta veya sunucuyu yöneten kişiyle görüşmektir — ve burada, en başta yer alan uyarıyı tekrarlayacağız, çünkü bu, insanların proxy satın almalarının en yaygın nedeni ve proxy'lerin hiç çözemediği birkaç sorundan biridir. Fiyatlandırmamız, Eylül 2026 itibarıyla konut trafiği için GB başına 0,79 $ ve veri merkezi trafiği için GB başına 0,14 $'dan başlar; bunların hiçbiri yavaş bir kaynak sunucuyu hızlandırmaz.

Sıkça Sorulan Sorular

Curl’da varsayılan zaman aşımı süresi nedir?

Genel bir varsayılan zaman aşımı süresi yoktur — curl, bağlantı kurulduktan sonra yanıtı süresiz olarak bekler. Bağlantı aşaması için ise varsayılan süre 300 saniyedir. Bu nedenle komut dosyalarında -m seçeneği önemlidir: bu seçenek olmadan, takılan bir istek komut dosyasının da takılmasına neden olur.

--max-time ile `--connect-timeout` arasındaki fark nedir?

yalnızca DNS çözümlemeyi ve TCP/TLS/QUIC el sıkışma işlemlerini kapsar ve bağlantı kurulduktan sonra geçerliliğini yitirir. --max-time ise yanıt aktarımı da dahil olmak üzere baştan sona tüm işlemi kapsar. Her ikisini de kullanın — çalışmayan ana bilgisayarlarda hızlı hata için kısa bir bağlantı zaman aşımı, genel üst sınır için daha uzun bir maksimum süre.

Neden curl komutum, ayarladığım zaman aşım süresinden daha uzun sürüyor?

Neredeyse her zaman yeniden denemeler yapılır. --max-time her deneme için geçerlidir ve --retry hem ekstra denemeler hem de bunlar arasındaki üstel geri çekilme ekler. Toplamı sınırlamak için --retry-max-time ekleyin ve en kötü durumda bu değere bir tane daha --max-time ekleneceğini unutmayın.

curl zaman aşımını milisaniye cinsinden nasıl ayarlayabilirim?

Ondalık bir değer kullanın: --connect-timeout 0.25, 250 milisaniyeye karşılık gelir. Hem --max-time hem de --connect-timeout, curl 7.32.0 sürümünden itibaren desteklenen nokta ayırıcılı ondalık sayıları kabul eder. Hassasiyet, birkaç saniyenin altında en iyi sonuç verir; daha büyük değerlerde ondalık kısmın doğruluğu düşer.

Zaman aşımı durumunda curl hangi çıkış kodunu döndürür?

28, CURLE_OPERATION_TIMEDOUT. Üç zaman aşımı mekanizmasının tümü bu kodu döndürür; dolayısıyla kod, bir sınıra ulaşıldığını belirtir ancak hangisi olduğunu söylemez. Bu kodu, farklı anlamlara gelen ve genellikle yeniden denenmemesi gereken 7 (bağlantı reddedildi) ve 6 (DNS hatası) kodlarıyla karşılaştırın.

Büyük dosyaları kesintiye uğratmadan yavaş bir indirme işlemini zaman aşımına uğratmak için ne yapmalıyım?

--max-time yerine --speed-limit ve --speed-time kullanın. Bunlar, yalnızca verim uzun bir süre boyunca bir eşik değerin altında kaldığında işlemi sonlandırır; böylece birkaç saat süren normal bir indirme işlemi etkilenmezken, takılmış bir indirme işlemi hızla sonlandırılır.

Zaman aşımı, proxy üzerinden farklı şekilde mi çalışır?

Evet. --connect-timeout yalnızca proxy'ye olan bağlantınızı ölçer; proxy'nin hedefe olan bağlantısı ise --max-time kapsamında değerlendirilir. Ev tipi proxy'ler de gerçek gecikme süresi ekler, bu nedenle doğrudan bağlantılar için ayarlanan değerler yanlış hata sonuçlarına yol açar. Ölçümü proxy üzerinden yapın ve değerleri buna göre ayarlayın.

Yalnızca DNS çözümlemesi için bir zaman aşımı ayarlayabilir miyim?

Ayrı bir seçenek olarak değil — DNS, --connect-timeout içinde yer alır. DNS'yi özel olarak sınırlamanız gerekiyorsa, çözümlemeyi ayrı olarak yapın ve sonucu --resolve ile aktarın; bu, curl'ün kendi arama işlemini tamamen atlar.

Sonuç

Neredeyse her durumu kapsayan iki seçenek vardır: Bir ana bilgisayara ulaşılamadığında hızlı hata için --connect-timeout, genel üst sınır için --max-time. Her komut dosyasında her zaman ikisini de ayarlayın. Varsayılan olarak “sonsuza kadar bekleme” seçeneği, etkileşimli bir araç için makul bir seçimdir; ancak otomasyon için berbat bir seçimdir.

Kullanıcıların sıkça takıldığı iki noktayı tekrarlamakta fayda var. --max-time değeri her deneme için geçerlidir; bu nedenle, --retry kullanıldığında mutlaka --retry-max-time ile birlikte kullanılmalıdır, aksi takdirde on saniyelik komutunuz bir dakikalık bir komuta dönüşür. Ayrıca, sabit bir zaman sınırı, boyutu öngörülemeyen aktarımlar için yanlış bir araçtır — --speed-limit ile --speed-time birlikte kullanıldığında, meşru uzun indirmeleri etkilemeyen bir durma algılayıcısı elde edersiniz.

Değerleri, kulağa doğru gelen yuvarlak bir sayıdan ziyade ölçüm sonuçlarına göre ayarlayın. Gerçek hedefinize karşı curl -w komutunu bir kez çalıştırdığınızda bir dağılım elde edersiniz; dağılımdan türetilen bir zaman aşımı, ağın sıradan bir kötü gününde değil, gerçekten bir sorun olduğunda hata verir.

curl ile Zaman Aşımı Nasıl Ayarlanır (+Örnekler)