[Asterisk-Dev] Long comments and ideas for sip.conf

[John Todd]

Long message.  Get a big mug of coffee or something before you start 
to read this.  Mark, take a few aspirin with that coffee.

I have a few comments on some extensions and re-arrangements of the 
sip.conf file that might make it a bit more extensible, and a bit 
better organized for some of the complex things people (like myself) 
are asking it to do.  After quite a bit of thought and some 
understanding of how components elsewhere in the system work, I think 
the following modifications to the SIP configuration parsing and 
functionality might be useful.  There are many sub-portions of these 
comments, each of which might be it's own feature request, but I 
thought that putting them into one long message here might induce 
some commentary before I went through the process of getting it into 
bugs.digium.com.  Here we go...


1) Addition of "include" logic into sip.conf:

I have been adding large numbers of SIP phones to various Asterisk 
servers, and as my fingers have worn down, it has occurred to me that 
the use of some type of macro or other quick addition method might 
make sense.  The use of the [default] stanza is great, but that only 
allows one default to be easily referenced.  I have multiple 
defaults, usually based on what type of equipment the user has on 
their desk.  I really like the concept of "include" statements in the 
extensions.conf, and a natural expansion of that concept I think 
would work well in sip.conf to make configuration there easier.  For 
large locations. this would reduce the duplication of data for each 
customer, and would allow "global" changes for certain equipment 
types very quickly.  The ability to create "meta-users" for SIP (see 
example #1) would allow for selection of codecs, bitrates, etc. from 
within the dialplan in a reasonably extendable way, simply by 
specifying a different meta-user which is being referenced in the 
Dial application.


2) Selective inclusion based on User-Agent:

Additionally, I have had great pains when users switch what type of 
phone they're using without telling me.  Some phones work with 
certain sip.conf configurations; others do not.  The ability to 
automatically detect these phones exists: it's in the User-Agent: 
string that gets sent in the SIP headers.  It would be of great 
benefit to automatically detect these strings, and using a wildcard 
system provide different actions within sip.conf.  This would 
virtually eliminate configuration changes entirely in sip.conf once a 
peer was configured correctly.  There may be rare circumstances where 
User-Agent: settings are not sufficient, but I am very much 
interested in the 90/10 rule here - if I can take care of 90% of the 
problems, then I can handle the 10% exceptions.

The only "twist" on this concept outside of the use of "include" as I 
define it in #1 would be that the new concept of "equipment=" would 
spin include=> a little differently.  Any stanza starting with 
"equipment-" would be treated specially, in that Asterisk would try 
to match the User-Agent: data and then use the first included stanza 
in the tree that has a "user-agent=" string that matches.  This 
method might even be able to eventually replace the [default] stanza, 
but it can certainly co-exist with it.  The current use and syntax of 
sip.conf is compatible with the new version, so this method is 
backwards-compatible.  Note that "includes" can be nested for 
equipment- calls, so you can create one big stanza that includes all 
of the other equipment- stanzas, for a global match.  I am open to 
other ways of doing this, but it was the only one I came up with off 
the top of my head (see Example #2)


3) Registration with other SIP servers - clean up syntax:

While I had started this huge undertaking, I figured: 'What the hell, 
let's look at registration, since I'm already writing nearly a book 
on the sip.conf.'   The current method of listing SIP register=> 
commands in the [general] context is getting pretty ugly all on one 
line, and doesn't offer much flexibility.  The extraction of these 
register commands out of one-line summaries and into the general 
format of the sip.conf file seems to be a good idea.  There are 
additional flags and timers that would be desirable to set on 
outbound REGISTER requests, and the only way to cleanly do that is to 
change the way register=> is done and make it look more like the rest 
of the file.  See example #3.


4) Minor extensions and features

There are a few extra features that sip.conf needs to make it more 
compliant with both the RFCs and with the "real world".  Some of 
these features become possible only with some of the other 
modifications in this document.  Here's the list:

   - User-Agent: spoofing on a per host basis, to get around badly 
built or filtered servers that only want to talk to a certain piece 
of equipment
   - Configurable expire times for SIP registrations that are made 
with remote servers, on a per-peer basis
   - Protocol selection between TCP and UDP for SIP messages, on a 
per-peer selection (for registrations as well as any other SIP 
operation)


-------------------------------
Example #1: Using "includes" in the sip.conf file to regulate how we 
pass out calls to certain SIP peers.  This creates two "meta" users 
that have the same characteristics as 7003, except that one is a 
low-bandwidth restricted user and one is a high-bandwidth user.  We 
then refer to those "meta" users in the dialplan when we want to send 
a call to a user, but using slightly different configuration options 
for that peer entry.  If the host wasn't dynamic, I suppose this 
could be done with existing SIP configurations with static IP 
addresses (ugly) but if the host is dynamic it won't work at all, so 
a meta-user concept might suffice to handle this process.

; -- sip.conf start --

[7003]
username=bill
secret=notreallysecret
context=generic-customer1
nat=no
canreinvite=no
host=dynamic


[7003-low]
include => 7003
disallow=all
allow=g729


[7003-high]
include => 7003
disallow=all
allow=ulaw
allow=alaw

; -- sip.conf end --

