retawq Documentation
Run-Time Configuration Options
Introduction
When retawq starts, it tries to read a configuration file which is normally
located at /home/your_home/.retawq/config. (You can make retawq look in
a different directory with the command-line option
"--retawqdir=path".) This file consists of sections and
subsections:
- The beginning of a section is marked by a line which starts with a
non-whitespace character. (Space and tabulator characters are
"whitespace".)
- A subsection ("rule") within a section simply is a single line which starts
with a whitespace character. Rules are tested in the given order until a
matching rule (e.g. a rule containing a matching host name pattern) is found;
if no rules are given or none of the given rules matches, retawq's internal
default rule applies. - Not all sections can have subsections, simply because
they don't need any...
- Lines which begin with a "#" are comment lines and ignored by retawq.
Please note that case matters - don't use upper-case letters where
lower-case letters are required! :-)
There's a configuration file example
available.
The Options
- home - the document which shall be displayed when you use the keyboard command "h", e.g. your private home page
- search-engine - a search engine form which shall be displayed when
you use the keyboard command "S"
- languages - a comma-separated, whitespace-free list of language
codes for your preferred natural languages in which you would like to download
documents from HTTP servers; example: "fr,en" if you prefer French documents
but also accept ;-) English documents. If the server can't satisfy your
preference, it will send the document in "any" language, most likely English. -
The default value for this option is "en" (i.e., English documents are
preferred, nothing else is said). - This option corresponds to the HTTP header
"Accept-Language".
- colors - By default, retawq displays colored text on any text
terminal which supports colors, and it mostly uses white color on a black
background. If you don't like colors at all, use "colors off". If you want to
get black-on-white text, use "colors reverse".
- redirections - maximum number of automatic URL redirections with the
HTTP and FTP protocols; the default is 10 (which should be enough for any
"real-life" case), allowed values are in the range 3..20
- http-proxies - By default, retawq doesn't use any proxies when
sending HTTP requests to servers. But in some local networks, the connection to
the Internet is only possible via proxies - e.g. because your local network is
protected by a firewall.
To define HTTP proxies, you start a "http-proxies" section in the config
file and define one rule per subsection line; each rule consists of a proxy and
a host pattern, optionally followed by a username and a password for proxy
authentication. (The password is entered in clear text, which might be a
security problem, so you should make sure that nobody but you can read the
config file; for example, use the shell command "chmod go-rwx config" in
advance.)
You may also provide portnumbers in the usual "name:portnumber" notation;
if you don't provide a portnumber for the proxy, port 8080 is used; if you
don't provide a portnumber for the host pattern, the given rule applies to
all host ports. A host pattern can either be an exact name or begin with
a "*" character (which has the usual meaning).
For the example of a local network behind a firewall, your configuration
might look like this:
http-proxies:
none *my-domain.org
firewall.my-domain.org *
This means that all servers of your own domain (that is "inside the local
network" for this example) are accessed without proxies (use "none" as the
proxy name), and all other servers are contacted via the proxy
"firewall.my-domain.org".
- ftp-login - Specify standard username and password for FTP server
login; if you don't provide username and password in an URL (like in
"ftp://user:pass@foo.org/"), retawq uses the word "anonymous" for them by
default. But some public FTP servers require that the password is (or at least
looks like) an e-mail address. If you get a "login failed" error message when
trying to access a public FTP service, you should add something like the
following to the configuration file:
ftp-login
anonymous mail@foo.org *
Now retawq will send the username "anonymous" and password "mail@foo.org"
when trying to access any ("*") FTP server unless a username and password are
explicitly given in the URL. Of course you can define a more detailed
configuration with several rule lines.
In theory, you could use this configuration for non-public FTP server
access as well. But writing down passwords in clear text is a bad idea, so
don't do it in practice - this configuration option is only intended for
non-standard, public FTP access!
- http-cookies - If the compile-time
configuration option OPTION_COOKIES has been enabled, you can specify for
which HTTP servers cookies may actually be stored and sent (default: none are
stored/sent); cookies will only be stored in RAM, not written to disk, so they
are automatically discarded when you quit retawq. The first argument in each
rule must be either "allow" or "deny". The second argument is a host name
pattern which can be either an exact name or begin with a "*" character (which
has the usual meaning).
- local-cgi - If the compile-time
configuration option OPTION_LOCAL_CGI has been enabled, you can specify
which CGI scripts on the local computer may be executed with the protocol
scheme "local-cgi" (default: nothing allowed). The first argument in each rule
must be either "allow" or "deny". The second argument is a script path pattern
which must begin with a "/" character and may be either an exact script name or
end with a "*" character (which has the usual meaning).
- dont-confirm - Normally retawq asks you for confirmation if you try
to perform a command which may have "dangerous" or unwanted effects, e.g.
quitting the program or overwriting a file. If you know the program so good
that you don't handle it the wrong way, you can disable the enervating :-)
questions individually with the following keywords:
- quit - don't ask when quitting retawq (keyboard command "Q")
- close - don't ask when closing a window (keyboard command "C")
- overwrite - don't ask before overwriting a local file
- form-submit - don't ask before submitting an HTML form to an HTTP
server
- form-reset - don't ask before resetting an HTML form, i.e. setting
all elements of a form back to their default values
- form-repost - don't ask before re-submitting an HTML form to an HTTP
server using the "post" method; this method is often used for tasks like adding
a record to a database, and adding it twice normally isn't a good idea; a
re-submit can e.g. happen if you reload a document which resulted from a "post"
operation.
- enforce-html - don't ask before enforcing the interpretation of a
document as HTML source code (keyboard command "H")
- enable - don't ask before enabling a disabled HTML form element
(keyboard command "E")
- user-agent - retawq, like most other browsers, identifies itself to
HTTP servers by including a "User-Agent" line into the HTTP header. The
"user-agent" option allows you to specify how much information about your
computer retawq may reveal to the server. The amount of information is defined
by a number ranging from 0 to 3, which had the following effect on my
computer:
- "user-agent 0" - "User-Agent: retawq/0.0.1 [en] (text)"
- "user-agent 1" - "User-Agent: retawq/0.0.1 [en] (text; Linux)"
- "user-agent 2" - "User-Agent: retawq/0.0.1 [en] (text; Linux 2.2.19)"
- "user-agent 3" - "User-Agent: retawq/0.0.1 [en] (text; Linux 2.2.19;
i686)"
The resulting HTTP header line contains the program name ("retawq"), the
version number (here "0.0.1"), the language code for the default user interface
language (here "[en]" for the English language) and some additional information
in parentheses, e.g. the word "text" which is there to distinguish the
currently used text mode from the not-yet-implemented graphics mode.
Distinguishing text and graphics mode may help dynamic content creation
programs (CGI scripts) on servers to decide whether they should generate a
fully-blown graphics version of some document or a lightweight text-only
version.
Higher numbers for the option "user-agent" result in more information. If
you want to advertise your operating system (like me;-), you should set the
number to at least 1. The default value is 0, of course, so that you don't
reveal private information accidentally.
The information is obtained via the operating system function "uname()". If
you're curious, you can easily find out this information for your computer with
the command-line program "uname", e.g. "uname -srm" or "uname -a".
This documentation file is part of version 0.1.2 of retawq, a network client created by
Arne Thomaßen. retawq is basically released under
certain versions of the GNU General Public License and WITHOUT ANY WARRANTY.
Copyright (C) 2001-2002 Arne Thomaßen.