X-Git-Url: http://www.privoxy.org/gitweb/?a=blobdiff_plain;f=doc%2Fsource%2Fdeveloper-manual.sgml;h=c23da1daba94727b6ae284fbef291657b0115511;hb=2e8c7e4321104708859ad7bf3e5697c0897778c5;hp=f6b892d064a799c13f0844d6f8f0ecbd8ce1d8b5;hpb=c7277a8982dd2acb7a60877c7b903674bcfc3c34;p=privoxy.git

diff --git a/doc/source/developer-manual.sgml b/doc/source/developer-manual.sgml
index f6b892d0..c23da1da 100644
--- a/doc/source/developer-manual.sgml
+++ b/doc/source/developer-manual.sgml
@@ -5,7 +5,7 @@
 <!entity p-intro SYSTEM "privoxy.sgml">
 <!entity history SYSTEM "history.sgml">
 <!entity seealso SYSTEM "seealso.sgml">
-<!entity p-version "3.0.25">
+<!entity p-version "3.0.27">
 <!entity p-status "UNRELEASED">
 <!entity % p-not-stable "INCLUDE">
 <!entity % p-stable "IGNORE">
@@ -21,9 +21,9 @@
                 This file belongs into
                 ijbswa.sourceforge.net:/home/groups/i/ij/ijbswa/htdocs/
 
- $Id: developer-manual.sgml,v 2.66 2016/02/02 13:08:55 fabiankeil Exp $
+ $Id: developer-manual.sgml,v 2.83 2017/06/08 13:08:39 fabiankeil Exp $
 
- Copyright (C) 2001-2016 Privoxy Developers http://www.privoxy.org/
+ Copyright (C) 2001-2016 Privoxy Developers https://www.privoxy.org/
  See LICENSE.
 
  ========================================================================
@@ -42,14 +42,14 @@
      <subscript>
     <!-- Completely the wrong markup, but very little is allowed  -->
     <!-- in this part of an article. FIXME -->
-      <ulink url="http://www.privoxy.org/user-manual/copyright.html">Copyright</ulink>
+      <ulink url="https://www.privoxy.org/user-manual/copyright.html">Copyright</ulink>
       &my-copy; 2001-2016 by
-      <ulink url="http://www.privoxy.org/">Privoxy Developers</ulink>
+      <ulink url="https://www.privoxy.org/">Privoxy Developers</ulink>
      </subscript>
     </pubdate>
 
 
-    <pubdate>$Id: developer-manual.sgml,v 2.66 2016/02/02 13:08:55 fabiankeil Exp $</pubdate>
+    <pubdate>$Id: developer-manual.sgml,v 2.83 2017/06/08 13:08:39 fabiankeil Exp $</pubdate>
 
 <!--
 
@@ -98,14 +98,11 @@ Hal.
  Please note that this document is constantly evolving. This copy represents
  the state at the release of version &p-version;.
  You can find the latest version of the this manual at <ulink
- url="http://www.privoxy.org/developer-manual/">http://www.privoxy.org/developer-manual/</ulink>.
+ url="https://www.privoxy.org/developer-manual/">https://www.privoxy.org/developer-manual/</ulink>.
  Please have a look at the
- <ulink url="http://www.privoxy.org/user-manual/contact.html">contact section in the user manual</ulink>
+ <ulink url="https://www.privoxy.org/user-manual/contact.html">contact section in the user manual</ulink>
  if you are interested in contacting the developers.
 </para>
-<!--        <para> -->
-<!--    Feel free to send a note to the developers at <email>ijbswa-developers@lists.sourceforge.net</email>. -->
-<!--   </para> -->
 
     </abstract>
   </artheader>
@@ -137,7 +134,7 @@ Hal.
   <sect2 id="quickstart"><title>Quickstart to Privoxy Development</title>
    <para>
     The first step is to join the <ulink
-      url="mailto:ijbswa-developers@lists.sourceforge.net">developer's mailing list</ulink>.
+      url="https://lists.privoxy.org/mailman/listinfo/privoxy-devel">privoxy-devel mailing list</ulink>.
     You can submit your ideas, or even better patches. Patches are best
     submitted to the Sourceforge tracker set up for this purpose, but
     can be sent to the list for review too.
@@ -168,11 +165,8 @@ Hal.
     <sect2 id="cvsaccess"><title>Access to CVS</title>
       <para>
         The project's CVS repository is hosted on
-        <ulink url="http://sourceforge.net/">SourceForge.</ulink>
-        Please refer to the chapters 6 and 7 in
-        <ulink url="http://sourceforge.net/docman/?group_id=1">SF's site
-        documentation</ulink> for the technical access details for your
-        operating system. For historical reasons, the CVS server is
+        <ulink url="https://sourceforge.net/">SourceForge.</ulink>
+        For historical reasons, the CVS server is
         called <literal>ijbswa.cvs.sourceforge.net</literal>, the repository is
         called <literal>ijbswa</literal>, and the source tree module is called
         <literal>current</literal>.
