You always find news about what's going on as well as the latest versions
from the curl web pages, located at:
- http://curl.haxx.se
+ https://curl.haxx.se
SIMPLE USAGE
curl http://www.weirdserver.com:8000/
- Get a list of a directory of an FTP site:
+ Get a directory listing of an FTP site:
curl ftp://cool.haxx.se/
Get a file from an SSH server using SFTP:
- curl -u username sftp://shell.example.com/etc/issue
+ curl -u username sftp://example.com/etc/issue
- Get a file from an SSH server using SCP using a private key to authenticate:
+ Get a file from an SSH server using SCP using a private key
+ (not password-protected) to authenticate:
- curl -u username: --key ~/.ssh/id_dsa --pubkey ~/.ssh/id_dsa.pub \
- scp://shell.example.com/~/personal.txt
+ curl -u username: --key ~/.ssh/id_rsa \
+ scp://example.com/~/file.txt
+ Get a file from an SSH server using SCP using a private key
+ (password-protected) to authenticate:
+
+ curl -u username: --key ~/.ssh/id_rsa --pass private_key_password \
+ scp://example.com/~/file.txt
+
+ Get the main page from an IPv6 web server:
+
+ curl "http://[2001:1890:1112:1::20]/"
+
+ Get a file from an SMB server:
+
+ curl -u "domain\username:passwd" smb://server.example.com/share/file.txt
DOWNLOAD TO A FILE
- Get a web page and store in a local file:
+ Get a web page and store in a local file with a specific name:
curl -o thatpage.html http://www.netscape.com/
standards while the recommended "explicit" way is done by using FTP:// and
the --ftp-ssl option.
+ SFTP / SCP
+
+ This is similar to FTP, but you can use the --key option to specify a
+ private key to use instead of a password. Note that the private key may
+ itself be protected by a password that is unrelated to the login password
+ of the remote system; this password is specified using the --pass option.
+ Typically, curl will automatically extract the public key from the private
+ key file, but in cases where curl does not have the proper library support,
+ a matching public key file must be specified using the --pubkey option.
+
HTTP
Curl also supports user and password in HTTP URLs, thus you can pick a file
curl -u name:passwd http://machine.domain/full/path/to/file
HTTP offers many different methods of authentication and curl supports
- several: Basic, Digest, NTLM and Negotiate. Without telling which method to
- use, curl defaults to Basic. You can also ask curl to pick the most secure
- ones out of the ones that the server accepts for the given URL, by using
- --anyauth.
+ several: Basic, Digest, NTLM and Negotiate (SPNEGO). Without telling which
+ method to use, curl defaults to Basic. You can also ask curl to pick the
+ most secure ones out of the ones that the server accepts for the given URL,
+ by using --anyauth.
- NOTE! Since HTTP URLs don't support user and password, you can't use that
- style when using Curl via a proxy. You _must_ use the -u style fetch
- during such circumstances.
+ NOTE! According to the URL specification, HTTP URLs can not contain a user
+ and password, so that style will not work when using curl via a proxy, even
+ though curl allows it at other times. When using a proxy, you _must_ use
+ the -u style for user and password.
HTTPS
PROXY
- Get an ftp file using a proxy named my-proxy that uses port 888:
+ curl supports both HTTP and SOCKS proxy servers, with optional authentication.
+ It does not have special support for FTP proxy servers since there are no
+ standards for those, but it can still be made to work with many of them. You
+ can also use both HTTP and SOCKS proxies to transfer files to and from FTP
+ servers.
+
+ Get an ftp file using an HTTP proxy named my-proxy that uses port 888:
curl -x my-proxy:888 ftp://ftp.leachsite.com/README
- Get a file from a HTTP server that requires user and password, using the
+ Get a file from an HTTP server that requires user and password, using the
same proxy as above:
curl -u user:passwd -x my-proxy:888 http://www.get.this/
curl -U user:passwd -x my-proxy:888 http://www.get.this/
+ A comma-separated list of hosts and domains which do not use the proxy can
+ be specified as:
+
+ curl --noproxy localhost,get.this -x my-proxy:888 http://www.get.this/
+
+ If the proxy is specified with --proxy1.0 instead of --proxy or -x, then
+ curl will use HTTP/1.0 instead of HTTP/1.1 for any CONNECT attempts.
+
curl also supports SOCKS4 and SOCKS5 proxies with --socks4 and --socks5.
- See also the environment variables Curl support that offer further proxy
+ See also the environment variables Curl supports that offer further proxy
control.
+ Most FTP proxy servers are set up to appear as a normal FTP server from the
+ client's perspective, with special commands to select the remote FTP server.
+ curl supports the -u, -Q and --ftp-account options that can be used to
+ set up transfers through many FTP proxies. For example, a file can be
+ uploaded to a remote FTP server using a Blue Coat FTP proxy with the
+ options:
+
+ curl -u "Remote-FTP-Username@remote.ftp.server Proxy-Username:Remote-Pass" \
+ --ftp-account Proxy-Password --upload-file local-file \
+ ftp://my-ftp.proxy.server:21/remote/upload/path/
+
+ See the manual for your FTP proxy to determine the form it expects to set up
+ transfers, and curl's -v option to see exactly what curl is sending.
+
RANGES
- With HTTP 1.1 byte-ranges were introduced. Using this, a client can request
+ HTTP 1.1 introduced byte-ranges. Using this, a client can request
to get only one or more subparts of a specified document. Curl supports
this with the -r flag.
Get the first 100 bytes of a document using FTP:
- curl -r 0-99 ftp://www.get.this/README
+ curl -r 0-99 ftp://www.get.this/README
UPLOADING
- FTP
+ FTP / FTPS / SFTP / SCP
- Upload all data on stdin to a specified ftp site:
+ Upload all data on stdin to a specified server:
curl -T - ftp://ftp.upload.com/myfile
curl -T uploadfile -u user:passwd ftp://ftp.upload.com/myfile
- Upload a local file to the remote site, and use the local file name remote
- too:
-
+ Upload a local file to the remote site, and use the local file name at the remote
+ site too:
+
curl -T uploadfile -u user:passwd ftp://ftp.upload.com/
- Upload a local file to get appended to the remote file using ftp:
+ Upload a local file to get appended to the remote file:
curl -T localfile -a ftp://ftp.upload.com/remotefile
curl --proxytunnel -x proxy:port -T localfile ftp.upload.com
+SMB / SMBS
+
+ curl -T file.txt -u "domain\username:passwd"
+ smb://server.example.com/share/
+
HTTP
- Upload all data on stdin to a specified http site:
+ Upload all data on stdin to a specified HTTP site:
curl -T - http://www.upload.com/myfile
- Note that the http server must have been configured to accept PUT before
+ Note that the HTTP server must have been configured to accept PUT before
this can be done successfully.
- For other ways to do http data upload, see the POST section below.
+ For other ways to do HTTP data upload, see the POST section below.
VERBOSE / DEBUG
this:
curl --trace trace.txt www.haxx.se
-
+
DETAILED INFORMATION
How to post a form with curl, lesson #1:
- Dig out all the <input> tags in the form that you want to fill in. (There's
- a perl program called formfind.pl on the curl site that helps with this).
+ Dig out all the <input> tags in the form that you want to fill in.
If there's a "normal" post, you use -d to post. -d takes a full "post
string", which is in the format
The 'variable' names are the names set with "name=" in the <input> tags, and
the data is the contents you want to fill in for the inputs. The data *must*
be properly URL encoded. That means you replace space with + and that you
- write weird letters with %XX where XX is the hexadecimal representation of
+ replace weird letters with %XX where XX is the hexadecimal representation of
the letter's ASCII code.
Example:
If the content-type is not specified, curl will try to guess from the file
extension (it only knows a few), or use the previously specified type (from
an earlier file if several files are specified in a list) or else it will
- using the default type 'text/plain'.
+ use the default type 'application/octet-stream'.
Emulate a fill-in form with -F. Let's say you fill in three fields in a
form. One field is a file name which to post, one field is your name and one
To send two files in one post you can do it in two ways:
1. Send multiple files in a single "field" with a single field name:
-
- curl -F "pictures=@dog.gif,cat.gif"
-
- 2. Send two fields with two field names:
- curl -F "docpicture=@dog.gif" -F "catpicture=@cat.gif"
+ curl -F "pictures=@dog.gif,cat.gif"
+
+ 2. Send two fields with two field names:
+
+ curl -F "docpicture=@dog.gif" -F "catpicture=@cat.gif"
To send a field value literally without interpreting a leading '@'
or '<', or an embedded ';type=', use --form-string instead of
REFERRER
- A HTTP request has the option to include information about which address
- that referred to actual page. Curl allows you to specify the
+ An HTTP request has the option to include information about which address
+ referred it to the actual page. Curl allows you to specify the
referrer to be used on the command line. It is especially useful to
fool or trick stupid servers or CGI scripts that rely on that information
being available or contain certain data.
curl -e www.coolsite.com http://www.showme.com/
- NOTE: The referer field is defined in the HTTP spec to be a full URL.
+ NOTE: The Referer: [sic] field is defined in the HTTP spec to be a full URL.
USER AGENT
- A HTTP request has the option to include information about the browser
+ An HTTP request has the option to include information about the browser
that generated the request. Curl allows it to be specified on the command
line. It is especially useful to fool or trick stupid servers or CGI
scripts that only accept certain browsers.
stored cookies which match the request as it follows the location. The
file "empty.txt" may be a nonexistent file.
- Alas, to both read and write cookies from a netscape cookie file, you can
- set both -b and -c to use the same file:
+ To read and write cookies from a netscape cookie file, you can set both -b
+ and -c to use the same file:
curl -b cookies.txt -c cookies.txt www.example.com
can also specify the long options without the dashes to make it more
readable. You can separate the options and the parameter with spaces, or
with = or :. Comments can be used within the file. If the first letter on a
- line is a '#'-letter the rest of the line is treated as a comment.
+ line is a '#'-symbol the rest of the line is treated as a comment.
If you want the parameter to contain spaces, you must enclose the entire
parameter within double quotes ("). Within those quotes, you specify a
(I.e with an extra slash in front of the file name.)
+SFTP and SCP and PATH NAMES
+
+ With sftp: and scp: URLs, the path name given is the absolute name on the
+ server. To access a file relative to the remote user's home directory,
+ prefix the file with /~/ , such as:
+
+ curl -u $USER sftp://home.example.com/~/.bashrc
+
FTP and firewalls
The FTP protocol requires one of the involved parties to open a second
- connection as soon as data is about to get transfered. There are two ways to
+ connection as soon as data is about to get transferred. There are two ways to
do this.
The default way for curl is to issue the PASV command which causes the
server to open another port and await another connection performed by the
- client. This is good if the client is behind a firewall that don't allow
+ client. This is good if the client is behind a firewall that doesn't allow
incoming connections.
curl ftp.download.com
- If the server for example, is behind a firewall that don't allow connections
- on other ports than 21 (or if it just doesn't support the PASV command), the
+ If the server, for example, is behind a firewall that doesn't allow connections
+ on ports other than 21 (or if it just doesn't support the PASV command), the
other way to do it is to use the PORT command and instruct the server to
- connect to the client on the given (as parameters to the PORT command) IP
- number and port.
+ connect to the client on the given IP number and port (as parameters to the
+ PORT command).
The -P flag to curl supports a few different options. Your machine may have
several IP-addresses and/or network interfaces and curl allows you to select
If you neglect to specify the password on the command line, you will be
prompted for the correct password before any data can be received.
- Many older SSL-servers have problems with SSLv3 or TLS, that newer versions
- of OpenSSL etc is using, therefore it is sometimes useful to specify what
+ Many older SSL-servers have problems with SSLv3 or TLS, which newer versions
+ of OpenSSL etc use, therefore it is sometimes useful to specify what
SSL-version curl should use. Use -3, -2 or -1 to specify that exact SSL
version to use (for SSLv3, SSLv2 or TLSv1 respectively):
Otherwise, curl will first attempt to use v3 and then v2.
To use OpenSSL to convert your favourite browser's certificate into a PEM
- formatted one that curl can use, do something like this (assuming netscape,
- but IE is likely to work similarly):
+ formatted one that curl can use, do something like this:
- You start with hitting the 'security' menu button in netscape.
+ In Netscape, you start with hitting the 'Security' menu button.
- Select 'certificates->yours' and then pick a certificate in the list
+ Select 'certificates->yours' and then pick a certificate in the list
- Press the 'export' button
+ Press the 'Export' button
- enter your PIN code for the certs
+ enter your PIN code for the certs
- select a proper place to save it
+ select a proper place to save it
Run the 'openssl' application to convert the certificate. If you cd to the
openssl installation, you can do it like:
# ./apps/openssl pkcs12 -in [file you saved] -clcerts -out [PEMfile]
+ In Firefox, select Options, then Advanced, then the Encryption tab,
+ View Certificates. This opens the Certificate Manager, where you can
+ Export. Be sure to select PEM for the Save as type.
+
+ In Internet Explorer, select Internet Options, then the Content tab, then
+ Certificates. Then you can Export, and depending on the format you may
+ need to convert to PEM.
+
+ In Chrome, select Settings, then Show Advanced Settings. Under HTTPS/SSL
+ select Manage Certificates.
RESUMING FILE TRANSFERS
To continue a file transfer where it was previously aborted, curl supports
- resume on http(s) downloads as well as ftp uploads and downloads.
+ resume on HTTP(S) downloads as well as FTP uploads and downloads.
Continue downloading a document:
curl -C - -o file http://www.server.com/
- (*1) = This requires that the ftp server supports the non-standard command
+ (*1) = This requires that the FTP server supports the non-standard command
SIZE. If it doesn't, curl will say so.
(*2) = This requires that the web server supports at least HTTP/1.1. If it
TIME CONDITIONS
HTTP allows a client to specify a time condition for the document it
- requests. It is If-Modified-Since or If-Unmodified-Since. Curl allow you to
+ requests. It is If-Modified-Since or If-Unmodified-Since. Curl allows you to
specify them with the -z/--time-cond flag.
For example, you can easily make a download that only gets performed if the
If you have installed the OpenLDAP library, curl can take advantage of it
and offer ldap:// support.
+ On Windows, curl will use WinLDAP from Platform SDK by default.
- LDAP is a complex thing and writing an LDAP query is not an easy task. I do
- advice you to dig up the syntax description for that elsewhere. Two places
- that might suit you are:
+ Default protocol version used by curl is LDAPv3. LDAPv2 will be used as
+ fallback mechanism in case if LDAPv3 will fail to connect.
- Netscape's "Netscape Directory SDK 3.0 for C Programmer's Guide Chapter 10:
- Working with LDAP URLs":
- http://developer.netscape.com/docs/manuals/dirsdk/csdk30/url.htm
+ LDAP is a complex thing and writing an LDAP query is not an easy task. I do
+ advise you to dig up the syntax description for that elsewhere. One such
+ place might be:
- RFC 2255, "The LDAP URL Format" http://curl.haxx.se/rfc/rfc2255.txt
+ RFC 2255, "The LDAP URL Format" https://curl.haxx.se/rfc/rfc2255.txt
- To show you an example, this is now I can get all people from my local LDAP
+ To show you an example, this is how I can get all people from my local LDAP
server that has a certain sub-domain in their email address:
curl -B "ldap://ldap.frontec.se/o=frontec??sub?mail=*sth.frontec.se"
If I want the same info in HTML format, I can get it by not using the -B
(enforce ASCII) flag.
+ You also can use authentication when accessing LDAP catalog:
+
+ curl -u user:passwd "ldap://ldap.frontec.se/o=frontec??sub?mail=*"
+ curl "ldap://user:passwd@ldap.frontec.se/o=frontec??sub?mail=*"
+
+ By default, if user and password provided, OpenLDAP/WinLDAP will use basic
+ authentication. On Windows you can control this behavior by providing
+ one of --basic, --ntlm or --digest option in curl command line
+
+ curl --ntlm "ldap://user:passwd@ldap.frontec.se/o=frontec??sub?mail=*"
+
+ On Windows, if no user/password specified, auto-negotiation mechanism will
+ be used with current logon credentials (SSPI/SPNEGO).
+
ENVIRONMENT VARIABLES
Curl reads and understands the following environment variables:
They should be set for protocol-specific proxies. General proxy should be
set with
-
+
ALL_PROXY
A comma-separated list of host names that shouldn't go through any proxy is
NO_PROXY
- If a tail substring of the domain-path for a host matches one of these
- strings, transactions with that node will not be proxied.
-
+ If the host name matches one of these strings, or the host is within the
+ domain of one of these strings, transactions with that node will not be
+ proxied. When a domain is used, it needs to start with a period. A user can
+ specify that both www.example.com and foo.example.com should not uses a
+ proxy by setting NO_PROXY to ".example.com". By including the full name you
+ can exclude specific host names, so to make www.example.com not use a proxy
+ but still have foo.example.com do it, set NO_PROXY to "www.example.com"
The usage of the -x/--proxy flag overrides the environment variables.
NETRC
Unix introduced the .netrc concept a long time ago. It is a way for a user
- to specify name and password for commonly visited ftp sites in a file so
+ to specify name and password for commonly visited FTP sites in a file so
that you don't have to type them in each time you visit those sites. You
realize this is a big security risk if someone else gets hold of your
passwords, so therefore most unix programs won't read this file unless it is
only readable by yourself (curl doesn't care though).
- Curl supports .netrc files if told so (using the -n/--netrc and
- --netrc-optional options). This is not restricted to only ftp,
- but curl can use it for all protocols where authentication is used.
+ Curl supports .netrc files if told to (using the -n/--netrc and
+ --netrc-optional options). This is not restricted to just FTP,
+ so curl can use it for all protocols where authentication is used.
A very simple .netrc file could look something like:
Curl supports kerberos4 and kerberos5/GSSAPI for FTP transfers. You need
the kerberos package installed and used at curl build time for it to be
- used.
+ available.
First, get the krb-ticket the normal way, like with the kinit/kauth tool.
Then use curl in way similar to:
- NEW_ENV=<var,val> Sets an environment variable.
- NOTE: the telnet protocol does not specify any way to login with a specified
+ NOTE: The telnet protocol does not specify any way to login with a specified
user and password so curl can't do that automatically. To do that, you need
to track when the login prompt is received and send the username and
password accordingly.
Note that curl cannot use persistent connections for transfers that are used
in subsequence curl invokes. Try to stuff as many URLs as possible on the
same command line if they are using the same host, as that'll make the
- transfers faster. If you use a http proxy for file transfers, practically
+ transfers faster. If you use an HTTP proxy for file transfers, practically
all transfers will be persistent.
MULTIPLE TRANSFERS WITH A SINGLE COMMAND LINE
As is mentioned above, you can download multiple files with one command line
by simply adding more URLs. If you want those to get saved to a local file
instead of just printed to stdout, you need to add one save option for each
- URL you specify. Note that this also goes for the -O option.
+ URL you specify. Note that this also goes for the -O option (but not
+ --remote-name-all).
For example: get two files and use -O for the first and a custom file
name for the second:
When this style is used, the -g option must be given to stop curl from
interpreting the square brackets as special globbing characters. Link local
and site local addresses including a scope identifier, such as fe80::1234%1,
- may also be used, but the scope portion must be numeric and the percent
- character must be URL escaped. The previous example in an SFTP URL might
- look like:
+ may also be used, but the scope portion must be numeric or match an existing
+ network interface on Linux and the percent character must be URL escaped. The
+ previous example in an SFTP URL might look like:
sftp://[fe80::1234%251]/
+ IPv6 addresses provided other than in URLs (e.g. to the --proxy, --interface
+ or --ftp-port options) should not be URL encoded.
+
+METALINK
+
+ Curl supports Metalink (both version 3 and 4 (RFC 5854) are supported), a way
+ to list multiple URIs and hashes for a file. Curl will make use of the mirrors
+ listed within for failover if there are errors (such as the file or server not
+ being available). It will also verify the hash of the file after the download
+ completes. The Metalink file itself is downloaded and processed in memory and
+ not stored in the local file system.
+
+ Example to use a remote Metalink file:
+
+ curl --metalink http://www.example.com/example.metalink
+
+ To use a Metalink file in the local file system, use FILE protocol (file://):
+
+ curl --metalink file://example.metalink
+
+ Please note that if FILE protocol is disabled, there is no way to use a local
+ Metalink file at the time of this writing. Also note that if --metalink and
+ --include are used together, --include will be ignored. This is because including
+ headers in the response will break Metalink parser and if the headers are included
+ in the file described in Metalink file, hash check will fail.
MAILING LISTS
For your convenience, we have several open mailing lists to discuss curl,
its development and things relevant to this. Get all info at
- http://curl.haxx.se/mail/. Some of the lists available are:
+ https://curl.haxx.se/mail/. Some of the lists available are:
curl-users
projects / platform / upstream / curl.git / blobdiff