; -- extension.conf start --
;
; This checks to see if the variable "PAIDUP" has
;  been set to "1".  If so, then this customer gets
;  a nice fat alaw/ulaw (64kbps) pipe to use.  If not,
;  then we send him to a G.729 channel at 9.6kbps.
;
exten => 7003,1,DBget(PAIDUP=${EXTEN}/PAIDUP)
exten => 7003,2,GotoIf($[${PAIDUP} = 1]?3:5)
exten => 7003,3,Dial(SIP/${EXTEN}-high,50,r)
exten => 7003,4,Voicemail2(u${EXTEN})
exten => 7003,5,Dial(SIP/${EXTEN}-low,50,r)
exten => 7003,6,Voicemail2(u${EXTEN})
exten => 7003,104,Voicemail2(b${EXTEN})
exten => 7003,106,Voicemail2(b${EXTEN})

--------------------------------------


Example #2: We use "include" and "equipment-" stanzas to allow any 
user to access the system with any SIP device on which they might be 
sitting.


; Note: hypothetical "protocol=" command is used - this doesn't exist yet.
;   This could potentially be udp, or tcp.  Here's hoping.  :-)
;
; Wildcard matching is the same as that used in the dialplan, except that
;  special characters are escaped with "\" characters.
;

[7000]
equipment=allphones
username=bob
secret=foo
host=dynamic

[7001]
equipment=allphones
username=jane
secret=baz
host=dynamic

; We override the context for this user.
[7002]
equipment=allphones
context=special-customers
username=theboss
secret=bigsecret
host=dynamic

; Here, we create one easy-to-include list of includes
[equipment-allphones]
include => equipment-7960-4.4
include => equipment-ATA-new
include => equipment-grandstream1
include => equipment-asterisk-beta
include => equipment-allothers

; This matches Cisco 7960's running version 4 of the SIP code
;  i.e.: CSCO/4
;
[equipment-7960-4.4]
user-agent="CSCO/4"
context=from-customers1
canreinvite=no
type=friend
protocol=udp
dtmfmode=rfc2833
nat=yes

; This matches ATA-186 devices running v2.14 through 2.16
;  i.e.: Cisco ATA 186  v2.16 ata18x (030401a)
;
[equipment-ATA-new]
user-agent="Cisco ATA 186  v2.1\[4,5,6\]\*"
context=from-customers1
canreinvite=no
type=friend
protocol=udp
dtmfmode=rfc2833
nat=yes

; This matches Grandstream phones > 1.0
;  i.e.:  Grandstream SIP UA 1.0.3.81
;
[equipment-grandstream1]
user-agent="Grandstream SIP UA 1.0.\*"
context=from-customers1
canreinvite=no
type=friend
protocol=udp
dtmfmode=info
nat=no

; This matches Asterisk servers.  Currently, Asterisk does
;  not send version numbers.  :-(
;  i.e.: Asterisk PBX
;
[equipment-asterisk-beta]
user-agent="Asterisk PBX"
context=from-customers1
canreinvite=no
type=friend
protocol=udp
dtmfmode=rfc2833
nat=no


; If it doesn't match any of the above, this is the last match
;  in the "include" list in equipment-allphones, and it's a wildcard,
;  so it gets used.
;
[equipment-allothers]
user-agent="\*"
context=from-customers1
canreinvite=no
type=friend
protocol=udp
dtmfmode=rfc2833
nat=yes


------------------------------------------------------


Example #3: We replace the "register=>" lines with something that 
makes a bit more sense.  Breaking things out into stanza format seems 
to make a lot mor


; We add a few extra features in each sip peer.
;  expire = the number of seconds that this registration should
;    indicate for expiry.  Default is 500.
;  register = [yes, no] Is this a host to which we're sending
;    registrations, or receiving them? Despite the fact that some
;    remote servers may be both registered to and received from,
;    the presence of a "register = yes" line means that the definition
;    will only be used for REGISTER requests, and a separate peer
;    must be defined for outbound calls, even to the same host.  A
;    "no" definition means take no action.  Default = no.
;  user = [userid[@hostname][/localextension]] - This is more or
;    less identical to the prior syntax of the register=> lines,
;    where userid is the only mandatory field.  A domain and/or
;    local extension are optional.  No default.
;  secret = password for the user.  No default.


; When using "include", the order of the included lines is the order
;  in which the settings are taken.  The first match wins.  Thus:
;
; [foo]
; expire=100
;
; [bar]
; host=something.domain.com
; expire=200
; include => foo
;
; If running a call through peer "bar", then expire would
;   end up being 200.
;

; In this example, we have two lines that we want to register
;  with Free World Dialup.

; Note that only one "qualify" sample loop should be run against
;  a single host.  We don't want to measure for each meta-peer.

[fwd-main]
register=no
host=fwd.pulver.com
expire=200
register-agent="Wazoo SIP Proxy v1.0"
qualify=1000


[fwd-13392]
register=yes
user=13992 at fwd.pulver.com/13392
secret=somesecrethere
include => fwd-main

[fwd-4832]
register=yes
user=4832 at fwd.pulver.com/4832
secret=anothersecretword
register-agent="Asterisk PBX"
include => fwd-main