diff --git a/Makefile.am b/Makefile.am index 61cc5ec..18d5f61 100644 --- a/Makefile.am +++ b/Makefile.am @@ -136,8 +136,8 @@ WINBUILD_DIST = winbuild/BUILD.WINDOWS.txt winbuild/gen_resp_file.bat \ winbuild/MakefileBuild.vc winbuild/Makefile.vc \ winbuild/Makefile.msvc.names -EXTRA_DIST = CHANGES COPYING maketgz Makefile.dist curl-config.in \ - RELEASE-NOTES buildconf libcurl.pc.in MacOSX-Framework scripts/zsh.pl \ +EXTRA_DIST = CHANGES COPYING maketgz Makefile.dist gnurl-config.in \ + RELEASE-NOTES buildconf libgnurl.pc.in MacOSX-Framework scripts/zsh.pl \ $(CMAKE_DIST) $(VC_DIST) $(WINBUILD_DIST) lib/libcurl.vers.in \ buildconf.bat @@ -147,13 +147,13 @@ CLEANFILES = $(VC6_LIBDSP) $(VC6_SRCDSP) $(VC7_LIBVCPROJ) $(VC7_SRCVCPROJ) \ $(VC11_LIBVCXPROJ) $(VC11_SRCVCXPROJ) $(VC12_LIBVCXPROJ) $(VC12_SRCVCXPROJ) \ $(VC14_LIBVCXPROJ) $(VC14_SRCVCXPROJ) -bin_SCRIPTS = curl-config +bin_SCRIPTS = gnurl-config SUBDIRS = lib src include scripts DIST_SUBDIRS = $(SUBDIRS) tests packages docs pkgconfigdir = $(libdir)/pkgconfig -pkgconfig_DATA = libcurl.pc +pkgconfig_DATA = libgnurl.pc # List of files required to generate VC IDE .dsp, .vcproj and .vcxproj files include lib/Makefile.inc diff --git a/README b/README index f0b3b93..28e8cd8 100644 --- a/README +++ b/README @@ -1,3 +1,126 @@ +libgnurl is a fork of libcurl with the following major changes: + +Compilation requirements: +* libgnurl must be compiled so that it supports only HTTP and HTTPS + (remove Gopher, SSH, IMAP, etc.) +* libgnurl must be compiled so that it supports only GnuTLS + (remove CaySSL, QsoSSL, GSKit, etc.) +* removed support for NTLM, GSSAPI, SPNEGO, LDAP, metalink, HTTP2 + +Changes to the code: +* renamed the library binary from 'libcurl' to 'lignurl' + +Usage notes: +* exported symbols were NOT renamed, so they still all have the + curl prefix; you should be able to start using libgnurl simply + by changing -lcurl to -lgnurl. + +Note that the compilation requirements were not hard-coded, but +are rather socially enforced: if you compile libgnurl, please +use the following options to configure: + +./configure --enable-ipv6 --with-gnutls --without-libssh2 --without-libmetalink --without-winidn --without-librtmp --without-nghttp2 --without-nss --without-cyassl --without-polarssl --without-ssl --without-winssl --without-darwinssl --disable-sspi --disable-ntlm-wb --disable-ldap --disable-rtsp --disable-dict --disable-telnet --disable-tftp --disable-pop3 --disable-imap --disable-smtp --disable-gopher --disable-file --disable-ftp --disable-smb + +Naturally, you're free to specify additional options, such as +"--prefix". The result should have support only for HTTP, HTTPS (via +GnuTLS), IDN, zlib and TLS-SRP. + + + +Motivation: + +cURL supports a bunch of crypto backends. GNUnet requires the use of +GnuTLS, but other variants are used by some distributions. Supporting +other crypto backends would again expose us to a wider array of +security issues, may create licensing issues and most importantly +introduce new bugs as some crypto backends are known to introduce +subtle runtime issues. While it is possible to have two versions of +libcurl installed on the same system, this is error-prone, especially +as if we are linked against the wrong version, the bugs that arise +might be rather subtle. + +For GNUnet, we also need a particularly modern version of +GnuTLS. Thus, it would anyway be necessary to recompile cURL for +GNUnet. But what happens if one links cURL against this version of +GnuTLS? Well, first one would install GnuTLS by hand in the +system. Then, we build cURL. cURL will build against it just fine, but +the linker will eventually complain bitterly. The reason is that cURL +also links against a bunch of other system libraries (gssapi, ldap, +ssh2, rtmp, krb5, sasl2, see discussion on obscure protocols above), +which --- as they are part of the distribution --- were linked against +an older version of GnuTLS. As a result, the same binary would be +linked against two different versions of GnuTLS. That is typically a +recipe for disaster. Thus, in order to avoid updating a dozen system +libraries (and having two versions of those installed), it is +necessary to disable all of those cURL features that GNUnet does not +use, and there are many of those. For GNUnet, the more obscure +protocols supported by cURL are close to dead code --- mostly +harmless, but not useful. However, as some application may use one of +those features, distributions are typically forced to enable all of +those features, and thus including security issues that might arise +from that code. + +So to use a modern version of GnuTLS, a sane approach is to disable +all of the "optional" features of cURL that drag in system libraries +that link against the older GnuTLS. That works, except that one should +then NEVER install that version of libcurl in say /usr or /usr/local, +as that may break other parts of the system that might depend on these +features that we just disabled. Libtool versioning doesn't help here, +as it is not intended to deal with libraries that have optional +features. Naturally, installing cURL somewhere else is also +problematic, as we now need to be really careful that the linker will +link GNUnet against the right version. Note that none of this can +really be trivially fixed by the cURL developers. Rename to Fix + +At this point, developers that don't want to rebuild an entire +distribution from scratch get grumpy. Grumpy developers do silly +things, like forking code to fix it. I called the fork gnurl (to be +pronounced with a grumpy voice and an emphasis on the R) as it is bits +of cURL, a bit more GNUish, for GnuNet, and gnurl can be pronounced to +indicate the grumpy origins. + +How does forking fix it? Easy. First, we can get rid of all of the +compatibility issues --- if you use libgnurl, you state that you don't +need anything but HTTP/HTTPS. Those applications that need more, +should stick with the original cURL. Those that do not, can choose to +move to something simpler. As the library gets a new name, we do not +have to worry about tons of packages breaking as soon as one rebuilds +it. So renaming itself and saying that "libgnurl = libcurl with only +HTTP/HTTPS support and GnuTLS" fixes 99% of the problems that darkened +my mood. Note that this pretty much CANNOT be done without a fork, as +renaming is an essential part of the fix. Now, there might be creative +solutions to achieve the same thing within the standard cURL build +system, but I'm not happy to wait for a decade for Daniel to review +the patches. The changes libgnurl makes to curl are miniscule and can +easily be applied again and again whenever libcurl makes a new +release. + + +Summary: + +I want to note that the main motiviations for this fork are technical +The goal of the cURL project is clearly to support many crypto +backends and many protocols. That is a worthy goal, and I wish them +luck with it. The goal for libgnurl is to support only HTTP and HTTPS +(and only HTTP 1.x) with a single crypto backend (GnuTLS) to ensure a +small footprint and uniform experience for developers regardless of +how libcurl was compiled. + + +Using libgnurl: + +Projects that use cURL only for HTTP/HTTPS and that would work with +GnuTLS should be able to switch to libgnurl by changing "-lcurl" to +"-lgnurl". That's it. No changes to the source code should be +required. Continue to read the cURL documentation --- as libgnurl +strives for bug-for-bug compatibility with the HTTP/HTTPS/GnuTLS +subset of cURL. However, we're happy to add new features relating to +this core subset and might be easier to convince than the cURL +developers. ;-) + +Now, on to the cURL documentation... + + _ _ ____ _ ___| | | | _ \| | / __| | | | |_) | | diff --git a/configure.ac b/configure.ac index b208d4d..6aff8a4 100644 --- a/configure.ac +++ b/configure.ac @@ -24,7 +24,7 @@ dnl Process this file with autoconf to produce a configure script. AC_PREREQ(2.57) dnl We don't know the version number "statically" so we use a dash here -AC_INIT([curl], [-], [a suitable curl mailing list: https://curl.haxx.se/mail/]) +AC_INIT([gnurl], [-], [a suitable curl mailing list: https://curl.haxx.se/mail/]) XC_OVR_ZZ50 XC_OVR_ZZ60 @@ -1323,14 +1323,7 @@ if test x"$want_gss" = xyes; then esac else LDFLAGS="$LDFLAGS $GSSAPI_LIB_DIR" - case $host in - *-hp-hpux*) - LIBS="-lgss $LIBS" - ;; - *) - LIBS="-lgssapi $LIBS" - ;; - esac + LIBS="-lgssapi $LIBS" fi else CPPFLAGS="$save_CPPFLAGS" @@ -3862,8 +3855,8 @@ AC_CONFIG_FILES([Makefile \ packages/AIX/Makefile \ packages/AIX/RPM/Makefile \ packages/AIX/RPM/curl.spec \ - curl-config \ - libcurl.pc + gnurl-config \ + libgnurl.pc ]) AC_OUTPUT diff --git a/curl-config.in b/curl-config.in deleted file mode 100644 index af484b4..0000000 --- a/curl-config.in +++ /dev/null @@ -1,178 +0,0 @@ -#! /bin/sh -#*************************************************************************** -# _ _ ____ _ -# Project ___| | | | _ \| | -# / __| | | | |_) | | -# | (__| |_| | _ <| |___ -# \___|\___/|_| \_\_____| -# -# Copyright (C) 2001 - 2012, Daniel Stenberg, , 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 https://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. -# -########################################################################### - -prefix=@prefix@ -exec_prefix=@exec_prefix@ -includedir=@includedir@ -cppflag_curl_staticlib=@CPPFLAG_CURL_STATICLIB@ - -usage() -{ - cat <&2 - exit 1 - fi - ;; - - --configure) - echo @CONFIGURE_OPTIONS@ - ;; - - *) - echo "unknown option: $1" - usage 1 - ;; - esac - shift -done - -exit 0 diff --git a/docs/Makefile.am b/docs/Makefile.am index b202a5d..281fb9a 100644 --- a/docs/Makefile.am +++ b/docs/Makefile.am @@ -22,10 +22,10 @@ AUTOMAKE_OPTIONS = foreign no-dependencies -man_MANS = curl.1 curl-config.1 +man_MANS = gnurl.1 gnurl-config.1 noinst_man_MANS = mk-ca-bundle.1 -GENHTMLPAGES = curl.html curl-config.html mk-ca-bundle.html -PDFPAGES = curl.pdf curl-config.pdf mk-ca-bundle.pdf +GENHTMLPAGES = gnurl.html gnurl-config.html mk-ca-bundle.html +PDFPAGES = gnurl.pdf gnurl-config.pdf mk-ca-bundle.pdf HTMLPAGES = $(GENHTMLPAGES) index.html diff --git a/docs/curl-config.1 b/docs/curl-config.1 deleted file mode 100644 index 4c1e323..0000000 --- a/docs/curl-config.1 +++ /dev/null @@ -1,98 +0,0 @@ -.\" ************************************************************************** -.\" * _ _ ____ _ -.\" * Project ___| | | | _ \| | -.\" * / __| | | | |_) | | -.\" * | (__| |_| | _ <| |___ -.\" * \___|\___/|_| \_\_____| -.\" * -.\" * Copyright (C) 1998 - 2012, Daniel Stenberg, , 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 https://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-config 1 "25 Oct 2007" "Curl 7.17.1" "curl-config manual" -.SH NAME -curl-config \- Get information about a libcurl installation -.SH SYNOPSIS -.B curl-config [options] -.SH DESCRIPTION -.B curl-config -displays information about the curl and libcurl installation. -.SH OPTIONS -.IP "--ca" -Displays the built-in path to the CA cert bundle this libcurl uses. -.IP "--cc" -Displays the compiler used to build libcurl. -.IP "--cflags" -Set of compiler options (CFLAGS) to use when compiling files that use -libcurl. Currently that is only the include path to the curl include files. -.IP "--checkfor [version]" -Specify the oldest possible libcurl version string you want, and this -script will return 0 if the current installation is new enough or it -returns 1 and outputs a text saying that the current version is not new -enough. (Added in 7.15.4) -.IP "--configure" -Displays the arguments given to configure when building curl. -.IP "--feature" -Lists what particular main features the installed libcurl was built with. At -the time of writing, this list may include SSL, KRB4 or IPv6. Do not assume -any particular order. The keywords will be separated by newlines. There may be -none, one, or several keywords in the list. -.IP "--help" -Displays the available options. -.IP "--libs" -Shows the complete set of libs and other linker options you will need in order -to link your application with libcurl. -.IP "--prefix" -This is the prefix used when libcurl was installed. Libcurl is then installed -in $prefix/lib and its header files are installed in $prefix/include and so -on. The prefix is set with "configure --prefix". -.IP "--protocols" -Lists what particular protocols the installed libcurl was built to support. At -the time of writing, this list may include HTTP, HTTPS, FTP, FTPS, FILE, -TELNET, LDAP, DICT. Do not assume any particular order. The protocols will -be listed using uppercase and are separated by newlines. There may be none, -one, or several protocols in the list. (Added in 7.13.0) -.IP "--static-libs" -Shows the complete set of libs and other linker options you will need in order -to link your application with libcurl statically. (Added in 7.17.1) -.IP "--version" -Outputs version information about the installed libcurl. -.IP "--vernum" -Outputs version information about the installed libcurl, in numerical mode. -This outputs the version number, in hexadecimal, with 8 bits for each part; -major, minor, patch. So that libcurl 7.7.4 would appear as 070704 and libcurl -12.13.14 would appear as 0c0d0e... Note that the initial zero might be -omitted. (This option was broken in the 7.15.0 release.) -.SH "EXAMPLES" -What linker options do I need when I link with libcurl? - - $ curl-config --libs - -What compiler options do I need when I compile using libcurl functions? - - $ curl-config --cflags - -How do I know if libcurl was built with SSL support? - - $ curl-config --feature | grep SSL - -What's the installed libcurl version? - - $ curl-config --version - -How do I build a single file with a one-line command? - - $ `curl-config --cc --cflags` -o example example.c `curl-config --libs` -.SH "SEE ALSO" -.BR curl (1) diff --git a/docs/curl.1 b/docs/curl.1 deleted file mode 100644 index 0b0f4d2..0000000 --- a/docs/curl.1 +++ /dev/null @@ -1,2369 +0,0 @@ -.\" ************************************************************************** -.\" * _ _ ____ _ -.\" * Project ___| | | | _ \| | -.\" * / __| | | | |_) | | -.\" * | (__| |_| | _ <| |___ -.\" * \___|\___/|_| \_\_____| -.\" * -.\" * Copyright (C) 1998 - 2016, Daniel Stenberg, , 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 https://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 "30 Nov 2014" "Curl 7.40.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, SMB, SMBS, 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 -\fIlibcurl(3)\fP 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 - -When using [] or {} sequences when invoked from a command line prompt, you -probably have to put the full URL within double quotes to avoid the shell from -interfering with it. This also goes for other characters treated special, like -for example '&', '?' and '*'. - -Provide the IPv6 zone index in the URL with an escaped percentage sign and the -interface name. Like in - - http://[fe80::3%25eth0]/ - -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. Sometimes curl is built without SSLv2 support. SSLv2 is widely -considered insecure (see RFC 6176). -.IP "-3, --sslv3" -(SSL) Forces curl to use SSL version 3 when negotiating with a remote SSL -server. Sometimes curl is built without SSLv3 support. SSLv3 is widely -considered insecure (see RFC 7568). -.IP "-4, --ipv4" -This option tells curl to resolve names to IPv4 addresses only, and not for -example try IPv6. -.IP "-6, --ipv6" -This option tells curl to resolve names to IPv6 addresses only, and not for -example try IPv4. -.IP "-a, --append" -(FTP/SFTP) When used in an upload, this makes curl append to the target file -instead of overwriting it. If the remote file doesn't exist, it will be -created. Note that this flag is ignored by some SFTP servers (including -OpenSSH). -.IP "-A, --user-agent " -(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 " -(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 engine 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 (Set-Cookie style) or -the Netscape/Mozilla cookie file format. - -The file specified with \fI-b, --cookie\fP is only used as input. No cookies -will be written to the file. To store cookies, use the \fI-c, --cookie-jar\fP -option. - -Exercise caution if you are using this option and multiple transfers may occur. -If you use the NAME1=VALUE1; format, or in a file use the Set-Cookie format and -don't specify a domain, then the cookie is sent for any domain (even after -redirects are followed) and cannot be modified by a server-set cookie. If the -cookie engine is enabled and a server sets a cookie of the same name then both -will be sent on a future transfer to that server, likely not what you intended. -To address these issues set a domain in Set-Cookie (doing that will include -sub-domains) or use the Netscape format. - -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 with the remote host. 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). - -Used together with \fI-u, --user\fP and \fI-x, --proxy\fP. - -See also \fI--proxy-basic\fP. -.IP "-c, --cookie-jar " -(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 data 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. - -Since 7.43.0 cookies that were imported in the Set-Cookie format without a -domain name are not exported by this option. - -If this option is used several times, the last specified file name will be -used. -.IP "-C, --continue-at " -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 " -(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: -\fIhttps://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: -\fIhttps://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 " -Maximum time in seconds that you allow curl's connection to take. This only -limits the connection phase, so if curl connects within the given period it -will continue - if not it will exit. Since version 7.32.0, this option -accepts decimal values. - -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" -Convert LF to CRLF in upload. Useful for MVS (OS/390). - -(SMTP added in 7.40.0) -.IP "--crlfile " -(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 " -(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. \fI--data-raw\fP is almost -the same but does not have a special interpretation of the @ character. 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. If you don't want the @ character to have a special -interpretation use \fI--data-raw\fP instead. -.IP "-D, --dump-header " -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 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 " -See \fI-d, --data\fP. -.IP "--data-binary " -(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-raw " -(HTTP) This posts data similarly to \fI--data\fP but without the special -interpretation of the @ character. See \fI-d, --data\fP. -(Added in 7.43.0) -.IP "--data-urlencode " -(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 part should begin with a \fIname\fP followed -by a separator and a content specification. The 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. - -If the server is an IPv6 host, this option will have no effect as EPRT is -necessary then. - -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. - -If the server is an IPv6 host, this option will have no effect as EPSV is -necessary then. - -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 " -Tell curl to send outgoing DNS requests through . 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 " -Tell curl to bind to 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 " -Tell curl to bind to 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 " -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:\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 " -(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 " -(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 client 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 " -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 " -(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 "--expect100-timeout " -(HTTP) Maximum time in seconds that you allow curl to wait for a 100-continue -response when curl emits an Expects: 100-continue header in its request. By -default curl will wait one second. This option accepts decimal values! When -curl stops waiting, it will continue as if the response has been received. - -(Added in 7.47.0) -.IP "--cert-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 " -(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 " -(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 "--pinnedpubkey " -(SSL) Tells curl to use the specified public key file (or hashes) to verify the -peer. This can be a path to a file which contains a single public key in PEM or -DER format, or any number of base64 encoded sha256 hashes preceded by -\'sha256//\' and separated by \';\' - -When negotiating a TLS or SSL connection, the server sends a certificate -indicating its identity. A public key is extracted from this certificate and -if it does not exactly match the public key provided to this option, curl will -abort the connection before sending or receiving any data. - -Added in 7.39.0 for OpenSSL, GnuTLS and GSKit. Added in 7.43.0 for NSS and -wolfSSL/CyaSSL. sha256 support added in 7.44.0 for OpenSSL, -GnuTLS, NSS and wolfSSL/CyaSSL. Other SSL backends not supported. - -If this option is used several times, the last one will be used. -.IP "--cert-status" -(SSL) Tells curl to verify the status of the server certificate by using the -Certificate Status Request (aka. OCSP stapling) TLS extension. - -If this option is enabled and the server sends an invalid (e.g. expired) -response, if the response suggests that the server certificate has been revoked, -or no response at all is received, the verification fails. - -This is currently only implemented in the OpenSSL, GnuTLS and NSS backends. -(Added in 7.41.0) -.IP "--false-start" - -(SSL) Tells curl to use false start during the TLS handshake. False start is a -mode where a TLS client will start sending application data before verifying -the server's Finished message, thus saving a round trip when performing a full -handshake. - -This is currently only implemented in the NSS and Secure Transport (on iOS 7.0 -or later, or OS X 10.9 or later) backends. -(Added in 7.42.0) -.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 " -(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. Unfortunately it does not support reading the -file from a named pipe or similar, as it needs the full size before the -transfer starts. - -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 " -(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 -.IP -(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 " -(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
" -(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. - -Example: - -\&# curl -H "X-First-Name: Joe" http://192.168.0.1/ - -\fBWARNING\fP: headers set with this option will be set in all requests - even -after redirects are followed, like when told with \fB-L, --location\fP. This -can lead to the header being sent to other hosts than the original host, so -sensitive headers should be used with caution combined with following -redirects. - -This option can be used multiple times to add/replace/remove multiple headers. -.IP "--hostpubmd5 " -(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" -For 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. - -For FTP (since 7.46.0), skip the RETR command to figure out the size before -downloading a file. -.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 " -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. - -If the server specifies a file name and a file with that name already exists -in the current working directory it will not be overwritten and an error will -occur. If the server doesn't specify a file name then this option has no -effect. - -There's no attempt to decode %-sequences (yet) in the provided file name, so -this option may provide you with rather unexpected file names. - -\fBWARNING\fP: Exercise judicious use of this option, especially on Windows. A -rogue server could send you the name of a DLL or other file that could possibly -be loaded automatically by Windows or some third party software. -.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: -\fBhttps://curl.haxx.se/docs/sslcerts.html\fP -.IP "-K, --config " -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 = "https://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 " -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 " -(SSL/SSH) Private key file name. Allows you to provide your private key in this -separate file. For SSH, if not specified, curl tries the following candidates -in order: '~/.ssh/id_rsa', '~/.ssh/id_dsa', './id_rsa', './id_dsa'. - -If this option is used several times, the last one will be used. -.IP "--key-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 " -(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 \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 " -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 " -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]" -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 " -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 " -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
" -(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
" -(SMTP) Specify a single address that the given mail should get sent from. - -(Added in 7.20.0) -.IP "--max-filesize " -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
" -(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 " -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 -\fInetrc(5)\fP \fIftp(1)\fP 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 directory. - -A quick and very simple example of how to setup a \fI.netrc\fP to allow curl -to FTP to the machine host.domain.com with user name \&'myself' and password -\&'secret' should look similar to: - -.B "machine host.domain.com login myself password secret" -.IP "-N, --no-buffer" -Disables the buffering of the output stream. In normal work situations, curl -will use a standard buffered output stream that will have the effect that it -will output the data in chunks, not necessarily exactly when the data arrives. -Using this option will disable that buffering. - -Note that this is the negated option name documented. You can thus use -\fI--buffer\fP to enforce the buffering. -.IP "--netrc-file" -This option is similar to \fI--netrc\fP, except that you provide the path -(absolute or relative) to the netrc file that Curl should use. -You can only specify one netrc file per invocation. If several -\fI--netrc-file\fP options are provided, only the \fBlast one\fP will be used. -(Added in 7.21.5) - -This option overrides any use of \fI--netrc\fP as they are mutually exclusive. -It will also abide by \fI--netrc-optional\fP if specified. - -.IP "--netrc-optional" -Very similar to \fI--netrc\fP, but this option makes the .netrc usage -\fBoptional\fP and not mandatory as the \fI--netrc\fP option does. - -.IP "--negotiate" -(HTTP) Enables Negotiate (SPNEGO) authentication. - -If you want to enable Negotiate (SPNEGO) for proxy authentication, then use -\fI--proxy-negotiate\fP. - -This option requires a library built with GSS-API or SSPI support. Use \fI-V, ---version\fP to see if your curl supports GSS-API/SSPI and SPNEGO. - -When using this option, you must also provide a fake \fI-u, --user\fP option to -activate the authentication code properly. Sending a '-u :' is enough as the -user name and password from the \fI-u\fP option aren't actually used. - -If this option is used several times, only the first one is used. -.IP "--no-keepalive" -Disables the use of keepalive messages on the TCP connection, as by default -curl enables them. - -Note that this is the negated option name documented. You can thus use -\fI--keepalive\fP to enforce keepalive. -.IP "--no-sessionid" -(SSL) Disable curl's use of SSL session-ID caching. By default all transfers -are done using the cache. Note that while nothing should ever get hurt by -attempting to reuse SSL session-IDs, there seem to be broken SSL -implementations in the wild that may require you to disable this in order for -you to succeed. (Added in 7.16.0) - -Note that this is the negated option name documented. You can thus use -\fI--sessionid\fP to enforce session-ID caching. -.IP "--noproxy " -Comma-separated list of hosts which do not use a proxy, if one is specified. -The only wildcard is a single * character, which matches all hosts, and -effectively disables the proxy. Each name in this list is matched as either -a domain which contains the hostname, or the hostname itself. For example, -local.com would match local.com, local.com:80, and www.local.com, but not -www.notlocal.com. (Added in 7.19.4). -.IP "--ntlm" -(HTTP) Enables NTLM authentication. The NTLM authentication method was -designed by Microsoft and is used by IIS web servers. It is a proprietary -protocol, reverse-engineered by clever people and implemented in curl based -on their efforts. This kind of behavior should not be endorsed, you should -encourage everyone who uses NTLM to switch to a public and documented -authentication method instead, such as Digest. - -If you want to enable NTLM for your proxy authentication, then use -\fI--proxy-ntlm\fP. - -This option requires a library built with SSL support. Use -\fI-V, --version\fP to see if your curl supports NTLM. - -If this option is used several times, only the first one is used. -.IP "-o, --output " -Write output to instead of stdout. If you are using {} or [] to fetch -multiple documents, you can use '#' followed by a number in the -specifier. That variable will be replaced with the current string for the URL -being fetched. Like in: - - curl http://{one,two}.site.com -o "file_#1.txt" - -or use several variables like: - - curl http://{site,host}.host[1-5].com -o "#1_#2" - -You may use this option as many times as the number of URLs you have. - -See also the \fI--create-dirs\fP option to create the local directories -dynamically. Specifying the output as '-' (a single dash) will force the -output to be done to stdout. -.IP "-O, --remote-name" -Write output to a local file named like the remote file we get. (Only the file -part of the remote file is used, the path is cut off.) - -The file will be saved in the current working directory. If you want the file -saved in a different directory, make sure you change the current working -directory before invoking curl with this option. - -The remote file name to use for saving is extracted from the given URL, nothing -else, and if it already exists it will be overwritten. If you want the server -to be able to choose the file name refer to \fI-J, --remote-header-name\fP -which can be used in addition to this option. If the server chooses a file name -and that name already exists it will not be overwritten. - -There is no URL decoding done on the file name. If it has %20 or other URL -encoded parts of the name, they will end up as-is as file name. - -You may use this option as many times as the number of URLs you have. -.IP "--oauth2-bearer" -(IMAP, POP3, SMTP) -Specify the Bearer Token for OAUTH 2.0 server authentication. The Bearer Token -is used in conjunction with the user name which can be specified as part of the -\fI--url\fP or \fI-u, --user\fP options. - -The Bearer Token and user name are formatted according to RFC 6750. - -If this option is used several times, the last one will be used. -.IP "--proxy-header
" -(HTTP) Extra header to include in the request when sending HTTP to a -proxy. You may specify any number of extra headers. This is the equivalent -option to \fI-H, --header\fP but is for proxy communication only like in -CONNECT requests when you want a separate header sent to the proxy to what is -sent to the actual remote host. - -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. - -Headers specified with this option will not be included in requests that curl -knows will not be sent to a proxy. - -This option can be used multiple times to add/replace/remove multiple headers. - -(Added in 7.37.0) -.IP "-p, --proxytunnel" -When an HTTP proxy is used (\fI-x, --proxy\fP), this option will cause non-HTTP -protocols to attempt to tunnel through the proxy instead of merely using it to -do HTTP-like operations. The tunnel approach is made with the HTTP proxy -CONNECT request and requires that the proxy allows direct connect to the -remote port number curl wants to tunnel through to. -.IP "-P, --ftp-port
" -(FTP) Reverses the default initiator/listener roles when connecting with -FTP. This switch makes curl use active mode. In practice, curl then tells the -server to connect back to the client's specified address and port, while -passive mode asks the server to setup an IP address and port for it to connect -to.
should be one of: -.RS -.IP interface -i.e "eth0" to specify which interface's IP address you want to use (Unix only) -.IP "IP address" -i.e "192.168.10.1" to specify the exact IP address -.IP "host name" -i.e "my.host.domain" to specify the machine -.IP "-" -make curl pick the same IP address that is already used for the control -connection -.RE -.IP -If this option is used several times, the last one will be used. Disable the -use of PORT with \fI--ftp-pasv\fP. Disable the attempt to use the EPRT command -instead of PORT by using \fI--disable-eprt\fP. EPRT is really PORT++. - -Starting in 7.19.5, you can append \&":[start]-[end]\&" to the right of the -address, to tell curl what TCP port range to use. That means you specify a -port range, from a lower to a higher number. A single number works as well, -but do note that it increases the risk of failure since the port may not be -available. -.IP "--pass " -(SSL/SSH) Passphrase for the private key - -If this option is used several times, the last one will be used. -.IP "--path-as-is" -Tell curl to not handle sequences of /../ or /./ in the given URL -path. Normally curl will squash or merge them according to standards but with -this option set you tell it not to do that. - -(Added in 7.42.0) -.IP "--post301" -(HTTP) Tells curl to respect RFC 7230/6.4.2 and not convert POST requests -into GET requests when following a 301 redirection. The non-RFC behaviour is -ubiquitous in web browsers, so curl does the conversion by default to maintain -consistency. However, a server may require a POST to remain a POST after such -a redirection. This option is meaningful only when using \fI-L, --location\fP -(Added in 7.17.1) -.IP "--post302" -(HTTP) Tells curl to respect RFC 7230/6.4.3 and not convert POST requests -into GET requests when following a 302 redirection. The non-RFC behaviour is -ubiquitous in web browsers, so curl does the conversion by default to maintain -consistency. However, a server may require a POST to remain a POST after such -a redirection. This option is meaningful only when using \fI-L, --location\fP -(Added in 7.19.1) -.IP "--post303" -(HTTP) Tells curl to respect RFC 7230/6.4.4 and not convert POST requests -into GET requests when following a 303 redirection. The non-RFC behaviour is -ubiquitous in web browsers, so curl does the conversion by default to maintain -consistency. However, a server may require a POST to remain a POST after such -a redirection. This option is meaningful only when using \fI-L, --location\fP -(Added in 7.26.0) -.IP "--proto " -Tells curl to use the listed protocols for its initial retrieval. Protocols -are evaluated left to right, are comma separated, and are each a protocol -name or 'all', optionally prefixed by zero or more modifiers. Available -modifiers are: -.RS -.TP 3 -.B + -Permit this protocol in addition to protocols already permitted (this is -the default if no modifier is used). -.TP -.B - -Deny this protocol, removing it from the list of protocols already permitted. -.TP -.B = -Permit only this protocol (ignoring the list already permitted), though -subject to later modification by subsequent entries in the comma separated -list. -.RE -.IP -For example: -.RS -.TP 15 -.B --proto -ftps -uses the default protocols, but disables ftps -.TP -.B --proto -all,https,+http -only enables http and https -.TP -.B --proto =http,https -also only enables http and https -.RE -.IP -Unknown protocols produce a warning. This allows scripts to safely rely on -being able to disable potentially dangerous protocols, without relying upon -support for that protocol being built into curl to avoid an error. - -This option can be used multiple times, in which case the effect is the same -as concatenating the protocols into one instance of the option. - -(Added in 7.20.2) -.IP "--proto-default " -Tells curl to use \fIprotocol\fP for any URL missing a scheme name. - -Example: - -.RS -.IP "--proto-default https ftp.mozilla.org" -https://ftp.mozilla.org -.RE - -An unknown or unsupported protocol causes error -\fICURLE_UNSUPPORTED_PROTOCOL\fP. - -This option does not change the default proxy protocol (http). - -Without this option curl would make a guess based on the host, see \fI--url\fP -for details. - -(Added in 7.45.0) -.IP "--proto-redir " -Tells curl to use the listed protocols on redirect. See --proto for how -protocols are represented. - -Example: - -.RS -.IP "--proto-redir -all,http,https" -Allow only HTTP and HTTPS on redirect. -.RE - -By default curl will allow all protocols on redirect except several disabled -for security reasons: Since 7.19.4 FILE and SCP are disabled, and since 7.40.0 -SMB and SMBS are also disabled. Specifying \fIall\fP or \fI+all\fP enables all -protocols on redirect, including those disabled for security. - -(Added in 7.20.2) -.IP "--proxy-anyauth" -Tells curl to pick a suitable authentication method when communicating with -the given proxy. This might cause an extra request/response round-trip. (Added -in 7.13.2) -.IP "--proxy-basic" -Tells curl to use HTTP Basic authentication when communicating with the given -proxy. Use \fI--basic\fP for enabling HTTP Basic with a remote host. Basic is -the default authentication method curl uses with proxies. -.IP "--proxy-digest" -Tells curl to use HTTP Digest authentication when communicating with the given -proxy. Use \fI--digest\fP for enabling HTTP Digest with a remote host. -.IP "--proxy-negotiate" -Tells curl to use HTTP Negotiate (SPNEGO) authentication when communicating -with the given proxy. Use \fI--negotiate\fP for enabling HTTP Negotiate (SPNEGO) -with a remote host. (Added in 7.17.1) -.IP "--proxy-ntlm" -Tells curl to use HTTP NTLM authentication when communicating with the given -proxy. Use \fI--ntlm\fP for enabling NTLM with a remote host. -.IP "--proxy-service-name " -This option allows you to change the service name for proxy negotiation. - -Examples: --proxy-negotiate proxy-name \fI--proxy-service-name\fP sockd would use -sockd/proxy-name. (Added in 7.43.0). -.IP "--proxy1.0 " -Use the specified HTTP 1.0 proxy. If the port number is not specified, it is -assumed at port 1080. - -The only difference between this and the HTTP proxy option (\fI-x, --proxy\fP), -is that attempts to use CONNECT through the proxy will specify an HTTP 1.0 -protocol instead of the default HTTP 1.1. -.IP "--pubkey " -(SSH) Public key file name. Allows you to provide your public key in this -separate file. - -If this option is used several times, the last one will be used. - -(As of 7.39.0, curl attempts to automatically extract the public key from the -private key file, so passing this option is generally not required. Note that -this public key extraction requires libcurl to be linked against a copy of -libssh2 1.2.8 or higher that is itself linked against OpenSSL.) -.IP "-q" -If used as the first parameter on the command line, the \fIcurlrc\fP config -file will not be read and used. See the \fI-K, --config\fP for details on the -default config file search path. -.IP "-Q, --quote " -(FTP/SFTP) Send an arbitrary command to the remote FTP or SFTP server. Quote -commands are sent BEFORE the transfer takes place (just after the initial PWD -command in an FTP transfer, to be exact). To make commands take place after a -successful transfer, prefix them with a dash '-'. To make commands be sent -after curl has changed the working directory, just before the transfer -command(s), prefix the command with a '+' (this is only supported for -FTP). You may specify any number of commands. If the server returns failure -for one of the commands, the entire operation will be aborted. You must send -syntactically correct FTP commands as RFC 959 defines to FTP servers, or one -of the commands listed below to SFTP servers. This option can be used -multiple times. When speaking to an FTP server, prefix the command with an -asterisk (*) to make curl continue even if the command fails as by default -curl will stop at first failure. - -SFTP is a binary protocol. Unlike for FTP, curl interprets SFTP quote commands -itself before sending them to the server. File names may be quoted -shell-style to embed spaces or special characters. Following is the list of -all supported SFTP quote commands: -.RS -.IP "chgrp group file" -The chgrp command sets the group ID of the file named by the file operand to -the group ID specified by the group operand. The group operand is a decimal -integer group ID. -.IP "chmod mode file" -The chmod command modifies the file mode bits of the specified file. The -mode operand is an octal integer mode number. -.IP "chown user file" -The chown command sets the owner of the file named by the file operand to the -user ID specified by the user operand. The user operand is a decimal -integer user ID. -.IP "ln source_file target_file" -The ln and symlink commands create a symbolic link at the target_file location -pointing to the source_file location. -.IP "mkdir directory_name" -The mkdir command creates the directory named by the directory_name operand. -.IP "pwd" -The pwd command returns the absolute pathname of the current working directory. -.IP "rename source target" -The rename command renames the file or directory named by the source -operand to the destination path named by the target operand. -.IP "rm file" -The rm command removes the file specified by the file operand. -.IP "rmdir directory" -The rmdir command removes the directory entry specified by the directory -operand, provided it is empty. -.IP "symlink source_file target_file" -See ln. -.RE -.IP "-r, --range " -(HTTP/FTP/SFTP/FILE) Retrieve a byte range (i.e a partial document) from a -HTTP/1.1, FTP or SFTP server or a local FILE. Ranges can be specified -in a number of ways. -.RS -.TP 10 -.B 0-499 -specifies the first 500 bytes -.TP -.B 500-999 -specifies the second 500 bytes -.TP -.B -500 -specifies the last 500 bytes -.TP -.B 9500- -specifies the bytes from offset 9500 and forward -.TP -.B 0-0,-1 -specifies the first and last byte only(*)(HTTP) -.TP -.B 100-199,500-599 -specifies two separate 100-byte ranges(*) (HTTP) -.RE -.IP -(*) = NOTE that this will cause the server to reply with a multipart -response! - -Only digit characters (0-9) are valid in the 'start' and 'stop' fields of the -\&'start-stop' range syntax. If a non-digit character is given in the range, -the server's response will be unspecified, depending on the server's -configuration. - -You should also be aware that many HTTP/1.1 servers do not have this feature -enabled, so that when you attempt to get a range, you'll instead get the whole -document. - -FTP and SFTP range downloads only support the simple 'start-stop' syntax -(optionally with one of the numbers omitted). FTP use depends on the extended -FTP command SIZE. - -If this option is used several times, the last one will be used. -.IP "-R, --remote-time" -When used, this will make curl attempt to figure out the timestamp of the -remote file, and if that is available make the local file get that same -timestamp. -.IP "--random-file " -(SSL) Specify the path name to file containing what will be considered as -random data. The data is used to seed the random engine for SSL connections. -See also the \fI--egd-file\fP option. -.IP "--raw" -(HTTP) When used, it disables all internal HTTP decoding of content or transfer -encodings and instead makes them passed on unaltered, raw. (Added in 7.16.2) -.IP "--remote-name-all" -This option changes the default action for all given URLs to be dealt with as -if \fI-O, --remote-name\fP were used for each one. So if you want to disable -that for a specific URL after \fI--remote-name-all\fP has been used, you must -use "-o -" or \fI--no-remote-name\fP. (Added in 7.19.0) -.IP "--resolve " -Provide a custom address for a specific host and port pair. Using this, you -can make the curl requests(s) use a specified address and prevent the -otherwise normally resolved address to be used. Consider it a sort of -/etc/hosts alternative provided on the command line. The port number should be -the number used for the specific protocol the host will be used for. It means -you need several entries if you want to provide address for the same host but -different ports. - -This option can be used many times to add many host names to resolve. - -(Added in 7.21.3) -.IP "--retry " -If a transient error is returned when curl tries to perform a transfer, it -will retry this number of times before giving up. Setting the number to 0 -makes curl do no retries (which is the default). Transient error means either: -a timeout, an FTP 4xx response code or an HTTP 5xx response code. - -When curl is about to retry a transfer, it will first wait one second and then -for all forthcoming retries it will double the waiting time until it reaches -10 minutes which then will be the delay between the rest of the retries. By -using \fI--retry-delay\fP you disable this exponential backoff algorithm. See -also \fI--retry-max-time\fP to limit the total time allowed for -retries. (Added in 7.12.3) - -If this option is used several times, the last one will be used. -.IP "--retry-delay " -Make curl sleep this amount of time before each retry when a transfer has -failed with a transient error (it changes the default backoff time algorithm -between retries). This option is only interesting if \fI--retry\fP is also -used. Setting this delay to zero will make curl use the default backoff time. -(Added in 7.12.3) - -If this option is used several times, the last one will be used. -.IP "--retry-max-time " -The retry timer is reset before the first transfer attempt. Retries will be -done as usual (see \fI--retry\fP) as long as the timer hasn't reached this -given limit. Notice that if the timer hasn't reached the limit, the request -will be made and while performing, it may take longer than this given time -period. To limit a single request\'s maximum time, use \fI-m, --max-time\fP. -Set this option to zero to not timeout retries. (Added in 7.12.3) - -If this option is used several times, the last one will be used. -.IP "-s, --silent" -Silent or quiet mode. Don't show progress meter or error messages. Makes Curl -mute. It will still output the data you ask for, potentially even to the -terminal/stdout unless you redirect it. -.IP "--sasl-ir" -Enable initial response in SASL authentication. -(Added in 7.31.0) -.IP "--service-name " -This option allows you to change the service name for SPNEGO. - -Examples: --negotiate \fI--service-name\fP sockd would use -sockd/server-name. (Added in 7.43.0). -.IP "-S, --show-error" -When used with \fI-s\fP it makes curl show an error message if it fails. -.IP "--ssl" -(FTP, POP3, IMAP, SMTP) Try to use SSL/TLS for the connection. Reverts to a -non-secure connection if the server doesn't support SSL/TLS. See also -\fI--ftp-ssl-control\fP and \fI--ssl-reqd\fP for different levels of -encryption required. (Added in 7.20.0) - -This option was formerly known as \fI--ftp-ssl\fP (Added in 7.11.0). That -option name can still be used but will be removed in a future version. -.IP "--ssl-reqd" -(FTP, POP3, IMAP, SMTP) Require SSL/TLS for the connection. Terminates the -connection if the server doesn't support SSL/TLS. (Added in 7.20.0) - -This option was formerly known as \fI--ftp-ssl-reqd\fP (added in 7.15.5). That -option name can still be used but will be removed in a future version. -.IP "--ssl-allow-beast" -(SSL) This option tells curl to not work around a security flaw in the SSL3 -and TLS1.0 protocols known as BEAST. If this option isn't used, the SSL layer -may use workarounds known to cause interoperability problems with some older -SSL implementations. WARNING: this option loosens the SSL security, and by -using this flag you ask for exactly that. (Added in 7.25.0) -.IP "--ssl-no-revoke" -(WinSSL) This option tells curl to disable certificate revocation checks. -WARNING: this option loosens the SSL security, and by using this flag you ask -for exactly that. (Added in 7.44.0) -.IP "--socks4 " -Use the specified SOCKS4 proxy. If the port number is not specified, it is -assumed at port 1080. (Added in 7.15.2) - -This option overrides any previous use of \fI-x, --proxy\fP, as they are -mutually exclusive. - -Since 7.21.7, this option is superfluous since you can specify a socks4 proxy -with \fI-x, --proxy\fP using a socks4:// protocol prefix. - -If this option is used several times, the last one will be used. -.IP "--socks4a " -Use the specified SOCKS4a proxy. If the port number is not specified, it is -assumed at port 1080. (Added in 7.18.0) - -This option overrides any previous use of \fI-x, --proxy\fP, as they are -mutually exclusive. - -Since 7.21.7, this option is superfluous since you can specify a socks4a proxy -with \fI-x, --proxy\fP using a socks4a:// protocol prefix. - -If this option is used several times, the last one will be used. -.IP "--socks5-hostname " -Use the specified SOCKS5 proxy (and let the proxy resolve the host name). If -the port number is not specified, it is assumed at port 1080. (Added in -7.18.0) - -This option overrides any previous use of \fI-x, --proxy\fP, as they are -mutually exclusive. - -Since 7.21.7, this option is superfluous since you can specify a socks5 -hostname proxy with \fI-x, --proxy\fP using a socks5h:// protocol prefix. - -If this option is used several times, the last one will be used. (This option -was previously wrongly documented and used as --socks without the number -appended.) -.IP "--socks5 " -Use the specified SOCKS5 proxy - but resolve the host name locally. If the -port number is not specified, it is assumed at port 1080. - -This option overrides any previous use of \fI-x, --proxy\fP, as they are -mutually exclusive. - -Since 7.21.7, this option is superfluous since you can specify a socks5 proxy -with \fI-x, --proxy\fP using a socks5:// protocol prefix. - -If this option is used several times, the last one will be used. (This option -was previously wrongly documented and used as --socks without the number -appended.) - -This option (as well as \fI--socks4\fP) does not work with IPV6, FTPS or LDAP. -.IP "--socks5-gssapi-service " -The default service name for a socks server is rcmd/server-fqdn. This option -allows you to change it. - -Examples: --socks5 proxy-name \fI--socks5-gssapi-service\fP sockd would use -sockd/proxy-name --socks5 proxy-name \fI--socks5-gssapi-service\fP -sockd/real-name would use sockd/real-name for cases where the proxy-name does -not match the principal name. (Added in 7.19.4). -.IP "--socks5-gssapi-nec" -As part of the GSS-API negotiation a protection mode is negotiated. RFC 1961 -says in section 4.3/4.4 it should be protected, but the NEC reference -implementation does not. The option \fI--socks5-gssapi-nec\fP allows the -unprotected exchange of the protection mode negotiation. (Added in 7.19.4). -.IP "--stderr " -Redirect all writes to stderr to the specified file instead. If the file name -is a plain '-', it is instead written to stdout. - -If this option is used several times, the last one will be used. -.IP "-t, --telnet-option " -Pass options to the telnet protocol. Supported options are: - -TTYPE= Sets the terminal type. - -XDISPLOC= Sets the X display location. - -NEW_ENV= Sets an environment variable. -.IP "-T, --upload-file " -This transfers the specified local file to the remote URL. If there is no file -part in the specified URL, Curl will append the local file name. NOTE that you -must use a trailing / on the last directory to really prove to Curl that there -is no file name or curl will think that your last directory name is the remote -file name to use. That will most likely cause the upload operation to fail. If -this is used on an HTTP(S) server, the PUT command will be used. - -Use the file name "-" (a single dash) to use stdin instead of a given file. -Alternately, the file name "." (a single period) may be specified instead -of "-" to use stdin in non-blocking mode to allow reading server output -while stdin is being uploaded. - -You can specify one -T for each URL on the command line. Each -T + URL pair -specifies what to upload and to where. curl also supports "globbing" of the -T -argument, meaning that you can upload multiple files to a single URL by using -the same URL globbing style supported in the URL, like this: - -curl -T "{file1,file2}" http://www.uploadtothissite.com - -or even - -curl -T "img[1-1000].png" ftp://ftp.picturemania.com/upload/ -.IP "--tcp-nodelay" -Turn on the TCP_NODELAY option. See the \fIcurl_easy_setopt(3)\fP man page for -details about this option. (Added in 7.11.2) -.IP "--tftp-blksize " -(TFTP) Set TFTP BLKSIZE option (must be >512). This is the block size that -curl will try to use when transferring data to or from a TFTP server. By -default 512 bytes will be used. - -If this option is used several times, the last one will be used. - -(Added in 7.20.0) -.IP "--tftp-no-options" -(TFTP) Tells curl not to send TFTP options requests. - -This option improves interop with some legacy servers that do not acknowledge -or properly implement TFTP options. When this option is used -\fI--tftp-blksize\fP is ignored. - -(Added in 7.48.0) -.IP "--tlsauthtype " -Set TLS authentication type. Currently, the only supported option is "SRP", -for TLS-SRP (RFC 5054). If \fI--tlsuser\fP and \fI--tlspassword\fP are -specified but \fI--tlsauthtype\fP is not, then this option defaults to "SRP". -(Added in 7.21.4) -.IP "--tlspassword " -Set password for use with the TLS authentication method specified with -\fI--tlsauthtype\fP. Requires that \fI--tlsuser\fP also be set. (Added in -7.21.4) -.IP "--tlsuser " -Set username for use with the TLS authentication method specified with -\fI--tlsauthtype\fP. Requires that \fI--tlspassword\fP also be set. (Added in -7.21.4) -.IP "--tlsv1.0" -(SSL) -Forces curl to use TLS version 1.0 when negotiating with a remote TLS server. -(Added in 7.34.0) -.IP "--tlsv1.1" -(SSL) -Forces curl to use TLS version 1.1 when negotiating with a remote TLS server. -(Added in 7.34.0) -.IP "--tlsv1.2" -(SSL) -Forces curl to use TLS version 1.2 when negotiating with a remote TLS server. -(Added in 7.34.0) -.IP "--tr-encoding" -(HTTP) Request a compressed Transfer-Encoding response using one of the -algorithms curl supports, and uncompress the data while receiving it. - -(Added in 7.21.6) -.IP "--trace " -Enables a full trace dump of all incoming and outgoing data, including -descriptive information, to the given output file. Use "-" as filename to have -the output sent to stdout. - -This option overrides previous uses of \fI-v, --verbose\fP or -\fI--trace-ascii\fP. - -If this option is used several times, the last one will be used. -.IP "--trace-ascii " -Enables a full trace dump of all incoming and outgoing data, including -descriptive information, to the given output file. Use "-" as filename to have -the output sent to stdout. - -This is very similar to \fI--trace\fP, but leaves out the hex part and only -shows the ASCII part of the dump. It makes smaller output that might be easier -to read for untrained humans. - -This option overrides previous uses of \fI-v, --verbose\fP or \fI--trace\fP. - -If this option is used several times, the last one will be used. -.IP "--trace-time" -Prepends a time stamp to each trace or verbose line that curl displays. -(Added in 7.14.0) -.IP "--unix-socket " -(HTTP) Connect through this Unix domain socket, instead of using the -network. (Added in 7.40.0) -.IP "-u, --user " -Specify the user name and password to use for server authentication. Overrides -\fI-n, --netrc\fP and \fI--netrc-optional\fP. - -If you simply specify the user name, curl will prompt for a password. - -The user name and passwords are split up on the first colon, which makes it -impossible to use a colon in the user name with this option. The password can, -still. - -When using Kerberos V5 with a Windows based server you should include the -Windows domain name in the user name, in order for the server to successfully -obtain a Kerberos Ticket. If you don't then the initial authentication -handshake may fail. - -When using NTLM, the user name can be specified simply as the user name, -without the domain, if there is a single domain and forest in your setup -for example. - -To specify the domain name use either Down-Level Logon Name or UPN (User -Principal Name) formats. For example, EXAMPLE\\user and user@example.com -respectively. - -If you use a Windows SSPI-enabled curl binary and perform Kerberos V5, -Negotiate, NTLM or Digest authentication then you can tell curl to select -the user name and password from your environment by specifying a single colon -with this option: "-u :". - -If this option is used several times, the last one will be used. -.IP "-U, --proxy-user " -Specify the user name and password to use for proxy authentication. - -If you use a Windows SSPI-enabled curl binary and do either Negotiate or NTLM -authentication then you can tell curl to select the user name and password -from your environment by specifying a single colon with this option: "-U :". - -If this option is used several times, the last one will be used. -.IP "--url " -Specify a URL to fetch. This option is mostly handy when you want to specify -URL(s) in a config file. - -If the given URL is missing a scheme name (such as "http://" or "ftp://" etc) -then curl will make a guess based on the host. If the outermost sub-domain name -matches DICT, FTP, IMAP, LDAP, POP3 or SMTP then that protocol will be used, -otherwise HTTP will be used. Since 7.45.0 guessing can be disabled by setting a -default protocol, see \fI--proto-default\fP for details. - -This option may be used any number of times. To control where this URL is -written, use the \fI-o, --output\fP or the \fI-O, --remote-name\fP options. -.IP "-v, --verbose" -Be more verbose/talkative during the operation. Useful for debugging and -seeing what's going on "under the hood". A line starting with '>' means -"header data" sent by curl, '<' means "header data" received by curl that is -hidden in normal cases, and a line starting with '*' means additional info -provided by curl. - -Note that if you only want HTTP headers in the output, \fI-i, --include\fP -might be the option you're looking for. - -If you think this option still doesn't give you enough details, consider using -\fI--trace\fP or \fI--trace-ascii\fP instead. - -This option overrides previous uses of \fI--trace-ascii\fP or \fI--trace\fP. - -Use \fI-s, --silent\fP to make curl quiet. -.IP "-w, --write-out " -Make curl display information on stdout after a completed transfer. The format -is a string that may contain plain text mixed with any number of -variables. The format can be specified as a literal "string", or you can have -curl read the format from a file with "@filename" and to tell curl to read the -format from stdin you write "@-". - -The variables present in the output format will be substituted by the value or -text that curl thinks fit, as described below. All variables are specified -as %{variable_name} and to output a normal % you just write them as -%%. You can output a newline by using \\n, a carriage return with \\r and a tab -space with \\t. - -.B NOTE: -The %-symbol is a special symbol in the win32-environment, where all -occurrences of % must be doubled when using this option. - -The variables available are: -.RS -.TP 15 -.B content_type -The Content-Type of the requested document, if there was any. -.TP -.B filename_effective -The ultimate filename that curl writes out to. This is only meaningful if curl -is told to write to a file with the \fI--remote-name\fP or \fI--output\fP -option. It's most useful in combination with the \fI--remote-header-name\fP -option. (Added in 7.25.1) -.TP -.B ftp_entry_path -The initial path curl ended up in when logging on to the remote FTP -server. (Added in 7.15.4) -.TP -.B http_code -The numerical response code that was found in the last retrieved HTTP(S) or -FTP(s) transfer. In 7.18.2 the alias \fBresponse_code\fP was added to show the -same info. -.TP -.B http_connect -The numerical code that was found in the last response (from a proxy) to a -curl CONNECT request. (Added in 7.12.4) -.TP -.B local_ip -The IP address of the local end of the most recently done connection - can be -either IPv4 or IPv6 (Added in 7.29.0) -.TP -.B local_port -The local port number of the most recently done connection (Added in 7.29.0) -.TP -.B num_connects -Number of new connects made in the recent transfer. (Added in 7.12.3) -.TP -.B num_redirects -Number of redirects that were followed in the request. (Added in 7.12.3) -.TP -.B redirect_url -When an HTTP request was made without -L to follow redirects, this variable -will show the actual URL a redirect \fIwould\fP take you to. (Added in 7.18.2) -.TP -.B remote_ip -The remote IP address of the most recently done connection - can be either -IPv4 or IPv6 (Added in 7.29.0) -.TP -.B remote_port -The remote port number of the most recently done connection (Added in 7.29.0) -.TP -.B size_download -The total amount of bytes that were downloaded. -.TP -.B size_header -The total amount of bytes of the downloaded headers. -.TP -.B size_request -The total amount of bytes that were sent in the HTTP request. -.TP -.B size_upload -The total amount of bytes that were uploaded. -.TP -.B speed_download -The average download speed that curl measured for the complete download. Bytes -per second. -.TP -.B speed_upload -The average upload speed that curl measured for the complete upload. Bytes per -second. -.TP -.B ssl_verify_result -The result of the SSL peer certificate verification that was requested. 0 -means the verification was successful. (Added in 7.19.0) -.TP -.B time_appconnect -The time, in seconds, it took from the start until the SSL/SSH/etc -connect/handshake to the remote host was completed. (Added in 7.19.0) -.TP -.B time_connect -The time, in seconds, it took from the start until the TCP connect to the -remote host (or proxy) was completed. -.TP -.B time_namelookup -The time, in seconds, it took from the start until the name resolving was -completed. -.TP -.B time_pretransfer -The time, in seconds, it took from the start until the file transfer was just -about to begin. This includes all pre-transfer commands and negotiations that -are specific to the particular protocol(s) involved. -.TP -.B time_redirect -The time, in seconds, it took for all redirection steps include name lookup, -connect, pretransfer and transfer before the final transaction was -started. time_redirect shows the complete execution time for multiple -redirections. (Added in 7.12.3) -.TP -.B time_starttransfer -The time, in seconds, it took from the start until the first byte was just -about to be transferred. This includes time_pretransfer and also the time the -server needed to calculate the result. -.TP -.B time_total -The total time, in seconds, that the full operation lasted. The time will be -displayed with millisecond resolution. -.TP -.B url_effective -The URL that was fetched last. This is most meaningful if you've told curl -to follow location: headers. -.RE -.IP -If this option is used several times, the last one will be used. -.IP "-x, --proxy <[protocol://][user:password@]proxyhost[:port]>" -Use the specified proxy. - -The proxy string can be specified with a protocol:// prefix to specify -alternative proxy protocols. Use socks4://, socks4a://, socks5:// or -socks5h:// to request the specific SOCKS version to be used. No protocol -specified, http:// and all others will be treated as HTTP proxies. (The -protocol support was added in curl 7.21.7) - -If the port number is not specified in the proxy string, it is assumed to be -1080. - -This option overrides existing environment variables that set the proxy to -use. If there's an environment variable setting a proxy, you can set proxy to -\&"" to override it. - -All operations that are performed over an HTTP proxy will transparently be -converted to HTTP. It means that certain protocol specific operations might -not be available. This is not the case if you can tunnel through the proxy, as -one with the \fI-p, --proxytunnel\fP option. - -User and password that might be provided in the proxy string are URL decoded -by curl. This allows you to pass in special characters such as @ by using %40 -or pass in a colon with %3a. - -The proxy host can be specified the exact same way as the proxy environment -variables, including the protocol prefix (http://) and the embedded user + -password. - -If this option is used several times, the last one will be used. -.IP "-X, --request " -(HTTP) Specifies a custom request method to use when communicating with the -HTTP server. The specified request method will be used instead of the method -otherwise used (which defaults to GET). Read the HTTP 1.1 specification for -details and explanations. Common additional HTTP requests include PUT and -DELETE, but related technologies like WebDAV offers PROPFIND, COPY, MOVE and -more. - -Normally you don't need this option. All sorts of GET, HEAD, POST and PUT -requests are rather invoked by using dedicated command line options. - -This option only changes the actual word used in the HTTP request, it does not -alter the way curl behaves. So for example if you want to make a proper HEAD -request, using -X HEAD will not suffice. You need to use the \fI-I, --head\fP -option. - -The method string you set with -X will be used for all requests, which if you -for example use \fB-L, --location\fP may cause unintended side-effects when -curl doesn't change request method according to the HTTP 30x response codes - -and similar. - -(FTP) -Specifies a custom FTP command to use instead of LIST when doing file lists -with FTP. - -(POP3) -Specifies a custom POP3 command to use instead of LIST or RETR. (Added in -7.26.0) - -(IMAP) -Specifies a custom IMAP command to use instead of LIST. (Added in 7.30.0) - -(SMTP) -Specifies a custom SMTP command to use instead of HELP or VRFY. (Added in 7.34.0) - -If this option is used several times, the last one will be used. -.IP "--xattr" -When saving output to a file, this option tells curl to store certain file -metadata in extended file attributes. Currently, the URL is stored in the -xdg.origin.url attribute and, for HTTP, the content type is stored in -the mime_type attribute. If the file system does not support extended -attributes, a warning is issued. - -.IP "-y, --speed-time