@@ -186,7 +180,8 @@ Hal.
        mentioned, the sources are in the <literal>current</literal>
        <quote>module</quote>. Other modules are present for platform specific
        issues. There is a webview of the CVS hierarchy at <ulink
-       url="http://ijbswa.cvs.sourceforge.net/ijbswa/">http://ijbswa.cvs.sourceforge.net/ijbswa/</ulink>,
+        url="http://ijbswa.cvs.sourceforge.net/viewvc/ijbswa/"
+            >http://ijbswa.cvs.sourceforge.net/viewvc/ijbswa/</ulink>,
        which might help with visualizing how these pieces fit together.
      </para>
      <!--
@@ -267,7 +262,7 @@ Hal.
            <para>
             Note that near a major public release, we get more cautious.
             There is always the possibility to submit a patch to the <ulink
-            url="http://sourceforge.net/tracker/?atid=311118&amp;group_id=11118&amp;func=browse">patch
+            url="https://sourceforge.net/tracker/?atid=311118&amp;group_id=11118&amp;func=browse">patch
             tracker</ulink> instead.
           </para>
          </listitem>
@@ -303,7 +298,7 @@ Hal.
         <para>
           Alternately, proposed changes can be submitted as patches to the patch tracker on
           Sourceforge first: <ulink
-          url="http://sourceforge.net/tracker/?group_id=11118&#38;atid=311118">http://sourceforge.net/tracker/?group_id=11118&#38;atid=311118</ulink>.
+          url="https://sourceforge.net/tracker/?group_id=11118&#38;atid=311118">https://sourceforge.net/tracker/?group_id=11118&#38;atid=311118</ulink>.
           Then ask for peer review.
         </para>
        </listitem>
@@ -1808,7 +1803,7 @@ const char FILENAME_rcs[] = "$I&lt;!-- Break CVS Substitution -->d$";
  * Purpose     :  (Fill me in with a good description!)
  *
  * Copyright   :  Written by and Copyright (C) 2001-2009
- *                the Privoxy team. http://www.privoxy.org/
+ *                the Privoxy team. https://www.privoxy.org/
  *
  *                This program is free software; you can redistribute it
  *                and/or modify it under the terms of the GNU General
@@ -1840,7 +1835,7 @@ const char FILENAME_h_rcs[] = FILENAME_H_VERSION;
 </programlisting>
 
     <para><emphasis>Note:</emphasis> This declares the rcs variables that should be
-    added to the "show-proxy-args" page. If this is a brand new
+    added to the "show-version" page. If this is a brand new
     creation by you, you are free to change the "Copyright" section
     to represent the rights you wish to maintain.</para>
 
@@ -1862,7 +1857,7 @@ const char FILENAME_h_rcs[] = FILENAME_H_VERSION;
  * Purpose     :  (Fill me in with a good description!)
  *
  * Copyright   :  Written by and Copyright (C) 2001-2009
- *                the Privoxy team. http://www.privoxy.org/
+ *                the Privoxy team. https://www.privoxy.org/
  *
  *                This program is free software; you can redistribute it
  *                and/or modify it under the terms of the GNU General
@@ -1980,6 +1975,70 @@ Install the rpm. Any error messages?
 </para>
     </sect2>
     <!-- XXX: Document how to write test reports and where to send them -->
+
+    <!--   ~~~~~       New section      ~~~~~     -->
+    <sect2 id="fuzzing"><title>Fuzzing Privoxy</title>
+     <para>
+       To make fuzzing more convenient, Privoxy can be configured
+       with --enable-fuzz which will result in the --fuzz option
+       becoming available.
+     </para>
+     <para>
+      Example (tested on ElectroBSD):
+     </para>
+     <programlisting>
+# Compile Privoxy with instrumentation for afl
+$ export CC=afl-clang
+$ export CFLAGS="-fsanitize=address -ggdb"
+$ export CPPFLAGS=-I/usr/local/include/
+$ export LDFLAGS="-fsanitize=address -L/usr/local/lib"
+$ export AFL_USE_ASAN=1
+$ export AFL_HARDEN=1
+$ ./configure --with-debug --enable-extended-host-patterns --enable-accept-filter --enable-no-gifs --enable-compression --enable-strptime-sanity-checks --enable-external-filters --enable-fuzz
+
+$ ./privoxy --fuzz
+Privoxy version 3.0.24 (http://www.privoxy.org/)
+Usage: ./privoxy [--config-test] [--chroot] [--help] [--no-daemon] [--pidfile pidfile] [--pre-chroot-nslookup hostname] [--user user[.group]] [--version] [configfile]
+       ./privoxy --fuzz fuzz-mode ./path/to/fuzzed/input [--stfu]
+
+Supported fuzz modes and the expected input:
+ action: Text to parse as action file.
+ client-request: Client request to parse. Currently incomplete
+ client-header: Client header to parse.
+ chunked-transfer-encoding: Chunk-encoded data to dechunk.
+ deflate: deflate-compressed data to decompress.
+ filter: Text to parse as filter file.
+ gif: gif to deanimate.
+ gzip: gzip-compressed data to decompress.
+ pcrs-substitute: A pcrs-substitute to compile. Not a whole pcrs job! Example: Bla $1 bla C $3 blah.
+ server-header: Server header to parse.
+ server-response: Server response to parse.
+
+The following fuzz modes read data from stdin if the 'file' is '-'
+ client-request
+ client-header
+ chunked-transfer-encoding
+ deflate
+ gif
+ gzip
+ pcrs-substitute
+ server-header
+ server-response
+
+Aborting
+
+$ export ASAN_OPTIONS='abort_on_error=1'
+$ mkdir input output
+$ echo '$1 bla fasel $2' > input/pcrs
+$ afl-fuzz -i input -o output -m none ~/git/privoxy/privoxy --fuzz pcrs-substitute - --stfu
+
+$ cat >input/pcrs.txt
+FILTER: bla fasel
+s@(.{1})[432](\d+)@$1$2$hostname@UgisT
+
+$ afl-fuzz -i input/ -o output/ -f bla.filter -m none privoxy --fuzz filter bla.filter --stfu
+</programlisting>
+    </sect2>
   </sect1>
 
   <!--   ~~~~~       New section      ~~~~~     -->
@@ -2107,25 +2166,29 @@ Install the rpm. Any error messages?
       <listitem>
        <para>
          Increment the version number (point from odd to even in development
-         branches!) in <filename>configure.in</filename>. (RPM spec files
-         will need to be incremented as well.)
+         branches!) in <filename>configure.in</filename> and update the code
+         status (CODE_STATUS="xxx") to one of "alpha", "beta" or "stable".
+         Rebuild configure and GNUMakefile to make sure the updated values are
+         being used.
        </para>
       </listitem>
       <listitem>
        <para>
