1 files changed, 124 insertions, 0 deletions
diff --git a/proto/PCRE_README.html b/proto/PCRE_README.html
new file mode 100644
index 0000000..dd391b2
--- /dev/null
+++ b/proto/PCRE_README.html
@@ -0,0 +1,124 @@
+<!doctype html public "-//W3C//DTD HTML 4.01 Transitional//EN"
+        "http://www.w3.org/TR/html4/loose.dtd">
+
+<html>
+
+<head>
+
+<title>Postfix PCRE Support</title>
+
+<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
+<link rel='stylesheet' type='text/css' href='postfix-doc.css'>
+
+</head>
+
+<body>
+
+<h1><img src="postfix-logo.jpg" width="203" height="98" ALT="">Postfix PCRE Support</h1>
+
+<hr>
+
+<h2>PCRE (Perl Compatible Regular Expressions) map support</h2>
+
+<p> The optional "pcre" map type allows you to specify regular
+expressions with the PERL style notation such as \s for space and
+\S for non-space. The main benefit, however, is that pcre lookups
+are often faster than regexp lookups. This is because the pcre
+implementation is often more efficient than the POSIX regular
+expression implementation that you find on many systems. </p>
+
+<p> A description of how to use pcre tables, including examples,
+is given in the pcre_table(5) manual page. Information about PCRE
+itself can be found at http://www.pcre.org/. </p>
+
+<h2>Using Postfix packages with PCRE support</h2>
+
+<p> To use pcre with Debian GNU/Linux's Postfix, or with Fedora or
+RHEL Postfix, all you
+need is to install the postfix-pcre package and you're done.  There
+is no need to recompile Postfix. </p>
+
+<h2>Building Postfix from source with PCRE support</h2>
+
+<p> These instructions assume that you build Postfix from source
+code as described in the INSTALL document. </p>
+
+<p> To build Postfix from source with pcre support, you need a pcre
+library. Install a vendor package, or download the source code from
+locations in https://www.pcre.org/ and build that yourself.
+
+<p> Postfix can build with the pcre2 library or the legacy pcre
+library. It's probably easiest to let the Postfix build procedure
+pick one. The following commands will first discover if the pcre2
+library is installed, and if that is not available, will discover
+if the legacy pcre library is installed. </p>
+
+<blockquote>
+<pre>
+$ make -f Makefile.init makefiles 
+$ make
+</pre>
+</blockquote>
+
+<p> To build Postfix explicitly with a pcre2 library (Postfix 3.7
+and later): </p>
+
+<blockquote>
+<pre>
+$ make -f Makefile.init makefiles \
+    "CCARGS=-DHAS_PCRE=2 `pcre2-config --cflags`" \
+    "AUXLIBS_PCRE=`pcre2-config --libs8`"
+$ make
+</pre>
+</blockquote>
+
+<p> To build Postfix explicitly with a legacy pcre library (all
+Postfix versions): </p>
+
+<blockquote>
+<pre>
+$ make -f Makefile.init makefiles \
+    "CCARGS=-DHAS_PCRE=1 `pcre-config --cflags`" \
+    "AUXLIBS_PCRE=`pcre-config --libs`"
+$ make
+</pre>
+</blockquote>
+
+<p> Postfix versions before 3.0 use AUXLIBS instead of AUXLIBS_PCRE.
+With Postfix 3.0 and later, the old AUXLIBS variable still supports
+building a statically-loaded PCRE database client, but only the new
+AUXLIBS_PCRE variable supports building a dynamically-loaded or 
+statically-loaded PCRE database client.  </p>
+
+<blockquote>
+ 
+<p> Failure to use the AUXLIBS_PCRE variable will defeat the purpose
+of dynamic database client loading. Every Postfix executable file
+will have PCRE library dependencies. And that was exactly
+what dynamic database client loading was meant to avoid. </p>
+ 
+</blockquote>
+
+<h2>Things to know</h2>
+
+<ul>
+
+<li> <p> When Postfix searches a pcre: or regexp: lookup table,
+each pattern is applied to the entire input string. Depending on
+the application, that string is an entire client hostname, an entire
+client IP address, or an entire mail address. Thus, no parent domain
+or parent network search is done, "user@domain" mail addresses are
+not broken up into their user and domain constituent parts, and
+"user+foo" is not broken up into user and foo.  </p>
+
+<li> <p> Regular expression tables such as pcre: or regexp: are
+not allowed to do $number substitution in lookup results that can
+be security sensitive: currently, that restriction applies to the
+local aliases(5) database or the virtual(8) delivery agent tables.
+</p>
+
+</ul>
+
+</body>
+
+</html>