diff --git a/CMakeLists.txt b/CMakeLists.txt index af7f4dc40..be3fb4b3c 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -48,7 +48,7 @@ project( CURL C ) message(WARNING "the curl cmake build system is poorly maintained. Be aware") -file (READ ${CURL_SOURCE_DIR}/include/curl/curlver.h CURL_VERSION_H_CONTENTS) +file (READ ${CURL_SOURCE_DIR}/include/gnurl/curlver.h CURL_VERSION_H_CONTENTS) string (REGEX MATCH "#define LIBCURL_VERSION \"[^\"]*" CURL_VERSION ${CURL_VERSION_H_CONTENTS}) string (REGEX REPLACE "[^\"]+\"" "" CURL_VERSION ${CURL_VERSION}) @@ -69,7 +69,7 @@ message(STATUS "curl version=[${CURL_VERSION}]") set(OPERATING_SYSTEM "${CMAKE_SYSTEM_NAME}") set(OS "\"${CMAKE_SYSTEM_NAME}\"") -include_directories(${PROJECT_BINARY_DIR}/include/curl) +include_directories(${PROJECT_BINARY_DIR}/include/gnurl) include_directories( ${CURL_SOURCE_DIR}/include ) option(CURL_WERROR "Turn compiler warnings into errors" OFF) @@ -1315,7 +1315,7 @@ if(NOT CURL_CONFIG_HAS_BEEN_RUN_BEFORE) endif() # install headers -install(DIRECTORY "${CMAKE_CURRENT_SOURCE_DIR}/include/curl" +install(DIRECTORY "${CMAKE_CURRENT_SOURCE_DIR}/include/gnurl" DESTINATION include FILES_MATCHING PATTERN "*.h") diff --git a/Makefile.am b/Makefile.am index ab8f11cbc..7037d1c84 100644 --- a/Makefile.am +++ b/Makefile.am @@ -141,9 +141,9 @@ VC_DIST = projects/README \ WINBUILD_DIST = winbuild/BUILD.WINDOWS.txt winbuild/gen_resp_file.bat \ winbuild/MakefileBuild.vc winbuild/Makefile.vc -EXTRA_DIST = CHANGES COPYING maketgz Makefile.dist curl-config.in \ - RELEASE-NOTES buildconf libcurl.pc.in MacOSX-Framework scripts/zsh.pl \ - scripts/updatemanpages.pl $(CMAKE_DIST) $(VC_DIST) $(WINBUILD_DIST) \ +EXTRA_DIST = CHANGES COPYING maketgz Makefile.dist gnurl-config.in \ + RELEASE-NOTES buildconf libgnurl.pc.in MacOSX-Framework scripts/zsh.pl \ + scripts/updatemanpages.pl $(CMAKE_DIST) $(VC_DIST) $(WINBUILD_DIST) \ lib/libcurl.vers.in buildconf.bat scripts/coverage.sh CLEANFILES = $(VC6_LIBDSP) $(VC6_SRCDSP) $(VC7_LIBVCPROJ) $(VC7_SRCVCPROJ) \ @@ -152,13 +152,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 DIST_SUBDIRS = $(SUBDIRS) tests packages scripts include 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 f0b3b9393..6a63bd4b7 100644 --- a/README +++ b/README @@ -1,3 +1,134 @@ +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' +* adjustments to the testsuite, deleted tests/data/test1139 + +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/buildconf b/buildconf index 509575312..e151bb2e8 100755 --- a/buildconf +++ b/buildconf @@ -83,7 +83,7 @@ removethis(){ if test ! -f configure.ac || test ! -f src/tool_main.c || test ! -f lib/urldata.h || - test ! -f include/curl/curl.h || + test ! -f include/gnurl/curl.h || test ! -f m4/curl-functions.m4; then echo "Can not run buildconf from outside of curl's source subdirectory!" echo "Change to the subdirectory where buildconf is found, and try again." @@ -305,7 +305,7 @@ for fname in .deps \ config.sub \ configure \ configurehelp.pm \ - curl-config \ + gnurl-config \ depcomp \ libcares.pc \ libcurl.pc \ diff --git a/configure.ac b/configure.ac index edebfc77b..c27c516e4 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 @@ -122,7 +122,7 @@ AC_SUBST([AR]) AC_SUBST(libext) dnl figure out the libcurl version -CURLVERSION=`$SED -ne 's/^#define LIBCURL_VERSION "\(.*\)".*/\1/p' ${srcdir}/include/curl/curlver.h` +CURLVERSION=`$SED -ne 's/^#define LIBCURL_VERSION "\(.*\)".*/\1/p' ${srcdir}/include/gnurl/curlver.h` XC_CHECK_PROG_CC XC_AUTOMAKE AC_MSG_CHECKING([curl version]) @@ -132,7 +132,7 @@ AC_SUBST(CURLVERSION) dnl dnl we extract the numerical version for curl-config only -VERSIONNUM=`$SED -ne 's/^#define LIBCURL_VERSION_NUM 0x\([0-9A-Fa-f]*\).*/\1/p' ${srcdir}/include/curl/curlver.h` +VERSIONNUM=`$SED -ne 's/^#define LIBCURL_VERSION_NUM 0x\([0-9A-Fa-f]*\).*/\1/p' ${srcdir}/include/gnurl/curlver.h` AC_SUBST(VERSIONNUM) dnl Solaris pkgadd support definitions @@ -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" @@ -3883,7 +3876,7 @@ AC_CONFIG_FILES([Makefile \ docs/libcurl/opts/Makefile \ docs/cmdline-opts/Makefile \ include/Makefile \ - include/curl/Makefile \ + include/gnurl/Makefile \ src/Makefile \ lib/Makefile \ scripts/Makefile \ @@ -3910,8 +3903,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/docs/Makefile.am b/docs/Makefile.am index 086b8c15f..0cc9b5acf 100644 --- a/docs/Makefile.am +++ b/docs/Makefile.am @@ -24,12 +24,12 @@ AUTOMAKE_OPTIONS = foreign no-dependencies # EXTRA_DIST breaks with $(abs_builddir) so build it using this variable # but distribute it (using the relative file name) in the next variable -man_MANS = $(abs_builddir)/curl.1 -noinst_man_MANS = curl.1 mk-ca-bundle.1 -dist_man_MANS = curl-config.1 -GENHTMLPAGES = curl.html curl-config.html mk-ca-bundle.html -PDFPAGES = curl.pdf curl-config.pdf mk-ca-bundle.pdf -MANDISTPAGES = curl.1.dist curl-config.1.dist +man_MANS = $(abs_builddir)/gnurl.1 +noinst_man_MANS = gnurl.1 mk-ca-bundle.1 +dist_man_MANS = gnurl-config.1 +GENHTMLPAGES = gnurl.html gnurl-config.html mk-ca-bundle.html +PDFPAGES = gnurl.pdf gnurl-config.pdf mk-ca-bundle.pdf +MANDISTPAGES = gnurl.1.dist gnurl-config.1.dist HTMLPAGES = $(GENHTMLPAGES) index.html diff --git a/docs/examples/10-at-a-time.c b/docs/examples/10-at-a-time.c index 455529182..b0c65b77e 100644 --- a/docs/examples/10-at-a-time.c +++ b/docs/examples/10-at-a-time.c @@ -32,7 +32,7 @@ #ifndef WIN32 # include #endif -#include +#include static const char *urls[] = { "http://www.microsoft.com", diff --git a/docs/examples/Makefile.am b/docs/examples/Makefile.am index afd35c20b..fed027166 100644 --- a/docs/examples/Makefile.am +++ b/docs/examples/Makefile.am @@ -48,9 +48,9 @@ LIBS = $(BLANK_AT_MAKETIME) # Dependencies if USE_EXPLICIT_LIB_DEPS -LDADD = $(LIBDIR)/libcurl.la @LIBCURL_LIBS@ +LDADD = $(LIBDIR)/libgnurl.la @LIBCURL_LIBS@ else -LDADD = $(LIBDIR)/libcurl.la +LDADD = $(LIBDIR)/libgnurl.la endif # Makefile.inc provides the check_PROGRAMS and COMPLICATED_EXAMPLES defines diff --git a/docs/curl-config.1 b/docs/gnurl-config.1 similarity index 100% rename from docs/curl-config.1 rename to docs/gnurl-config.1 diff --git a/docs/gnurl.1 b/docs/gnurl.1 new file mode 100644 index 000000000..5866ba908 --- /dev/null +++ b/docs/gnurl.1 @@ -0,0 +1,2668 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * 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. +.\" * +.\" ************************************************************************** +.\" +.\" DO NOT EDIT. Generated by the curl project gen.pl man page generator. +.\" +.TH curl 1 "16 Dec 2016" "Curl 7.52.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.example.com/file[1-100].txt + + ftp://ftp.example.com/file[001-100].txt (with leading zeros) + + ftp://ftp.example.com/file[a-z].txt + +Nested sequences are not supported, but you can use several ones next to each +other: + + http://example.com/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://example.com/file[1-100:10].txt + + http://example.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. The +progress meter displays number of bytes and the speeds are in bytes per +second. The suffixes (k, M, G, T, P) are 1024 based. For example 1k is 1024 +bytes. 1M is 1048576 bytes. + +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-#, --progress-bar\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, \fI-d, --data\fP 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 "--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. + +Using \fI--anyauth\fP 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. + +Used together with \fI-u, --user\fP. + +See also \fI--proxy-anyauth\fP and \fI--basic\fP and \fI--digest\fP. +.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 "--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. + +See also \fI--proxy-basic\fP. +.IP "--cacert " +(TLS) 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. + +(iOS and macOS only) If curl is built against Secure Transport, then this +option is supported for backward compatibility with other SSL engines, but it +should not be set. If the option is not set, then curl will use the +certificates in the system and user Keychain to verify the peer, which is the +preferred method of verifying the peer's certificate chain. + +If this option is used several times, the last one will be used. +.IP "--capath " +(TLS) 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 --cacert 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 "--cert-status" +(TLS) 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 "--cert-type " +(TLS) 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. + +See also \fI-E, --cert\fP and \fI--key\fP and \fI--key-type\fP. +.IP "-E, --cert " +(TLS) 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-E, --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 macOS 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. + +See also \fI--cert-type\fP and \fI--key\fP and \fI--key-type\fP. +.IP "--ciphers " +(TLS) 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: + + https://www.openssl.org/docs/apps/ciphers.html + +NSS ciphers are done differently than OpenSSL and GnuTLS. The full list of NSS +ciphers is in the NSSCipherSuite entry at this URL: + + https://git.fedorahosted.org/cgit/mod_nss.git/plain/docs/mod_nss.html#Directives + +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 "-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 \fI-K, --config\fP 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, --disable\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 = "example.com" +output = "curlhere.html" +user-agent = "superagent/1.0" + +# and fetch another URL too +url = "example.com/docs/manpage.html" +-O +referer = "http://nowhereatall.example.com/" +# --- End of example file --- +.fi + +This option can be used multiple times to load multiple config files. +.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. + +If this option is used several times, the last one will be used. + +See also \fI-m, --max-time\fP. +.IP "--connect-to " + +For a request to the given HOST:PORT pair, connect to +CONNECT-TO-HOST:CONNECT-TO-PORT instead. This option is suitable to direct +requests at a specific server, e.g. at a specific cluster node in a cluster of +servers. This option is only used to establish the network connection. It +does NOT affect the hostname/port that is used for TLS/SSL (e.g. SNI, +certificate verification) or for the application protocols. "host" and "port" +may be the empty string, meaning "any host/port". "connect-to-host" and +"connect-to-port" may also be the empty string, meaning "use the request's +original host/port". + +This option can be used many times to add many connect rules. + +See also \fI--resolve\fP and \fI-H, --header\fP. Added in 7.49.0. +.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. + +See also \fI-r, --range\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 from its in-memory cookie storage to the +given file at the end of operations. 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 \fI-v, --verbose\fP will get a warning +displayed, but that is the only visible feedback you get about this possibly +lethal situation. + +If this option is used several times, the last specified file name will be +used. +.IP "-b, --cookie " +(HTTP) Pass the data to the HTTP server in the Cookie header. 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 argument, it is instead treated as a filename +to read previously stored cookie from. This option also activates the cookie +engine which will make curl record incoming cookies, which may be handy if +you're using this in combination with the \fI-L, --location\fP option or do multiple URL +transfers on the same invoke. + +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. + +Users very often want to both read cookies from a file and write updated +cookies back to a file, so using both \fI-b, --cookie\fP and \fI-c, --cookie-jar\fP in the same +command line is common. +.IP "--create-dirs" +When used in conjunction with the \fI-o, --output\fP option, curl will create the +necessary local directory hierarchy as needed. This option creates the dirs +mentioned with the \fI-o, --output\fP option, nothing else. If the --output file name +uses no dir or if the dirs it mentions already exist, no dir will be created. + +To create remote directories when using FTP or SFTP, try \fI--ftp-create-dirs\fP. +.IP "--crlf" +(FTP SMTP) Convert LF to CRLF in upload. Useful for MVS (OS/390). + +(SMTP added in 7.40.0) +.IP "--crlfile " +(TLS) 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 "--data-ascii " +(HTTP) This is just an alias for \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-d, --data\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-d, --data\fP but without the special +interpretation of the @ character. + +See also \fI-d, --data\fP. Added in 7.43.0. +.IP "--data-urlencode " +(HTTP) This posts data, similar to the other \fI-d, --data\fP options with the exception +that this performs URL-encoding. + +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 + +See also \fI-d, --data\fP and \fI--data-raw\fP. Added in 7.18.0. +.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--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-d, --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. + +See also \fI--data-binary\fP and \fI--data-urlencode\fP and \fI--data-raw\fP. This option overrides \fI-F, --form\fP and \fI-I, --head\fP and \fI--upload\fP. +.IP "--delegation " +(GSS/kerberos) Set LEVEL to tell the server what it is allowed to delegate when it +comes to user credentials. +.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. + +If this option is used several times, only the first one is used. + +See also \fI-u, --user\fP and \fI--proxy-digest\fP and \fI--anyauth\fP. This option overrides \fI--basic\fP and \fI--ntlm\fP and \fI--negotiate\fP. +.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. + +--eprt can be used to explicitly enable EPRT again and --no-eprt is an alias +for \fI--disable-eprt\fP. + +If the server is accessed using IPv6, 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) (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. + +--epsv can be used to explicitly enable EPSV again and --no-epsv is an alias +for \fI--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 "-q, --disable" +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 "--dns-interface " +(DNS) 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). + +See also \fI--dns-ipv4-addr\fP and \fI--dns-ipv6-addr\fP. \fI--dns-interface\fP requires that the underlying libcurl was built to support c-ares. Added in 7.33.0. +.IP "--dns-ipv4-addr
" +(DNS) 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. + +See also \fI--dns-interface\fP and \fI--dns-ipv6-addr\fP. \fI--dns-ipv4-addr\fP requires that the underlying libcurl was built to support c-ares. Added in 7.33.0. +.IP "--dns-ipv6-addr
" +(DNS) 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. + +See also \fI--dns-interface\fP and \fI--dns-ipv4-addr\fP. \fI--dns-ipv6-addr\fP requires that the underlying libcurl was built to support c-ares. 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. + +\fI--dns-servers\fP requires that the underlying libcurl was built to support c-ares. Added in 7.33.0. +.IP "-D, --dump-header " +(HTTP FTP) Write the received 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. + +See also \fI-o, --output\fP. +.IP "--egd-file " +(TLS) Specify the path name to the Entropy Gathering Daemon socket. The socket is +used to seed the random engine for SSL connections. + +See also \fI--random-file\fP. +.IP "--engine " +(TLS) Select the OpenSSL crypto engine to use for cipher operations. Use \fI--engine\fP +list 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" +Sets a range of environment variables, using the names the \fI-w, --write-out\fP option +supports, to allow easier extraction of useful information after having run +curl. + +\fI--environment\fP requires that the underlying libcurl was built to support RISC OS. +.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. + +See also \fI--connect-timeout\fP. Added in 7.47.0. +.IP "--fail-early" +Fail and exit on first detected error. + +When curl is used to do multiple transfers on the command line, it will +attempt to operate on each given URL, one by one. By default, it will ignore +errors if there are more URLs given and the last URL's success will determine +the error code curl returns. So early failures will be "hidden" by subsequent +successful transfers. + +Using this option, curl will instead return an error on the first transfers +that fails, independent on the amount of more URLs that are given on the +command line. This way, no transfer failures go undetected by scripts and +similar. + +This option will apply for all given URLs even if you use \fI-:, --next\fP. + +Added in 7.52.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 "--false-start" +(TLS) 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 "--form-string " +(HTTP) Similar to \fI-F, --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-F, --form\fP if +there's any possibility that the string value may accidentally trigger the +\&'@' or \&'<' features of \fI-F, --form\fP. + +See also \fI-F, --form\fP. +.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 an image to a server, where \&'profile' is the name of the +form-field to which portrait.jpg will be the input: + + curl -F profile=@portrait.jpg https://example.com/upload.cgi + +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: + + curl -F "web=@index.html;type=text/html" example.com + +or + + curl -F "name=daniel;type=text/foo" example.com + +You can also explicitly change the name field of a file upload part by setting +filename=, like this: + + curl -F "file=@localfile;filename=nameinpost" example.com + +If filename/path contains ',' or ';', it must be quoted by double-quotes like: + + curl -F "file=@\\"localfile\\";filename=\\"nameinpost\\"" example.com + +or + + curl -F 'file=@"localfile";filename="nameinpost"' example.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. + +This option overrides \fI-d, --data\fP and \fI-I, --head\fP and \fI--upload\fP. +.IP "--ftp-account " +(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. + +If this option is used several times, the last one will be used. + +Added in 7.13.0. +.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. + +See also \fI--create-dirs\fP. +.IP "--ftp-method " +(FTP) Control what method curl should use to reach a file on an FTP(S) +server. The method argument should be one of the following alternatives: +.RS +.IP multicwd +curl does a single CWD operation for each path part in the given URL. For deep +hierarchies this means very many commands. This is how RFC 1738 says it should +be done. This is the default but the slowest behavior. +.IP nocwd +curl does no CWD at all. curl will do SIZE, RETR, STOR etc and give a full +path to the server for all these commands. This is the fastest behavior. +.IP singlecwd +curl does one CWD with the full target directory and then operates on the file +\&"normally" (like in the multicwd case). This is somewhat more standards +compliant than 'nocwd' but without the full penalty of 'multicwd'. +.RE + +Added in 7.15.1. +.IP "--ftp-pasv" +(FTP) Use passive mode for the data connection. Passive is the internal default +behavior, but using this option can be used to override a previous \fI-P, --ftp-port\fP +option. + +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. + +See also \fI--disable-epsv\fP. Added in 7.11.0. +.IP "-P, --ftp-port
" +(FTP) Reverses the default initiator/listener roles when connecting with FTP. This +option makes curl use active mode. 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 + +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++. + +Since 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. + +See also \fI--ftp-pasv\fP and \fI--disable-eprt\fP. +.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.0. +.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. + +This option has no effect if PORT, EPRT or EPSV is used instead of PASV. + +See also \fI--ftp-pasv\fP. Added in 7.14.2. +.IP "--ftp-ssl-ccc-mode " +(FTP) 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. + +See also \fI--ftp-ssl-ccc\fP. Added in 7.16.2. +.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 also \fI--ssl\fP and \fI--ftp-ssl-ccc-mode\fP. Added in 7.16.1. +.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. +.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 \fI-I, --head\fP, 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 "-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 "-I, --head" +(HTTP FTP FILE) Fetch the headers 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 "-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://example.com/ + +\fBWARNING\fP: headers set with this option will be set in all requests - even +after redirects are followed, like when told with \fI-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 "-h, --help" +Usage help. This lists all current command line options with a short +description. +.IP "--hostpubmd5 " +(SFTP SCP) 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 "-0, --http1.0" +(HTTP) Tells curl to use HTTP version 1.0 instead of using its internally preferred +HTTP version. + +This option overrides \fI--http1.1\fP and \fI--http2\fP. +.IP "--http1.1" +(HTTP) Tells curl to use HTTP version 1.1. + +This option overrides \fI-0, --http1.0\fP and \fI--http2\fP. Added in 7.33.0. +.IP "--http2-prior-knowledge" +(HTTP) Tells curl to issue its non-TLS HTTP requests using HTTP/2 without HTTP/1.1 +Upgrade. It requires prior knowledge that the server supports HTTP/2 straight +away. HTTPS requests will still do HTTP/2 the standard way with negotiated +protocol version in the TLS handshake. + +\fI--http2-prior-knowledge\fP requires that the underlying libcurl was built to support HTTP/2. This option overrides \fI--http1.1\fP and \fI-0, --http1.0\fP and \fI--http2\fP. Added in 7.49.0. +.IP "--http2" +(HTTP) Tells curl to use HTTP version 2. + +See also \fI--no-alpn\fP. \fI--http2\fP requires that the underlying libcurl was built to support HTTP/2. This option overrides \fI--http1.1\fP and \fI-0, --http1.0\fP and \fI--http2-prior-knowledge\fP. Added in 7.33.0. +.IP "--ignore-content-length" +(FTP HTTP) 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" +Include the HTTP-header in the output. The HTTP-header includes things like +server-name, date of the document, HTTP-version and more... + +See also \fI-v, --verbose\fP. +.IP "-k, --insecure" +(TLS) 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: + https://curl.haxx.se/docs/sslcerts.html +.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 https://www.example.com/ + +If this option is used several times, the last one will be used. + +See also \fI--dns-interface\fP. +.IP "-4, --ipv4" +This option tells curl to resolve names to IPv4 addresses only, and not for +example try IPv6. + +See also \fI--http1.1\fP and \fI--http2\fP. This option overrides \fI-6, --ipv6\fP. +.IP "-6, --ipv6" +This option tells curl to resolve names to IPv6 addresses only, and not for +example try IPv4. + +See also \fI--http1.1\fP and \fI--http2\fP. This option overrides \fI-6, --ipv6\fP. +.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. + +See also \fI-b, --cookie\fP and \fI-c, --cookie-jar\fP. +.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. + +If this option is used several times, the last one will be used. If +unspecified, the option defaults to 60 seconds. + +Added in 7.18.0. +.IP "--key-type " +(TLS) 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 "--key " +(TLS 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 "--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. + +If this option is used several times, the last one will be used. + +\fI--krb\fP requires that the underlying libcurl was built to support Kerberos. +.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. + +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 "-l, --list-only" +(FTP POP3) (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 "--local-port " +Set a preferred single number or range (FROM-TO) 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) 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). + +See also \fI-u, --user\fP. +.IP "-L, --location" +(HTTP) 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 "--login-options " +(IMAP POP3 SMTP) 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 + +If this option is used several times, the last one will be used. + +Added in 7.34.0. +.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. + +See also \fI--mail-rcpt\fP and \fI--mail-from\fP. Added in 7.25.0. +.IP "--mail-from
" +(SMTP) Specify a single address that the given mail should get sent from. + +See also \fI--mail-rcpt\fP and \fI--mail-auth\fP. Added in 7.20.0. +.IP "--mail-rcpt
" +(SMTP) Specify a single address, user name or mailing list name. Repeat this +option several times to send to multiple recipients. + +When performing a mail transfer, the recipient should specify a valid email +address to send the mail to. + +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) + +Added in 7.20.0. +.IP "-M, --manual" +Manual. Display the huge help text. +.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. + +See also \fI--limit-rate\fP. +.IP "--max-redirs " +(HTTP) Set maximum number of redirection-followings allowed. When \fI-L, --location\fP is used, +is 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 +unlimited. + +If this option is used several times, the last one will be used. +.IP "-m, --max-time