[TASK] Add documentation 88/25488/2
authorNicole Cordes <cordes@cps-it.de>
Mon, 18 Nov 2013 14:50:18 +0000 (15:50 +0100)
committerNicole Cordes <typo3@cordes.co>
Mon, 18 Nov 2013 15:17:06 +0000 (16:17 +0100)
Release: 1.0
Change-Id: If1f68066bc0f82fdc0c7cbaea933119b5c53bec5
Reviewed-on: https://review.typo3.org/25488
Reviewed-by: Nicole Cordes
Tested-by: Nicole Cordes
Documentation/AdministratorManual/Index.rst [new file with mode: 0644]
Documentation/Images/Introduction/Overview.png [new file with mode: 0644]
Documentation/Includes.txt [new file with mode: 0644]
Documentation/Index.rst [new file with mode: 0644]
Documentation/Introduction/Index.rst [new file with mode: 0644]
Documentation/Settings.yml [new file with mode: 0644]
Documentation/Support/Index.rst [new file with mode: 0644]
Documentation/default.vcl [new file with mode: 0644]
Documentation/vcc_ban.vcl [deleted file]

diff --git a/Documentation/AdministratorManual/Index.rst b/Documentation/AdministratorManual/Index.rst
new file mode 100644 (file)
index 0000000..b0856dc
--- /dev/null
@@ -0,0 +1,115 @@
+.. ==================================================
+.. FOR YOUR INFORMATION
+.. --------------------------------------------------
+.. -*- coding: utf-8 -*- with BOM.
+
+.. include:: ../Includes.txt
+
+.. _admin-manual:
+
+Administrator Manual
+====================
+
+Varnish configuration
+---------------------
+
+Please add the following configuration to your vcl_recv function in your Varnish configuration file ::
+
+    # Add BAN request
+    if (req.request == "BAN") {
+        if (req.http.X-Host) {
+            ban("req.http.host == " + req.http.X-Host + " && req.url ~ " + req.http.X-Url + "[/]?(\?|&|$)");
+            error 200 "OK";
+        } else {
+            error 400 "Bad Request";
+        }
+    }
+
+To secure your environment consider to include reset of some server information in vcl_deliver ::
+
+    remove resp.http.Age;
+    remove resp.http.Via;
+    remove resp.http.X-Powered-By;
+    remove resp.http.X-Varnish;
+
+**For a best practise configuration see file** *Documentation/default.vcl*
+
+
+
+Installation
+------------
+
+To install the extension you just need to enable it in the Extension Manager.
+
+Extension configuration
+-----------------------
+
+Varnish Server [basic.server]
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Enter the IP address of your Varnish server. Use a comma seperated list for multiple server support.
+
+HTTP ban method [basic.httpMethod]
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+If you want to insert an own method which is sent to the Varnish server you can edit it here. Please note that this method has to be equal to the method used in your Varnish configuration file.
+
+HTTP protocol [basic.httpProtocol]
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Set the version of the http protocol which should be used to contact the Varnish server.
+
+Strip slash [basic.stripSlash]
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+If you use realurl extension (or any other url rendering) with the "appendMissingSlash" configuration you can configure vcc to strip the last slash. This can be useful if you want to customize the BAN handling in your varnish configuration e.g. use regular expressions.
+
+Support index.php script [basic.enableIndexScript]
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+If you use realurl extension (or any other url rendering) this option enables the cache clearing for alternative
+index.php url. This might help your editor to see the latest version if they view the page within the backend.
+
+Maximum age of log entries [basic.maxLogAge]
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+For each action one or multiple log entries (depends on debug setting) are generated in an own table. To minimize the table size you can set a specific age (in days) for the entries.
+
+Debug mode [basic.debug]
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+You can enable a detailed logging of the values generated for each action. These information are stored in an own database table as well as send to any devLog extension.
+
+TYPO3 PageTS configuration
+--------------------------
+
+You can configure the Varnish Cache Controll extension to be compatible to any data record in the backend. You just need to adopt the PageTS configuration which comes pre defined for pages and content elements. ::
+
+    mod.vcc {
+        pages = 1
+        pages {
+            typolink {
+                parameter.field = uid
+            }
+        }
+
+        pages_language_overlay = 1
+        pages_language_overlay {
+            typolink {
+                parameter.field = pid
+                additionalParams = &L={field:sys_language_uid}
+                additionalParams.insertData = 1
+            }
+        }
+
+        tt_content = 1
+        tt_content {
+            typolink {
+                parameter.field = pid
+                additionalParams = &L={field:sys_language_uid}
+                additionalParams.insertData = 1
+            }
+        }
+    }
+
+Just add a configuration with the name of your database table and a configuration how to generate the link to any (detail) page.
\ No newline at end of file
diff --git a/Documentation/Images/Introduction/Overview.png b/Documentation/Images/Introduction/Overview.png
new file mode 100644 (file)
index 0000000..97e13b2
Binary files /dev/null and b/Documentation/Images/Introduction/Overview.png differ
diff --git a/Documentation/Includes.txt b/Documentation/Includes.txt
new file mode 100644 (file)
index 0000000..636ed16
--- /dev/null
@@ -0,0 +1,21 @@
+.. ==================================================\r
+.. FOR YOUR INFORMATION\r
+.. --------------------------------------------------\r
+.. -*- coding: utf-8 -*- with BOM.\r
+\r
+.. This is 'Includes.txt'. It is included at the very top of each and\r
+   every ReST source file in this documentation project (= manual).\r
+\r
+\r
+.. ==================================================\r
+.. DEFINE SOME TEXT ROLES\r
+.. --------------------------------------------------\r
+\r
+.. role::   typoscript(code)\r
+\r
+.. role::   ts(typoscript)\r
+   :class:  typoscript\r
+\r
+.. role::   php(code)\r
+\r
+.. highlight:: php\r
diff --git a/Documentation/Index.rst b/Documentation/Index.rst
new file mode 100644 (file)
index 0000000..9b1f0de
--- /dev/null
@@ -0,0 +1,61 @@
+.. ==================================================
+.. FOR YOUR INFORMATION
+.. --------------------------------------------------
+.. -*- coding: utf-8 -*- with BOM.
+
+.. include:: Includes.txt
+
+
+.. _start:
+
+=============================================================
+Varnish Cache Control
+=============================================================
+
+.. only:: html
+
+       :Classification:
+               vcc
+
+       :Version:
+               |release|
+
+       :Language:
+               en
+
+       :Description:
+               Extension to clear Varnish cache on demand
+
+       :Keywords:
+               Varnish, Cache, Clear
+
+       :Copyright:
+               2013
+
+       :Author:
+               Nicole Cordes
+
+       :Email:
+               cordes@cps-it.de
+
+       :License:
+               This document is published under the Open Content License
+               available from http://www.opencontent.org/opl.shtml
+
+       :Rendered:
+               |today|
+
+       The content of this document is related to TYPO3,
+       a GNU/GPL CMS/Framework available from `www.typo3.org <http://www.typo3.org/>`_.
+
+
+       **Table of Contents**
+
+.. toctree::
+       :maxdepth: 5
+       :titlesonly:
+       :glob:
+
+       Introduction/Index
+       AdministratorManual/Index
+       Support/Index
diff --git a/Documentation/Introduction/Index.rst b/Documentation/Introduction/Index.rst
new file mode 100644 (file)
index 0000000..cbc6fb1
--- /dev/null
@@ -0,0 +1,29 @@
+.. ==================================================
+.. FOR YOUR INFORMATION
+.. --------------------------------------------------
+.. -*- coding: utf-8 -*- with BOM.
+
+.. include:: ../Includes.txt
+
+
+What does it do?
+================
+
+The extension provides an api to be able to handle commands to control the Varnish Cache within TYPO3.
+
+Besides it adds an icon to clear the Varnish Cache by every backend user.
+
+Screenshots
+===========
+
+.. figure:: ../Images/Introduction/Overview.png
+       :width: 600px
+       :alt: Visible server status of cache clearing
+
+Requirements
+============
+
+- Varnish server should be up and running
+- You should be familiar with the configuration language vcl of Varnish
+
+If you need an introduction or further information on the configuration of Varnish you can find a comprehensive documentation at https://www.varnish-software.com/book/
diff --git a/Documentation/Settings.yml b/Documentation/Settings.yml
new file mode 100644 (file)
index 0000000..6023097
--- /dev/null
@@ -0,0 +1,21 @@
+# This is the project specific Settings.yml file.
+# Place Sphinx specific build information here.
+# Settings given here will replace the settings of 'conf.py'.
+
+---
+conf.py:
+  copyright: 2013
+  project: Varnish Cache Control
+  version: 1.0
+  release: 1.0.1
+  latex_documents:
+  - - Index
+    - vcc.tex
+    - Varnish Cache Control
+    - Nicole Cordes
+    - manual
+  latex_elements:
+    papersize: a4paper
+    pointsize: 10pt
+    preamble: \usepackage{typo3}
+...
diff --git a/Documentation/Support/Index.rst b/Documentation/Support/Index.rst
new file mode 100644 (file)
index 0000000..025582e
--- /dev/null
@@ -0,0 +1,22 @@
+.. ==================================================
+.. FOR YOUR INFORMATION
+.. --------------------------------------------------
+.. -*- coding: utf-8 -*- with BOM.
+
+.. include:: ../Includes.txt
+
+
+Support
+=======
+
+forge.typo3.org
+^^^^^^^^^^^^^^^
+
+You can find further information about development and open issues of the Varnish Cache Control extension (vcc) on its
+projects site under http://forge.typo3.org/projects/extension-vcc .
+
+E-Mail
+^^^^^^
+
+If you have any open questions or if you need consulting for your projects we would like to help you.
+Feel free to contact us at cordes@cps-it.de if you need any kind of support.
\ No newline at end of file
diff --git a/Documentation/default.vcl b/Documentation/default.vcl
new file mode 100644 (file)
index 0000000..5c949eb
--- /dev/null
@@ -0,0 +1,168 @@
+# This is a basic VCL configuration file for varnish.  See the vcl(7)\r
+# man page for details on VCL syntax and semantics.\r
+#\r
+# Default backend definition.  Set this to point to your content\r
+# server.\r
+#\r
+backend default {\r
+       .host = "127.0.0.1";\r
+       .port = "80";\r
+\r
+       # Define health test\r
+       #.probe = {\r
+       #       .url = "/clear.gif";\r
+       #       .timeout = 1s;\r
+       #       .window = 5;\r
+       #       .threshold = 3;\r
+       #}\r
+}\r
+\r
+# Enable flushing access only to internals\r
+acl flushers {\r
+       "127.0.0.1";\r
+}\r
+\r
+sub vcl_recv {\r
+       # Set backend\r
+       set req.backend = default;\r
+\r
+       # Set a unique cache header with client ip\r
+       if (req.http.x-forwarded-for) {\r
+               set req.http.X-Forwarded-For = req.http.X-Forwarded-For + ", " + client.ip;\r
+       } else {\r
+               set req.http.X-Forwarded-For = client.ip;\r
+       }\r
+\r
+       # Allow the backend to deliver old content up to 1 day\r
+       set req.grace = 24h;\r
+       #if (req.backend.healthy) {\r
+       #       set req.grace = 30s;\r
+       #} else {\r
+       #       set req.grace = 24h;\r
+       #}\r
+\r
+       if (req.request != "GET" &&\r
+               req.request != "HEAD" &&\r
+               req.request != "PUT" &&\r
+               req.request != "POST" &&\r
+               req.request != "TRACE" &&\r
+               req.request != "OPTIONS" &&\r
+               req.request != "DELETE") {\r
+\r
+               # Add BAN request for acl flushers\r
+               if (req.request == "BAN") {\r
+                       if (client.ip ~ flushers) {\r
+                               if (req.http.X-Host) {\r
+                                       ban("req.http.host == " + req.http.X-Host + " && req.url ~ " + req.url + "[/]?(\?.*)?$");\r
+                                       error 200 "OK";\r
+                               } else {\r
+                                       error 400 "Bad Request";\r
+                               }\r
+                       } else {\r
+                               error 405 "Not allowed";\r
+                       }\r
+               } else {\r
+                       /* Non-RFC2616 or CONNECT which is weird. */\r
+                       return (pipe);\r
+               }\r
+       }\r
+\r
+       # If neither GET nor HEAD request, send to backend but do not cached\r
+       # This means that POST requests are not cached\r
+       if (req.request != "GET" && req.request != "HEAD") {\r
+               return (pass);\r
+       }\r
+\r
+       # If we work in backend don't cache anything\r
+       if (req.http.Cookie ~ "be_typo_user") {\r
+               return (pass);\r
+       }\r
+\r
+       # Always cache the following file types for all users.\r
+       if (req.url ~ "\.(png|gif|jpeg|jpg|ico|swf|css|js|pdf|txt)$") {\r
+               unset req.http.Cookie;\r
+       }\r
+\r
+       # If any authorisation was set do not cache\r
+       if (req.http.Authorization || req.http.Cookie ~ "fe_typo_user") {\r
+               return (pass);\r
+       } else {\r
+               # Pass all no_cache=1 sites and ajax requests\r
+               if (req.url ~ "no_cache=1" || req.url ~ "(\?|&)eID=") {\r
+                       return (pass);\r
+               }\r
+\r
+               # Delete cookies\r
+               unset req.http.Cookie;\r
+       }\r
+\r
+       # Handle compression correctly. Different browsers send different\r
+       # "Accept-Encoding" headers, even though they mostly all support the same\r
+       # compression mechanisms.\r
+       if (req.http.Accept-Encoding) {\r
+               if (req.http.Accept-Encoding ~ "gzip") {\r
+                       # If the browser supports gzip, that is what we use\r
+                       set req.http.Accept-Encoding = "gzip";\r
+               } else if (req.http.Accept-Encoding ~ "deflate") {\r
+                       # Next try deflate encoding\r
+                       set req.http.Accept-Encoding = "deflate";\r
+               } else {\r
+                       # Unknown algorithm. Remove it and send unencoded.\r
+                       unset req.http.Accept-Encoding;\r
+               }\r
+       }\r
+\r
+       # Lookup in cache\r
+       return (lookup);\r
+}\r
+\r
+sub vcl_hash {\r
+       # Build hash depending on url\r
+       hash_data(req.url);\r
+\r
+       # Build hash depending on host or server ip\r
+       if (req.http.host) {\r
+               hash_data(req.http.host);\r
+       } else {\r
+               hash_data(server.ip);\r
+       }\r
+\r
+       return (hash);\r
+}\r
+\r
+sub vcl_fetch {\r
+       # Set default cache to 3 days\r
+       set beresp.ttl = 3d;\r
+\r
+       # Deliver old content up to 1 day\r
+       set req.grace = 24h;\r
+\r
+       # Set cache to 10 days\r
+       if (req.url ~ "\.(png|gif|jpeg|jpg|ico|swf|css|js|pdf|txt)$") {\r
+               set beresp.ttl = 10d;\r
+       }\r
+\r
+       # Delete cookie\r
+       if (req.request == "POST" || req.url ~ "^/typo3" || req.url ~ "no_cache=1" || req.url ~ "(\?|&)eID=") {\r
+       } else {\r
+               unset beresp.http.Set-Cookie;\r
+       }\r
+\r
+       if (beresp.http.Set-Cookie || beresp.http.Vary == "*") {\r
+               # Mark as "Hit-For-Pass" for the next 2 minutes\r
+               set beresp.ttl = 120s;\r
+               return (hit_for_pass);\r
+       }\r
+\r
+       return (deliver);\r
+}\r
+\r
+sub vcl_deliver {\r
+       # Remove some suspect headers\r
+       remove resp.http.Age;\r
+       remove resp.http.Via;\r
+       remove resp.http.X-Powered-By;\r
+       remove resp.http.X-Varnish;\r
+\r
+       return (deliver);\r
+}
\ No newline at end of file
diff --git a/Documentation/vcc_ban.vcl b/Documentation/vcc_ban.vcl
deleted file mode 100644 (file)
index d1c6140..0000000
+++ /dev/null
@@ -1,32 +0,0 @@
-# Enable flushing access only to defined ip addresses\r
-acl flushers {\r
-       "127.0.0.1";\r
-}\r
-\r
-sub vcl_recv {\r
-       if (req.request != "GET" &&\r
-               req.request != "HEAD" &&\r
-               req.request != "PUT" &&\r
-               req.request != "POST" &&\r
-               req.request != "TRACE" &&\r
-               req.request != "OPTIONS" &&\r
-               req.request != "DELETE") {\r
-\r
-               # Add BAN request for acl flushers\r
-               if (req.request == "BAN") {\r
-                       if (client.ip ~ flushers) {\r
-                               if (req.http.X-Host) {\r
-                                       ban("req.http.host == " + req.http.X-Host + " && req.url ~ " + req.http.X-Url + "[/]?(\?|&|$)");\r
-                                       error 200 "OK";\r
-                               } else {\r
-                                       error 400 "Bad Request";\r
-                               }\r
-                       } else {\r
-                               error 405 "Not allowed";\r
-                       }\r
-               } else {\r
-                       /* Non-RFC2616 or CONNECT which is weird. */\r
-                       return (pipe);\r
-               }\r
-       }\r
-}
\ No newline at end of file