Blame docs/manual/mod/mod_session_dbd.html.en

Packit 90a5c9
Packit 90a5c9
Packit 90a5c9
<html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en"><head>
Packit 90a5c9
<meta content="text/html; charset=ISO-8859-1" http-equiv="Content-Type" />
Packit 90a5c9
Packit 90a5c9
        XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
Packit 90a5c9
              This file is generated from xml source: DO NOT EDIT
Packit 90a5c9
        XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
Packit 90a5c9
      -->
Packit 90a5c9
<title>mod_session_dbd - Apache HTTP Server Version 2.4</title>
Packit 90a5c9
<link href="../style/css/manual.css" rel="stylesheet" media="all" type="text/css" title="Main stylesheet" />
Packit 90a5c9
<link href="../style/css/manual-loose-100pc.css" rel="alternate stylesheet" media="all" type="text/css" title="No Sidebar - Default font size" />
Packit 90a5c9
<link href="../style/css/manual-print.css" rel="stylesheet" media="print" type="text/css" /><link rel="stylesheet" type="text/css" href="../style/css/prettify.css" />
Packit 90a5c9
<script src="../style/scripts/prettify.min.js" type="text/javascript">
Packit 90a5c9
</script>
Packit 90a5c9
Packit 90a5c9
<link href="../images/favicon.ico" rel="shortcut icon" /></head>
Packit 90a5c9
<body>
Packit 90a5c9
Packit 90a5c9

Modules | Directives | FAQ | Glossary | Sitemap

Packit 90a5c9

Apache HTTP Server Version 2.4

Packit 90a5c9
Packit 90a5c9
<-
Packit 90a5c9
Packit 90a5c9
Apache > HTTP Server > Documentation > Version 2.4 > Modules
Packit 90a5c9
Packit 90a5c9

Apache Module mod_session_dbd

Packit 90a5c9
Packit 90a5c9

Available Languages:  en  |

Packit 90a5c9
 fr 

Packit 90a5c9
Packit 90a5c9
Description:DBD/SQL based session support
Packit 90a5c9
Status:Extension
Packit 90a5c9
Module Identifier:session_dbd_module
Packit 90a5c9
Source File:mod_session_dbd.c
Packit 90a5c9
Compatibility:Available in Apache 2.3 and later
Packit 90a5c9

Summary

Packit 90a5c9
Packit 90a5c9
    

Warning

Packit 90a5c9
      

The session modules make use of HTTP cookies, and as such can fall

Packit 90a5c9
      victim to Cross Site Scripting attacks, or expose potentially private
Packit 90a5c9
      information to clients. Please ensure that the relevant risks have
Packit 90a5c9
      been taken into account before enabling the session functionality on
Packit 90a5c9
      your server.

Packit 90a5c9
    
Packit 90a5c9
Packit 90a5c9
    

This submodule of mod_session provides support for the

Packit 90a5c9
    storage of user sessions within a SQL database using the
Packit 90a5c9
    mod_dbd module.

Packit 90a5c9
Packit 90a5c9
    

Sessions can either be anonymous, where the session is

Packit 90a5c9
    keyed by a unique UUID string stored on the browser in a cookie, or
Packit 90a5c9
    per user, where the session is keyed against the userid of
Packit 90a5c9
    the logged in user.

Packit 90a5c9
Packit 90a5c9
    

SQL based sessions are hidden from the browser, and so offer a measure of

Packit 90a5c9
    privacy without the need for encryption.

Packit 90a5c9
Packit 90a5c9
    

Different webservers within a server farm may choose to share a database,

Packit 90a5c9
    and so share sessions with one another.

Packit 90a5c9
Packit 90a5c9
    

For more details on the session interface, see the documentation for

Packit 90a5c9
    the mod_session module.

Packit 90a5c9
Packit 90a5c9
Packit 90a5c9
Support Apache!

Topics

