Asterisk.org: Developer Documentation (28 Oct 2009)

Wed Oct 28 15:49:24 2009

## Asterisk developer's documentation

# SIP configuration

Also see RTP configuration RTP configuration

- Implemented in chan_sip.c

## sip.conf

    ;
    ; SIP Configuration example for Asterisk
    ;
    ; Syntax for specifying a SIP device in extensions.conf is
    ; SIP/devicename where devicename is defined in a section below.
    ;
    ; You may also use
    ; SIP/username@domain to call any SIP user on the Internet
    ; (Don't forget to enable DNS SRV records if you want to use this)
    ;
    ; If you define a SIP proxy as a peer below, you may call
    ; SIP/proxyhostname/user or SIP/user@proxyhostname
    ; where the proxyhostname is defined in a section below
    ;
    ; Useful CLI commands to check peers/users:
    ;   sip show peers		Show all SIP peers (including friends)
    ;   sip show users		Show all SIP users (including friends)
    ;   sip show registry		Show status of hosts we register with
    ;
    ;   sip debug			Show all SIP messages
    ;
    ;   reload chan_sip.so		Reload configuration file
    ;				Active SIP peers will not be reconfigured
    ;

    [general]
    context=default			; Default context for incoming calls
    ;allowguest=no			; Allow or reject guest calls (default is yes, this can also be set to 'osp'
    				; if asterisk was compiled with OSP support.
    ;realm=mydomain.tld		; Realm for digest authentication
    				; defaults to "asterisk"
    				; Realms MUST be globally unique according to RFC 3261
    				; Set this to your host name or domain name
    bindport=5060			; UDP Port to bind to (SIP standard port is 5060)
    				; bindport is the local UDP port that Asterisk will listen on
    bindaddr=0.0.0.0		; IP address to bind to (0.0.0.0 binds to all)
    srvlookup=yes			; Enable DNS SRV lookups on outbound calls
    				; Note: Asterisk only uses the first host
    				; in SRV records
    				; Disabling DNS SRV lookups disables the
    				; ability to place SIP calls based on domain
    				; names to some other SIP users on the Internet

    ;domain=mydomain.tld		; Set default domain for this host
    				; If configured, Asterisk will only allow
    				; INVITE and REFER to non-local domains
    				; Use "sip show domains" to list local domains
    ;domain=mydomain.tld,mydomain-incoming
    				; Add domain and configure incoming context
    				; for external calls to this domain
    ;domain=1.2.3.4			; Add IP address as local domain
    				; You can have several "domain" settings
    ;allowexternalinvites=no	; Disable INVITE and REFER to non-local domains
    				; Default is yes
    ;autodomain=yes			; Turn this on to have Asterisk add local host
    				; name and local IP to domain list.
    ;pedantic=yes			; Enable slow, pedantic checking for Pingtel
    				; and multiline formatted headers for strict
    				; SIP compatibility (defaults to "no")
    ;tos=184			; Set IP QoS to either a keyword or numeric val
    ;tos=lowdelay			; lowdelay,throughput,reliability,mincost,none
    ;maxexpiry=3600			; Max length of incoming registration we allow
    ;defaultexpiry=120		; Default length of incoming/outgoing registration
    ;notifymimetype=text/plain	; Allow overriding of mime type in MWI NOTIFY
    ;checkmwi=10			; Default time between mailbox checks for peers
    ;vmexten=voicemail      ; dialplan extension to reach mailbox sets the
    						; Message-Account in the MWI notify message
    						; defaults to "asterisk"
    ;videosupport=yes		; Turn on support for SIP video
    ;recordhistory=yes		; Record SIP history by default
    				; (see sip history / sip no history)

    ;disallow=all			; First disallow all codecs
    ;allow=ulaw			; Allow codecs in order of preference
    ;allow=ilbc			;
    ;musicclass=default		; Sets the default music on hold class for all SIP calls
    				; This may also be set for individual users/peers
    ;language=en			; Default language setting for all users/peers
    				; This may also be set for individual users/peers
    ;relaxdtmf=yes			; Relax dtmf handling
    ;rtptimeout=60			; Terminate call if 60 seconds of no RTP activity
    				; when we're not on hold
    ;rtpholdtimeout=300		; Terminate call if 300 seconds of no RTP activity
    				; when we're on hold (must be > rtptimeout)
    ;trustrpid = no			; If Remote-Party-ID should be trusted
    ;sendrpid = yes			; If Remote-Party-ID should be sent
    ;progressinband=never		; If we should generate in-band ringing always
    				; use 'never' to never use in-band signalling, even in cases
    				; where some buggy devices might not render it
    				; Valid values: yes, no, never Default: never
    ;useragent=Asterisk PBX		; Allows you to change the user agent string
    ;promiscredir = no      	; If yes, allows 302 or REDIR to non-local SIP address
    	                       	; Note that promiscredir when redirects are made to the
           	                	; local system will cause loops since SIP is incapable
           	                	; of performing a "hairpin" call.
    ;usereqphone = no		; If yes, ";user=phone" is added to uri that contains
    				; a valid phone number
    ;dtmfmode = rfc2833		; Set default dtmfmode for sending DTMF. Default: rfc2833
    				; Other options:
    				; info : SIP INFO messages
    				; inband : Inband audio (requires 64 kbit codec -alaw, ulaw)
    				; auto : Use rfc2833 if offered, inband otherwise

    ;compactheaders = yes		; send compact sip headers.
    ;sipdebug = yes			; Turn on SIP debugging by default, from
    				; the moment the channel loads this configuration
    ;subscribecontext = default	; Set a specific context for SUBSCRIBE requests
    				; Useful to limit subscriptions to local extensions
    				; Settable per peer/user also
    ;notifyringing = yes		; Notify subscriptions on RINGING state
    ;alwaysauthreject = yes          ; When an incoming INVITE or REGISTER is to be rejected,
                                     ; for any reason, always reject with an identical response
                                     ; equivalent to valid username and invalid password/hash
                                     ; instead of letting the requester know whether there was
                                     ; a matching user or peer for their request.  This reduces
                                     ; the ability of an attacker to scan for valid SIP usernames.
    ;
    ; If regcontext is specified, Asterisk will dynamically create and destroy a
    ; NoOp priority 1 extension for a given peer who registers or unregisters with
    ; us.  The actual extension is the 'regexten' parameter of the registering
    ; peer or its name if 'regexten' is not provided.  More than one regexten may
    ; be supplied if they are separated by '&'.  Patterns may be used in regexten.
    ;
    ;regcontext=sipregistrations
    ;
    ; Asterisk can register as a SIP user agent to a SIP proxy (provider)
    ; Format for the register statement is:
    ;       register => user[:secret[:authuser]]@host[:port][/extension]
    ;
    ; If no extension is given, the 's' extension is used. The extension needs to
    ; be defined in extensions.conf to be able to accept calls from this SIP proxy
    ; (provider).
    ;
    ; host is either a host name defined in DNS or the name of a section defined
    ; below.
    ;
    ; Examples:
    ;
    ;register => 1234:password@mysipprovider.com
    ;
    ;     This will pass incoming calls to the 's' extension
    ;
    ;
    ;register => 2345:password@sip_proxy/1234
    ;
    ;    Register 2345 at sip provider 'sip_proxy'.  Calls from this provider
    ;    connect to local extension 1234 in extensions.conf, default context,
    ;    unless you configure a [sip_proxy] section below, and configure a
    ;    context.
    ;    Tip 1: Avoid assigning hostname to a sip.conf section like [provider.com]
    ;    Tip 2: Use separate type=peer and type=user sections for SIP providers
    ;           (instead of type=friend) if you have calls in both directions

    ;registertimeout=20		; retry registration calls every 20 seconds (default)
    ;registerattempts=10		; Number of registration attempts before we give up
    				; 0 = continue forever, hammering the other server until it
    				; accepts the registration
    				; Default is 0 tries, continue forever
    ;callevents=no			; generate manager events when sip ua performs events (e.g. hold)

    ;----------------------------------------- NAT SUPPORT ------------------------
    ; The externip, externhost and localnet settings are used if you use Asterisk
    ; behind a NAT device to communicate with services on the outside.

    ;externip = 200.201.202.203	; Address that we're going to put in outbound SIP messages
    				; if we're behind a NAT

    				; The externip and localnet is used
    				; when registering and communicating with other proxies
    				; that we're registered with
    ;externhost=foo.dyndns.net	; Alternatively you can specify an
    				; external host, and Asterisk will
    				; perform DNS queries periodically.  Not
    				; recommended for production
    				; environments!  Use externip instead
    ;externrefresh=10		; How often to refresh externhost if
    				; used
    				; You may add multiple local networks.  A reasonable set of defaults
    				; are:
    ;localnet=192.168.0.0/255.255.0.0; All RFC 1918 addresses are local networks
    ;localnet=10.0.0.0/255.0.0.0	; Also RFC1918
    ;localnet=172.16.0.0/12		; Another RFC1918 with CIDR notation
    ;localnet=169.254.0.0/255.255.0.0 ;Zero conf local network

    ; The nat= setting is used when Asterisk is on a public IP, communicating with
    ; devices hidden behind a NAT device (broadband router).  If you have one-way
    ; audio problems, you usually have problems with your NAT configuration or your
    ; firewall's support of SIP+RTP ports.  You configure Asterisk choice of RTP
    ; ports for incoming audio in rtp.conf
    ;
    ;nat=no				; Global NAT settings  (Affects all peers and users)
                                    ; yes = Always ignore info and assume NAT
                                    ; no = Use NAT mode only according to RFC3581 (;rport)
                                    ; never = Never attempt NAT mode or RFC3581 support
    				; route = Assume NAT, don't send rport
    				; (work around more UNIDEN bugs)

    ;rtcachefriends=yes		; Cache realtime friends by adding them to the internal list
    				; just like friends added from the config file only on a
    				; as-needed basis? (yes|no)

    ;rtupdate=yes			; Send registry updates to database using realtime? (yes|no)
    				; If set to yes, when a SIP UA registers successfully, the ip address,
    				; the origination port, the registration period, and the username of
    				; the UA will be set to database via realtime. If not present, defaults to 'yes'.

    ;rtautoclear=yes		; Auto-Expire friends created on the fly on the same schedule
    				; as if it had just registered? (yes|no|<seconds>)
    				; If set to yes, when the registration expires, the friend will vanish from
    				; the configuration until requested again. If set to an integer,
    				; friends expire within this number of seconds instead of the
    				; registration interval.

    ;ignoreregexpire=yes		; Enabling this setting has two functions:
    				;
    				; For non-realtime peers, when their registration expires, the information
    				; will _not_ be removed from memory or the Asterisk database; if you attempt
    				; to place a call to the peer, the existing information will be used in spite
    				; of it having expired
    				;
    				; For realtime peers, when the peer is retrieved from realtime storage,
    				; the registration information will be used regardless of whether
    				; it has expired or not; if it expires while the realtime peer is still in
    				; memory (due to caching or other reasons), the information will not be
    				; removed from realtime storage

    ; Incoming INVITE and REFER messages can be matched against a list of 'allowed'
    ; domains, each of which can direct the call to a specific context if desired.
    ; By default, all domains are accepted and sent to the default context or the
    ; context associated with the user/peer placing the call.
    ; Domains can be specified using:
    ; domain=<domain>[,<context>]
    ; Examples:
    ; domain=myasterisk.dom
    ; domain=customer.com,customer-context
    ;
    ; In addition, all the 'default' domains associated with a server should be
    ; added if incoming request filtering is desired.
    ; autodomain=yes
    ;
    ; To disallow requests for domains not serviced by this server:
    ; allowexternaldomains=no

    ; fromdomain=mydomain.tld ; When making outbound SIP INVITEs to
                              ; non-peers, use your primary domain "identity"
                              ; for From: headers instead of just your IP
                              ; address. This is to be polite and
                              ; it may be a mandatory requirement for some
                              ; destinations which do not have a prior
                              ; account relationship with your server.

    [authentication]
    ; Global credentials for outbound calls, i.e. when a proxy challenges your
    ; Asterisk server for authentication. These credentials override
    ; any credentials in peer/register definition if realm is matched.
    ;
    ; This way, Asterisk can authenticate for outbound calls to other
    ; realms. We match realm on the proxy challenge and pick an set of
    ; credentials from this list
    ; Syntax:
    ;	auth = <user>:<secret>@<realm>
    ;	auth = <user>#<md5secret>@<realm>
    ; Example:
    ;auth=mark:topsecret@digium.com
    ;
    ; You may also add auth= statements to [peer] definitions
    ; Peer auth= override all other authentication settings if we match on realm

    ;------------------------------------------------------------------------------
    ; Users and peers have different settings available. Friends have all settings,
    ; since a friend is both a peer and a user
    ;
    ; User config options:        Peer configuration:
    ; --------------------        -------------------
    ; context                     context
    ; permit                      permit
    ; deny                        deny
    ; secret                      secret
    ; md5secret                   md5secret
    ; dtmfmode                    dtmfmode
    ; canreinvite                 canreinvite
    ; nat                         nat
    ; callgroup                   callgroup
    ; pickupgroup                 pickupgroup
    ; language                    language
    ; allow                       allow
    ; disallow                    disallow
    ; insecure                    insecure
    ; trustrpid                   trustrpid
    ; progressinband              progressinband
    ; promiscredir                promiscredir
    ; useclientcode               useclientcode
    ; accountcode                 accountcode
    ; setvar                      setvar
    ; callerid		      callerid
    ; amaflags		      amaflags
    ; call-limit		      call-limit
    ; restrictcid		      restrictcid
    ; subscribecontext	      subscribecontext
    ;                             mailbox
    ;                             username
    ;                             template
    ;                             fromdomain
    ;                             regexten
    ;                             fromuser
    ;                             host
    ;                             port
    ;                             qualify
    ;                             defaultip
    ;                             rtptimeout
    ;                             rtpholdtimeout
    ;                             sendrpid
    ;                             outboundproxy

    ;[sip_proxy]
    ; For incoming calls only. Example: FWD (Free World Dialup)
    ; We match on IP address of the proxy for incoming calls
    ; since we can not match on username (caller id)
    ;type=peer
    ;context=from-fwd
    ;host=fwd.pulver.com

    ;[sip_proxy-out]
    ;type=peer          			; we only want to call out, not be called
    ;secret=guessit
    ;username=yourusername			; Authentication user for outbound proxies
    ;fromuser=yourusername			; Many SIP providers require this!
    ;fromdomain=provider.sip.domain
    ;host=box.provider.com
    ;usereqphone=yes			; This provider requires ";user=phone" on URI
    ;call-limit=5				; permit only 5 simultaneous outgoing calls to this peer
    ;outboundproxy=proxy.provider.domain	; send outbound signaling to this proxy, not directly to the peer
    ;port=80				; The port number we want to connect to on the remote side

    ;------------------------------------------------------------------------------
    ; Definitions of locally connected SIP phones
    ;
    ; type = user	a device that authenticates to us by "from" field to place calls
    ; type = peer	a device we place calls to or that calls us and we match by host
    ; type = friend two configurations (peer+user) in one
    ;
    ; For local phones, type=friend works most of the time
    ;
    ; If you have one-way audio, you probably have NAT problems.
    ; If Asterisk is on a public IP, and the phone is inside of a NAT device
    ; you will need to configure nat option for those phones.
    ; Also, turn on qualify=yes to keep the nat session open

    ;[grandstream1]
    ;type=friend
    ;context=from-sip		; Where to start in the dialplan when this phone calls
    ;callerid=John Doe <1234>	; Full caller ID, to override the phones config
    ;host=192.168.0.23		; we have a static but private IP address
    				; No registration allowed
    ;nat=no				; there is not NAT between phone and Asterisk
    ;canreinvite=yes		; allow RTP voice traffic to bypass Asterisk
    ;dtmfmode=info			; either RFC2833 or INFO for the BudgeTone
    ;call-limit=1			; permit only 1 outgoing call and 1 incoming call at a time
    				; from the phone to asterisk
    				; (1 for the explicit peer, 1 for the explicit user,
    				; remember that a friend equals 1 peer and 1 user in
    				; memory)
    ;mailbox=1234@default		; mailbox 1234 in voicemail context "default"
    ;disallow=all			; need to disallow=all before we can use allow=
    ;allow=ulaw			; Note: In user sections the order of codecs
    				; listed with allow= does NOT matter!
    ;allow=alaw
    ;allow=g723.1			; Asterisk only supports g723.1 pass-thru!
    ;allow=g729			; Pass-thru only unless g729 license obtained

    ;[xlite1]
    ; Turn off silence suppression in X-Lite ("Transmit Silence"=YES)!
    ; Note that Xlite sends NAT keep-alive packets, so qualify=yes is not needed
    ;type=friend
    ;regexten=1234			; When they register, create extension 1234
    ;callerid="Jane Smith" <5678>
    ;host=dynamic			; This device needs to register
    ;nat=yes			; X-Lite is behind a NAT router
    ;canreinvite=no			; Typically set to NO if behind NAT
    ;disallow=all
    ;allow=gsm			; GSM consumes far less bandwidth than ulaw
    ;allow=ulaw
    ;allow=alaw
    ;mailbox=1234@default,1233@default	; Subscribe to status of multiple mailboxes

    ;[snom]
    ;type=friend			; Friends place calls and receive calls
    ;context=from-sip		; Context for incoming calls from this user
    ;secret=blah
    ;subscribecontext=localextensions	; Only allow SUBSCRIBE for local extensions
    ;language=de			; Use German prompts for this user
    ;host=dynamic			; This peer register with us
    ;dtmfmode=inband		; Choices are inband, rfc2833, or info
    ;defaultip=192.168.0.59		; IP used until peer registers
    ;mailbox=1234@context,2345      ; Mailbox(-es) for message waiting indicator
    ;vmexten=voicemail      ; dialplan extension to reach mailbox
                            ; sets the Message-Account in the MWI notify message
                            ; defaults to global vmexten which defaults to "asterisk"
    ;restrictcid=yes		; To have the callerid restriced -> sent as ANI
    ;disallow=all
    ;allow=ulaw			; dtmfmode=inband only works with ulaw or alaw!

    ;[polycom]
    ;type=friend			; Friends place calls and receive calls
    ;context=from-sip		; Context for incoming calls from this user
    ;secret=blahpoly
    ;host=dynamic			; This peer register with us
    ;dtmfmode=rfc2833		; Choices are inband, rfc2833, or info
    ;username=polly			; Username to use in INVITE until peer registers
    				; Normally you do NOT need to set this parameter
    ;disallow=all
    ;allow=ulaw                     ; dtmfmode=inband only works with ulaw or alaw!
    ;progressinband=no		; Polycom phones don't work properly with "never"

    ;[pingtel]
    ;type=friend
    ;secret=blah
    ;host=dynamic
    ;insecure=port			; Allow matching of peer by IP address without matching port number
    ;insecure=invite		; Do not require authentication of incoming INVITEs
    ;insecure=port,invite		; (both)
    ;qualify=1000			; Consider it down if it's 1 second to reply
    				; Helps with NAT session
    				; qualify=yes uses default value
    ;
    ; Call group and Pickup group should be in the range from 0 to 63
    ;
    ;callgroup=1,3-4		; We are in caller groups 1,3,4
    ;pickupgroup=1,3-5		; We can do call pick-p for call group 1,3,4,5
    ;defaultip=192.168.0.60		; IP address to use if peer has not registered

    ;[cisco1]
    ;type=friend
    ;secret=blah
    ;qualify=200			; Qualify peer is no more than 200ms away
    ;nat=yes			; This phone may be natted
    				; Send SIP and RTP to the IP address that packet is
    				; received from instead of trusting SIP headers
    ;host=dynamic			; This device registers with us
    ;canreinvite=no			; Asterisk by default tries to redirect the
    				; RTP media stream (audio) to go directly from
    				; the caller to the callee.  Some devices do not
    				; support this (especially if one of them is
    				; behind a NAT).
    ;defaultip=192.168.0.4		; IP address to use until registration
    ;username=goran			; Username to use when calling this device before registration
    				; Normally you do NOT need to set this parameter
    ;setvar=CUSTID=5678		; Channel variable to be set for all calls from this device

- Back Channel configuration files