On 29 May 2002, Patrick K. O'Brien said:
> Please make sure the new documents really hit you over the head with these
> items, their importance and how to set them properly. These were the bits I
> got wrong initially.

OK, I've just added the following text to doc/session-mgmt.txt; please
tell me if this explains things enough:

------------------------------------------------------------------------
Configuring the session cookie
------------------------------

Quixote allows you to configure several aspects of the session cookie
that it exchanges with clients.  First, you can set the name of the
cookie; this is important if you have multiple independent Quixote
applications running on the same server.  For example, the config file
for the first application might have

  COOKIE_NAME = "foo_session"

and the second application might have

  COOKIE_NAME = "bar_session"

Next, you can use COOKIE_DOMAIN and COOKIE_PATH to set the cookie
attributes that control which requests the cookie is included with.  By
default, these are both None, which instructs Quixote to send the cookie
without "Domain" or "Path" qualifiers.  For example, if the client
requests /foo/bar/ from www.example.com, and Quixote decides that it
must set the session cookie in the response to that request, then the
server would send

  Set-Cookie: QX_session="928F82A9B8FA92FD"

in the response headers.  Since no domain or path were specified with
that cookie, the browser will only include the cookie with requests to
www.example.com for URIs that start with "/foo/bar/".

If you want to ensure that your session cookie is included with all
requests to www.example.com, you should set COOKIE_PATH in your config
file:

  COOKIE_PATH = "/"

which will cause Quixote to set the cookie like this:

  Set-Cookie: QX_session="928F82A9B8FA92FD"; Path="/"

which will instruct the browser to include that cookie with *all*
requests to www.example.com.

However, think carefully about what you set COOKIE_PATH to -- eg. if you
set it to "/", but all of your Quixote code is under "/q/" in your
server's URL-space, then your user's session cookies could be
unnecessarily exposed.  On shared servers where you don't control all of
the code, this is especially dangerous.

If you want to share the cookie across servers in your domain,
eg. www1.example.com and www2.example.com, you'll also need to set
COOKIE_DOMAIN:

  COOKIE_DOMAIN = ".example.com"

See RFCs 2109 and 2965 for more information on the rules browsers are
supposed to follow for including cookies with HTTP requests.
------------------------------------------------------------------------

--
Greg Ward - software developer                gward@mems-exchange.org
MEMS Exchange                            http://www.mems-exchange.org