The Asterisk project has a very strict policy in regards to backwards compatibility. Unless we can’t find another solution, we’re not allowed to remove a function between releases. A configuration for Asterisk 2.4 should work in the next release. In order to be able to change functionality we warn users in one release and then remove the functionality in the coming release. So a configuration in 3.0 works in 3.2 but maybe not in 3.4.

This article tries to provide help with known problems with upgrading. Read on to learn how to avoid the traps!

Watch out for DEPRECATED functions, applications, global and channel variables!

We document all the changes in the file UPGRADE.TXT. In addition, we add messages to the log files and the online documentation (“core show application” etc) that something is deprecated. If you get these messages in your log files, you should take action and reconfigure.

The first time this happened in the Asterisk community was with the release of Asterisk 1.4. Old configurations, created for Asterisk 1.0 worked in Asterisk 1.2. The Asterisk server sent a lot of warnings and there was an UPGRADE.TXT file with clear indications of what should be changed.

And at the release of 1.4, a lot of upgraded PBX’s stopped working. Applications and channel variables in the dialplan was gone, configuration options in the configuration files stopped working. Don’t put yourself in this situation when upgrading to 1.4.


  • Read the 1.2 UPGRADE.TXT file and update your 1.2 configuration to run smoothly in 1.2. In this file, you will find suggestions on how to change your dialplan to work with the new dialplan functions that replace a lot of applications and global channel variables.
  • Test your configuration in Asterisk 1.4. Since the diaplan (extensions.conf) is not checked at the time you start your Asterisk server, you need to place calls in order to check that it works properly. Applications that are gone will cause the call to fail at the stage you try to execute the application.
  • Read the 1.4 UPGRADE.TXT file and make sure you are future-proof in time for the next upgrade. You don’t want to run Asterisk 1.4 with a 1.2-style configuration when it’s time for the next release to be installed on your system.
  • If you are upgrading from a 1.0 system, you need to first make sure that you update according to the 1.2 UPGRADE.TXT, then according to the 1.4 UPGRADE.TXT.

Deleted applications

  • Cut
  • Sort
  • DBGet, DBPut
  • SetCIDNum, SetCIDNamem SetRDNIS
  • AbsoluteTimeout, DigitTimeout, ResponseTimeout
  • SetLanguage,
  • GetGroupCount, GetGroupMatchCount

Global and channel variables

Deleted variables (globals and channel variables)

  • ${DNID}
  • ${RDNIS}
  • ${PRI_CAUSE} is now replaced by a variable to the hangup() application.

SETVAR() is now replaced with the SET() application.

SIP configuration

  • The “port” setting is now named “bindport”
  • The “incominglimit“setting is now named “call-limit” since it covers both incoming and outgoing calls.
  • Canreinvite=yes now does not disable re-invites if you have nat=yes. You will need to change all canreinvite=yes to canrevinvite=nonat to get the old behaviour (which is usually what you want).
  • Videosupport now needs to be enabled in the [general] section of sip.conf, and then enabled/disabled per device.

IP Type of Service (QoS) in VoIP channels

The settings for IP ToS has changed in all VoIP channels to reflect the new standards and recommendations. In SIP, you can now have different ToS for media and signalling. There is a good document that describes these changes in the documentation.

IVRs that rely on “background()”

If you have IVR scripts that work with background, you have to add a waitexten() call after background. Since the default setting of the “autofallthrough” variable in extensions.conf changed to yes, background() will no longer wait for an extension to be entered after playing the audio file.

Jumping to priority + 101

Jumping to priority+101 is no longer supported. All applications return a STATUS variable in the dialplan to indicate the result of the application. Check the application help texts if you have any logic in your dialplan that is based on an application changing the priority. Dial() and EnumLookup() are two of the changed applications. If you really need this functionality, you can still enable it, but it will be removed soon. In most cases, using the STATUS variable will give you better functionality in the dialplan.


The music on hold subsystem has gone through some dramatic changes and you will want to look over the documentation and your configuration. This is one of the few exceptions to the rule about backwards compatibility. There was no way we could make it work properly and resolve bugs in the bug tracker while maintaining compatibility with old versions of Asterisk. Check the “musicclass” setting in your channel driver configurations.

The Queue and Agent system

The queue and agent system has gone through a massive amount of changes, so you do not want to use an old configuration. Read the supplied documentation and discover the new dialplan functions to set up a better working queue system. There’s documentation in UPGRADE.TXT, the tutorial on callback agents, the sample queues.conf and agents.conf.

I’ve tried to cover as much as possible of the changes that you need to do to keep your system working. This document does not cover all the new features, there are other articles in this series that try to convince you about the new and useful features of the new release.