# HG changeset patch
# User Mads Kiilerich <madski@unity3d.com>
# Date 1439766702 -7200
# Node ID 6257de126ec71cbd924a1dcdd2396dc83b821557
# Parent  4610a39d3be99f95d378af8b2407479d7ca07e9f
docs: improve documentation of beaker session configuration

beaker.session.auto is dropped; it defaults to false and there is no reason to
ever set it true for Kallithea.

beaker.session.cookie_path and secure are dropped; like cookie_domain, they
should automatically be set to the right value.
* * *
beaker.session.cookie_expires MUST have the default value of True to provide the default value of 'browser session lifetime' when not enabling 'remember' in the login box. The cookie life is hardcoded to 365 days when remember is selected.

diff -r 4610a39d3be9 -r 6257de126ec7 development.ini
--- a/development.ini	Mon Aug 17 01:11:42 2015 +0200
+++ b/development.ini	Mon Aug 17 01:11:42 2015 +0200
@@ -353,46 +353,35 @@
 ####################################
 ###       BEAKER SESSION        ####
 ####################################
+
+## Name of session cookie. Should be unique for a given host and path, even when running
+## on different ports. Otherwise, cookie sessions will be shared and messed up.
+beaker.session.key = kallithea
+## Sessions should always only be accessible by the browser, not directly by JavaScript.
+beaker.session.httponly = true
+## Session lifetime. 2592000 seconds is 30 days.
+beaker.session.timeout = 2592000
+
+## Server secret used with HMAC to ensure integrity of cookies.
+beaker.session.secret = development-not-secret
+## Further, encrypt the data with AES.
+#beaker.session.encrypt_key = <key_for_encryption>
+#beaker.session.validate_key = <validation_key>
+
 ## Type of storage used for the session, current types are
 ## dbm, file, memcached, database, and memory.
-## The storage uses the Container API
-## that is also used by the cache system.
+
+## File system storage of session data. (default)
+#beaker.session.type = file
 
-## db session ##
+## Cookie only, store all session data inside the cookie. Requires secure secrets.
+#beaker.session.type = cookie
+
+## Database storage of session data.
 #beaker.session.type = ext:database
 #beaker.session.sa.url = postgresql://postgres:qwe@localhost/kallithea
 #beaker.session.table_name = db_session
 
-## encrypted cookie client side session, good for many instances ##
-#beaker.session.type = cookie
-
-## file based cookies (default) ##
-#beaker.session.type = file
-
-## beaker.session.key should be unique for a given host, even when running
-## on different ports. Otherwise, cookie sessions will be shared and messed up.
-beaker.session.key = kallithea
-beaker.session.secret = development-not-secret
-
-## Secure encrypted cookie. Requires AES and AES python libraries
-## you must disable beaker.session.secret to use this
-#beaker.session.encrypt_key = <key_for_encryption>
-#beaker.session.validate_key = <validation_key>
-
-## sets session as invalid if it haven't been accessed for given amount of time
-beaker.session.timeout = 2592000
-beaker.session.httponly = true
-#beaker.session.cookie_path = /<your-prefix>
-
-## uncomment for https secure cookie
-beaker.session.secure = false
-
-## auto save the session to not to use .save()
-beaker.session.auto = False
-
-## default cookie expiration time in seconds `true` expire at browser close ##
-#beaker.session.cookie_expires = 3600
-
 ############################
 ## ERROR HANDLING SYSTEMS ##
 ############################
diff -r 4610a39d3be9 -r 6257de126ec7 docs/usage/performance.rst
--- a/docs/usage/performance.rst	Mon Aug 17 01:11:42 2015 +0200
+++ b/docs/usage/performance.rst	Mon Aug 17 01:11:42 2015 +0200
@@ -22,7 +22,7 @@
 
 1. Increase cache
 
-    Tweak beaker cache settings in the ini file. That actual effect of that
+    Tweak beaker cache settings in the ini file. The actual effect of that
     is questionable.
 
 2. Switch from sqlite to postgres or mysql
diff -r 4610a39d3be9 -r 6257de126ec7 kallithea/bin/template.ini.mako
--- a/kallithea/bin/template.ini.mako	Mon Aug 17 01:11:42 2015 +0200
+++ b/kallithea/bin/template.ini.mako	Mon Aug 17 01:11:42 2015 +0200
@@ -351,46 +351,35 @@
 <%text>####################################</%text>
 <%text>###       BEAKER SESSION        ####</%text>
 <%text>####################################</%text>
