diff options
Diffstat (limited to '')
| -rw-r--r-- | samples/cernrules.txt | 640 |
1 files changed, 640 insertions, 0 deletions
diff --git a/samples/cernrules.txt b/samples/cernrules.txt new file mode 100644 index 0000000..6df8b30 --- /dev/null +++ b/samples/cernrules.txt @@ -0,0 +1,640 @@ +# This files contains examples and an explanation for the RULESFILE / RULE +# feature. +# +# Rules for Lynx are experimental. They provide a rudimentary capability +# for URL rejection and substitution based on string matching. +# Most users and most installations will not need this feature, it is here +# in case you find it useful. Note that this may change or go away in +# future releases of Lynx; if you find it useful, consider describing your +# use of it in a message to <lynx-dev@nongnu.org>. +# +# Syntax: +# ======= +# Summary of common forms: +# +# Fail URL1 +# Map URL1 URL2 [CONDITION] +# Pass URL1 [URL2] [CONDITION] +# Redirect URL1 URL2 [CONDITION] +# RedirectPerm URL1 URL2 [CONDITION] +# UseProxy URL1 PROXYURL [CONDITION] +# UseProxy URL1 "none" [CONDITION] +# +# Alert URL1 MESSAGE [CONDITION] +# AlwaysAlert URL1 MESSAGE [CONDITION] +# UserMsg URL1 MESSAGE [CONDITION] +# InfoMsg URL1 MESSAGE [CONDITION] +# Progress URL1 MESSAGE [CONDITION] +# +# As you may have guessed, comments are introduced by a '#' character. +# Rules have the general form +# Operator Operand1 [Operand2] [CONDITION] +# with words separated by whitespace. Words containing space can be quoted +# with "double quotes". Although normally this should not be necessary +# necessary for URLs, it has to be used for MESSAGE Operands in Alert etc. +# See below for an explanation of the optional CONDITION. +# +# Recognized operators are +# +# Fail URL1 +# Reject access to this URL, stop processing further rules. +# +# Map URL1 URL2 +# Change the current URL to URL2, then continue processing. +# +# Pass URL1 [URL2] +# Accept this URL and stop processing further rules; if URL2 +# is given, apply this as the last mapping. +# See the next item for reasons why you generally don't want to "pass" +# a changed URL. +# +# RedirectTemp URL1 URL2 +# RedirectPerm URL1 URL2 +# Redirect [STATUS] URL1 URL2 +# Stop processing further rules and redirect to URL2, just as if lynx had +# received a HTTP redirection with URL2 as the new location. This means that +# URL2 is subject to any applicable permission checking, if it passes a new +# request will be issued (which may result in a new round of rules checking, +# with a new "current URL") or the new URL might be taken from the cache, and, +# after successful loading, lynx's idea of what the loaded document's URL is +# will be fully updated. All this does not happen if you just "pass" a changed +# URL (or let it fall through), so this is generally the preferred way for +# substituting URLs. +# If the RedirectPerm variant is used, or if the optional word is supplied and +# is either "permanent" or "301", act as if lynx had received a permanent +# redirection (with HTTP status 301). In most cases this will not make a +# noticeable difference. Lynx may cache the location in a special way for 301 +# redirections, so that the redirection is followed immediately the next time +# the same original URL is accessed, without re-checking of rules. Therefore +# the permanent variant should never be used if the desired outcome of rules +# processing depends on variable conditions (see CONDITIONS below) or on +# setting a special flag (see next item). +# +# PermitRedirection URL1 +# Mark following redirection as permitted, and continue processing. Some +# redirection locations are normally not allowed, because permitting them in a +# response from an arbitrary remote server would open a security hole, and +# others are not allowed if certain restrictions options are in effect. Among +# redirection locations normally always forbidden are lynxprog: and lynxexec: +# schemes. With "default" anonymous restrictions in effect, many URL schemes +# are disallowed if the user would not be allowed to use them with 'g'oto. +# This rule allows to override the permission checking if rules processing ends +# with a Redirect (including the RedirectPerm or RedirectTemp forms). It is +# ignored otherwise, in particular, it does not influence acceptance if rules +# processing ends with a "Pass" and a real redirection is received in the +# subsequent HTTP request. If redirections are chained, it only applies to the +# redirection that ends the same rules cycle. Note that the new URL is still +# subject to other permission checks that are not specific to redirections; but +# using this rule may still weaken the expected effect of -anonymous, +# -validate, -realm, and other restriction options, including TRUSTED_EXEC and +# similar in lynx.cfg, so be careful where you redirect to if restrictions are +# important! +# +# UseProxy URL1 PROXYURL +# Stop processing further rules, and force access through the proxy given by +# PROXYURL. PROXYURL should have the same form as required for foo_proxy +# environment variables and lynx.cfg options, i.e., (unless you are trying to +# do something unusual) "http://some.proxy-server.dom:port/". This rule +# overrides any use of a proxy (or external gateway) that might otherwise apply +# because of environment variables or lynx.cfg options, it also overrides any +# "no_proxy" settings. +# +# UseProxy URL1 none +# Mark request as NOT using any proxy (or external gateway), and continue +# processing(!). For a request marked this way, any subsequent UseProxy +# rule with a PROXYURL will be ignored, and any use of a proxy (or external +# gateway) that might otherwise apply because of environment variables or +# lynx.cfg options will be overridden. Note that the marking will not +# survive a Redirect rule (since that will result, if successful, in a +# new request). +# +# Alert URL1 MESSAGE +# AlwaysAlert URL1 MESSAGE +# UserMsg URL1 MESSAGE +# InfoMsg URL1 MESSAGE +# Progress URL1 MESSAGE +# These produce various kinds of statusline messages, differing in whether +# a pause is enforced and in its duration, immediately when the rule is +# applied. AlwaysAlert shows the message text even in non-interactive mode +# (-dump, -source, etc.). Rule processing continues after the message is +# shown. As usual, these rules only apply if URL1 matches. MESSAGE is +# the text to be displayed, it can contain one occurrence of "%s" which +# will be replaced by the current URL, literal '%' characters should be +# doubled as "%%". +# +# Rules are processed sequentially first to last for each request, a rule +# applies if the current URL matches URL1. The current URL is initially the +# URL for the resource the user is trying to access, but may change as the +# result of applied Map rules. case-sensitive (!) string comparison is used, +# in addition URL1 can contain one '*' which is interpreted as a wildcard +# matching 0 or more characters. So if for example +# "http://example.com/dir/doc.html" is requested, it would match any of +# the following: +# Pass http:* +# Pass http://example.com/*.html +# Pass http://example.com/* +# Pass http://example* +# Pass http://*/doc.html +# but not: +# Pass http://example/* +# Pass http://Example.COM/dir/doc.html +# Pass http://Example.COM/* +# +# If a URL2 is given and also contains a '*', that character will be +# replaced by whatever matched in URL1. Processing stops with the +# first matching "Fail" or "Pass" or when the end of the rules is reached. +# If the end is reached without a "Fail" or "Pass", the URL is allowed +# (equivalent to a final "Pass *"). +# +# The requested URL will have been transformed to Lynx's normal +# representation. This means that local file resources should be +# expected in the form "file://localhost/<path using slash separators>", +# not in the machine's native representation for filenames. +# +# Anyone with experience configuring the venerable CERN httpd server will +# recognize some of the syntax - in fact, the code implementing rules goes +# back to a common ancestor. But note the differences: all URLs and URL- +# patterns here have to be given as absolute URLs, even for local files. +# (Absolute URLs don't imply proxying.) +# +# CONDITIONS +# ---------- +# All rules mentioned can be followed by an optional CONDITION, which can +# be used to further restrict when the rule should be applied (in addition +# to the match on URL1). A CONDITION takes one of the forms +# "if" CONDITIONFLAG +# "unless" CONDITIONFLAG +# and currently two condition flags are recognized: +# "userspecified" (or abbreviated "userspec") +# "redirected" +# To explain these, first some terms need to be defined. A "request" +# is... +# +# A user action (like following a link, or entering a 'g'oto URL) can either be +# rejected immediately (for example, because of restrictions in effect, or +# because of invalid input), or can generate a "request". For the purpose of +# this discussion, a "request" is the sequence of processing done by lynx, +# which might ultimately lead to an actual network request and loading and +# display of data; a request can also result in rejection (for example, some +# restrictions are checked at this stage), or in a redirection. A redirection +# in turn can be rejected (which makes the request fail), or can automatically +# generate a new request. A "request chain" is the sequence of one or more +# requests triggered by the same user event that are chained together by +# redirections. +# For each request, some URL schemes are handled (or rejected) specially, see +# Limitation 1 below, the others are passed to the generic access code. Rules +# processing occurs at the beginning of the generic access code, before a +# request is dispatched to the scheme-specific protocol module (but after +# checking whether the request can be satisfied by re-displaying an already +# cached document). +# With these definitions, the meaning of the possible CONDITIONFLAGS: +# +# if redirected +# The rule applies if the current request results from a redirection; +# whether that was a real HTTP redirection or one generated by a rule +# in the previous request makes no difference. In other words, the +# condition is true if the current request is not the first one in the +# request chain. +# +# if userspecified +# The rule applies if the initial URL of the request chain was specified +# by the user. Lynx marks a request as "user specified" for URLs that +# come from 'g'oto prompts, as well as for following links in a bookmark +# or Jump file and some other special (lynx-generated) pages that may +# contain URLs that were typed in by the user. +# Note that this is not a property of the request, but of the whole request +# chain (based on where the first request's URL came from). The current +# URL may differ from what the user typed +# - because of initial fixups, including conversion of Guess-URLs and file +# paths to full URLs, +# - because of Map rules applied, and/or +# - because of a previous redirection. +# So to make reasonably sure a suspicious or potentially dangerous URL has +# been entered by the user, i.e. is not a link or external redirection +# location that cannot be trusted, a combination of "userspecified" and +# "redirected" flags should be used, for example +# Fail URL1 unless userspecified +# Fail URL1 if redirected +# ... +# +# CAVEAT +# ====== +# First, to squash any false expectations, an example for what NOT TO DO. +# It might be expected that a rule like +# Fail file://localhost/etc/passwd # <- DON'T RELY ON THIS +# could be used to prevent access to the file "/etc/passwd". This might +# fool a naive user, but the more sophisticated user could still gain +# access, by experimenting with other forms like (@@@ untested) +# "file://<machine's domain name>/etc/passwd" or "/etc//passwd" +# or "/etc/p%61asswd" or "/etc/passwd?" or "/etc/passwd#X" and so on. +# There are many URL forms for accessing the same resource, and Lynx +# just doesn't guarantee that URLs for the same resource will look the +# same way. +# +# The same reservation applies to any attempts to block access to unwanted +# sites and so on. This isn't the right place for implementing it. +# (Lynx has a number of mechanisms documented elsewhere to restrict access, +# see the INSTALLATION file, lynx.cfg, lynx -help, lynx -restrictions.) +# +# Some more useful applications: +# +# 1. Disabling URLs by access scheme +# ---------------------------------- +# Fail gopher:* +# Fail finger:* +# Fail lynxcgi:* +# Fail LYNXIMGMAP:* +# This should work (but no guarantees) because Lynx canonicalizes +# the case of recognized access schemes and does not interpret +# %-escaping in the scheme part (@@@ always?) +# +# Note that for many access schemes Lynx already has mechanisms to +# restrict access (see lynx.cfg, -help, -restrictions, etc.), others +# have to be specifically enabled. Those mechanisms should be used +# in preference. +# Note especially Limitation 1 below. +# This can be used for the remaining cases, or in addition by the +# more paranoid. Note that disabling "file:*" will also make many +# of the special pages generated by lynx as temporary files (INFO, +# history, ...) inaccessible, on the other hand it doesn't prevent +# _writing_ of various temp files - probably not what you want. +# +# You could also direct access for a scheme to a brief text explaining +# why it's not available: +# Redirect news:* http://localhost/texts/newsserver-is-broken.html +# +# 2. Preventing accidental access +# ------------------------------- +# If there is a page or site you don't want to access for whatever +# reason (say there's a link to it that crashes Lynx [don't forget to +# report a bug], or if that starts sending you a 5 Mb file you don't +# want, or you just don't like the people...), you can prevent yourself +# from accidentally accessing it: +# Fail http://bad.site.com/* +# +# 3. Compressed files +# ------------------- +# You have downloaded a bunch of HTML documents, and compressed them +# to save space. Then you discover that links between the files don't +# work, because they all use the names of the uncompressed files. The +# following kind of rule will allow you to navigate, invisibly accessing +# the compressed files: +# Map file://localhost/somedir/*.html file://localhost/somedir/*.html.gz +# or, perhaps better: +# Redirect file://localhost/somedir/*.html file://localhost/somedir/*.html.gz +# +# 4. Use local copies +# ------------------- +# You have downloaded a tree of HTML documents, but there are many links +# between them that still point to the remote location. You want to access +# the local copies instead, after all that's why you downloaded them. You +# could start editing the HTML, but the following might be simpler: +# Map http://remote.com/docs/*.html file://localhost/home/me/docs/*.html +# Or even combine this with compressing the files: +# Map http://remote.com/docs/*.html file://localhost/home/me/docs/*.html.gz +# +# Again, replacing the "Map" with "Redirect" is probably better - it will +# allow you to see the _real_ location on the lynx INFO screen or in the +# HISTORY list, will avoid duplicates in the cache if the same document is +# loaded with two different URLs, and may allow you to 'e'dit the local +# from within lynx if you feel like it. +# +# 5. Broken links etc. +# -------------------- +# A user has moved from http://www.siteA.com/~jdoe to http://siteB.org/john, +# or http://www.provider.com/company/ has moved to their own server +# http://www.company.com, but there are still links to the old location +# all over the place; they now are broken or lead to a stupid "this page +# has moved, please update your bookmarks. Refresh in 5 seconds" page +# which you're tired of seeing. This will not fix your bookmarks, and +# it will let you see the outdated URLs for longer (Limitation 3 below), +# but for a quick fix: +# Redirect http://www.siteA.com/~jdoe/* http://siteB.org/john/* +# Redirect http://www.provider.com/company/* http://www.company.com/* +# +# You could use "Map" instead of "Redirect", but this would let you see the +# outdated URLs for longer and even bookmark them, and you are likely to +# create invalid links if not all documents from a site are mapped +# (Limitation 3). +# +# 6. DNS troubles +# --------------- +# A special case of broken links. If a site is inaccessible because the +# name cannot be resolved (your or their name server is broken, or the +# name registry once again made a mistake, or they really didn't pay in +# time...) but you still somehow know the address; or if name lookups are +# just too slow: +# Map http://www.somesite.com/* http://10.1.2.3/* +# (You could do the equivalent more cleanly by adding an entry to the hosts +# file, if you have access to it.) +# +# Or, if a name resolves to several addresses of which one is down, and the +# DNS hasn't caught up: +# Map http://www.w3.org/* http://www12.w3.org/* +# +# Note that this can break access to some name-based virtually hosted sites. +# +# In this case use of "Map" is probably preferred over "Redirect", as long +# as the URL on the left side contains the real and preferred hostname or +# the problem is only temporary. +# +# 7. Avoid redirections +# --------------------- +# Some sites have a habit to provide links that don't go to the destination +# directly but always force redirection via some intermediate URL. The +# delay imposed by this, especially for users with slower connections and +# for overloaded servers, can be avoided if the intermediate URLs always +# follow some simple pattern: we can then anticipate the redirect that will +# inevitably follow and generate it internally. For example, +# Redirect http://lwn.net/cgi-bin/vr/* http://* +# +# Warning: The page authors may not like this circumvention. Often the +# redirection is wanted by them to track access, sometimes in connection +# with cookies. Some sites may employ mechanisms that defeat the shortcut. +# It is your responsibility to decide whether use of this feature is +# acceptable. (But note that the same effect can be achieved anyway for +# any link by editing the URL, e.g. with the ELGOTO ('E') key in Lynx, so +# a shortcut like this does not create some new kind of intrusion.) +# +# 8. Detailed proxy selection +# --------------------------- +# Basic use for this one should be obvious, if you have a need for it. +# It simply allows selecting use (or non-use) of proxies on a more detailed +# level than the traditional <scheme>_proxy and no_proxy variables, as well +# as using different proxies for different sites. +# For example, to request access through an anonymizing proxy for all pages +# on a "suspicious" site: +# UseProxy http://suspicious.site/* http://anonymyzing.proxy.dom/ +# (as long as all URLs really have a matching form, not some alternative +# like <http://suspicious.site:80/> or <http://SuSpIcIoUs.site/>!) +# +# To access some site through a local squid proxy, running on the same host +# as lynx, except for some image types (say because you rarely access images +# with lynx anyway, and if you do, you don't want them cached by the proxy): +# UseProxy http://some.site/*.gif none +# UseProxy http://some.site/*.jpg none +# UseProxy http://some.site/* http://localhost:3128/ +# Note that order is important here. +# +# To exempt a local address from all proxying: +# UseProxy http://local.site/* none +# +# Note however that for some purposes the "no_proxy" setting may be better +# suited than "UseProxy ... none", because of its different matching logic +# (see comments in lynx.cfg). +# +# 9. Invent your own scheme +# ------------------------- +# Suppose you want to teach lynx to handle a completely new URL scheme. +# If what's required for the new scheme is already available in lynx in +# _some_ way, this may be possible with some inventive use of rules. +# As an example, let's assume you want to introduce a simple "man:" scheme +# for showing manual pages, so (for a Unix-like system, at least) "man:lynx" +# would display the same help information as the "man lynx" command and so +# on (we ignore section numbers etc. for simplicity here). +# First, since lynx doesn't know anything about a "man:" scheme, it will +# normally reject any such URLs at an early stage. However, a trick exists +# to bypass that hurdle: define a man_proxy environment variable *outside of +# lynx, before starting lynx* (it won't work in lynx.cfg), the actual value +# is unimportant and won't actually be used. For example, in your shell: +# export man_proxy=X +# +# If you already have some kind of HTTP-accessible man gateway available, +# the task then probably just amounts to transforming the URL into the right +# form. For one such gateway (in this case, a CGI script running on the +# local machine), the rule +# Redirect man:* http://localhost/cgi-bin/dwww?type=runman&location=*/ +# or, alternatively, +# UseProxy man:* none +# Map man:* http://localhost/cgi-bin/dwww?type=runman&location=*/ +# does it, for other setups the right-hand side just has to be modified +# appropriately. The "UseProxy" is to make sure the bogus man_proxy gets +# ignored. +# +# If no CGI-like access is available, you might want to invoke your system's +# man command directly for a man: URL. Here is some discussion of how this +# could be done, and why ultimately you may not want to do it; this is also +# an opportunity to show examples for how some of the rules and conditions +# can be used that haven't been discussed in detail elsewhere. +# Lynx provides the lynxexec: (and the similar lynxprog:) scheme for running +# (nearly) arbitrary commands locally. At the heart of employing it for +# man: would be a rule like this: +# Redirect man:* "lynxexec:/usr/bin/man *" +# (It is a peculiarity of this scheme that the literal space and quoting +# are necessary here. Also note that Map cannot be used here instead of +# Redirect, since lynxexec, as a special kind of URL, needs to be handled +# "early" in a request.) +# Of course, execution of arbitrary commands is a potentially dangerous +# thing. lynxexec has to be specifically enabled at compile time and in +# lynx.cfg (or with command line options), and there are various levels +# of control, too much to go into here. It is assumed in the following that +# lynxexec has been enabled to the degree necessary (allow /usr/bin/man +# execution) but hopefully not too much. +# What needs to be prevented is that allowing local execution of the man +# command might unintentionally open up unwanted execution of other commands, +# possibly by some trick that could be exploited. For example, redirecting +# man:* as above, the URL "man:lynx;rm -r *" could result in the command +# "man lynx;rm -r *" executed by the system, with obvious disastrous results. +# (This particular example won't actually work, for several reasons; but +# for the purpose of discussion let's assume it did, there may be similar +# ones that do.) +# Because of such dangers, redirection to a lynxexec: is normally never +# accepted by lynx. We need at least a PermitRedirection rule to override +# this protective limitation: +# PermitRedirection man:* +# Redirect man:* "lynxexec:/usr/bin/man *" +# But now we have potentially opened up local execution more than is +# acceptable via the man: scheme, so this needs to be examined. +# There are two aspects to security here: (1) restricting the user, and (2) +# protecting the user. The first could also be phrased as protecting the +# system from the user; the second as preventing lynx (and the system) from +# doing things the user doesn't really want. Aspect (1) is very important +# for setups providing anonymous guest accounts and similarly restricted +# environments. (Otherwise shell access is normally allowed, and trying to +# protect the system in lynx would be rather pointless.) As far as access +# to some URLs is concerned, the difference can be characterized in terms of +# which sources of URLs are trusted enough to allow access: for (1), only +# links occurring in a limited number of documents are trusted enough for +# some (or all) URLs, user input at 'g'oto prompts and the like is not (if +# not completely disabled). For (2) and assuming a user with normal shell +# privileges, the user may be trusted enough to accept any URL explicitly +# entered, but URLs from arbitrary external sources are not - someone might +# try to use them to trick the user (by following an innocent-looking link) +# or lynx (by following a redirection) into doing something undesirable. +# +# In the following we are concerned with (2); it is assumed that providers +# of anonymous accounts would not want to follow this path, and would have +# no need for additional schemes that imply local execution anyway. (For +# one thing, with the man example they would have to carefully check that +# users cannot break out of the man command to a local shell prompt.) +# +# Getting back to the example, it was already mentioned that lynx does not +# allow redirections to lynxexec. In fact this continues to be disallowed +# for real redirection received from HTTP servers. But we have introduced +# a new man: scheme, and the lynx code that does the redirection checking +# doesn't know anything about special considerations for man: URLs, so +# an external HTTP server might send a redirection message with "Location: +# man:<something>", which lynx would allow, and which would in turn be +# redirected by our rule to "lynxexec:/usr/bin/man <something>". Unless +# we are 100% sure that either this can never happen or that the lynxexec +# URL resulting from this can have no harmful effect, this needs to be +# prevented. It can be done by checking for the "redirected" condition, +# either by putting something like (the first line is of course optional) +# Alert man:* "Redirection to man: not allowed" if redirected +# Fail man:* if redirected +# somewhere before the Redirect rule, or, reversing the logic, by adding +# a condition to the redirection rules, i.e. they become +# PermitRedirection man:* unless redirected +# Redirect man:* "lynxexec:/usr/bin/man *" unless redirected +# (actually, putting the condition on either one of the rules would be +# sufficient). The second variant assumes that the attempted access to +# man: via redirection will ultimately fail because there is no other way +# to handle such URLs. +# +# The above should take care of rejecting man: URLs from redirections, but +# what about regular links in HTML (like <A HREF="man:...">)? As long as +# it can be assumed that the user will always inspect each and every link +# before following it, and never follow a link that can have harmful effect, +# no further restrictions are necessary. But this is a very big assumption, +# unrealistic except perhaps in some single-user setups where the user is +# is identical with the rule writer. So normally most links have to be +# regarded as suspect, and only URLs entered by the user can be accepted: +# Alert man:* "Redirection to man: not allowed" if redirected +# Fail man:* if redirected +# Alert man:* "Link to man: not allowed" unless userspecified +# Fail man:* unless userspecified +# +# With these restrictions we have limited the ways our new man: scheme can +# be used rather severely, to the point where its usefulness is questionable. +# In addition to 'g'oto prompts, it may work in Jump files; also, should +# links to man:<something> appear in HTML text, the user could retype them +# manually or use the ELGOTO ('E') command with some trivial editing (like +# adding a space) to "confirm" the URL. Even if the precautions outlined +# above are followed: THIS TEXT DOES NOT IMPLY ANY PROMISE THAT, BY FOLLOWING +# THE EXAMPLES, LYNX WILL BE SAFE. On the other hand, some of the precautions +# *may* not be necessary: it is possible that careful use of TRUSTED_EXEC +# options in lynx.cfg could offer enough protection while making the new +# scheme more useful. +# +# If all this seems a bit too scary, that's intentional; it should be noted +# that these considerations are not in general necessary for "harmless" URL +# schemes, but appropriate for this "extreme" example. One last remark +# regarding the hypothetical man scheme: instead of implementing it through +# "lynxexec:" or "lynxprog:", it would be somewhat safer to use "lynxcgi:" +# instead if it is supported. A simple lynxcgi script would have to write +# the man page to stdout (either converted to text/html or as plain text, +# preceded by an appropriate Content-Type header line), and all necessary +# checking for special shell characters would be done within the script - +# lynx does not use the system() function to run the script. +# +# Other Limitations +# ================= +# First, see CAVEAT above. There are other limitations: +# +# 1. Applicable URL schemes +# ------------------------- +# Rules processing does not apply to all URL schemes. Some are +# handled differently from the generic access code, therefore rules +# for such URLs will never be "seen". This limitation applies at +# least to lynxexec:, lynxprog:, mailto:, LYNXHIST:, LYNXMESSAGES:, +# LYNXCFG:, and LYNXCOMPILEOPTS: URLs. You shouldn't be tempted +# to try to redirect most of these schemes anyway, but this also +# makes it impossible to disable them with "Fail" rules. +# +# Also, a scheme has to be known to Lynx in order to get as far as +# applying rules - you cannot just define your own new foobar: scheme +# and then map it to something here, but see Application 9, above, +# for a workaround. +# +# 2. No re-checking +# ----------------- +# When a URL is mapped to a different one, the new URL is not checked +# again for compliance with most restrictions established by -anonymous, +# -restrictions, lynx.cfg and so on. This can be regarded as a feature: +# it allows specific exceptions. Of course it means that users for +# whom any restrictions must be enforced cannot have write access to a +# personal rules file, but that should be obvious anyway! +# This limitation does not applies if "Redirect" is used, in that case +# the new URL will always be re-examined. +# +# 3. Mappings are invisible +# ------------------------- +# Changing the URL with "Map" or "Pass" rules will in general not be +# visible to the user, because it happens at a late stage of processing +# a request (similar to directing a request through a proxy). One +# can think of two kinds of URL for every resource: a "Document URL" as +# the user sees it (on INFO page, history list, status line, etc.), and +# a "physical URL" used for the actual access. Rules change only the +# physical URL. This is different from the effect of HTTP redirection. +# Often this is bad, sometimes it may be desirable. +# +# Changing the URL can create broken links if a document has relative URLs, +# since they are taken to be relative to the "Document URL" (if no BASE tag +# is present) when the HTML is parsed. +# +# This limitation does not apply if "Redirect" is used - the new location +# will be visible to the user, and will be used by lynx for resolving +# relative URLs within the document. +# +# 4. Interaction with proxying +# ---------------------------- +# Rules processing is done after most other access checks, but before +# proxy (and gateway) settings are examined. A "Fail" rule works +# as expected, but when the URL has been mapped to a different one, +# the subsequent proxy checking can get confused. If it decides that +# access is through a proxy or gateway, it will generally use the +# original URL to construct the "physical" URL, effectively overriding +# the mapping rules. If the mapping is to a different access scheme +# or hostname, proxy checking could also be fooled to use a proxy when +# it shouldn't, to not use one when it should, or (if different proxies +# are used for different schemes) to use the wrong proxy. So "just +# don't do that"; in some cases setting the no_proxy variable will help. +# Example 3 happens to work nicely if there is a http_proxy but no +# ftp_proxy. +# +# This limitation does not come into play if a "UseProxy" rule is applied, +# in either of its two forms: with a PROXYURL, proxying is fully under +# the control of the rules author, and with "none", subsequent proxy +# and gateway checking is completely disabled. It is therefore a good +# idea to combine any "Map" and "Pass" rules that might result in passing +# the changed URL with explicit "UseProxy" rules, if the rules file is +# expected to be used together with proxying; or else always use "Redirect" +# instead of simple passing. +# +# 5. Case-sensitive matching +# -------------------------- +# The matching logic is generic string-based. It doesn't know anything +# about URL syntax, and so it cannot know in which parts of a URL case +# matters and where it doesn't. As a result, all comparisons are case- +# sensitive. If (a limited number of) case variations of a URL need +# to be dealt with, several rules can be used instead of one. +# In particular, this makes "UseProxy ... none" in some ways more limited +# than a no_proxy setting. +# +# 6. Redirection differences +# -------------------------- +# For some URLs lynx does never check after a request whether a redirection +# occurs; that makes the "Redirect" rule useless for such URLs (in addition +# to those mentioned under limitation 1.). Some of them are some gopher +# types, telnet: and similar in most situations, newspost: and similar, +# lynxcgi:, and some other private types. Trying to redirect these will +# make access fail. You probable don't want to change such URLs anyway, +# but if you feel you must, try using "Map" and "Pass" instead. +# +# The -noredir command line option only applies for real HTTP redirection +# responses, Redirect rules are still applied. Also for certain other +# command line options (-mime_header, -head) and command keys (HEAD) lynx +# shows the redirection message (or part of it) in case of a real HTTP +# redirection, instead of following the redirection. Here, too, a Redirect +# rule remains effective (there is no redirection message to show, after all). +# +# 7. URLs required +# ---------------- +# Full absolute URLs (modulo possible "*" matching wildcards) are required +# in rules. Strings like "www.somewhere.com" or "/some/dir/some.file" or +# "www.somewhere.com/some/dir/some.file" are not URLs. Lynx may accept +# them as user input, as abbreviated forms for URLs; but by the time the +# rules get checked, those have been converted to full URLs, if they can +# be recognized. This also means that rules cannot influence which strings +# typed at a 'g'oto prompt are recognized for URLs - rules processing kicks +# in later. |