luna - curl/docs/MANUAL.md

   1<!--
   2Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al.
   3
   4SPDX-License-Identifier: curl
   5-->
   6
   7# curl tutorial
   8
   9## Simple Usage
  10
  11Get the main page from a web-server:
  12
  13    curl https://www.example.com/
  14
  15Get a README file from an FTP server:
  16
  17    curl ftp://ftp.example.com/README
  18
  19Get a webpage from a server using port 8000:
  20
  21    curl http://www.example.com:8000/
  22
  23Get a directory listing of an FTP site:
  24
  25    curl ftp://ftp.example.com/
  26
  27Get the all terms matching curl from a dictionary:
  28
  29    curl dict://dict.example.com/m:curl
  30
  31Get the definition of curl from a dictionary:
  32
  33    curl dict://dict.example.com/d:curl
  34
  35Fetch two documents at once:
  36
  37    curl ftp://ftp.example.com/ https://www.example.com:8000/
  38
  39Get a file off an FTPS server:
  40
  41    curl ftps://files.are.example.com/secrets.txt
  42
  43or use the more appropriate FTPS way to get the same file:
  44
  45    curl --ssl-reqd ftp://files.are.example.com/secrets.txt
  46
  47Get a file from an SSH server using SFTP:
  48
  49    curl -u username sftp://example.com/etc/issue
  50
  51Get a file from an SSH server using SCP using a private key (not
  52password-protected) to authenticate:
  53
  54    curl -u username: --key ~/.ssh/id_rsa scp://example.com/~/file.txt
  55
  56Get a file from an SSH server using SCP using a private key
  57(password-protected) to authenticate:
  58
  59    curl -u username: --key ~/.ssh/id_rsa --pass private_key_password
  60    scp://example.com/~/file.txt
  61
  62Get the main page from an IPv6 web server:
  63
  64    curl "http://[2001:1890:1112:1::20]/"
  65
  66Get a file from an SMB server:
  67
  68    curl -u "domain\username:passwd" smb://server.example.com/share/file.txt
  69
  70## Download to a File
  71
  72Get a webpage and store in a local file with a specific name:
  73
  74    curl -o thatpage.html https://www.example.com/
  75
  76Get a webpage and store in a local file, make the local file get the name of
  77the remote document (if no filename part is specified in the URL, this fails):
  78
  79    curl -O https://www.example.com/index.html
  80
  81Fetch two files and store them with their remote names:
  82
  83    curl -O www.haxx.se/index.html -O curl.se/download.html
  84
  85## Using Passwords
  86
  87### FTP
  88
  89To ftp files using name and password, include them in the URL like:
  90
  91    curl ftp://name:passwd@ftp.server.example:port/full/path/to/file
  92
  93or specify them with the `-u` flag like
  94
  95    curl -u name:passwd ftp://ftp.server.example:port/full/path/to/file
  96
  97### FTPS
  98
  99It is like FTP, but you may also want to specify and use SSL-specific options
 100for certificates etc.
 101
 102Note that using `FTPS://` as prefix is the *implicit* way as described in the
 103standards while the recommended *explicit* way is done by using `FTP://` and
 104the `--ssl-reqd` option.
 105
 106### SFTP / SCP
 107
 108This is similar to FTP, but you can use the `--key` option to specify a
 109private key to use instead of a password. Note that the private key may itself
 110be protected by a password that is unrelated to the login password of the
 111remote system; this password is specified using the `--pass` option.
 112Typically, curl automatically extracts the public key from the private key
 113file, but in cases where curl does not have the proper library support, a
 114matching public key file must be specified using the `--pubkey` option.
 115
 116### HTTP
 117
 118curl also supports user and password in HTTP(S) URLs. You can download a file
 119like:
 120
 121    curl https://name:passwd@http.server.example/full/path/to/file
 122
 123or specify user and password separately like in
 124
 125    curl -u name:passwd https://http.server.example/full/path/to/file
 126
 127HTTP offers many different methods of authentication and curl supports
 128several: Basic, Digest, NTLM and Negotiate (SPNEGO). Without telling which
 129method to use, curl defaults to Basic. You can also ask curl to pick the most
 130secure ones out of the ones that the server accepts for the given URL, by
 131using `--anyauth`.
 132
 133**Note**! According to the URL specification, HTTP URLs can not contain a user
 134and password, so that style does not work when using curl via a proxy, even
 135though curl allows it at other times. When using a proxy, you _must_ use the
 136`-u` style for user and password.
 137
 138### HTTPS
 139
 140Probably most commonly used with private certificates, as explained below.
 141
 142## Proxy
 143
 144curl supports both HTTP and SOCKS proxy servers, with optional authentication.
 145It does not have special support for FTP proxy servers since there are no
 146standards for those, but it can still be made to work with many of them. You
 147can also use both HTTP and SOCKS proxies to transfer files to and from FTP
 148servers.
 149
 150Get an ftp file using an HTTP proxy named my-proxy that uses port 888:
 151
 152    curl -x my-proxy:888 ftp://ftp.example.com/README
 153
 154Get a file from an HTTPS server that requires user and password, using the
 155same proxy as above:
 156
 157    curl -u user:passwd -x my-proxy:888 https://www.example.com/
 158
 159Some proxies require special authentication. Specify by using -U as above:
 160
 161    curl -U user:passwd -x my-proxy:888 https://www.example.com/
 162
 163A comma-separated list of hosts and domains which do not use the proxy can be
 164specified as:
 165
 166    curl --noproxy example.com -x my-proxy:888 https://www.example.com/
 167
 168If the proxy is specified with `--proxy1.0` instead of `--proxy` or `-x`, then
 169curl uses HTTP/1.0 instead of HTTP/1.1 for any `CONNECT` attempts.
 170
 171curl also supports SOCKS4 and SOCKS5 proxies with `--socks4` and `--socks5`.
 172
 173See also the environment variables curl supports that offer further proxy
 174control.
 175
 176Most FTP proxy servers are set up to appear as a normal FTP server from the
 177client's perspective, with special commands to select the remote FTP server.
 178curl supports the `-u`, `-Q` and `--ftp-account` options that can be used to
 179set up transfers through many FTP proxies. For example, a file can be uploaded
 180to a remote FTP server using a Blue Coat FTP proxy with the options:
 181
 182    curl -u "username@ftp.server.example Proxy-Username:Remote-Pass"
 183      --ftp-account Proxy-Password --upload-file local-file
 184      ftp://my-ftp.proxy.example:21/remote/upload/path/
 185
 186See the manual for your FTP proxy to determine the form it expects to set up
 187transfers, and curl's `-v` option to see exactly what curl is sending.
 188
 189## Piping
 190
 191Get a key file and add it with `apt-key` (when on a system that uses `apt` for
 192package management):
 193
 194    curl -L https://apt.example.org/llvm-snapshot.gpg.key | sudo apt-key add -
 195
 196The '|' pipes the output to STDIN. `-` tells `apt-key` that the key file
 197should be read from STDIN.
 198
 199## Ranges
 200
 201HTTP 1.1 introduced byte-ranges. Using this, a client can request to get only
 202one or more sub-parts of a specified document. curl supports this with the
 203`-r` flag.
 204
 205Get the first 100 bytes of a document:
 206
 207    curl -r 0-99 https://www.example.com/
 208
 209Get the last 500 bytes of a document:
 210
 211    curl -r -500 https://www.example.com/
 212
 213curl also supports simple ranges for FTP files as well. Then you can only
 214specify start and stop position.
 215
 216Get the first 100 bytes of a document using FTP:
 217
 218    curl -r 0-99 ftp://www.example.com/README
 219
 220## Uploading
 221
 222### FTP / FTPS / SFTP / SCP
 223
 224Upload all data on stdin to a specified server:
 225
 226    curl -T - ftp://ftp.example.com/myfile
 227
 228Upload data from a specified file, login with user and password:
 229
 230    curl -T uploadfile -u user:passwd ftp://ftp.example.com/myfile
 231
 232Upload a local file to the remote site, and use the local filename at the
 233remote site too:
 234
 235    curl -T uploadfile -u user:passwd ftp://ftp.example.com/
 236
 237Upload a local file to get appended to the remote file:
 238
 239    curl -T localfile -a ftp://ftp.example.com/remotefile
 240
 241curl also supports ftp upload through a proxy, but only if the proxy is
 242configured to allow that kind of tunneling. If it does, you can run curl in a
 243fashion similar to:
 244
 245    curl --proxytunnel -x proxy:port -T localfile ftp.example.com
 246
 247### SMB / SMBS
 248
 249    curl -T file.txt -u "domain\username:passwd"
 250      smb://server.example.com/share/
 251
 252### HTTP
 253
 254Upload all data on stdin to a specified HTTPS site:
 255
 256    curl -T - https://www.example.com/myfile
 257
 258Note that the HTTP server must have been configured to accept PUT before this
 259can be done successfully.
 260
 261For other ways to do HTTP data upload, see the POST section below.
 262
 263## Verbose / Debug
 264
 265If curl fails where it is not supposed to, if the servers do not let you in,
 266if you cannot understand the responses: use the `-v` flag to get verbose
 267fetching. curl outputs lots of info and what it sends and receives in order to
 268let the user see all client-server interaction (but it does not show you the
 269actual data).
 270
 271    curl -v ftp://ftp.example.com/
 272
 273To get even more details and information on what curl does, try using the
 274`--trace` or `--trace-ascii` options with a given filename to log to, like
 275this:
 276
 277    curl --trace my-trace.txt www.haxx.se
 278
 279## Detailed Information
 280
 281Different protocols provide different ways of getting detailed information
 282about specific files/documents. To get curl to show detailed information about
 283a single file, you should use `-I`/`--head` option. It displays all available
 284info on a single file for HTTP and FTP. The HTTP information is a lot more
 285extensive.
 286
 287For HTTP, you can get the header information (the same as `-I` would show)
 288shown before the data by using `-i`/`--include`. curl understands the
 289`-D`/`--dump-header` option when getting files from both FTP and HTTP, and it
 290then stores the headers in the specified file.
 291
 292Store the HTTP headers in a separate file (headers.txt in the example):
 293
 294      curl --dump-header headers.txt curl.se
 295
 296Note that headers stored in a separate file can be useful at a later time if
 297you want curl to use cookies sent by the server. More about that in the
 298cookies section.
 299
 300## POST (HTTP)
 301
 302It is easy to post data using curl. This is done using the `-d <data>` option.
 303The post data must be urlencoded.
 304
 305Post a simple `name` and `phone` guestbook.
 306
 307    curl -d "name=Rafael%20Sagula&phone=3320780" https://www.example.com/guest.cgi
 308
 309Or automatically [URL encode the data](https://everything.curl.dev/http/post/url-encode).
 310
 311    curl --data-urlencode "name=Rafael Sagula&phone=3320780"
 312      https://www.example.com/guest.cgi
 313
 314How to post a form with curl, lesson #1:
 315
 316Dig out all the `<input>` tags in the form that you want to fill in.
 317
 318If there is a normal post, you use `-d` to post. `-d` takes a full post
 319string, which is in the format
 320
 321    <variable1>=<data1>&<variable2>=<data2>&...
 322
 323The variable names are the names set with `"name="` in the `<input>` tags, and
 324the data is the contents you want to fill in for the inputs. The data *must*
 325be properly URL encoded. That means you replace space with + and that you
 326replace weird letters with `%XX` where `XX` is the hexadecimal representation
 327of the letter's ASCII code.
 328
 329Example:
 330
 331(say if `https://example.com` had the following html)
 332
 333```html
 334<form action="post.cgi" method="post">
 335  <input name=user size=10>
 336  <input name=pass type=password size=10>
 337  <input name=id type=hidden value="blablabla">
 338  <input name=ding value="submit">
 339</form>
 340```
 341
 342We want to enter user `foobar` with password `12345`.
 343
 344To post to this, you would enter a curl command line like:
 345
 346    curl -d "user=foobar&pass=12345&id=blablabla&ding=submit"
 347      https://example.com/post.cgi
 348
 349While `-d` uses the application/x-www-form-urlencoded mime-type, generally
 350understood by CGI's and similar, curl also supports the more capable
 351multipart/form-data type. This latter type supports things like file upload.
 352
 353`-F` accepts parameters like `-F "name=contents"`. If you want the contents to
 354be read from a file, use `@filename` as contents. When specifying a file, you
 355can also specify the file content type by appending `;type=<mime type>` to the
 356filename. You can also post the contents of several files in one field.  For
 357example, the field name `coolfiles` is used to send three files, with
 358different content types using the following syntax:
 359
 360    curl -F "coolfiles=@fil1.gif;type=image/gif,fil2.txt,fil3.html"
 361      https://www.example.com/postit.cgi
 362
 363If the content-type is not specified, curl tries to guess from the file
 364extension (it only knows a few), or use the previously specified type (from an
 365earlier file if several files are specified in a list) or else it uses the
 366default type `application/octet-stream`.
 367
 368Emulate a fill-in form with `-F`. Let's say you fill in three fields in a
 369form. One field is a filename which to post, one field is your name and one
 370field is a file description. We want to post the file we have written named
 371`cooltext.txt`. To let curl do the posting of this data instead of your
 372favorite browser, you have to read the HTML source of the form page and find
 373the names of the input fields. In our example, the input field names are
 374`file`, `yourname` and `filedescription`.
 375
 376    curl -F "file=@cooltext.txt" -F "yourname=Daniel"
 377      -F "filedescription=Cool text file with cool text inside"
 378      https://www.example.com/postit.cgi
 379
 380To send two files in one post you can do it in two ways:
 381
 382Send multiple files in a single field with a single field name:
 383
 384    curl -F "pictures=@dog.gif,cat.gif" $URL
 385
 386Send two fields with two field names
 387
 388    curl -F "docpicture=@dog.gif" -F "catpicture=@cat.gif" $URL
 389
 390To send a field value literally without interpreting a leading `@` or `<`, or
 391an embedded `;type=`, use `--form-string` instead of `-F`. This is recommended
 392when the value is obtained from a user or some other unpredictable
 393source. Under these circumstances, using `-F` instead of `--form-string` could
 394allow a user to trick curl into uploading a file.
 395
 396## Referrer
 397
 398An HTTP request has the option to include information about which address
 399referred it to the actual page. curl allows you to specify the referrer to be
 400used on the command line. It is especially useful to fool or trick stupid
 401servers or CGI scripts that rely on that information being available or
 402contain certain data.
 403
 404    curl -e www.example.org https://www.example.com/
 405
 406## User Agent
 407
 408An HTTP request has the option to include information about the browser that
 409generated the request. curl allows it to be specified on the command line. It
 410is especially useful to fool or trick stupid servers or CGI scripts that only
 411accept certain browsers.
 412
 413Example:
 414
 415    curl -A 'Mozilla/3.0 (Win95; I)' https://www.bank.example.com/
 416
 417Other common strings:
 418
 419- `Mozilla/3.0 (Win95; I)` - Netscape Version 3 for Windows 95
 420- `Mozilla/3.04 (Win95; U)` - Netscape Version 3 for Windows 95
 421- `Mozilla/2.02 (OS/2; U)` - Netscape Version 2 for OS/2
 422- `Mozilla/4.04 [en] (X11; U; AIX 4.2; Nav)` - Netscape for AIX
 423- `Mozilla/4.05 [en] (X11; U; Linux 2.0.32 i586)` - Netscape for Linux
 424
 425Note that Internet Explorer tries hard to be compatible in every way:
 426
 427- `Mozilla/4.0 (compatible; MSIE 4.01; Windows 95)` - MSIE for W95
 428
 429Mozilla is not the only possible User-Agent name:
 430
 431- `Konqueror/1.0` - KDE File Manager desktop client
 432- `Lynx/2.7.1 libwww-FM/2.14` - Lynx command line browser
 433
 434## Cookies
 435
 436Cookies are generally used by web servers to keep state information at the
 437client's side. The server sets cookies by sending a response line in the
 438headers that looks like `Set-Cookie: <data>` where the data part then
 439typically contains a set of `NAME=VALUE` pairs (separated by semicolons `;`
 440like `NAME1=VALUE1; NAME2=VALUE2;`). The server can also specify for what path
 441the cookie should be used for (by specifying `path=value`), when the cookie
 442should expire (`expire=DATE`), for what domain to use it (`domain=NAME`) and
 443if it should be used on secure connections only (`secure`).
 444
 445If you have received a page from a server that contains a header like:
 446
 447```http
 448Set-Cookie: sessionid=boo123; path="/foo";
 449```
 450
 451it means the server wants that first pair passed on when we get anything in a
 452path beginning with `/foo`.
 453
 454Example, get a page that wants my name passed in a cookie:
 455
 456    curl -b "name=Daniel" www.example.com
 457
 458curl also has the ability to use previously received cookies in following
 459sessions. If you get cookies from a server and store them in a file in a
 460manner similar to:
 461
 462    curl --dump-header headers www.example.com
 463
 464... you can then in a second connect to that (or another) site, use the
 465cookies from the `headers.txt` file like:
 466
 467    curl -b headers.txt www.example.com
 468
 469While saving headers to a file is a working way to store cookies, it is
 470however error-prone and not the preferred way to do this. Instead, make curl
 471save the incoming cookies using the well-known Netscape cookie format like
 472this:
 473
 474    curl -c cookies.txt www.example.com
 475
 476Note that by specifying `-b` you enable the cookie engine and with `-L` you
 477can make curl follow a `location:` (which often is used in combination with
 478cookies). If a site sends cookies and a location field, you can use a
 479non-existing file to trigger the cookie awareness like:
 480
 481    curl -L -b empty.txt www.example.com
 482
 483The file to read cookies from must be formatted using plain HTTP headers OR as
 484Netscape's cookie file. curl determines what kind it is based on the file
 485contents. In the above command, curl parses the header and store the cookies
 486received from www.example.com. curl sends the stored cookies which match the
 487request to the server as it follows the location. The file `empty.txt` may be
 488a nonexistent file.
 489
 490To read and write cookies from a Netscape cookie file, you can set both `-b`
 491and `-c` to use the same file:
 492
 493    curl -b cookies.txt -c cookies.txt www.example.com
 494
 495## Progress Meter
 496
 497The progress meter exists to show a user that something actually is
 498happening. The different fields in the output have the following meaning:
 499
 500    % Total    % Received % Xferd  Average Speed          Time             Curr.
 501                                   Dload  Upload Total    Current  Left    Speed
 502    0  151M    0 38608    0     0   9406      0  4:41:43  0:00:04  4:41:39  9287
 503
 504From left-to-right:
 505
 506- `%`            - percentage completed of the whole transfer
 507- `Total`        - total size of the whole expected transfer
 508- `%`            - percentage completed of the download
 509- `Received`     - currently downloaded amount of bytes
 510- `%`            - percentage completed of the upload
 511- `Xferd`        - currently uploaded amount of bytes
 512- `Average Speed Dload` - the average transfer speed of the download
 513- `Average Speed Upload` - the average transfer speed of the upload
 514- `Time Total`   - expected time to complete the operation
 515- `Time Current` - time passed since the invoke
 516- `Time Left`    - expected time left to completion
 517- `Curr.Speed`   - the average transfer speed the last 5 seconds (the first
 518                   5 seconds of a transfer is based on less time of course.)
 519
 520The `-#` option displays a totally different progress bar that does not need
 521much explanation!
 522
 523## Speed Limit
 524
 525curl allows the user to set the transfer speed conditions that must be met to
 526let the transfer keep going. By using the switch `-y` and `-Y` you can make
 527curl abort transfers if the transfer speed is below the specified lowest limit
 528for a specified time.
 529
 530To have curl abort the download if the speed is slower than 3000 bytes per
 531second for 1 minute, run:
 532
 533    curl -Y 3000 -y 60 www.far-away.example.com
 534
 535This can be used in combination with the overall time limit, so that the above
 536operation must be completed in whole within 30 minutes:
 537
 538    curl -m 1800 -Y 3000 -y 60 www.far-away.example.com
 539
 540Forcing curl not to transfer data faster than a given rate is also possible,
 541which might be useful if you are using a limited bandwidth connection and you
 542do not want your transfer to use all of it (sometimes referred to as
 543*bandwidth throttle*).
 544
 545Make curl transfer data no faster than 10 kilobytes per second:
 546
 547    curl --limit-rate 10K www.far-away.example.com
 548
 549or
 550
 551    curl --limit-rate 10240 www.far-away.example.com
 552
 553Or prevent curl from uploading data faster than 1 megabyte per second:
 554
 555    curl -T upload --limit-rate 1M ftp://uploads.example.com
 556
 557When using the `--limit-rate` option, the transfer rate is regulated on a
 558per-second basis, which causes the total transfer speed to become lower than
 559the given number. Sometimes of course substantially lower, if your transfer
 560stalls during periods.
 561
 562## Config File
 563
 564curl automatically tries to read the `.curlrc` file (or `_curlrc` file on
 565Microsoft Windows systems) from the user's home directory on startup.
 566
 567The config file could be made up with normal command line switches, but you
 568can also specify the long options without the dashes to make it more
 569readable. You can separate the options and the parameter with spaces, or with
 570`=` or `:`. Comments can be used within the file. If the first letter on a
 571line is a `#`-symbol the rest of the line is treated as a comment.
 572
 573If you want the parameter to contain spaces, you must enclose the entire
 574parameter within double quotes (`"`). Within those quotes, you specify a quote
 575as `\"`.
 576
 577NOTE: You must specify options and their arguments on the same line.
 578
 579Example, set default time out and proxy in a config file:
 580
 581    # We want a 30 minute timeout:
 582    -m 1800
 583    # ... and we use a proxy for all accesses:
 584    proxy = proxy.our.domain.example.com:8080
 585
 586Whitespaces ARE significant at the end of lines, but all whitespace leading
 587up to the first characters of each line are ignored.
 588
 589Prevent curl from reading the default file by using -q as the first command
 590line parameter, like:
 591
 592    curl -q www.example.org
 593
 594Force curl to get and display a local help page in case it is invoked without
 595URL by making a config file similar to:
 596
 597    # default URL to get
 598    url = "https://help.with.curl.example.com/curlhelp.html"
 599
 600You can specify another config file to be read by using the `-K`/`--config`
 601flag. If you set config filename to `-` it reads the config from stdin, which
 602can be handy if you want to hide options from being visible in process tables
 603etc:
 604
 605    echo "user = user:passwd" | curl -K - https://that.secret.example.com
 606
 607## Extra Headers
 608
 609When using curl in your own programs, you may end up needing to pass on your
 610own custom headers when getting a webpage. You can do this by using the `-H`
 611flag.
 612
 613Example, send the header `X-you-and-me: yes` to the server when getting a
 614page:
 615
 616    curl -H "X-you-and-me: yes" love.example.com
 617
 618This can also be useful in case you want curl to send a different text in a
 619header than it normally does. The `-H` header you specify then replaces the
 620header curl would normally send. If you replace an internal header with an
 621empty one, you prevent that header from being sent. To prevent the `Host:`
 622header from being used:
 623
 624    curl -H "Host:" server.example.com
 625
 626## FTP and Path Names
 627
 628Do note that when getting files with a `ftp://` URL, the given path is
 629relative to the directory you enter. To get the file `README` from your home
 630directory at your ftp site, do:
 631
 632    curl ftp://user:passwd@my.example.com/README
 633
 634If you want the README file from the root directory of that same site, you
 635need to specify the absolute filename:
 636
 637    curl ftp://user:passwd@my.example.com//README
 638
 639(I.e with an extra slash in front of the filename.)
 640
 641## SFTP and SCP and Path Names
 642
 643With sftp: and scp: URLs, the path name given is the absolute name on the
 644server. To access a file relative to the remote user's home directory, prefix
 645the file with `/~/` , such as:
 646
 647    curl -u $USER sftp://home.example.com/~/.bashrc
 648
 649## FTP and Firewalls
 650
 651The FTP protocol requires one of the involved parties to open a second
 652connection as soon as data is about to get transferred. There are two ways to
 653do this.
 654
 655The default way for curl is to issue the PASV command which causes the server
 656to open another port and await another connection performed by the
 657client. This is good if the client is behind a firewall that does not allow
 658incoming connections.
 659
 660    curl ftp.example.com
 661
 662If the server, for example, is behind a firewall that does not allow
 663connections on ports other than 21 (or if it does not support the `PASV`
 664command), the other way to do it is to use the `PORT` command and instruct the
 665server to connect to the client on the given IP number and port (as parameters
 666to the PORT command).
 667
 668The `-P` flag to curl supports a few different options. Your machine may have
 669several IP-addresses and/or network interfaces and curl allows you to select
 670which of them to use. Default address can also be used:
 671
 672    curl -P - ftp.example.com
 673
 674Download with `PORT` but use the IP address of our `le0` interface (this does
 675not work on Windows):
 676
 677    curl -P le0 ftp.example.com
 678
 679Download with `PORT` but use 192.168.0.10 as our IP address to use:
 680
 681    curl -P 192.168.0.10 ftp.example.com
 682
 683## Network Interface
 684
 685Get a webpage from a server using a specified port for the interface:
 686
 687    curl --interface eth0:1 https://www.example.com/
 688
 689or
 690
 691    curl --interface 192.168.1.10 https://www.example.com/
 692
 693## HTTPS
 694
 695Secure HTTP requires a TLS library to be installed and used when curl is
 696built. If that is done, curl is capable of retrieving and posting documents
 697using the HTTPS protocol.
 698
 699Example:
 700
 701    curl https://secure.example.com
 702
 703curl is also capable of using client certificates to get/post files from sites
 704that require valid certificates. The only drawback is that the certificate
 705needs to be in PEM-format. PEM is a standard and open format to store
 706certificates with, but it is not used by the most commonly used browsers. If
 707you want curl to use the certificates you use with your favorite browser, you
 708may need to download/compile a converter that can convert your browser's
 709formatted certificates to PEM formatted ones.
 710
 711Example on how to automatically retrieve a document using a certificate with a
 712personal password:
 713
 714    curl -E /path/to/cert.pem:password https://secure.example.com/
 715
 716If you neglect to specify the password on the command line, you are prompted
 717for the correct password before any data can be received.
 718
 719Many older HTTPS servers have problems with specific SSL or TLS versions,
 720which newer versions of OpenSSL etc use, therefore it is sometimes useful to
 721specify what TLS version curl should use.:
 722
 723    curl --tlv1.0 https://secure.example.com/
 724
 725Otherwise, curl attempts to use a sensible TLS default version.
 726
 727## Resuming File Transfers
 728
 729To continue a file transfer where it was previously aborted, curl supports
 730resume on HTTP(S) downloads as well as FTP uploads and downloads.
 731
 732Continue downloading a document:
 733
 734    curl -C - -o file ftp://ftp.example.com/path/file
 735
 736Continue uploading a document:
 737
 738    curl -C - -T file ftp://ftp.example.com/path/file
 739
 740Continue downloading a document from a web server
 741
 742    curl -C - -o file https://www.example.com/
 743
 744## Time Conditions
 745
 746HTTP allows a client to specify a time condition for the document it requests.
 747It is `If-Modified-Since` or `If-Unmodified-Since`. curl allows you to specify
 748them with the `-z`/`--time-cond` flag.
 749
 750For example, you can easily make a download that only gets performed if the
 751remote file is newer than a local copy. It would be made like:
 752
 753    curl -z local.html https://remote.example.com/remote.html
 754
 755Or you can download a file only if the local file is newer than the remote
 756one. Do this by prepending the date string with a `-`, as in:
 757
 758    curl -z -local.html https://remote.example.com/remote.html
 759
 760You can specify a plain text date as condition. Tell curl to only download the
 761file if it was updated since January 12, 2012:
 762
 763    curl -z "Jan 12 2012" https://remote.example.com/remote.html
 764
 765curl accepts a wide range of date formats. You always make the date check the
 766other way around by prepending it with a dash (`-`).
 767
 768## DICT
 769
 770For fun try
 771
 772    curl dict://dict.org/m:curl
 773    curl dict://dict.org/d:heisenbug:jargon
 774    curl dict://dict.org/d:daniel:gcide
 775
 776Aliases for `m` are `match` and `find`, and aliases for `d` are `define` and
 777`lookup`. For example,
 778
 779    curl dict://dict.org/find:curl
 780
 781Commands that break the URL description of the RFC (but not the DICT
 782protocol) are
 783
 784    curl dict://dict.org/show:db
 785    curl dict://dict.org/show:strat
 786
 787Authentication support is still missing
 788
 789## LDAP
 790
 791If you have installed the OpenLDAP library, curl can take advantage of it and
 792offer `ldap://` support. On Windows, curl uses WinLDAP from Platform SDK by
 793default.
 794
 795Default protocol version used by curl is LDAP version 3. Version 2 is used as
 796a fallback mechanism in case version 3 fails to connect.
 797
 798LDAP is a complex thing and writing an LDAP query is not an easy
 799task. Familiarize yourself with the exact syntax description elsewhere. One
 800such place might be: [RFC 2255, The LDAP URL
 801Format](https://curl.se/rfc/rfc2255.txt)
 802
 803To show you an example, this is how to get all people from an LDAP server that
 804has a certain subdomain in their email address:
 805
 806    curl -B "ldap://ldap.example.com/o=frontec??sub?mail=*sth.example.com"
 807
 808You also can use authentication when accessing LDAP catalog:
 809
 810    curl -u user:passwd "ldap://ldap.example.com/o=frontec??sub?mail=*"
 811    curl "ldap://user:passwd@ldap.example.com/o=frontec??sub?mail=*"
 812
 813By default, if user and password are provided, OpenLDAP/WinLDAP uses basic
 814authentication. On Windows you can control this behavior by providing one of
 815`--basic`, `--ntlm` or `--digest` option in curl command line
 816
 817    curl --ntlm "ldap://user:passwd@ldap.example.com/o=frontec??sub?mail=*"
 818
 819On Windows, if no user/password specified, auto-negotiation mechanism is used
 820with current logon credentials (SSPI/SPNEGO).
 821
 822## Environment Variables
 823
 824curl reads and understands the following proxy related environment variables:
 825
 826    http_proxy, HTTPS_PROXY, FTP_PROXY
 827
 828They should be set for protocol-specific proxies. General proxy should be set
 829with
 830
 831    ALL_PROXY
 832
 833A comma-separated list of hostnames that should not go through any proxy is
 834set in (only an asterisk, `*` matches all hosts)
 835
 836    NO_PROXY
 837
 838If the hostname matches one of these strings, or the host is within the domain
 839of one of these strings, transactions with that node is not done over the
 840proxy. When a domain is used, it needs to start with a period. A user can
 841specify that both www.example.com and foo.example.com should not use a proxy
 842by setting `NO_PROXY` to `.example.com`. By including the full name you can
 843exclude specific hostnames, so to make `www.example.com` not use a proxy but
 844still have `foo.example.com` do it, set `NO_PROXY` to `www.example.com`.
 845
 846The usage of the `-x`/`--proxy` flag overrides the environment variables.
 847
 848## Netrc
 849
 850Unix introduced the `.netrc` concept a long time ago. It is a way for a user
 851to specify name and password for commonly visited FTP sites in a file so that
 852you do not have to type them in each time you visit those sites. You realize
 853this is a big security risk if someone else gets hold of your passwords,
 854therefore most Unix programs do not read this file unless it is only readable
 855by yourself (curl does not care though).
 856
 857curl supports `.netrc` files if told to (using the `-n`/`--netrc` and
 858`--netrc-optional` options). This is not restricted to FTP, so curl can use it
 859for all protocols where authentication is used.
 860
 861A simple `.netrc` file could look something like:
 862
 863    machine curl.se login iamdaniel password mysecret
 864
 865## Custom Output
 866
 867To better allow script programmers to get to know about the progress of curl,
 868the `-w`/`--write-out` option was introduced. Using this, you can specify what
 869information from the previous transfer you want to extract.
 870
 871To display the amount of bytes downloaded together with some text and an
 872ending newline:
 873
 874    curl -w 'We downloaded %{size_download} bytes\n' www.example.com
 875
 876## Kerberos FTP Transfer
 877
 878curl supports kerberos4 and kerberos5/GSSAPI for FTP transfers. You need the
 879kerberos package installed and used at curl build time for it to be available.
 880
 881First, get the krb-ticket the normal way, like with the `kinit`/`kauth` tool.
 882Then use curl in way similar to:
 883
 884    curl --krb private ftp://krb4site.example.com -u username:fakepwd
 885
 886There is no use for a password on the `-u` switch, but a blank one makes curl
 887ask for one and you already entered the real password to `kinit`/`kauth`.
 888
 889## TELNET
 890
 891The curl telnet support is basic and easy to use. curl passes all data passed
 892to it on stdin to the remote server. Connect to a remote telnet server using a
 893command line similar to:
 894
 895    curl telnet://remote.example.com
 896
 897Enter the data to pass to the server on stdin. The result is sent to stdout or
 898to the file you specify with `-o`.
 899
 900You might want the `-N`/`--no-buffer` option to switch off the buffered output
 901for slow connections or similar.
 902
 903Pass options to the telnet protocol negotiation, by using the `-t` option. To
 904tell the server we use a vt100 terminal, try something like:
 905
 906    curl -tTTYPE=vt100 telnet://remote.example.com
 907
 908Other interesting options for it `-t` include:
 909
 910- `XDISPLOC=<X display>` Sets the X display location.
 911- `NEW_ENV=<var,val>` Sets an environment variable.
 912
 913NOTE: The telnet protocol does not specify any way to login with a specified
 914user and password so curl cannot do that automatically. To do that, you need to
 915track when the login prompt is received and send the username and password
 916accordingly.
 917
 918## Persistent Connections
 919
 920Specifying multiple files on a single command line makes curl transfer all of
 921them, one after the other in the specified order.
 922
 923libcurl attempts to use persistent connections for the transfers so that the
 924second transfer to the same host can use the same connection that was already
 925initiated and was left open in the previous transfer. This greatly decreases
 926connection time for all but the first transfer and it makes a far better use
 927of the network.
 928
 929Note that curl cannot use persistent connections for transfers that are used
 930in subsequent curl invokes. Try to stuff as many URLs as possible on the same
 931command line if they are using the same host, as that makes the transfers
 932faster. If you use an HTTP proxy for file transfers, practically all transfers
 933are persistent.
 934
 935## Multiple Transfers With A Single Command Line
 936
 937As is mentioned above, you can download multiple files with one command line
 938by adding more URLs. If you want those to get saved to a local file
 939instead of printed to stdout, you need to add one save option for each URL you
 940specify. Note that this also goes for the `-O` option (but not
 941`--remote-name-all`).
 942
 943For example: get two files and use `-O` for the first and a custom file
 944name for the second:
 945
 946    curl -O https://example.com/file.txt ftp://example.com/moo.exe -o moo.jpg
 947
 948You can also upload multiple files in a similar fashion:
 949
 950    curl -T local1 ftp://example.com/moo.exe -T local2 ftp://example.com/moo2.txt
 951
 952## IPv6
 953
 954curl connects to a server with IPv6 when a host lookup returns an IPv6 address
 955and fall back to IPv4 if the connection fails. The `--ipv4` and `--ipv6`
 956options can specify which address to use when both are available. IPv6
 957addresses can also be specified directly in URLs using the syntax:
 958
 959    https://[2001:1890:1112:1::20]/overview.html
 960
 961When this style is used, the `-g` option must be given to stop curl from
 962interpreting the square brackets as special globbing characters. Link local
 963and site local addresses including a scope identifier, such as `fe80::1234%1`,
 964may also be used, but the scope portion must be numeric or match an existing
 965network interface on Linux and the percent character must be URL escaped. The
 966previous example in an SFTP URL might look like:
 967
 968    sftp://[fe80::1234%251]/
 969
 970IPv6 addresses provided other than in URLs (e.g. to the `--proxy`,
 971`--interface` or `--ftp-port` options) should not be URL encoded.
 972
 973## Mailing Lists
 974
 975For your convenience, we have several open mailing lists to discuss curl, its
 976development and things relevant to this. Get all info at
 977https://curl.se/mail/.
 978
 979Please direct curl questions, feature requests and trouble reports to one of
 980these mailing lists instead of mailing any individual.
 981
 982Available lists include:
 983
 984### `curl-users`
 985
 986Users of the command line tool. How to use it, what does not work, new
 987features, related tools, questions, news, installations, compilations,
 988running, porting etc.
 989
 990### `curl-library`
 991
 992Developers using or developing libcurl. Bugs, extensions, improvements.
 993
 994### `curl-announce`
 995
 996Low-traffic. Only receives announcements of new public versions. At worst,
 997that makes something like one or two mails per month, but usually only one
 998mail every second month.
 999
1000### `curl-and-php`
1001
1002Using the curl functions in PHP. Everything curl with a PHP angle. Or PHP with
1003a curl angle.
1004
1005### `curl-and-python`
1006
1007Python hackers using curl with or without the python binding pycurl.