It is clear from multiple mailing list, forum, wiki and other sorts of posts that users don't really understand the effects that the 'canreinvite' config option actually has, and that in some cases they think that setting it to 'no' will actually cause various other features (T.38, MOH, etc.) to not work properly, when in fact this is not the case. This patch changes the proper name of the option to what it should have been from the beginning ('directmedia'), but preserves backwards compatibility for existing configurations. git-svn-id: https://origsvn.digium.com/svn/asterisk/trunk@210190 65c4cc65-6c06-0410-ace0-fbb531ad65f3
308 lines
12 KiB
TeX
308 lines
12 KiB
TeX
\section{Introduction}
|
|
|
|
Asterisk includes basic phone provisioning support through the res\_phoneprov module. The
|
|
current implementation is based on a templating system using Asterisk dialplan function
|
|
and variable substitution and obtains information to substitute into those templates from
|
|
\path{phoneprov.conf} and \path{users.conf}. A profile and set of templates is provided
|
|
for provisioning Polycom phones. Note that res\_phoneprov is currently limited to
|
|
provisioning a single user per device.
|
|
|
|
\section{Configuration of phoneprov.conf}
|
|
|
|
The configuration file, \path{phoneprov.conf}, is used to set up the built-in variables
|
|
SEVER and SERVER\_PORT, to define a default phone profile to use, and to define different
|
|
phone profiles available for provisioning.
|
|
|
|
\subsection{The [general] section}
|
|
|
|
Below is a sample of the general section of \path{phoneprov.conf}:
|
|
|
|
\begin{astlisting}
|
|
\begin{verbatim}
|
|
[general]
|
|
;serveriface=eth0
|
|
;serveraddr=192.168.1.1
|
|
;serverport=5060
|
|
default_profile=polycom
|
|
\end{verbatim}
|
|
\end{astlisting}
|
|
|
|
By default, res\_phoneprov will set the SERVER variable to the IP address on the server
|
|
that the requesting phone uses to contact the asterisk HTTP server. The SERVER\_PORT
|
|
variable will default to the \textbf{bindport} setting in sip.conf.
|
|
|
|
Should the defaults be insufficient, there are two choices for overriding the default
|
|
setting of the SERVER variable. If the IP address of the server is known, or the hostname
|
|
resolvable by the phones, the appropriate \textbf{serveraddr} value should be set.
|
|
Alternatively, the network interface that the server listens on can be set by specifying a
|
|
\textbf{serveriface} and SERVER will be set to the IP address of that interface. Only one
|
|
of these options should be set.
|
|
|
|
The default SERVER\_PORT variable can be overridden by setting the \textbf{serverport}.
|
|
If \textbf{bindport} is not set in \path{sip.conf} and serverport is not specified, it
|
|
is set to a default value of 5060.
|
|
|
|
Any user set for auto-provisioning in users.conf without a specified profile will be
|
|
assumed to belong to the profile set with \textbf{default\_profile}.
|
|
|
|
\subsection{Creating phone profiles}
|
|
|
|
A phone profile is basically a list of files that a particular group of phones needs to
|
|
function. For most phone types there are files that are identical for all phones
|
|
(firmware, for instance) as well as a configuration file that is specific to individual
|
|
phones. res\_phoneprov breaks these two groups of files into static files and dynamic
|
|
files, respectively. A sample profile:
|
|
|
|
\begin{astlisting}
|
|
\begin{verbatim}
|
|
[polycom]
|
|
staticdir => configs/
|
|
mime_type => text/xml
|
|
setvar => CUSTOM_CONFIG=/var/lib/asterisk/phoneprov/configs/custom.cfg
|
|
static_file => bootrom.ld,application/octet-stream
|
|
static_file => bootrom.ver,plain/text
|
|
static_file => sip.ld,application/octet-stream
|
|
static_file => sip.ver,plain/text
|
|
static_file => sip.cfg
|
|
static_file => custom.cfg
|
|
${TOLOWER(${MAC})}.cfg => 000000000000.cfg
|
|
${TOLOWER(${MAC})}-phone.cfg => 000000000000-phone.cfg
|
|
config/${TOLOWER(${MAC})} => polycom.xml
|
|
${TOLOWER(${MAC})}-directory.xml => 000000000000-directory.xml
|
|
\end{verbatim}
|
|
\end{astlisting}
|
|
|
|
A \textbf{static\_file} is set by specifying the file name, relative to
|
|
\path{AST\_DATA\_DIR/phoneprov}. The mime-type of the file can optionally be specified
|
|
after a comma. If \textbf{staticdir} is set, all static files will be relative to the
|
|
subdirectory of AST\_DATA\_DIR/phoneprov specified.
|
|
|
|
Since phone-specific config files generally have file names based on phone-specifc data,
|
|
dynamic filenames in res\_phoneprov can be defined with Asterisk dialplan function and
|
|
variable substitution. In the above example, \$\{TOLOWER(\$\{MAC\})\}.cfg $\Rightarrow$
|
|
000000000000.cfg would define a relative URI to be served that matches the format of
|
|
MACADDRESS.cfg, all lower case. A request for that file would then point to the template
|
|
found at AST\_DATA\_DIR/phoneprov/000000000000.cfg. The template can be followed by a
|
|
comma and mime-type. Notice that the dynamic filename (URI) can contain contain
|
|
directories. Since these files are dynamically generated, the config file itself does not
|
|
reside on the filesystem--only the template. To view the generated config file, open it
|
|
in a web browser. If the config file is XML, Firefox should display it. Some browsers
|
|
will require viewing the source of the page requested.
|
|
|
|
A default mime-type for the profile can be defined by setting \textbf{mime-type}. If a
|
|
custom variable is required for a template, it can be specified with \textbf{setvar}.
|
|
Variable substitution on this value is done while building the route list, so
|
|
\$\{USERNAME\} would expand to the username of the users.conf user that registers the
|
|
dynamic filename.
|
|
|
|
NOTE: Any dialplan function that is used for generation of dynamic file names MUST be
|
|
loaded before res\_phoneprov. Add "preload $\Rightarrow$ modulename.so" to
|
|
\path{modules.conf} for required functions. In the example above, "preload $\Rightarrow$
|
|
func\_strings.so" would be required.
|
|
|
|
\section{Configuration of users.conf}
|
|
|
|
The asterisk-gui sets up extensions, SIP/IAX2 peers, and a host of other settings.
|
|
User-specific settings are stored in users.conf. If the asterisk-gui is not being used,
|
|
manual entries to users.conf can be made.
|
|
|
|
\subsection{The [general] section}
|
|
|
|
There are only two settings in the general section of \path{users.conf} that apply to
|
|
phone provisioning: localextenlength which maps to template variable EXTENSION\_LENGTH
|
|
and \textbf{vmexten} which maps to the VOICEMAIL\_EXTEN variable.
|
|
|
|
\subsection{Invdividual Users}
|
|
|
|
To enable auto-provisioning of a phone, the user in \path{users.conf} needs to have:
|
|
|
|
\begin{astlisting}
|
|
\begin{verbatim}
|
|
...
|
|
autoprov=yes
|
|
macaddress=deadbeef4dad
|
|
profile=polycom
|
|
\end{verbatim}
|
|
\end{astlisting}
|
|
|
|
The profile is optional if a \textbf{default\_profile} is set in \path{phoneprov.conf}.
|
|
The following is a sample users.conf entry, with the template variables commented next to
|
|
the settings:
|
|
|
|
\begin{astlisting}
|
|
\begin{verbatim}
|
|
[6001]
|
|
callwaiting = yes
|
|
context = numberplan-custom-1
|
|
hasagent = no
|
|
hasdirectory = yes
|
|
hasiax = no
|
|
hasmanager = no
|
|
hassip = yes
|
|
hasvoicemail = yes
|
|
host = dynamic
|
|
mailbox = 6001
|
|
threewaycalling = yes
|
|
deletevoicemail = no
|
|
autoprov = yes
|
|
profile = polycom
|
|
directmedia = no
|
|
nat = no
|
|
fullname = User Two ; ${DISPLAY_NAME}
|
|
secret = test ; ${SECRET}
|
|
username = 6001 ; ${USERNAME}
|
|
macaddress = deadbeef4dad ; ${MAC}
|
|
label = 6001 ; ${LABEL}
|
|
cid_number = 6001 ; ${CALLERID}
|
|
\end{verbatim}
|
|
\end{astlisting}
|
|
|
|
The variables above, are the user-specfic variables that can be substituted into dynamic
|
|
filenames and config templates.
|
|
|
|
\section{Templates}
|
|
|
|
Configuration templates are a generic way to configure phones with text-based
|
|
configuration files. Templates can use any loaded dialplan function and all of the
|
|
variables created by \path{phoneprov.conf} and \path{users.conf}. A short example is the
|
|
included 000000000000.cfg Polycom template:
|
|
|
|
\begin{astlisting}
|
|
\begin{verbatim}
|
|
<?xml version="1.0" standalone="yes"?>
|
|
<APPLICATION
|
|
APP_FILE_PATH="sip.ld"
|
|
CONFIG_FILES="${IF($[${STAT(e|${CUSTOM_CONFIG})}] ? "custom.cfg,
|
|
")}config/${TOLOWER(${MAC})}, sip.cfg"
|
|
MISC_FILES="" LOG_FILE_DIRECTORY=""
|
|
/>
|
|
\end{verbatim}
|
|
\end{astlisting}
|
|
|
|
This template uses dialplan functions, expressions, and a couple of variables to generate
|
|
a config file to instruct the Polycom where to pull other needed config files. If a phone
|
|
with MAC address 0xDEADBEEF4DAD requests this config file, and the filename that is
|
|
stored in variable CUSTOM\_CONFIG does not exist, then the generated output would be:
|
|
|
|
\begin{astlisting}
|
|
\begin{verbatim}
|
|
<?xml version="1.0" standalone="yes"?>
|
|
<APPLICATION
|
|
APP_FILE_PATH="sip.ld"
|
|
CONFIG_FILES="config/deadbeef4dad, sip.cfg"
|
|
MISC_FILES="" LOG_FILE_DIRECTORY=""
|
|
/>
|
|
\end{verbatim}
|
|
\end{astlisting}
|
|
|
|
The Polycom phone would then download both sip.cfg (which would be registered in
|
|
\path{phoneprov.conf} as a static file) and config/deadbeef4dad (which would be
|
|
registered as a dynamic file pointing to another template, polycom.xml).
|
|
|
|
res\_phoneprov also registers its own dialplan function: PP\_EACH\_USER. This function
|
|
was designed to be able to print out a particular string for each user that
|
|
res\_phoneprov knows about. An example use of this function is the template for a Polycom
|
|
contact directory:
|
|
|
|
\begin{astlisting}
|
|
\begin{verbatim}
|
|
<?xml version="1.0" standalone="yes"?>
|
|
<directory>
|
|
<item_list>
|
|
${PP_EACH_USER(<item><fn>%{DISPLAY_NAME}</fn><ct>%{CALLERID}</ct><bw>1</bw></item>|${MAC})}
|
|
</item_list>
|
|
</directory>
|
|
\end{verbatim}
|
|
\end{astlisting}
|
|
|
|
PP\_EACH\_USER takes two arguments. The first is the string to be printed for each user.
|
|
Any variables that are to be substituted need to be in the format \%\{VARNAME\} so that
|
|
Asterisk doesn't try to substitute the variable immediately before it is passed to
|
|
PP\_EACH\_USER. The second, optional, argument is a MAC address to exclude from the list
|
|
iterated over (so, in this case, a phone won't be listed in its own contact directory).
|
|
|
|
\section{Putting it all together}
|
|
|
|
Make sure that \path{manager.conf} has:
|
|
|
|
\begin{astlisting}
|
|
\begin{verbatim}
|
|
[general]
|
|
enabled = yes
|
|
webenabled = yes
|
|
\end{verbatim}
|
|
\end{astlisting}
|
|
|
|
and that \path{http.conf} has:
|
|
|
|
\begin{astlisting}
|
|
\begin{verbatim}
|
|
[general]
|
|
enabled = yes
|
|
bindaddr = 192.168.1.1 ; Your IP here ;-)
|
|
bindport = 8088 ; Or port 80 if it is the only http server running on the machine
|
|
\end{verbatim}
|
|
\end{astlisting}
|
|
|
|
With \path{phoneprov.conf} and \path{users.conf} in place, start Astersik. From the CLI,
|
|
type "http show status". An example output:
|
|
\begin{astlisting}
|
|
\begin{verbatim}
|
|
HTTP Server Status:
|
|
Prefix: /asterisk
|
|
Server Enabled and Bound to 192.168.1.1:8088
|
|
|
|
Enabled URI's:
|
|
/asterisk/httpstatus => Asterisk HTTP General Status
|
|
/asterisk/phoneprov/... => Asterisk HTTP Phone Provisioning Tool
|
|
/asterisk/manager => HTML Manager Event Interface
|
|
/asterisk/rawman => Raw HTTP Manager Event Interface
|
|
/asterisk/static/... => Asterisk HTTP Static Delivery
|
|
/asterisk/mxml => XML Manager Event Interface
|
|
|
|
Enabled Redirects:
|
|
None.
|
|
|
|
POST mappings:
|
|
None.
|
|
\end{verbatim}
|
|
\end{astlisting}
|
|
|
|
There should be a phoneprov URI listed. Next, from the CLI, type "phoneprov show routes"
|
|
and verify that the information there is correct. An example output for Polycom phones
|
|
woud look like:
|
|
|
|
\begin{astlisting}
|
|
\begin{verbatim}
|
|
Static routes
|
|
|
|
Relative URI Physical location
|
|
sip.ver configs/sip.ver
|
|
sip.ld configs/sip.ld
|
|
bootrom.ver configs/bootrom.ver
|
|
sip.cfg configs/sip.cfg
|
|
bootrom.ld configs/bootrom.ld
|
|
custom.cfg configs/custom.cfg
|
|
|
|
Dynamic routes
|
|
|
|
Relative URI Template
|
|
deadbeef4dad.cfg 000000000000.cfg
|
|
deadbeef4dad-directory.xml 000000000000-directory.xml
|
|
deadbeef4dad-phone.cfg 000000000000-phone.cfg
|
|
config/deadbeef4dad polycom.xml
|
|
\end{verbatim}
|
|
\end{astlisting}
|
|
|
|
With the above examples, the phones would be pointed to
|
|
\url{http://192.168.1.1:8080/asterisk/phoneprov} for pulling config files. Templates
|
|
would all be placed in AST\_DATA\_DIR/phoneprov and static files would be placed in
|
|
AST\_DATA\_DIR/phoneprov/configs. Examples of valid URIs would be:
|
|
|
|
\begin{itemize}
|
|
\item http://192.168.1.1:8080/asterisk/phoneprov/sip.cfg
|
|
\item http://192.168.1.1:8080/asterisk/phoneprov/deadbeef4dad.cfg
|
|
\item http://192.168.1.1:8080/asterisk/phoneprov/config/deadbeef4dad
|
|
\end{itemize}
|
|
|