manuel curl

8/12/2019 Manuel cURL

1/13

Related:

Man PageFAQ

Front Page

Docs Index

Bug Report

CA Extract

CompaniesComparison

Copyright

curl Man Page

Dependencies

Donate!

FAQ

Features

History

HTTP Cookies

HTTP Scripting

Install

Known Bugs

Legal

Manual

mk-ca-bundle

Programs

Related Tools

Release Table

Security

SSL Certs

Thanks

TODO

Version Nums

Vulnerabilities

Search

Sponsors:Haxx

cURL Docs Manual

LATEST VERSI ON

You al ways f i nd news about what ' s goi ng on as wel l as t he l at est ver si ons f r omt he cur l web pages, l ocated at:

ht tp: / / cur l . haxx. seSI MPLE USAGE

Get t he mai n page f r om Netscape' s web- ser ver :

cur l ht t p: / / www. net scape. com/

Get t he README f i l e the user' s home di r ect ory at f unet ' s f t p- server :

cur l f t p: / / f t p. f unet . f i / README

Get a web page f r om a server usi ng por t 8000:

cur l ht t p: / / www. wei r dserver . com: 8000/

Get a di r ectory l i st i ng of an FTP si t e:cur l f t p: / / cool . haxx. se/

Get t he def i ni t i on of cur l f r om a di cti onar y:

cur l di ct : / / di ct . org/ m: cur l

Fet ch t wo documents at once:

cur l f t p: / / cool . haxx. se/ ht t p: / / www. wei r dserver . com: 8000/

Get a f i l e of f an FTPS ser ver :

cur l f tps: / / f i l es. are. secure. com/ secrets. txt

or use t he more appr opr i at e FTPS way to get t he same f i l e:

cur l - - f t p- s sl f t p: / / f i l es. are. secure. com/ secret s. t xt

Get a f i l e f r oman SSH server usi ng SFTP:

cur l - u user name sf t p: / / shel l . exampl e. com/ et c/ i ssue

Get a f i l e f r oman SSH server usi ng SCP usi ng a pr i vat e key t o aut hent i cate:

cur l - u username: - - key ~/ . ssh/ i d_dsa - - pubkey ~/ . ssh/ i d_dsa. pub \scp: / / shel l . exampl e. com/ ~/ per sonal . t xt

Get t he mai n page f r om an I Pv6 web ser ver :

cur l "ht t p: / / [ 2001: 1890: 1112: 1: : 20] / "

DOWNLOAD TO A FI LE

Get a web page and st ore i n a l ocal f i l e wi t h a speci f i c name:

cur l - o t hat page. ht ml htt p: / / www. net scape. com/

Get a web page and st ore i n a l ocal f i l e, make t he l ocal f i l e get t he name of t he r emot e document ( i f no f i l e name part i s speci f i ed i n t he URL, t hi s wi l l f ai l ) :

cur l - O ht t p: / / www. netscape. com/ i ndex. ht ml

Fet ch t wo f i l es and st ore t hemwi t h t hei r r emote names:

cur l - O www. haxx. se/ i ndex. ht ml - O curl . haxx. se/ downl oad. ht mlUSI NG PASSWORDSFTP

To f t p f i l es usi ng name+passwd, i ncl ude t hemi n t he URL l i ke:

RL - Manual file:///C:/Documents and Settings/user/My Documents/Downloads/cURL...

13 19/07/2014 18:40


2/13

cur l f t p: / / name: passwd@machi ne. domai n: por t / f ul l / pat h/ t o/ f i l e

or speci f y t hem wi t h t he - u f l ag l i ke

cur l - u name: passwd f t p: / / machi ne. domai n: por t / f ul l / pat h/ t o/ f i l e

FTPS

I t i s j ust l i ke f or FTP, but you may al so want t o speci f y and use

SSL-speci f i c opt i ons f or cert i f i cat es et c.

Not e t hat usi ng FTPS: / / as pr ef i x i s t he "i mpl i ci t " way as descri bed i n t he

st andards whi l e t he r ecommended "expl i ci t " way i s done by usi ng FTP: / / and the - - f t p- ssl opt i on.SFTP / SCP

Thi s i s si mi l ar t o FTP, but you can speci f y a pr i vat e key t o use i nst ead of

a password. Note t hat t he pr i vat e key may i t sel f be pr otected by a password t hat i s unr el ated t o t he l ogi n password of t he r emote syst em. I f you pr ovi de a pr i vat e key f i l e you must al so pr ovi de a publ i c key f i l e.HTTP

Cur l al so support s user and password i n HTTP URLs, t hus you can pi ck a f i l e

l i ke:

cur l ht t p: / / name: passwd@machi ne. domai n/ f ul l / pat h/ t o/ f i l e

or speci f y user and password separat el y l i ke i n

cur l - u name: passwd ht t p: / / machi ne. domai n/ f ul l / pat h/ t o/ f i l e

HTTP of f ers many di f f erent methods of aut hent i cat i on and cur l support s

sever al : Basi c, Di gest , NTLM and Negoti ate. Wi t hout t el l i ng whi ch met hod t o use, curl def aul t s to Basi c. You can al so ask cur l t o pi ck t he most secur e ones out of t he ones t hat t he server accept s f or t he gi ven URL, by usi ng - - anyaut h.

NOTE! Accor di ng t o the URL speci f i cat i on, HTTP URLs can not cont ai n a user and password, so t hat st yl e wi l l not work when usi ng cur l vi a a pr oxy, even t hough curl al l ows i t at other t i mes. When usi ng a pr oxy, you _must _ use t he - u st yl e f or user and password.HTTPS

Probabl y most commonl y used wi t h pr i vat e cer t i f i cates, as expl ai ned bel ow.

PROXYcur l support s bot h HTTP and SOCKS pr oxy servers , wi t h opt i onal aut hent i cat i on.

I t does not have speci al support f or FTP pr oxy ser ver s si nce ther e ar e no st andards f or t hose, but i t can st i l l be made to work wi t h many of t hem. You can al so use both HTTP and SOCKS pr oxi es t o t r ansf er f i l es t o and f r om FTP servers.Get an f t p f i l e usi ng an HTTP pr oxy named my- proxy t hat uses por t 888:

cur l - x my- pr oxy: 888 f t p: / / f t p. l eachsi t e. com/ READMEGet a f i l e f r oman HTTP ser ver t hat r equi r es user and password, usi ng the

same proxy as above:

cur l - u user : passwd - x my- pr oxy: 888 ht t p: / / www. get . t hi s/Some pr oxi es r equi r e speci al aut hent i cat i on. Speci f y by usi ng - U as above:

cur l - U user : passwd - x my- pr oxy: 888 ht t p: / / www. get . t hi s/

A comma- separat ed l i st of host s and domai ns whi ch do not use the proxy can

be speci f i ed as:

cur l - - nopr oxy l ocal host , get . t hi s - x my-proxy: 888 ht t p: / / www. get . t hi s/

I f t he pr oxy i s speci f i ed wi t h - - pr oxy1. 0 i nst ead of - - pr oxy or - x, t hen

cur l wi l l use HTTP/ 1. 0 i nst ead of HTTP/ 1. 1 f or any CONNECT at t empt s.cur l al so suppor t s SOCKS4 and SOCKS5 proxi es wi t h - - socks4 and - - socks5.


13 19/07/2014 18:40


3/13

See al so the envi r onment var i abl es Cur l support s t hat of f er f ur t her pr oxy cont r ol .Most FTP pr oxy server s ar e set up to appear as a normal FTP server f r omt he

cl i ent ' s per spect i ve, wi t h speci al commands t o sel ect t he remote FTP ser ver . cur l support s t he - u, - Q and - - f t p- account opt i ons t hat can be used t o set up t r ansf ers t hr ough many FTP pr oxi es. For exampl e, a f i l e can be upl oaded to a remote FTP server usi ng a Bl ue Coat FTP proxy wi t h the opt i ons:

cur l - u "Remot e- FTP- User name@r emote. f t p. ser ver Proxy- User name: Remot e- Pass" \

- - f t p- account Proxy- Password -- upl oad- f i l e l ocal - f i l e \f t p: / / my- f t p. pr oxy. ser ver : 21/ r emote/ upl oad/ path/

See t he manual f or your FTP pr oxy t o deter mi ne the f orm i t expects t o set up

t r ansf er s, and cur l ' s - v opt i on t o see exact l y what cur l i s sendi ng.RANGES

HTTP 1. 1 i nt r oduced byte- r anges. Usi ng thi s, a cl i ent can request t o get onl y one or more subpart s of a speci f i ed document . Cur l support s t hi s wi t h the - r f l ag.

Get t he f i r st 100 byt es of a document :

cur l - r 0- 99 ht t p: / / www. get . t hi s/

Get t he l ast 500 byt es of a document :

cur l - r - 500 ht t p: / / www. get . t hi s/

Cur l al so support s si mpl e ranges f or FTP f i l es as wel l . Then you can onl y speci f y st ar t and st op posi t i on.

Get t he f i r st 100 byt es of a document usi ng FTP:

cur l - r 0- 99 f t p: / / www. get . t hi s/ READMEUPLOADI NGFTP / FTPS / SFTP / SCP

Upl oad al l dat a on st di n to a speci f i ed ser ver :

cur l - T - f t p: / / f t p. upl oad. com/ myf i l e

Upl oad data f r om a speci f i ed f i l e, l ogi n wi t h user and passwor d:

cur l - T upl oadf i l e -u user : passwd f t p: / / f t p. upl oad. com/ myf i l e

Upl oad a l ocal f i l e t o the r emote si t e, and use the l ocal f i l e name at t he r emote

si t e t oo:

cur l - T upl oadf i l e -u user : passwd f t p: / / f t p. upl oad. com/

Upl oad a l ocal f i l e t o get appended t o the r emote f i l e:

cur l - T l ocal f i l e - a f t p: / / f t p. upl oad. com/ remot ef i l e

Cur l al so support s f t p upl oad t hr ough a pr oxy, but onl y i f t he pr oxy i s conf i gur ed t o al l ow t hat ki nd of t unnel i ng. I f i t does, you can r un cur l i n a f ashi on si mi l ar to:

cur l - - proxyt unnel - x proxy: port - T l ocal f i l e ft p. upl oad. comHTTP

Upl oad al l data on st di n t o a speci f i ed HTTP si t e:

cur l - T - ht t p: / / www. upl oad. com/ myf i l e

Note t hat t he HTTP ser ver must have been conf i gur ed t o accept PUT bef ore

t hi s can be done successf ul l y.

For other ways t o do HTTP dat a upl oad, see t he POST sect i on bel ow.VERBOSE / DEBUG

I f curl f ai l s where i t i sn' t supposed t o, i f t he servers don' t l et you i n, i f you can' t under st and t he r esponses: use t he - v f l ag t o get ver bose


13 19/07/2014 18:40


4/13