+
+<%text>## Name of session cookie. Should be unique for a given host and path, even when running</%text>
+<%text>## on different ports. Otherwise, cookie sessions will be shared and messed up.</%text>
+beaker.session.key = kallithea
+<%text>## Sessions should always only be accessible by the browser, not directly by JavaScript.</%text>
+beaker.session.httponly = true
+<%text>## Session lifetime. 2592000 seconds is 30 days.</%text>
+beaker.session.timeout = 2592000
+
+<%text>## Server secret used with HMAC to ensure integrity of cookies.</%text>
+beaker.session.secret = ${uuid()}
+<%text>## Further, encrypt the data with AES.</%text>
+#beaker.session.encrypt_key = <key_for_encryption>
+#beaker.session.validate_key = <validation_key>
+
 <%text>## Type of storage used for the session, current types are</%text>
 <%text>## dbm, file, memcached, database, and memory.</%text>
-<%text>## The storage uses the Container API</%text>
-<%text>## that is also used by the cache system.</%text>
+
+<%text>## File system storage of session data. (default)</%text>
+#beaker.session.type = file
 
-<%text>## db session ##</%text>
+<%text>## Cookie only, store all session data inside the cookie. Requires secure secrets.</%text>
+#beaker.session.type = cookie
+
+<%text>## Database storage of session data.</%text>
 #beaker.session.type = ext:database
 #beaker.session.sa.url = postgresql://postgres:qwe@localhost/kallithea
 #beaker.session.table_name = db_session
 
-<%text>## encrypted cookie client side session, good for many instances ##</%text>
-#beaker.session.type = cookie
-
-<%text>## file based cookies (default) ##</%text>
-#beaker.session.type = file
-
-<%text>## beaker.session.key should be unique for a given host, even when running</%text>
-<%text>## on different ports. Otherwise, cookie sessions will be shared and messed up.</%text>
-beaker.session.key = kallithea
-beaker.session.secret = ${uuid()}
-
-<%text>## Secure encrypted cookie. Requires AES and AES python libraries</%text>
-<%text>## you must disable beaker.session.secret to use this</%text>
-#beaker.session.encrypt_key = <key_for_encryption>
-#beaker.session.validate_key = <validation_key>
-
-<%text>## sets session as invalid if it haven't been accessed for given amount of time</%text>
-beaker.session.timeout = 2592000
-beaker.session.httponly = true
-#beaker.session.cookie_path = /<your-prefix>
-
-<%text>## uncomment for https secure cookie</%text>
-beaker.session.secure = false
-
-<%text>## auto save the session to not to use .save()</%text>
-beaker.session.auto = False
-
-<%text>## default cookie expiration time in seconds `true` expire at browser close ##</%text>
-#beaker.session.cookie_expires = 3600
-
 %if error_aggregation_service == 'errormator':
 <%text>############################</%text>
 <%text>## ERROR HANDLING SYSTEMS ##</%text>
diff -r 4610a39d3be9 -r 6257de126ec7 kallithea/config/deployment.ini_tmpl
--- a/kallithea/config/deployment.ini_tmpl	Mon Aug 17 01:11:42 2015 +0200
+++ b/kallithea/config/deployment.ini_tmpl	Mon Aug 17 01:11:42 2015 +0200
@@ -347,46 +347,35 @@
 ####################################
 ###       BEAKER SESSION        ####
 ####################################
+
+## Name of session cookie. Should be unique for a given host and path, even when running
+## on different ports. Otherwise, cookie sessions will be shared and messed up.
+beaker.session.key = kallithea
+## Sessions should always only be accessible by the browser, not directly by JavaScript.
+beaker.session.httponly = true
+## Session lifetime. 2592000 seconds is 30 days.
+beaker.session.timeout = 2592000
+
+## Server secret used with HMAC to ensure integrity of cookies.
+beaker.session.secret = ${app_instance_uuid}
+## Further, encrypt the data with AES.
+#beaker.session.encrypt_key = <key_for_encryption>
+#beaker.session.validate_key = <validation_key>
+
 ## Type of storage used for the session, current types are
 ## dbm, file, memcached, database, and memory.
-## The storage uses the Container API
-## that is also used by the cache system.
+
+## File system storage of session data. (default)
+#beaker.session.type = file
 
-## db session ##
+## Cookie only, store all session data inside the cookie. Requires secure secrets.
+#beaker.session.type = cookie
+
+## Database storage of session data.
 #beaker.session.type = ext:database
 #beaker.session.sa.url = postgresql://postgres:qwe@localhost/kallithea
 #beaker.session.table_name = db_session
 
