path: root/doc/tex/phoneprov.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
canreinvite = 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}