Browseable session backend ========================== Presentation ------------ Browseable session backend (`Apache::Session::Browseable `) works exactly like Apache::Session::\* corresponding module but add index that increase :doc:`session explorer` and :doc:`session restrictions` performances. If you use features like SAML (authentication and issuer), CAS (issuer) and password reset self-service, you also need to index some fields. .. important:: Without index, LL::NG will have to retrieve all sessions stored in backend and parse them to find the needed sessions. With index, LL::NG wil be able to get only wanted sessions from the backend. The following table list fields to index depending on the feature you want to increase performance: ====================================== =================================================================== Feature Fields to index ====================================== =================================================================== Database cleanup *(cron)* \_session_kind \_utime Session explorer \_session_kind ipAddr \_httpSessionType *WHATTOTRACE* Session explorer (persistent sessions) \_session_kind \_session_uid ipAddr \_httpSessionType *WHATTOTRACE* Session restrictions \_session_kind ipAddr *WHATTOTRACE* Password reset by email user SAML Session \_saml_id ====================================== =================================================================== See Apache::Session::Browseable man page to see how use indexes. .. important:: \ *WHATTOTRACE* must be replaced by the attribute or macro configured in the What To Trace parameter (REMOTE_USER). By default: **\_whatToTrace**\ .. tip:: It is advised to use separate session backends for standard sessions, SAML sessions and CAS sessions, in order to manage index separately. .. important:: Documentation below explains how set index on ipAddr and \_whatToTrace. Adapt it to configure the index you need. Browseable NoSQL ---------------- You can use Redis and set up the database like explained in :doc:`Redis session backend`. You then just have to add the ``Index`` parameter in ``General parameters`` » ``Sessions`` » ``Session storage`` » ``Apache::Session module`` : =================== ============ ==================== Required parameters =================== ============ ==================== Name Comment Example **server** Redis server 127.0.0.1:6379 **Index** Index \_whatToTrace ipAddr =================== ============ ==================== Browseable SQL -------------- .. important:: This documentation concerns PostgreSQL. Some adaptations are needed with other databases. When using Apache::Session::Browseable::Postgres, it is strongly recommended to use version 1.3.1 at least. See `bug 1732 `. Prepare database ~~~~~~~~~~~~~~~~ Database must be prepared exactly like in :doc:`SQL session backend` except that a field must be added for each data to index. .. important:: Data written to UNLOGGED tables is not written to the WAL, which makes them considerably faster than ordinary tables. However, they are not crash-safe: an unlogged table is automatically truncated after a crash or unclean shutdown. The contents of an unlogged table are also not replicated to standby servers. Any indexes created on an unlogged table are automatically unlogged as well. Apache::Session::Browseable::Postgres example: :: CREATE UNLOGGED TABLE sessions ( id varchar(64) not null primary key, a_session text, _whatToTrace text, _session_kind text, _utime bigint, _httpSessionType text, ipAddr text ); CREATE INDEX uid1 ON sessions USING BTREE (_whatToTrace text_pattern_ops); CREATE INDEX s1 ON sessions (_session_kind); CREATE INDEX u1 ON sessions (_utime); CREATE INDEX ip1 ON sessions USING BTREE (ipAddr); CREATE INDEX h1 ON sessions (_httpSessionType); .. important:: For Session Explorer and one-off sessions, it is recommended to use BTREE or any index method that indexes partial content. "id" fieds is set to ``varchar(64)`` (instead of char(32)) to use the now recommended SHA256 hash algorithm. See :doc:`Sessions` for more details. .. tip:: With new Apache::Session::Browseable::PgHstore and **PgJSON**, you don't need to declare indexes in ``CREATE TABLE`` since "json" and "hstore" type are browseable. You should anyway add some indexes *(see manpage)*. Manager ~~~~~~~ Go in the Manager and set the session module (`Apache::Session::Browseable::MySQL `__ for MySQL) in ``General parameters`` » ``Sessions`` » ``Session storage`` » ``Apache::Session module`` and add the following parameters (case sensitive): =================== ================================================= ============================================================= Required parameters =================== ================================================= ============================================================= Name Comment Example **DataSource** The `DBI `__ string dbi:Pg:database=lemonldap-ng **UserName** The database username lemonldapng **Password** The database password mysuperpassword **Index** Index \_whatToTrace ipAddr \_session_kind \_utime \_httpSessionType **TableName** Table name (optional) sessions =================== ================================================= ============================================================= .. tip:: Apache::Session::Browseable::MySQL doesn't use locks so performances are keeped. For databases like PostgreSQL, don't forget to add "Commit" with a value of 1 Browseable LDAP --------------- Go in the Manager and set the session module to ``Apache::Session::Browseable::LDAP``. Then configure the options like in :doc:`LDAP session backend`. You need to add the ``Index`` field and can also configure the ``ldapAttributeIndex`` field to set the attribute name where index values will be stored. ======================== ================================= =============================== Required parameters ======================== ================================= =============================== Name Comment Example **ldapServer** URI of the server ldap://localhost **ldapConfBase** DN of sessions branch ou=sessions,dc=example,dc=com **ldapBindDN** Connection login cn=admin,dc=example,dc=password **ldapBindPassword** Connection password secret **Index** Index list \_whatToTrace ipAddr Optional parameters Name Comment Default value **ldapObjectClass** Objectclass of the entry applicationProcess **ldapAttributeId** Attribute storing session ID cn **ldapAttributeContent** Attribute storing session content description **ldapAttributeIndex** Attribute storing index ou ======================== ================================= =============================== Security -------- Restrict network access to the backend. You can also use different user/password for your servers by overriding parameters ``globalStorage`` and ``globalStorageOptions`` in lemonldap-ng.ini file. Performances ------------ Here are some recommended configurations: **Browseable::Postgres**: :: CREATE UNLOGGED TABLE sessions ( id varchar(64) not null primary key, a_session text, _whatToTrace text, _session_kind text, _utime bigint, _httpSessionType text, ipAddr text ); CREATE INDEX uid1 ON sessions USING BTREE (_whatToTrace text_pattern_ops); CREATE INDEX s1 ON sessions (_session_kind); CREATE INDEX u1 ON sessions (_utime); CREATE INDEX ip1 ON sessions USING BTREE (ipAddr); CREATE INDEX h1 ON sessions (_httpSessionType); **Browseable::MySQL**: :: CREATE TABLE sessions ( id varchar(64) not null primary key, a_session text, _whatToTrace varchar(64), _session_kind varchar(15), user text, _utime bigint ); CREATE INDEX uid1 ON sessions (_whatToTrace) USING BTREE; CREATE INDEX _s1 ON sessions (_session_kind); CREATE INDEX _u1 ON sessions (_utime); CREATE INDEX ip1 ON sessions (ipAddr) USING BTREE;