diff options
Diffstat (limited to 'docs/curl.1')
| -rw-r--r-- | docs/curl.1 | 150 |
1 files changed, 112 insertions, 38 deletions
diff --git a/docs/curl.1 b/docs/curl.1 index f2ce1425d..1cd598d03 100644 --- a/docs/curl.1 +++ b/docs/curl.1 @@ -5,7 +5,7 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2017, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2018, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms @@ -22,13 +22,12 @@ .\" .\" DO NOT EDIT. Generated by the curl project gen.pl man page generator. .\" -.TH curl 1 "November 16, 2016" "Curl 7.59.0" "Curl Manual" +.TH curl 1 "November 16, 2016" "Curl 7.62.0" "Curl Manual" .SH NAME curl \- transfer a URL .SH SYNOPSIS -.B curl [options] -.I [URL...] +.B curl [options / URLs] .SH DESCRIPTION .B curl is a tool to transfer data from or to a server, using one of the supported @@ -66,7 +65,8 @@ 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. +in a sequential manner in the specified order. You can specify command line +options and URLs mixed and in any order on the command line. You can specify a step counter for the ranges to get every Nth number or letter: @@ -197,6 +197,11 @@ 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. +(Schannel/WinSSL only) This option is supported for WinSSL in Windows 7 or +later with libcurl 7.60 or later. This option is supported for backward +compatibility with other SSL engines; instead it is recommended to use Windows' +store of root certificates (the default for WinSSL). + If this option is used several times, the last one will be used. .IP "--capath <dir>" (TLS) Tells curl to use the specified certificate directory to verify the @@ -221,8 +226,8 @@ This is currently only implemented in the OpenSSL, GnuTLS and NSS backends. Added in 7.41.0. .IP "--cert-type <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. +(TLS) Tells curl what type the provided client certificate is using. PEM, DER, ENG +and P12 are recognized types. If not specified, PEM is assumed. If this option is used several times, the last one will be used. @@ -246,12 +251,30 @@ 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. +If curl is built against OpenSSL library, and the engine pkcs11 is available, +then a PKCS#11 URI (RFC 7512) can be used to specify a certificate located in +a PKCS#11 device. A string beginning with "pkcs11:" will be interpreted as a +PKCS#11 URI. If a PKCS#11 URI is provided, then the \fI--engine\fP option will be set +as "pkcs11" if none was provided and the \fI--cert-type\fP option will be set as +"ENG" if none was provided. + (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. +(Schannel/WinSSL only) Client certificates must be specified by a path +expression to a certificate store. (Loading PFX is not supported; you can +import it to a store first). You can use +"<store location>\\<store name>\\<thumbprint>" to refer to a certificate +in the system certificates store, for example, +"CurrentUser\\MY\\934a7ac6f8a5d579285a74fa61e19f23ddfe8d7a". Thumbprint is +usually a SHA-1 hex string which you can see in certificate details. Following +store locations are supported: CurrentUser, LocalMachine, CurrentService, +Services, CurrentUserGroupPolicy, LocalMachineGroupPolicy, +LocalMachineEnterprise. + 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. @@ -395,7 +418,8 @@ 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. +transfers on the same invoke. If the file name is exactly a minus ("-"), curl +will instead the contents from stdin. 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. @@ -444,6 +468,11 @@ 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. +Like \fI-d, --data\fP the default content-type sent to the server is +application/x-www-form-urlencoded. If you want the data to be treated as +arbitrary binary data by the server then set the content-type to octet-stream: +-H "Content-Type: application/octet-stream". + 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 <data>" @@ -504,7 +533,7 @@ 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. +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-T, --upload-file\fP. .IP "--delegation <LEVEL>" (GSS/kerberos) Set LEVEL to tell the server what it is allowed to delegate when it comes to user credentials. @@ -558,6 +587,10 @@ active mode you need to use \fI-P, --ftp-port\fP. 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 "--disallow-username-in-url" +(HTTP) This tells curl to exit if passed a url containing a username. + +See also \fI--proto\fP. Added in 7.61.0. .IP "--dns-interface <interface>" (DNS) Tell curl to send outgoing DNS requests through <interface>. This option is a counterpart to \fI--interface\fP (which does not affect DNS). The supplied string @@ -583,6 +616,11 @@ may also optionally be given as \fI:<port-number>\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 "--doh-url <URL>" +(all) Specifies which DNS-over-HTTPS (DOH) server to use to resolve hostnames, +instead of using the default name resolver mechanism. The URL must be HTTPS. + +If this option is used several times, the last one will be used. .IP "-D, --dump-header <filename>" (HTTP FTP) Write the received protocol headers to the specified file. @@ -794,7 +832,7 @@ 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. +This option overrides \fI-d, --data\fP and \fI-I, --head\fP and \fI-T, --upload-file\fP. .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. @@ -854,11 +892,11 @@ to setup an IP address and port for it to connect to. <address> should be one of: .RS .IP interface -i.e "eth0" to specify which interface's IP address you want to use (Unix only) +e.g. "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 +e.g. "192.168.10.1" to specify the exact IP address .IP "host name" -i.e "my.host.domain" to specify the machine +e.g. "my.host.domain" to specify the machine .IP "-" make curl pick the same IP address that is already used for the control connection @@ -941,6 +979,15 @@ balance human factors against network load." libcurl currently defaults to If this option is used several times, the last one will be used. Added in 7.59.0. +.IP "--haproxy-protocol" +(HTTP) Send a HAProxy PROXY protocol v1 header at the beginning of the connection. This +is used by some load balancers and reverse proxies to indicate the client's +true IP address and port. + +This option is primarily useful when sending test requests to a service that +expects this header. + +Added in 7.60.0. .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, @@ -1048,7 +1095,7 @@ name, IP address or host name. An example could look like: If this option is used several times, the last one will be used. On Linux it can be used to specify a VRF, but the binary needs to either -have CAP_NET_RAW or to be ran as root. More information about Linux VRF: +have CAP_NET_RAW or to be run as root. More information about Linux VRF: https://www.kernel.org/doc/Documentation/networking/vrf.txt See also \fI--dns-interface\fP. @@ -1061,7 +1108,7 @@ See also \fI--http1.1\fP and \fI--http2\fP. This option overrides \fI-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. +See also \fI--http1.1\fP and \fI--http2\fP. This option overrides \fI-4, --ipv4\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 @@ -1090,6 +1137,13 @@ If this option is used several times, the last one will be used. file. For SSH, if not specified, curl tries the following candidates in order: '~/.ssh/id_rsa', '~/.ssh/id_dsa', './id_rsa', './id_dsa'. +If curl is built against OpenSSL library, and the engine pkcs11 is available, +then a PKCS#11 URI (RFC 7512) can be used to specify a private key located in a +PKCS#11 device. A string beginning with "pkcs11:" will be interpreted as a +PKCS#11 URI. If a PKCS#11 URI is provided, then the \fI--engine\fP option will be set +as "pkcs11" if none was provided and the \fI--key-type\fP option will be set as +"ENG" if none was provided. + If this option is used several times, the last one will be used. .IP "--krb <level>" (FTP) Enable Kerberos authentication and use. The level must be entered and should @@ -1237,7 +1291,7 @@ 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 <time>" +.IP "-m, --max-time <seconds>" Maximum time in seconds that you allow the whole operation to take. This is useful for preventing your batch jobs from hanging for hours due to slow networks or links going down. Since 7.32.0, this option accepts decimal @@ -1270,7 +1324,6 @@ 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. - \fI--metalink\fP requires that the underlying libcurl was built to support metalink. Added in 7.27.0. .IP "--negotiate" (HTTP) Enables Negotiate (SPNEGO) authentication. @@ -1396,7 +1449,7 @@ If you want to enable NTLM for your proxy authentication, then use If this option is used several times, only the first one is used. -See also \fI--proxy-ntlm\fP. \fI--ntlm\fP requires that the underlying libcurl was built to support TLS. This option overrides \fI--basic\fP and \fI--negotiated\fP and \fI--digest\fP and \fI--anyauth\fP. +See also \fI--proxy-ntlm\fP. \fI--ntlm\fP requires that the underlying libcurl was built to support TLS. This option overrides \fI--basic\fP and \fI--negotiate\fP and \fI--digest\fP and \fI--anyauth\fP. .IP "--oauth2-bearer <token>" (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 @@ -1484,11 +1537,10 @@ a redirection. This option is meaningful only when using \fI-L, --location\fP. See also \fI--post301\fP and \fI--post303\fP and \fI-L, --location\fP. Added in 7.19.1. .IP "--post303" -(HTTP) Tells curl to respect RFC 7231/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. +(HTTP) Tells curl to violate RFC 7231/6.4.4 and not convert POST requests into GET +requests when following 303 redirections. A server may require a POST to +remain a POST after a 303 redirection. This option is meaningful only when +using \fI-L, --location\fP. See also \fI--post302\fP and \fI--post301\fP and \fI-L, --location\fP. Added in 7.26.0. .IP "--preproxy [protocol://]host[:port]" @@ -1697,6 +1749,14 @@ Added in 7.43.0. Same as \fI--ssl-allow-beast\fP but used in HTTPS proxy context. Added in 7.52.0. +.IP "--proxy-tls13-ciphers <ciphersuite list>" +(TLS) Specifies which cipher suites to use in the connection to your HTTPS proxy +when it negotiates TLS 1.3. The list of ciphers suites must specify valid +ciphers. Read up on TLS 1.3 cipher suite details on this URL: + + https://curl.haxx.se/docs/ssl-ciphers.html + +If this option is used several times, the last one will be used. .IP "--proxy-tlsauthtype <type>" Same as \fI--tlsauthtype\fP but used in HTTPS proxy context. @@ -1841,7 +1901,7 @@ Specify the path name to file containing what will be considered as random data. The data may be used to seed the random engine for SSL connections. See also the \fI--egd-file\fP option. .IP "-r, --range <range>" -(HTTP FTP SFTP FILE) Retrieve a byte range (i.e a partial document) from a HTTP/1.1, FTP or SFTP +(HTTP FTP SFTP FILE) Retrieve a byte range (i.e. a partial document) from an HTTP/1.1, FTP or SFTP server or a local FILE. Ranges can be specified in a number of ways. .RS .TP 10 @@ -2030,7 +2090,7 @@ Added in 7.12.3. 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. +a timeout, an FTP 4xx response code or an HTTP 408 or 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 @@ -2227,6 +2287,11 @@ is a plain '-', it is instead written to stdout. If this option is used several times, the last one will be used. See also \fI-v, --verbose\fP and \fI-s, --silent\fP. +.IP "--styled-output" +Enables the automatic use of bold font styles when writing HTTP headers to the +terminal. Use --no-styled-output to switch them off. + +Added in 7.61.0. .IP "--suppress-connect-headers" When \fI-p, --proxytunnel\fP is used and a CONNECT request is made don't output proxy CONNECT response headers. This option is meant to be used with \fI-D, --dump-header\fP or @@ -2300,6 +2365,14 @@ Use up to TLSv1.3. .RE See also \fI--tlsv1.0\fP and \fI--tlsv1.1\fP and \fI--tlsv1.2\fP. \fI--tls-max\fP requires that the underlying libcurl was built to support TLS. Added in 7.54.0. +.IP "--tls13-ciphers <list of TLS 1.3 ciphersuites>" +(TLS) Specifies which cipher suites to use in the connection if it negotiates TLS +1.3. The list of ciphers suites must specify valid ciphers. Read up on TLS 1.3 +cipher suite details on this URL: + + https://curl.haxx.se/docs/ssl-ciphers.html + +If this option is used several times, the last one will be used. .IP "--tlsauthtype <type>" 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 @@ -2319,19 +2392,19 @@ Set username for use with the TLS authentication method specified with Added in 7.21.4. .IP "--tlsv1.0" -(TLS) Forces curl to use TLS version 1.0 when connecting to a remote TLS server. +(TLS) Forces curl to use TLS version 1.0 or later when connecting to a remote TLS server. Added in 7.34.0. .IP "--tlsv1.1" -(TLS) Forces curl to use TLS version 1.1 when connecting to a remote TLS server. +(TLS) Forces curl to use TLS version 1.1 or later when connecting to a remote TLS server. Added in 7.34.0. .IP "--tlsv1.2" -(TLS) Forces curl to use TLS version 1.2 when connecting to a remote TLS server. +(TLS) Forces curl to use TLS version 1.2 or later when connecting to a remote TLS server. Added in 7.34.0. .IP "--tlsv1.3" -(TLS) Forces curl to use TLS version 1.3 when connecting to a remote TLS server. +(TLS) Forces curl to use TLS version 1.3 or later when connecting to a remote TLS server. Note that TLS 1.3 is only supported by a subset of TLS backends. At the time of this writing, they are BoringSSL, NSS, and Secure Transport (on iOS 11 or @@ -2339,8 +2412,8 @@ later, and macOS 10.13 or later). Added in 7.52.0. .IP "-1, --tlsv1" -(SSL) Tells curl to use TLS version 1.x when negotiating with a remote TLS -server. That means TLS version 1.0, 1.1 or 1.2. +(SSL) Tells curl to use at least TLS version 1.x when negotiating with a remote TLS +server. That means TLS version 1.0 or higher See also \fI--http1.1\fP and \fI--http2\fP. \fI-1, --tlsv1\fP requires that the underlying libcurl was built to support TLS. This option overrides \fI--tlsv1.1\fP and \fI--tlsv1.2\fP and \fI--tlsv1.3\fP. .IP "--tr-encoding" @@ -2425,8 +2498,8 @@ for win32 systems. .IP "-A, --user-agent <name>" (HTTP) Specify the User-Agent string to send to the HTTP server. 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. +the string, surround the string with single quote marks. This header can also +be set with the \fI-H, --header\fP or the \fI--proxy-header\fP options. If this option is used several times, the last one will be used. .IP "-u, --user <user:password>" @@ -2695,9 +2768,10 @@ protocol that curl supports and as specified in a URL. FTP, FTPS, POP3, IMAP, SMTP, LDAP etc. .IP "ALL_PROXY [protocol://]<host>[:port]" Sets the proxy server to use if no protocol-specific proxy is set. -.IP "NO_PROXY <comma-separated list of hosts>" -list of host names that shouldn't go through any proxy. If set to a asterisk -\&'*' only, it matches all hosts. +.IP "NO_PROXY <comma-separated list of hosts/domains>" +list of host names that shouldn't go through any proxy. If set to an asterisk +\&'*' only, it matches all hosts. Each name in this list is matched as either +a domain name which contains the hostname, or the hostname itself. This environment variable disables use of the proxy even when specified with the \fI-x, --proxy\fP option. That is @@ -2720,9 +2794,9 @@ a supported one, the proxy will be treated as an HTTP proxy. The supported proxy protocol prefixes are as follows: .IP "http://" -Makes it use it as a HTTP proxy. The default if no scheme prefix is used. +Makes it use it as an HTTP proxy. The default if no scheme prefix is used. .IP "https://" -Makes it treated as a \fBHTTPS\fP proxy. +Makes it treated as an \fBHTTPS\fP proxy. .IP "socks4://" Makes it the equivalent of \fI--socks4\fP .IP "socks4a://" |