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.Dd June 27, 2026 28.Dt FETCH 3 29.Os 30.Sh NAME 31.Nm fetchMakeURL , 32.Nm fetchParseURL , 33.Nm fetchFreeURL , 34.Nm fetchXGetURL , 35.Nm fetchGetURL , 36.Nm fetchPutURL , 37.Nm fetchStatURL , 38.Nm fetchListURL , 39.Nm fetchXGet , 40.Nm fetchGet , 41.Nm fetchPut , 42.Nm fetchStat , 43.Nm fetchList , 44.Nm fetchXGetFile , 45.Nm fetchGetFile , 46.Nm fetchPutFile , 47.Nm fetchStatFile , 48.Nm fetchListFile , 49.Nm fetchXGetHTTP , 50.Nm fetchGetHTTP , 51.Nm fetchPutHTTP , 52.Nm fetchStatHTTP , 53.Nm fetchListHTTP , 54.Nm fetchReqHTTP , 55.Nm fetchXGetFTP , 56.Nm fetchGetFTP , 57.Nm fetchPutFTP , 58.Nm fetchStatFTP , 59.Nm fetchListFTP , 60.Nm fetchTimeout 61.Nd file transfer functions 62.Sh LIBRARY 63.Lb libfetch 64.Sh SYNOPSIS 65.In sys/param.h 66.In stdio.h 67.In fetch.h 68.Vt extern int fetchTimeout; 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.Pp 295The 296.Va fetchTimeout 297global variable can be set to the amount of time in seconds to wait 298for each network operation, including each connection attempt (keeping 299in mind that one name may resolve to multiple addresses which will 300each be tried sequentially), each read, and each write. 301Thus, 302.Va fetchTimeout 303can safely be set to a relatively low value without fear of 304prematurely terminating a long transfer; it will only kick in if the 305transfer is stalled. 306.Sh FILE SCHEME 307.Fn fetchXGetFile , 308.Fn fetchGetFile 309and 310.Fn fetchPutFile 311provide access to documents which are files in a locally mounted file 312system. 313Only the <document> component of the URL is used. 314.Pp 315.Fn fetchXGetFile 316and 317.Fn fetchGetFile 318do not accept any flags. 319.Pp 320.Fn fetchPutFile 321accepts the 322.Ql a 323(append to file) flag. 324If that flag is specified, the data written to 325the stream returned by 326.Fn fetchPutFile 327will be appended to the previous contents of the file, instead of 328replacing them. 329.Sh FTP SCHEME 330.Fn fetchXGetFTP , 331.Fn fetchGetFTP 332and 333.Fn fetchPutFTP 334implement the FTP protocol as described in RFC959. 335.Pp 336If the 337.Ql P 338(not passive) flag is specified, an active (rather than passive) 339connection will be attempted. 340.Pp 341The 342.Ql p 343flag is supported for compatibility with earlier versions where active 344connections were the default. 345It has precedence over the 346.Ql P 347flag, so if both are specified, 348.Nm 349will use a passive connection. 350.Pp 351If the 352.Ql l 353(low) flag is specified, data sockets will be allocated in the low (or 354default) port range instead of the high port range (see 355.Xr ip 4 ) . 356.Pp 357If the 358.Ql d 359(direct) flag is specified, 360.Fn fetchXGetFTP , 361.Fn fetchGetFTP 362and 363.Fn fetchPutFTP 364will use a direct connection even if a proxy server is defined. 365.Pp 366If no user name or password is given, the 367.Nm fetch 368library will attempt an anonymous login, with user name "anonymous" 369and password "anonymous@<hostname>". 370.Sh HTTP SCHEME 371The 372.Fn fetchXGetHTTP , 373.Fn fetchGetHTTP , 374.Fn fetchPutHTTP 375and 376.Fn fetchReqHTTP 377functions implement the HTTP/1.1 protocol. 378With a little luck, there is 379even a chance that they comply with RFC2616 and RFC2617. 380.Pp 381If the 382.Ql d 383(direct) flag is specified, 384.Fn fetchXGetHTTP , 385.Fn fetchGetHTTP 386and 387.Fn fetchPutHTTP 388will use a direct connection even if a proxy server is defined. 389.Pp 390If the 391.Ql i 392(if-modified-since) flag is specified, and 393the 394.Va ims_time 395field is set in 396.Vt "struct url" , 397then 398.Fn fetchXGetHTTP 399and 400.Fn fetchGetHTTP 401will send a conditional 402.Li If-Modified-Since 403HTTP header to only fetch the content if it is newer than 404.Va ims_time . 405.Pp 406The function 407.Fn fetchReqHTTP 408can be used to make requests with an arbitrary HTTP verb, 409including POST, DELETE, CONNECT, OPTIONS, TRACE or PATCH. 410This can be done by setting the argument 411.Fa method 412to the intended verb, such as 413.Ql POST , 414and 415.Fa body 416to the content. 417.Pp 418Since there seems to be no good way of implementing the HTTP PUT 419method in a manner consistent with the rest of the 420.Nm fetch 421library, 422.Fn fetchPutHTTP 423is currently unimplemented. 424.Sh HTTPS SCHEME 425Based on HTTP SCHEME. 426The CA bundle used for peer verification can be changed by setting the 427environment variables 428.Ev SSL_CA_CERT_FILE 429to point to a concatenated bundle of trusted certificates and 430.Ev SSL_CA_CERT_PATH 431to point to a directory containing hashes of trusted CAs (see 432.Xr verify 1 ) . 433.Pp 434A certificate revocation list (CRL) can be used by setting the 435environment variable 436.Ev SSL_CRL_FILE 437(see 438.Xr crl 1 ) . 439.Pp 440Peer verification can be disabled by setting the environment variable 441.Ev SSL_NO_VERIFY_PEER . 442Note that this also disables CRL checking. 443.Pp 444By default the service identity is verified according to the rules 445detailed in RFC6125 (also known as hostname verification). 446This feature can be disabled by setting the environment variable 447.Ev SSL_NO_VERIFY_HOSTNAME . 448.Pp 449Client certificate based authentication is supported. 450The environment variable 451.Ev SSL_CLIENT_CERT_FILE 452should be set to point to a file containing key and client certificate 453to be used in PEM format. 454When a PEM-format key is in a separate file from the client certificate, 455the environment variable 456.Ev SSL_CLIENT_KEY_FILE 457can be set to point to the key file. 458In case the key uses a password, the user will be prompted on standard 459input. 460.Pp 461By default 462.Nm libfetch 463allows TLSv1 and newer when negotiating the connecting with the remote 464peer. 465You can change this behavior by setting the 466.Ev SSL_NO_TLS1 , 467.Ev SSL_NO_TLS1_1 , 468.Ev SSL_NO_TLS1_2 and 469.Ev SSL_NO_TLS1_3 470environment variables to disable TLS 1.0, 1.1, 1.2 and 1.3 471respectively. 472.Sh AUTHENTICATION 473Apart from setting the appropriate environment variables and 474specifying the user name and password in the URL or the 475.Vt struct url , 476the calling program has the option of defining an authentication 477function with the following prototype: 478.Pp 479.Ft int 480.Fn myAuthMethod "struct url *u" 481.Pp 482The callback function should fill in the 483.Fa user 484and 485.Fa pwd 486fields in the provided 487.Vt struct url 488and return 0 on success, or any other value to indicate failure. 489.Pp 490To register the authentication callback, simply set 491.Va fetchAuthMethod 492to point at it. 493The callback will be used whenever a site requires authentication and 494the appropriate environment variables are not set. 495.Pp 496This interface is experimental and may be subject to change. 497.Sh RETURN VALUES 498.Fn fetchParseURL 499returns a pointer to a 500.Vt struct url 501containing the individual components of the URL. 502If it is 503unable to allocate memory, or the URL is syntactically incorrect, 504.Fn fetchParseURL 505returns a NULL pointer. 506.Pp 507The 508.Fn fetchStat 509functions return 0 on success and -1 on failure. 510.Pp 511All other functions return a stream pointer which may be used to 512access the requested document, or NULL if an error occurred. 513.Pp 514The following error codes are defined in 515.In fetch.h : 516.Bl -tag -width 18n 517.It Bq Er FETCH_ABORT 518Operation aborted 519.It Bq Er FETCH_AUTH 520Authentication failed 521.It Bq Er FETCH_DOWN 522Service unavailable 523.It Bq Er FETCH_EXISTS 524File exists 525.It Bq Er FETCH_FULL 526File system full 527.It Bq Er FETCH_INFO 528Informational response 529.It Bq Er FETCH_MEMORY 530Insufficient memory 531.It Bq Er FETCH_MOVED 532File has moved 533.It Bq Er FETCH_NETWORK 534Network error 535.It Bq Er FETCH_OK 536No error 537.It Bq Er FETCH_PROTO 538Protocol error 539.It Bq Er FETCH_RESOLV 540Resolver error 541.It Bq Er FETCH_SERVER 542Server error 543.It Bq Er FETCH_TEMP 544Temporary error 545.It Bq Er FETCH_TIMEOUT 546Operation timed out 547.It Bq Er FETCH_UNAVAIL 548File is not available 549.It Bq Er FETCH_UNKNOWN 550Unknown error 551.It Bq Er FETCH_URL 552Invalid URL 553.El 554.Pp 555The accompanying error message includes a protocol-specific error code 556and message, like "File is not available (404 Not Found)" 557.Sh ENVIRONMENT 558.Bl -tag -width ".Ev FETCH_BIND_ADDRESS" 559.It Ev FETCH_BIND_ADDRESS 560Specifies a hostname or IP address to which sockets used for outgoing 561connections will be bound. 562.It Ev FTP_LOGIN 563Default FTP login if none was provided in the URL. 564.It Ev FTP_PASSIVE_MODE 565If set to 566.Ql no , 567forces the FTP code to use active mode. 568If set to any other value, forces passive mode even if the application 569requested active mode. 570.It Ev FTP_PASSWORD 571Default FTP password if the remote server requests one and none was 572provided in the URL. 573.It Ev FTP_PROXY 574URL of the proxy to use for FTP requests. 575The document part is ignored. 576FTP and HTTP proxies are supported; if no scheme is specified, FTP is 577assumed. 578If the proxy is an FTP proxy, 579.Nm libfetch 580will send 581.Ql user@host 582as user name to the proxy, where 583.Ql user 584is the real user name, and 585.Ql host 586is the name of the FTP server. 587.Pp 588If this variable is set to an empty string, no proxy will be used for 589FTP requests, even if the 590.Ev HTTP_PROXY 591variable is set. 592.It Ev ftp_proxy 593Same as 594.Ev FTP_PROXY , 595for compatibility. 596.It Ev HTTP_ACCEPT 597Specifies the value of the 598.Va Accept 599header for HTTP requests. 600If empty, no 601.Va Accept 602header is sent. 603The default is 604.Dq */* . 605.It Ev HTTP_AUTH 606Specifies HTTP authorization parameters as a colon-separated list of 607items. 608The first and second item are the authorization scheme and realm 609respectively; further items are scheme-dependent. 610Currently, the 611.Dq basic 612and 613.Dq digest 614authorization methods are supported. 615.Pp 616Both methods require two parameters: the user name and 617password, in that order. 618.Pp 619This variable is only used if the server requires authorization and 620no user name or password was specified in the URL. 621.It Ev HTTP_PROXY 622URL of the proxy to use for HTTP requests. 623The document part is ignored. 624Only HTTP proxies are supported for HTTP requests. 625If no port number is specified, the default is 3128. 626.Pp 627Note that this proxy will also be used for FTP documents, unless the 628.Ev FTP_PROXY 629variable is set. 630.It Ev http_proxy 631Same as 632.Ev HTTP_PROXY , 633for compatibility. 634.It Ev HTTP_PROXY_AUTH 635Specifies authorization parameters for the HTTP proxy in the same 636format as the 637.Ev HTTP_AUTH 638variable. 639.Pp 640This variable is used if and only if connected to an HTTP proxy, and 641is ignored if a user and/or a password were specified in the proxy 642URL. 643.It Ev HTTP_REFERER 644Specifies the referrer URL to use for HTTP requests. 645If set to 646.Dq auto , 647the document URL will be used as referrer URL. 648.It Ev HTTP_USER_AGENT 649Specifies the User-Agent string to use for HTTP requests. 650This can be useful when working with HTTP origin or proxy servers that 651differentiate between user agents. 652If defined but empty, no User-Agent header is sent. 653.It Ev NETRC 654Specifies a file to use instead of 655.Pa ~/.netrc 656to look up login names and passwords for FTP and HTTP sites as well as 657HTTP proxies. 658See 659.Xr ftp 1 660for a description of the file format. 661.It Ev NO_PROXY 662Either a single asterisk, which disables the use of proxies 663altogether, or a comma- or whitespace-separated list of hosts for 664which proxies should not be used. 665.It Ev no_proxy 666Same as 667.Ev NO_PROXY , 668for compatibility. 669.It Ev SOCKS5_PROXY 670Uses SOCKS version 5 to make connection. 671The format must be the IP or hostname followed by a colon for the port. 672IPv6 addresses must enclose the address in brackets. 673If no port is specified, the default is 1080. 674This setting will supercede a connection to an 675.Ev HTTP_PROXY . 676.It Ev SSL_CA_CERT_FILE 677CA certificate bundle containing trusted CA certificates. 678Default value: See HTTPS SCHEME above. 679.It Ev SSL_CA_CERT_PATH 680Path containing trusted CA hashes. 681.It Ev SSL_CLIENT_CERT_FILE 682PEM encoded client certificate/key which will be used in 683client certificate authentication. 684.It Ev SSL_CLIENT_KEY_FILE 685PEM encoded client key in case key and client certificate 686are stored separately. 687.It Ev SSL_CRL_FILE 688File containing certificate revocation list. 689.It Ev SSL_NO_TLS1 690Do not allow TLS version 1.0 when negotiating the connection. 691.It Ev SSL_NO_TLS1_1 692Do not allow TLS version 1.1 when negotiating the connection. 693.It Ev SSL_NO_TLS1_2 694Do not allow TLS version 1.2 when negotiating the connection. 695.It Ev SSL_NO_TLS1_3 696Do not allow TLS version 1.3 when negotiating the connection. 697.It Ev SSL_NO_VERIFY_HOSTNAME 698If set, do not verify that the hostname matches the subject of the 699certificate presented by the server. 700.It Ev SSL_NO_VERIFY_PEER 701If set, do not verify the peer certificate against trusted CAs. 702.El 703.Sh EXAMPLES 704To access a proxy server on 705.Pa proxy.example.com 706port 8080, set the 707.Ev HTTP_PROXY 708environment variable in a manner similar to this: 709.Pp 710.Dl HTTP_PROXY=http://proxy.example.com:8080 711.Pp 712If the proxy server requires authentication, there are 713two options available for passing the authentication data. 714The first method is by using the proxy URL: 715.Pp 716.Dl HTTP_PROXY=http://<user>:<pwd>@proxy.example.com:8080 717.Pp 718The second method is by using the 719.Ev HTTP_PROXY_AUTH 720environment variable: 721.Bd -literal -offset indent 722HTTP_PROXY=http://proxy.example.com:8080 723HTTP_PROXY_AUTH=basic:*:<user>:<pwd> 724.Ed 725.Pp 726To disable the use of a proxy for an HTTP server running on the local 727host, define 728.Ev NO_PROXY 729as follows: 730.Bd -literal -offset indent 731NO_PROXY=localhost,127.0.0.1 732.Ed 733.Pp 734To use a SOCKS5 proxy, set the 735.Ev SOCKS5_PROXY 736environment variable to a 737valid host or IP followed by an optional colon and the port. 738IPv6 addresses must be enclosed in brackets. 739The following are examples of valid settings: 740.Bd -literal -offset indent 741SOCKS5_PROXY=proxy.example.com 742SOCKS5_PROXY=proxy.example.com:1080 743SOCKS5_PROXY=192.0.2.0 744SOCKS5_PROXY=198.51.100.0:1080 745SOCKS5_PROXY=[2001:db8::1] 746SOCKS5_PROXY=[2001:db8::2]:1080 747.Ed 748.Pp 749Access HTTPS website without any certificate verification whatsoever: 750.Bd -literal -offset indent 751SSL_NO_VERIFY_PEER=1 752SSL_NO_VERIFY_HOSTNAME=1 753.Ed 754.Pp 755Access HTTPS website using client certificate based authentication 756and a private CA: 757.Bd -literal -offset indent 758SSL_CLIENT_CERT_FILE=/path/to/client.pem 759SSL_CA_CERT_FILE=/path/to/myca.pem 760.Ed 761.Sh SEE ALSO 762.Xr fetch 1 , 763.Xr ip 4 764.Rs 765.%A J. Postel 766.%A J. K. Reynolds 767.%D October 1985 768.%B File Transfer Protocol 769.%O RFC959 770.Re 771.Rs 772.%A P. Deutsch 773.%A A. Emtage 774.%A A. Marine. 775.%D May 1994 776.%T How to Use Anonymous FTP 777.%O RFC1635 778.Re 779.Rs 780.%A T. Berners-Lee 781.%A L. Masinter 782.%A M. McCahill 783.%D December 1994 784.%T Uniform Resource Locators (URL) 785.%O RFC1738 786.Re 787.Rs 788.%A R. Fielding 789.%A J. Gettys 790.%A J. Mogul 791.%A H. Frystyk 792.%A L. Masinter 793.%A P. Leach 794.%A T. Berners-Lee 795.%D January 1999 796.%B Hypertext Transfer Protocol -- HTTP/1.1 797.%O RFC2616 798.Re 799.Rs 800.%A J. Franks 801.%A P. Hallam-Baker 802.%A J. Hostetler 803.%A S. Lawrence 804.%A P. Leach 805.%A A. Luotonen 806.%A L. Stewart 807.%D June 1999 808.%B HTTP Authentication: Basic and Digest Access Authentication 809.%O RFC2617 810.Re 811.Sh HISTORY 812The 813.Nm fetch 814library first appeared in 815.Fx 3.0 . 816.Sh AUTHORS 817.An -nosplit 818The 819.Nm fetch 820library was mostly written by 821.An Dag-Erling Sm\(/orgrav Aq Mt des@FreeBSD.org 822with numerous suggestions and contributions from 823.An Jordan K. Hubbard Aq Mt jkh@FreeBSD.org , 824.An Eugene Skepner Aq Mt eu@qub.com , 825.An Hajimu Umemoto Aq Mt ume@FreeBSD.org , 826.An Henry Whincup Aq Mt henry@techiebod.com , 827.An Jukka A. Ukkonen Aq Mt jau@iki.fi , 828.An Jean-Fran\(,cois Dockes Aq Mt jf@dockes.org , 829.An Michael Gmelin Aq Mt freebsd@grem.de 830and others. 831It replaces the older 832.Nm ftpio 833library written by 834.An Poul-Henning Kamp Aq Mt phk@FreeBSD.org 835and 836.An Jordan K. Hubbard Aq Mt jkh@FreeBSD.org . 837.Pp 838This manual page was written by 839.An Dag-Erling Sm\(/orgrav Aq Mt des@FreeBSD.org 840and 841.An Michael Gmelin Aq Mt freebsd@grem.de . 842.Sh BUGS 843Some parts of the library are not yet implemented. 844The most notable 845examples of this are 846.Fn fetchPutHTTP , 847.Fn fetchListHTTP , 848.Fn fetchListFTP 849and FTP proxy support. 850.Pp 851There is no way to select a proxy at run-time other than setting the 852.Ev HTTP_PROXY 853or 854.Ev FTP_PROXY 855environment variables as appropriate. 856.Pp 857.Nm libfetch 858does not understand or obey 305 (Use Proxy) replies. 859.Pp 860Error numbers are unique only within a certain context; the error 861codes used for FTP and HTTP overlap, as do those used for resolver and 862system errors. 863For instance, error code 202 means "Command not 864implemented, superfluous at this site" in an FTP context and 865"Accepted" in an HTTP context. 866.Pp 867.Fn fetchStatFTP 868does not check that the result of an MDTM command is a valid date. 869.Pp 870In case password protected keys are used for client certificate based 871authentication the user is prompted for the password on each and every 872fetch operation. 873.Pp 874The man page is incomplete, poorly written and produces badly 875formatted text. 876.Pp 877The error reporting mechanism is unsatisfactory. 878.Pp 879Some parts of the code are not fully reentrant. 880