Asterisk sip canreinvite

Asterisk sip.conf, peer definition: canreinvite option


Migration from Asterisk 1.2 to 1.4: The "canreinvite" option has changed. canreinvite=yes used to disable re-invites if you had NAT=yes. In 1.4, you need to set canreinvite=nonat to disable re-invites when NAT=yes. This is propably what you want. The settings are now: "yes", "no", "nonat", "update". Please consult sip.conf.sample for detailed information.

canreinvite= was renamed to directmedia= in Asterisk 1.6.2 to more accurately describe what this setting does. See also the closely related setting directrtpsetup.

Asterisk 1.8 added directmediapermit and directmediadeny to limit which peers can send direct media to each other.


This peer option in sip.conf is used to tell the Asterisk server to not issue a reinvite to the client unless really necessary. This is used to interoperate with some (buggy) hardware that crashes if we reinvite, such as the common Cisco ATA 186.

When SIP initiates the call, the INVITE message contains the information on where to send the media streams. Asterisk uses itself as the end-points of media streams when setting up the call. Once the call has been accepted, Asterisk sends another (re)INVITE message to the clients with the information necessary to have the two clients send the media streams directly to each other.

  • If one of the clients is configured with canreinvite=NO, Asterisk will not issue a re-invite at all.
  • If the clients use different codecs, Asterisk will not issue a re-invite.
  • If the Dial() command contains ''t'', ''T", "h", "H", "w", "W" or "L" (with multiple arguments) Asterisk will not issue a re-invite.

'canreinvite=no' stops the sending of the (re)INVITEs once the call is established. From messages in the archives and the Asterisk handbook one finds out that the Cisco ATA-186 does not handle the (re)INVITE well. This is necessary if the client and the Asterisk server is on opposite sides of a NAT gateway or firewall.

  • canreinvite = yes "allow RTP media direct"
  • canreinvite = no "deny re-invites"
  • canreinvite = nonat "allow reinvite when local, deny reinvite when NAT"
  • canreinvite = update "use UPDATE instead of INVITE"
  • canreinvite = update,nonat "use UPDATE when local, deny when NAT"

Note: In spite of its name 'canreinvite' being set to 'no' does *NOT* disable all reINVITE operations. It *only* controls Asterisk generating reINVITEs for the specific purpose of setting up a direct media path. If a reINVITE is needed to switch a media stream to inactive (when placed on hold) or to T.38, it will still be done, regardless of this setting!


  • reinvite=yes/no is plain wrong, even if you see it mentioned in example .conf files. The correct syntax is canreinvite=yes/no
  • Connecting media paths direct to an endpoint behind NAT won't be pretty. Especially if both devices are behind NAT. You might want to try using SER's nathelper in conjunction since can rewrite the SDP so that the private IP addresses are not included in the re-invite.
  • When dtmfmode=rfc2833, asterisk will send the RTP stream through asterisk. With dtmfmode=info canreinvite works properly.
  • Asterisk 1.8 added the media_address= configuration option which can be used to explicitly specify the IP address to use in the SDP for media (audio, video, and text) streams.

Background info

In general Asterisk supports 3 methods of media handling:

1. bridging: media (audio, video) is received on one channel, handed over to Asterisk's core, forwarded to the bridged channel, and sent out again.

2. native-bridging (see also below): if both bridged channels use the same technology then (WRONG! This is confused with P2P, see below) media can be bridged directly in the channel driver, no need to feed the media into Asterisk's core. For example SIP-to-SIP calls or DAHDI-to-DAHDI calls.

3. bypass: here, the media flow bypasses Asterisk directly. AFAIK this works only with SIP as channel technology. This comes in 2 flavors:

3a) During call setup the media will be forwarded via Asterisk. Once the call is set-up, Asterisk will send reINVITEs to both clients using the clients original SDP contact information. For this you must set canreinvite=yes (1.4) or directmedia=yes (1.6) in sip.conf. Of course Asterisk will initiate the direct media only if the media is not needed in Asterisk, e.g. if you monitor a call, the media will always be routed via Asterisk.

3b) Media will bypass Asterisk from the beginning. Therefore you have to set directrtpsetup=yes. This is still experimental and causes weird reINVITEs (e.g. after call setup to lock down on a certain codec or after call termination to redirect media to Asterisk before hanging up).

Both bypass modes Note only work if either there are no NATs at all, or the clients are behind the same NAT and do not use STUN.

