//
// ========================================================================
// Copyright (c) 1995-2020 Mort Bay Consulting Pty Ltd and others.
//
// This program and the accompanying materials are made available under
// the terms of the Eclipse Public License 2.0 which is available at
// https://www.eclipse.org/legal/epl-2.0
//
// This Source Code may also be made available under the following
// Secondary Licenses when the conditions for such availability set
// forth in the Eclipse Public License, v. 2.0 are satisfied:
// the Apache License v2.0 which is available at
// https://www.apache.org/licenses/LICENSE-2.0
//
// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
// ========================================================================
//

[[session-configuration-housekeeper]]
=== The SessionIdManager and the Housekeeper

==== Default Settings
By default, Jetty will instantiate a single instance of the `DefaultSessionIdManager` and `HouseKeeper` at startup with default settings.

The default settings are:

DefaultSessionIdManager: worker name::
This uniquely identifies the jetty server instance within a cluster.
It is set from the value of the `JETTY_WORKER_INSTANCE` environment variable, or `node0` if the environment value is not set.
If you have more than one Jetty instance, it is *crucial* that you explicitly configure the worker name on each Jetty instance (see link:#session-idmanager-housekeeper-config[below] for how to configure).

HouseKeeper: scavenge interval::
This is the period in seconds between runs of the session scavenger, and by default is set to the equivalent of 10 minutes.
As a rule of thumb, you should ensure that the scavenge interval is shorter than the `maxInactiveInterval` of your sessions to ensure that they are promptly scavenged.
See below for instructions on how to configure this.

[[session-idmanager-housekeeper-config]]
==== Configuration
To change the default values, use the link:#startup-modules[module system] to link:#startup-modules[enable] the `sessions` module.

This will enable the `$jetty.home/etc/sessions/id-manager.xml` file and generate a `$jetty.base/start.d/sessions.ini` file.

The `id-manager.xml` file instantiates a single `DefaultSessionIdManager` and `HouseKeeper` and configures them using the properties from the `sessions.ini` file.

Edit the ini file to change the properties to easily customize the `DefaultSessionIdManager` and `HouseKeeper`:

jetty.sessionIdManager.workerName::
By default it is `node1`.
This uniquely identifies the Jetty server instance within a cluster.
If you have more than one Jetty instance, it is crucial that you configure the worker name differently on each jetty instance.


jetty.sessionScavengeInterval.seconds::
This is the period in seconds between runs of the session scavenger.
By default it will run every 600 secs (ie 10 mins).
As a rule of thumb, you should  ensure that the scavenge interval is shorter than the  maxInactiveInterval of your sessions to ensure that they are promptly scavenged.