f et chi ng. Cur l wi l l out put l ot s of i nf o and what i t sends and r ecei ves i n or der t o l et t he user see al l cl i ent - ser ver i nt er acti on ( but i t won' t show you t he actual dat a) .

cur l - v f t p: / / f t p. upl oad. com/

To get even mor e detai l s and i nf or mat i on on what cur l does, t r y usi ng t he - - t r ace or - - t r ace- asci i opt i ons wi t h a gi ven f i l e name t o l og t o, l i ke thi s :

cur l - - t r ace t r ace. t xt www. haxx. se

DETAI LED I NFORMATI ON

Di f f er ent pr ot ocol s pr ovi de di f f er ent ways of get t i ng det ai l ed i nf or mat i on about speci f i c f i l es/ document s. To get cur l t o show det ai l ed i nf or mati on about a si ngl e f i l e, you shoul d use - I / - - head opt i on. I t di spl ays al l avai l abl e i nf o on a si ngl e f i l e f or HTTP and FTP. The HTTP i nf ormati on i s a l ot more ext ensi ve.

For HTTP, you can get t he header i nf ormat i on ( t he same as - I woul d show) shown bef ore t he data by usi ng - i / - - i ncl ude. Cur l under st ands the - D/ - - dump-header opti on when gett i ng f i l es f r omboth FTP and HTTP, and i t wi l l t hen store t he header s i n t he speci f i ed f i l e.

St ore t he HTTP header s i n a separat e f i l e ( header s. t xt i n the exampl e) :

cur l - - dump- header header s. t xt cur l . haxx. se

Note t hat header s st ored i n a separat e f i l e can be ver y usef ul at a l ater

t i me i f you want cur l t o use cooki es sent by t he server . More about t hat i n t he cooki es secti on.POST ( HTTP)

I t ' s easy t o post dat a usi ng cur l . Thi s i s done usi ng t he - d opt i on. The post data must be url encoded.

Post a si mpl e "name" and "phone" guest book.

cur l - d " name=Raf ael %20Sagul a&phone=3320780" \ht t p: / / www. where. com/ guest . cgi

How t o post a f orm wi t h cur l , l esson #1:

Di g out al l t he t ags i n t he f or m t hat you want t o f i l l i n. ( Ther e' s

a per l pr ogr am cal l ed f or mf i nd. pl on t he cur l si t e t hat hel ps wi t h t hi s).

I f t her e' s a "nor mal " post , you use - d t o post . - d t akes a f ul l "post st r i ng", whi ch i s i n t he f or mat

=&=&. . .

The ' var i abl e' names ar e t he names set wi t h "name=" i n t he t ags, and t he data i s t he cont ent s you want t o f i l l i n f or t he i nput s. The data *must * be proper l y URL encoded. That means you r epl ace space wi t h + and t hat you r epl ace wei r d l ett ers wi t h %XX where XX i s t he hexadeci mal r epr esent at i on of

t he l et t er ' s ASCI I code.Exampl e:

( page l ocat ed at ht t p: / / www. f ormpost. com/ get t hi s/

We want t o ent er user ' f oobar' wi t h password ' 12345' .

To post t o t hi s, you enter a cur l command l i ne l i ke:

cur l - d "user =f oobar &pass=12345&i d=bl abl abl a&di ng=submi t " ( cont i nues)

ht t p: / / www. f ormpost. com/ get t hi s/ post. cgi

Whi l e - d uses t he appl i cat i on/ x- www- f orm- ur l encoded mi me- t ype, general l y


13 19/07/2014 18:40


5/13

underst ood by CGI ' s and si mi l ar, cur l al so support s the more capabl e mul t i par t / f or m- dat a t ype. Thi s l at t er t ype suppor t s thi ngs l i ke f i l e upl oad.

- F accept s par ameter s l i ke - F "name=cont ent s" . I f you want t he cont ent s t o be r ead f r oma f i l e, use as cont ent s. When speci f yi ng a f i l e, you can al so speci f y the f i l e cont ent t ype by appendi ng ' ; t ype=' t o t he f i l e name. You can al so post t he cont ent s of sever al f i l es i n one f i el d. For exampl e, t he f i el d name ' cool f i l es' i s used t o send t hr ee f i l es, wi t h di f f er ent cont ent t ypes usi ng t he f ol l owi ng synt ax:

cur l - F "cool f i l es=@f i l 1. gi f ; type=i mage/ gi f , f i l 2. txt , f i l 3. html " \

ht t p: / / www. post . com/ post i t . cgi

I f t he content - t ype i s not speci f i ed, cur l wi l l t ry to guess fr om t he f i l e extensi on ( i t onl y knows a f ew) , or use t he pr evi ousl y speci f i ed t ype ( f r om an ear l i er f i l e i f several f i l es are spec i f i ed i n a l i s t ) or el se i t wi l l use t he def aul t t ype ' appl i cat i on/ oct et - st r eam' .

Emul ate a f i l l - i n f orm wi th -F . Let ' s say you f i l l i n three f i el ds i n a f orm. One f i el d i s a f i l e name whi ch t o post , one f i el d i s your name and one f i el d i s a f i l e descr i pt i on. We want t o post t he f i l e we have wr i t t en named "cool t ext . t xt ". To l et cur l do t he post i ng of t hi s dat a i nst ead of your f avouri t e br owser , you have t o r ead t he HTML sour ce of t he f orm page and f i nd t he names of t he i nput f i el ds. I n our exampl e, t he i nput f i el d names are ' f i l e' , ' yourname' and ' f i l edescr i pt i on' .

cur l - F "f i l e=@cool t ext. t xt" - F "your name=Dani el " \

- F "f i l edescri pt i on=Cool t ext f i l e wi t h cool t ext i nsi de" \ht t p: / / www. post. com/ post i t . cgi

To send t wo f i l es i n one post you can do i t i n t wo ways:

1. Send mul t i pl e f i l es i n a si ngl e "f i el d" wi t h a si ngl e fi el d name:

cur l - F "pi ctures=@dog. gi f , cat . gi f "

2. Send t wo f i el ds wi t h t wo f i el d names:

cur l - F "docpi ct ur e=@dog. gi f " - F "cat pi ct ur e=@cat . gi f "

To send a f i el d val ue l i t eral l y wi t hout i nterpret i ng a l eadi ng ' @'

or '


6/13

Mozi l l a i s not t he onl y possi bl e User - Agent name: ' Konqueror / 1. 0' KDE Fi l e Manager desktop cl i ent ' Lynx/ 2. 7. 1 l i bwww- FM/ 2. 14' Lynx command l i ne browserCOOKI ES

Cooki es are general l y used by web server s t o keep st ate i nf ormat i on at t he cl i ent ' s si de. The ser ver set s cooki es by sendi ng a r esponse l i ne i n t he header s t hat l ooks l i ke ' Set - Cooki e: ' wher e t he data part t hen t ypi cal l y cont ai ns a set of NAME=VALUE pai r s ( separat ed by semi col ons ' ; ' l i ke "NAME1=VALUE1; NAME2=VALUE2; " ) . The server can al so speci f y f or what

path t he "cooki e" shoul d be used f or ( by speci f yi ng "path=val ue") , when t he cooki e shoul d expi r e ( "expi r e=DATE") , f or what domai n t o use i t ( "domai n=NAME") and i f i t shoul d be used on secure connect i ons onl y ("secure").

I f you' ve r ecei ved a page f r oma ser ver t hat cont ai ns a header l i ke: Set - Cooki e: sessi oni d=boo123; path="/ f oo" ;

i t means t he ser ver want s t hat f i r st pai r passed on when we get anyt hi ng i n a path begi nni ng wi t h "/ f oo".

Exampl e, get a page that wants my name passed i n a cooki e:

cur l - b "name=Dani el " www. si l l ypage. com

Cur l al so has t he abi l i t y to use pr evi ousl y r ecei ved cooki es i n f ol l owi ng

sessi ons. I f you get cooki es f r om a ser ver and st or e t hem i n a f i l e i n a manner si mi l ar t o:

cur l - - dump- header headers www. exampl e. com

. . . you can t hen i n a second connect t o that ( or another ) si t e, use the cooki es f romt he ' headers' f i l e l i ke:

cur l - b headers www. exampl e. com

Whi l e savi ng header s t o a f i l e i s a wor ki ng way to st or e cooki es, i t i s however er r or- pr one and not t he pr ef err ed way t o do thi s. I nst ead, make curl save t he i ncomi ng cooki es usi ng t he wel l - known netscape cooki e f ormat l i ke thi s :

cur l - c cooki es. t xt www. exampl e. com

Note that by speci f yi ng - b you enabl e the "cooki e awareness" and wi t h -L you can make cur l f ol l ow a l ocati on: ( whi ch of t en i s used i n combi nati on wi t h cooki es) . So t hat i f a si t e sends cooki es and a l ocat i on, you can use a nonexi st i ng f i l e t o t r i gger t he cooki e awar eness l i ke:

cur l - L - b empty. t xt www. exampl e. com

The f i l e t o r ead cooki es f r om must be f or mat t ed usi ng pl ai n HTTP headers OR as net scape' s cooki e f i l e. Cur l wi l l det er mi ne what ki nd i t i s based on t he f i l e cont ent s. I n t he above command, cur l wi l l parse t he header and st ore t he cooki es r ecei ved f r om www. exampl e. com. cur l wi l l send t o t he server t he st ored cooki es whi ch match t he r equest as i t f ol l ows the l ocati on. The f i l e "empt y. t xt" may be a nonexi st ent f i l e.

Al as, t o bot h r ead and wr i t e cooki es f r oma net scape cooki e f i l e, you can set bot h - b and - c to use t he same f i l e:

cur l - b cooki es. t xt - c cooki es. t xt www. exampl e. comPROGRESS METER

The progress met er exi st s t o show a user t hat somet hi ng act ual l y i s happeni ng. The di f f er ent f i el ds i n t he out put have t he f ol l owi ng meani ng:

% Tot al % Recei ved % Xf erd Aver age Speed Ti me Curr . Dl oad Upl oad Tot al Cur r ent Lef t Speed 0 151M 0 38608 0 0 9406 0 4: 41: 43 0: 00: 04 4: 41: 39 9287

Froml ef t - to- r i ght : % - percent age compl eted of t he whol e t r ansf er

Tot al - t ot al si ze of t he whol e expect ed t r ansf er % - per cent age compl eted of t he downl oad Recei ved - curr ent l y downl oaded amount of byt es % - percent age compl eted of t he upl oad Xf erd - cur r ent l y upl oaded amount of bytes Average Speed


13 19/07/2014 18:40


7/13

Dl oad - t he aver age t r ansf er speed of t he downl oad Average Speed Upl oad - t he average t r ansf er speed of t he upl oad Ti me Tot al - expected t i me t o compl ete t he operat i on Ti me Cur r ent - t i me passed si nce t he i nvoke Ti me Lef t - expect ed t i me l ef t t o compl et i on Cur r . Speed - the aver age t r ansf er speed t he l ast 5 seconds ( t he f i r st 5 seconds of a t r ansf er i s based on l ess t i me of cour se. )

The - # opt i on wi l l di spl ay a t ot al l y di f f erent progress bar t hat doesn' t need much expl anat i on!

SPEED LI MI T

Cur l al l ows t he user t o set t he t r ansf er speed condi t i ons t hat must be met t o l et t he t r ansf er keep goi ng. By usi ng t he swi t ch - y and - Y you can make cur l abort t r ansf er s i f t he t r ansf er speed i s bel ow t he speci f i ed l owest l i mi t f or a speci f i ed t i me.

To have cur l abort t he downl oad i f t he speed i s sl ower t han 3000 byt es per second f or 1 mi nut e, r un:

cur l - Y 3000 - y 60 www. f ar- away- si t e. com

Thi s can very wel l be used i n combi nat i on wi t h t he overal l t i me l i mi t , so t hat t he above operat i on must be compl eted i n whol e wi t hi n 30 mi nut es:

cur l - m 1800 - Y 3000 - y 60 www. f ar- away- si t e. com

For ci ng cur l not t o t r ansf er dat a f ast er t han a gi ven r at e i s al so possi bl e, whi ch mi ght be usef ul i f you' r e usi ng a l i mi t ed bandwi dt h connecti on and you don' t want your t r ansf er t o use al l of i t ( somet i mes r ef er r ed t o as "bandwi dt h t hr ot t l e") .

Make cur l t r ansf er dat a no f ast er t han 10 ki l obytes per second:

cur l - - l i mi t - r at e 10K www. f ar - away- si t e. com

or

cur l - - l i mi t - r at e 10240 www. f ar - away- si t e. com

Or pr event cur l f r omupl oadi ng data f ast er t han 1 megabyt e per second:

cur l - T upl oad - - l i mi t - rate 1M f t p: / / upl oadsher epl ease. com

When usi ng t he -- l i mi t - r ate opt i on, t he t r ansf er r at e i s r egul at ed on a per- second basi s, whi ch wi l l cause t he t otal t r ansf er speed t o become l ower t han t he gi ven number. Someti mes of course subst ant i al l y l ower, i f your t r ansf er stal l s dur i ng per i ods.CONFI G FI LE

Curl aut omat i cal l y tr i es t o read t he . cur l rc f i l e ( or _curl rc f i l e on wi n32 syst ems) f r omt he user' s home di r on st art up.

The conf i g f i l e coul d be made up wi t h normal command l i ne swi t ches, but you can al so speci f y the l ong opt i ons wi t hout t he dashes to make i t more

r eadabl e. You can separat e t he opt i ons and t he par ameter wi t h spaces, or wi t h = or : . Comment s can be used wi t hi n t he f i l e. I f t he f i r st l et t er on a l i ne i s a ' #' - symbol t he r est of t he l i ne i s t r eated as a comment .

I f you want t he parameter t o cont ai n spaces, you must encl ose the enti r e paramet er wi t hi n doubl e quotes ( ") . Wi t hi n t hose quotes, you speci f y a quote as \ ".

NOTE: You must speci f y opt i ons and t hei r argument s on t he same l i ne.

Exampl e, set def aul t t i me out and pr oxy i n a conf i g f i l e:# We want a 30 mi nut e t i meout : - m 1800# . . . and we use a pr oxy f or al l accesses: proxy = proxy. our . domai n. com: 8080

Whi t e spaces ARE si gni f i cant at t he end of l i nes, but al l whi t e spaces

l eadi ng up t o t he f i r st char act er s of each l i ne ar e i gnor ed.

Prevent cur l f r omr eadi ng t he def aul t f i l e by usi ng - q as the f i r st command l i ne par amet er , l i ke:


13 19/07/2014 18:40


8/13

cur l - q www. t hat si t e. com

For ce cur l t o get and di spl ay a l ocal hel p page i n case i t i s i nvoked

wi t hout URL by maki ng a conf i g f i l e si mi l ar t o:# def aul t ur l t o get ur l = "ht t p: / / hel p. wi t h. cur l . com/ cur l hel p. ht ml "

You can speci f y another conf i g f i l e t o be r ead by usi ng t he - K/ - - conf i g f l ag. I f you set conf i g f i l e name t o "- " i t ' l l read t he conf i g f romst di n,

whi ch can be handy i f you want t o hi de opt i ons f r ombei ng vi si bl e i n pr ocess t abl es et c:

echo "user = user: passwd" | cur l - K - htt p: / / that . secret . s i te .comEXTRA HEADERS

When usi ng cur l i n your own ver y speci al progr ams, you may end up needi ng t o pass on your own cust om headers when get t i ng a web page. You can do t hi s by usi ng t he - H f l ag.

Exampl e, send the header "X- you- and-me: yes" t o t he ser ver when get t i ng a page:

cur l - H "X- you- and- me: yes" www. l ove. com

Thi s can al so be usef ul i n case you want cur l t o send a di f f erent t ext i n a header t han i t normal l y does. The - H header you speci f y then r epl aces t he header curl woul d normal l y send. I f you r epl ace an i nt ernal header wi t h an empty one, you prevent t hat header f r om bei ng sent . To prevent t he Host : header f r ombei ng used:

cur l - H "Host: " www. server . comFTP and PATH NAMES

Do note t hat when get t i ng f i l es wi t h t he f t p: / / URL, t he gi ven path i s r el ati ve t he di r ect ory you ent er . To get t he f i l e ' README' f r omyour home di r ectory at your f t p si t e, do:

cur l f tp : / /user : passwd@my. si t e. com/ README

But i f you want t he README f i l e f r omt he root di r ect ory of t hat ver y same si t e, you need t o speci f y t he absol ut e f i l e name:

cur l f tp : / /user : passwd@my. si t e. com/ / README

( I . e wi t h an ext r a sl ash i n f r ont of t he fi l e name. )SFTP and SCP and PATH NAMES

Wi t h sf t p: and scp: URLs, t he pat h name gi ven i s t he absol ute name on t he server . To access a f i l e r el ati ve t o t he r emote user' s home di r ect ory, pr ef i x t he f i l e wi t h / ~/ , such as:

cur l - u $USER sf t p: / / home. exampl e. com/ ~/ . bashr c

FTP and f i r ewal l sThe FTP prot ocol r equi r es one of t he i nvol ved part i es t o open a second

connecti on as soon as data i s about t o get t r ansf err ed. There ar e t wo ways t o do t hi s.

The def aul t way f or cur l i s t o i ssue t he PASV command whi ch causes t he ser ver t o open another por t and awai t anot her connect i on per f ormed by t he cl i ent . Thi s i s good i f t he cl i ent i s behi nd a f i rewal l t hat doesn' t al l ow i ncomi ng connect i ons.

cur l f t p. downl oad. com

I f t he ser ver , f or exampl e, i s behi nd a f i r ewal l t hat doesn' t al l ow connect i ons on port s other t han 21 ( or i f i t j ust doesn' t support t he PASV command) , t he other way t o do i t i s t o use the PORT command and i nst r uct t he ser ver t o

connect t o t he cl i ent on t he gi ven I P number and port ( as parameter s t o t he PORT command) .

The - P f l ag t o cur l support s a f ew di f f er ent opt i ons. Your machi ne may have sever al I P-addr esses and/ or net work i nt er f aces and cur l al l ows you t o sel ect whi ch of t hemt o use. Def aul t addr ess can al so be used:


13 19/07/2014 18:40


9/13

cur l - P - f t p. downl oad. com

Downl oad wi t h PORT but use the I P addr ess of our ' l e0' i nter f ace ( t hi s does

not wor k on wi ndows) :

cur l - P l e0 f t p. downl oad. com

Downl oad wi t h PORT but use 192. 168. 0. 10 as our I P address t o use:

cur l - P 192. 168. 0. 10 f t p. downl oad. com

NETWORK I NTERFACE

Get a web page f r oma server usi ng a speci f i ed port f or t he i nt er f ace:

cur l - - i nt erf ace et h0: 1 htt p: / / www. net scape. com/

or

cur l - - i nt er f ace 192. 168. 1. 10 ht t p: / / www. net scape. com/HTTPS

Secur e HTTP requi r es SSL l i br ari es t o be i nst al l ed and used when cur l i s bui l t . I f t hat i s done, cur l i s capabl e of r et r i evi ng and post i ng document s usi ng t he HTTPS prot ocol .

Exampl e:

cur l ht t ps: / / www. secur e- si t e. com

Cur l i s al so capabl e of usi ng your per sonal cer t i f i cat es t o get / post f i l es

f r om si t es that r equi r e val i d cer t i f i cat es. The onl y dr awback i s that t he cer t i f i cate needs t o be i n PEM- f ormat. PEM i s a st andard and open f ormat t o st ore cer t i f i cates wi t h, but i t i s not used by the most commonl y used browser s ( Netscape and MSI E bot h use t he so cal l ed PKCS#12 f ormat ) . I f you want curl t o use t he cer t i f i cat es you use wi t h your ( f avour i t e) browser, you may need t o downl oad/ compi l e a conver t er t hat can conver t your browser ' s f or mat t ed cer t i f i cat es to PEM f or mat t ed ones. Thi s ki nd of conver t er i s i ncl uded i n r ecent ver si ons of OpenSSL, and f or ol der ver si ons Dr St ephen N. Henson has wr i t t en a patch f or SSLeay t hat adds t hi s f unct i onal i t y. You can get hi s pat ch ( t hat r equi r es an SSLeay i nst al l at i on) f r om hi s si t e at : ht t p: / / www. dr h- consul t ancy. demon. co. uk/

Exampl e on how t o aut omat i cal l y ret r i eve a document usi ng a cer t i f i cate wi t h a per sonal password:

cur l - E / pat h/ t o/ cer t . pem: passwor d ht t ps: / / secur e. si t e. com/

I f you negl ect t o speci f y t he password on t he command l i ne, you wi l l be prompted f or t he cor r ect password bef ore any data can be r ecei ved.

Many ol der SSL- ser ver s have probl ems wi t h SSLv3 or TLS, whi ch newer ver si ons of OpenSSL etc use, t heref ore i t i s somet i mes usef ul t o speci f y what SSL- ver si on cur l shoul d use. Use - 3, - 2 or - 1 t o speci f y t hat exact SSL ver si on t o use ( f or SSLv3, SSLv2 or TLSv1 r espect i vel y):

cur l - 2 ht t ps: / / secur e. si t e. com/Ot her wi se, cur l wi l l f i r st att empt t o use v3 and t hen v2.

To use OpenSSL t o convert your f avouri t e browser ' s cer t i f i cat e i nto a PEM

f ormatt ed one t hat cur l can use, do somet hi ng l i ke t hi s:

I n Net scape, you st art wi t h hi t t i ng t he ' Secur i t y' menu but t on.

Sel ect ' cert i f i cat es- >yours' and t hen pi ck a cert i f i cat e i n t he l i st

Pr ess t he ' Expor t ' but t on

ent er your PI N code f or t he cer t s

sel ect a pr oper pl ace t o save i t

Run t he ' openssl ' appl i cat i on t o conver t t he cer t i f i cat e. I f you cd t o the

openssl i nst al l at i on, you can do i t l i ke:# . / apps/ openssl pkcs12 - i n [ f i l e you saved] - cl cer t s - out [ PEMf i l e]


13 19/07/2014 18:40


10/13

I n Fi r ef ox, sel ect Opt i ons, t hen Advanced, t hen t he Encr ypt i on t ab, Vi ew Cert i f i cat es. Thi s opens t he Cer t i f i cat e Manager , wher e you can Export . Be sure t o sel ect PEM f or t he Save as t ype.

I n I nt er net Expl or er , sel ect I nt er net Opt i ons, t hen t he Cont ent t ab, t hen Cert i f i cates. Then you can Expor t , and dependi ng on t he f ormat you may need t o conver t t o PEM.

I n Chrome, sel ect Set t i ngs, t hen Show Advanced Set t i ngs. Under HTTPS/ SSL sel ect Manage Cer t i f i cates.

RESUMI NG FI LE TRANSFERSTo cont i nue a f i l e t r ansf er where i t was previ ousl y abort ed, cur l support s r esume on HTTP( S) downl oads as wel l as FTP upl oads and downl oads.Cont i nue downl oadi ng a document:

cur l -C - - o f i l e f tp: / / f tp. server. com/ path/ f i l e

Cont i nue upl oadi ng a document ( *1) :

cur l -C - - T f i l e f tp: / / f tp. server. com/ path/ f i l e

Cont i nue downl oadi ng a document f r om a web ser ver ( *2) :

cur l -C - - o f i l e ht t p: / / www. server . com/

( *1) = Thi s r equi r es t hat t he FTP ser ver suppor t s t he non- st andar d command

SI ZE. I f i t doesn' t , cur l wi l l say so.( *2) = Thi s r equi r es t hat t he web ser ver suppor t s at l east HTTP/ 1. 1. I f i t

doesn' t , curl wi l l say so.

TI ME CONDI TI ONSHTTP al l ows a cl i ent t o speci f y a t i me condi t i on f or t he document i t

r equest s. I t i s I f - Modi f i ed- Si nce or I f - Unmodi f i ed- Si nce. Cur l al l ows you t o speci f y them wi t h t he -z/ - - t i me- cond f l ag.For exampl e, you can easi l y make a downl oad t hat onl y gets perf ormed i f t he

r emote f i l e i s newer t han a l ocal copy. I t woul d be made l i ke:

cur l - z l ocal . html ht t p: / / r emote. server . com/ r emote. ht mlOr you can downl oad a f i l e onl y i f t he l ocal f i l e i s newer t han t he r emot e

one. Do thi s by pr ependi ng the dat e str i ng wi t h a ' - ' , as i n:

cur l - z - l ocal . html ht t p: / / r emote. server . com/ r emote. ht mlYou can speci f y a " f r ee t ext " date as condi t i on. Tel l cur l t o onl y downl oad t he f i l e i f i t was updated si nce J anuary 12, 2012:

cur l - z " J an 12 2012" ht t p: / / r emote. server . com/ r emote. ht mlCurl wi l l t hen accept a wi de r ange of dat e f ormats. You al ways make t he dat e

check t he ot her way ar ound by pr ependi ng i t wi t h a dash ' - ' .

DI CTFor f un t r y

cur l di ct : / / di ct . org/ m: cur l

cur l di ct: / / di ct. or g/ d: hei senbug: j argon cur l di ct: / / di ct. or g/ d: dani el : web1913

Al i ases f or ' m' ar e ' mat ch' and ' f i nd' , and al i ases f or ' d' ar e ' def i ne' and ' l ookup' . For exampl e,

cur l di c t : / / di ct . org/ f i nd: cur l

Commands t hat break t he URL descr i pt i on of t he RFC ( but not t he DI CT pr ot ocol ) ar e

cur l di ct : / / di ct . org/ show: db cur l di ct : / / di ct . org/ show: str at

Aut hent i cat i on i s st i l l mi ssi ng ( but t hi s i s not r equi r ed by t he RFC)LDAP


f 13 19/07/2014 18:40


11/13

I f you have i nst al l ed t he OpenLDAP l i br ary, cur l can t ake advant age of i t

and of f er l dap: / / suppor t .

LDAP i s a compl ex t hi ng and wr i t i ng an LDAP quer y i s not an easy t ask. I do advi se you t o di g up t he synt ax descr i pt i on f or t hat el sewhere. Two pl aces t hat mi ght sui t you are:

Netscape' s " Net scape Di r ect ory SDK 3. 0 f or C Progr ammer' s Gui de Chapter 10: Wor ki ng wi t h LDAP URLs" : ht t p: / / devel oper . net scape. com/ docs/ manual s/ di r sdk/ csdk30/ ur l . ht m

RFC 2255, "The LDAP URL For mat " htt p: / / cur l . haxx. se/ r f c/r f c2255. t xt

To show you an exampl e, t hi s i s how I can get al l peopl e f r om my l ocal LDAP

server t hat has a cer t ai n sub- domai n i n t hei r emai l addr ess:

cur l - B " l dap: / / l dap. f r ont ec. se/ o=f r ont ec??sub?mai l =*st h. f r ont ec. se"

I f I want t he same i nf o i n HTML f ormat, I can get i t by not usi ng t he -B ( enf or ce ASCI I ) fl ag.ENVI RONMENT VARI ABLES

Cur l r eads and underst ands the f ol l owi ng envi r onment var i abl es:

ht t p_pr oxy, HTTPS_PROXY, FTP_PROXY

They shoul d be set f or prot ocol - speci f i c proxi es. Gener al proxy shoul d be

set wi t h

ALL_PROXY

A comma- separat ed l i st of host names that shoul dn' t go t hrough any pr oxy i s set i n ( onl y an ast er i sk, ' *' mat ches al l host s)

NO_PROXY

I f t he host name matches one of t hese st r i ngs, or t he host i s wi t hi n the domai n of one of t hese st r i ngs, t r ansacti ons wi t h t hat node wi l l not be pr oxi ed.

The usage of t he - x/ - - proxy f l ag overr i des t he envi r onment var i abl es.NETRC

Uni x i nt r oduced the . net r c concept a l ong ti me ago. I t i s a way f or a user t o speci f y name and password f or commonl y vi si t ed FTP si t es i n a f i l e so t hat you don' t have t o t ype t hem i n each t i me you vi si t t hose si t es. You r eal i ze t hi s i s a bi g secur i t y r i sk i f someone el se get s hol d of your passwords, so t her ef ore most uni x pr ogr ams won' t r ead t hi s f i l e unl ess i t i s onl y r eadabl e by your sel f ( cur l doesn' t car e t hough) .

Curl support s . net rc f i l es i f t ol d t o ( usi ng t he - n/ - - net rc and - - net rc- opti onal opt i ons). Thi s i s not r estr i cted t o j ust FTP, so cur l can use i t f or al l pr ot ocol s wher e aut hent i cat i on i s used.

A ver y si mpl e . net r c f i l e coul d l ook somet hi ng l i ke:machi ne cur l . haxx. se l ogi n i amdani el password mysecr et

CUSTOM OUTPUT

To bett er al l ow scr i pt programmers t o get t o know about t he progress of cur l , t he - w/ - - wr i t e- out opt i on was i nt r oduced. Usi ng t hi s, you can speci f y what i nf ormati on f r omt he pr evi ous t r ansf er you want t o ext r act .

To di spl ay t he amount of bytes downl oaded t oget her wi t h some t ext and an endi ng newl i ne:

cur l - w ' We downl oaded %{si ze_downl oad} byt es\ n' www. downl oad. comKERBEROS FTP TRANSFER

Cur l suppor t s kerberos4 and kerber os5/ GSSAPI f or FTP t r ansf ers . You need

t he ker beros package i nst al l ed and used at cur l bui l d t i me f or i t t o be avai l abl e.

Fi r st , get t he kr b- t i cket t he nor mal way, l i ke wi t h t he ki ni t / kaut h t ool .


f 13 19/07/2014 18:40


12/13

Then use cur l i n way si mi l ar t o:

cur l - - krb pri vat e f tp: / / krb4si te . com - u user name: f akepwd

Ther e' s no use f or a passwor d on t he - u swi t ch, but a bl ank one wi l l make cur l ask f or one and you al r eady ent er ed t he r eal password to ki ni t / kaut h.

TELNET

The cur l t el net support i s basi c and very easy t o use. Cur l passes al l data passed t o i t on st di n t o t he r emote server . Connect t o a r emote t el net

server usi ng a command l i ne si mi l ar t o:

cur l t el net : / / r emot e. ser ver . com

And ent er t he data t o pass t o the server on st di n. The resul t wi l l be sent t o st dout or t o t he f i l e you speci f y wi t h - o.

You mi ght want t he - N/ - - no- buf f er opt i on t o swi t ch of f t he buf f ered output f or sl ow connect i ons or si mi l ar .

Pass opt i ons t o t he t el net pr ot ocol negot i at i on, by usi ng t he - t opt i on. To t el l t he ser ver we use a vt100 t er mi nal , t r y somet hi ng l i ke:

cur l - t TTYPE=vt100 t el net : / / r emot e. ser ver . com

Ot her i nt eresti ng opt i ons f or i t - t i ncl ude:

- XDI SPLOC= Set s t he X di spl ay l ocat i on.

- NEW_ENV= Set s an envi r onment var i abl e.

NOTE: The tel net pr otocol does not speci f y any way t o l ogi n wi t h a speci f i ed

user and password so cur l can' t do t hat aut omat i cal l y. To do t hat , you need t o t r ack when t he l ogi n prompt i s r ecei ved and send t he username and password accor di ngl y.PERSI STENT CONNECTI ONS

Speci f yi ng mul t i pl e f i l es on a si ngl e command l i ne wi l l make cur l t r ansf er al l of t hem, one af t er t he ot her i n t he speci f i ed or der .

l i bcur l wi l l att empt t o use per si st ent connect i ons f or t he t r ansf er s so t hat t he second t r ansf er t o the same host can use t he same connect i on t hat was al r eady i ni t i ated and was l ef t open i n t he pr evi ous tr ansf er . Thi s gr eat l y decr eases connect i on t i me f or al l but t he f i r st t r ansf er and i t makes a f ar bett er use of t he network.

Note that curl cannot use per si st ent connect i ons f or t r ansf er s t hat ar e used i n subsequence cur l i nvokes. Try t o st uf f as many URLs as possi bl e on t he same command l i ne i f t hey ar e usi ng t he same host , as that ' l l make t he t r ansf er s faster. I f you use an HTTP pr oxy f or f i l e t r ansf er s, pr acti cal l y al l t ransf ers wi l l be per si stent .MULTI PLE TRANSFERS WI TH A SI NGLE COMMAND LI NE

As i s ment i oned above, you can downl oad mul t i pl e f i l es wi t h one command l i ne by si mpl y addi ng more URLs. I f you want t hose t o get saved t o a l ocal f i l e

i nst ead of j ust pr i nt ed t o stdout , you need t o add one save opt i on f or each URL you speci f y. Note that t hi s al so goes f or t he - O opt i on ( but not - - r emote- name- al l ) .

For exampl e: get t wo f i l es and use - O f or t he f i r st and a cust om f i l e name f or t he second:

cur l - O ht t p: / / ur l . com/ f i l e. tx t f t p: / / f t p. com/ moo. exe - o moo. j pg

You can al so upl oad mul t i pl e f i l es i n a si mi l ar f ashi on:

curl - T l ocal 1 f t p: / / f t p. com/ moo. exe - T l ocal 2 f t p: / / f t p. com/ moo2. t xtI Pv6

cur l wi l l connect t o a server wi t h I Pv6 when a host l ookup retur ns an I Pv6

addr ess and f al l back t o I Pv4 i f t he connect i on f ai l s. The - - i pv4 and - - i pv6 opt i ons can speci f y whi ch addr ess to use when both are avai l abl e. I Pv6 addr esses can al so be speci f i ed di r ect l y i n URLs usi ng t he synt ax:

ht t p: / / [ 2001: 1890: 1112: 1: : 20] / over vi ew. ht ml


f 13 19/07/2014 18:40


13/13

Page updated March 31, 2014.

web site info

When t hi s st yl e i s used, t he - g opt i on must be gi ven t o st op cur l f r om i nt er pr et i ng t he squar e br acket s as speci al gl obbi ng char act er s. Li nk l ocal and si t e l ocal addr esses i ncl udi ng a scope i dent i f i er , such as f e80: : 1234%1, may al so be used, but t he scope por t i on must be numeri c or match an exi st i ng net work i nter f ace on Li nux and t he per cent char act er must be URL escaped. The previ ous exampl e i n an SFTP URL mi ght l ook l i ke:

sf t p: / / [ f e80: : 1234%251] /

I Pv6 addr esses provi ded other t han i n URLs ( e. g. t o the - - pr oxy, - - i nt er f ace or - - f t p- port opt i ons) shoul d not be URL encoded.

METALI NK

Cur l suppor t s Metal i nk ( bot h vers i on 3 and 4 (RFC 5854) are support ed) , a way t o l i st mul t i pl e URI s and hashes f or a f i l e. Cur l wi l l make use of t he mi r r or s l i st ed wi t hi n f or f ai l over i f t her e ar e er r or s (such as the f i l e or server not bei ng avai l abl e) . I t wi l l al so ver i f y t he hash of t he f i l e af t er t he downl oad compl etes. The Metal i nk f i l e i t sel f i s downl oaded and pr ocessed i n memory and not st or ed i n t he l ocal f i l e system.

Exampl e t o use a remote Metal i nk f i l e:

cur l - - met al i nk htt p: / / www. exampl e. com/ exampl e. metal i nk

To use a Metal i nk f i l e i n t he l ocal f i l e sys t em, use FI LE prot ocol ( f i l e: / / ) :

cur l - - met al i nk f i l e: / / exampl e. met al i nk

Pl ease note that i f FI LE pr ot ocol i s di sabl ed, t her e i s no way to use a l ocal Met al i nk f i l e at t he t i me of t hi s wr i t i ng. Al so not e t hat i f - - met al i nk and - - i ncl ude ar e used t oget her , - - i ncl ude wi l l be i gnor ed. Thi s i s because i ncl udi ng header s i n t he response wi l l br eak Met al i nk parser and i f t he header s are i ncl uded i n t he f i l e descri bed i n Met al i nk f i l e, hash check wi l l f ai l .MAI LI NG LI STS

For your conveni ence, we have sever al open mai l i ng l i st s t o di scuss curl , i t s devel opment and t hi ngs rel evant t o t hi s. Get al l i nf o at ht t p: / / curl . haxx. se/ mai l / . Some of t he l i st s avai l abl e ar e:

curl - user s

Users of t he command l i ne t ool . How t o use i t , what doesn' t work, new f eat ur es, r el at ed t ool s, quest i ons, news, i nst al l at i ons, compi l at i ons, r unni ng, por t i ng et c.

cur l - l i brary

Devel opers usi ng or devel opi ng l i bcur l . Bugs, ext ensi ons, i mpr ovement s.

cur l - announce

Low- t r af f i c. Onl y r ecei ves announcement s of new publ i c ver si ons. At worst , t hat makes somethi ng l i ke one or t wo mai l s per mont h, but usual l y onl y one mai l every second month.

cur l - and- php

Usi ng the cur l f unct i ons i n PHP. Ever ythi ng cur l wi t h a PHP angl e. Or PHP wi t h a cur l angl e.

cur l - and- pyt hon

Pyt hon hackers usi ng curl wi t h or wi t hout t he python bi ndi ng pycur l .

Pl ease di r ect cur l quest i ons, f eature request s and t r oubl e r eport s t o one of t hese mai l i ng l i st s i nst ead of mai l i ng any i ndi vi dual .

File upload with ASP.NET