-## encrypted cookie client side session, good for many instances ##
-#beaker.session.type = cookie
-
-## file based cookies (default) ##
-#beaker.session.type = file
-
-## beaker.session.key should be unique for a given host, even when running
-## on different ports. Otherwise, cookie sessions will be shared and messed up.
-beaker.session.key = kallithea
-beaker.session.secret = ${app_instance_uuid}
-
-## Secure encrypted cookie. Requires AES and AES python libraries
-## you must disable beaker.session.secret to use this
-#beaker.session.encrypt_key = <key_for_encryption>
-#beaker.session.validate_key = <validation_key>
-
-## sets session as invalid if it haven't been accessed for given amount of time
-beaker.session.timeout = 2592000
-beaker.session.httponly = true
-#beaker.session.cookie_path = /<your-prefix>
-
-## uncomment for https secure cookie
-beaker.session.secure = false
-
-## auto save the session to not to use .save()
-beaker.session.auto = False
-
-## default cookie expiration time in seconds `true` expire at browser close ##
-#beaker.session.cookie_expires = 3600
-
 ############################
 ## ERROR HANDLING SYSTEMS ##
 ############################
diff -r 4610a39d3be9 -r 6257de126ec7 kallithea/lib/base.py
--- a/kallithea/lib/base.py	Mon Aug 17 01:11:42 2015 +0200
+++ b/kallithea/lib/base.py	Mon Aug 17 01:11:42 2015 +0200
@@ -123,7 +123,8 @@
     session.invalidate()
     session['authuser'] = cookie = auth_user.to_cookie()
 
-    # If they want to be remembered, update the cookie
+    # If they want to be remembered, update the cookie.
+    # NOTE: Assumes that beaker defaults to browser session cookie.
     if remember:
         t = datetime.datetime.now() + datetime.timedelta(days=365)
         session._set_cookie_expires(t)
diff -r 4610a39d3be9 -r 6257de126ec7 test.ini
--- a/test.ini	Mon Aug 17 01:11:42 2015 +0200
+++ b/test.ini	Mon Aug 17 01:11:42 2015 +0200
@@ -353,46 +353,35 @@
 ####################################
 ###       BEAKER SESSION        ####
 ####################################
+
+## Name of session cookie. Should be unique for a given host and path, even when running
+## on different ports. Otherwise, cookie sessions will be shared and messed up.
+beaker.session.key = kallithea
+## Sessions should always only be accessible by the browser, not directly by JavaScript.
+beaker.session.httponly = true
+## Session lifetime. 2592000 seconds is 30 days.
+beaker.session.timeout = 2592000
+
+## Server secret used with HMAC to ensure integrity of cookies.
+beaker.session.secret = {74e0cd75-b339-478b-b129-07dd221def1f}
+## Further, encrypt the data with AES.
+#beaker.session.encrypt_key = <key_for_encryption>
+#beaker.session.validate_key = <validation_key>
+
 ## Type of storage used for the session, current types are
 ## dbm, file, memcached, database, and memory.
-## The storage uses the Container API
-## that is also used by the cache system.
+
+## File system storage of session data. (default)
+#beaker.session.type = file
 
-## db session ##
+## Cookie only, store all session data inside the cookie. Requires secure secrets.
+#beaker.session.type = cookie
+
+## Database storage of session data.
 #beaker.session.type = ext:database
 #beaker.session.sa.url = postgresql://postgres:qwe@localhost/kallithea
 #beaker.session.table_name = db_session
 
-## encrypted cookie client side session, good for many instances ##
-#beaker.session.type = cookie
-
-## file based cookies (default) ##
-#beaker.session.type = file
-
-## beaker.session.key should be unique for a given host, even when running
-## on different ports. Otherwise, cookie sessions will be shared and messed up.
-beaker.session.key = kallithea
-beaker.session.secret = {74e0cd75-b339-478b-b129-07dd221def1f}
-
-## Secure encrypted cookie. Requires AES and AES python libraries
-## you must disable beaker.session.secret to use this
-#beaker.session.encrypt_key = <key_for_encryption>
-#beaker.session.validate_key = <validation_key>
-
-## sets session as invalid if it haven't been accessed for given amount of time
-beaker.session.timeout = 2592000
-beaker.session.httponly = true
-#beaker.session.cookie_path = /<your-prefix>
-
-## uncomment for https secure cookie
-beaker.session.secure = false
-
-## auto save the session to not to use .save()
-beaker.session.auto = False
-
-## default cookie expiration time in seconds `true` expire at browser close ##
-#beaker.session.cookie_expires = 3600
-
 ############################
 ## ERROR HANDLING SYSTEMS ##
 ############################