dacshttp

DACSHTTP(1)                   DACS Commands Manual                   DACSHTTP(1)



NAME
       dacshttp - perform an HTTP/HTTPS request

SYNOPSIS
       dacshttp [-get | -post | -delete | -head | -options | -soptions | -put]
                [-ll log_level]
                [-prompt] [-v] [--version] [[-ct string] |
                [--content-type string]]
                [{-header name value}...] [-headers filename] [-body filename]
                [-ih]
                [-user-agent string] [{-p name value}...] [-proto version-num]
                [-proxy proxyhost:proxyport]
                [-proxymatch hostname[:port] proxyhost:proxyport]
                [-f name filename] [{-cookies filename}...] [-ah]
                [-ssl command-line] [-ssl-flags flags]
                [-u userinfo] [-U proxy-userinfo] uri

DESCRIPTION
       This program is part of the DACS suite. It is a stand-alone program that
       neither accepts the usual DACS command line options (dacsoptions[1]) nor
       accesses any DACS configuration files.

       This general-purpose utility sends an HTTP/HTTPS request for uri to a web
       server and prints the reply to its standard output.

       dacshttp will automatically follow redirects according to RFC 2616[2] and
       up to a compile-time maximum, unless the -prompt flag is given. A
       non-standard extension is that a redirect to a non-absolute URI is
       interpreted in a manner compatible with most browsers.

       In versions 1.4.27b and earlier, this command was called http.

           Note
           DACS can issue its own HTTP requests, such as from dacs_authenticate
           to an external authentication module. This HTTP functionality is
           provided by the same support code that the dacshttp command uses, and
           therefore much of the following information applies to these
           internally generated requests also (e.g., HTTP_PROG[3], SSL_PROG[4],
           SSL_PROG_ARGS[5], SSL_PROG_CA_CRT[6], SSL_PROG_CLIENT_CRT[7],
           VFS[8]).

