--- a/doc/upgrading.txt	Sat Mar 18 15:12:39 2017 -0400
+++ b/doc/upgrading.txt	Sat Mar 18 16:59:01 2017 -0400
@@ -23,6 +23,84 @@
 Migrating from 1.5.1 to 1.6.0
 =============================
 
+Cross Site Request Forgery Detection Added
+------------------------------------------
+
+Roundup 1.6. supports a number of defenses against CSRF.
+
+Http header verification against the tracker's ``web``
+setting in the ``[tracker]`` section of config.ini for the
+following headers:
+
+# Analyze the ``Referer`` HTTP header to make sure it
+  includes the web setting.
+# Analyse the ``Origin`` HTTP header to make sure the
+  schema://host matches the web setting.
+# Analyze the ``X-Forwarded-Host`` header set by a proxy
+  running in front of roundup to make sure it agrees with
+  the host part of the web setting.
+# Analyze the ``Host`` header to make sure it agrees with
+  the host part of the web setting. This is not done if
+  ``X-Forwarded-Host`` is set.
+
+By default roundup 1.6 does not require any specific header
+to be present. However at least one of the headers above
+*must* pass validation checks (usually ``Host`` or
+``Referer``) or the submission is rejected with an error.
+If any header fails validation, the submission is
+rejected. (Note the user's form keeps all the data they
+entered if it was rejected.)
+
+Also the admin can include unique csrf tokens for all forms
+submitted via post (delete and put methods are also
+included, but not currently used by roundup)). The csrf
+token (nonce) is tied to the user's session. When the user
+submits the form and nonce, the nonce is checked to make
+sure it was issued to the user and the same session. If this
+is not true the post is rejected and the user is notified.
+
+The standard context/submit templating item creates CSRF
+tokens by default. If you have forms that are not using the
+standard submit routine, you should add the following field
+to all forms:
+
+   <input name="@csrf" type="hidden"
+      tal:attributes="value python:utils.anti_csrf_nonce()">
+
+A unique random token is generated by every call to
+utils.anti_csrf_nonce() and is put in a database to be
+retreived if the token is used. Token lifetimes are 2 weeks
+by default but can be configured in config.ini. Roundup will
+automatically prune old tokens. Calling anti_csrf_nonce with
+an integer lifetime, for example
+
+   <input name="@csrf" type="hidden"
+      tal:attributes="value python:utils.anti_csrf_nonce(lifetime=10)">
+
+sets the lifetime of that nonce to 10 minutes.
+
+If you want to change the default settings, you have to
+update the web section in your tracker's config.ini's. To do
+this backup your existing config.ini.  Run:
+
+   roundup-admin -i /path/to/tracker genconfig config.ini.new
+
+to create a new config.ini in the file config.ini.new. Then
+merge the new csrf settings into your tracker's config.
+Look for settings that start with csrf. The config.ini.new
+file includes detailed descriptions of the settings.
+
+In general one of four values can be set for these
+settings. The default is ``yes``, which validates the header
+or nonce and blocks access if the validation fails. If the
+field/header is missing it allows access. Setting these
+fields to ``required`` blocks access if the header/nonce is
+missing.
+
+It is suggested that you change your templates so every form
+has an @csrf field and change the setting to 'required' for
+the csrf_enforce_token.
+
 Fix for path traversal changes template resolution
 --------------------------------------------------