A.2. SIP
Just as with IAX, the SIP configuration file
(sip.conf) contains configuration
information for SIP channels. The headings for the channel
definitions are formed by a word framed in square brackets
([])again, with the exception of the [general]
section, where we define global SIP parameters. Don't forget to use
comments generously in your sip.conf file. Precede the comment text with a
semicolon; everything to the right will be ignored.
A.2.1. General SIP Parameters
The following options are to be used within the
[general] section of sip.conf:
allowguest
-
If set to no, this disallows guest SIP
connections. The default is to allow guest connections. SIP
normally requires authentication, but you can accept calls from
users who do not support authentication (i.e., do not have a
secret field defined). Certain SIP appliances (such as the
Cisco Call Manager v4.1) do not support authentication, so they
will not be able to connect if you set allowguest=no.
allowguest=no
bindaddr and bindport
-
These optional parameters allow you to control
the IP interface and port on which you wish to accept SIP
connections. If omitted, the port will be set to 5060, and all IP
addresses in your Asterisk system will accept incoming SIP
connections. If multiple bind addresses are configured, only those
interfaces will listen for connections. The address 0.0.0.0 tells
Asterisk to listen on all interfaces.
bindaddr=0.0.0.0
bindport=5060
callevents
-
Set this to yes when you want SIP to
generate Manager events. This will be important if you have
external programs that use the Asterisk Manager interface, such as
the Flash Operator Panel.
callevents=yes
checkmwi
-
This option specifies the default amount of
time, in seconds, between mailbox checks for peers.
checkmwi=30
compactheaders
-
You can set compactheaders to
yes or no. If it's set to yes, the SIP
headers will use a compact format, which may be required if the
size of the SIP header is larger than the maximum transmission unit
(MTU) of your IP headers, causing the IP packet to be fragmented.
Do not use this option unless you know what you are doing.
compactheaders=no
defaultexpirey
-
This sets the default SIP registration
expiration time, in seconds, for incoming and outgoing
registrations. A client will normally define this value when it
initially registers, so the default value you set here will be used
only if the client does not specify a timeout when it registers. If
you are registering to another user agent server (UAS), this is the
registration timeout that it will send to the far end.
defaultexpirey=300
externhost
-
externhost takes a fully qualified
domain name as its argument. If Asterisk is behind NAT, the SIP
header will normally use the private IP address assigned to the
server. If you set this option, Asterisk will perform periodic DNS
lookups on the hostname and replace the private IP address with the
IP address returned from the DNS lookup.
externhost=my.hostname.tld
|
The use of externhost is not
recommended in production systems, because if the IP address of the
server changes, the wrong IP address will be set in the SIP headers
until the next lookup is performed. The use of externip is
recommended instead.
|
|
externip
-
externip takes an IP address as its
argument. If Asterisk is behind NAT, the SIP header will normally
use the private IP address assigned to the server. The remote
server will not know how to route back to this address; thus, it
must be replaced with a valid, routable address.
externip=216.239.39.104
externrefresh
-
If externhost is used,
externrefresh configures how long, in seconds, should pass
between DNS lookups.
externrefresh=30
localnet
-
localnet is used to tell Asterisk which
IP addresses are considered local, so that the address in the SIP
header can be translated to that specified by externip or
the IP address can be looked up with externhost.
localnet=192.168.1.0/24
localnet=172.16.0.0/16
maxexpirey
-
This sets the maximum amount of time, in
seconds, until a peer's registration expires.
maxexpirey=3600
notifymimetype
-
This takes as its argument a string specifying
the MIME type used for the message waiting notification (MWI) in
the SIP NOTIFY message. The most common setting for this
field is text/plain, although it can be customized if need
be.
notifymimetype=text/plain
pedantic
-
You can set pedantic to yes or
no. Setting it to yes enables slow pedantic
checking for phones that require it, such as the Pingtel, and
enables more strict SIP RFC compliancy. In an effort to improve
performance, SIP RFC compliance is not normally strictly adhered
to.
pedantic=yes
realm
-
This option sets the realm for digest
authentication. Set realm to your fully qualified domain
name, which must be globally unique.
realm=my.hostname.tld
recordhistory
-
You can set recordhistory to
yes or no to enable or disable SIP history
recording for all channels. (See sip
history and sip no history in Appendix E.)
recordhistory=yes
relaxdtmf
-
You can set relaxdtmf to yes
or no. Setting it to yes will relax the DTMF
detection handling. Use this if Asterisk is having a difficult time
determining the DTMF on the SIP channel. Note that this may cause
"talkoff," where Asterisk incorrectly detects DTMF when it should
not.
relaxdtmf=yes
srvlookup
-
DNS SRV records are a way of setting up a
logical, resolvable address where you can be reached. This allows
calls to be forwarded to different locations without the need to
change the logical address. By using SRV records, you gain many of
the advantages of DNS, whereas disabling them removes the ability
to place SIP calls based on domain names. (Note that if multiple
records are returned, Asterisk will use only the first.) DNS SRV
record lookups are recommended. To enable them, set
srvlookup=yes in the [general] section of
sip.conf.
srvlookup=yes
tos
-
Asterisk can set the Type of Service (TOS) bits
in the IP header to help improve performance on routers that
respect TOS bits in their routing calculations. The following
values are valid:
lowdelay
-
Minimize delay.
throughput
-
Maximize throughput.
reliability
-
Maximize reliability.
mincost
-
Minimize cost.
none
-
No bits set.
tos=lowdelay|throughput|reliability|mincost|none
useragent
-
useragent takes as its argument a
string specifying the value for the useragent field in the
SIP header. The default value is asterisk.
useragent=asterisk
videosupport
-
You can set videosupport to
yes or no. Setting it to yes will enable
SIP video support. Video support works only between two
endpointsAsterisk does not support video conferencing at this
time.
videosupport=yes
A.2.2. SIP Channel Definitions
Now that we've covered the global SIP
parameters, we will discuss the channel-specific parameters. These
parameters can be defined for a user, a peer, or both (as noted in
parentheses):
accountcode (both)
-
The account code can be defined on a per-user
basis. If defined, this account code will be assigned to a call
record whenever no specific user account code is set. The
accountcode name configured will be used as the
filename.csv in the /var/log/asterisk/cdr-csv/ directory to store
CDRs for the user/peer/friend.
accountcode=iax-username
allow and disallow
(both)
-
Specific codecs can be allowed or disallowed,
limiting codec use to those preferred by the system designer.
allow and disallow can also be defined on a
per-channel basis. Keep in mind that allow statements in the
[general] section will carry over to each of the channels,
unless you reset with a disallow=all. Codec negotiation is
attempted in the order in which the codecs are defined. Best
practice suggests that you define disallow=all, followed
by explicit allow statements for each codec you wish to
use. If nothing is defined, allow=all is assumed.
disallow=all
allow=ulaw
allow=gsm
allow=ilbc
amaflags (both)
-
Automatic Message Accounting (AMA) is defined in
the Telcordia Family of Documents listed under FR-AMA-1. These
documents specify standard mechanisms for generation and
transmission of CDRs. You can specify one of four AMA flags
(default, omit, billing, or
documentation) to apply to all SIP connections.
amaflags=documentation
callerid (both)
-
You can set a suggested Caller ID string for a
user or peer with callerid. If you define a Caller ID
field for a user, any calls that come in on that channel will have
that Caller ID assigned to them, regardless of what the far end
sends to you. If Caller ID is defined for a peer, you are
requesting that the far end use that to identify you (keep in mind,
however, that you have no way to ensure that it will do so). If you
want incoming callers to be able to define their own Caller IDs
(i.e., for guests), make sure you do not set the callerid
field.
callerid=John Smith <(800) 555-1234>
callgroup and pickupgroup
(both)
-
You can use the callgroup parameter to
assign a channel definition to one or more groups, and you can use
the pickupgroup option in conjunction with this parameter
to allow a ringing phone to be answered from another extension. The
pickupgroup option is used to control which callgroups a
channel may pick upa channel is given authority to answer another
ringing channel if it is assigned to the same pickupgroup
as the ringing channel's callgroup. By default, remote ringing
extensions can be answered with *8 (this is configurable
in the features.conf file).
callgroup=1,3-5
pickupgroup=1,3-5
canreinvite (both)
-
The SIP protocol tries to connect endpoints
directly. However, Asterisk must remain in the transmission path
between the endpoints if it is required to detect DTMF. (For more
information, see Chapter 4.)
canreinvite=no
context (both)
-
A context is assigned to a channel definition to
direct incoming calls into the matching context in extensions.conf, where call handling is
performed (see Chapters 4 and 5). Any
channel connecting to an Asterisk machine has to have a context
defined into which it will arrive. The context is essential for any
user channel definitionif you do not define a context,
incoming calls will be directed to the default
context.
context=incoming
defaultip (peer)
-
The defaultip setting complements
host=dynamic. If a host has not yet registered with your
server, you'll attempt to send messages to the default IP address
configured here.
defaultip=192.168.1.101
deny (both)
-
Specific IP addresses and ranges can be
controlled with the deny option. To restrict access from a
range of IP addresses, use a subnet maskfor example,
deny=192.168.1.0/255.255.255.0. You can also deny all
addresses with deny=0.0.0.0/0.0.0.0 and then allow only
certain addresses with the permit command. Be aware of the
security implications of this setting. (See also
permit.)
deny=0.0.0.0/0.0.0.0
disallow (both)
-
See allow.
dtmfmode (both)
-
You can set dtmfmode to
inband, rfc2833, or info. DTMF digits
can be sent either in band (as part of the audio stream), or out of
band (as signaling information), using the RFC 2833 or INFO
methods. The inband method only works reliably when using
an uncompressed codec such as G.711, ulaw, or alaw. The recommended
method is to use rfc2833; however, some devicessuch as
those by Grandstreamsupport the info method.
dtmfmode=rfc2833
fromdomain (peer)
-
This allows you to set the domain in the
From: field of the SIP header. It may be required by some
providers for authentication.
fromdomain=my.hostname.tld
fromuser (peer)
-
This allows you to set the username with which
to authenticate. The name contained within the square brackets of
the channel definition is usually used, but this can be overridden
with the fromuser option. This allows a channel definition
to be referenced with a name other than that used to
authenticate.
fromuser=john_smith
host (peer)
-
This configures the host to which this peer is
to connect. Use a fully qualified domain name.
host=remote.hostname.tld
incominglimit (both)
-
This option limits the total number of
simultaneous calls for a peer or user. It sets the max number of
simultaneous outgoing calls for a peer, or the max number of
incoming calls for a user.
incominglimit=3
insecure (both)
-
When an INVITE is received from a
remote location, Asterisk attempts to authenticate the string of
characters before the @ sign on the INVITE line
received in the SIP header with the name of a channel definition in
sip.conf. If the remote end is a
user agent, it will authenticate based on a user
definition. However, if the remote end is a SIP proxy service, it
will authenticate on the peer entry. When calls come from
a provider such as Free World Dialup, which acts as a proxy for the
true remote end who is calling you, that provider cannot
authenticate the call on behalf of the endpoint. Since it would be
impractical to have an authentication configured for every FWD
user, and since FWD cannot respond to a 407 Proxy Authentication
Required response, there must be an alternate way to allow calls
from these callers.
If you set insecure=invite, you'll
determine which peer to match on by comparing the IP address or
hostname and port number to those provided in the Contact
field of the SIP header with the host and port
options in sip.conf. If a match is
found, authentication will not be required on the initial
INVITE, and the call will be allowed.
If you have multiple endpoints behind a NAT
device, you need to enable insecure=port to match only
against the IP address. To not require authentication on the
incoming INVITE for the peer, set
insecure=invite,port.
insecure=invite
language (both)
-
This sets the language flag to whatever you
define. The global default language is English. The language that
is set is sent by the channel as an information element. It is also
used by applications such as SayNumber( ) that have
different files for different languages. Keep in mind that
languages other than English are not explicitly installed on the
system, and it is up to you to configure the system to ensure that
the language you specify is handled properly.
language=en
mailbox (peer)
-
If you associate a mailbox with a peer
within the channel definition, voicemail will send a message
waiting indication to the nodes on the end of that channel. If the
mailbox number is in a voicemail context other than
default, you can specify it as
mailbox@context. To
associate multiple mailboxes with a single peer, use multiple
mailbox statements.
mailbox=1000@internal
md5secret (both)
-
If you do not wish to have plain-text secrets in
your sip.conf files, you can use
md5secret to configure the MD5 hash that can be used for
authentication. To generate the MD5 hash from the Linux console,
use the following command:
# echo -n " username : realm : secret " | md5sum
Be sure to use the -n flag, or
echo will add a \n to the end of the string; the
line feed will then be calculated into the MD5 hash, creating the
incorrect hash. The realm, if not specified with
the realm option (discussed in the list of general SIP
parameters), defaults to asterisk. If both an
md5secret and a secret are specified in the same
channel definition, the secret will be ignored.
md5secret=0bcbe762982374c276fb01af6d272dca
musicclass (both)
-
This option sets the default Music on Hold
class.
musicclass=classical
nat (both)
-
You can set nat to yes,
no, or never. If you set it to yes,
Asterisk ignores the IP address in the SIP and SDP headers and
responds to the address and port in the IP header. The
never option is for devices that cannot handle
rport in the SIP header, such as the Uniden UIP200.
nat=yes
permit (both)
-
See deny.
pickupgroup (both)
-
See callgroup.
port (peer)
-
You can use this to define the port on which to
listen for SIP signaling, if you want to listen on a nonstandard
port. (The default port for SIP signaling is 5060.)
port=5060
progressinband (both)
-
You can set progressinband to
yes, no, or never, to configure whether
or not to generate in-band ringing. Normally, Asterisk will send
the progress of a call via a few methods, such as 183 Session
Progress, 180 Ringing, 486 Busy, and so on. If you set
progressinband=yes, Asterisk will indicate the call
progress in band by generating tones.
progressinband=yes
promiscredir (both)
-
You can set promiscredir to
yes or no. Normally, when you perform call
forwarding on a phone, Asterisk will use the Local channel (for
example, ocal/18005551212@peer). If you set
promiscredir=yes, Asterisk will use the SIP channel
instead, which enables you to forward the calls to remote
boxes.
promiscredir=yes
|
Note that if Asterisk performs a redirect to
itself when promiscredir=yes, the system will receive an
INVITE with the same Caller ID and detect a loop to
itself. SIP does not have the ability to perform a hairpin call, so
the channel will then be destroyed.
|
|
qualify (peer)
-
You can set qualify to yes,
no, or a time in milliseconds. If you set
qualify=yes, NOTIFY messages will be sent
periodically to the remote peers to determine whether they are
available and what the latency between replies is. A peer is
determined unreachable if no reply is received within 2,000 ms (to
change this default, instead set qualify to the number of
milliseconds to wait for the reply). Use this option in conjunction
with nat=yes to keep the path through the NAT device
alive.
qualify=yes
regcontext (peer)
-
By specifying the context that contains the
actions to perform, you can configure Asterisk to perform a number
of actions when a peer registers to your server. This option works
in conjunction with regexten, by specifying the extension
to execute. If no regexten is configured, the peer name is
used as the extension. Asterisk will dynamically create and destroy
a NoOp at priority 1 for the extension. All actions to be
performed upon registration should start at priority 2. More than
one regexten may be supplied, if separated by an
&. regcontext can be set on a per-peer basis
or globally.
regcontext=peer_registrations
regexten (peer)
-
The regexten option is used in
conjunction with regcontext to specify the extension that
is executed within the configured context. If regexten is
not explicitly configured, the peer name is used as the extension
to match.
regexten=1000
rtpholdtimeout (peer)
-
This takes as its argument an integer, specified
in seconds. It terminates a call if no RTP data is received while
on hold. The value of rtpholdtimeout must be greater than
that of rtptimeout. (See also rtptimeout.)
rtpholdtimeout=120
rtptimeout (peer)
-
This takes as its argument an integer, specified
in seconds. It terminates a call if no RTP data is received within
the time specified.
rtptimeout=60
secret (both)
-
This sets the password to use for
authentication.
secret=welcome
setvar (both)
-
This sets a channel variable, which will be
available when a channel to the peer or user is created and will be
destroyed when the call is hung up. For example, to set the channel
variable foo with a value of bar, use
setvar=foo=bar.
setvar=foo=bar
username (peer)
-
The username field allows you to
attempt contact with a peer before it has registered with you. At
registration, a SIP device tells Asterisk which SIP URI to use to
contact it. The username is used in conjunction with
defaultip to create the SIP URI in the SIP INVITE
header. This might be useful following a reboot, in order to place
a call. The endpoints will not attempt to register with the server
until their registration timeouts expire, so you will not know
their locations. For non-dynamic hosts, you will require the
username to be specified, as it is used to construct the
authorization username.
username=john_smith
|