OPTIONS
       The HTTP GET method is used by default, but some flags implicitly select
       a different method (e.g., -f and -p). One of the following flags can be
       used to explicitly specify the HTTP method, provided it is compatible
       with the other options:

       -get
           Use the GET method (the default).

       -post
           Use the POST method.

       -head
           Use the HEAD method.

       -put
           Use the PUT method.

       -delete
           Use the DELETE method.

       -options
           Use the OPTIONS method.

       -soptions
           Use the OPTIONS method but ignore anything that follows the authority
           component of uri and instead use the special case "*" request URI
           that means that the request applies to the server itself rather than
           to a particular resource.

       These command line flags are also recognized:

       -ah
           If cookies (credentials) are to be sent (see -cookies), use an
           Authorization header rather than a Cookie header.

       -body filename
           Read the message body from filename. It is assumed that the body has
           already been appropriately formatted for the request's content type.

       -cookies filename
           Obtain cookies from filename, one per line, to send with the request
           using the Cookie header. Multiple cookies are separated using a
           semi-colon, which follows the Netscape spec[9]. Alternatively,
           multiple cookies can be combined on a single line, separated by
           either a semi-colon or a comma (following RFC 2109[10], RFC 2965[11]
           or RFC 6265[12]). This argument may be repeated.

       -ct string
       --content-type string
           Set the Content-Type request-header to string. If the request has an
           entity-body, the default Content-Type is
           application/x-www-form-urlencoded; if the request does not have an
           entity-body, by default the Content-Type request-header is not set.

       -f name filename
           Passes and encodes the contents of filename as the value for name. By
           default, the POST method will be used, although PUT and OPTIONS can
           be selected. If filename is "-", the standard input is read; this
           form can only be used once on the command line. This argument may be
           repeated.

       -header name value
           This flag, which may be repeated, causes the HTTP header name: value
           to be sent with the request. Neither name nor value are checked in
           any way.

               Note
               This will not override headers required or implied by other
               command line flags, and can result in multiple instances of the
               same header. For example, the following flags are not equivalent:

                   -header User-Agent foo
                   -user-agent foo

               The former case will send the User-Agent header twice.

       -headers filename
           Read additional message headers from filename, one per line, and send
           them with the request (refer to the -header flag). This flag may be
           repeated.

       -ih
           Include the HTTP response headers in the output. They are terminated
           by a blank line. The status line is labelled "Status-Line".

       -ll log_level
           Set the debugging output level to log_level (see dacs(1)[13]). The
           default level is warn, and the -v flag bumps the level to debug or
           trace.

       -p name value
           Passes and encodes name=value as part of the entity-body. By default,
           the POST method will be used, although PUT and OPTIONS can be
           selected. This argument may be repeated.

       -prompt
           Prompt the user for permission to proceed after certain events, such
           as receiving a redirect; the response is affirmative only if it is
           "yes" or "y". If this option is not specified, the affirmative action
           will automatically be taken.

       -proto version-num
           Function in compliance with version-num of the HTTP protocol (e.g.,
           1.0).

       -proxy proxyhost:proxyport
           Forward all HTTP requests (except for those that match a -proxymatch
           flag) to the proxy server at proxyport (a numeric port number or
           recognized service name) on proxyhost (a domain name or IP address).
           Proxying is not fully supported by dacshttp, but it will connect to
           the specified proxy server instead of the server implied by uri.

       -proxymatch hostname[:port] proxyhost:proxyport
           If hostname matches the host specified in uri, proxy the HTTP request
           through proxyhost (a domain name or IP address) at proxyport (a
           numeric port number or recognized service name). If port is not
           given, it is assumed to be 80 (for the http scheme) or 443 (for the
           https scheme). Matching is done by resolving hostname to an IP
           address (if necessary) and comparing it to the effective IP address
           that is specified by uri. This flag is given priority over the -proxy
           flag, so it can be used to override a default proxy server.

               Note
               This option is not implemented. The SSL/TLS flags apply to all
               connections; this is probably a bug.

       -ssl command-line
           This flag indicates that HTTPS (i.e, HTTP over an SSL/TLS connection)
           is to be used, regardless of the scheme specified by uri. Because
           dacshttp does not directly include SSL/TLS functionality, it uses
           pipes to communicate with an external program that provides the
           SSL/TLS connection. The sslclient(1)[14] command is strongly
           recommended for this purpose (version 3.26 of stunnel(1) and
           stunnel3, which comes with some releases of stunnel-4.x, might also
           work).

           The command-line is a complete shell command line that will be used
           to run the program as a filter. For example, this argument might look
           like either of:

               -ssl "/usr/local/dacs/bin/sslclient example.com:443"

               -ssl "/usr/local/bin/stunnel -c -r example.com:443"

           If the -ssl argument is absent but the uri argument uses the https
           scheme, dacshttp will still try to use SSL/TLS. It will attempt to
           use sslclient(1)[14] and assume it is in its default location. If the
           -ssl argument is present but specifies only one string, that string
           is assumed to be the path to sslclient(1)[14]. The first example
           below will run sslclient(1)[14] from /tmp/sslclient to connect to
           port 443 at example.com; the second example has the same effect but
           will run sslclient(1)[14] from its default location:

               % dacshttp -ssl "/tmp/sslclient" https://example.com
               % dacshttp https://example.com


       -ssl-flags flags
           If SSL/TLS operation is enabled but the -ssl flag is absent or did
           not simply specify a pathname, append flags to the list of arguments
           to be passed to the external SSL/TLS provider; when the -ssl flag
           specifies more than one argument, this flag is ignored. The flags
           string is a space-separated list of arguments. This flag may be
           repeated.

           For example, in this example dacshttp will invoke sslclient with the
           two arguments -sm and bobo.example.com:

               % dacshttp -ssl-flags "-sm bobo.example.com" https://example.com

           If a wildcard server certificate is used, it may be necessary to
           explicitly match all hosts within a specific domain:

               % dacshttp -ssl-flags "-sm .*\.example\.com" https://example.com


               Important
               When called by dacshttp, error messages produced by sslclient may
               be lost. If you encounter problems with SSL/TLS operation, work
               with sslclient(1)[14] to ensure that an SSL/TLS connection can be
               established, or to determine and resolve the problem. If you
               discover that sslclient requires command line flags for proper
               operation, you will need to make sure that dacshttp passes those
               flags to it.

       -user-agent string
           Set the User-Agent request-header to string. If not provided, this
           string will have the prefix "DACS-http/", followed by a DACS release
           identifier (example: "DACS-http/1.4.1").

       -u userinfo
       --user userinfo
           Send an Authorization header conforming to the HTTP Basic
           Authentication scheme (RFC 2617[15]). The userinfo consists of a
           username followed by a colon followed by the user's password. Since
           the password will be visible, use this flag with caution.

       -U proxy-userinfo
       --proxyuser proxy-userinfo
           Send a Proxy-Authorization header conforming to the HTTP Basic
           Authentication scheme (RFC 2617[15]). The proxy-userinfo consists of
           a username, a colon, and then a password for the proxy server. Since
           the password will be visible, use this flag with caution.

       -v
           Increase the level of debugging output. This will cause response
           headers to be displayed, for example. The flag may be repeated.

       --version
           Print version information to stderr, then exit immediately.

       The uri argument is the URL to invoke. It may include a query string
       suffix (even if HTTP POST is selected). Though not recommended because it
       is not secure, the uri may include a userinfo component (RFC 2617[15]).

       It is an error to attempt to send more than one Authorization header.

       Whether selected implicitly or explicitly, the command line must specify
       exactly one of the HTTP methods.

       Request headers specified using the -header or -headers flags are sent in
       the order in which the flags appear on the command line. If they are read
       from a file, there ordering is maintained.