Packit 90a5c9
    Packit 90a5c9
  • DBD Configuration
  • Packit 90a5c9
  • Anonymous Sessions
  • Packit 90a5c9
  • Per User Sessions
  • Packit 90a5c9
  • Database Housekeeping
  • Packit 90a5c9

    Directives

    Packit 90a5c9
      Packit 90a5c9
    • SessionDBDCookieName
    • Packit 90a5c9
    • SessionDBDCookieName2
    • Packit 90a5c9
    • SessionDBDCookieRemove
    • Packit 90a5c9
    • SessionDBDDeleteLabel
    • Packit 90a5c9
    • SessionDBDInsertLabel
    • Packit 90a5c9
    • SessionDBDPerUser
    • Packit 90a5c9
    • SessionDBDSelectLabel
    • Packit 90a5c9
    • SessionDBDUpdateLabel
    • Packit 90a5c9
      Packit 90a5c9

      Bugfix checklist

      See also

      Packit 90a5c9
        Packit 90a5c9
      • mod_session
      • Packit 90a5c9
      • mod_session_crypto
      • Packit 90a5c9
      • mod_session_cookie
      • Packit 90a5c9
      • mod_dbd
      • Packit 90a5c9
      • Comments
      • Packit 90a5c9
        top
        Packit 90a5c9
        Packit 90a5c9

        DBD Configuration

        Packit 90a5c9
        Packit 90a5c9
              

        Before the mod_session_dbd module can be configured to maintain a

        Packit 90a5c9
              session, the mod_dbd module must be configured to make the various database queries
        Packit 90a5c9
              available to the server.

        Packit 90a5c9
        Packit 90a5c9
              

        There are four queries required to keep a session maintained, to select an existing session,

        Packit 90a5c9
              to update an existing session, to insert a new session, and to delete an expired or empty
        Packit 90a5c9
              session. These queries are configured as per the example below.

        Packit 90a5c9
        Packit 90a5c9
              

        Sample DBD configuration

        DBDriver pgsql
        Packit 90a5c9
        DBDParams "dbname=apachesession user=apache password=xxxxx host=localhost"
        Packit 90a5c9
        DBDPrepareSQL "delete from session where key = %s" deletesession
        Packit 90a5c9
        DBDPrepareSQL "update session set value = %s, expiry = %lld, key = %s where key = %s" updatesession
        Packit 90a5c9
        DBDPrepareSQL "insert into session (value, expiry, key) values (%s, %lld, %s)" insertsession
        Packit 90a5c9
        DBDPrepareSQL "select value from session where key = %s and (expiry = 0 or expiry > %lld)" selectsession
        Packit 90a5c9
        DBDPrepareSQL "delete from session where expiry != 0 and expiry < %lld" cleansession
        Packit 90a5c9
        Packit 90a5c9
        Packit 90a5c9
            
        top
        Packit 90a5c9
        Packit 90a5c9

        Anonymous Sessions

        Packit 90a5c9
        Packit 90a5c9
              

        Anonymous sessions are keyed against a unique UUID, and stored on the

        Packit 90a5c9
              browser within an HTTP cookie. This method is similar to that used by most
        Packit 90a5c9
              application servers to store session information.

        Packit 90a5c9
        Packit 90a5c9
              

        To create a simple anonymous session and store it in a postgres database

        Packit 90a5c9
              table called apachesession, and save the session ID in a cookie
        Packit 90a5c9
              called session, configure the session as follows:

        Packit 90a5c9
        Packit 90a5c9
              

        SQL based anonymous session

        Session On
        Packit 90a5c9
        SessionDBDCookieName session path=/
        Packit 90a5c9
        Packit 90a5c9
        Packit 90a5c9
              

        For more examples on how the session can be configured to be read

        Packit 90a5c9
              from and written to by a CGI application, see the
        Packit 90a5c9
              mod_session examples section.

        Packit 90a5c9
        Packit 90a5c9
              

        For documentation on how the session can be used to store username

        Packit 90a5c9
              and password details, see the mod_auth_form module.

        Packit 90a5c9
        Packit 90a5c9
            
        top
        Packit 90a5c9
        Packit 90a5c9

        Per User Sessions

        Packit 90a5c9
        Packit 90a5c9
              

        Per user sessions are keyed against the username of a successfully

        Packit 90a5c9
              authenticated user. It offers the most privacy, as no external handle
        Packit 90a5c9
              to the session exists outside of the authenticated realm.

        Packit 90a5c9
        Packit 90a5c9
              

        Per user sessions work within a correctly configured authenticated

        Packit 90a5c9
              environment, be that using basic authentication, digest authentication
        Packit 90a5c9
              or SSL client certificates. Due to the limitations of who came first,
        Packit 90a5c9
              the chicken or the egg, per user sessions cannot be used to store
        Packit 90a5c9
              authentication credentials from a module like
        Packit 90a5c9
              mod_auth_form.

        Packit 90a5c9
        Packit 90a5c9
              

        To create a simple per user session and store it in a postgres database

        Packit 90a5c9
              table called apachesession, and with the session keyed to the
        Packit 90a5c9
              userid, configure the session as follows:

        Packit 90a5c9
        Packit 90a5c9
              

        SQL based per user session

        Session On
        Packit 90a5c9
        SessionDBDPerUser On
        Packit 90a5c9
        Packit 90a5c9
        Packit 90a5c9
            
        top
        Packit 90a5c9
        Packit 90a5c9

        Database Housekeeping

        Packit 90a5c9
              

        Over the course of time, the database can be expected to start accumulating

        Packit 90a5c9
              expired sessions. At this point, the mod_session_dbd module
        Packit 90a5c9
              is not yet able to handle session expiry automatically.

        Packit 90a5c9
        Packit 90a5c9
              

        Warning

        Packit 90a5c9
              

        The administrator will need to set up an external process via cron to clean

        Packit 90a5c9
              out expired sessions.

        Packit 90a5c9
              
        Packit 90a5c9
        Packit 90a5c9
            
        Packit 90a5c9
        top
        Packit 90a5c9
        Packit 90a5c9
        Packit 90a5c9
        Description:Name and attributes for the RFC2109 cookie storing the session ID
        Packit 90a5c9
        Syntax:SessionDBDCookieName name attributes
        Packit 90a5c9
        Default:none
        Packit 90a5c9
        Context:server config, virtual host, directory, .htaccess
        Packit 90a5c9
        Status:Extension
        Packit 90a5c9
        Module:mod_session_dbd
        Packit 90a5c9
        Packit 90a5c9
            

        The SessionDBDCookieName directive specifies the name and

        Packit 90a5c9
            optional attributes of an RFC2109 compliant cookie inside which the session ID will
        Packit 90a5c9
            be stored. RFC2109 cookies are set using the Set-Cookie HTTP header.
        Packit 90a5c9
            

        Packit 90a5c9
        Packit 90a5c9
            

        An optional list of cookie attributes can be specified, as per the example below.

        Packit 90a5c9
            These attributes are inserted into the cookie as is, and are not interpreted by
        Packit 90a5c9
            Apache. Ensure that your attributes are defined correctly as per the cookie specification.
        Packit 90a5c9
            

        Packit 90a5c9
        Packit 90a5c9
            

        Cookie with attributes

        Session On
        Packit 90a5c9
        SessionDBDCookieName session path=/private;domain=example.com;httponly;secure;version=1;
        Packit 90a5c9
        Packit 90a5c9
        Packit 90a5c9
        Packit 90a5c9
        Packit 90a5c9
        top
        Packit 90a5c9
        Packit 90a5c9
        Packit 90a5c9
        Description:Name and attributes for the RFC2965 cookie storing the session ID
        Packit 90a5c9
        Syntax:SessionDBDCookieName2 name attributes
        Packit 90a5c9
        Default:none
        Packit 90a5c9
        Context:server config, virtual host, directory, .htaccess
        Packit 90a5c9
        Status:Extension
        Packit 90a5c9
        Module:mod_session_dbd
        Packit 90a5c9
        Packit 90a5c9
            

        The SessionDBDCookieName2 directive specifies the name and

        Packit 90a5c9
            optional attributes of an RFC2965 compliant cookie inside which the session ID will
        Packit 90a5c9
            be stored. RFC2965 cookies are set using the Set-Cookie2 HTTP header.
        Packit 90a5c9
            

        Packit 90a5c9
        Packit 90a5c9
            

        An optional list of cookie attributes can be specified, as per the example below.

        Packit 90a5c9
            These attributes are inserted into the cookie as is, and are not interpreted by
        Packit 90a5c9
            Apache. Ensure that your attributes are defined correctly as per the cookie specification.
        Packit 90a5c9
            

        Packit 90a5c9
        Packit 90a5c9
            

        Cookie2 with attributes

        Session On
        Packit 90a5c9
        SessionDBDCookieName2 session path=/private;domain=example.com;httponly;secure;version=1;
        Packit 90a5c9
        Packit 90a5c9
        Packit 90a5c9
        Packit 90a5c9
        Packit 90a5c9
        top
        Packit 90a5c9
        Packit 90a5c9
        Packit 90a5c9
        Description:Control for whether session ID cookies should be removed from incoming HTTP headers
        Packit 90a5c9
        Syntax:SessionDBDCookieRemove On|Off
        Packit 90a5c9
        Default:SessionDBDCookieRemove On
        Packit 90a5c9
        Context:server config, virtual host, directory, .htaccess
        Packit 90a5c9
        Status:Extension
        Packit 90a5c9
        Module:mod_session_dbd
        Packit 90a5c9
        Packit 90a5c9
            

        The SessionDBDCookieRemove flag controls whether the cookies

        Packit 90a5c9
            containing the session ID will be removed from the headers during request processing.

        Packit 90a5c9
        Packit 90a5c9
            

        In a reverse proxy situation where the Apache server acts as a server frontend for

        Packit 90a5c9
            a backend origin server, revealing the contents of the session ID cookie to the backend
        Packit 90a5c9
            could be a potential privacy violation. When set to on, the session ID cookie will be
        Packit 90a5c9
            removed from the incoming HTTP headers.

        Packit 90a5c9
        Packit 90a5c9
        Packit 90a5c9
        Packit 90a5c9
        top
        Packit 90a5c9
        Packit 90a5c9
        Packit 90a5c9
        Description:The SQL query to use to remove sessions from the database
        Packit 90a5c9
        Syntax:SessionDBDDeleteLabel label
        Packit 90a5c9
        Default:SessionDBDDeleteLabel deletesession
        Packit 90a5c9
        Context:server config, virtual host, directory, .htaccess
        Packit 90a5c9
        Status:Extension
        Packit 90a5c9
        Module:mod_session_dbd
        Packit 90a5c9
        Packit 90a5c9
            

        The SessionDBDDeleteLabel directive sets the default delete

        Packit 90a5c9
            query label to be used to delete an expired or empty session. This label must have been previously
        Packit 90a5c9
            defined using the DBDPrepareSQL directive.

        Packit 90a5c9
        Packit 90a5c9
        Packit 90a5c9
        Packit 90a5c9
        top
        Packit 90a5c9
        Packit 90a5c9
        Packit 90a5c9
        Description:The SQL query to use to insert sessions into the database
        Packit 90a5c9
        Syntax:SessionDBDInsertLabel label
        Packit 90a5c9
        Default:SessionDBDInsertLabel insertsession
        Packit 90a5c9
        Context:server config, virtual host, directory, .htaccess
        Packit 90a5c9
        Status:Extension
        Packit 90a5c9
        Module:mod_session_dbd
        Packit 90a5c9
        Packit 90a5c9
            

        The SessionDBDInsertLabel directive sets the default insert

        Packit 90a5c9
            query label to be used to load in a session. This label must have been previously defined using the
        Packit 90a5c9
            DBDPrepareSQL directive.

        Packit 90a5c9
        Packit 90a5c9
            

        If an attempt to update the session affects no rows, this query will be called to insert the

        Packit 90a5c9
            session into the database.

        Packit 90a5c9
        Packit 90a5c9
        Packit 90a5c9
        Packit 90a5c9
        top
        Packit 90a5c9
        Packit 90a5c9
        Packit 90a5c9
        Description:Enable a per user session
        Packit 90a5c9
        Syntax:SessionDBDPerUser On|Off
        Packit 90a5c9
        Default:SessionDBDPerUser Off
        Packit 90a5c9
        Context:server config, virtual host, directory, .htaccess
        Packit 90a5c9
        Status:Extension
        Packit 90a5c9
        Module:mod_session_dbd
        Packit 90a5c9
        Packit 90a5c9
            

        The SessionDBDPerUser flag enables a per user session keyed

        Packit 90a5c9
            against the user's login name. If the user is not logged in, this directive will be
        Packit 90a5c9
            ignored.

        Packit 90a5c9
        Packit 90a5c9
        Packit 90a5c9
        Packit 90a5c9
        top
        Packit 90a5c9
        Packit 90a5c9
        Packit 90a5c9
        Description:The SQL query to use to select sessions from the database
        Packit 90a5c9
        Syntax:SessionDBDSelectLabel label
        Packit 90a5c9
        Default:SessionDBDSelectLabel selectsession
        Packit 90a5c9
        Context:server config, virtual host, directory, .htaccess
        Packit 90a5c9
        Status:Extension
        Packit 90a5c9
        Module:mod_session_dbd
        Packit 90a5c9
        Packit 90a5c9
            

        The SessionDBDSelectLabel directive sets the default select

        Packit 90a5c9
            query label to be used to load in a session. This label must have been previously defined using the
        Packit 90a5c9
            DBDPrepareSQL directive.

        Packit 90a5c9
        Packit 90a5c9
        Packit 90a5c9
        Packit 90a5c9
        top
        Packit 90a5c9
        Packit 90a5c9
        Packit 90a5c9
        Description:The SQL query to use to update existing sessions in the database
        Packit 90a5c9
        Syntax:SessionDBDUpdateLabel label
        Packit 90a5c9
        Default:SessionDBDUpdateLabel updatesession
        Packit 90a5c9
        Context:server config, virtual host, directory, .htaccess
        Packit 90a5c9
        Status:Extension
        Packit 90a5c9
        Module:mod_session_dbd
        Packit 90a5c9
        Packit 90a5c9
            

        The SessionDBDUpdateLabel directive sets the default update

        Packit 90a5c9
            query label to be used to load in a session. This label must have been previously defined using the
        Packit 90a5c9
            DBDPrepareSQL directive.

        Packit 90a5c9
        Packit 90a5c9
            

        If an attempt to update the session affects no rows, the insert query will be

        Packit 90a5c9
            called to insert the session into the database. If the database supports InsertOrUpdate,
        Packit 90a5c9
            override this query to perform the update in one query instead of two.

        Packit 90a5c9
        Packit 90a5c9
        Packit 90a5c9
        Packit 90a5c9
        Packit 90a5c9
        Packit 90a5c9

        Available Languages:  en  |

        Packit 90a5c9
         fr 

        Packit 90a5c9
        top

        Comments

        Notice:
        This is not a Q&A section. Comments placed here should be pointed towards suggestions on improving the documentation or server, and may be removed again by our moderators if they are either implemented or considered invalid/off-topic. Questions on how to manage the Apache HTTP Server should be directed at either our IRC channel, #httpd, on Freenode, or sent to our mailing lists.
        Packit 90a5c9
        <script type="text/javascript">
        Packit 90a5c9
        var comments_shortname = 'httpd';
        Packit 90a5c9
        var comments_identifier = 'http://httpd.apache.org/docs/2.4/mod/mod_session_dbd.html';
        Packit 90a5c9
        (function(w, d) {
        Packit 90a5c9
            if (w.location.hostname.toLowerCase() == "httpd.apache.org") {
        Packit 90a5c9
                d.write('
        <\/div>');
        Packit 90a5c9
                var s = d.createElement('script');
        Packit 90a5c9
                s.type = 'text/javascript';
        Packit 90a5c9
                s.async = true;
        Packit 90a5c9
                s.src = 'https://comments.apache.org/show_comments.lua?site=' + comments_shortname + '&page=' + comments_identifier;
        Packit 90a5c9
                (d.getElementsByTagName('head')[0] || d.getElementsByTagName('body')[0]).appendChild(s);
        Packit 90a5c9
            }
        Packit 90a5c9
            else { 
        Packit 90a5c9
                d.write('
        Comments are disabled for this page at the moment.<\/div>');
        Packit 90a5c9
            }
        Packit 90a5c9
        })(window, document);
        Packit 90a5c9
        //--></script>
        Packit 90a5c9

        Copyright 2018 The Apache Software Foundation.
        Licensed under the Apache License, Version 2.0.

        Packit 90a5c9

        Modules | Directives | FAQ | Glossary | Sitemap

        <script type="text/javascript">
        Packit 90a5c9
        if (typeof(prettyPrint) !== 'undefined') {
        Packit 90a5c9
            prettyPrint();
        Packit 90a5c9
        }
        Packit 90a5c9
        //--></script>
        Packit 90a5c9
        </body></html>