Migrating registrations to OpenSIPS 2.2

Starting with OpenSIPS 2.2 the registered SIP contacts (stored the location table) have a new unique ID named contact ID. This new ID is contact specific (computed based on various contact elements) and it replaces the old opaque ID which was a simple DB auto-increment key. But why ?

• to increase the efficiency of the DB operations, by using a single value key (the contact ID) instead of multi-values key (Call-ID, Contact URI, AOR, and more);
• to create a more powerful API for the usrloc (registration) module and allow other on-top modules to easily operate and reference the contacts (like the nathelper module when performing auto de-registration based on SIP pinging.

The problem

This change of IDs in the location table introduced a series of problems.

The first one is compatibility with older versions of  OpenSIPS. While before this change the id could have arbitrary values, now this value needs to comply with a specific format. Therefore older versions are no longer compatible, making the migration of existing SIP contacts/registrations to 2.2 almost impossible. The way OpenSIPS works now is to check, at every start, if the contact IDs existing in the database have been built correctly. Each contact that does not pass this test will not be loaded. This means that tables generated with older versions cannot be used by default with this version. This might not a problem for registrar servers that have users registering at short periods of time, but it might become a major problem for production systems that cannot afford losing their customers SIP registrations, not even for minutes.

The same issue might occur when changing the size of the hash that stores the contacts in user location module. The contact ID is computed based on this size, therefore changing it could result in missing contacts. Again this might be a major problem for a production server that cannot afford losing their contacts cache.

The solution

The typical message that appears when you have these issues is to get the following errors in your system logs during OpenSIPS startup:

ERROR:usrloc:preload_udomain: failed to match aorhashes for user callee,
db aorhash [1706] new aorhash [170],db contactid [120051833657672447]

All contacts for which we see such error will not be loaded into memory. If you find at least one error as the one shown above this means that you did not manage to load those contacts in memory. After all contacts are loaded you will see an indication about possible causes and what you can do to prevent them, such as:

NOTICE:usrloc:preload_udomain: At least 1 contact(s) 
from the database has invalid contact_id!
Possible causes for this can be:
 * you are migrating your location table from a version older than 2.2
 * you have changed 'hash_size' module parameter from when current
contact_id's were generated;
If you want to regenerate new contact_id's for the broken entries
enable 'regen_broken_contactid' module parameter.

If you follow the recommendations above and set the regen_broken_contactid parameter, you will instruct OpenSIPS to forcefully load and fix/convert the contacts with broken/invalid contact ID.

Note that by default, regen_broken_contactid is disabled(set to 0). Migrating your database or changing the size of the hash is not something you are doing on a daily basis, therefore there is no need to keep this option active. Seeing what went wrong at start time helps you identify the contacts that are broken. By having OpenSIPS  automatically recomputing the contact ID (regen_broken_contactid enabled) may result in losing information about the original contact without any clue about what the problem was or how it could have been solved. What is more, there may be cases when your contacts could have been modified if regen_broken_contactid was active, but you had no intention in doing that.

In conclusion, OpenSIPS 2.2 user location module comes with a new concept designed to shorten database operations and uniquely identify a contact named contact ID. If you migrate OpenSIPS contacts from an older version or you change the size of the hash, you will probably need instruct OpenSIPS  to regenerate the contact IDs. In order to achieve this one can enable regen_broken_contactid module parameter which will regenerate all the broken contact IDs. By default the parameter is not set to avoid unwanted modifications in location table.