mirror of https://github.com/sipwise/kamailio.git
You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
256 lines
7.3 KiB
256 lines
7.3 KiB
Memcached Module
|
|
|
|
Henning Westerholt
|
|
|
|
Copyright © 2009 Henning Westerholt
|
|
__________________________________________________________________
|
|
|
|
Table of Contents
|
|
|
|
1. Admin Guide
|
|
|
|
1. Overview
|
|
2. Implementation notes
|
|
|
|
2.1. Error behaviour
|
|
2.2. Data safety
|
|
2.3. Size restrictions
|
|
|
|
3. Dependencies
|
|
|
|
3.1. Kamailio Modules
|
|
3.2. External Libraries or Applications
|
|
|
|
4. Parameters
|
|
|
|
4.1. servers (str)
|
|
4.2. expire (integer)
|
|
4.3. mode (integer)
|
|
4.4. timeout (integer)
|
|
|
|
5.
|
|
|
|
5.1. Exported pseudo-variables
|
|
|
|
List of Examples
|
|
|
|
1.1. Storing and retrieving entries
|
|
1.2. Using atomic operations
|
|
1.3. Modifying expire time for existing entries
|
|
1.4. Set servers parameter
|
|
1.5. Set expire parameter
|
|
1.6. Set mode parameter
|
|
1.7. Set timeout parameter
|
|
|
|
Chapter 1. Admin Guide
|
|
|
|
Table of Contents
|
|
|
|
1. Overview
|
|
2. Implementation notes
|
|
|
|
2.1. Error behaviour
|
|
2.2. Data safety
|
|
2.3. Size restrictions
|
|
|
|
3. Dependencies
|
|
|
|
3.1. Kamailio Modules
|
|
3.2. External Libraries or Applications
|
|
|
|
4. Parameters
|
|
|
|
4.1. servers (str)
|
|
4.2. expire (integer)
|
|
4.3. mode (integer)
|
|
4.4. timeout (integer)
|
|
|
|
5.
|
|
|
|
5.1. Exported pseudo-variables
|
|
|
|
1. Overview
|
|
|
|
The module provides access to the distributed hash table memcached.
|
|
This hash table is stored in memory and can can be accessed via a
|
|
pseudo-variable: $mct(key). Entries are stored and retrieved from an
|
|
external server application.
|
|
|
|
The “key” can be a static string and also any existing pseudo-variable.
|
|
Further interfaces to the functionality provided from memcached are
|
|
also provided, like access to the atomic increment and decrement
|
|
operations.
|
|
|
|
Example 1.1. Storing and retrieving entries
|
|
...
|
|
$mct(test) = 1;
|
|
xlog("stored value is $mct(test)");
|
|
$mct(test) = $null; # delete it
|
|
xlog("stored value is $mct(test)"); # will return <null> or empty string
|
|
...
|
|
|
|
Example 1.2. Using atomic operations
|
|
...
|
|
$mct(cnt) = 1;
|
|
$mcinc(cnt) = 1; # increment by 1
|
|
xlog("counter is now $mct(cnt)");
|
|
$mcdec(cnt) = 1; # decrement by 1
|
|
xlog("counter is now $mct(cnt)");
|
|
...
|
|
|
|
Example 1.3. Modifying expire time for existing entries
|
|
...
|
|
$mct(test) = 1;
|
|
xlog("stored value is $mct(test)");
|
|
$mctex(test) = 10; # set expire time to 10 seconds
|
|
# sleep 10 seconds
|
|
xlog("stored value is $mct(test)"); # will return <null>
|
|
...
|
|
|
|
This module is an addition to the existing htable functionality, not a
|
|
replacement. In smaller architectures or installations where only one
|
|
instance needs access to the hash table the htable module is easier to
|
|
setup, as no dedicated server needs to be provided. But when a
|
|
distributed storage facilility is necessary, or one want to separate
|
|
the storage from the SIP server, this module could be used.
|
|
|
|
2. Implementation notes
|
|
|
|
2.1. Error behaviour
|
|
2.2. Data safety
|
|
2.3. Size restrictions
|
|
|
|
Important notes about made assumptions and adaptions that were
|
|
necessary for the proper integration of this library into Kamailio.
|
|
|
|
2.1. Error behaviour
|
|
|
|
The used memcache library has a rather conservative approach to error
|
|
handling. In the default configuration each error with severity above
|
|
“WARN” will lead to a immediately exit (or even an abort) of the
|
|
execution, causing also a shutdown of Kamailio. This is of course not
|
|
optimal from a availability point of view. Therefore in the internal
|
|
error handler this is overriden. This means that we err a bit on the
|
|
side of data integrity in order to get a sufficient availability. But
|
|
even with this changes some problems in the memcache server can lead to
|
|
problems in the library and subsequently also in the server.
|
|
|
|
2.2. Data safety
|
|
|
|
Don't store data in memcached that you don't also have somewhere else.
|
|
This system was designed as fast cache, and not for persistent storage.
|
|
The memcached server can crash, machines can reboot or are restarted.
|
|
If the memcache storage pool gets fulls, it starts to drop the least
|
|
used items, even if they are not yet expired. So don't store any data
|
|
in it where it would be a problem when it disappear from one moment to
|
|
the other.
|
|
|
|
2.3. Size restrictions
|
|
|
|
The maximum key length that is supported from memcached is 250
|
|
characters. In order to support longer keys in the Kamailio
|
|
configuration script they are hashed with MD5. This should normally be
|
|
safe against collisions, as the value space is sufficient large enough.
|
|
|
|
The maximum value size that is supported is 1MB. The reason for this is
|
|
the internal memory manager used from memcached. But normally this
|
|
restriction should be not a problem in the SIP environment where this
|
|
module is used.
|
|
|
|
3. Dependencies
|
|
|
|
3.1. Kamailio Modules
|
|
3.2. External Libraries or Applications
|
|
|
|
3.1. Kamailio Modules
|
|
|
|
The following modules must be loaded before this module:
|
|
* No dependencies on other Kamailio modules.
|
|
|
|
3.2. External Libraries or Applications
|
|
|
|
The following libraries or applications must be installed before
|
|
running Kamailio with this module loaded:
|
|
* the libmemcache library.
|
|
* the memcached server implementation.
|
|
|
|
4. Parameters
|
|
|
|
4.1. servers (str)
|
|
4.2. expire (integer)
|
|
4.3. mode (integer)
|
|
4.4. timeout (integer)
|
|
|
|
4.1. servers (str)
|
|
|
|
The servers to connect to. At the moment only one server is supported.
|
|
|
|
Default value is “localhost:11211”.
|
|
|
|
Example 1.4. Set servers parameter
|
|
...
|
|
modparam("memcached", "servers", "localhost:11211")
|
|
...
|
|
|
|
4.2. expire (integer)
|
|
|
|
The default expire value of all entries in memcached in seconds. The
|
|
maximal value is 2592000 (about 30 days). You can also specify an
|
|
arbitrary unix time stamp in the future. A value of zero means that no
|
|
automatic expiration is done, memcached will then delete the least used
|
|
items when the cache gets full.
|
|
|
|
Please note that memcached implements lazy caching, that means items
|
|
are only deleted when they requested (they are of course not delivered
|
|
to the client), or on insertion of new entries when the cache is full.
|
|
Items can also be deleted before there expire time when the available
|
|
space in memory is exhausted.
|
|
|
|
Its possible to override this default value later on by setting a
|
|
different timeout for this key with the mctex pseudo-variable.
|
|
|
|
Default value is “10800”s (3h).
|
|
|
|
Example 1.5. Set expire parameter
|
|
...
|
|
modparam("memcached", "expire", 10800)
|
|
...
|
|
|
|
4.3. mode (integer)
|
|
|
|
The used storage mode for the memcached module for write access to the
|
|
hash table. A value of “0” means to set (overwrite) the old value, with
|
|
a value of “1” the module will not overwrite it. Here every entry to
|
|
the hash table could be written only once, subsequent inserts will
|
|
fail.
|
|
|
|
Default value is “0” (overwrite).
|
|
|
|
Example 1.6. Set mode parameter
|
|
...
|
|
modparam("memcached", "mode", 0)
|
|
...
|
|
|
|
4.4. timeout (integer)
|
|
|
|
The timeout for the memcache servers access in milliseconds.
|
|
|
|
Default value is “5000” (5s).
|
|
|
|
Example 1.7. Set timeout parameter
|
|
...
|
|
modparam("memcached", "timeout", 10000)
|
|
...
|
|
|
|
5.1. Exported pseudo-variables
|
|
|
|
5.1. Exported pseudo-variables
|
|
|
|
* $mct(key)
|
|
* $mcinc(key)
|
|
* $mcdec(key)
|
|
* $mctex(key)
|
|
|
|
Exported pseudo-variables are documented at
|
|
http://www.kamailio.org/dokuwiki/.
|