diff --git a/.gitignore b/.gitignore index eea36b461d7d22d850c486185752372d31c0c220..27179590523824e9e4091c29ec2488afa7bddc90 100644 --- a/.gitignore +++ b/.gitignore @@ -1,72 +1,72 @@ # for c project # Prerequisites -*.d +# *.d # Object files -*.o -*.ko -*.obj -*.elf +# *.o +# *.ko +# *.obj +# *.elf # Linker output -*.ilk -*.map -*.exp +# *.ilk +# *.map +# *.exp # Precompiled Headers -*.gch -*.pch +# *.gch +# *.pch # Libraries -*.lib -*.a -*.la -*.lo +# *.lib +# *.a +# *.la +# *.lo # Shared objects (inc. Windows DLLs) -*.dll -*.so -*.so.* -*.dylib +# *.dll +# *.so +# *.so.* +# *.dylib # Executables -*.exe -*.out -*.app -*.i*86 -*.x86_64 -*.hex +# *.exe +# *.out +# *.app +# *.i*86 +# *.x86_64 +# *.hex # Debug files -*.dSYM/ -*.su -*.idb -*.pdb +# *.dSYM/ +# *.su +# *.idb +# *.pdb # Kernel Module Compile Results -*.mod* -*.cmd -.tmp_versions/ -modules.order -Module.symvers -Mkfile.old -dkms.conf +# *.mod* +# *.cmd +# .tmp_versions/ +# modules.order +# Module.symvers +# Mkfile.old +# dkms.conf # for rust project # Generated by Cargo # will have compiled files and executables -debug/ -target/ +# debug/ +# target/ # Remove Cargo.lock from gitignore if creating an executable, leave it for libraries # More information here https://doc.rust-lang.org/cargo/guide/cargo-toml-vs-cargo-lock.html -Cargo.lock +# Cargo.lock # These are backup files generated by rustfmt -**/*.rs.bk +# **/*.rs.bk # MSVC Windows builds of rustc generate these, which store debugging information -*.pdb +# *.pdb # for vscode .vscode/* diff --git a/Cargo.toml b/Cargo.toml deleted file mode 100644 index 9d930756fd031bbe4437bcfe82284bdb62730309..0000000000000000000000000000000000000000 --- a/Cargo.toml +++ /dev/null @@ -1,4 +0,0 @@ -[workspace] -members = [ - "lib", -] diff --git a/README.md b/README.md index b31f6c2860a20cda41e0b587d189ea0be35d1488..e51fd859198c722a7f73f3906c7461cf23baf210 100644 --- a/README.md +++ b/README.md @@ -1,23 +1,31 @@ # curl-rust #### 介绍 -Rewrite memory leak related modules for curl using Rust -#### 软件架构 -软件架构说明 +cURL 提供了curl（命令行工具）和 libcurl（C语言的API库），两者功能均是基于网络协议，对指定 URL 进行网络传输。cURL 使用C语言实现，libcurl 历史安全漏洞较多，其中内存类占比51%。本项目通过使用 Rust 重写 cURL 的高危模块，利用 Rust 语言的内存安全优势，以增加 libcurl 的安全性和可靠性。 +#### 项目实施方案 -#### 安装教程 +对 cURL 的改写，分为以下步骤进行： -1. 进入`rust/`目录，执行`cargo build` -2. 在项目根目录下，执行`LDFLAGS="-L./rust/target/debug" LIBS="-lrust_project -ldl" ./configure --disable-shared` -3. 执行`make`完成编译 +- 构建 Rust 项目结构，确定重写的部分的组织方式 +- 使用 c2rust 工具自动改写 C 代码 +- 手动将一些数据结构定义和函数声明移动到公共模块中 +- 改写宏定义 +- 与 C 代码混合编译并通过测试 -#### 使用说明 +#### 编译教程 -1. xxxx -2. xxxx -3. xxxx +需准备前置条件，以便 curl-rust 能正确地编译，需要的前置条件有： +make, rustup, cargo, nightly 版的 rustc, gcc, openssl-libs, automake 等。 + +准备好前置条件后，可以按如下步骤完成编译： + +1. 进入`rust/`目录，执行`cargo build --release -v` +2. 在项目根目录下，执行`aclocal`和`automake` +3. 在项目根目录下，执行`LDFLAGS="-L./rust/target/debug" LIBS="-lrust_project -ldl" ./configure --without-ssl --disable-shared` +4. 执行`make`完成编译 +5. 还可以执行`make test`进行测试 #### 参与贡献 diff --git a/ci/00-pre.sh b/ci/00-pre.sh index 14fc4968ea17089dd1ab20c6c2e8ba734ef458c5..3130348d360c3d8ec3de29fd0cd0d9e976f133ab 100755 --- a/ci/00-pre.sh +++ b/ci/00-pre.sh @@ -1,6 +1,6 @@ #!/bin/bash sudo yum clean all -sudo yum install -y gcc openssl-libs +sudo yum install -y gcc openssl-libs automake make cmake #git加速并安装rust工具链 git config --global url."https://github.91chi.fun/https://github.com/".insteadOf "https://github.com/" @@ -9,3 +9,8 @@ sh rustlang.sh -y source ~/.bashrc +rustup install nightly +rustup default nightly + +source ~/.bashrc + diff --git a/ci/01-base.sh b/ci/01-base.sh index 2fe2ffadf8b763001c91283d41477d49b2e40e1a..b4c9457f362f0ad22d5f5b2139aeff53b05561de 100755 --- a/ci/01-base.sh +++ b/ci/01-base.sh @@ -1,27 +1,38 @@ #!/bin/bash -#开始检查 +cd rust/ + +# 开始检查 cargo fmt --all -- --check -v cargo clean -#cargo clippy --all-targets --all-features --tests --benches -- -D warnings +# cargo clippy --all-targets --all-features --tests --benches -- -D warnings cargo clippy --all-targets --all-features --tests --benches -- -v cargo clean cargo check cargo clean -#cargo rustc -- -D warnings -bin=$(sed -n '/[[bin]]/ {n;p}' Cargo.toml | sed 's/\"//g' | sed 's/name = //g') -for bin_name in $bin -do -echo $bin_name -cargo rustc --bin $bin_name -- -D warnings -v -done +# cargo rustc -- -D warnings +# bin=$(sed -n '/[[bin]]/ {n;p}' Cargo.toml | sed 's/\"//g' | sed 's/name = //g') +# for bin_name in $bin +# do +# echo $bin_name +# cargo rustc --bin $bin_name -- -D warnings -v +# done cargo build --release -v -#RUST_BACKTRACE=1 cargo test --all -v -- --nocapture --test-threads=1 -RUST_BACKTRACE=1 cargo test --all -- --nocapture +# RUST_BACKTRACE=1 cargo test --all -v -- --nocapture --test-threads=1 +# RUST_BACKTRACE=1 cargo test --all -- --nocapture + +# cargo doc --all --no-deps + +cd ../ + +aclocal +automake + +LDFLAGS="-L`pwd`/rust/target/release" LIBS="-lrust_project -ldl" ./configure --without-ssl --disable-shared -cargo doc --all --no-deps +make \ No newline at end of file diff --git a/ci/02-examples.sh b/ci/02-examples.sh index bc43b8279fabadf8400cd559307ba00170e3a4e8..55e8b6fb0f390da5de2795044af843188c1fa3f2 100755 --- a/ci/02-examples.sh +++ b/ci/02-examples.sh @@ -1,3 +1,3 @@ #!/bin/bash -RUST_BACKTRACE=1 cargo run --example signals +# RUST_BACKTRACE=1 cargo run --example signals diff --git a/docs/cmdline-opts/abstract-unix-socket.d b/docs/cmdline-opts/abstract-unix-socket.d new file mode 100644 index 0000000000000000000000000000000000000000..e26048f1de06291277a727c6357b75350daeef4e --- /dev/null +++ b/docs/cmdline-opts/abstract-unix-socket.d @@ -0,0 +1,11 @@ +Long: abstract-unix-socket +Arg: +Help: Connect via abstract Unix domain socket +Added: 7.53.0 +Protocols: HTTP +Category: connection +Example: --abstract-unix-socket socketpath $URL +--- +Connect through an abstract Unix domain socket, instead of using the network. +Note: netstat shows the path of an abstract socket prefixed with '@', however +the argument should not have this leading character. diff --git a/docs/cmdline-opts/alt-svc.d b/docs/cmdline-opts/alt-svc.d new file mode 100644 index 0000000000000000000000000000000000000000..914b1fbc6b79db5f7bb24338d24da9dd048e6d1c --- /dev/null +++ b/docs/cmdline-opts/alt-svc.d @@ -0,0 +1,17 @@ +Long: alt-svc +Arg: +Protocols: HTTPS +Help: Enable alt-svc with this cache file +Added: 7.64.1 +Category: http +Example: --alt-svc svc.txt $URL +--- +This option enables the alt-svc parser in curl. If the file name points to an +existing alt-svc cache file, that will be used. After a completed transfer, +the cache will be saved to the file name again if it has been modified. + +Specify a "" file name (zero length) to avoid loading/saving and make curl +just handle the cache in memory. + +If this option is used several times, curl will load contents from all the +files but the last one will be used for saving. diff --git a/docs/cmdline-opts/anyauth.d b/docs/cmdline-opts/anyauth.d new file mode 100644 index 0000000000000000000000000000000000000000..427a64c89f0f89ccca850f09a921faeae137c56b --- /dev/null +++ b/docs/cmdline-opts/anyauth.d @@ -0,0 +1,19 @@ +Long: anyauth +Help: Pick any authentication method +Protocols: HTTP +See-also: proxy-anyauth basic digest +Category: http proxy auth +Example: --anyauth --user me:pwd $URL +--- +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 --basic, --digest, --ntlm, and --negotiate. + +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. + +Used together with --user. diff --git a/docs/cmdline-opts/append.d b/docs/cmdline-opts/append.d new file mode 100644 index 0000000000000000000000000000000000000000..8afaf0eb6190138f98707b2dbfe9e77c3fee1765 --- /dev/null +++ b/docs/cmdline-opts/append.d @@ -0,0 +1,10 @@ +Short: a +Long: append +Help: Append to target file when uploading +Protocols: FTP SFTP +Category: ftp sftp +Example: --upload-file local --append ftp://example.com/ +--- +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). diff --git a/docs/cmdline-opts/aws-sigv4.d b/docs/cmdline-opts/aws-sigv4.d new file mode 100644 index 0000000000000000000000000000000000000000..db988640b457e3ac55916b9ed401fa839dc7500b --- /dev/null +++ b/docs/cmdline-opts/aws-sigv4.d @@ -0,0 +1,18 @@ +Long: aws-sigv4 +Arg: +Help: Use AWS V4 signature authentication +Category: auth http +Added: 7.75.0 +Example: --aws-sigv4 "aws:amz:east-2:es" --user "key:secret" $URL +--- +Use AWS V4 signature authentication in the transfer. + +The provider argument is a string that is used by the algorithm when creating +outgoing authentication headers. + +The region argument is a string that points to a geographic area of +a resources collection (region-code) when the region name is omitted from +the endpoint. + +The service argument is a string that points to a function provided by a cloud +(service-code) when the service name is omitted from the endpoint. diff --git a/docs/cmdline-opts/basic.d b/docs/cmdline-opts/basic.d new file mode 100644 index 0000000000000000000000000000000000000000..62d2c22b0adcf559dd43e7eced29981c70264d20 --- /dev/null +++ b/docs/cmdline-opts/basic.d @@ -0,0 +1,13 @@ +Long: basic +Help: Use HTTP Basic Authentication +See-also: proxy-basic +Protocols: HTTP +Category: auth +Example: -u name:password --basic $URL +--- +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 +--ntlm, --digest, or --negotiate). + +Used together with --user. diff --git a/docs/cmdline-opts/cacert.d b/docs/cmdline-opts/cacert.d new file mode 100644 index 0000000000000000000000000000000000000000..1f38040461f9bdf17ea0fa26ef60e66c869150dd --- /dev/null +++ b/docs/cmdline-opts/cacert.d @@ -0,0 +1,35 @@ +Long: cacert +Arg: +Help: CA certificate to verify peer against +Protocols: TLS +Category: tls +Example: --cacert CA-file.txt $URL +--- +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. + +(Schannel only) This option is supported for Schannel 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 Schannel). + +If this option is used several times, the last one will be used. diff --git a/docs/cmdline-opts/capath.d b/docs/cmdline-opts/capath.d new file mode 100644 index 0000000000000000000000000000000000000000..ba407ed0ce1aceaf6cfda5439520d7824e9b1f64 --- /dev/null +++ b/docs/cmdline-opts/capath.d @@ -0,0 +1,17 @@ +Long: capath +Arg: +Help: CA directory to verify peer against +Protocols: TLS +Category: tls +Example: --capath /local/directory $URL +--- +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 --capath can allow +OpenSSL-powered curl to make SSL-connections much more efficiently than using +--cacert 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. diff --git a/docs/cmdline-opts/cert-status.d b/docs/cmdline-opts/cert-status.d new file mode 100644 index 0000000000000000000000000000000000000000..360e5c9019e3fd7498c6e6e49f9469c0339c96d4 --- /dev/null +++ b/docs/cmdline-opts/cert-status.d @@ -0,0 +1,15 @@ +Long: cert-status +Protocols: TLS +Added: 7.41.0 +Help: Verify the status of the server cert via OCSP-staple +Category: tls +Example: --cert-status $URL +--- +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. diff --git a/docs/cmdline-opts/cert-type.d b/docs/cmdline-opts/cert-type.d new file mode 100644 index 0000000000000000000000000000000000000000..9fcbfe752ae8138e6d65909cc3f9f3a11cf06f78 --- /dev/null +++ b/docs/cmdline-opts/cert-type.d @@ -0,0 +1,12 @@ +Long: cert-type +Protocols: TLS +Arg: +Help: Certificate type (DER/PEM/ENG) +See-also: cert key key-type +Category: tls +Example: --cert-type PEM --cert file $URL +--- +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. diff --git a/docs/cmdline-opts/cert.d b/docs/cmdline-opts/cert.d new file mode 100644 index 0000000000000000000000000000000000000000..8e0fb88e8e1014d72a016f54475c9f3bceda1215 --- /dev/null +++ b/docs/cmdline-opts/cert.d @@ -0,0 +1,52 @@ +Short: E +Long: cert +Arg: +Help: Client certificate file and password +Protocols: TLS +See-also: cert-type key key-type +Category: tls +Example: --cert certfile --key keyfile $URL +--- +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 --cert and --key 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. + +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 --engine option will be set +as "pkcs11" if none was provided and the --cert-type 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 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 +"\\\\" 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. diff --git a/docs/cmdline-opts/ciphers.d b/docs/cmdline-opts/ciphers.d new file mode 100644 index 0000000000000000000000000000000000000000..c2cb92e0653ef846e3c4bfa0650f5d8f9fac1a40 --- /dev/null +++ b/docs/cmdline-opts/ciphers.d @@ -0,0 +1,13 @@ +Long: ciphers +Arg: +Help: SSL ciphers to use +Protocols: TLS +Category: tls +Example: --ciphers ECDHE-ECDSA-AES256-CCM8 $URL +--- +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://curl.se/docs/ssl-ciphers.html + +If this option is used several times, the last one will be used. diff --git a/docs/cmdline-opts/compressed-ssh.d b/docs/cmdline-opts/compressed-ssh.d new file mode 100644 index 0000000000000000000000000000000000000000..d95c6adfb0fece6864b4c20d9d45c3732fb2dc5d --- /dev/null +++ b/docs/cmdline-opts/compressed-ssh.d @@ -0,0 +1,9 @@ +Long: compressed-ssh +Help: Enable SSH compression +Protocols: SCP SFTP +Added: 7.56.0 +Category: scp ssh +Example: --compressed-ssh sftp://example.com/ +--- +Enables built-in SSH compression. +This is a request, not an order; the server may or may not do it. diff --git a/docs/cmdline-opts/compressed.d b/docs/cmdline-opts/compressed.d new file mode 100644 index 0000000000000000000000000000000000000000..945beb85d9f763ac325390e1a45732f2978fbb4b --- /dev/null +++ b/docs/cmdline-opts/compressed.d @@ -0,0 +1,12 @@ +Long: compressed +Help: Request compressed response +Protocols: HTTP +Category: http +Example: --compressed $URL +--- +Request a compressed response using one of the algorithms curl supports, and +automatically decompress the content. Headers are not modified. + +If this option is used and the server sends an unsupported encoding, curl will +report an error. This is a request, not an order; the server may or may not +deliver data compressed. diff --git a/docs/cmdline-opts/config.d b/docs/cmdline-opts/config.d new file mode 100644 index 0000000000000000000000000000000000000000..1de0b31f4dcc3ff77e941aa258448400ab27c5d1 --- /dev/null +++ b/docs/cmdline-opts/config.d @@ -0,0 +1,72 @@ +Long: config +Arg: +Help: Read config from a file +Short: K +Category: curl +Example: --config file.txt $URL +--- + +Specify a text file to read curl arguments from. The command line arguments +found in the text file will be used as if they were provided on the command +line. + +Options and their parameters must be specified on the same line in the file, +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 contains whitespace (or starts with : or =), 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 --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 --url option, and not by simply writing the URL on its own +line. So, it could look similar to this: + +url = "https://curl.se/docs/" + +When curl is invoked, it (unless --disable is used) checks for a default +config file and uses it if found, even when this option is used. The default +config file is checked for in the following places in this order: + +1) Use the CURL_HOME environment variable if set + +2) Use the XDG_CONFIG_HOME environment variable if set (Added in 7.73.0) + +3) Use the HOME environment variable if set + +4) Non-windows: use getpwuid to find the home directory + +5) Windows: use APPDATA if set + +6) Windows: use "USERPROFILE\\Application Data" if set + +7) 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. diff --git a/docs/cmdline-opts/connect-timeout.d b/docs/cmdline-opts/connect-timeout.d new file mode 100644 index 0000000000000000000000000000000000000000..e66e35adfbea6c6063ef51b1f91ad2959181d273 --- /dev/null +++ b/docs/cmdline-opts/connect-timeout.d @@ -0,0 +1,14 @@ +Long: connect-timeout +Arg: +Help: Maximum time allowed for connection +See-also: max-time +Category: connection +Example: --connect-timeout 20 $URL +Example: --connect-timeout 3.14 $URL +--- +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. diff --git a/docs/cmdline-opts/connect-to.d b/docs/cmdline-opts/connect-to.d new file mode 100644 index 0000000000000000000000000000000000000000..ebea9b9daed6d79b6cedab42dbb55c0154193758 --- /dev/null +++ b/docs/cmdline-opts/connect-to.d @@ -0,0 +1,23 @@ +Long: connect-to +Arg: +Help: Connect to host +Added: 7.49.0 +See-also: resolve header +Category: connection +Example: --connect-to example.com:443:example.net:8443 $URL +--- + +For a request to the given HOST1:PORT1 pair, connect to HOST2:PORT2 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. "HOST1" and "PORT1" may be the empty string, meaning "any +host/port". "HOST2" and "PORT2" may also be the empty string, meaning "use the +request's original host/port". + +A "host" specified to this option is compared as a string, so it needs to +match the name used in request URL. It can be either numerical such as +"127.0.0.1" or the full host name such as "example.org". + +This option can be used many times to add many connect rules. diff --git a/docs/cmdline-opts/continue-at.d b/docs/cmdline-opts/continue-at.d new file mode 100644 index 0000000000000000000000000000000000000000..9e11bdb1234b5c2fa9912aa272cad9f8ae77b568 --- /dev/null +++ b/docs/cmdline-opts/continue-at.d @@ -0,0 +1,18 @@ +Short: C +Long: continue-at +Arg: +Help: Resumed transfer offset +See-also: range +Category: connection +Example: -C - $URL +Example: -C 400 $URL +--- +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. diff --git a/docs/cmdline-opts/cookie-jar.d b/docs/cmdline-opts/cookie-jar.d new file mode 100644 index 0000000000000000000000000000000000000000..f418af6d7673780b50a9108d2ad165abd64e9330 --- /dev/null +++ b/docs/cmdline-opts/cookie-jar.d @@ -0,0 +1,27 @@ +Short: c +Long: cookie-jar +Arg: +Protocols: HTTP +Help: Write cookies to after operation +Category: http +Example: -c store-here.txt $URL +Example: -c store-here.txt -b read-these $URL +--- +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 --cookie +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 --verbose 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. diff --git a/docs/cmdline-opts/cookie.d b/docs/cmdline-opts/cookie.d new file mode 100644 index 0000000000000000000000000000000000000000..b593935eb77185bb2007893ad021fc5a1e686dd7 --- /dev/null +++ b/docs/cmdline-opts/cookie.d @@ -0,0 +1,36 @@ +Short: b +Long: cookie +Arg: +Protocols: HTTP +Help: Send cookies from string/file +Category: http +Example: -b cookiefile $URL +Example: -b cookiefile -c cookiefile $URL +--- +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 --location option or do multiple URL +transfers on the same invoke. If the file name is exactly a minus ("-"), curl +will instead read 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. + +The file specified with --cookie is only used as input. No cookies will be +written to the file. To store cookies, use the --cookie-jar option. + +If you use the Set-Cookie file format and don't specify a domain then the +cookie is not sent since the domain will never match. To address this, set a +domain in Set-Cookie line (doing that will include sub-domains) or preferably: +use the Netscape format. + +This option can be used multiple times. + +Users very often want to both read cookies from a file and write updated +cookies back to a file, so using both --cookie and --cookie-jar in the same +command line is common. diff --git a/docs/cmdline-opts/create-dirs.d b/docs/cmdline-opts/create-dirs.d new file mode 100644 index 0000000000000000000000000000000000000000..cae1d5a51c32c6dd52c2da93ff05b944c3a977cd --- /dev/null +++ b/docs/cmdline-opts/create-dirs.d @@ -0,0 +1,14 @@ +Long: create-dirs +Help: Create necessary local directory hierarchy +Category: curl +Example: --create-dirs --output local/dir/file $URL +--- +When used in conjunction with the --output option, curl will create the +necessary local directory hierarchy as needed. This option creates the +directories mentioned with the --output option, nothing else. If the --output +file name uses no directory, or if the directories it mentions already exist, +no directories will be created. + +Created dirs are made with mode 0750 on unix style file systems. + +To create remote directories when using FTP or SFTP, try --ftp-create-dirs. diff --git a/docs/cmdline-opts/create-file-mode.d b/docs/cmdline-opts/create-file-mode.d new file mode 100644 index 0000000000000000000000000000000000000000..429b5ee33ce40b18affcc90e34558226dbc6436c --- /dev/null +++ b/docs/cmdline-opts/create-file-mode.d @@ -0,0 +1,16 @@ +Long: create-file-mode +Arg: +Help: File mode for created files +Protocols: SFTP SCP FILE +Category: sftp scp file upload +See-also: ftp-create-dirs +Added: 7.75.0 +Example: --create-file-mode 0777 -T localfile sftp://example.com/new +--- +When curl is used to create files remotely using one of the supported +protocols, this option allows the user to set which 'mode' to set on the file +at creation time, instead of the default 0644. + +This option takes an octal number as argument. + +If this option is used several times, the last one will be used. diff --git a/docs/cmdline-opts/crlf.d b/docs/cmdline-opts/crlf.d new file mode 100644 index 0000000000000000000000000000000000000000..856cd135a57c69b839b6b5bda40320989e5b6e7f --- /dev/null +++ b/docs/cmdline-opts/crlf.d @@ -0,0 +1,9 @@ +Long: crlf +Help: Convert LF to CRLF in upload +Protocols: FTP SMTP +Category: ftp smtp +Example: --crlf -T file ftp://example.com/ +--- +Convert LF to CRLF in upload. Useful for MVS (OS/390). + +(SMTP added in 7.40.0) diff --git a/docs/cmdline-opts/crlfile.d b/docs/cmdline-opts/crlfile.d new file mode 100644 index 0000000000000000000000000000000000000000..21e86a8c24f79d1c8d07957286e95f3e81bc7ae7 --- /dev/null +++ b/docs/cmdline-opts/crlfile.d @@ -0,0 +1,12 @@ +Long: crlfile +Arg: +Protocols: TLS +Help: Use this CRL list +Added: 7.19.7 +Category: tls +Example: --crlfile rejects.txt $URL +--- +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. diff --git a/docs/cmdline-opts/curves.d b/docs/cmdline-opts/curves.d new file mode 100644 index 0000000000000000000000000000000000000000..ac5ab10169389cc6e456f8ea7dcd202df7b15d68 --- /dev/null +++ b/docs/cmdline-opts/curves.d @@ -0,0 +1,19 @@ +Long: curves +Arg: +Help: (EC) TLS key exchange algorithm(s) to request +Protocols: TLS +Added: 7.73.0 +Category: tls +Example: --curves X25519 $URL +--- +Tells curl to request specific curves to use during SSL session establishment +according to RFC 8422, 5.1. Multiple algorithms can be provided by separating +them with ":" (e.g. "X25519:P-521"). The parameter is available identically +in the "openssl s_client/s_server" utilities. + +--curves allows a OpenSSL powered curl to make SSL-connections with exactly +the (EC) curve requested by the client, avoiding intransparent client/server +negotiations. + +If this option is set, the default curves list built into openssl will be +ignored. diff --git a/docs/cmdline-opts/data-ascii.d b/docs/cmdline-opts/data-ascii.d new file mode 100644 index 0000000000000000000000000000000000000000..943f301dd1517b96b854e0d74a5d740cd9a5bff4 --- /dev/null +++ b/docs/cmdline-opts/data-ascii.d @@ -0,0 +1,8 @@ +Long: data-ascii +Arg: +Help: HTTP POST ASCII data +Protocols: HTTP +Category: http post upload +Example: --data-ascii @file $URL +--- +This is just an alias for --data. diff --git a/docs/cmdline-opts/data-binary.d b/docs/cmdline-opts/data-binary.d new file mode 100644 index 0000000000000000000000000000000000000000..578cebca62caf2f4b5dc55402dc3528bd82f8be8 --- /dev/null +++ b/docs/cmdline-opts/data-binary.d @@ -0,0 +1,20 @@ +Long: data-binary +Arg: +Help: HTTP POST binary data +Protocols: HTTP +Category: http post upload +Example: --data-binary @filename $URL +--- +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 --data does, except that newlines and +carriage returns are preserved and conversions are never done. + +Like --data 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 --data. diff --git a/docs/cmdline-opts/data-raw.d b/docs/cmdline-opts/data-raw.d new file mode 100644 index 0000000000000000000000000000000000000000..b8cd0f72117dec56dd80ebb17c1afb59f7bd3cb7 --- /dev/null +++ b/docs/cmdline-opts/data-raw.d @@ -0,0 +1,12 @@ +Long: data-raw +Arg: +Protocols: HTTP +Help: HTTP POST data, '@' allowed +Added: 7.43.0 +See-also: data +Category: http post upload +Example: --data-raw "hello" $URL +Example: --data-raw "@at@at@" $URL +--- +This posts data similarly to --data but without the special +interpretation of the @ character. diff --git a/docs/cmdline-opts/data-urlencode.d b/docs/cmdline-opts/data-urlencode.d new file mode 100644 index 0000000000000000000000000000000000000000..8b12957543d16c836786aa12f5c0c35cf2653e65 --- /dev/null +++ b/docs/cmdline-opts/data-urlencode.d @@ -0,0 +1,38 @@ +Long: data-urlencode +Arg: +Help: HTTP POST data url encoded +Protocols: HTTP +See-also: data data-raw +Added: 7.18.0 +Category: http post upload +Example: --data-urlencode name=val $URL +Example: --data-urlencode =encodethis $URL +Example: --data-urlencode name@file $URL +Example: --data-urlencode @fileonly $URL +--- +This posts data, similar to the other --data options with the exception +that this performs URL-encoding. + +To be CGI-compliant, the part should begin with a *name* 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 *name=urlencoded-file-content*. Note that the +name is expected to be URL-encoded already. +.RE diff --git a/docs/cmdline-opts/data.d b/docs/cmdline-opts/data.d new file mode 100644 index 0000000000000000000000000000000000000000..35fd675edb43bb107a8a0c9b2be30ba1ca44a7ef --- /dev/null +++ b/docs/cmdline-opts/data.d @@ -0,0 +1,33 @@ +Long: data +Short: d +Arg: +Help: HTTP POST data +Protocols: HTTP MQTT +See-also: data-binary data-urlencode data-raw +Mutexed: form head upload-file +Category: important http post upload +Example: -d "name=curl" $URL +Example: -d "name=curl" -d "tool=cmdline" $URL +Example: -d @filename $URL +--- +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 --form. + +--data-raw is almost the same but does not have a special interpretation of +the @ character. To post data purely binary, you should instead use the +--data-binary option. To URL-encode the value of a form field you may use +--data-urlencode. + +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. Posting +data from a file named \&'foobar' would thus be done with --data @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 --data-raw instead. diff --git a/docs/cmdline-opts/delegation.d b/docs/cmdline-opts/delegation.d new file mode 100644 index 0000000000000000000000000000000000000000..1514d66bc8bbaa9d7f13df29ac24aeaa3cd628a7 --- /dev/null +++ b/docs/cmdline-opts/delegation.d @@ -0,0 +1,20 @@ +Long: delegation +Arg: +Help: GSS-API delegation permission +Protocols: GSS/kerberos +Category: auth +Example: --delegation "none" $URL +--- +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 + +If this option is used several times, the last one will be used. diff --git a/docs/cmdline-opts/digest.d b/docs/cmdline-opts/digest.d new file mode 100644 index 0000000000000000000000000000000000000000..193413777aee129980ae5299666b528c37101263 --- /dev/null +++ b/docs/cmdline-opts/digest.d @@ -0,0 +1,13 @@ +Long: digest +Help: Use HTTP Digest Authentication +Protocols: HTTP +Mutexed: basic ntlm negotiate +See-also: user proxy-digest anyauth +Category: proxy auth http +Example: -u name:password --digest $URL +--- +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 --user option to set user name and password. + +If this option is used several times, only the first one is used. diff --git a/docs/cmdline-opts/disable-eprt.d b/docs/cmdline-opts/disable-eprt.d new file mode 100644 index 0000000000000000000000000000000000000000..38b3e0b3812c80caef1363a72b3873d31444bb56 --- /dev/null +++ b/docs/cmdline-opts/disable-eprt.d @@ -0,0 +1,21 @@ +Long: disable-eprt +Help: Inhibit using EPRT or LPRT +Protocols: FTP +Category: ftp +Example: --disable-eprt ftp://example.com/ +--- +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 --disable-eprt. + +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 --ftp-port or force it with --ftp-pasv. diff --git a/docs/cmdline-opts/disable-epsv.d b/docs/cmdline-opts/disable-epsv.d new file mode 100644 index 0000000000000000000000000000000000000000..281ec5c9d5f4565a332b60aea8073aa3e0aff431 --- /dev/null +++ b/docs/cmdline-opts/disable-epsv.d @@ -0,0 +1,18 @@ +Long: disable-epsv +Help: Inhibit using EPSV +Protocols: FTP +Category: ftp +Example: --disable-epsv ftp://example.com/ +--- +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 --disable-epsv. + +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 --ftp-port. diff --git a/docs/cmdline-opts/disable.d b/docs/cmdline-opts/disable.d new file mode 100644 index 0000000000000000000000000000000000000000..3eb87f8d4dfdfad064fa28f05df34793208801f3 --- /dev/null +++ b/docs/cmdline-opts/disable.d @@ -0,0 +1,9 @@ +Long: disable +Short: q +Help: Disable .curlrc +Category: curl +Example: -q $URL +--- +If used as the first parameter on the command line, the *curlrc* config +file will not be read and used. See the --config for details on the default +config file search path. diff --git a/docs/cmdline-opts/disallow-username-in-url.d b/docs/cmdline-opts/disallow-username-in-url.d new file mode 100644 index 0000000000000000000000000000000000000000..f3122aea56918abf511a5a8ff232d094542b9d06 --- /dev/null +++ b/docs/cmdline-opts/disallow-username-in-url.d @@ -0,0 +1,10 @@ +Long: disallow-username-in-url +Help: Disallow username in url +Protocols: HTTP +Added: 7.61.0 +See-also: proto +Category: curl http +Example: --disallow-username-in-url $URL +--- +This tells curl to exit if passed a url containing a username. This is probably +most useful when the URL is being provided at run-time or similar. diff --git a/docs/cmdline-opts/dns-interface.d b/docs/cmdline-opts/dns-interface.d new file mode 100644 index 0000000000000000000000000000000000000000..fec7927eb6ec8edd263a75e2610511388f66bce0 --- /dev/null +++ b/docs/cmdline-opts/dns-interface.d @@ -0,0 +1,13 @@ +Long: dns-interface +Arg: +Help: Interface to use for DNS requests +Protocols: DNS +See-also: dns-ipv4-addr dns-ipv6-addr +Added: 7.33.0 +Requires: c-ares +Category: dns +Example: --dns-interface eth0 $URL +--- +Tell curl to send outgoing DNS requests through . This option is a +counterpart to --interface (which does not affect DNS). The supplied string +must be an interface name (not an address). diff --git a/docs/cmdline-opts/dns-ipv4-addr.d b/docs/cmdline-opts/dns-ipv4-addr.d new file mode 100644 index 0000000000000000000000000000000000000000..e09153ab494d3d6293dc8598cef2309439dbd55f --- /dev/null +++ b/docs/cmdline-opts/dns-ipv4-addr.d @@ -0,0 +1,15 @@ +Long: dns-ipv4-addr +Arg:
+Help: IPv4 address to use for DNS requests +Protocols: DNS +See-also: dns-interface dns-ipv6-addr +Added: 7.33.0 +Requires: c-ares +Category: dns +Example: --dns-ipv4-addr 10.1.2.3 $URL +--- +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. + +If this option is used several times, the last one will be used. diff --git a/docs/cmdline-opts/dns-ipv6-addr.d b/docs/cmdline-opts/dns-ipv6-addr.d new file mode 100644 index 0000000000000000000000000000000000000000..954cb98b321d1b1428c4c510b8bd12ca6ce5ab30 --- /dev/null +++ b/docs/cmdline-opts/dns-ipv6-addr.d @@ -0,0 +1,15 @@ +Long: dns-ipv6-addr +Arg:
+Help: IPv6 address to use for DNS requests +Protocols: DNS +See-also: dns-interface dns-ipv4-addr +Added: 7.33.0 +Requires: c-ares +Category: dns +Example: --dns-ipv6-addr 2a04:4e42::561 $URL +--- +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. + +If this option is used several times, the last one will be used. diff --git a/docs/cmdline-opts/dns-servers.d b/docs/cmdline-opts/dns-servers.d new file mode 100644 index 0000000000000000000000000000000000000000..089473580f8e50b8751f7f561000ddedbe97dce9 --- /dev/null +++ b/docs/cmdline-opts/dns-servers.d @@ -0,0 +1,14 @@ +Long: dns-servers +Arg: +Help: DNS server addrs to use +Requires: c-ares +Added: 7.33.0 +Category: dns +Example: --dns-servers 192.168.0.1,192.168.0.2 $URL +--- +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 *:* after each IP +address. + +If this option is used several times, the last one will be used. diff --git a/docs/cmdline-opts/doh-cert-status.d b/docs/cmdline-opts/doh-cert-status.d new file mode 100644 index 0000000000000000000000000000000000000000..a760a6fb1f8b9dd5e427b95183878f1ba5d4aef7 --- /dev/null +++ b/docs/cmdline-opts/doh-cert-status.d @@ -0,0 +1,8 @@ +Long: doh-cert-status +Help: Verify the status of the DoH server cert via OCSP-staple +Protocols: all +Added: 7.76.0 +Category: dns tls +Example: --doh-cert-status --doh-url https://doh.example $URL +--- +Same as --cert-status but used for DoH (DNS-over-HTTPS). diff --git a/docs/cmdline-opts/doh-insecure.d b/docs/cmdline-opts/doh-insecure.d new file mode 100644 index 0000000000000000000000000000000000000000..907a5dcd69ba09d071c2c2bd30097968b55cf717 --- /dev/null +++ b/docs/cmdline-opts/doh-insecure.d @@ -0,0 +1,8 @@ +Long: doh-insecure +Help: Allow insecure DoH server connections +Protocols: all +Added: 7.76.0 +Category: dns tls +Example: --doh-insecure --doh-url https://doh.example $URL +--- +Same as --insecure but used for DoH (DNS-over-HTTPS). diff --git a/docs/cmdline-opts/doh-url.d b/docs/cmdline-opts/doh-url.d new file mode 100644 index 0000000000000000000000000000000000000000..80ff96ccc1524904fde0a1d9b91999a78fab4516 --- /dev/null +++ b/docs/cmdline-opts/doh-url.d @@ -0,0 +1,17 @@ +Long: doh-url +Arg: +Help: Resolve host names over DoH +Protocols: all +Added: 7.62.0 +Category: dns +Example: --doh-url https://doh.example $URL +--- +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. + +Some SSL options that you set for your transfer will apply to DoH since the +name lookups take place over SSL. However, the certificate verification +settings are not inherited and can be controlled separately via +--doh-insecure and --doh-cert-status. + +If this option is used several times, the last one will be used. diff --git a/docs/cmdline-opts/dump-header.d b/docs/cmdline-opts/dump-header.d new file mode 100644 index 0000000000000000000000000000000000000000..62c92f44bba6d4ad18596b4669b9416d45db4058 --- /dev/null +++ b/docs/cmdline-opts/dump-header.d @@ -0,0 +1,16 @@ +Long: dump-header +Short: D +Arg: +Help: Write the received headers to +Protocols: HTTP FTP +See-also: output +Category: http ftp +Example: --dump-header store.txt $URL +--- +Write the received protocol headers to the specified file. If no headers are +received, the use of this option will create an empty file. + +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. diff --git a/docs/cmdline-opts/egd-file.d b/docs/cmdline-opts/egd-file.d new file mode 100644 index 0000000000000000000000000000000000000000..2e99df4cd14cc213ff0e762bcf80380db7af65de --- /dev/null +++ b/docs/cmdline-opts/egd-file.d @@ -0,0 +1,10 @@ +Long: egd-file +Arg: +Help: EGD socket path for random data +Protocols: TLS +See-also: random-file +Category: tls +Example: --egd-file /random/here $URL +--- +Specify the path name to the Entropy Gathering Daemon socket. The socket is +used to seed the random engine for SSL connections. diff --git a/docs/cmdline-opts/engine.d b/docs/cmdline-opts/engine.d new file mode 100644 index 0000000000000000000000000000000000000000..8a2dcf7463bd8705e14da9ccc65cf8752b87a696 --- /dev/null +++ b/docs/cmdline-opts/engine.d @@ -0,0 +1,10 @@ +Long: engine +Arg: +Help: Crypto engine to use +Protocols: TLS +Category: tls +Example: --engine flavor $URL +--- +Select the OpenSSL crypto engine to use for cipher operations. Use --engine +list to print a list of build-time supported engines. Note that not all (and +possibly none) of the engines may be available at run-time. diff --git a/docs/cmdline-opts/etag-compare.d b/docs/cmdline-opts/etag-compare.d new file mode 100644 index 0000000000000000000000000000000000000000..fa16762876e08744477114ce804e61167845b4dd --- /dev/null +++ b/docs/cmdline-opts/etag-compare.d @@ -0,0 +1,19 @@ +Long: etag-compare +Arg: +Help: Pass an ETag from a file as a custom header +Protocols: HTTP +Added: 7.68.0 +Category: http +Example: --etag-compare etag.txt $URL +--- +This option makes a conditional HTTP request for the specific ETag read +from the given file by sending a custom If-None-Match header using the +stored ETag. + +For correct results, make sure that the specified file contains only a +single line with the desired ETag. An empty file is parsed as an empty +ETag. + +Use the option --etag-save to first save the ETag from a response, and +then use this option to compare against the saved ETag in a subsequent +request. diff --git a/docs/cmdline-opts/etag-save.d b/docs/cmdline-opts/etag-save.d new file mode 100644 index 0000000000000000000000000000000000000000..8efad9044f0e1a02f9e30bdb64d1b8f820bec92f --- /dev/null +++ b/docs/cmdline-opts/etag-save.d @@ -0,0 +1,12 @@ +Long: etag-save +Arg: +Help: Parse ETag from a request and save it to a file +Protocols: HTTP +Added: 7.68.0 +Category: http +Example: --etag-save storetag.txt $URL +--- +This option saves an HTTP ETag to the specified file. An ETag is a +caching related header, usually returned in a response. + +If no ETag is sent by the server, an empty file is created. diff --git a/docs/cmdline-opts/expect100-timeout.d b/docs/cmdline-opts/expect100-timeout.d new file mode 100644 index 0000000000000000000000000000000000000000..8855edd0b7237caaba221c46ecff9e04462b767f --- /dev/null +++ b/docs/cmdline-opts/expect100-timeout.d @@ -0,0 +1,13 @@ +Long: expect100-timeout +Arg: +Help: How long to wait for 100-continue +Protocols: HTTP +Added: 7.47.0 +See-also: connect-timeout +Category: http +Example: --expect100-timeout 2.5 -T file $URL +--- +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. diff --git a/docs/cmdline-opts/fail-early.d b/docs/cmdline-opts/fail-early.d new file mode 100644 index 0000000000000000000000000000000000000000..aad15c3feb8fb9d5741a30fe0d1a58092c8c0a6d --- /dev/null +++ b/docs/cmdline-opts/fail-early.d @@ -0,0 +1,23 @@ +Long: fail-early +Help: Fail on first transfer error, do not continue +Added: 7.52.0 +Category: curl +Example: --fail-early $URL https://two.example +--- +Fail and exit on the first detected transfer 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 transfer +that fails, independent of the amount of URLs that are given on the command +line. This way, no transfer failures go undetected by scripts and similar. + +This option is global and does not need to be specified for each use of --next. + +This option does not imply --fail, which causes transfers to fail due to the +server's HTTP status code. You can combine the two options, however note --fail +is not global and is therefore contained by --next. diff --git a/docs/cmdline-opts/fail-with-body.d b/docs/cmdline-opts/fail-with-body.d new file mode 100644 index 0000000000000000000000000000000000000000..9b8c7db4ef13fc72e1a09cdf2f98d3bc987c8451 --- /dev/null +++ b/docs/cmdline-opts/fail-with-body.d @@ -0,0 +1,16 @@ +Long: fail-with-body +Protocols: HTTP +Help: Fail on HTTP errors but save the body +Category: http output +Added: 7.76.0 +See-also: fail +Example: --fail-with-body $URL +--- +Return an error on server errors where the HTTP response code is 400 or +greater). 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 still allow curl to output and save that content but +also to return error 22. + +This is an alternative option to --fail which makes curl fail for the same +circumstances but without saving the content. diff --git a/docs/cmdline-opts/fail.d b/docs/cmdline-opts/fail.d new file mode 100644 index 0000000000000000000000000000000000000000..a5e0c91e7ede96af95379f31e7acc4ede2aeb0ca --- /dev/null +++ b/docs/cmdline-opts/fail.d @@ -0,0 +1,17 @@ +Long: fail +Short: f +Protocols: HTTP +Help: Fail silently (no output at all) on HTTP errors +See-also: fail-with-body +Category: important http +Example: --fail $URL +--- +Fail silently (no output at all) on server errors. This is mostly done to +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). diff --git a/docs/cmdline-opts/false-start.d b/docs/cmdline-opts/false-start.d new file mode 100644 index 0000000000000000000000000000000000000000..de36962eea3df1f1bf2650a0c1a820f70fb890ad --- /dev/null +++ b/docs/cmdline-opts/false-start.d @@ -0,0 +1,14 @@ +Long: false-start +Help: Enable TLS False Start +Protocols: TLS +Added: 7.42.0 +Category: tls +Example: --false-start $URL +--- +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. diff --git a/docs/cmdline-opts/form-string.d b/docs/cmdline-opts/form-string.d new file mode 100644 index 0000000000000000000000000000000000000000..4f1a766bc7f522eb6304020f2c3bf9c90f848c5e --- /dev/null +++ b/docs/cmdline-opts/form-string.d @@ -0,0 +1,13 @@ +Long: form-string +Help: Specify multipart MIME data +Protocols: HTTP SMTP IMAP +Arg: +See-also: form +Category: http upload +Example: --form-string "data" $URL +--- +Similar to --form 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 --form if +there's any possibility that the string value may accidentally trigger the +\&'@' or \&'<' features of --form. diff --git a/docs/cmdline-opts/form.d b/docs/cmdline-opts/form.d new file mode 100644 index 0000000000000000000000000000000000000000..06f2c553269489323f11bb8fc9d8eacea6fe55ed --- /dev/null +++ b/docs/cmdline-opts/form.d @@ -0,0 +1,140 @@ +Long: form +Short: F +Arg: +Help: Specify multipart MIME data +Protocols: HTTP SMTP IMAP +Mutexed: data head upload-file +Category: http upload +Example: --form "name=curl" --form "file=@loadthis" $URL +--- +For HTTP protocol family, 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. + +For SMTP and IMAP protocols, this is the means to compose a multipart mail +message to transmit. + +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. + +Tell curl to read content from stdin instead of a file by using - as +filename. This goes for both @ and < constructs. When stdin is used, the +contents is buffered in memory first by curl to determine its size and allow a +possible resend. Defining a part's data from a named non-regular file (such +as a named pipe or similar) is unfortunately not subject to buffering and will +be effectively read at transmission time; since the full size is unknown +before the transfer starts, such data is sent as chunks by HTTP and rejected +by IMAP. + +Example: send an image to an HTTP server, where \&'profile' is the name of the +form-field to which the file portrait.jpg will be the input: + + curl -F profile=@portrait.jpg https://example.com/upload.cgi + +Example: send your name and shoe size in two text fields to the server: + + curl -F name=John -F shoesize=11 https://example.com/ + +Example: send your essay in a text field to the server. Send it as a plain +text field, but get the contents for it from a local file: + + curl -F "story=HTML message;type=text/html' \\ +.br + -F '=)' -F '=@textfile.txt' ... smtp://example.com + +Data can be encoded for transfer using encoder=. Available encodings are +*binary* and *8bit* that do nothing else than adding the corresponding +Content-Transfer-Encoding header, *7bit* that only rejects 8-bit characters +with a transfer error, *quoted-printable* and *base64* that encodes data +according to the corresponding schemes, limiting lines length to 76 +characters. + +Example: send multipart mail with a quoted-printable text message and a +base64 attached file: + + curl -F '=text message;encoder=quoted-printable' \\ +.br + -F '=@localfile;encoder=base64' ... smtp://example.com + +See further examples and details in the MANUAL. + +This option can be used multiple times. diff --git a/docs/cmdline-opts/ftp-account.d b/docs/cmdline-opts/ftp-account.d new file mode 100644 index 0000000000000000000000000000000000000000..ce816f10d2b9ecf4e104b89096db912fc4a792e3 --- /dev/null +++ b/docs/cmdline-opts/ftp-account.d @@ -0,0 +1,12 @@ +Long: ftp-account +Arg: +Help: Account data string +Protocols: FTP +Added: 7.13.0 +Category: ftp auth +Example: --ftp-account "mr.robot" ftp://example.com/ +--- +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. diff --git a/docs/cmdline-opts/ftp-alternative-to-user.d b/docs/cmdline-opts/ftp-alternative-to-user.d new file mode 100644 index 0000000000000000000000000000000000000000..a5fb9853d22c6a2ec860d0bdea260ce11496b987 --- /dev/null +++ b/docs/cmdline-opts/ftp-alternative-to-user.d @@ -0,0 +1,12 @@ +Long: ftp-alternative-to-user +Arg: +Help: String to replace USER [name] +Protocols: FTP +Added: 7.15.5 +Category: ftp +Example: --ftp-alternative-to-user "U53r" ftp://example.com +--- +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. diff --git a/docs/cmdline-opts/ftp-create-dirs.d b/docs/cmdline-opts/ftp-create-dirs.d new file mode 100644 index 0000000000000000000000000000000000000000..579f8e36d89ca860e9d175976d60ee1c0159baf3 --- /dev/null +++ b/docs/cmdline-opts/ftp-create-dirs.d @@ -0,0 +1,10 @@ +Long: ftp-create-dirs +Protocols: FTP SFTP +Help: Create the remote dirs if not present +See-also: create-dirs +Category: ftp sftp curl +Example: --ftp-create-dirs -T file ftp://example.com/remote/path/file +--- +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. diff --git a/docs/cmdline-opts/ftp-method.d b/docs/cmdline-opts/ftp-method.d new file mode 100644 index 0000000000000000000000000000000000000000..4af0baf4234530fff83bc4cbf9ee202062b62f90 --- /dev/null +++ b/docs/cmdline-opts/ftp-method.d @@ -0,0 +1,25 @@ +Long: ftp-method +Arg: +Help: Control CWD usage +Protocols: FTP +Added: 7.15.1 +Category: ftp +Example: --ftp-method multicwd ftp://example.com/dir1/dir2/file +Example: --ftp-method nocwd ftp://example.com/dir1/dir2/file +Example: --ftp-method singlecwd ftp://example.com/dir1/dir2/file +--- +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 diff --git a/docs/cmdline-opts/ftp-pasv.d b/docs/cmdline-opts/ftp-pasv.d new file mode 100644 index 0000000000000000000000000000000000000000..d920fefa6e724c7ffa68e22ca86b82915eed4231 --- /dev/null +++ b/docs/cmdline-opts/ftp-pasv.d @@ -0,0 +1,18 @@ +Long: ftp-pasv +Help: Use PASV/EPSV instead of PORT +Protocols: FTP +Added: 7.11.0 +See-also: disable-epsv +Category: ftp +Example: --ftp-pasv ftp://example.com/ +--- +Use passive mode for the data connection. Passive is the internal default +behavior, but using this option can be used to override a previous --ftp-port +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 --ftp-port again. + +Passive mode means that curl will try the EPSV command first and then PASV, +unless --disable-epsv is used. diff --git a/docs/cmdline-opts/ftp-port.d b/docs/cmdline-opts/ftp-port.d new file mode 100644 index 0000000000000000000000000000000000000000..52e55e58f9069624ae16713bb9aec94703778d19 --- /dev/null +++ b/docs/cmdline-opts/ftp-port.d @@ -0,0 +1,36 @@ +Long: ftp-port +Arg:
+Help: Use PORT instead of PASV +Short: P +Protocols: FTP +See-also: ftp-pasv disable-eprt +Category: ftp +Example: -P - ftp:/example.com +Example: -P eth0 ftp:/example.com +Example: -P 192.168.0.2 ftp:/example.com +--- +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 +e.g. "eth0" to specify which interface's IP address you want to use (Unix only) +.IP "IP address" +e.g. "192.168.10.1" to specify the exact IP address +.IP "host name" +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 +.RE + +If this option is used several times, the last one will be used. Disable the +use of PORT with --ftp-pasv. Disable the attempt to use the EPRT command +instead of PORT by using --disable-eprt. 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. diff --git a/docs/cmdline-opts/ftp-pret.d b/docs/cmdline-opts/ftp-pret.d new file mode 100644 index 0000000000000000000000000000000000000000..453d8cf85871e2a0a9d824b5d6bbe95b4c2b10f9 --- /dev/null +++ b/docs/cmdline-opts/ftp-pret.d @@ -0,0 +1,10 @@ +Long: ftp-pret +Help: Send PRET before PASV +Protocols: FTP +Added: 7.20.0 +Category: ftp +Example: --ftp-pret ftp://example.com/ +--- +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. diff --git a/docs/cmdline-opts/ftp-skip-pasv-ip.d b/docs/cmdline-opts/ftp-skip-pasv-ip.d new file mode 100644 index 0000000000000000000000000000000000000000..36f9e6da13c608c73959fc56a71694162e946726 --- /dev/null +++ b/docs/cmdline-opts/ftp-skip-pasv-ip.d @@ -0,0 +1,16 @@ +Long: ftp-skip-pasv-ip +Help: Skip the IP address for PASV +Protocols: FTP +Added: 7.14.2 +See-also: ftp-pasv +Category: ftp +Example: --ftp-skip-pasv-ip ftp://example.com/ +--- +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. + +Since curl 7.74.0 this option is enabled by default. + +This option has no effect if PORT, EPRT or EPSV is used instead of PASV. diff --git a/docs/cmdline-opts/ftp-ssl-ccc-mode.d b/docs/cmdline-opts/ftp-ssl-ccc-mode.d new file mode 100644 index 0000000000000000000000000000000000000000..15ad1f54b00fab4fc6e45bc64ab383e7107eac63 --- /dev/null +++ b/docs/cmdline-opts/ftp-ssl-ccc-mode.d @@ -0,0 +1,13 @@ +Long: ftp-ssl-ccc-mode +Arg: +Help: Set CCC mode +Protocols: FTP +Added: 7.16.2 +See-also: ftp-ssl-ccc +Category: ftp tls +Example: --ftp-ssl-ccc-mode active --ftp-ssl-ccc ftps://example.com/ +--- +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. diff --git a/docs/cmdline-opts/ftp-ssl-ccc.d b/docs/cmdline-opts/ftp-ssl-ccc.d new file mode 100644 index 0000000000000000000000000000000000000000..bfaf431bbb3dee250f9b72bb43d288ac7d18068e --- /dev/null +++ b/docs/cmdline-opts/ftp-ssl-ccc.d @@ -0,0 +1,12 @@ +Long: ftp-ssl-ccc +Help: Send CCC after authenticating +Protocols: FTP +See-also: ssl ftp-ssl-ccc-mode +Added: 7.16.1 +Category: ftp tls +Example: --ftp-ssl-ccc ftps://example.com/ +--- +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. diff --git a/docs/cmdline-opts/ftp-ssl-control.d b/docs/cmdline-opts/ftp-ssl-control.d new file mode 100644 index 0000000000000000000000000000000000000000..72dc080bcabb03cf07900ea78c02eb3659b8fac2 --- /dev/null +++ b/docs/cmdline-opts/ftp-ssl-control.d @@ -0,0 +1,10 @@ +Long: ftp-ssl-control +Help: Require SSL/TLS for FTP login, clear for transfer +Protocols: FTP +Added: 7.16.0 +Category: ftp tls +Example: --ftp-ssl-control ftp://example.com +--- +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. diff --git a/docs/cmdline-opts/get.d b/docs/cmdline-opts/get.d new file mode 100644 index 0000000000000000000000000000000000000000..c5fb5c94116673cc9f8e46fce527b1a3ce024a22 --- /dev/null +++ b/docs/cmdline-opts/get.d @@ -0,0 +1,19 @@ +Long: get +Short: G +Help: Put the post data in the URL and use GET +Category: http upload +Example: --get $URL +Example: --get -d "tool=curl" -d "age=old" $URL +Example: --get -I -d "tool=curl" $URL +--- +When used, this option will make all data specified with --data, --data-binary +or --data-urlencode 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 --head, 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. diff --git a/docs/cmdline-opts/globoff.d b/docs/cmdline-opts/globoff.d new file mode 100644 index 0000000000000000000000000000000000000000..ec2c7ae48a8c56a18e5d42b5803753ec9537e8bb --- /dev/null +++ b/docs/cmdline-opts/globoff.d @@ -0,0 +1,10 @@ +Long: globoff +Short: g +Help: Disable URL sequences and ranges using {} and [] +Category: curl +Example: -g "https://example.com/{[]}}}}" +--- +This option switches off the "URL globbing parser". When you set this option, +you can specify URLs that contain the letters {}[] without having curl itself +interpret them. Note that these letters are not normal legal URL contents but +they should be encoded according to the URI standard. diff --git a/docs/cmdline-opts/happy-eyeballs-timeout-ms.d b/docs/cmdline-opts/happy-eyeballs-timeout-ms.d new file mode 100644 index 0000000000000000000000000000000000000000..c3b2a51322b302063d0d823a0610aaf93d1dcb50 --- /dev/null +++ b/docs/cmdline-opts/happy-eyeballs-timeout-ms.d @@ -0,0 +1,19 @@ +Long: happy-eyeballs-timeout-ms +Arg: +Help: Time for IPv6 before trying IPv4 +Added: 7.59.0 +Category: connection +Example: --happy-eyeballs-timeout-ms 500 $URL +--- +Happy Eyeballs is an algorithm that attempts to connect to both IPv4 and IPv6 +addresses for dual-stack hosts, giving IPv6 a head-start of the specified +number of milliseconds. If the IPv6 address cannot be connected to within that +time, then a connection attempt is made to the IPv4 address in parallel. The +first connection to be established is the one that is used. + +The range of suggested useful values is limited. Happy Eyeballs RFC 6555 says +"It is RECOMMENDED that connection attempts be paced 150-250 ms apart to +balance human factors against network load." libcurl currently defaults to +200 ms. Firefox and Chrome currently default to 300 ms. + +If this option is used several times, the last one will be used. diff --git a/docs/cmdline-opts/haproxy-protocol.d b/docs/cmdline-opts/haproxy-protocol.d new file mode 100644 index 0000000000000000000000000000000000000000..446dc657223680fcc60b2bed644e4c3e3b50632e --- /dev/null +++ b/docs/cmdline-opts/haproxy-protocol.d @@ -0,0 +1,13 @@ +Long: haproxy-protocol +Help: Send HAProxy PROXY protocol v1 header +Protocols: HTTP +Added: 7.60.0 +Category: http proxy +Example: --haproxy-protocol $URL +--- +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. diff --git a/docs/cmdline-opts/head.d b/docs/cmdline-opts/head.d new file mode 100644 index 0000000000000000000000000000000000000000..06d2489d5eaa0b52d7b18e03134074b830f14e73 --- /dev/null +++ b/docs/cmdline-opts/head.d @@ -0,0 +1,10 @@ +Long: head +Short: I +Help: Show document info only +Protocols: HTTP FTP FILE +Category: http ftp file +Example: -I $URL +--- +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. diff --git a/docs/cmdline-opts/header.d b/docs/cmdline-opts/header.d new file mode 100644 index 0000000000000000000000000000000000000000..11c96d5eae2f4b09e6218ca56f9ed611726ca434 --- /dev/null +++ b/docs/cmdline-opts/header.d @@ -0,0 +1,43 @@ +Long: header +Short: H +Arg:
+Help: Pass custom header(s) to server +Protocols: HTTP +Category: http +See-also: user-agent referer +Example: -H "X-First-Name: Joe" $URL +Example: -H "User-Agent: yes-please/2000" $URL +Example: -H "Host:" $URL +--- +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 **not** add that as a part of the header +content: do not add newlines or carriage returns, they will only mess things +up for you. + +This option can take an argument in @filename style, which then adds a header +for each line in the input file. Using @- will make curl read the header file +from stdin. Added in 7.55.0. + +You need --proxy-header to send custom headers intended for a HTTP +proxy. Added in 7.37.0. + +Passing on a "Transfer-Encoding: chunked" header when doing a HTTP request +with a request body, will make curl send the data using chunked encoding. + +**WARNING**: headers set with this option will be set in all requests - even +after redirects are followed, like when told with --location. 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. diff --git a/docs/cmdline-opts/help.d b/docs/cmdline-opts/help.d new file mode 100644 index 0000000000000000000000000000000000000000..28ae868d2ff9f730de8a971f38877e7aacd1629e --- /dev/null +++ b/docs/cmdline-opts/help.d @@ -0,0 +1,13 @@ +Long: help +Arg: +Short: h +Help: Get help for commands +Category: important curl +Example: --help all +--- +Usage help. This lists all commands of the . +If no arg was provided, curl will display the most important +command line arguments. +If the argument "all" was provided, curl will display all options available. +If the argument "category" was provided, curl will display all categories and +their meanings. diff --git a/docs/cmdline-opts/hostpubmd5.d b/docs/cmdline-opts/hostpubmd5.d new file mode 100644 index 0000000000000000000000000000000000000000..833db950c7e8e6bbf912c50378417d70cefc9415 --- /dev/null +++ b/docs/cmdline-opts/hostpubmd5.d @@ -0,0 +1,11 @@ +Long: hostpubmd5 +Arg: +Help: Acceptable MD5 hash of the host public key +Protocols: SFTP SCP +Added: 7.17.1 +Category: sftp scp +Example: --hostpubmd5 e5c1c49020640a5ab0f2034854c321a8 sftp://example.com/ +--- +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. diff --git a/docs/cmdline-opts/hsts.d b/docs/cmdline-opts/hsts.d new file mode 100644 index 0000000000000000000000000000000000000000..f9cd453dac6d7fcae0de38384351a731ba0b96d1 --- /dev/null +++ b/docs/cmdline-opts/hsts.d @@ -0,0 +1,17 @@ +Long: hsts +Arg: +Protocols: HTTPS +Help: Enable HSTS with this cache file +Added: 7.74.0 +Category: http +Example: --hsts cache.txt $URL +--- +This option enables HSTS for the transfer. If the file name points to an +existing HSTS cache file, that will be used. After a completed transfer, the +cache will be saved to the file name again if it has been modified. + +Specify a "" file name (zero length) to avoid loading/saving and make curl +just handle HSTS in memory. + +If this option is used several times, curl will load contents from all the +files but the last one will be used for saving. diff --git a/docs/cmdline-opts/http0.9.d b/docs/cmdline-opts/http0.9.d new file mode 100644 index 0000000000000000000000000000000000000000..7c45d565a8f55d3fec263a531e382c1a0e7cac40 --- /dev/null +++ b/docs/cmdline-opts/http0.9.d @@ -0,0 +1,15 @@ +Long: http0.9 +Tags: Versions +Protocols: HTTP +Added: +Help: Allow HTTP 0.9 responses +Category: http +Example: --http0.9 $URL +--- +Tells curl to be fine with HTTP version 0.9 response. + +HTTP/0.9 is a completely headerless response and therefore you can also +connect with this to non-HTTP servers and still get a response since curl will +simply transparently downgrade - if allowed. + +Since curl 7.66.0, HTTP/0.9 is disabled by default. diff --git a/docs/cmdline-opts/http1.0.d b/docs/cmdline-opts/http1.0.d new file mode 100644 index 0000000000000000000000000000000000000000..cbfbaee40dc5ac0c17b8ab212e7ab1205c73341b --- /dev/null +++ b/docs/cmdline-opts/http1.0.d @@ -0,0 +1,12 @@ +Short: 0 +Long: http1.0 +Tags: Versions +Protocols: HTTP +Added: +Mutexed: http1.1 http2 +Help: Use HTTP 1.0 +Category: http +Example: --http1.0 $URL +--- +Tells curl to use HTTP version 1.0 instead of using its internally preferred +HTTP version. diff --git a/docs/cmdline-opts/http1.1.d b/docs/cmdline-opts/http1.1.d new file mode 100644 index 0000000000000000000000000000000000000000..01fa76d332e0abfb79e63af9b84a7ebfc00d1cb9 --- /dev/null +++ b/docs/cmdline-opts/http1.1.d @@ -0,0 +1,10 @@ +Long: http1.1 +Tags: Versions +Protocols: HTTP +Added: 7.33.0 +Mutexed: http1.0 http2 +Help: Use HTTP 1.1 +Category: http +Example: --http1.1 $URL +--- +Tells curl to use HTTP version 1.1. diff --git a/docs/cmdline-opts/http2-prior-knowledge.d b/docs/cmdline-opts/http2-prior-knowledge.d new file mode 100644 index 0000000000000000000000000000000000000000..e3b32f6ba4a259488d4d55a70c011646296c22a4 --- /dev/null +++ b/docs/cmdline-opts/http2-prior-knowledge.d @@ -0,0 +1,14 @@ +Long: http2-prior-knowledge +Tags: Versions +Protocols: HTTP +Added: 7.49.0 +Mutexed: http1.1 http1.0 http2 +Requires: HTTP/2 +Help: Use HTTP 2 without HTTP/1.1 Upgrade +Category: http +Example: --http2-prior-knowledge $URL +--- +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. diff --git a/docs/cmdline-opts/http2.d b/docs/cmdline-opts/http2.d new file mode 100644 index 0000000000000000000000000000000000000000..2a85db600d756b15724d8178429b97bf85c59181 --- /dev/null +++ b/docs/cmdline-opts/http2.d @@ -0,0 +1,19 @@ +Long: http2 +Tags: Versions +Protocols: HTTP +Added: 7.33.0 +Mutexed: http1.1 http1.0 http2-prior-knowledge +Requires: HTTP/2 +See-also: no-alpn +Help: Use HTTP 2 +See-also: http1.1 http3 +Category: http +Example: --http2 $URL +--- +Tells curl to use HTTP version 2. + +For HTTPS, this means curl will attempt to negotiate HTTP/2 in the TLS +handshake. curl does this by default. + +For HTTP, this means curl will attempt to upgrade the request to HTTP/2 using +the Upgrade: request header. diff --git a/docs/cmdline-opts/http3.d b/docs/cmdline-opts/http3.d new file mode 100644 index 0000000000000000000000000000000000000000..f6c92b39a60c8eaeca78a5f33c00cf6bda90b1d4 --- /dev/null +++ b/docs/cmdline-opts/http3.d @@ -0,0 +1,20 @@ +Long: http3 +Tags: Versions +Protocols: HTTP +Added: 7.66.0 +Mutexed: http1.1 http1.0 http2 http2-prior-knowledge +Requires: HTTP/3 +Help: Use HTTP v3 +See-also: http1.1 http2 +Category: http +Example: --http3 $URL +--- +**WARNING**: this option is experimental. Do not use in production. + +Tells curl to use HTTP version 3 directly to the host and port number used in +the URL. A normal HTTP/3 transaction will be done to a host and then get +redirected via Alt-Svc, but this option allows a user to circumvent that when +you know that the target speaks HTTP/3 on the given host and port. + +This option will make curl fail if a QUIC connection cannot be established, it +cannot fall back to a lower HTTP version on its own. diff --git a/docs/cmdline-opts/ignore-content-length.d b/docs/cmdline-opts/ignore-content-length.d new file mode 100644 index 0000000000000000000000000000000000000000..8a4c24754a44cf801f693868e86627c1d12099b4 --- /dev/null +++ b/docs/cmdline-opts/ignore-content-length.d @@ -0,0 +1,14 @@ +Long: ignore-content-length +Help: Ignore the size of the remote resource +Protocols: FTP HTTP +Category: http ftp +Example: --ignore-content-length $URL +--- +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. + +This option doesn't work for HTTP if libcurl was built to use hyper. diff --git a/docs/cmdline-opts/include.d b/docs/cmdline-opts/include.d new file mode 100644 index 0000000000000000000000000000000000000000..80a05e0c86b46707df81ccee07867b279f145796 --- /dev/null +++ b/docs/cmdline-opts/include.d @@ -0,0 +1,12 @@ +Long: include +Short: i +Help: Include protocol response headers in the output +See-also: verbose +Category: important verbose +Example: -i $URL +--- +Include the HTTP response headers in the output. The HTTP response headers can +include things like server name, cookies, date of the document, HTTP version +and more... + +To view the request headers, consider the --verbose option. diff --git a/docs/cmdline-opts/insecure.d b/docs/cmdline-opts/insecure.d new file mode 100644 index 0000000000000000000000000000000000000000..fb2c17d8bb8f9b65cb8468b8b0af73296dbad043 --- /dev/null +++ b/docs/cmdline-opts/insecure.d @@ -0,0 +1,19 @@ +Long: insecure +Short: k +Help: Allow insecure server connections when using SSL +Protocols: TLS +See-also: proxy-insecure cacert +Category: tls +Example: --insecure $URL +--- +By default, every SSL connection curl makes is verified to be secure. This +option allows curl to proceed and operate even for server connections +otherwise considered insecure. + +The server connection is verified by making sure the server's certificate +contains the right name and verifies successfully using the cert store. + +See this online resource for further details: + https://curl.se/docs/sslcerts.html + +**WARNING**: this makes the transfer insecure. diff --git a/docs/cmdline-opts/interface.d b/docs/cmdline-opts/interface.d new file mode 100644 index 0000000000000000000000000000000000000000..b2c8eeec5ebff9eb82c9b063b2e171647a3d58f8 --- /dev/null +++ b/docs/cmdline-opts/interface.d @@ -0,0 +1,18 @@ +Long: interface +Arg: +Help: Use network INTERFACE (or address) +See-also: dns-interface +Category: connection +Example: --interface eth0 $URL +--- + +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. + +On Linux it can be used to specify a VRF, but the binary needs to either +have CAP_NET_RAW or to be run as root. More information about Linux VRF: +https://www.kernel.org/doc/Documentation/networking/vrf.txt diff --git a/docs/cmdline-opts/ipv4.d b/docs/cmdline-opts/ipv4.d new file mode 100644 index 0000000000000000000000000000000000000000..90a6dda007865bbde08ef42076555d7b79ad1727 --- /dev/null +++ b/docs/cmdline-opts/ipv4.d @@ -0,0 +1,14 @@ +Short: 4 +Long: ipv4 +Tags: Versions +Protocols: +Added: +Mutexed: ipv6 +Requires: +See-also: http1.1 http2 +Help: Resolve names to IPv4 addresses +Category: connection dns +Example: --ipv4 $URL +--- +This option tells curl to resolve names to IPv4 addresses only, and not for +example try IPv6. diff --git a/docs/cmdline-opts/ipv6.d b/docs/cmdline-opts/ipv6.d new file mode 100644 index 0000000000000000000000000000000000000000..dfa79abab33bcbb13eb99ff866cd6eb8b10f09e7 --- /dev/null +++ b/docs/cmdline-opts/ipv6.d @@ -0,0 +1,14 @@ +Short: 6 +Long: ipv6 +Tags: Versions +Protocols: +Added: +Mutexed: ipv4 +Requires: +See-also: http1.1 http2 +Help: Resolve names to IPv6 addresses +Category: connection dns +Example: --ipv6 $URL +--- +This option tells curl to resolve names to IPv6 addresses only, and not for +example try IPv4. diff --git a/docs/cmdline-opts/junk-session-cookies.d b/docs/cmdline-opts/junk-session-cookies.d new file mode 100644 index 0000000000000000000000000000000000000000..0cc342c72010f2c1ce0b9ac1feddd1f4c8d95094 --- /dev/null +++ b/docs/cmdline-opts/junk-session-cookies.d @@ -0,0 +1,12 @@ +Long: junk-session-cookies +Short: j +Help: Ignore session cookies read from file +Protocols: HTTP +See-also: cookie cookie-jar +Category: http +Example: --junk-session-cookies -b cookies.txt $URL +--- +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. diff --git a/docs/cmdline-opts/keepalive-time.d b/docs/cmdline-opts/keepalive-time.d new file mode 100644 index 0000000000000000000000000000000000000000..1b96c4dc5fe509d41ead20edd94e4561b5112db8 --- /dev/null +++ b/docs/cmdline-opts/keepalive-time.d @@ -0,0 +1,15 @@ +Long: keepalive-time +Arg: +Help: Interval time for keepalive probes +Added: 7.18.0 +Category: connection +Example: --keepalive-time 20 $URL +--- +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 --no-keepalive is used. + +If this option is used several times, the last one will be used. If +unspecified, the option defaults to 60 seconds. diff --git a/docs/cmdline-opts/key-type.d b/docs/cmdline-opts/key-type.d new file mode 100644 index 0000000000000000000000000000000000000000..4baa9afa29a6b2a34b4a3e3dfee4c99d5223b191 --- /dev/null +++ b/docs/cmdline-opts/key-type.d @@ -0,0 +1,11 @@ +Long: key-type +Arg: +Help: Private key file type (DER/PEM/ENG) +Protocols: TLS +Category: tls +Example: --key-type DER --key here $URL +--- +Private key file type. Specify which type your --key 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. diff --git a/docs/cmdline-opts/key.d b/docs/cmdline-opts/key.d new file mode 100644 index 0000000000000000000000000000000000000000..d7f5e22a6a750755dc4cc36a8904b1cedf264b68 --- /dev/null +++ b/docs/cmdline-opts/key.d @@ -0,0 +1,19 @@ +Long: key +Arg: +Protocols: TLS SSH +Help: Private key file name +Category: tls ssh +Example: --cert certificate --key here $URL +--- +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 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 --engine option will be set +as "pkcs11" if none was provided and the --key-type option will be set as +"ENG" if none was provided. + +If this option is used several times, the last one will be used. diff --git a/docs/cmdline-opts/krb.d b/docs/cmdline-opts/krb.d new file mode 100644 index 0000000000000000000000000000000000000000..3d9ce999e9a43c9e30ee613f0a0b30f240e01d4c --- /dev/null +++ b/docs/cmdline-opts/krb.d @@ -0,0 +1,13 @@ +Long: krb +Arg: +Help: Enable Kerberos with security +Protocols: FTP +Requires: Kerberos +Category: ftp +Example: --krb clear ftp://example.com/ +--- +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. diff --git a/docs/cmdline-opts/libcurl.d b/docs/cmdline-opts/libcurl.d new file mode 100644 index 0000000000000000000000000000000000000000..b7371fffe20977ccb1531c537b273f961192feeb --- /dev/null +++ b/docs/cmdline-opts/libcurl.d @@ -0,0 +1,16 @@ +Long: libcurl +Arg: +Help: Dump libcurl equivalent code of this command line +Added: 7.16.1 +Category: curl +Example: --libcurl client.c $URL +--- +Append this option to any ordinary curl command line, and you will get +libcurl-using C source code written to the file that does the equivalent +of what your command-line operation does! + +This option is global and does not need to be specified for each use of +--next. + +If this option is used several times, the last given file name will be +used. diff --git a/docs/cmdline-opts/limit-rate.d b/docs/cmdline-opts/limit-rate.d new file mode 100644 index 0000000000000000000000000000000000000000..7c46e544a34be13805b7b9d27c797e30db76671f --- /dev/null +++ b/docs/cmdline-opts/limit-rate.d @@ -0,0 +1,23 @@ +Long: limit-rate +Arg: +Help: Limit transfer speed to RATE +Category: connection +Example: --limit-rate 100K $URL +Example: --limit-rate 1000 $URL +Example: --limit-rate 10M $URL +--- +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. The suffixes (k, M, G, T, P) +are 1024 based. For example 1k is 1024. Examples: 200K, 3m and 1G. + +If you also use the --speed-limit 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. diff --git a/docs/cmdline-opts/list-only.d b/docs/cmdline-opts/list-only.d new file mode 100644 index 0000000000000000000000000000000000000000..29f9ba2f3c3456722e5df619180d6ec7f844c296 --- /dev/null +++ b/docs/cmdline-opts/list-only.d @@ -0,0 +1,26 @@ +Long: list-only +Short: l +Protocols: FTP POP3 +Help: List only mode +Added: 4.0 +Category: ftp pop3 +Example: --list-only ftp://example.com/dir/ +--- +(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 an 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 --request, this option can be used to send a UIDL +command instead, so the user may use the email's unique identifier rather than +its message-id to make the request. diff --git a/docs/cmdline-opts/local-port.d b/docs/cmdline-opts/local-port.d new file mode 100644 index 0000000000000000000000000000000000000000..77664170032a2d5de617467fca0ccf0aedf13fbf --- /dev/null +++ b/docs/cmdline-opts/local-port.d @@ -0,0 +1,11 @@ +Long: local-port +Arg: +Help: Force use of RANGE for local port numbers +Added: 7.15.2 +Category: connection +Example: --local-port 1000-3000 $URL +--- +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. diff --git a/docs/cmdline-opts/location-trusted.d b/docs/cmdline-opts/location-trusted.d new file mode 100644 index 0000000000000000000000000000000000000000..98c49ffe194c18722ab969f5874f56f9aa271e92 --- /dev/null +++ b/docs/cmdline-opts/location-trusted.d @@ -0,0 +1,11 @@ +Long: location-trusted +Help: Like --location, and send auth to other hosts +Protocols: HTTP +See-also: user +Category: http auth +Example: --location-trusted -u user:password $URL +--- +Like --location, 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). diff --git a/docs/cmdline-opts/location.d b/docs/cmdline-opts/location.d new file mode 100644 index 0000000000000000000000000000000000000000..08c939c15d6ce32fcc0d64f1786f152c229c02e8 --- /dev/null +++ b/docs/cmdline-opts/location.d @@ -0,0 +1,27 @@ +Long: location +Short: L +Help: Follow redirects +Protocols: HTTP +Category: http +Example: -L $URL +--- +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 +--include or --head, 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 --location-trusted on how to change +this. You can limit the amount of redirects to follow by using the +--max-redirs option. + +When curl follows a redirect and if the request is a POST, it will send 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 POST requests to GET after a 30x response by +using the dedicated options for that: --post301, --post302 and --post303. + +The method set with --request overrides the method curl would otherwise select +to use. diff --git a/docs/cmdline-opts/login-options.d b/docs/cmdline-opts/login-options.d new file mode 100644 index 0000000000000000000000000000000000000000..de7728854e541f2f03557e9c81429a4568993c8d --- /dev/null +++ b/docs/cmdline-opts/login-options.d @@ -0,0 +1,16 @@ +Long: login-options +Arg: +Protocols: IMAP POP3 SMTP +Help: Server login options +Added: 7.34.0 +Category: imap pop3 smtp auth +Example: --login-options 'AUTH=*' imap://example.com +--- +Specify the login options to use during server authentication. + +You can use 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 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. diff --git a/docs/cmdline-opts/mail-auth.d b/docs/cmdline-opts/mail-auth.d new file mode 100644 index 0000000000000000000000000000000000000000..49a02d5baa709d5af12ef17c552e9645d7144e95 --- /dev/null +++ b/docs/cmdline-opts/mail-auth.d @@ -0,0 +1,12 @@ +Long: mail-auth +Arg:
+Protocols: SMTP +Help: Originator address of the original email +Added: 7.25.0 +See-also: mail-rcpt mail-from +Category: smtp +Example: --mail-auth user@example.come -T mail smtp://example.com/ +--- +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. diff --git a/docs/cmdline-opts/mail-from.d b/docs/cmdline-opts/mail-from.d new file mode 100644 index 0000000000000000000000000000000000000000..be0547c9f2fa71a7a3966630492b0d4ab1a7ef2b --- /dev/null +++ b/docs/cmdline-opts/mail-from.d @@ -0,0 +1,10 @@ +Long: mail-from +Arg:
+Help: Mail from this address +Protocols: SMTP +Added: 7.20.0 +See-also: mail-rcpt mail-auth +Category: smtp +Example: --mail-from user@example.com -T mail smtp://example.com/ +--- +Specify a single address that the given mail should get sent from. diff --git a/docs/cmdline-opts/mail-rcpt-allowfails.d b/docs/cmdline-opts/mail-rcpt-allowfails.d new file mode 100644 index 0000000000000000000000000000000000000000..36d555e17c48d3f97b64f73ba5cc388edf4db199 --- /dev/null +++ b/docs/cmdline-opts/mail-rcpt-allowfails.d @@ -0,0 +1,18 @@ +Long: mail-rcpt-allowfails +Help: Allow RCPT TO command to fail for some recipients +Protocols: SMTP +Added: 7.69.0 +Category: smtp +Example: --mail-rcpt-allowfails --mail-rcpt dest@example.com smtp://example.com +--- +When sending data to multiple recipients, by default curl will abort SMTP +conversation if at least one of the recipients causes RCPT TO command to +return an error. + +The default behavior can be changed by passing --mail-rcpt-allowfails +command-line option which will make curl ignore errors and proceed with the +remaining valid recipients. + +If all recipients trigger RCPT TO failures and this flag is specified, curl +will still abort the SMTP conversation and return the error received from to +the last RCPT TO command. diff --git a/docs/cmdline-opts/mail-rcpt.d b/docs/cmdline-opts/mail-rcpt.d new file mode 100644 index 0000000000000000000000000000000000000000..d4a2502eea70e5c0721dc3bd5a081f968e5a1b57 --- /dev/null +++ b/docs/cmdline-opts/mail-rcpt.d @@ -0,0 +1,18 @@ +Long: mail-rcpt +Arg:
+Help: Mail to this address +Protocols: SMTP +Added: 7.20.0 +Category: smtp +Example: --mail-rcpt user@example.net smtp://example.com +--- +Specify a single e-mail address, user name or mailing list name. Repeat this +option several times to send to multiple recipients. + +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) diff --git a/docs/cmdline-opts/manual.d b/docs/cmdline-opts/manual.d new file mode 100644 index 0000000000000000000000000000000000000000..c81754b7a7a608defdeed4f14c55d1b739c7ebf3 --- /dev/null +++ b/docs/cmdline-opts/manual.d @@ -0,0 +1,7 @@ +Long: manual +Short: M +Help: Display the full manual +Category: curl +Example: --manual +--- +Manual. Display the huge help text. diff --git a/docs/cmdline-opts/max-filesize.d b/docs/cmdline-opts/max-filesize.d new file mode 100644 index 0000000000000000000000000000000000000000..0f8aca42e2cf3a91a03c3fb771495c4968ca4e4e --- /dev/null +++ b/docs/cmdline-opts/max-filesize.d @@ -0,0 +1,19 @@ +Long: max-filesize +Arg: +Help: Maximum file size to download +Protocols: FTP HTTP MQTT +See-also: limit-rate +Category: connection +Example: --max-filesize 100K $URL +--- +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. + +A size modifier may be used. For example, 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. (Added in 7.58.0) + +**NOTE**: 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. \ No newline at end of file diff --git a/docs/cmdline-opts/max-redirs.d b/docs/cmdline-opts/max-redirs.d new file mode 100644 index 0000000000000000000000000000000000000000..eade17f7bccecd8eb5a535f2cb6803ff746f4ec6 --- /dev/null +++ b/docs/cmdline-opts/max-redirs.d @@ -0,0 +1,12 @@ +Long: max-redirs +Arg: +Help: Maximum number of redirects allowed +Protocols: HTTP +Category: http +Example: --max-redirs 3 --location $URL +--- +Set maximum number of redirections to follow. When --location is used, to +prevent curl from following too many redirects, by default, the limit is +set to 50 redirects. Set this option to -1 to make it unlimited. + +If this option is used several times, the last one will be used. diff --git a/docs/cmdline-opts/max-time.d b/docs/cmdline-opts/max-time.d new file mode 100644 index 0000000000000000000000000000000000000000..cb86fa9fcd59455cb62c32b9369739cfc3e01d3a --- /dev/null +++ b/docs/cmdline-opts/max-time.d @@ -0,0 +1,16 @@ +Long: max-time +Short: m +Arg: +Help: Maximum time allowed for transfer +See-also: connect-timeout +Category: connection +Example: --max-time 10 $URL +Example: --max-time 2.92 $URL +--- +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. + +If this option is used several times, the last one will be used. diff --git a/docs/cmdline-opts/metalink.d b/docs/cmdline-opts/metalink.d new file mode 100644 index 0000000000000000000000000000000000000000..1fc10874213ba7783babec9ede0046280388e3b7 --- /dev/null +++ b/docs/cmdline-opts/metalink.d @@ -0,0 +1,8 @@ +Long: metalink +Help: Process given URLs as metalink XML file +Added: 7.27.0 +Category: misc +Example: --metalink file $URL +--- +This option was previously used to specify a metalink resource. Metalink +support has been disabled in curl since 7.78.0 for security reasons. diff --git a/docs/cmdline-opts/negotiate.d b/docs/cmdline-opts/negotiate.d new file mode 100644 index 0000000000000000000000000000000000000000..e862bc82026bba6e2422d7067cc10eea953b64c5 --- /dev/null +++ b/docs/cmdline-opts/negotiate.d @@ -0,0 +1,17 @@ +Long: negotiate +Help: Use HTTP Negotiate (SPNEGO) authentication +Protocols: HTTP +See-also: basic ntlm anyauth proxy-negotiate +Category: auth http +Example: --negotiate -u : $URL +--- +Enables Negotiate (SPNEGO) authentication. + +This option requires a library built with GSS-API or SSPI support. Use +--version to see if your curl supports GSS-API/SSPI or SPNEGO. + +When using this option, you must also provide a fake --user option to activate +the authentication code properly. Sending a '-u :' is enough as the user name +and password from the --user option aren't actually used. + +If this option is used several times, only the first one is used. diff --git a/docs/cmdline-opts/netrc-file.d b/docs/cmdline-opts/netrc-file.d new file mode 100644 index 0000000000000000000000000000000000000000..df89d51f54946b3f54bfdcb714f7e519058f839d --- /dev/null +++ b/docs/cmdline-opts/netrc-file.d @@ -0,0 +1,14 @@ +Long: netrc-file +Help: Specify FILE for netrc +Arg: +Added: 7.21.5 +Mutexed: netrc +Category: curl +Example: --netrc-file netrc $URL +--- +This option is similar to --netrc, 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 --netrc-file options are provided, +the last one will be used. + +It will abide by --netrc-optional if specified. diff --git a/docs/cmdline-opts/netrc-optional.d b/docs/cmdline-opts/netrc-optional.d new file mode 100644 index 0000000000000000000000000000000000000000..3869a2009b6b3e9a770253d8895fa5e1df716622 --- /dev/null +++ b/docs/cmdline-opts/netrc-optional.d @@ -0,0 +1,9 @@ +Long: netrc-optional +Help: Use either .netrc or URL +Mutexed: netrc +See-also: netrc-file +Category: curl +Example: --netrc-optional $URL +--- +Very similar to --netrc, but this option makes the .netrc usage **optional** +and not mandatory as the --netrc option does. diff --git a/docs/cmdline-opts/netrc.d b/docs/cmdline-opts/netrc.d new file mode 100644 index 0000000000000000000000000000000000000000..21e33a164a804f72908a650537ead7ccc4f1c3de --- /dev/null +++ b/docs/cmdline-opts/netrc.d @@ -0,0 +1,19 @@ +Long: netrc +Short: n +Help: Must read .netrc for user name and password +Category: curl +Example: --netrc $URL +--- +Makes curl scan the *.netrc* (*_netrc* 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 +*netrc(5)* and *ftp(1)* for details on the file format. Curl will not +complain if that file doesn't have the right permissions (it should be +neither world- nor group-readable). The environment variable "HOME" is used +to find the home directory. + +A quick and very simple example of how to setup a *.netrc* 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" diff --git a/docs/cmdline-opts/next.d b/docs/cmdline-opts/next.d new file mode 100644 index 0000000000000000000000000000000000000000..bcbad68e58a5589707a5fea0374e5d1b5d3ea595 --- /dev/null +++ b/docs/cmdline-opts/next.d @@ -0,0 +1,25 @@ +Short: : +Long: next +Tags: +Protocols: +Added: 7.36.0 +Magic: divider +Help: Make next URL use its separate set of options +Category: curl +Example: $URL --next -d postthis www2.example.com +Example: -I $URL --next https://example.net/ +--- +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. + +--next will reset all local options and only global ones will have their +values survive over to the operation following the --next instruction. Global +options include --verbose, --trace, --trace-ascii and --fail-early. + +For example, you can do both a GET and a POST in a single command line: + +.nf + curl www1.example.com --next -d postthis www2.example.com +.fi diff --git a/docs/cmdline-opts/no-alpn.d b/docs/cmdline-opts/no-alpn.d new file mode 100644 index 0000000000000000000000000000000000000000..bc620763235414806f9bf8dc777bf152e606eb2a --- /dev/null +++ b/docs/cmdline-opts/no-alpn.d @@ -0,0 +1,13 @@ +Long: no-alpn +Tags: HTTP/2 +Protocols: HTTPS +Added: 7.36.0 +See-also: no-npn http2 +Requires: TLS +Help: Disable the ALPN TLS extension +Category: tls http +Example: --no-alpn $URL +--- +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. diff --git a/docs/cmdline-opts/no-buffer.d b/docs/cmdline-opts/no-buffer.d new file mode 100644 index 0000000000000000000000000000000000000000..fe8da4e9645e33e3ca862ef28c50f11733ee919a --- /dev/null +++ b/docs/cmdline-opts/no-buffer.d @@ -0,0 +1,13 @@ +Long: no-buffer +Short: N +Help: Disable buffering of the output stream +Category: curl +Example: --no-buffer $URL +--- +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 +--buffer to enforce the buffering. diff --git a/docs/cmdline-opts/no-keepalive.d b/docs/cmdline-opts/no-keepalive.d new file mode 100644 index 0000000000000000000000000000000000000000..a264b7ac586c466405520e97e63852fc21278e44 --- /dev/null +++ b/docs/cmdline-opts/no-keepalive.d @@ -0,0 +1,10 @@ +Long: no-keepalive +Help: Disable TCP keepalive on the connection +Category: connection +Example: --no-keepalive $URL +--- +Disables the use of keepalive messages on the TCP connection. curl otherwise +enables them by default. + +Note that this is the negated option name documented. You can thus use +--keepalive to enforce keepalive. diff --git a/docs/cmdline-opts/no-npn.d b/docs/cmdline-opts/no-npn.d new file mode 100644 index 0000000000000000000000000000000000000000..7a9239d361c6b2d554167f8acf5fb2b35de881af --- /dev/null +++ b/docs/cmdline-opts/no-npn.d @@ -0,0 +1,14 @@ +Long: no-npn +Tags: Versions HTTP/2 +Protocols: HTTPS +Added: 7.36.0 +Mutexed: +See-also: no-alpn http2 +Requires: TLS +Help: Disable the NPN TLS extension +Category: tls http +Example: --no-npn $URL +--- +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. diff --git a/docs/cmdline-opts/no-progress-meter.d b/docs/cmdline-opts/no-progress-meter.d new file mode 100644 index 0000000000000000000000000000000000000000..9c7413eeb9d160bf857ce854b4d5618970bbdbf8 --- /dev/null +++ b/docs/cmdline-opts/no-progress-meter.d @@ -0,0 +1,12 @@ +Long: no-progress-meter +Help: Do not show the progress meter +See-also: verbose silent +Added: 7.67.0 +Category: verbose +Example: --no-progress-meter -o store $URL +--- +Option to switch off the progress meter output without muting or otherwise +affecting warning and informational messages like --silent does. + +Note that this is the negated option name documented. You can thus use +--progress-meter to enable the progress meter again. diff --git a/docs/cmdline-opts/no-sessionid.d b/docs/cmdline-opts/no-sessionid.d new file mode 100644 index 0000000000000000000000000000000000000000..70a32210ecddc3fa8664f5a3a6acda6161f75b08 --- /dev/null +++ b/docs/cmdline-opts/no-sessionid.d @@ -0,0 +1,15 @@ +Long: no-sessionid +Help: Disable SSL session-ID reusing +Protocols: TLS +Added: 7.16.0 +Category: tls +Example: --no-sessionid $URL +--- +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. + +Note that this is the negated option name documented. You can thus use +--sessionid to enforce session-ID caching. diff --git a/docs/cmdline-opts/noproxy.d b/docs/cmdline-opts/noproxy.d new file mode 100644 index 0000000000000000000000000000000000000000..ee0978e03997f5c0781658b75e2197b45dd4ce17 --- /dev/null +++ b/docs/cmdline-opts/noproxy.d @@ -0,0 +1,17 @@ +Long: noproxy +Arg: +Help: List of hosts which do not use proxy +Added: 7.19.4 +Category: proxy +Example: --noproxy "www.example" $URL +--- +Comma-separated list of hosts for which not to 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. + +Since 7.53.0, This option overrides the environment variables that disable the +proxy ('no_proxy' and 'NO_PROXY'). If there's an environment variable +disabling a proxy, you can set the noproxy list to \&"" to override it. diff --git a/docs/cmdline-opts/ntlm-wb.d b/docs/cmdline-opts/ntlm-wb.d new file mode 100644 index 0000000000000000000000000000000000000000..890137062cc7cbaef747c74ac26c40acc6b82c54 --- /dev/null +++ b/docs/cmdline-opts/ntlm-wb.d @@ -0,0 +1,9 @@ +Long: ntlm-wb +Help: Use HTTP NTLM authentication with winbind +Protocols: HTTP +See-also: ntlm proxy-ntlm +Category: auth http +Example: --ntlm-wb -u user:password $URL +--- +Enables NTLM much in the style --ntlm does, but hand over the authentication +to the separate binary ntlmauth application that is executed when needed. diff --git a/docs/cmdline-opts/ntlm.d b/docs/cmdline-opts/ntlm.d new file mode 100644 index 0000000000000000000000000000000000000000..5a50632678b26a1c002fadfff7b481d29d7b9a73 --- /dev/null +++ b/docs/cmdline-opts/ntlm.d @@ -0,0 +1,20 @@ +Long: ntlm +Help: Use HTTP NTLM authentication +Mutexed: basic negotiate digest anyauth +See-also: proxy-ntlm +Protocols: HTTP +Requires: TLS +Category: auth http +Example: --ntlm -u user:password $URL +--- +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 +--proxy-ntlm. + +If this option is used several times, only the first one is used. diff --git a/docs/cmdline-opts/oauth2-bearer.d b/docs/cmdline-opts/oauth2-bearer.d new file mode 100644 index 0000000000000000000000000000000000000000..1662a366cd669fbc18db1e6296eab9abea518aa2 --- /dev/null +++ b/docs/cmdline-opts/oauth2-bearer.d @@ -0,0 +1,14 @@ +Long: oauth2-bearer +Help: OAuth 2 Bearer Token +Arg: +Protocols: IMAP POP3 SMTP HTTP +Category: auth +Example: --oauth2-bearer "mF_9.B5f-4.1JqM" $URL +--- +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 --url or --user 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. diff --git a/docs/cmdline-opts/output-dir.d b/docs/cmdline-opts/output-dir.d new file mode 100644 index 0000000000000000000000000000000000000000..1664f4590f3a8ebe05660299789e4a61b36958fe --- /dev/null +++ b/docs/cmdline-opts/output-dir.d @@ -0,0 +1,20 @@ +Long: output-dir +Arg: +Help: Directory to save files in +Added: 7.73.0 +See-also: remote-name remote-header-name +Category: curl +Example: --output-dir "tmp" -O $URL +--- + +This option specifies the directory in which files should be stored, when +--remote-name or --output are used. + +The given output directory is used for all URLs and output options on the +command line, up until the first --next. + +If the specified target directory doesn't exist, the operation will fail +unless --create-dirs is also used. + +If this option is used multiple times, the last specified directory will be +used. diff --git a/docs/cmdline-opts/output.d b/docs/cmdline-opts/output.d new file mode 100644 index 0000000000000000000000000000000000000000..ce9749d5db7c768ec7ced5ad476b55b012c297de --- /dev/null +++ b/docs/cmdline-opts/output.d @@ -0,0 +1,45 @@ +Long: output +Arg: +Short: o +Help: Write to file instead of stdout +See-also: remote-name remote-name-all remote-header-name +Category: important curl +Example: -o file $URL +Example: "http://{one,two}.example.com" -o "file_#1.txt" +Example: "http://{site,host}.host[1-5].com" -o "#1_#2" +Example: -o file $URL -o file2 https://example.net +--- +Write output to instead of stdout. If you are using {} or [] to fetch +multiple documents, you should quote the URL and 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}.example.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. For +example, if you specify two URLs on the same command line, you can use it like +this: + + curl -o aa example.com -o bb example.net + +and the order of the -o options and the URLs doesn't matter, just that the +first -o is for the first URL and so on, so the above command line can also be +written as + + curl example.com example.net -o aa -o bb + +See also the --create-dirs option to create the local directories +dynamically. Specifying the output as '-' (a single dash) will force the +output to be done to stdout. + +To suppress response bodies, you can redirect output to /dev/null: + + curl example.com -o /dev/null + +Or for Windows use nul: + + curl example.com -o nul diff --git a/docs/cmdline-opts/parallel-immediate.d b/docs/cmdline-opts/parallel-immediate.d new file mode 100644 index 0000000000000000000000000000000000000000..4f7468de658df107006bf977b923e37c91b8cced --- /dev/null +++ b/docs/cmdline-opts/parallel-immediate.d @@ -0,0 +1,14 @@ +Long: parallel-immediate +Help: Do not wait for multiplexing (with --parallel) +Added: 7.68.0 +See-also: parallel parallel-max +Category: connection curl +Example: --parallel-immediate -Z $URL -o file1 $URL -o file2 +--- +When doing parallel transfers, this option will instruct curl that it should +rather prefer opening up more connections in parallel at once rather than +waiting to see if new transfers can be added as multiplexed streams on another +connection. + +This option is global and does not need to be specified for each use of +--next. diff --git a/docs/cmdline-opts/parallel-max.d b/docs/cmdline-opts/parallel-max.d new file mode 100644 index 0000000000000000000000000000000000000000..1f22fcb7d23af9ea5033048fceccabe10b545455 --- /dev/null +++ b/docs/cmdline-opts/parallel-max.d @@ -0,0 +1,15 @@ +Long: parallel-max +Arg: +Help: Maximum concurrency for parallel transfers +Added: 7.66.0 +See-also: parallel +Category: connection curl +Example: --parallel-max 100 -Z $URL ftp://example.com/ +--- +When asked to do parallel transfers, using --parallel, this option controls +the maximum amount of transfers to do simultaneously. + +This option is global and does not need to be specified for each use of +--next. + +The default is 50. diff --git a/docs/cmdline-opts/parallel.d b/docs/cmdline-opts/parallel.d new file mode 100644 index 0000000000000000000000000000000000000000..2a0ca4340fec9c76e634549377741ca2e214b228 --- /dev/null +++ b/docs/cmdline-opts/parallel.d @@ -0,0 +1,12 @@ +Short: Z +Long: parallel +Help: Perform transfers in parallel +Added: 7.66.0 +Category: connection curl +Example: --parallel $URL -o file1 $URL -o file2 +--- +Makes curl perform its transfers in parallel as compared to the regular serial +manner. + +This option is global and does not need to be specified for each use of +--next. diff --git a/docs/cmdline-opts/pass.d b/docs/cmdline-opts/pass.d new file mode 100644 index 0000000000000000000000000000000000000000..58e355827ba4d46b75d4559b923d951261feaa8f --- /dev/null +++ b/docs/cmdline-opts/pass.d @@ -0,0 +1,10 @@ +Long: pass +Arg: +Help: Pass phrase for the private key +Protocols: SSH TLS +Category: ssh tls auth +Example: --pass secret --key file $URL +--- +Passphrase for the private key. + +If this option is used several times, the last one will be used. diff --git a/docs/cmdline-opts/path-as-is.d b/docs/cmdline-opts/path-as-is.d new file mode 100644 index 0000000000000000000000000000000000000000..fb87def947c26d52e56dc22c4a0d5e9b5f1a40ae --- /dev/null +++ b/docs/cmdline-opts/path-as-is.d @@ -0,0 +1,9 @@ +Long: path-as-is +Help: Do not squash .. sequences in URL path +Added: 7.42.0 +Category: curl +Example: --path-as-is https://example.com/../../etc/passwd +--- +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. diff --git a/docs/cmdline-opts/pinnedpubkey.d b/docs/cmdline-opts/pinnedpubkey.d new file mode 100644 index 0000000000000000000000000000000000000000..dc98b29f846adce2aff8ebbc5dec795a72424460 --- /dev/null +++ b/docs/cmdline-opts/pinnedpubkey.d @@ -0,0 +1,35 @@ +Long: pinnedpubkey +Arg: +Help: FILE/HASHES Public key to verify peer against +Protocols: TLS +Category: tls +Example: --pinnedpubkey keyfile $URL +Example: --pinnedpubkey 'sha256//ce118b51897f4452dc' $URL +--- +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. + +PEM/DER support: + +7.39.0: OpenSSL, GnuTLS and GSKit + +7.43.0: NSS and wolfSSL + +7.47.0: mbedtls + +sha256 support: + +7.44.0: OpenSSL, GnuTLS, NSS and wolfSSL + +7.47.0: mbedtls + +Other SSL backends not supported. + +If this option is used several times, the last one will be used. diff --git a/docs/cmdline-opts/post301.d b/docs/cmdline-opts/post301.d new file mode 100644 index 0000000000000000000000000000000000000000..744ef5813ad727324f0066e694ce130911e2e173 --- /dev/null +++ b/docs/cmdline-opts/post301.d @@ -0,0 +1,13 @@ +Long: post301 +Help: Do not switch to GET after following a 301 +Protocols: HTTP +See-also: post302 post303 location +Added: 7.17.1 +Category: http post +Example: --post301 --location -d "data" $URL +--- +Tells curl to respect RFC 7231/6.4.2 and not convert POST requests into GET +requests when following a 301 redirection. The non-RFC behavior 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 --location. diff --git a/docs/cmdline-opts/post302.d b/docs/cmdline-opts/post302.d new file mode 100644 index 0000000000000000000000000000000000000000..2c6d4b615c56f1c85782091e33b2e473a51fa31b --- /dev/null +++ b/docs/cmdline-opts/post302.d @@ -0,0 +1,13 @@ +Long: post302 +Help: Do not switch to GET after following a 302 +Protocols: HTTP +See-also: post301 post303 location +Added: 7.19.1 +Category: http post +Example: --post302 --location -d "data" $URL +--- +Tells curl to respect RFC 7231/6.4.3 and not convert POST requests into GET +requests when following a 302 redirection. The non-RFC behavior 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 --location. diff --git a/docs/cmdline-opts/post303.d b/docs/cmdline-opts/post303.d new file mode 100644 index 0000000000000000000000000000000000000000..a2fec18c4be196187e352ea55635912f4354bae5 --- /dev/null +++ b/docs/cmdline-opts/post303.d @@ -0,0 +1,12 @@ +Long: post303 +Help: Do not switch to GET after following a 303 +Protocols: HTTP +See-also: post302 post301 location +Added: 7.26.0 +Category: http post +Example: --post303 --location -d "data" $URL +--- +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 --location. diff --git a/docs/cmdline-opts/preproxy.d b/docs/cmdline-opts/preproxy.d new file mode 100644 index 0000000000000000000000000000000000000000..c91565c0e78773fe502273b8a5910c736a1e68f1 --- /dev/null +++ b/docs/cmdline-opts/preproxy.d @@ -0,0 +1,24 @@ +Long: preproxy +Arg: [protocol://]host[:port] +Help: Use this proxy first +Added: 7.52.0 +Category: proxy +Example: --preproxy socks5://proxy.example -x http://http.example $URL +--- +Use the specified SOCKS proxy before connecting to an HTTP or HTTPS --proxy. In +such a case curl first connects to the SOCKS proxy and then connects (through +SOCKS) to the HTTP or HTTPS proxy. Hence pre proxy. + +The pre proxy string should 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 will make curl default to SOCKS4. + +If the port number is not specified in the proxy string, it is assumed to be +1080. + +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. + +If this option is used several times, the last one will be used. diff --git a/docs/cmdline-opts/progress-bar.d b/docs/cmdline-opts/progress-bar.d new file mode 100644 index 0000000000000000000000000000000000000000..96ac3009b1ddee438695c757590c2f25ab463fae --- /dev/null +++ b/docs/cmdline-opts/progress-bar.d @@ -0,0 +1,17 @@ +Short: # +Long: progress-bar +Help: Display transfer progress as a bar +Category: verbose +Example: -# -O $URL +--- +Make curl display transfer progress as a simple progress bar instead of the +standard, more informational, meter. + +This progress bar draws a single line of '#' characters across the screen and +shows a percentage if the transfer size is known. For transfers without a +known size, there will be space ship (-=o=-) that moves back and forth but +only while data is being transferred, with a set of flying hash sign symbols on +top. + +This option is global and does not need to be specified for each use of +--next. diff --git a/docs/cmdline-opts/proto-default.d b/docs/cmdline-opts/proto-default.d new file mode 100644 index 0000000000000000000000000000000000000000..a659b840dc5fb701d35e0d6a31fd5298ea21bf9a --- /dev/null +++ b/docs/cmdline-opts/proto-default.d @@ -0,0 +1,16 @@ +Long: proto-default +Help: Use PROTOCOL for any URL missing a scheme +Arg: +Added: 7.45.0 +Category: connection curl +Example: --proto-default https ftp.example.com +--- +Tells curl to use *protocol* for any URL missing a scheme name. + +An unknown or unsupported protocol causes error +*CURLE_UNSUPPORTED_PROTOCOL* (1). + +This option does not change the default proxy protocol (http). + +Without this option set, curl guesses protocol based on the host name, see +--url for details. diff --git a/docs/cmdline-opts/proto-redir.d b/docs/cmdline-opts/proto-redir.d new file mode 100644 index 0000000000000000000000000000000000000000..81d495dd8f3c234ab88b7c75c8b405a89731443e --- /dev/null +++ b/docs/cmdline-opts/proto-redir.d @@ -0,0 +1,20 @@ +Long: proto-redir +Arg: +Help: Enable/disable PROTOCOLS on redirect +Added: 7.20.2 +Category: connection curl +Example: --proto-redir =http,https $URL +--- +Tells curl to limit what protocols it may use on redirect. Protocols denied by +--proto are not overridden by this option. See --proto for how protocols are +represented. + +Example, allow only HTTP and HTTPS on redirect: + + curl --proto-redir -all,http,https http://example.com + +By default curl will allow HTTP, HTTPS, FTP and FTPS on redirect (7.65.2). +Older versions of curl allowed 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 *all* or *+all* +enables all protocols on redirect, including those disabled for security. diff --git a/docs/cmdline-opts/proto.d b/docs/cmdline-opts/proto.d new file mode 100644 index 0000000000000000000000000000000000000000..6ff52c41740f4446016f4b7ffa110e2573cec9d2 --- /dev/null +++ b/docs/cmdline-opts/proto.d @@ -0,0 +1,45 @@ +Long: proto +Arg: +Help: Enable/disable PROTOCOLS +See-also: proto-redir proto-default +Added: 7.20.2 +Category: connection curl +Example: --proto =http,https,sftp $URL +--- +Tells curl to limit what protocols it may use for transfers. 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. diff --git a/docs/cmdline-opts/proxy-anyauth.d b/docs/cmdline-opts/proxy-anyauth.d new file mode 100644 index 0000000000000000000000000000000000000000..80f2b970125cb49fd23521df7377209da6d38491 --- /dev/null +++ b/docs/cmdline-opts/proxy-anyauth.d @@ -0,0 +1,9 @@ +Long: proxy-anyauth +Help: Pick any proxy authentication method +Added: 7.13.2 +See-also: proxy proxy-basic proxy-digest +Category: proxy auth +Example: --proxy-anyauth --proxy-user user:passwd -x proxy $URL +--- +Tells curl to pick a suitable authentication method when communicating with +the given HTTP proxy. This might cause an extra request/response round-trip. diff --git a/docs/cmdline-opts/proxy-basic.d b/docs/cmdline-opts/proxy-basic.d new file mode 100644 index 0000000000000000000000000000000000000000..6d38c733a027578780fb1472922058f6e12fc5d3 --- /dev/null +++ b/docs/cmdline-opts/proxy-basic.d @@ -0,0 +1,9 @@ +Long: proxy-basic +Help: Use Basic authentication on the proxy +See-also: proxy proxy-anyauth proxy-digest +Category: proxy auth +Example: --proxy-basic --proxy-user user:passwd -x proxy $URL +--- +Tells curl to use HTTP Basic authentication when communicating with the given +proxy. Use --basic for enabling HTTP Basic with a remote host. Basic is the +default authentication method curl uses with proxies. diff --git a/docs/cmdline-opts/proxy-cacert.d b/docs/cmdline-opts/proxy-cacert.d new file mode 100644 index 0000000000000000000000000000000000000000..5c3294475804a54ea315888b4ff1b7c46afff06b --- /dev/null +++ b/docs/cmdline-opts/proxy-cacert.d @@ -0,0 +1,9 @@ +Long: proxy-cacert +Help: CA certificate to verify peer against for proxy +Arg: +Added: 7.52.0 +See-also: proxy-capath cacert capath proxy +Category: proxy tls +Example: --proxy-cacert CA-file.txt -x https://proxy $URL +--- +Same as --cacert but used in HTTPS proxy context. diff --git a/docs/cmdline-opts/proxy-capath.d b/docs/cmdline-opts/proxy-capath.d new file mode 100644 index 0000000000000000000000000000000000000000..0429984f2a168adc1914916967309f9a78746350 --- /dev/null +++ b/docs/cmdline-opts/proxy-capath.d @@ -0,0 +1,9 @@ +Long: proxy-capath +Help: CA directory to verify peer against for proxy +Arg: +Added: 7.52.0 +See-also: proxy-cacert proxy capath +Category: proxy tls +Example: --proxy-capath /local/directory -x https://proxy $URL +--- +Same as --capath but used in HTTPS proxy context. diff --git a/docs/cmdline-opts/proxy-cert-type.d b/docs/cmdline-opts/proxy-cert-type.d new file mode 100644 index 0000000000000000000000000000000000000000..2152f537d63f77a0f7277b33fc044777a9206b3e --- /dev/null +++ b/docs/cmdline-opts/proxy-cert-type.d @@ -0,0 +1,8 @@ +Long: proxy-cert-type +Arg: +Added: 7.52.0 +Help: Client certificate type for HTTPS proxy +Category: proxy tls +Example: --proxy-cert-type PEM --proxy-cert file -x https://proxy $URL +--- +Same as --cert-type but used in HTTPS proxy context. diff --git a/docs/cmdline-opts/proxy-cert.d b/docs/cmdline-opts/proxy-cert.d new file mode 100644 index 0000000000000000000000000000000000000000..3cf54b73f30adef8a673f7568104f6b7be89495d --- /dev/null +++ b/docs/cmdline-opts/proxy-cert.d @@ -0,0 +1,8 @@ +Long: proxy-cert +Arg: +Help: Set client certificate for proxy +Added: 7.52.0 +Category: proxy tls +Example: --proxy-cert file -x https://proxy $URL +--- +Same as --cert but used in HTTPS proxy context. diff --git a/docs/cmdline-opts/proxy-ciphers.d b/docs/cmdline-opts/proxy-ciphers.d new file mode 100644 index 0000000000000000000000000000000000000000..b4c358091350502edcbfe1c634ca1fea952b602b --- /dev/null +++ b/docs/cmdline-opts/proxy-ciphers.d @@ -0,0 +1,8 @@ +Long: proxy-ciphers +Arg: +Help: SSL ciphers to use for proxy +Added: 7.52.0 +Category: proxy tls +Example: --proxy-ciphers ECDHE-ECDSA-AES256-CCM8 -x https://proxy $URL +--- +Same as --ciphers but used in HTTPS proxy context. diff --git a/docs/cmdline-opts/proxy-crlfile.d b/docs/cmdline-opts/proxy-crlfile.d new file mode 100644 index 0000000000000000000000000000000000000000..1ac199965f1d2b43b88bf35588a8329bd7a5a7e6 --- /dev/null +++ b/docs/cmdline-opts/proxy-crlfile.d @@ -0,0 +1,8 @@ +Long: proxy-crlfile +Arg: +Help: Set a CRL list for proxy +Added: 7.52.0 +Category: proxy tls +Example: --proxy-crlfile rejects.txt -x https://proxy $URL +--- +Same as --crlfile but used in HTTPS proxy context. diff --git a/docs/cmdline-opts/proxy-digest.d b/docs/cmdline-opts/proxy-digest.d new file mode 100644 index 0000000000000000000000000000000000000000..cc187023683de28f5f582bcc3d44673271a6fbcd --- /dev/null +++ b/docs/cmdline-opts/proxy-digest.d @@ -0,0 +1,8 @@ +Long: proxy-digest +Help: Use Digest authentication on the proxy +See-also: proxy proxy-anyauth proxy-basic +Category: proxy tls +Example: --proxy-digest --proxy-user user:passwd -x proxy $URL +--- +Tells curl to use HTTP Digest authentication when communicating with the given +proxy. Use --digest for enabling HTTP Digest with a remote host. diff --git a/docs/cmdline-opts/proxy-header.d b/docs/cmdline-opts/proxy-header.d new file mode 100644 index 0000000000000000000000000000000000000000..273a773d948eabe7285b111901b7638f5c6a8562 --- /dev/null +++ b/docs/cmdline-opts/proxy-header.d @@ -0,0 +1,28 @@ +Long: proxy-header +Arg:
+Help: Pass custom header(s) to proxy +Protocols: HTTP +Added: 7.37.0 +Category: proxy +Example: --proxy-header "X-First-Name: Joe" -x http://proxy $URL +Example: --proxy-header "User-Agent: surprise" -x http://proxy $URL +Example: --proxy-header "Host:" -x http://proxy $URL +--- +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 --header +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 **not** 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. + +Starting in 7.55.0, this option can take an argument in @filename style, which +then adds a header for each line in the input file. Using @- will make curl +read the header file from stdin. + +This option can be used multiple times to add/replace/remove multiple headers. diff --git a/docs/cmdline-opts/proxy-insecure.d b/docs/cmdline-opts/proxy-insecure.d new file mode 100644 index 0000000000000000000000000000000000000000..3f4f7c18051c34e0b11022b6f103819874a581c0 --- /dev/null +++ b/docs/cmdline-opts/proxy-insecure.d @@ -0,0 +1,7 @@ +Long: proxy-insecure +Help: Do HTTPS proxy connections without verifying the proxy +Added: 7.52.0 +Category: proxy tls +Example: --proxy-insecure -x https://proxy $URL +--- +Same as --insecure but used in HTTPS proxy context. diff --git a/docs/cmdline-opts/proxy-key-type.d b/docs/cmdline-opts/proxy-key-type.d new file mode 100644 index 0000000000000000000000000000000000000000..31f47afa4aba63151b8fb0d2821d172176749754 --- /dev/null +++ b/docs/cmdline-opts/proxy-key-type.d @@ -0,0 +1,8 @@ +Long: proxy-key-type +Arg: +Help: Private key file type for proxy +Added: 7.52.0 +Category: proxy tls +Example: --proxy-key-type DER --proxy-key here -x https://proxy $URL +--- +Same as --key-type but used in HTTPS proxy context. diff --git a/docs/cmdline-opts/proxy-key.d b/docs/cmdline-opts/proxy-key.d new file mode 100644 index 0000000000000000000000000000000000000000..1b9797307a95de61a7ce539a29e2d339bd7f1d79 --- /dev/null +++ b/docs/cmdline-opts/proxy-key.d @@ -0,0 +1,7 @@ +Long: proxy-key +Help: Private key for HTTPS proxy +Arg: +Category: proxy tls +Example: --proxy-key here -x https://proxy $URL +--- +Same as --key but used in HTTPS proxy context. diff --git a/docs/cmdline-opts/proxy-negotiate.d b/docs/cmdline-opts/proxy-negotiate.d new file mode 100644 index 0000000000000000000000000000000000000000..5085a7cb3aa023ad202a3ce26ba4b056f62ddb36 --- /dev/null +++ b/docs/cmdline-opts/proxy-negotiate.d @@ -0,0 +1,10 @@ +Long: proxy-negotiate +Help: Use HTTP Negotiate (SPNEGO) authentication on the proxy +Added: 7.17.1 +See-also: proxy-anyauth proxy-basic +Category: proxy auth +Example: --proxy-negotiate --proxy-user user:passwd -x proxy $URL +--- +Tells curl to use HTTP Negotiate (SPNEGO) authentication when communicating +with the given proxy. Use --negotiate for enabling HTTP Negotiate (SPNEGO) +with a remote host. diff --git a/docs/cmdline-opts/proxy-ntlm.d b/docs/cmdline-opts/proxy-ntlm.d new file mode 100644 index 0000000000000000000000000000000000000000..074b7df85569305af8be633fdd9c84b6e32f7f13 --- /dev/null +++ b/docs/cmdline-opts/proxy-ntlm.d @@ -0,0 +1,8 @@ +Long: proxy-ntlm +Help: Use NTLM authentication on the proxy +See-also: proxy-negotiate proxy-anyauth +Category: proxy auth +Example: --proxy-ntlm --proxy-user user:passwd -x http://proxy $URL +--- +Tells curl to use HTTP NTLM authentication when communicating with the given +proxy. Use --ntlm for enabling NTLM with a remote host. diff --git a/docs/cmdline-opts/proxy-pass.d b/docs/cmdline-opts/proxy-pass.d new file mode 100644 index 0000000000000000000000000000000000000000..b71468413a8a42714fa3451d352a5c40c4e427a3 --- /dev/null +++ b/docs/cmdline-opts/proxy-pass.d @@ -0,0 +1,8 @@ +Long: proxy-pass +Arg: +Help: Pass phrase for the private key for HTTPS proxy +Added: 7.52.0 +Category: proxy tls auth +Example: --proxy-pass secret --proxy-key here -x https://proxy $URL +--- +Same as --pass but used in HTTPS proxy context. diff --git a/docs/cmdline-opts/proxy-pinnedpubkey.d b/docs/cmdline-opts/proxy-pinnedpubkey.d new file mode 100644 index 0000000000000000000000000000000000000000..b7f50a769fdcff6fcc0d106d7d8f1184d2a490f8 --- /dev/null +++ b/docs/cmdline-opts/proxy-pinnedpubkey.d @@ -0,0 +1,19 @@ +Long: proxy-pinnedpubkey +Arg: +Help: FILE/HASHES public key to verify proxy with +Protocols: TLS +Category: proxy tls +Example: --proxy-pinnedpubkey keyfile $URL +Example: --proxy-pinnedpubkey 'sha256//ce118b51897f4452dc' $URL +--- +Tells curl to use the specified public key file (or hashes) to verify the +proxy. 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. + +If this option is used several times, the last one will be used. diff --git a/docs/cmdline-opts/proxy-service-name.d b/docs/cmdline-opts/proxy-service-name.d new file mode 100644 index 0000000000000000000000000000000000000000..fbed175700ac5e13c9b1303696a5a0576a479395 --- /dev/null +++ b/docs/cmdline-opts/proxy-service-name.d @@ -0,0 +1,8 @@ +Long: proxy-service-name +Arg: +Help: SPNEGO proxy service name +Added: 7.43.0 +Category: proxy tls +Example: --proxy-service-name "shrubbery" -x proxy $URL +--- +This option allows you to change the service name for proxy negotiation. diff --git a/docs/cmdline-opts/proxy-ssl-allow-beast.d b/docs/cmdline-opts/proxy-ssl-allow-beast.d new file mode 100644 index 0000000000000000000000000000000000000000..b3e701f05a386648ecc86caba982a6eff4744fb9 --- /dev/null +++ b/docs/cmdline-opts/proxy-ssl-allow-beast.d @@ -0,0 +1,7 @@ +Long: proxy-ssl-allow-beast +Help: Allow security flaw for interop for HTTPS proxy +Added: 7.52.0 +Category: proxy tls +Example: --proxy-ssl-allow-beast -x https://proxy $URL +--- +Same as --ssl-allow-beast but used in HTTPS proxy context. diff --git a/docs/cmdline-opts/proxy-ssl-auto-client-cert.d b/docs/cmdline-opts/proxy-ssl-auto-client-cert.d new file mode 100644 index 0000000000000000000000000000000000000000..7c071d7eca0f2e226a92fc07237234a404178f4d --- /dev/null +++ b/docs/cmdline-opts/proxy-ssl-auto-client-cert.d @@ -0,0 +1,7 @@ +Long: proxy-ssl-auto-client-cert +Help: Use auto client certificate for proxy (Schannel) +Added: 7.77.0 +Category: proxy tls +Example: --proxy-ssl-auto-client-cert -x https://proxy $URL +--- +Same as --ssl-auto-client-cert but used in HTTPS proxy context. diff --git a/docs/cmdline-opts/proxy-tls13-ciphers.d b/docs/cmdline-opts/proxy-tls13-ciphers.d new file mode 100644 index 0000000000000000000000000000000000000000..62578f7f4eb98329852f6bb60391ea9218b866e6 --- /dev/null +++ b/docs/cmdline-opts/proxy-tls13-ciphers.d @@ -0,0 +1,18 @@ +Long: proxy-tls13-ciphers +Arg: +help: TLS 1.3 proxy cipher suites +Protocols: TLS +Category: proxy tls +Example: --proxy-tls13-ciphers TLS_AES_128_GCM_SHA256 -x proxy $URL +--- +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.se/docs/ssl-ciphers.html + +This option is currently used only when curl is built to use OpenSSL 1.1.1 or +later. If you are using a different SSL backend you can try setting TLS 1.3 +cipher suites by using the --proxy-ciphers option. + +If this option is used several times, the last one will be used. diff --git a/docs/cmdline-opts/proxy-tlsauthtype.d b/docs/cmdline-opts/proxy-tlsauthtype.d new file mode 100644 index 0000000000000000000000000000000000000000..c00928ed56454d2d8b7c97c68d090875c65382ae --- /dev/null +++ b/docs/cmdline-opts/proxy-tlsauthtype.d @@ -0,0 +1,8 @@ +Long: proxy-tlsauthtype +Arg: +Help: TLS authentication type for HTTPS proxy +Added: 7.52.0 +Category: proxy tls auth +Example: --proxy-tlsauthtype SRP -x https://proxy $URL +--- +Same as --tlsauthtype but used in HTTPS proxy context. diff --git a/docs/cmdline-opts/proxy-tlspassword.d b/docs/cmdline-opts/proxy-tlspassword.d new file mode 100644 index 0000000000000000000000000000000000000000..89b551d68affcaaaf69cb3d182f2c331e88cf3c3 --- /dev/null +++ b/docs/cmdline-opts/proxy-tlspassword.d @@ -0,0 +1,8 @@ +Long: proxy-tlspassword +Arg: +Help: TLS password for HTTPS proxy +Added: 7.52.0 +Category: proxy tls auth +Example: --proxy-tlspassword passwd -x https://proxy $URL +--- +Same as --tlspassword but used in HTTPS proxy context. diff --git a/docs/cmdline-opts/proxy-tlsuser.d b/docs/cmdline-opts/proxy-tlsuser.d new file mode 100644 index 0000000000000000000000000000000000000000..b3c400ed5d5398cacb6fd11c520f41f227808e5a --- /dev/null +++ b/docs/cmdline-opts/proxy-tlsuser.d @@ -0,0 +1,8 @@ +Long: proxy-tlsuser +Arg: +Help: TLS username for HTTPS proxy +Added: 7.52.0 +Category: proxy tls auth +Example: --proxy-tlsuser smith -x https://proxy $URL +--- +Same as --tlsuser but used in HTTPS proxy context. diff --git a/docs/cmdline-opts/proxy-tlsv1.d b/docs/cmdline-opts/proxy-tlsv1.d new file mode 100644 index 0000000000000000000000000000000000000000..c54782e8f8a6268b1492d7f6db65ca834597b5bc --- /dev/null +++ b/docs/cmdline-opts/proxy-tlsv1.d @@ -0,0 +1,7 @@ +Long: proxy-tlsv1 +Help: Use TLSv1 for HTTPS proxy +Added: 7.52.0 +Category: proxy tls auth +Example: --proxy-tlsv1 -x https://proxy $URL +--- +Same as --tlsv1 but used in HTTPS proxy context. diff --git a/docs/cmdline-opts/proxy-user.d b/docs/cmdline-opts/proxy-user.d new file mode 100644 index 0000000000000000000000000000000000000000..81d29f2ab0efaefb5a0b53eb75416f1be5e4d641 --- /dev/null +++ b/docs/cmdline-opts/proxy-user.d @@ -0,0 +1,20 @@ +Long: proxy-user +Short: U +Arg: +Help: Proxy user and password +Category: proxy auth +Example: --proxy-user name:pwd -x proxy $URL +--- +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 :". + +On systems where it works, curl will hide the given option argument from +process listings. This is not enough to protect credentials from possibly +getting seen by other users on the same system as they will still be visible +for a brief moment before cleared. Such sensitive data should be retrieved +from a file instead or similar and never used in clear text in a command line. + +If this option is used several times, the last one will be used. diff --git a/docs/cmdline-opts/proxy.d b/docs/cmdline-opts/proxy.d new file mode 100644 index 0000000000000000000000000000000000000000..81d9bc9521cac42f7fd3f47f94ac66944d58304b --- /dev/null +++ b/docs/cmdline-opts/proxy.d @@ -0,0 +1,41 @@ +Long: proxy +Short: x +Arg: [protocol://]host[:port] +Help: Use this proxy +Category: proxy +Example: --proxy http://proxy.example $URL +--- +Use the specified proxy. + +The proxy string can be specified with a protocol:// prefix. No protocol +specified or http:// will be treated as HTTP proxy. Use socks4://, socks4a://, +socks5:// or socks5h:// to request a specific SOCKS version to be used. +(The protocol support was added in curl 7.21.7) + +HTTPS proxy support via https:// protocol prefix was added in 7.52.0 for +OpenSSL, GnuTLS and NSS. + +Unrecognized and unsupported proxy protocols cause an error since 7.52.0. +Prior versions may ignore the protocol and use http:// instead. + +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 --proxytunnel 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. diff --git a/docs/cmdline-opts/proxy1.0.d b/docs/cmdline-opts/proxy1.0.d new file mode 100644 index 0000000000000000000000000000000000000000..f74834567524243c4b9f6f7ac3618ce071880302 --- /dev/null +++ b/docs/cmdline-opts/proxy1.0.d @@ -0,0 +1,12 @@ +Long: proxy1.0 +Arg: +Help: Use HTTP/1.0 proxy on given port +Category: proxy +Example: --proxy1.0 -x http://proxy $URL +--- +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 --proxy, is that +attempts to use CONNECT through the proxy will specify an HTTP 1.0 protocol +instead of the default HTTP 1.1. diff --git a/docs/cmdline-opts/proxytunnel.d b/docs/cmdline-opts/proxytunnel.d new file mode 100644 index 0000000000000000000000000000000000000000..712c755a87e58a2b480be1fbfb22958f6b92b4e5 --- /dev/null +++ b/docs/cmdline-opts/proxytunnel.d @@ -0,0 +1,14 @@ +Long: proxytunnel +Short: p +Help: Operate through an HTTP proxy tunnel (using CONNECT) +See-also: proxy +Category: proxy +Example: --proxytunnel -x http://proxy $URL +--- +When an HTTP proxy is used --proxy, this option will make curl tunnel through +the proxy. 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. + +To suppress proxy CONNECT response headers when curl is set to output headers +use --suppress-connect-headers. diff --git a/docs/cmdline-opts/pubkey.d b/docs/cmdline-opts/pubkey.d new file mode 100644 index 0000000000000000000000000000000000000000..c1fb5d8ef30e5451920d7374c13dbc318217a2e6 --- /dev/null +++ b/docs/cmdline-opts/pubkey.d @@ -0,0 +1,16 @@ +Long: pubkey +Arg: +Protocols: SFTP SCP +Help: SSH Public key file name +Category: sftp scp auth +Example: --pubkey file.pub sftp://example.com/ +--- +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.) diff --git a/docs/cmdline-opts/quote.d b/docs/cmdline-opts/quote.d new file mode 100644 index 0000000000000000000000000000000000000000..2707c87dd7f87d944cc22b09066f61ecac6c49e4 --- /dev/null +++ b/docs/cmdline-opts/quote.d @@ -0,0 +1,68 @@ +Long: quote +Arg: +Short: Q +Help: Send command(s) to server before transfer +Protocols: FTP SFTP +Category: ftp sftp +Example: --quote "DELE file" ftp://example.com/foo +--- +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. + +By default curl will stop at first failure. To make curl continue even if the +command fails, prefix the command with an asterisk (*). Otherwise, 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. + +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 "atime date file" +The atime command sets the last access time of the file named by the file +operand. The can be all sorts of date strings, see the +*curl_getdate(3)* man page for date expression details. (Added in 7.73.0) +.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 "mtime date file" +The mtime command sets the last modification time of the file named by the +file operand. The can be all sorts of date strings, see the +*curl_getdate(3)* man page for date expression details. (Added in 7.73.0) +.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 diff --git a/docs/cmdline-opts/random-file.d b/docs/cmdline-opts/random-file.d new file mode 100644 index 0000000000000000000000000000000000000000..a207c1e1ba773b625fd39c4f19b2d45b02959955 --- /dev/null +++ b/docs/cmdline-opts/random-file.d @@ -0,0 +1,9 @@ +Long: random-file +Arg: +Help: File for reading random data from +Category: misc +Example: --random-file rubbish $URL +--- +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 --egd-file option. diff --git a/docs/cmdline-opts/range.d b/docs/cmdline-opts/range.d new file mode 100644 index 0000000000000000000000000000000000000000..0637f8fc2be43d4ee725188e009c433792311a57 --- /dev/null +++ b/docs/cmdline-opts/range.d @@ -0,0 +1,49 @@ +Long: range +Short: r +Help: Retrieve only the bytes within RANGE +Arg: +Protocols: HTTP FTP SFTP FILE +Category: http ftp sftp file +Example: --range 22-44 $URL +--- +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 +.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, which will be returned as-is by curl! Parsing or otherwise +transforming this response is the responsibility of the caller. + +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. diff --git a/docs/cmdline-opts/raw.d b/docs/cmdline-opts/raw.d new file mode 100644 index 0000000000000000000000000000000000000000..c44d33f5cc5f970b7f79a3d9005314180b06d4b2 --- /dev/null +++ b/docs/cmdline-opts/raw.d @@ -0,0 +1,9 @@ +Long: raw +Help: Do HTTP "raw"; no transfer decoding +Added: 7.16.2 +Protocols: HTTP +Category: http +Example: --raw $URL +--- +When used, it disables all internal HTTP decoding of content or transfer +encodings and instead makes them passed on unaltered, raw. diff --git a/docs/cmdline-opts/referer.d b/docs/cmdline-opts/referer.d new file mode 100644 index 0000000000000000000000000000000000000000..3f6b7c7e12a535f588fe402e3f32c491edd54dc5 --- /dev/null +++ b/docs/cmdline-opts/referer.d @@ -0,0 +1,18 @@ +Long: referer +Short: e +Arg: +Protocols: HTTP +Help: Referrer URL +See-also: user-agent header +Category: http +Example: --referer "https://fake.example" $URL +Example: --referer "https://fake.example;auto" -L $URL +Example: --referer ";auto" -L $URL +--- +Sends the "Referrer Page" information to the HTTP server. This can also be set +with the --header flag of course. When used with --location 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. diff --git a/docs/cmdline-opts/remote-header-name.d b/docs/cmdline-opts/remote-header-name.d new file mode 100644 index 0000000000000000000000000000000000000000..6e0b98bd1fc94c0197d3a255d98cc3efffc3ad38 --- /dev/null +++ b/docs/cmdline-opts/remote-header-name.d @@ -0,0 +1,21 @@ +Long: remote-header-name +Short: J +Protocols: HTTP +Help: Use the header-provided filename +Category: output +Example: -OJ https://example.com/file +--- +This option tells the --remote-name 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. + +**WARNING**: 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. diff --git a/docs/cmdline-opts/remote-name-all.d b/docs/cmdline-opts/remote-name-all.d new file mode 100644 index 0000000000000000000000000000000000000000..e27bd5f48d76123061dd33e5bf78d6ea0d0f7da3 --- /dev/null +++ b/docs/cmdline-opts/remote-name-all.d @@ -0,0 +1,10 @@ +Long: remote-name-all +Help: Use the remote file name for all URLs +Added: 7.19.0 +Category: output +Example: --remote-name-all ftp://example.com/file1 ftp://example.com/file2 +--- +This option changes the default action for all given URLs to be dealt with as +if --remote-name were used for each one. So if you want to disable that for a +specific URL after --remote-name-all has been used, you must use "-o -" or +--no-remote-name. diff --git a/docs/cmdline-opts/remote-name.d b/docs/cmdline-opts/remote-name.d new file mode 100644 index 0000000000000000000000000000000000000000..68928794b57e18c6a0a33fd7156c3be7842b1466 --- /dev/null +++ b/docs/cmdline-opts/remote-name.d @@ -0,0 +1,23 @@ +Long: remote-name +Short: O +Help: Write output to a file named as the remote file +Category: important output +Example: -O https://example.com/filename +--- +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 --remote-header-name 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. diff --git a/docs/cmdline-opts/remote-time.d b/docs/cmdline-opts/remote-time.d new file mode 100644 index 0000000000000000000000000000000000000000..9c463ae81986da238ca899b384462d9eaf5508d5 --- /dev/null +++ b/docs/cmdline-opts/remote-time.d @@ -0,0 +1,9 @@ +Long: remote-time +Short: R +Help: Set the remote file's time on the local output +Category: output +Example: --remote-time -o foo $URL +--- +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. diff --git a/docs/cmdline-opts/request-target.d b/docs/cmdline-opts/request-target.d new file mode 100644 index 0000000000000000000000000000000000000000..5f9e475514d79fd59e58f2cd7534d8419321028f --- /dev/null +++ b/docs/cmdline-opts/request-target.d @@ -0,0 +1,12 @@ +Long: request-target +Arg: +Help: Specify the target for this request +Protocols: HTTP +Added: 7.55.0 +Category: http +Example: --request-target "*" -X OPTIONS $URL +--- +Tells curl to use an alternative "target" (path) instead of using the path as +provided in the URL. Particularly useful when wanting to issue HTTP requests +without leading slash or other data that doesn't follow the regular URL +pattern, like "OPTIONS *". diff --git a/docs/cmdline-opts/request.d b/docs/cmdline-opts/request.d new file mode 100644 index 0000000000000000000000000000000000000000..0db0bc9f7700a012c1339d560fb698f8c8752af9 --- /dev/null +++ b/docs/cmdline-opts/request.d @@ -0,0 +1,42 @@ +Long: request +Short: X +Arg: +Help: Specify request command to use +Category: connection +Example: -X "DELETE" $URL +Example: -X NLST ftp://example.com/ +--- +(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 --head option. + +The method string you set with --request will be used for all requests, which +if you for example use --location 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. diff --git a/docs/cmdline-opts/resolve.d b/docs/cmdline-opts/resolve.d new file mode 100644 index 0000000000000000000000000000000000000000..6464c42fb511acca6884de8f18ecd876cd02724d --- /dev/null +++ b/docs/cmdline-opts/resolve.d @@ -0,0 +1,37 @@ +Long: resolve +Arg: <[+]host:port:addr[,addr]...> +Help: Resolve the host+port to this address +Added: 7.21.3 +Category: connection +Example: --resolve example.com:443:127.0.0.1 $URL +--- +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. + +By specifying '*' as host you can tell curl to resolve any host and specific +port pair to the specified address. Wildcard is resolved last so any --resolve +with a specific host and port will be used first. + +The provided address set by this option will be used even if --ipv4 or --ipv6 +is set to make curl use another IP version. + +By prefixing the host with a '+' you can make the entry time out after curl's +default timeout (1 minute). Note that this will only make sense for long +running parallel transfers with a lot of files. In such cases, if this option +is used curl will try to resolve the host as it normally would once the +timeout has expired. + +Support for providing the IP address within [brackets] was added in 7.57.0. + +Support for providing multiple IP addresses per entry was added in 7.59.0. + +Support for resolving with wildcard was added in 7.64.0. + +Support for the '+' prefix was was added in 7.75.0. + +This option can be used many times to add many host names to resolve. diff --git a/docs/cmdline-opts/retry-all-errors.d b/docs/cmdline-opts/retry-all-errors.d new file mode 100644 index 0000000000000000000000000000000000000000..5cab5ddaafa1e3b857362324e2a8058ca9ce2e39 --- /dev/null +++ b/docs/cmdline-opts/retry-all-errors.d @@ -0,0 +1,30 @@ +Long: retry-all-errors +Help: Retry all errors (use with --retry) +Added: 7.71.0 +Category: curl +Example: --retry-all-errors $URL +--- +Retry on any error. This option is used together with --retry. + +This option is the "sledgehammer" of retrying. Do not use this option by +default (eg in curlrc), there may be unintended consequences such as sending or +receiving duplicate data. Do not use with redirected input or output. You'd be +much better off handling your unique problems in shell script. Please read the +example below. + +**WARNING**: For server compatibility curl attempts to retry failed flaky +transfers as close as possible to how they were started, but this is not +possible with redirected input or output. For example, before retrying it +removes output data from a failed partial transfer that was written to an +output file. However this is not true of data redirected to a | pipe or > +file, which are not reset. We strongly suggest don't parse or record output +via redirect in combination with this option, since you may receive duplicate +data. + +By default curl will not error on an HTTP response code that indicates an HTTP +error, if the transfer was successful. For example, if a server replies 404 +Not Found and the reply is fully received then that is not an error. When +--retry is used then curl will retry on some HTTP response codes that indicate +transient HTTP errors, but that does not include most 4xx response codes such +as 404. If you want to retry on all response codes that indicate HTTP errors +(4xx and 5xx) then combine with --fail. diff --git a/docs/cmdline-opts/retry-connrefused.d b/docs/cmdline-opts/retry-connrefused.d new file mode 100644 index 0000000000000000000000000000000000000000..ad079e09626614b92a934b98570d9976a2b65682 --- /dev/null +++ b/docs/cmdline-opts/retry-connrefused.d @@ -0,0 +1,8 @@ +Long: retry-connrefused +Help: Retry on connection refused (use with --retry) +Added: 7.52.0 +Category: curl +Example: --retry-connrefused --retry $URL +--- +In addition to the other conditions, consider ECONNREFUSED as a transient +error too for --retry. This option is used together with --retry. diff --git a/docs/cmdline-opts/retry-delay.d b/docs/cmdline-opts/retry-delay.d new file mode 100644 index 0000000000000000000000000000000000000000..28391290444676f12f491508db55e747bc3bdf61 --- /dev/null +++ b/docs/cmdline-opts/retry-delay.d @@ -0,0 +1,13 @@ +Long: retry-delay +Arg: +Help: Wait time between retries +Added: 7.12.3 +Category: curl +Example: --retry-delay 5 --retry $URL +--- +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 --retry is also +used. Setting this delay to zero will make curl use the default backoff time. + +If this option is used several times, the last one will be used. diff --git a/docs/cmdline-opts/retry-max-time.d b/docs/cmdline-opts/retry-max-time.d new file mode 100644 index 0000000000000000000000000000000000000000..acccff5d415035599e5096476930c3eb92e371ff --- /dev/null +++ b/docs/cmdline-opts/retry-max-time.d @@ -0,0 +1,15 @@ +Long: retry-max-time +Arg: +Help: Retry only within this period +Added: 7.12.3 +Category: curl +Example: --retry-max-time 30 --retry 10 $URL +--- +The retry timer is reset before the first transfer attempt. Retries will be +done as usual (see --retry) 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 --max-time. Set this option to +zero to not timeout retries. + +If this option is used several times, the last one will be used. diff --git a/docs/cmdline-opts/retry.d b/docs/cmdline-opts/retry.d new file mode 100644 index 0000000000000000000000000000000000000000..6238383fe36fb595b5fd57fbd32f593175e7feae --- /dev/null +++ b/docs/cmdline-opts/retry.d @@ -0,0 +1,23 @@ +Long: retry +Arg: +Added: 7.12.3 +Help: Retry request if transient problems occur +Category: curl +Example: --retry 7 $URL +--- +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 408, 429, 500, 502, 503 or 504 +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 --retry-delay you disable this exponential backoff algorithm. See also +--retry-max-time to limit the total time allowed for retries. + +Since curl 7.66.0, curl will comply with the Retry-After: response header if +one was present to know when to issue the next retry. + +If this option is used several times, the last one will be used. diff --git a/docs/cmdline-opts/sasl-authzid.d b/docs/cmdline-opts/sasl-authzid.d new file mode 100644 index 0000000000000000000000000000000000000000..9065bd5ecb22ccc1aface64fa6b0b16fb4d24420 --- /dev/null +++ b/docs/cmdline-opts/sasl-authzid.d @@ -0,0 +1,14 @@ +Long: sasl-authzid +Arg: +Help: Identity for SASL PLAIN authentication +Added: 7.66.0 +Category: auth +Example: --sasl-authzid zid imap://example.com/ +--- +Use this authorisation identity (authzid), during SASL PLAIN authentication, +in addition to the authentication identity (authcid) as specified by --user. + +If the option isn't specified, the server will derive the authzid from the +authcid, but if specified, and depending on the server implementation, it may +be used to access another user's inbox, that the user has been granted access +to, or a shared mailbox for example. diff --git a/docs/cmdline-opts/sasl-ir.d b/docs/cmdline-opts/sasl-ir.d new file mode 100644 index 0000000000000000000000000000000000000000..5004306a4addde20178e22189890e4e54559e18d --- /dev/null +++ b/docs/cmdline-opts/sasl-ir.d @@ -0,0 +1,7 @@ +Long: sasl-ir +Help: Enable initial response in SASL authentication +Added: 7.31.0 +Category: auth +Example: --sasl-ir imap://example.com/ +--- +Enable initial response in SASL authentication. diff --git a/docs/cmdline-opts/service-name.d b/docs/cmdline-opts/service-name.d new file mode 100644 index 0000000000000000000000000000000000000000..3a5559bc865786c910dacec9234b1dc40c1ccf40 --- /dev/null +++ b/docs/cmdline-opts/service-name.d @@ -0,0 +1,10 @@ +Long: service-name +Help: SPNEGO service name +Arg: +Added: 7.43.0 +Category: misc +Example: --service-name sockd/server $URL +--- +This option allows you to change the service name for SPNEGO. + +Examples: --negotiate --service-name sockd would use sockd/server-name. diff --git a/docs/cmdline-opts/show-error.d b/docs/cmdline-opts/show-error.d new file mode 100644 index 0000000000000000000000000000000000000000..e8b2177129e7c3d1e344bcfad61a61a27685d720 --- /dev/null +++ b/docs/cmdline-opts/show-error.d @@ -0,0 +1,11 @@ +Long: show-error +Short: S +Help: Show error even when -s is used +See-also: no-progress-meter +Category: curl +Example: --show-error --silent $URL +--- +When used with --silent, it makes curl show an error message if it fails. + +This option is global and does not need to be specified for each use of +--next. diff --git a/docs/cmdline-opts/silent.d b/docs/cmdline-opts/silent.d new file mode 100644 index 0000000000000000000000000000000000000000..7122c542eb2bf0237e80f5cea5c835a64df4e0ff --- /dev/null +++ b/docs/cmdline-opts/silent.d @@ -0,0 +1,13 @@ +Long: silent +Short: s +Help: Silent mode +See-also: verbose stderr no-progress-meter +Category: important verbose +Example: -s $URL +--- +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. + +Use --show-error in addition to this option to disable progress meter but +still show error messages. diff --git a/docs/cmdline-opts/socks4.d b/docs/cmdline-opts/socks4.d new file mode 100644 index 0000000000000000000000000000000000000000..1cae1e1fcec0379753abeae08b6dbb00be84ba06 --- /dev/null +++ b/docs/cmdline-opts/socks4.d @@ -0,0 +1,22 @@ +Long: socks4 +Arg: +Help: SOCKS4 proxy on given host + port +Added: 7.15.2 +Category: proxy +Example: --socks4 hostname:4096 $URL +--- +Use the specified SOCKS4 proxy. If the port number is not specified, it is +assumed at port 1080. Using this socket type make curl resolve the host name +and passing the address on to the proxy. + +This option overrides any previous use of --proxy, as they are mutually +exclusive. + +Since 7.21.7, this option is superfluous since you can specify a socks4 proxy +with --proxy using a socks4:// protocol prefix. + +Since 7.52.0, --preproxy can be used to specify a SOCKS proxy at the same time +--proxy is used with an HTTP/HTTPS proxy. In such a case curl first connects to +the SOCKS proxy and then connects (through SOCKS) to the HTTP or HTTPS proxy. + +If this option is used several times, the last one will be used. diff --git a/docs/cmdline-opts/socks4a.d b/docs/cmdline-opts/socks4a.d new file mode 100644 index 0000000000000000000000000000000000000000..8edefdd1b626aa59fa58367168d6fe68a6e66839 --- /dev/null +++ b/docs/cmdline-opts/socks4a.d @@ -0,0 +1,21 @@ +Long: socks4a +Arg: +Help: SOCKS4a proxy on given host + port +Added: 7.18.0 +Category: proxy +Example: --socks4a hostname:4096 $URL +--- +Use the specified SOCKS4a proxy. If the port number is not specified, it is +assumed at port 1080. This asks the proxy to resolve the host name. + +This option overrides any previous use of --proxy, as they are mutually +exclusive. + +Since 7.21.7, this option is superfluous since you can specify a socks4a proxy +with --proxy using a socks4a:// protocol prefix. + +Since 7.52.0, --preproxy can be used to specify a SOCKS proxy at the same time +--proxy is used with an HTTP/HTTPS proxy. In such a case curl first connects to +the SOCKS proxy and then connects (through SOCKS) to the HTTP or HTTPS proxy. + +If this option is used several times, the last one will be used. diff --git a/docs/cmdline-opts/socks5-basic.d b/docs/cmdline-opts/socks5-basic.d new file mode 100644 index 0000000000000000000000000000000000000000..f32e0bf3ea4e114d42821e4dbada1c998e1192f9 --- /dev/null +++ b/docs/cmdline-opts/socks5-basic.d @@ -0,0 +1,9 @@ +Long: socks5-basic +Help: Enable username/password auth for SOCKS5 proxies +Added: 7.55.0 +Category: proxy auth +Example: --socks5-basic --socks5 hostname:4096 $URL +--- +Tells curl to use username/password authentication when connecting to a SOCKS5 +proxy. The username/password authentication is enabled by default. Use +--socks5-gssapi to force GSS-API authentication to SOCKS5 proxies. diff --git a/docs/cmdline-opts/socks5-gssapi-nec.d b/docs/cmdline-opts/socks5-gssapi-nec.d new file mode 100644 index 0000000000000000000000000000000000000000..73cac7a2265bd17483d9ddd13b3731207f352e03 --- /dev/null +++ b/docs/cmdline-opts/socks5-gssapi-nec.d @@ -0,0 +1,10 @@ +Long: socks5-gssapi-nec +Help: Compatibility with NEC SOCKS5 server +Added: 7.19.4 +Category: proxy auth +Example: --socks5-gssapi-nec --socks5 hostname:4096 $URL +--- +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 --socks5-gssapi-nec allows the +unprotected exchange of the protection mode negotiation. diff --git a/docs/cmdline-opts/socks5-gssapi-service.d b/docs/cmdline-opts/socks5-gssapi-service.d new file mode 100644 index 0000000000000000000000000000000000000000..451be8e2d1a0b55709f30e90616e03bfbcbd80d7 --- /dev/null +++ b/docs/cmdline-opts/socks5-gssapi-service.d @@ -0,0 +1,14 @@ +Long: socks5-gssapi-service +Arg: +Help: SOCKS5 proxy service name for GSS-API +Added: 7.19.4 +Category: proxy auth +Example: --socks5-gssapi-service sockd --socks5 hostname:4096 $URL +--- +The default service name for a socks server is rcmd/server-fqdn. This option +allows you to change it. + +Examples: --socks5 proxy-name --socks5-gssapi-service sockd would use +sockd/proxy-name --socks5 proxy-name --socks5-gssapi-service sockd/real-name +would use sockd/real-name for cases where the proxy-name does not match the +principal name. diff --git a/docs/cmdline-opts/socks5-gssapi.d b/docs/cmdline-opts/socks5-gssapi.d new file mode 100644 index 0000000000000000000000000000000000000000..2ce806955b42aeee941e0ba31151acc5308763ea --- /dev/null +++ b/docs/cmdline-opts/socks5-gssapi.d @@ -0,0 +1,10 @@ +Long: socks5-gssapi +Help: Enable GSS-API auth for SOCKS5 proxies +Added: 7.55.0 +Category: proxy auth +Example: --socks5-gssapi --socks5 hostname:4096 $URL +--- +Tells curl to use GSS-API authentication when connecting to a SOCKS5 proxy. +The GSS-API authentication is enabled by default (if curl is compiled with +GSS-API support). Use --socks5-basic to force username/password authentication +to SOCKS5 proxies. diff --git a/docs/cmdline-opts/socks5-hostname.d b/docs/cmdline-opts/socks5-hostname.d new file mode 100644 index 0000000000000000000000000000000000000000..729a7bf85902754d7080fe42d46f02d777e3df90 --- /dev/null +++ b/docs/cmdline-opts/socks5-hostname.d @@ -0,0 +1,21 @@ +Long: socks5-hostname +Arg: +Help: SOCKS5 proxy, pass host name to proxy +Added: 7.18.0 +Category: proxy +Example: --socks5-hostname proxy.example:7000 $URL +--- +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. + +This option overrides any previous use of --proxy, as they are mutually +exclusive. + +Since 7.21.7, this option is superfluous since you can specify a socks5 +hostname proxy with --proxy using a socks5h:// protocol prefix. + +Since 7.52.0, --preproxy can be used to specify a SOCKS proxy at the same time +--proxy is used with an HTTP/HTTPS proxy. In such a case curl first connects to +the SOCKS proxy and then connects (through SOCKS) to the HTTP or HTTPS proxy. + +If this option is used several times, the last one will be used. diff --git a/docs/cmdline-opts/socks5.d b/docs/cmdline-opts/socks5.d new file mode 100644 index 0000000000000000000000000000000000000000..99c740f885e54405a723bbe1471bd188571458f2 --- /dev/null +++ b/docs/cmdline-opts/socks5.d @@ -0,0 +1,23 @@ +Long: socks5 +Arg: +Help: SOCKS5 proxy on given host + port +Added: 7.18.0 +Category: proxy +Example: --socks5 proxy.example:7000 $URL +--- +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 --proxy, as they are mutually +exclusive. + +Since 7.21.7, this option is superfluous since you can specify a socks5 proxy +with --proxy using a socks5:// protocol prefix. + +Since 7.52.0, --preproxy can be used to specify a SOCKS proxy at the same time +--proxy is used with an HTTP/HTTPS proxy. In such a case curl first connects to +the SOCKS proxy and then connects (through SOCKS) to the HTTP or HTTPS proxy. + +If this option is used several times, the last one will be used. + +This option (as well as --socks4) does not work with IPV6, FTPS or LDAP. diff --git a/docs/cmdline-opts/speed-limit.d b/docs/cmdline-opts/speed-limit.d new file mode 100644 index 0000000000000000000000000000000000000000..7bf8d5fb1b86b0bfa729895cb601566af186274d --- /dev/null +++ b/docs/cmdline-opts/speed-limit.d @@ -0,0 +1,12 @@ +Long: speed-limit +Short: Y +Arg: +Help: Stop transfers slower than this +Category: connection +Example: --speed-limit 300 --speed-time 10 $URL +--- +If a download is slower than this given speed (in bytes per second) for +speed-time seconds it gets aborted. speed-time is set with --speed-time and is +30 if not set. + +If this option is used several times, the last one will be used. diff --git a/docs/cmdline-opts/speed-time.d b/docs/cmdline-opts/speed-time.d new file mode 100644 index 0000000000000000000000000000000000000000..6095214564ea7c2a23a99ddab9d36c6b2ea3e76a --- /dev/null +++ b/docs/cmdline-opts/speed-time.d @@ -0,0 +1,15 @@ +Long: speed-time +Short: y +Arg: +Help: Trigger 'speed-limit' abort after this time +Category: connection +Example: --speed-limit 300 --speed-time 10 $URL +--- +If a download is slower than speed-limit bytes per second during a speed-time +period, the download gets aborted. If speed-time is used, the default +speed-limit will be 1 unless set with --speed-limit. + +This option controls transfers and thus will not affect slow connects etc. If +this is a concern for you, try the --connect-timeout option. + +If this option is used several times, the last one will be used. diff --git a/docs/cmdline-opts/ssl-allow-beast.d b/docs/cmdline-opts/ssl-allow-beast.d new file mode 100644 index 0000000000000000000000000000000000000000..f54cf6416fbec3e46d86e57410aaf0a62fa81d9c --- /dev/null +++ b/docs/cmdline-opts/ssl-allow-beast.d @@ -0,0 +1,13 @@ +Long: ssl-allow-beast +Help: Allow security flaw to improve interop +Added: 7.25.0 +Category: tls +Example: --ssl-allow-beast $URL +--- +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. diff --git a/docs/cmdline-opts/ssl-auto-client-cert.d b/docs/cmdline-opts/ssl-auto-client-cert.d new file mode 100644 index 0000000000000000000000000000000000000000..7581bdff688c18ca02e4bbf099ad3d9235abef15 --- /dev/null +++ b/docs/cmdline-opts/ssl-auto-client-cert.d @@ -0,0 +1,13 @@ +Long: ssl-auto-client-cert +Help: Use auto client certificate (Schannel) +Added: 7.77.0 +See-also: proxy-ssl-auto-client-cert +Category: tls +Example: --ssl-auto-client-cert $URL +--- +Tell libcurl to automatically locate and use a client certificate for +authentication, when requested by the server. This option is only supported +for Schannel (the native Windows SSL library). Prior to 7.77.0 this was the +default behavior in libcurl with Schannel. Since the server can request any +certificate that supports client authentication in the OS certificate store it +could be a privacy violation and unexpected. diff --git a/docs/cmdline-opts/ssl-no-revoke.d b/docs/cmdline-opts/ssl-no-revoke.d new file mode 100644 index 0000000000000000000000000000000000000000..dde77aa113c0a75c4f6584325bcbe331957ecd94 --- /dev/null +++ b/docs/cmdline-opts/ssl-no-revoke.d @@ -0,0 +1,9 @@ +Long: ssl-no-revoke +Help: Disable cert revocation checks (Schannel) +Added: 7.44.0 +Category: tls +Example: --ssl-no-revoke $URL +--- +(Schannel) 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. diff --git a/docs/cmdline-opts/ssl-reqd.d b/docs/cmdline-opts/ssl-reqd.d new file mode 100644 index 0000000000000000000000000000000000000000..489be00d97c7f2dc6073be7ff489ec86b4d5410c --- /dev/null +++ b/docs/cmdline-opts/ssl-reqd.d @@ -0,0 +1,11 @@ +Long: ssl-reqd +Help: Require SSL/TLS +Protocols: FTP IMAP POP3 SMTP +Added: 7.20.0 +Category: tls +Example: --ssl-reqd ftp://example.com +--- +Require SSL/TLS for the connection. Terminates the connection if the server +doesn't support SSL/TLS. + +This option was formerly known as --ftp-ssl-reqd. diff --git a/docs/cmdline-opts/ssl-revoke-best-effort.d b/docs/cmdline-opts/ssl-revoke-best-effort.d new file mode 100644 index 0000000000000000000000000000000000000000..2db32192ee363559b0910526b7bff86a746950c3 --- /dev/null +++ b/docs/cmdline-opts/ssl-revoke-best-effort.d @@ -0,0 +1,9 @@ +Long: ssl-revoke-best-effort +Help: Ignore missing/offline cert CRL dist points +Added: 7.70.0 +Category: tls +Example: --ssl-revoke-best-effort $URL +--- +(Schannel) This option tells curl to ignore certificate revocation checks when +they failed due to missing/offline distribution points for the revocation check +lists. diff --git a/docs/cmdline-opts/ssl.d b/docs/cmdline-opts/ssl.d new file mode 100644 index 0000000000000000000000000000000000000000..bc339faed30581d1e29a96e22bfc67d31e06ce55 --- /dev/null +++ b/docs/cmdline-opts/ssl.d @@ -0,0 +1,13 @@ +Long: ssl +Help: Try SSL/TLS +Protocols: FTP IMAP POP3 SMTP +Added: 7.20.0 +Category: tls +Example: --ssl pop3://example.com/ +--- +Try to use SSL/TLS for the connection. Reverts to a non-secure connection if +the server doesn't support SSL/TLS. See also --ftp-ssl-control and --ssl-reqd +for different levels of encryption required. + +This option was formerly known as --ftp-ssl (Added in 7.11.0). That option +name can still be used but will be removed in a future version. diff --git a/docs/cmdline-opts/sslv2.d b/docs/cmdline-opts/sslv2.d new file mode 100644 index 0000000000000000000000000000000000000000..d96a6cc8d8592a57190d38f936b5a017429710df --- /dev/null +++ b/docs/cmdline-opts/sslv2.d @@ -0,0 +1,15 @@ +Short: 2 +Long: sslv2 +Tags: Versions +Protocols: SSL +Added: +Mutexed: sslv3 tlsv1 tlsv1.1 tlsv1.2 +Requires: TLS +See-also: http1.1 http2 +Help: Use SSLv2 +Category: tls +Example: --sslv2 $URL +--- +This option previously asked curl to use SSLv2, but starting in curl 7.77.0 +this instruction is ignored. SSLv2 is widely considered insecure (see RFC +6176). diff --git a/docs/cmdline-opts/sslv3.d b/docs/cmdline-opts/sslv3.d new file mode 100644 index 0000000000000000000000000000000000000000..3ee483d2aecb0f785a91c18f305a1fc3942cd0a4 --- /dev/null +++ b/docs/cmdline-opts/sslv3.d @@ -0,0 +1,15 @@ +Short: 3 +Long: sslv3 +Tags: Versions +Protocols: SSL +Added: +Mutexed: sslv2 tlsv1 tlsv1.1 tlsv1.2 +Requires: TLS +See-also: http1.1 http2 +Help: Use SSLv3 +Category: tls +Example: --sslv3 $URL +--- +This option previously asked curl to use SSLv3, but starting in curl 7.77.0 +this instruction is ignored. SSLv3 is widely considered insecure (see RFC +7568). diff --git a/docs/cmdline-opts/stderr.d b/docs/cmdline-opts/stderr.d new file mode 100644 index 0000000000000000000000000000000000000000..c0f0efa38bbb67073901dd748f4c5dc8e361ae4d --- /dev/null +++ b/docs/cmdline-opts/stderr.d @@ -0,0 +1,14 @@ +Long: stderr +Arg: +Help: Where to redirect stderr +See-also: verbose silent +Category: verbose +Example: --stderr output.txt $URL +--- +Redirect all writes to stderr to the specified file instead. If the file name +is a plain '-', it is instead written to stdout. + +This option is global and does not need to be specified for each use of +--next. + +If this option is used several times, the last one will be used. diff --git a/docs/cmdline-opts/styled-output.d b/docs/cmdline-opts/styled-output.d new file mode 100644 index 0000000000000000000000000000000000000000..bf636019a63b04f15780329732b0fd1385fe9067 --- /dev/null +++ b/docs/cmdline-opts/styled-output.d @@ -0,0 +1,11 @@ +Long: styled-output +Help: Enable styled output for HTTP headers +Added: 7.61.0 +Category: verbose +Example: --styled-output -I $URL +--- +Enables the automatic use of bold font styles when writing HTTP headers to the +terminal. Use --no-styled-output to switch them off. + +This option is global and does not need to be specified for each use of +--next. diff --git a/docs/cmdline-opts/suppress-connect-headers.d b/docs/cmdline-opts/suppress-connect-headers.d new file mode 100644 index 0000000000000000000000000000000000000000..71078e8877dbddc9fc3a41896114fd85ce29a73c --- /dev/null +++ b/docs/cmdline-opts/suppress-connect-headers.d @@ -0,0 +1,10 @@ +Long: suppress-connect-headers +Help: Suppress proxy CONNECT response headers +See-also: dump-header include proxytunnel +Category: proxy +Example: --suppress-connect-headers --include -x proxy $URL +--- +When --proxytunnel is used and a CONNECT request is made don't output proxy +CONNECT response headers. This option is meant to be used with --dump-header or +--include which are used to show protocol headers in the output. It has no +effect on debug options such as --verbose or --trace, or any statistics. diff --git a/docs/cmdline-opts/tcp-fastopen.d b/docs/cmdline-opts/tcp-fastopen.d new file mode 100644 index 0000000000000000000000000000000000000000..e7e9d2e9af488e374cd16abce070f171877dab75 --- /dev/null +++ b/docs/cmdline-opts/tcp-fastopen.d @@ -0,0 +1,7 @@ +Long: tcp-fastopen +Added: 7.49.0 +Help: Use TCP Fast Open +Category: connection +Example: --tcp-fastopen $URL +--- +Enable use of TCP Fast Open (RFC7413). diff --git a/docs/cmdline-opts/tcp-nodelay.d b/docs/cmdline-opts/tcp-nodelay.d new file mode 100644 index 0000000000000000000000000000000000000000..97cd30aa0e7e9547a7fc69af906baa7de5ecf929 --- /dev/null +++ b/docs/cmdline-opts/tcp-nodelay.d @@ -0,0 +1,11 @@ +Long: tcp-nodelay +Help: Use the TCP_NODELAY option +Added: 7.11.2 +Category: connection +Example: --tcp-nodelay $URL +--- +Turn on the TCP_NODELAY option. See the *curl_easy_setopt(3)* man page for +details about this option. + +Since 7.50.2, curl sets this option by default and you need to explicitly +switch it off if you don't want it on. diff --git a/docs/cmdline-opts/telnet-option.d b/docs/cmdline-opts/telnet-option.d new file mode 100644 index 0000000000000000000000000000000000000000..3475cb596c753369104beb73ebdf46395badca72 --- /dev/null +++ b/docs/cmdline-opts/telnet-option.d @@ -0,0 +1,14 @@ +Long: telnet-option +Short: t +Arg: +Help: Set telnet option +Category: telnet +Example: -t TTYPE=vt100 telnet://example.com/ +--- +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. diff --git a/docs/cmdline-opts/tftp-blksize.d b/docs/cmdline-opts/tftp-blksize.d new file mode 100644 index 0000000000000000000000000000000000000000..3b19e5cf786c52775691ab824be9960829b3c9b9 --- /dev/null +++ b/docs/cmdline-opts/tftp-blksize.d @@ -0,0 +1,13 @@ +Long: tftp-blksize +Arg: +Help: Set TFTP BLKSIZE option +Protocols: TFTP +Added: 7.20.0 +Category: tftp +Example: --tftp-blksize 1024 tftp://example.com/file +--- +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. diff --git a/docs/cmdline-opts/tftp-no-options.d b/docs/cmdline-opts/tftp-no-options.d new file mode 100644 index 0000000000000000000000000000000000000000..9ff334b86877a6d2ca0a453414843f83fdef87b4 --- /dev/null +++ b/docs/cmdline-opts/tftp-no-options.d @@ -0,0 +1,12 @@ +Long: tftp-no-options +Help: Do not send any TFTP options +Protocols: TFTP +Added: 7.48.0 +Category: tftp +Example: --tftp-no-options tftp://192.168.0.1/ +--- +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 --tftp-blksize is +ignored. diff --git a/docs/cmdline-opts/time-cond.d b/docs/cmdline-opts/time-cond.d new file mode 100644 index 0000000000000000000000000000000000000000..f82f497fc0d16b48e3b80527c5551093ad30dc5f --- /dev/null +++ b/docs/cmdline-opts/time-cond.d @@ -0,0 +1,21 @@ +Long: time-cond +Short: z +Arg: