Added in Asterisk 12, Asterisk has a data abstraction and object persistence CRUD API called Sorcery. Sorcery provides Asterisk modules with a useful abstraction on top of the many storage mechanisms in Asterisk. Such as the:
- Asterisk Database
- Static Configuration Files
- Asterisk Realtime Architecture
Sorcery also provides a caching service as well as the capability for push configuration through the Asterisk REST Interface. See the section ARI Push Configuration for more information on that topic.
Modules Supporting Sorcery
The PJSIP modules and resources were the first to use the Sorcery DAL. All future modules which utilize Sorcery for object persistence must have a column named id within their schema when using the Sorcery realtime module. This column must be able to contain a string of up to 128 characters in length.
Sorcery API Actions
AMI actions existing at the time of Asterisk 14.2.1
Sorcery functions existing at the time of Asterisk 14.2.1
Sorcery Mapping Configuration
Users can configure a hierarchy of data storage layers for specific modules in sorcery.conf.
You can view the sorcery.conf sample in your configs/samples/ Asterisk source subdirectory. Or you can check it out on github: https://github.com/asterisk/asterisk/blob/master/configs/samples/sorcery.conf.sample
We've included roughly the same instructions below while taking advantage of wiki formatting.
Constructing a Mapping
To allow configuration of where and how an object is persisted, object mappings can be defined within sorcery.conf on a per-module basis. The mapping consists of the object type, options, wizard name, and wizard configuration data.
The basic format follows:
[module_name] ;The brackets around the module name are literal, just as in most other Asterisk configuration files. object_type[/options] = wizard_name[,wizard_configuration_data] ;Bracketed items here are optional
Object/Wizard mappings are defined within sections denoted by the module name in brackets. The section name must match the module.
Note that an object type can have multiple mappings defined. Each mapping will be consulted in the order in which it appears within the configuration file. This means that if you are configuring a wizard as a cache it should appear as the first mapping so the cache is consulted before all other mappings.
Object types available depend on the modules loaded and what objects they provide. There are PJSIP types for all the configuration objects in PJSIP, such as endpoint, auth,aor, etc. You can find a more exhaustive list of PJSIP objects in the Sorcery Caching page.
Wizards are the persistence mechanism for objects. They are loaded as Asterisk modules and register themselves with the sorcery core. All implementation specific details of how objects are persisted is isolated within wizards.
A wizard can optionally be marked as an object cache by adding "/cache" to the object type within the mapping. If an object is returned from a non-object cache it is immediately given to the cache to be created. Multiple object caches can be configured for a single object type.
Wizards available at the time of writing:
- memory_cache (For further details on this wizard type see the documentation here)
Example Mapping Configurations
The following object mappings are used by the unit test to test certain functionality of sorcery.
[test_sorcery_section] test=memory [test_sorcery_cache] test/cache=test test=memory
The following object mapping is the default mapping of external MWI mailbox objects to give persistence to the message counts.
The following object mappings set PJSIP objects to use realtime database mappings from extconfig with the table names used when automatically generating configuration from the alembic script.
[res_pjsip] endpoint=realtime,ps_endpoints auth=realtime,ps_auths aor=realtime,ps_aors domain_alias=realtime,ps_domain_aliases contact=realtime,ps_contacts [res_pjsip_endpoint_identifier_ip] identify=realtime,ps_endpoint_id_ips
PJSIP Default Wizard Configurations
When configuring PJSIP sorcery mappings it can be useful to allow both the configuration file and other wizards to be used. The below configuration matches the default configuration for the PJSIP sorcery usage.
[res_pjsip] auth=config,pjsip.conf,criteria=type=auth domain_alias=config,pjsip.conf,criteria=type=domain_alias global=config,pjsip.conf,criteria=type=global system=config,pjsip.conf,criteria=type=system transport=config,pjsip.conf,criteria=type=transport aor=config,pjsip.conf,criteria=type=aor endpoint=config,pjsip.conf,criteria=type=endpoint contact=astdb,registrator [res_pjsip_endpoint_identifier_ip] identify=config,pjsip.conf,criteria=type=identify [res_pjsip_outbound_publish] outbound-publish=config,pjsip.conf,criteria=type=outbound-publish [res_pjsip_outbound_registration] registration=config,pjsip.conf,criteria=type=registration