1.\"- 2.\" Copyright (c) 1998-2013 Dag-Erling Smørgrav 3.\" Copyright (c) 2013-2016 Michael Gmelin <freebsd@grem.de> 4.\" All rights reserved. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice, this list of conditions and the following disclaimer in the 13.\" documentation and/or other materials provided with the distribution. 14.\" 15.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 16.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 17.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 18.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 19.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 20.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 21.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 22.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 23.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 24.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 25.\" SUCH DAMAGE. 26.\" 27.\" $FreeBSD$ 28.\" 29.Dd August 28, 2019 30.Dt FETCH 3 31.Os 32.Sh NAME 33.Nm fetchMakeURL , 34.Nm fetchParseURL , 35.Nm fetchFreeURL , 36.Nm fetchXGetURL , 37.Nm fetchGetURL , 38.Nm fetchPutURL , 39.Nm fetchStatURL , 40.Nm fetchListURL , 41.Nm fetchXGet , 42.Nm fetchGet , 43.Nm fetchPut , 44.Nm fetchStat , 45.Nm fetchList , 46.Nm fetchXGetFile , 47.Nm fetchGetFile , 48.Nm fetchPutFile , 49.Nm fetchStatFile , 50.Nm fetchListFile , 51.Nm fetchXGetHTTP , 52.Nm fetchGetHTTP , 53.Nm fetchPutHTTP , 54.Nm fetchStatHTTP , 55.Nm fetchListHTTP , 56.Nm fetchReqHTTP , 57.Nm fetchXGetFTP , 58.Nm fetchGetFTP , 59.Nm fetchPutFTP , 60.Nm fetchStatFTP , 61.Nm fetchListFTP 62.Nd file transfer functions 63.Sh LIBRARY 64.Lb libfetch 65.Sh SYNOPSIS 66.In sys/param.h 67.In stdio.h 68.In fetch.h 69.Ft struct url * 70.Fn fetchMakeURL "const char *scheme" "const char *host" "int port" "const char *doc" "const char *user" "const char *pwd" 71.Ft struct url * 72.Fn fetchParseURL "const char *URL" 73.Ft void 74.Fn fetchFreeURL "struct url *u" 75.Ft FILE * 76.Fn fetchXGetURL "const char *URL" "struct url_stat *us" "const char *flags" 77.Ft FILE * 78.Fn fetchGetURL "const char *URL" "const char *flags" 79.Ft FILE * 80.Fn fetchPutURL "const char *URL" "const char *flags" 81.Ft int 82.Fn fetchStatURL "const char *URL" "struct url_stat *us" "const char *flags" 83.Ft struct url_ent * 84.Fn fetchListURL "const char *URL" "const char *flags" 85.Ft FILE * 86.Fn fetchXGet "struct url *u" "struct url_stat *us" "const char *flags" 87.Ft FILE * 88.Fn fetchGet "struct url *u" "const char *flags" 89.Ft FILE * 90.Fn fetchPut "struct url *u" "const char *flags" 91.Ft int 92.Fn fetchStat "struct url *u" "struct url_stat *us" "const char *flags" 93.Ft struct url_ent * 94.Fn fetchList "struct url *u" "const char *flags" 95.Ft FILE * 96.Fn fetchXGetFile "struct url *u" "struct url_stat *us" "const char *flags" 97.Ft FILE * 98.Fn fetchGetFile "struct url *u" "const char *flags" 99.Ft FILE * 100.Fn fetchPutFile "struct url *u" "const char *flags" 101.Ft int 102.Fn fetchStatFile "struct url *u" "struct url_stat *us" "const char *flags" 103.Ft struct url_ent * 104.Fn fetchListFile "struct url *u" "const char *flags" 105.Ft FILE * 106.Fn fetchXGetHTTP "struct url *u" "struct url_stat *us" "const char *flags" 107.Ft FILE * 108.Fn fetchGetHTTP "struct url *u" "const char *flags" 109.Ft FILE * 110.Fn fetchPutHTTP "struct url *u" "const char *flags" 111.Ft int 112.Fn fetchStatHTTP "struct url *u" "struct url_stat *us" "const char *flags" 113.Ft struct url_ent * 114.Fn fetchListHTTP "struct url *u" "const char *flags" 115.Ft FILE * 116.Fn fetchReqHTTP "struct url *u" "const char *method" "const char *flags" "const char *content_type" "const char *body" 117.Ft FILE * 118.Fn fetchXGetFTP "struct url *u" "struct url_stat *us" "const char *flags" 119.Ft FILE * 120.Fn fetchGetFTP "struct url *u" "const char *flags" 121.Ft FILE * 122.Fn fetchPutFTP "struct url *u" "const char *flags" 123.Ft int 124.Fn fetchStatFTP "struct url *u" "struct url_stat *us" "const char *flags" 125.Ft struct url_ent * 126.Fn fetchListFTP "struct url *u" "const char *flags" 127.Sh DESCRIPTION 128These functions implement a high-level library for retrieving and 129uploading files using Uniform Resource Locators (URLs). 130.Pp 131.Fn fetchParseURL 132takes a URL in the form of a null-terminated string and splits it into 133its components function according to the Common Internet Scheme Syntax 134detailed in RFC1738. 135A regular expression which produces this syntax is: 136.Bd -literal 137 <scheme>:(//(<user>(:<pwd>)?@)?<host>(:<port>)?)?/(<document>)? 138.Ed 139.Pp 140If the URL does not seem to begin with a scheme name, the following 141syntax is assumed: 142.Bd -literal 143 ((<user>(:<pwd>)?@)?<host>(:<port>)?)?/(<document>)? 144.Ed 145.Pp 146Note that some components of the URL are not necessarily relevant to 147all URL schemes. 148For instance, the file scheme only needs the <scheme> and <document> 149components. 150.Pp 151.Fn fetchMakeURL 152and 153.Fn fetchParseURL 154return a pointer to a 155.Vt url 156structure, which is defined as follows in 157.In fetch.h : 158.Bd -literal 159#define URL_SCHEMELEN 16 160#define URL_USERLEN 256 161#define URL_PWDLEN 256 162 163struct url { 164 char scheme[URL_SCHEMELEN+1]; 165 char user[URL_USERLEN+1]; 166 char pwd[URL_PWDLEN+1]; 167 char host[MAXHOSTNAMELEN+1]; 168 int port; 169 char *doc; 170 off_t offset; 171 size_t length; 172 time_t ims_time; 173}; 174.Ed 175.Pp 176The 177.Va ims_time 178field stores the time value for 179.Li If-Modified-Since 180HTTP requests. 181.Pp 182The pointer returned by 183.Fn fetchMakeURL 184or 185.Fn fetchParseURL 186should be freed using 187.Fn fetchFreeURL . 188.Pp 189.Fn fetchXGetURL , 190.Fn fetchGetURL , 191and 192.Fn fetchPutURL 193constitute the recommended interface to the 194.Nm fetch 195library. 196They examine the URL passed to them to determine the transfer 197method, and call the appropriate lower-level functions to perform the 198actual transfer. 199.Fn fetchXGetURL 200also returns the remote document's metadata in the 201.Vt url_stat 202structure pointed to by the 203.Fa us 204argument. 205.Pp 206The 207.Fa flags 208argument is a string of characters which specify transfer options. 209The 210meaning of the individual flags is scheme-dependent, and is detailed 211in the appropriate section below. 212.Pp 213.Fn fetchStatURL 214attempts to obtain the requested document's metadata and fill in the 215structure pointed to by its second argument. 216The 217.Vt url_stat 218structure is defined as follows in 219.In fetch.h : 220.Bd -literal 221struct url_stat { 222 off_t size; 223 time_t atime; 224 time_t mtime; 225}; 226.Ed 227.Pp 228If the size could not be obtained from the server, the 229.Fa size 230field is set to -1. 231If the modification time could not be obtained from the server, the 232.Fa mtime 233field is set to the epoch. 234If the access time could not be obtained from the server, the 235.Fa atime 236field is set to the modification time. 237.Pp 238.Fn fetchListURL 239attempts to list the contents of the directory pointed to by the URL 240provided. 241If successful, it returns a malloced array of 242.Vt url_ent 243structures. 244The 245.Vt url_ent 246structure is defined as follows in 247.In fetch.h : 248.Bd -literal 249struct url_ent { 250 char name[PATH_MAX]; 251 struct url_stat stat; 252}; 253.Ed 254.Pp 255The list is terminated by an entry with an empty name. 256.Pp 257The pointer returned by 258.Fn fetchListURL 259should be freed using 260.Fn free . 261.Pp 262.Fn fetchXGet , 263.Fn fetchGet , 264.Fn fetchPut 265and 266.Fn fetchStat 267are similar to 268.Fn fetchXGetURL , 269.Fn fetchGetURL , 270.Fn fetchPutURL 271and 272.Fn fetchStatURL , 273except that they expect a pre-parsed URL in the form of a pointer to 274a 275.Vt struct url 276rather than a string. 277.Pp 278All of the 279.Fn fetchXGetXXX , 280.Fn fetchGetXXX 281and 282.Fn fetchPutXXX 283functions return a pointer to a stream which can be used to read or 284write data from or to the requested document, respectively. 285Note that 286although the implementation details of the individual access methods 287vary, it can generally be assumed that a stream returned by one of the 288.Fn fetchXGetXXX 289or 290.Fn fetchGetXXX 291functions is read-only, and that a stream returned by one of the 292.Fn fetchPutXXX 293functions is write-only. 294.Sh FILE SCHEME 295.Fn fetchXGetFile , 296.Fn fetchGetFile 297and 298.Fn fetchPutFile 299provide access to documents which are files in a locally mounted file 300system. 301Only the <document> component of the URL is used. 302.Pp 303.Fn fetchXGetFile 304and 305.Fn fetchGetFile 306do not accept any flags. 307.Pp 308.Fn fetchPutFile 309accepts the 310.Ql a 311(append to file) flag. 312If that flag is specified, the data written to 313the stream returned by 314.Fn fetchPutFile 315will be appended to the previous contents of the file, instead of 316replacing them. 317.Sh FTP SCHEME 318.Fn fetchXGetFTP , 319.Fn fetchGetFTP 320and 321.Fn fetchPutFTP 322implement the FTP protocol as described in RFC959. 323.Pp 324If the 325.Ql P 326(not passive) flag is specified, an active (rather than passive) 327connection will be attempted. 328.Pp 329The 330.Ql p 331flag is supported for compatibility with earlier versions where active 332connections were the default. 333It has precedence over the 334.Ql P 335flag, so if both are specified, 336.Nm 337will use a passive connection. 338.Pp 339If the 340.Ql l 341(low) flag is specified, data sockets will be allocated in the low (or 342default) port range instead of the high port range (see 343.Xr ip 4 ) . 344.Pp 345If the 346.Ql d 347(direct) flag is specified, 348.Fn fetchXGetFTP , 349.Fn fetchGetFTP 350and 351.Fn fetchPutFTP 352will use a direct connection even if a proxy server is defined. 353.Pp 354If no user name or password is given, the 355.Nm fetch 356library will attempt an anonymous login, with user name "anonymous" 357and password "anonymous@<hostname>". 358.Sh HTTP SCHEME 359The 360.Fn fetchXGetHTTP , 361.Fn fetchGetHTTP , 362.Fn fetchPutHTTP 363and 364.Fn fetchReqHTTP 365functions implement the HTTP/1.1 protocol. 366With a little luck, there is 367even a chance that they comply with RFC2616 and RFC2617. 368.Pp 369If the 370.Ql d 371(direct) flag is specified, 372.Fn fetchXGetHTTP , 373.Fn fetchGetHTTP 374and 375.Fn fetchPutHTTP 376will use a direct connection even if a proxy server is defined. 377.Pp 378If the 379.Ql i 380(if-modified-since) flag is specified, and 381the 382.Va ims_time 383field is set in 384.Vt "struct url" , 385then 386.Fn fetchXGetHTTP 387and 388.Fn fetchGetHTTP 389will send a conditional 390.Li If-Modified-Since 391HTTP header to only fetch the content if it is newer than 392.Va ims_time . 393.Pp 394The function 395.Fn fetchReqHTTP 396can be used to make requests with an arbitrary HTTP verb, 397including POST, DELETE, CONNECT, OPTIONS, TRACE or PATCH. 398This can be done by setting the argument 399.Fa method 400to the intended verb, such as 401.Ql POST , 402and 403.Fa body 404to the content. 405.Pp 406Since there seems to be no good way of implementing the HTTP PUT 407method in a manner consistent with the rest of the 408.Nm fetch 409library, 410.Fn fetchPutHTTP 411is currently unimplemented. 412.Sh HTTPS SCHEME 413Based on HTTP SCHEME. 414By default the peer is verified using the CA bundle located in 415.Pa /usr/local/etc/ssl/cert.pem . 416If this file does not exist, 417.Pa /etc/ssl/cert.pem 418is used instead. 419If neither file exists, and 420.Ev SSL_CA_CERT_PATH 421has not been set, 422OpenSSL's default CA cert and path settings apply. 423The certificate bundle can contain multiple CA certificates. 424A common source of a current CA bundle is 425.Pa \%security/ca_root_nss . 426.Pp 427The CA bundle used for peer verification can be changed by setting the 428environment variables 429.Ev SSL_CA_CERT_FILE 430to point to a concatenated bundle of trusted certificates and 431.Ev SSL_CA_CERT_PATH 432to point to a directory containing hashes of trusted CAs (see 433.Xr verify 1 ) . 434.Pp 435A certificate revocation list (CRL) can be used by setting the 436environment variable 437.Ev SSL_CRL_FILE 438(see 439.Xr crl 1 ) . 440.Pp 441Peer verification can be disabled by setting the environment variable 442.Ev SSL_NO_VERIFY_PEER . 443Note that this also disables CRL checking. 444.Pp 445By default the service identity is verified according to the rules 446detailed in RFC6125 (also known as hostname verification). 447This feature can be disabled by setting the environment variable 448.Ev SSL_NO_VERIFY_HOSTNAME . 449.Pp 450Client certificate based authentication is supported. 451The environment variable 452.Ev SSL_CLIENT_CERT_FILE 453should be set to point to a file containing key and client certificate 454to be used in PEM format. 455When a PEM-format key is in a separate file from the client certificate, 456the environment variable 457.Ev SSL_CLIENT_KEY_FILE 458can be set to point to the key file. 459In case the key uses a password, the user will be prompted on standard 460input (see 461.Xr PEM 3 ) . 462.Pp 463By default 464.Nm libfetch 465allows TLSv1 and newer when negotiating the connecting with the remote 466peer. 467You can change this behavior by setting the 468.Ev SSL_ALLOW_SSL3 469environment variable to allow SSLv3 and 470.Ev SSL_NO_TLS1 , 471.Ev SSL_NO_TLS1_1 and 472.Ev SSL_NO_TLS1_2 473to disable TLS 1.0, 1.1 and 1.2 respectively. 474.Sh AUTHENTICATION 475Apart from setting the appropriate environment variables and 476specifying the user name and password in the URL or the 477.Vt struct url , 478the calling program has the option of defining an authentication 479function with the following prototype: 480.Pp 481.Ft int 482.Fn myAuthMethod "struct url *u" 483.Pp 484The callback function should fill in the 485.Fa user 486and 487.Fa pwd 488fields in the provided 489.Vt struct url 490and return 0 on success, or any other value to indicate failure. 491.Pp 492To register the authentication callback, simply set 493.Va fetchAuthMethod 494to point at it. 495The callback will be used whenever a site requires authentication and 496the appropriate environment variables are not set. 497.Pp 498This interface is experimental and may be subject to change. 499.Sh RETURN VALUES 500.Fn fetchParseURL 501returns a pointer to a 502.Vt struct url 503containing the individual components of the URL. 504If it is 505unable to allocate memory, or the URL is syntactically incorrect, 506.Fn fetchParseURL 507returns a NULL pointer. 508.Pp 509The 510.Fn fetchStat 511functions return 0 on success and -1 on failure. 512.Pp 513All other functions return a stream pointer which may be used to 514access the requested document, or NULL if an error occurred. 515.Pp 516The following error codes are defined in 517.In fetch.h : 518.Bl -tag -width 18n 519.It Bq Er FETCH_ABORT 520Operation aborted 521.It Bq Er FETCH_AUTH 522Authentication failed 523.It Bq Er FETCH_DOWN 524Service unavailable 525.It Bq Er FETCH_EXISTS 526File exists 527.It Bq Er FETCH_FULL 528File system full 529.It Bq Er FETCH_INFO 530Informational response 531.It Bq Er FETCH_MEMORY 532Insufficient memory 533.It Bq Er FETCH_MOVED 534File has moved 535.It Bq Er FETCH_NETWORK 536Network error 537.It Bq Er FETCH_OK 538No error 539.It Bq Er FETCH_PROTO 540Protocol error 541.It Bq Er FETCH_RESOLV 542Resolver error 543.It Bq Er FETCH_SERVER 544Server error 545.It Bq Er FETCH_TEMP 546Temporary error 547.It Bq Er FETCH_TIMEOUT 548Operation timed out 549.It Bq Er FETCH_UNAVAIL 550File is not available 551.It Bq Er FETCH_UNKNOWN 552Unknown error 553.It Bq Er FETCH_URL 554Invalid URL 555.El 556.Pp 557The accompanying error message includes a protocol-specific error code 558and message, like "File is not available (404 Not Found)" 559.Sh ENVIRONMENT 560.Bl -tag -width ".Ev FETCH_BIND_ADDRESS" 561.It Ev FETCH_BIND_ADDRESS 562Specifies a hostname or IP address to which sockets used for outgoing 563connections will be bound. 564.It Ev FTP_LOGIN 565Default FTP login if none was provided in the URL. 566.It Ev FTP_PASSIVE_MODE 567If set to 568.Ql no , 569forces the FTP code to use active mode. 570If set to any other value, forces passive mode even if the application 571requested active mode. 572.It Ev FTP_PASSWORD 573Default FTP password if the remote server requests one and none was 574provided in the URL. 575.It Ev FTP_PROXY 576URL of the proxy to use for FTP requests. 577The document part is ignored. 578FTP and HTTP proxies are supported; if no scheme is specified, FTP is 579assumed. 580If the proxy is an FTP proxy, 581.Nm libfetch 582will send 583.Ql user@host 584as user name to the proxy, where 585.Ql user 586is the real user name, and 587.Ql host 588is the name of the FTP server. 589.Pp 590If this variable is set to an empty string, no proxy will be used for 591FTP requests, even if the 592.Ev HTTP_PROXY 593variable is set. 594.It Ev ftp_proxy 595Same as 596.Ev FTP_PROXY , 597for compatibility. 598.It Ev HTTP_ACCEPT 599Specifies the value of the 600.Va Accept 601header for HTTP requests. 602If empty, no 603.Va Accept 604header is sent. 605The default is 606.Dq */* . 607.It Ev HTTP_AUTH 608Specifies HTTP authorization parameters as a colon-separated list of 609items. 610The first and second item are the authorization scheme and realm 611respectively; further items are scheme-dependent. 612Currently, the 613.Dq basic 614and 615.Dq digest 616authorization methods are supported. 617.Pp 618Both methods require two parameters: the user name and 619password, in that order. 620.Pp 621This variable is only used if the server requires authorization and 622no user name or password was specified in the URL. 623.It Ev HTTP_PROXY 624URL of the proxy to use for HTTP requests. 625The document part is ignored. 626Only HTTP proxies are supported for HTTP requests. 627If no port number is specified, the default is 3128. 628.Pp 629Note that this proxy will also be used for FTP documents, unless the 630.Ev FTP_PROXY 631variable is set. 632.It Ev http_proxy 633Same as 634.Ev HTTP_PROXY , 635for compatibility. 636.It Ev HTTP_PROXY_AUTH 637Specifies authorization parameters for the HTTP proxy in the same 638format as the 639.Ev HTTP_AUTH 640variable. 641.Pp 642This variable is used if and only if connected to an HTTP proxy, and 643is ignored if a user and/or a password were specified in the proxy 644URL. 645.It Ev HTTP_REFERER 646Specifies the referrer URL to use for HTTP requests. 647If set to 648.Dq auto , 649the document URL will be used as referrer URL. 650.It Ev HTTP_USER_AGENT 651Specifies the User-Agent string to use for HTTP requests. 652This can be useful when working with HTTP origin or proxy servers that 653differentiate between user agents. 654If defined but empty, no User-Agent header is sent. 655.It Ev NETRC 656Specifies a file to use instead of 657.Pa ~/.netrc 658to look up login names and passwords for FTP and HTTP sites as well as 659HTTP proxies. 660See 661.Xr ftp 1 662for a description of the file format. 663.It Ev NO_PROXY 664Either a single asterisk, which disables the use of proxies 665altogether, or a comma- or whitespace-separated list of hosts for 666which proxies should not be used. 667.It Ev no_proxy 668Same as 669.Ev NO_PROXY , 670for compatibility. 671.It Ev SOCKS5_PROXY 672Uses SOCKS version 5 to make connection. 673The format must be the IP or hostname followed by a colon for the port. 674IPv6 addresses must enclose the address in brackets. 675If no port is specified, the default is 1080. 676This setting will supercede a connection to an 677.Ev HTTP_PROXY . 678.It Ev SSL_ALLOW_SSL3 679Allow SSL version 3 when negotiating the connection (not recommended). 680.It Ev SSL_CA_CERT_FILE 681CA certificate bundle containing trusted CA certificates. 682Default value: See HTTPS SCHEME above. 683.It Ev SSL_CA_CERT_PATH 684Path containing trusted CA hashes. 685.It Ev SSL_CLIENT_CERT_FILE 686PEM encoded client certificate/key which will be used in 687client certificate authentication. 688.It Ev SSL_CLIENT_KEY_FILE 689PEM encoded client key in case key and client certificate 690are stored separately. 691.It Ev SSL_CRL_FILE 692File containing certificate revocation list. 693.It Ev SSL_NO_TLS1 694Do not allow TLS version 1.0 when negotiating the connection. 695.It Ev SSL_NO_TLS1_1 696Do not allow TLS version 1.1 when negotiating the connection. 697.It Ev SSL_NO_TLS1_2 698Do not allow TLS version 1.2 when negotiating the connection. 699.It Ev SSL_NO_VERIFY_HOSTNAME 700If set, do not verify that the hostname matches the subject of the 701certificate presented by the server. 702.It Ev SSL_NO_VERIFY_PEER 703If set, do not verify the peer certificate against trusted CAs. 704.El 705.Sh EXAMPLES 706To access a proxy server on 707.Pa proxy.example.com 708port 8080, set the 709.Ev HTTP_PROXY 710environment variable in a manner similar to this: 711.Pp 712.Dl HTTP_PROXY=http://proxy.example.com:8080 713.Pp 714If the proxy server requires authentication, there are 715two options available for passing the authentication data. 716The first method is by using the proxy URL: 717.Pp 718.Dl HTTP_PROXY=http://<user>:<pwd>@proxy.example.com:8080 719.Pp 720The second method is by using the 721.Ev HTTP_PROXY_AUTH 722environment variable: 723.Bd -literal -offset indent 724HTTP_PROXY=http://proxy.example.com:8080 725HTTP_PROXY_AUTH=basic:*:<user>:<pwd> 726.Ed 727.Pp 728To disable the use of a proxy for an HTTP server running on the local 729host, define 730.Ev NO_PROXY 731as follows: 732.Bd -literal -offset indent 733NO_PROXY=localhost,127.0.0.1 734.Ed 735.Pp 736To use a SOCKS5 proxy, set the 737.Ev SOCKS5_PROXY 738environment variable to a 739valid host or IP followed by an optional colon and the port. 740IPv6 addresses must be enclosed in brackets. 741The following are examples of valid settings: 742.Bd -literal -offset indent 743SOCKS5_PROXY=proxy.example.com 744SOCKS5_PROXY=proxy.example.com:1080 745SOCKS5_PROXY=192.0.2.0 746SOCKS5_PROXY=198.51.100.0:1080 747SOCKS5_PROXY=[2001:db8::1] 748SOCKS5_PROXY=[2001:db8::2]:1080 749.Ed 750.Pp 751Access HTTPS website without any certificate verification whatsoever: 752.Bd -literal -offset indent 753SSL_NO_VERIFY_PEER=1 754SSL_NO_VERIFY_HOSTNAME=1 755.Ed 756.Pp 757Access HTTPS website using client certificate based authentication 758and a private CA: 759.Bd -literal -offset indent 760SSL_CLIENT_CERT_FILE=/path/to/client.pem 761SSL_CA_CERT_FILE=/path/to/myca.pem 762.Ed 763.Sh SEE ALSO 764.Xr fetch 1 , 765.Xr ip 4 766.Rs 767.%A J. Postel 768.%A J. K. Reynolds 769.%D October 1985 770.%B File Transfer Protocol 771.%O RFC959 772.Re 773.Rs 774.%A P. Deutsch 775.%A A. Emtage 776.%A A. Marine. 777.%D May 1994 778.%T How to Use Anonymous FTP 779.%O RFC1635 780.Re 781.Rs 782.%A T. Berners-Lee 783.%A L. Masinter 784.%A M. McCahill 785.%D December 1994 786.%T Uniform Resource Locators (URL) 787.%O RFC1738 788.Re 789.Rs 790.%A R. Fielding 791.%A J. Gettys 792.%A J. Mogul 793.%A H. Frystyk 794.%A L. Masinter 795.%A P. Leach 796.%A T. Berners-Lee 797.%D January 1999 798.%B Hypertext Transfer Protocol -- HTTP/1.1 799.%O RFC2616 800.Re 801.Rs 802.%A J. Franks 803.%A P. Hallam-Baker 804.%A J. Hostetler 805.%A S. Lawrence 806.%A P. Leach 807.%A A. Luotonen 808.%A L. Stewart 809.%D June 1999 810.%B HTTP Authentication: Basic and Digest Access Authentication 811.%O RFC2617 812.Re 813.Sh HISTORY 814The 815.Nm fetch 816library first appeared in 817.Fx 3.0 . 818.Sh AUTHORS 819.An -nosplit 820The 821.Nm fetch 822library was mostly written by 823.An Dag-Erling Sm\(/orgrav Aq Mt des@FreeBSD.org 824with numerous suggestions and contributions from 825.An Jordan K. Hubbard Aq Mt jkh@FreeBSD.org , 826.An Eugene Skepner Aq Mt eu@qub.com , 827.An Hajimu Umemoto Aq Mt ume@FreeBSD.org , 828.An Henry Whincup Aq Mt henry@techiebod.com , 829.An Jukka A. Ukkonen Aq Mt jau@iki.fi , 830.An Jean-Fran\(,cois Dockes Aq Mt jf@dockes.org , 831.An Michael Gmelin Aq Mt freebsd@grem.de 832and others. 833It replaces the older 834.Nm ftpio 835library written by 836.An Poul-Henning Kamp Aq Mt phk@FreeBSD.org 837and 838.An Jordan K. Hubbard Aq Mt jkh@FreeBSD.org . 839.Pp 840This manual page was written by 841.An Dag-Erling Sm\(/orgrav Aq Mt des@FreeBSD.org 842and 843.An Michael Gmelin Aq Mt freebsd@grem.de . 844.Sh BUGS 845Some parts of the library are not yet implemented. 846The most notable 847examples of this are 848.Fn fetchPutHTTP , 849.Fn fetchListHTTP , 850.Fn fetchListFTP 851and FTP proxy support. 852.Pp 853There is no way to select a proxy at run-time other than setting the 854.Ev HTTP_PROXY 855or 856.Ev FTP_PROXY 857environment variables as appropriate. 858.Pp 859.Nm libfetch 860does not understand or obey 305 (Use Proxy) replies. 861.Pp 862Error numbers are unique only within a certain context; the error 863codes used for FTP and HTTP overlap, as do those used for resolver and 864system errors. 865For instance, error code 202 means "Command not 866implemented, superfluous at this site" in an FTP context and 867"Accepted" in an HTTP context. 868.Pp 869.Fn fetchStatFTP 870does not check that the result of an MDTM command is a valid date. 871.Pp 872In case password protected keys are used for client certificate based 873authentication the user is prompted for the password on each and every 874fetch operation. 875.Pp 876The man page is incomplete, poorly written and produces badly 877formatted text. 878.Pp 879The error reporting mechanism is unsatisfactory. 880.Pp 881Some parts of the code are not fully reentrant. 882