diff options
Diffstat (limited to 'doc/tex/phoneprov.tex')
| -rw-r--r-- | doc/tex/phoneprov.tex | 307 |
1 files changed, 0 insertions, 307 deletions
diff --git a/doc/tex/phoneprov.tex b/doc/tex/phoneprov.tex deleted file mode 100644 index 790c1d7c2..000000000 --- a/doc/tex/phoneprov.tex +++ /dev/null @@ -1,307 +0,0 @@ -\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 =$>$ -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 =$>$ modulename.so" to -\path{modules.conf} for required functions. In the example above, "preload =$>$ -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} - |