Added a new module, res_phoneprov, which allows auto-provisioning of phones

based on configuration templates that use Asterisk dialplan function and
variable substitution.  It should be possible to create phone profiles and
templates that work for the majority of phones provisioned over http. It
is currently only intended to provision a single user account per phone.
An example profile and set of templates for Polycom phones is provided.
NOTE: Polycom firmware is not included, but should be placed in
AST_DATA_DIR/phoneprov/configs to match up with the included templates.



git-svn-id: http://svn.digium.com/svn/asterisk/trunk@97634 f38db490-d61c-443f-a65b-d21fe96a405b

2 files changed, 305 insertions, 1 deletions

diff --git a/doc/tex/asterisk.tex b/doc/tex/asterisk.tex
index ca0a0dc6b..0feb3d7d9 100644
--- a/doc/tex/asterisk.tex
+++ b/doc/tex/asterisk.tex
@@ -32,7 +32,7 @@
 
 
 \author{Asterisk Development Team \\ Asterisk.org}
-\title{Asterisk Reference Information \\ Version ASTERISKVERSION}
+\title{Asterisk Reference Information \\ Version }
 
 \begin{document}
 \maketitle
@@ -132,6 +132,9 @@ reference purposes.
   \section{Queue Logs}
   \input{queuelog.tex}
 
+\chapter{Phone Provisioning}
+  \input{phoneprov.tex}
+
 \chapter{Development}
   \section{Backtrace}
   \input{backtrace.tex}
diff --git a/doc/tex/phoneprov.tex b/doc/tex/phoneprov.tex
new file mode 100644
index 000000000..d813a7f45
--- /dev/null
+++ b/doc/tex/phoneprov.tex
@@ -0,0 +1,301 @@
+\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}
+
+There are two choices for setting 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 SERVER\_PORT variable is set by setting the \textbf{serverport}.  If 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}
+