EXAMPLES
       The following will retrieve RFC 2616[2] and save it in rfc2616.txt:

           % dacshttp "http://www.rfc-editor.org/rfc/rfc2616.txt" > rfc2616.txt

       This will do a GET on the given URL, passing the query string foo=baz,
       and writing the result to stdout:

           % dacshttp "https://example.com/cgi-bin/dacs/dacs_prenv?foo=baz"

       This will do a POST on the given URL, passing two arguments:

           % dacshttp -p foo baz -p bar zork https://example.com/cgi-bin/dacs/dacs_prenv

       This will make an HTTP GET method request over SSL/TLS to the given URL:

           % dacshttp -ssl "/usr/local/dacs/bin/sslclient example.com:443" \
               https://example.com/cgi-bin/dacs/dacs_prenv

       These two commands are equivalent. They submit a request associated with
       username julia and password herpasswd, which causes an Authorization
       header conforming to the HTTP Basic Authentication scheme (RFC 2617[15])
       to be sent:

           % dacshttp http://julia:herpasswd@example.com
           % dacshttp -u julia:herpasswd http://example.com

DIAGNOSTICS
       The program exits 0 if everything was fine, 1 if an error occurred.

BUGS
       It can sometimes be a useful tool, but this program's primary purpose is
       for developing and testing DACS core functionality. There are many
       readily-available and better HTTP clients.

       Use of an SSL/TLS provider other than sslclient(1)[14] is officially
       deprecated.  dacshttp should not require an external program to provide
       SSL/TLS functionality. Recent development makes it doubtful that any
       other program will function properly with dacshttp.

       dacshttp is only a partial implementation of RFC 2616[2]. It only talks
       HTTP (no other URI schemes are supported). Received cookies are
       discarded. Authentication via RFC 2617[15] is only partially implemented:
       a single username and password to authenticate the user submitting the
       request and/or a single username and password to gain access to a proxy
       server can be specified to be sent with the request. No client-side
       caching of any kind is performed.

SEE ALSO
       sslclient(1)[14], lynx(1)[16], curl(1)[17], Wget(1)[18], RFC 1738[19],
       RFC 2396[20], RFC 2616[2], RFC 3986[21]

AUTHOR
       Distributed Systems Software (www.dss.ca[22])

COPYING
       Copyright © 2003-2014 Distributed Systems Software. See the LICENSE[23]
       file that accompanies the distribution for licensing information.

NOTES
        1. dacsoptions
           http://dacs.dss.ca/man/dacs.1.html#dacsoptions

        2. RFC 2616
           http://www.rfc-editor.org/rfc/rfc2616.txt

        3. HTTP_PROG
           http://dacs.dss.ca/man/dacs.conf.5.html#HTTP_PROG

        4. SSL_PROG
           http://dacs.dss.ca/man/dacs.conf.5.html#SSL_PROG

        5. SSL_PROG_ARGS
           http://dacs.dss.ca/man/dacs.conf.5.html#SSL_PROG_ARGS

        6. SSL_PROG_CA_CRT
           http://dacs.dss.ca/man/dacs.conf.5.html#SSL_PROG_CA_CRT

        7. SSL_PROG_CLIENT_CRT
           http://dacs.dss.ca/man/dacs.conf.5.html#SSL_PROG_CLIENT_CRT

        8. VFS
           http://dacs.dss.ca/man/dacs.conf.5.html#VFS

        9. Netscape spec
           http://web.archive.org/web/20070805052634/http://wp.netscape.com/newsref/std/cookie_spec.html

       10. RFC 2109
           http://www.rfc-editor.org/rfc/rfc2109.txt

       11. RFC 2965
           http://www.rfc-editor.org/rfc/rfc2965.txt

       12. RFC 6265
           http://www.rfc-editor.org/rfc/rfc6265.txt

       13. dacs(1)
           http://dacs.dss.ca/man/dacs.1.html

       14. sslclient(1)
           http://dacs.dss.ca/man/sslclient.1.html

       15. RFC 2617
           http://www.rfc-editor.org/rfc/rfc2617.txt

       16. lynx(1)
           http://lynx.isc.org

       17. curl(1)
           http://directory.fsf.org/All_Packages_in_Directory/cURL.html

       18. Wget(1)
           http://www.gnu.org/software/wget/wget.html

       19. RFC 1738
           http://www.rfc-editor.org/rfc/rfc1738.txt

       20. RFC 2396
           http://www.rfc-editor.org/rfc/rfc2396.txt

       21. RFC 3986
           http://www.rfc-editor.org/rfc/rfc3986.txt

       22. www.dss.ca
           http://www.dss.ca

       23. LICENSE
           http://dacs.dss.ca/man/../misc/LICENSE



DACS 1.4.40                        02/19/2019                        DACSHTTP(1)