documentation:2.1:browseablesessionbackend

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

documentation:2.1:browseablesessionbackend [2019/11/07 14:36] (current)
Line 1: Line 1:
 +====== Browseable session backend ======
  
 +===== Presentation =====
 +
 +Browseable session backend ([[https://metacpan.org/pod/Apache::Session::Browseable|Apache::Session::Browseable]]) works exactly like Apache::Session::* corresponding module but add index that increase [[documentation:features#session_explorer|session explorer]] and [[documentation:features#session_restrictions|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.
 +
 +<note>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.</note>
 +
 +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.
 +
 +<note important>//WHATTOTRACE// must be replaced by the attribute or macro configured in the What To Trace parameter (REMOTE_USER). By default: **_whatToTrace**</note>
 +
 +<note tip>It is advised to use separate session backends for standard sessions, SAML sessions and CAS sessions, in order to manage index separately.</note>
 +
 +<note>Documentation below explains how set index on ipAddr and _whatToTrace. Adapt it to configure the index you need.</note>
 +
 +===== Browseable NoSQL =====
 +
 +You can use Redis and set up the database like explained in [[nosqlsessionbackend|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 =====
 +
 +<note>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 [[https://gitlab.ow2.org/lemonldap-ng/lemonldap-ng/issues/1732|bug 1732]].</note>
 +
 +==== Prepare database ====
 +
 +Database must be prepared exactly like in [[sqlsessionbackend#prepare_the_database|SQL session backend]] except that a field must be added for each data to index.
 +
 +<note 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.
 +</note>
 +
 + 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);
 +
 +<note important>For Session Explorer and one-off sessions, it is recommended to use BTREE or any index method that indexes partial content.</note>
 +
 +"id" fieds is set to ''varchar(64)'' (instead of char(32)) to use the now recommended SHA256 hash algorithm. See [[documentation:latest:sessions|Sessions]] for more details.
 +
 +<note 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)//.</note>
 +
 +==== Manager ====
 +
 +Go in the Manager and set the session module ([[https://metacpan.org/pod/Apache::Session::Browseable::MySQL|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 [[https://metacpan.org/pod/DBI|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 |
 +
 +<note 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</note>
 +
 +===== Browseable LDAP =====
 +
 +Go in the Manager and set the session module to ''Apache::Session::Browseable::LDAP''. Then configure the options like in [[ldapsessionbackend|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;