/
curl.1
2177 lines (1908 loc) · 94.1 KB
/
curl.1
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
.\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2014, Daniel Stenberg, <daniel@haxx.se>, et al.
.\" *
.\" * This software is licensed as described in the file COPYING, which
.\" * you should have received as part of this distribution. The terms
.\" * are also available at http://curl.haxx.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" **************************************************************************
.\"
.TH curl 1 "2 Aug 2014" "Curl 7.38.0" "Curl Manual"
.SH NAME
curl \- transfer a URL
.SH SYNOPSIS
.B curl [options]
.I [URL...]
.SH DESCRIPTION
.B curl
is a tool to transfer data from or to a server, using one of the supported
protocols (DICT, FILE, FTP, FTPS, GOPHER, HTTP, HTTPS, IMAP, IMAPS, LDAP,
LDAPS, POP3, POP3S, RTMP, RTSP, SCP, SFTP, SMTP, SMTPS, TELNET and TFTP). The
command is designed to work without user interaction.
curl offers a busload of useful tricks like proxy support, user
authentication, FTP upload, HTTP post, SSL connections, cookies, file transfer
resume, Metalink, and more. As you will see below, the number of features will
make your head spin!
curl is powered by libcurl for all transfer-related features. See
.BR libcurl (3)
for details.
.SH URL
The URL syntax is protocol-dependent. You'll find a detailed description in
RFC 3986.
You can specify multiple URLs or parts of URLs by writing part sets within
braces as in:
http://site.{one,two,three}.com
or you can get sequences of alphanumeric series by using [] as in:
ftp://ftp.numericals.com/file[1-100].txt
ftp://ftp.numericals.com/file[001-100].txt (with leading zeros)
ftp://ftp.letters.com/file[a-z].txt
Nested sequences are not supported, but you can use several ones next to each
other:
http://any.org/archive[1996-1999]/vol[1-4]/part{a,b,c}.html
You can specify any amount of URLs on the command line. They will be fetched
in a sequential manner in the specified order.
You can specify a step counter for the ranges to get every Nth number or
letter:
http://www.numericals.com/file[1-100:10].txt
http://www.letters.com/file[a-z:2].txt
If you specify URL without protocol:// prefix, curl will attempt to guess what
protocol you might want. It will then default to HTTP but try other protocols
based on often-used host name prefixes. For example, for host names starting
with "ftp." curl will assume you want to speak FTP.
curl will do its best to use what you pass to it as a URL. It is not trying to
validate it as a syntactically correct URL by any means but is instead
\fBvery\fP liberal with what it accepts.
curl will attempt to re-use connections for multiple file transfers, so that
getting many files from the same server will not do multiple connects /
handshakes. This improves speed. Of course this is only done on files
specified on a single command line and cannot be used between separate curl
invokes.
.SH "PROGRESS METER"
curl normally displays a progress meter during operations, indicating the
amount of transferred data, transfer speeds and estimated time left, etc.
curl displays this data to the terminal by default, so if you invoke curl to
do an operation and it is about to write data to the terminal, it
\fIdisables\fP the progress meter as otherwise it would mess up the output
mixing progress meter and response data.
If you want a progress meter for HTTP POST or PUT requests, you need to
redirect the response output to a file, using shell redirect (>), -o [file] or
similar.
It is not the same case for FTP upload as that operation does not spit out
any response data to the terminal.
If you prefer a progress "bar" instead of the regular meter, \fI-#\fP is your
friend.
.SH OPTIONS
Options start with one or two dashes. Many of the options require an
additional value next to them.
The short "single-dash" form of the options, -d for example, may be used with
or without a space between it and its value, although a space is a recommended
separator. The long "double-dash" form, --data for example, requires a space
between it and its value.
Short version options that don't need any additional values can be used
immediately next to each other, like for example you can specify all the
options -O, -L and -v at once as -OLv.
In general, all boolean options are enabled with --\fBoption\fP and yet again
disabled with --\fBno-\fPoption. That is, you use the exact same option name
but prefix it with "no-". However, in this list we mostly only list and show
the --option version of them. (This concept with --no options was added in
7.19.0. Previously most options were toggled on/off on repeated use of the
same command line option.)
.IP "-#, --progress-bar"
Make curl display progress as a simple progress bar instead of the standard,
more informational, meter.
.IP "-:, --next"
Tells curl to use a separate operation for the following URL and associated
options. This allows you to send several URL requests, each with their own
specific options, for example, such as different user names or custom requests
for each. (Added in 7.36.0)
.IP "-0, --http1.0"
(HTTP) Tells curl to use HTTP version 1.0 instead of using its internally
preferred: HTTP 1.1.
.IP "--http1.1"
(HTTP) Tells curl to use HTTP version 1.1. This is the internal default
version. (Added in 7.33.0)
.IP "--http2"
(HTTP) Tells curl to issue its requests using HTTP 2. This requires that the
underlying libcurl was built to support it. (Added in 7.33.0)
.IP "--no-npn"
Disable the NPN TLS extension. NPN is enabled by default if libcurl was built
with an SSL library that supports NPN. NPN is used by a libcurl that supports
HTTP 2 to negotiate HTTP 2 support with the server during https sessions.
(Added in 7.36.0)
.IP "--no-alpn"
Disable the ALPN TLS extension. ALPN is enabled by default if libcurl was built
with an SSL library that supports ALPN. ALPN is used by a libcurl that supports
HTTP 2 to negotiate HTTP 2 support with the server during https sessions.
(Added in 7.36.0)
.IP "-1, --tlsv1"
(SSL)
Forces curl to use TLS version 1.x when negotiating with a remote TLS server.
You can use options \fI--tlsv1.0\fP, \fI--tlsv1.1\fP, and \fI--tlsv1.2\fP to
control the TLS version more precisely (if the SSL backend in use supports such
a level of control).
.IP "-2, --sslv2"
(SSL)
Forces curl to use SSL version 2 when negotiating with a remote SSL server.
.IP "-3, --sslv3"
(SSL)
Forces curl to use SSL version 3 when negotiating with a remote SSL server.
.IP "-4, --ipv4"
If curl is capable of resolving an address to multiple IP versions (which it
is if it is IPv6-capable), this option tells curl to resolve names to IPv4
addresses only.
.IP "-6, --ipv6"
If curl is capable of resolving an address to multiple IP versions (which it
is if it is IPv6-capable), this option tells curl to resolve names to IPv6
addresses only.
.IP "-a, --append"
(FTP/SFTP) When used in an upload, this will tell curl to append to the target
file instead of overwriting it. If the file doesn't exist, it will be created.
Note that this flag is ignored by some SSH servers (including OpenSSH).
.IP "-A, --user-agent <agent string>"
(HTTP) Specify the User-Agent string to send to the HTTP server. Some badly
done CGIs fail if this field isn't set to "Mozilla/4.0". To encode blanks in
the string, surround the string with single quote marks. This can also be set
with the \fI-H, --header\fP option of course.
If this option is used several times, the last one will be used.
.IP "--anyauth"
(HTTP) Tells curl to figure out authentication method by itself, and use the
most secure one the remote site claims to support. This is done by first
doing a request and checking the response-headers, thus possibly inducing an
extra network round-trip. This is used instead of setting a specific
authentication method, which you can do with \fI--basic\fP, \fI--digest\fP,
\fI--ntlm\fP, and \fI--negotiate\fP.
Note that using --anyauth is not recommended if you do uploads from stdin,
since it may require data to be sent twice and then the client must be able to
rewind. If the need should arise when uploading from stdin, the upload
operation will fail.
.IP "-b, --cookie <name=data>"
(HTTP)
Pass the data to the HTTP server as a cookie. It is supposedly the
data previously received from the server in a "Set-Cookie:" line.
The data should be in the format "NAME1=VALUE1; NAME2=VALUE2".
If no '=' symbol is used in the line, it is treated as a filename to use to
read previously stored cookie lines from, which should be used in this session
if they match. Using this method also activates the "cookie parser" which will
make curl record incoming cookies too, which may be handy if you're using this
in combination with the \fI-L, --location\fP option. The file format of the
file to read cookies from should be plain HTTP headers or the Netscape/Mozilla
cookie file format.
\fBNOTE\fP that the file specified with \fI-b, --cookie\fP is only used as
input. No cookies will be stored in the file. To store cookies, use the
\fI-c, --cookie-jar\fP option or you could even save the HTTP headers to a file
using \fI-D, --dump-header\fP!
If this option is used several times, the last one will be used.
.IP "-B, --use-ascii"
(FTP/LDAP) Enable ASCII transfer. For FTP, this can also be
enforced by using an URL that ends with ";type=A". This option causes data
sent to stdout to be in text mode for win32 systems.
.IP "--basic"
(HTTP) Tells curl to use HTTP Basic authentication. This is the default and
this option is usually pointless, unless you use it to override a previously
set option that sets a different authentication method (such as \fI--ntlm\fP,
\fI--digest\fP, or \fI--negotiate\fP).
.IP "-c, --cookie-jar <file name>"
(HTTP) Specify to which file you want curl to write all cookies after a
completed operation. Curl writes all cookies previously read from a specified
file as well as all cookies received from remote server(s). If no cookies are
known, no file will be written. The file will be written using the Netscape
cookie file format. If you set the file name to a single dash, "-", the
cookies will be written to stdout.
This command line option will activate the cookie engine that makes curl
record and use cookies. Another way to activate it is to use the \fI-b,
--cookie\fP option.
If the cookie jar can't be created or written to, the whole curl operation
won't fail or even report an error clearly. Using -v will get a warning
displayed, but that is the only visible feedback you get about this possibly
lethal situation.
If this option is used several times, the last specified file name will be
used.
.IP "-C, --continue-at <offset>"
Continue/Resume a previous file transfer at the given offset. The given offset
is the exact number of bytes that will be skipped, counting from the beginning
of the source file before it is transferred to the destination. If used with
uploads, the FTP server command SIZE will not be used by curl.
Use "-C -" to tell curl to automatically find out where/how to resume the
transfer. It then uses the given output/input files to figure that out.
If this option is used several times, the last one will be used.
.IP "--ciphers <list of ciphers>"
(SSL) Specifies which ciphers to use in the connection. The list of ciphers
must specify valid ciphers. Read up on SSL cipher list details on this URL:
\fIhttp://www.openssl.org/docs/apps/ciphers.html\fP
NSS ciphers are done differently than OpenSSL and GnuTLS. The full list of NSS
ciphers is in the NSSCipherSuite entry at this URL:
\fIhttp://git.fedorahosted.org/cgit/mod_nss.git/plain/docs/mod_nss.html#Directives\fP
If this option is used several times, the last one will be used.
.IP "--compressed"
(HTTP) Request a compressed response using one of the algorithms curl
supports, and save the uncompressed document. If this option is used and the
server sends an unsupported encoding, curl will report an error.
.IP "--connect-timeout <seconds>"
Maximum time in seconds that you allow the connection to the server to take.
This only limits the connection phase, once curl has connected this option is
of no more use. Since 7.32.0, this option accepts decimal values, but the
actual timeout will decrease in accuracy as the specified timeout increases in
decimal precision. See also the \fI-m, --max-time\fP option.
If this option is used several times, the last one will be used.
.IP "--create-dirs"
When used in conjunction with the \fI-o\fP option, curl will create the
necessary local directory hierarchy as needed. This option creates the dirs
mentioned with the \fI-o\fP option, nothing else. If the \fI-o\fP file name
uses no dir or if the dirs it mentions already exist, no dir will be created.
To create remote directories when using FTP or SFTP, try
\fI--ftp-create-dirs\fP.
.IP "--crlf"
(FTP) Convert LF to CRLF in upload. Useful for MVS (OS/390).
.IP "--crlfile <file>"
(HTTPS/FTPS) Provide a file using PEM format with a Certificate Revocation
List that may specify peer certificates that are to be considered revoked.
If this option is used several times, the last one will be used.
(Added in 7.19.7)
.IP "-d, --data <data>"
(HTTP) Sends the specified data in a POST request to the HTTP server, in the
same way that a browser does when a user has filled in an HTML form and
presses the submit button. This will cause curl to pass the data to the server
using the content-type application/x-www-form-urlencoded. Compare to
\fI-F, --form\fP.
\fI-d, --data\fP is the same as \fI--data-ascii\fP. To post data purely binary,
you should instead use the \fI--data-binary\fP option. To URL-encode the value
of a form field you may use \fI--data-urlencode\fP.
If any of these options is used more than once on the same command line, the
data pieces specified will be merged together with a separating
&-symbol. Thus, using '-d name=daniel -d skill=lousy' would generate a post
chunk that looks like \&'name=daniel&skill=lousy'.
If you start the data with the letter @, the rest should be a file name to
read the data from, or - if you want curl to read the data from
stdin. Multiple files can also be specified. Posting data from a file
named 'foobar' would thus be done with \fI--data\fP @foobar. When --data is
told to read from a file like that, carriage returns and newlines will be
stripped out.
.IP "-D, --dump-header <file>"
Write the protocol headers to the specified file.
This option is handy to use when you want to store the headers that an HTTP
site sends to you. Cookies from the headers could then be read in a second
curl invocation by using the \fI-b, --cookie\fP option! The
\fI-c, --cookie-jar\fP option is however a better way to store cookies.
When used in FTP, the FTP server response lines are considered being "headers"
and thus are saved there.
If this option is used several times, the last one will be used.
.IP "--data-ascii <data>"
See \fI-d, --data\fP.
.IP "--data-binary <data>"
(HTTP) This posts data exactly as specified with no extra processing
whatsoever.
If you start the data with the letter @, the rest should be a filename. Data
is posted in a similar manner as \fI--data-ascii\fP does, except that newlines
and carriage returns are preserved and conversions are never done.
If this option is used several times, the ones following the first will append
data as described in \fI-d, --data\fP.
.IP "--data-urlencode <data>"
(HTTP) This posts data, similar to the other --data options with the exception
that this performs URL-encoding. (Added in 7.18.0)
To be CGI-compliant, the <data> part should begin with a \fIname\fP followed
by a separator and a content specification. The <data> part can be passed to
curl using one of the following syntaxes:
.RS
.IP "content"
This will make curl URL-encode the content and pass that on. Just be careful
so that the content doesn't contain any = or @ symbols, as that will then make
the syntax match one of the other cases below!
.IP "=content"
This will make curl URL-encode the content and pass that on. The preceding =
symbol is not included in the data.
.IP "name=content"
This will make curl URL-encode the content part and pass that on. Note that
the name part is expected to be URL-encoded already.
.IP "@filename"
This will make curl load data from the given file (including any newlines),
URL-encode that data and pass it on in the POST.
.IP "name@filename"
This will make curl load data from the given file (including any newlines),
URL-encode that data and pass it on in the POST. The name part gets an equal
sign appended, resulting in \fIname=urlencoded-file-content\fP. Note that the
name is expected to be URL-encoded already.
.RE
.IP "--delegation LEVEL"
Set \fILEVEL\fP to tell the server what it is allowed to delegate when it
comes to user credentials. Used with GSS/kerberos.
.RS
.IP "none"
Don't allow any delegation.
.IP "policy"
Delegates if and only if the OK-AS-DELEGATE flag is set in the Kerberos
service ticket, which is a matter of realm policy.
.IP "always"
Unconditionally allow the server to delegate.
.RE
.IP "--digest"
(HTTP) Enables HTTP Digest authentication. This is an authentication scheme
that prevents the password from being sent over the wire in clear text. Use
this in combination with the normal \fI-u, --user\fP option to set user name
and password. See also \fI--ntlm\fP, \fI--negotiate\fP and \fI--anyauth\fP for
related options.
If this option is used several times, only the first one is used.
.IP "--disable-eprt"
(FTP) Tell curl to disable the use of the EPRT and LPRT commands when doing
active FTP transfers. Curl will normally always first attempt to use EPRT,
then LPRT before using PORT, but with this option, it will use PORT right
away. EPRT and LPRT are extensions to the original FTP protocol, and may not
work on all servers, but they enable more functionality in a better way than
the traditional PORT command.
\fB--eprt\fP can be used to explicitly enable EPRT again and \fB--no-eprt\fP
is an alias for \fB--disable-eprt\fP.
Disabling EPRT only changes the active behavior. If you want to switch to
passive mode you need to not use \fI-P, --ftp-port\fP or force it with
\fI--ftp-pasv\fP.
.IP "--disable-epsv"
(FTP) Tell curl to disable the use of the EPSV command when doing passive FTP
transfers. Curl will normally always first attempt to use EPSV before PASV,
but with this option, it will not try using EPSV.
\fB--epsv\fP can be used to explicitly enable EPSV again and \fB--no-epsv\fP
is an alias for \fB--disable-epsv\fP.
Disabling EPSV only changes the passive behavior. If you want to switch to
active mode you need to use \fI-P, --ftp-port\fP.
.IP "--dns-interface <interface>"
Tell curl to send outgoing DNS requests through <interface>. This option
is a counterpart to \fI--interface\fP (which does not affect DNS). The
supplied string must be an interface name (not an address).
This option requires that libcurl was built with a resolver backend that
supports this operation. The c-ares backend is the only such one. (Added in
7.33.0)
.IP "--dns-ipv4-addr <ip-address>"
Tell curl to bind to <ip-address> when making IPv4 DNS requests, so that
the DNS requests originate from this address. The argument should be a
single IPv4 address.
This option requires that libcurl was built with a resolver backend that
supports this operation. The c-ares backend is the only such one. (Added in
7.33.0)
.IP "--dns-ipv6-addr <ip-address>"
Tell curl to bind to <ip-address> when making IPv6 DNS requests, so that
the DNS requests originate from this address. The argument should be a
single IPv6 address.
This option requires that libcurl was built with a resolver backend that
supports this operation. The c-ares backend is the only such one. (Added in
7.33.0)
.IP "--dns-servers <ip-address,ip-address>"
Set the list of DNS servers to be used instead of the system default.
The list of IP addresses should be separated with commas. Port numbers
may also optionally be given as \fI:<port-number>\fP after each IP
address.
This option requires that libcurl was built with a resolver backend that
supports this operation. The c-ares backend is the only such one. (Added in
7.33.0)
.IP "-e, --referer <URL>"
(HTTP) Sends the "Referrer Page" information to the HTTP server. This can also
be set with the \fI-H, --header\fP flag of course. When used with
\fI-L, --location\fP you can append ";auto" to the --referer URL to make curl
automatically set the previous URL when it follows a Location: header. The
\&";auto" string can be used alone, even if you don't set an initial --referer.
If this option is used several times, the last one will be used.
.IP "-E, --cert <certificate[:password]>"
(SSL) Tells curl to use the specified client certificate file when getting a
file with HTTPS, FTPS or another SSL-based protocol. The certificate must be
in PKCS#12 format if using Secure Transport, or PEM format if using any other
engine. If the optional password isn't specified, it will be queried
for on the terminal. Note that this option assumes a \&"certificate" file that
is the private key and the private certificate concatenated! See \fI--cert\fP
and \fI--key\fP to specify them independently.
If curl is built against the NSS SSL library then this option can tell
curl the nickname of the certificate to use within the NSS database defined
by the environment variable SSL_DIR (or by default /etc/pki/nssdb). If the
NSS PEM PKCS#11 module (libnsspem.so) is available then PEM files may be
loaded. If you want to use a file from the current directory, please precede
it with "./" prefix, in order to avoid confusion with a nickname. If the
nickname contains ":", it needs to be preceded by "\\" so that it is not
recognized as password delimiter. If the nickname contains "\\", it needs to
be escaped as "\\\\" so that it is not recognized as an escape character.
(iOS and Mac OS X only) If curl is built against Secure Transport, then the
certificate string can either be the name of a certificate/private key in the
system or user keychain, or the path to a PKCS#12-encoded certificate and
private key. If you want to use a file from the current directory, please
precede it with "./" prefix, in order to avoid confusion with a nickname.
If this option is used several times, the last one will be used.
.IP "--engine <name>"
Select the OpenSSL crypto engine to use for cipher
operations. Use \fI--engine list\fP to print a list of build-time supported
engines. Note that not all (or none) of the engines may be available at
run-time.
.IP "--environment"
(RISC OS ONLY) Sets a range of environment variables, using the names the
\fI-w\fP option supports, to allow easier extraction of useful information
after having run curl.
.IP "--egd-file <file>"
(SSL) Specify the path name to the Entropy Gathering Daemon socket. The socket
is used to seed the random engine for SSL connections. See also the
\fI--random-file\fP option.
.IP "--cert-type <type>"
(SSL) Tells curl what certificate type the provided certificate is in. PEM,
DER and ENG are recognized types. If not specified, PEM is assumed.
If this option is used several times, the last one will be used.
.IP "--cacert <CA certificate>"
(SSL) Tells curl to use the specified certificate file to verify the peer. The
file may contain multiple CA certificates. The certificate(s) must be in PEM
format. Normally curl is built to use a default file for this, so this option
is typically used to alter that default file.
curl recognizes the environment variable named 'CURL_CA_BUNDLE' if it is
set, and uses the given path as a path to a CA cert bundle. This option
overrides that variable.
The windows version of curl will automatically look for a CA certs file named
\'curl-ca-bundle.crt\', either in the same directory as curl.exe, or in the
Current Working Directory, or in any folder along your PATH.
If curl is built against the NSS SSL library, the NSS PEM PKCS#11 module
(libnsspem.so) needs to be available for this option to work properly.
If this option is used several times, the last one will be used.
.IP "--capath <CA certificate directory>"
(SSL) Tells curl to use the specified certificate directory to verify the
peer. Multiple paths can be provided by separating them with ":" (e.g.
\&"path1:path2:path3"). The certificates must be in PEM format, and if curl is
built against OpenSSL, the directory must have been processed using the
c_rehash utility supplied with OpenSSL. Using \fI--capath\fP can allow
OpenSSL-powered curl to make SSL-connections much more efficiently than using
\fI--cacert\fP if the \fI--cacert\fP file contains many CA certificates.
If this option is set, the default capath value will be ignored, and if it is
used several times, the last one will be used.
.IP "-f, --fail"
(HTTP) Fail silently (no output at all) on server errors. This is mostly done
to better enable scripts etc to better deal with failed attempts. In
normal cases when an HTTP server fails to deliver a document, it returns an
HTML document stating so (which often also describes why and more). This flag
will prevent curl from outputting that and return error 22.
This method is not fail-safe and there are occasions where non-successful
response codes will slip through, especially when authentication is involved
(response codes 401 and 407).
.IP "-F, --form <name=content>"
(HTTP) This lets curl emulate a filled-in form in which a user has pressed the
submit button. This causes curl to POST data using the Content-Type
multipart/form-data according to RFC 2388. This enables uploading of binary
files etc. To force the 'content' part to be a file, prefix the file name
with an @ sign. To just get the content part from a file, prefix the file name
with the symbol <. The difference between @ and < is then that @ makes a file
get attached in the post as a file upload, while the < makes a text field and
just get the contents for that text field from a file.
Example, to send your password file to the server, where
\&'password' is the name of the form-field to which /etc/passwd will be the
input:
\fBcurl\fP -F password=@/etc/passwd www.mypasswords.com
To read content from stdin instead of a file, use - as the filename. This goes
for both @ and < constructs.
You can also tell curl what Content-Type to use by using 'type=', in a manner
similar to:
\fBcurl\fP -F "web=@index.html;type=text/html" url.com
or
\fBcurl\fP -F "name=daniel;type=text/foo" url.com
You can also explicitly change the name field of a file upload part by setting
filename=, like this:
\fBcurl\fP -F "file=@localfile;filename=nameinpost" url.com
If filename/path contains ',' or ';', it must be quoted by double-quotes like:
\fBcurl\fP -F "file=@\\"localfile\\";filename=\\"nameinpost\\"" url.com
or
\fBcurl\fP -F 'file=@"localfile";filename="nameinpost"' url.com
Note that if a filename/path is quoted by double-quotes, any double-quote
or backslash within the filename must be escaped by backslash.
See further examples and details in the MANUAL.
This option can be used multiple times.
.IP "--ftp-account [data]"
(FTP) When an FTP server asks for "account data" after user name and password
has been provided, this data is sent off using the ACCT command. (Added in
7.13.0)
If this option is used several times, the last one will be used.
.IP "--ftp-alternative-to-user <command>"
(FTP) If authenticating with the USER and PASS commands fails, send this
command. When connecting to Tumbleweed's Secure Transport server over FTPS
using a client certificate, using "SITE AUTH" will tell the server to retrieve
the username from the certificate. (Added in 7.15.5)
.IP "--ftp-create-dirs"
(FTP/SFTP) When an FTP or SFTP URL/operation uses a path that doesn't
currently exist on the server, the standard behavior of curl is to
fail. Using this option, curl will instead attempt to create missing
directories.
.IP "--ftp-method [method]"
(FTP) Control what method curl should use to reach a file on an FTP(S)
server. The method argument should be one of the following alternatives:
.RS
.IP multicwd
curl does a single CWD operation for each path part in the given URL. For deep
hierarchies this means very many commands. This is how RFC 1738 says it should
be done. This is the default but the slowest behavior.
.IP nocwd
curl does no CWD at all. curl will do SIZE, RETR, STOR etc and give a full
path to the server for all these commands. This is the fastest behavior.
.IP singlecwd
curl does one CWD with the full target directory and then operates on the file
\&"normally" (like in the multicwd case). This is somewhat more standards
compliant than 'nocwd' but without the full penalty of 'multicwd'.
.RE
(Added in 7.15.1)
.IP "--ftp-pasv"
(FTP) Use passive mode for the data connection. Passive is the internal default
behavior, but using this option can be used to override a previous
\fI-P/-ftp-port\fP option. (Added in 7.11.0)
If this option is used several times, only the first one is used. Undoing an
enforced passive really isn't doable but you must then instead enforce the
correct \fI-P, --ftp-port\fP again.
Passive mode means that curl will try the EPSV command first and then PASV,
unless \fI--disable-epsv\fP is used.
.IP "--ftp-skip-pasv-ip"
(FTP) Tell curl to not use the IP address the server suggests in its response
to curl's PASV command when curl connects the data connection. Instead curl
will re-use the same IP address it already uses for the control
connection. (Added in 7.14.2)
This option has no effect if PORT, EPRT or EPSV is used instead of PASV.
.IP "--ftp-pret"
(FTP) Tell curl to send a PRET command before PASV (and EPSV). Certain
FTP servers, mainly drftpd, require this non-standard command for
directory listings as well as up and downloads in PASV mode.
(Added in 7.20.x)
.IP "--ftp-ssl-ccc"
(FTP) Use CCC (Clear Command Channel)
Shuts down the SSL/TLS layer after authenticating. The rest of the
control channel communication will be unencrypted. This allows
NAT routers to follow the FTP transaction. The default mode is
passive. See \fI--ftp-ssl-ccc-mode\fP for other modes.
(Added in 7.16.1)
.IP "--ftp-ssl-ccc-mode [active/passive]"
(FTP) Use CCC (Clear Command Channel)
Sets the CCC mode. The passive mode will not initiate the shutdown, but
instead wait for the server to do it, and will not reply to the
shutdown from the server. The active mode initiates the shutdown and
waits for a reply from the server.
(Added in 7.16.2)
.IP "--ftp-ssl-control"
(FTP) Require SSL/TLS for the FTP login, clear for transfer. Allows secure
authentication, but non-encrypted data transfers for efficiency. Fails the
transfer if the server doesn't support SSL/TLS. (Added in 7.16.0)
that can still be used but will be removed in a future version.
.IP "--form-string <name=string>"
(HTTP) Similar to \fI--form\fP except that the value string for the named
parameter is used literally. Leading \&'@' and \&'<' characters, and the
\&';type=' string in the value have no special meaning. Use this in preference
to \fI--form\fP if there's any possibility that the string value may
accidentally trigger the \&'@' or \&'<' features of \fI--form\fP.
.IP "-g, --globoff"
This option switches off the "URL globbing parser". When you set this option,
you can specify URLs that contain the letters {}[] without having them being
interpreted by curl itself. Note that these letters are not normal legal URL
contents but they should be encoded according to the URI standard.
.IP "-G, --get"
When used, this option will make all data specified with \fI-d, --data\fP,
\fI--data-binary\fP or \fI--data-urlencode\fP to be used in an HTTP GET
request instead of the POST request that otherwise would be used. The data
will be appended to the URL with a '?' separator.
If used in combination with -I, the POST data will instead be appended to the
URL with a HEAD request.
If this option is used several times, only the first one is used. This is
because undoing a GET doesn't make sense, but you should then instead enforce
the alternative method you prefer.
.IP "-H, --header <header>"
(HTTP) Extra header to include in the request when sending HTTP to a
server. You may specify any number of extra headers. Note that if you should
add a custom header that has the same name as one of the internal ones curl
would use, your externally set header will be used instead of the internal
one. This allows you to make even trickier stuff than curl would normally
do. You should not replace internally set headers without knowing perfectly
well what you're doing. Remove an internal header by giving a replacement
without content on the right side of the colon, as in: -H \&"Host:". If you
send the custom header with no-value then its header must be terminated with a
semicolon, such as \-H \&"X-Custom-Header;" to send "X-Custom-Header:".
curl will make sure that each header you add/replace is sent with the proper
end-of-line marker, you should thus \fBnot\fP add that as a part of the header
content: do not add newlines or carriage returns, they will only mess things up
for you.
See also the \fI-A, --user-agent\fP and \fI-e, --referer\fP options.
Starting in 7.37.0, you need \fI--proxy-header\fP to send custom headers
intended for a proxy.
This option can be used multiple times to add/replace/remove multiple headers.
.IP "--hostpubmd5 <md5>"
(SCP/SFTP) Pass a string containing 32 hexadecimal digits. The string should
be the 128 bit MD5 checksum of the remote host's public key, curl will refuse
the connection with the host unless the md5sums match. (Added in 7.17.1)
.IP "--ignore-content-length"
(HTTP)
Ignore the Content-Length header. This is particularly useful for servers
running Apache 1.x, which will report incorrect Content-Length for files
larger than 2 gigabytes.
.IP "-i, --include"
(HTTP) Include the HTTP-header in the output. The HTTP-header includes things
like server-name, date of the document, HTTP-version and more...
.IP "-I, --head"
(HTTP/FTP/FILE)
Fetch the HTTP-header only! HTTP-servers feature the command HEAD
which this uses to get nothing but the header of a document. When used
on an FTP or FILE file, curl displays the file size and last modification
time only.
.IP "--interface <name>"
Perform an operation using a specified interface. You can enter interface
name, IP address or host name. An example could look like:
curl --interface eth0:1 http://www.netscape.com/
If this option is used several times, the last one will be used.
.IP "-j, --junk-session-cookies"
(HTTP) When curl is told to read cookies from a given file, this option will
make it discard all "session cookies". This will basically have the same effect
as if a new session is started. Typical browsers always discard session
cookies when they're closed down.
.IP "-J, --remote-header-name"
(HTTP) This option tells the \fI-O, --remote-name\fP option to use the
server-specified Content-Disposition filename instead of extracting a filename
from the URL.
There's no attempt to decode %-sequences (yet) in the provided file name, so
this option may provide you with rather unexpected file names.
.IP "-k, --insecure"
(SSL) This option explicitly allows curl to perform "insecure" SSL connections
and transfers. All SSL connections are attempted to be made secure by using
the CA certificate bundle installed by default. This makes all connections
considered "insecure" fail unless \fI-k, --insecure\fP is used.
See this online resource for further details:
\fBhttp://curl.haxx.se/docs/sslcerts.html\fP
.IP "-K, --config <config file>"
Specify which config file to read curl arguments from. The config file is a
text file in which command line arguments can be written which then will be
used as if they were written on the actual command line.
Options and their parameters must be specified on the same config file line,
separated by whitespace, colon, or the equals sign. Long option names can
optionally be given in the config file without the initial double dashes and
if so, the colon or equals characters can be used as separators. If the option
is specified with one or two dashes, there can be no colon or equals character
between the option and its parameter.
If the parameter is to contain whitespace, the parameter must be enclosed
within quotes. Within double quotes, the following escape sequences are
available: \\\\, \\", \\t, \\n, \\r and \\v. A backslash preceding any other
letter is ignored. If the first column of a config line is a '#' character,
the rest of the line will be treated as a comment. Only write one option per
physical line in the config file.
Specify the filename to -K, --config as '-' to make curl read the file from
stdin.
Note that to be able to specify a URL in the config file, you need to specify
it using the \fI--url\fP option, and not by simply writing the URL on its own
line. So, it could look similar to this:
url = "http://curl.haxx.se/docs/"
When curl is invoked, it always (unless \fI-q\fP is used) checks for a default
config file and uses it if found. The default config file is checked for in
the following places in this order:
1) curl tries to find the "home dir": It first checks for the CURL_HOME and
then the HOME environment variables. Failing that, it uses getpwuid() on
UNIX-like systems (which returns the home dir given the current user in your
system). On Windows, it then checks for the APPDATA variable, or as a last
resort the '%USERPROFILE%\\Application Data'.
2) On windows, if there is no _curlrc file in the home dir, it checks for one
in the same dir the curl executable is placed. On UNIX-like systems, it will
simply try to load .curlrc from the determined home dir.
.nf
# --- Example file ---
# this is a comment
url = "curl.haxx.se"
output = "curlhere.html"
user-agent = "superagent/1.0"
# and fetch another URL too
url = "curl.haxx.se/docs/manpage.html"
-O
referer = "http://nowhereatall.com/"
# --- End of example file ---
.fi
This option can be used multiple times to load multiple config files.
.IP "--keepalive-time <seconds>"
This option sets the time a connection needs to remain idle before sending
keepalive probes and the time between individual keepalive probes. It is
currently effective on operating systems offering the TCP_KEEPIDLE and
TCP_KEEPINTVL socket options (meaning Linux, recent AIX, HP-UX and more). This
option has no effect if \fI--no-keepalive\fP is used. (Added in 7.18.0)
If this option is used several times, the last one will be used. If
unspecified, the option defaults to 60 seconds.
.IP "--key <key>"
(SSL/SSH) Private key file name. Allows you to provide your private key in this
separate file.
If this option is used several times, the last one will be used.
.IP "--key-type <type>"
(SSL) Private key file type. Specify which type your \fI--key\fP provided
private key is. DER, PEM, and ENG are supported. If not specified, PEM is
assumed.
If this option is used several times, the last one will be used.
.IP "--krb <level>"
(FTP) Enable Kerberos authentication and use. The level must be entered and
should be one of 'clear', 'safe', 'confidential', or 'private'. Should you use
a level that is not one of these, 'private' will instead be used.
This option requires a library built with kerberos4 support. This is not
very common. Use \fI-V, --version\fP to see if your curl supports it.
If this option is used several times, the last one will be used.
.IP "-l, --list-only"
(FTP)
When listing an FTP directory, this switch forces a name-only view. This is
especially useful if the user wants to machine-parse the contents of an FTP
directory since the normal directory view doesn't use a standard look or
format. When used like this, the option causes a NLST command to be sent to
the server instead of LIST.
Note: Some FTP servers list only files in their response to NLST; they do not
include sub-directories and symbolic links.
(POP3)
When retrieving a specific email from POP3, this switch forces a LIST command
to be performed instead of RETR. This is particularly useful if the user wants
to see if a specific message id exists on the server and what size it is.
Note: When combined with \fI-X, --request <command>\fP, this option can be used
to send an UIDL command instead, so the user may use the email's unique
identifier rather than it's message id to make the request. (Added in 7.21.5)
.IP "-L, --location"
(HTTP/HTTPS) If the server reports that the requested page has moved to a
different location (indicated with a Location: header and a 3XX response code),
this option will make curl redo the request on the new place. If used together
with \fI-i, --include\fP or \fI-I, --head\fP, headers from all requested pages
will be shown. When authentication is used, curl only sends its credentials to
the initial host. If a redirect takes curl to a different host, it won't be
able to intercept the user+password. See also \fI--location-trusted\fP on how
to change this. You can limit the amount of redirects to follow by using the
\fI--max-redirs\fP option.
When curl follows a redirect and the request is not a plain GET (for example
POST or PUT), it will do the following request with a GET if the HTTP response
was 301, 302, or 303. If the response code was any other 3xx code, curl will
re-send the following request using the same unmodified method.
You can tell curl to not change the non-GET request method to GET after a 30x
response by using the dedicated options for that: \fI--post301\fP,
\fI--post302\fP and \fI-post303\fP.
.IP "--libcurl <file>"
Append this option to any ordinary curl command line, and you will get a
libcurl-using C source code written to the file that does the equivalent
of what your command-line operation does!
If this option is used several times, the last given file name will be
used. (Added in 7.16.1)
.IP "--limit-rate <speed>"
Specify the maximum transfer rate you want curl to use - for both downloads
and uploads. This feature is useful if you have a limited pipe and you'd like
your transfer not to use your entire bandwidth. To make it slower than it
otherwise would be.
The given speed is measured in bytes/second, unless a suffix is appended.
Appending 'k' or 'K' will count the number as kilobytes, 'm' or M' makes it
megabytes, while 'g' or 'G' makes it gigabytes. Examples: 200K, 3m and 1G.
The given rate is the average speed counted during the entire transfer. It
means that curl might use higher transfer speeds in short bursts, but over
time it uses no more than the given rate.
If you also use the \fI-Y, --speed-limit\fP option, that option will take
precedence and might cripple the rate-limiting slightly, to help keeping the
speed-limit logic working.
If this option is used several times, the last one will be used.
.IP "--local-port <num>[-num]"
Set a preferred number or range of local port numbers to use for the
connection(s). Note that port numbers by nature are a scarce resource that
will be busy at times so setting this range to something too narrow might
cause unnecessary connection setup failures. (Added in 7.15.2)
.IP "--location-trusted"
(HTTP/HTTPS) Like \fI-L, --location\fP, but will allow sending the name +
password to all hosts that the site may redirect to. This may or may not
introduce a security breach if the site redirects you to a site to which
you'll send your authentication info (which is plaintext in the case of HTTP
Basic authentication).
.IP "-m, --max-time <seconds>"
Maximum time in seconds that you allow the whole operation to take. This is
useful for preventing your batch jobs from hanging for hours due to slow
networks or links going down. Since 7.32.0, this option accepts decimal
values, but the actual timeout will decrease in accuracy as the specified
timeout increases in decimal precision. See also the \fI--connect-timeout\fP
option.
If this option is used several times, the last one will be used.
.IP "--login-options <options>"
Specify the login options to use during server authentication.
You can use the login options to specify protocol specific options that may
be used during authentication. At present only IMAP, POP3 and SMTP support
login options. For more information about the login options please see
RFC 2384, RFC 5092 and IETF draft draft-earhart-url-smtp-00.txt (Added in
7.34.0).
If this option is used several times, the last one will be used.
.IP "--mail-auth <address>"
(SMTP) Specify a single address. This will be used to specify the
authentication address (identity) of a submitted message that is being relayed
to another server.
(Added in 7.25.0)
.IP "--mail-from <address>"
(SMTP) Specify a single address that the given mail should get sent from.
(Added in 7.20.0)
.IP "--max-filesize <bytes>"
Specify the maximum size (in bytes) of a file to download. If the file
requested is larger than this value, the transfer will not start and curl will
return with exit code 63.
\fBNOTE:\fP The file size is not always known prior to download, and for such
files this option has no effect even if the file transfer ends up being larger
than this given limit. This concerns both FTP and HTTP transfers.
.IP "--mail-rcpt <address>"
(SMTP) Specify a single address, user name or mailing list name.
When performing a mail transfer, the recipient should specify a valid email
address to send the mail to. (Added in 7.20.0)
When performing an address verification (VRFY command), the recipient should be
specified as the user name or user name and domain (as per Section 3.5 of
RFC5321). (Added in 7.34.0)
When performing a mailing list expand (EXPN command), the recipient should be
specified using the mailing list name, such as "Friends" or "London-Office".
(Added in 7.34.0)
.IP "--max-redirs <num>"
Set maximum number of redirection-followings allowed. If \fI-L, --location\fP
is used, this option can be used to prevent curl from following redirections
\&"in absurdum". By default, the limit is set to 50 redirections. Set this
option to -1 to make it limitless.
If this option is used several times, the last one will be used.
.IP "--metalink"
This option can tell curl to parse and process a given URI as Metalink file
(both version 3 and 4 (RFC 5854) are supported) and make use of the mirrors
listed within for failover if there are errors (such as the file or server not
being available). It will also verify the hash of the file after the download
completes. The Metalink file itself is downloaded and processed in memory and
not stored in the local file system.
Example to use a remote Metalink file:
\fBcurl\fP --metalink http://www.example.com/example.metalink
To use a Metalink file in the local file system, use FILE protocol
(file://):
\fBcurl\fP --metalink file://example.metalink
Please note that if FILE protocol is disabled, there is no way to use
a local Metalink file at the time of this writing. Also note that if
\fI--metalink\fP and \fI--include\fP are used together, \fI--include\fP will be
ignored. This is because including headers in the response will break
Metalink parser and if the headers are included in the file described
in Metalink file, hash check will fail.
(Added in 7.27.0, if built against the libmetalink library.)
.IP "-n, --netrc"
Makes curl scan the \fI.netrc\fP (\fI_netrc\fP on Windows) file in the user's
home directory for login name and password. This is typically used for FTP on
UNIX. If used with HTTP, curl will enable user authentication. See
.BR netrc(4)
or
.BR ftp(1)
for details on the file format. Curl will not complain if that file
doesn't have the right permissions (it should not be either world- or
group-readable). The environment variable "HOME" is used to find the home