-        If <filename>default.action</filename> has changed since last
-        release (i.e. software release or standalone actions file release),
-        bump up its version info to A.B in this line:
+        Use the dok-release target to update the sgml documentation source files.
        </para>
+      </listitem>
+      <listitem>
        <para>
+        If action file processing has changed and is not backward-compatible,
+        make sure the "for-privoxy-version=x.y.z" minimum version number in
+        default.action.master has been updated:
         <programlisting>
-  {+add-header{X-Actions-File-Version: A.B} -filter -no-popups}
+{{settings}}
+#############################################################################
+#MASTER# COMMENT: The minimum Privoxy version:
+for-privoxy-version=3.0.11
 </programlisting>
        </para>
-       <para>
-        Then change the version info in doc/webserver/actions/index.php,
-        line: '$required_actions_file_version = "A.B";'
-       </para>
       </listitem>
       <listitem>
        <para>
@@ -2134,7 +2197,7 @@ Install the rpm. Any error messages?
         without the ability to build these). Some docs may require
         rather obscure processing tools. <filename>config</filename>,
         the man page (and the html version of the man page)
-        fall in this category. REAMDE, the man page, AUTHORS, and config
+        fall in this category. README, the man page, AUTHORS, and config
         should all also be committed to CVS for other packagers. The
         formal docs should be uploaded to the webserver. See the
         Section "Updating the webserver" in this manual for details.
@@ -2412,7 +2475,7 @@ Install the rpm. Any error messages?
         be reset to one if this is the first RPM for
         <replaceable class="parameter">dist</replaceable> which is built from version
         X.Y.Z. Check the
-        <ulink url="http://sourceforge.net/project/showfiles.php?group_id=11118">file
+        <ulink url="https://sourceforge.net/project/showfiles.php?group_id=11118">file
         list</ulink> if unsure. Else, it must be set to the highest already available RPM
         release number for that version plus one.
       </para>
@@ -2723,6 +2786,7 @@ Install the rpm. Any error messages?
         For details see the <ulink url="https://www.freebsd.org/doc/en_US.ISO8859-1/books/porters-handbook/">FreeBSD Porter's Handbook</ulink>.
       </para>
     </sect3>
+   </sect2>
 
    <sect2 id="releasing">
    <title>Uploading and Releasing Your Package</title>
@@ -2786,10 +2850,10 @@ Install the rpm. Any error messages?
     <title>After the Release</title>
      <para>
       When all (or: most of the) packages have been uploaded and made available,
-      send an email to the <ulink url="mailto:ijbswa-announce@lists.sourceforge.net">announce
+      send an email to the <ulink url="mailto:privoxy-announce@lists.privoxy.org">announce
       mailing list</ulink>, Subject: "Version X.Y.Z available for download". Be sure to
       include the
-      <ulink url="http://sourceforge.net/project/showfiles.php?group_id=11118">download
+      <ulink url="https://sourceforge.net/project/showfiles.php?group_id=11118">download
       location</ulink>, the release notes and the Changelog. Also, post an
       updated News item on the project page Sourceforge, and update the Home
       page and docs linked from the Home page (see below). Other news sites
@@ -2844,7 +2908,7 @@ Install the rpm. Any error messages?
 </programlisting>
    </para>
    <para>
-    This will do the upload to <ulink url="http://www.privoxy.org/">the
+    This will do the upload to <ulink url="https://www.privoxy.org/">the
     webserver</ulink> (www.privoxy.org) and ensure all files and directories
     there are group writable.
    </para>