Ubuntu Manpage: dacshttp - perform an HTTP/HTTPS request

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.

AUTHOR

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

COPYING

       Copyright2003-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