Packet2Packet Bridging (aka P2P) = Audio is not going through the Asterisk core, it comes into the RTP stack and goes directly out. This decreases the amount of memory allocation that happens, and things require less processing.

With native bridging, the audio flows outside of Asterisk between the endpoints. With P2P bridging, the audio comes into the RTP layer of Asterisk but does not pass through the Asterisk core. This allows for Asterisk to intercept DTMF or play warning files to the bridged parties.

Note that also the jitter buffer and packet loss concealment (aka PLC) features of Asterisk are affected by the decision how to route the RTP media traffic.

A longer explanation on reINVITEs

[Based on a posting to asterisk-users mailing list]

> I've set canreinvite=no on the channel to the SIP provider and it
> immediately worked. O.k., I'm happy about that but I want to
> *understand* what's going on here.
> .
> My setup is:
> Asterisk is connected on one side via eth1 to the "outside world" (IP
> adress and on the other side via eth0 to the internal
> LAN (eth0 has IP, SNOM phone has, ...).

A good question, for which it's hard to give a short answer :-)

Firstly, you need to understand how SIP itself was designed to set up calls between handsets.

The SIP 'INVITE' message says "I want to set up a call". In the body of this message is a block of SDP (Session Description Protocol) which says "my audio endpoint is IP x.x.x.x port x, and I can use codecs A, B and C".

In the intended architecture of SIP, the INVITE is forwarded via a series of proxies until it reaches the requested destination. The remote end responds with a 200 saying "OK, my audio stream is on IP y.y.y.y port y, and I choose codec B", which is sent back to the first phone. At this point, the first phone starts sending RTP audio packets from x.x.x.x:x to y.y.y.y:y, and the second phone sends them from y.y.y.y:y to x.x.x.x:x. That is, the audio path is direct, whereas the SIP messages went via intervening proxies.

[This is horrendously over-simplified, but it's enough to make the point]

Now, the second thing to understand is that Asterisk is not a SIP proxy, and its default behaviour is to set up the two legs as two separate audio streams: phone X to Asterisk and Asterisk to phone Y. The way this works is:

  • Phone sends INVITE saying "I am on IP x.x.x.x:x, I can use codecs A,B,C"

  • Asterisk decides where the next leg is. If it is another SIP device, it sends a fresh SIP INVITE (with a different Call-Id) to the second phone saying "I am on IP z.z.z.z:z1, I can use codecs C and D" where z.z.z.z is Asterisk's own IP address and :z1 is a port it has chosen.

  • This arrives at the second phone, which says "OK, I am on IP y.y.y.y:y, I choose codec C", and sends it back to Asterisk

  • Asterisk is happy, so it completes the first leg by replying to the first phone "OK, I am on IP z.z.z.z:z2, I choose codec C"

So now the first phone is sending packets between x.x.x.x:x and z.z.z.z:z2, and the second phone is sending packets between y.y.y.y:y and z.z.z.z:z1

This means that Asterisk is in the media path - each RTP packet has to be received and resent, in both directions. On the minus side, this means more workload on the Asterisk server. On the plus side, being in the media stream means that Asterisk can perform a whole bunch of useful voice services - recording, conferencing, call parking, music on hold, even codec conversion (i.e. the stream from phone X to Asterisk can be using one codec, and phone Y to Asterisk a different one)

With me so far?

The third thing to realise is that Asterisk can optimise this out so that the media path is set up directly between the endpoints. This is what it means by "native bridging" - connecting two compatible endpoints directly together, instead of relaying the audio via Asterisk.

So, under the right conditions, the SIP message Asterisk sends to the second phone will contain the IP address of the first phone, and vice versa. This means it looks and smells almost like a SIP proxy.

Note: Asterisk is still really not a SIP proxy in this case. The two legs have different Call-Ids, and so are different SIP calls. However the SDP descriptors for the audio of the two calls point directly at each other.

This short-circuit way of setting up calls was introduced in 1.4; for earlier versions, I believe the call is set up initially as two legs, and then Asterisk reconnects the endpoints directly using a re-INVITE
--> try directrtpsetup=yes

What do I mean by "the right conditions"? Well I'm not sure what the complete set is, but one of those conditions is that both SIP channels must be marked "canreinvite=yes". If either has "canreinvite=no", then Asterisk falls back to the default behaviour of setting up two separate legs.

In your case, you need the default behaviour when calling the provider, because the SIP phone is on a private IP, whilst the provider is on a public IP P.P.P.P. If the SIP messages were to try to set up a direct media path between the two it wouldn't work [*]; in particular, there's no point the public SIP provider trying to send an RTP packet to, because it won't be able to route to it.

[*] To be fair, if you have a NAT firewall between your internal network and the Internet, then some packets will be able to go directly between your network and the outside world, with the firewall modifying the source IP address and/or port in the process. There are a whole bunch of nasty tricks which can be done, both on the phone and at the provider, which mean that if you are really lucky you can make VoIP work this way. However I recommend you avoid this. You are in the fortunate situation that your Asterisk box has a real public IP address, so make use of it.

The last thing, which took me a while to figure out, is why the option which means "I prefer to use a direct RTP media path" is called "canreinvite=yes".

Even if the normal audio path for a call can be set up with native bridging, Asterisk sometimes needs to be able to re-insert itself into the media path in the middle of a call - to provide services such as music on hold, transfer, parking and so on when they are requested.

The SIP mechanism for this is called re-INVITE. Two phones which are happily talking to each other can have the media stream changed mid-call using this mechanism, so Asterisk can unstitch the direct link and re-connect the two legs to itself.

However, not all phones support this mechanism. If you set canreinvite=no on a SIP channel, it's saying "this phone doesn't support the re-INVITE mechanism for reconnecting the audio mid-call". Asterisk therefore decides that it must insert itself into the media stream for the whole duration of the call, so that it is already there if later on one of the parties requests one of these in-call features.

Hopefully that's enough to answer your question :-) The best way to see what's going on is to look at the SIP/SDP packets themselves, which you can do either using 'sip debug' in Asterisk, or using tcpdump:

  1. tcpdump -i eth0 -n -s0 -v udp port 5060
  2. tcpdump -i eth1 -n -s0 -v udp port 5060

With a recent version of tcpdump, the -v option will show you the SIP/SDP payload. If it doesn't, use -X instead (capital X) which will show you hex and ASCII. -s0 means capture the whole packet, and -n means don't try to do reverse DNS lookups on every packet's IP address.

Related methods

directrtpsetup is similar to directmedia=, except the audio is redirected in the initial INVITEs rather than reinviting the media a
few RTP packets later.

CanReinvite Explain


Canreinvite=yes *only* works if all devices are on the same side of the NAT, the
outside or the inside.

If one device is on a different side of a NAT device than another phone
or Asterisk, you can't allow re-invites for that device.

Let me explain:

Phone A -------------> Asterisk -----------------> phone B

Phone A calls phone B. The first thing you have to remember is that Asterisk
is *not* a SIP proxy, it's a SIP PBX. So phone A sends an invite to Asterisk.
Asterisk starts a *new* SIP dialog and sends an invite to Phone B.
If Phone B accepts the call ("answers"), it sends an "200 OK" sip message
to Asterisk. Asterisk sends a "200 OK" SIP message to phone A. We now have
  • two* SIP calls, or dialogs, that are bridged through Asterisk.

The natural behaviour for the Asterisk SIP channel in this case is
to get a feeling of "Hey, these two phones are using me just for transport
of bits between themselves. Why not get out of the loop and let them
exchange these bits directly with each other? I can use the spare CPU
cycles for something more meaningful than shipping these bits..."

So, in order to get out of this meaningless position, Asterisk checks if
the phones are compatible. If they support the same codec, if they
can talk to each other. If *one* of them have canreinvite=no
or something else that stops a direct audio relationship from phone A to B,
Asterisk stays in the middle of things, shipping bits between the phones
(the audio stream).

If they are compatible, Asterisk sends a new SIP INVITE to both of the
phones, redirecting the media streams for the current calls to each
other. This is called a Re-INVITE, an INVITE where we change media
for an existing SIP dialog, not trying to start a new call.

This works perfectly well if all phones are compatible and we have
the network configured so that they can talk full duplex to each other.
If one is behind a NAT, they can't. If that's the case, we'll only
get one audio stream, from the phone on the inside to the one on the
outside. That's why we want to set canreinvite=no to make sure
Asterisk doesn't even try to re-INVITE.

Executive Summary:

canreinvite=no in a [peer] configuration makes Asterisk stay
in the middle of the media stream. This is the "safe" setting,
but remember it makes your CPU always handle the media stream.

See also

Created by: oej, Last modification: Tue 03 of Nov, 2015 (23:34) by admin
Please update this page with new information, just login and click on the "Edit" or "Discussion" tab. Get a free login here: Register Thanks! - Find us on Google+