Added a new module, res_phoneprov, which allows auto-provisioning of phones
[asterisk/asterisk.git] / doc / tex / phoneprov.tex
1 \section{Introduction}
2
3 Asterisk includes basic phone provisioning support through the res\_phoneprov module. The 
4 current implementation is based on a templating system using Asterisk dialplan function 
5 and variable substitution and obtains information to substitute into those templates from 
6 \path{phoneprov.conf} and \path{users.conf}.  A profile and set of templates is provided 
7 for provisioning Polycom phones. Note that res\_phoneprov is currently limited to 
8 provisioning a single user per device.
9
10 \section{Configuration of phoneprov.conf}
11
12 The configuration file, \path{phoneprov.conf}, is used to set up the built-in variables 
13 SEVER and SERVER\_PORT, to define a default phone profile to use, and to define different 
14 phone profiles available for provisioning.
15
16 \subsection{The [general] section}
17
18 Below is a sample of the general section of \path{phoneprov.conf}:
19
20 \begin{astlisting}
21 \begin{verbatim}
22 [general]
23 ;serveriface=eth0
24 serveraddr=192.168.1.1
25 serverport=5060
26 default_profile=polycom
27 \end{verbatim}
28 \end{astlisting}
29
30 There are two choices for setting the SERVER variable. If the IP address of the server is 
31 known, or the hostname resolvable by the phones, the appropriate \textbf{serveraddr} 
32 value should be set.  Alternatively, the network interface that the server listens on can 
33 be set by specifying a \textbf{serveriface} and SERVER will be set to the IP address of 
34 that interface.  Only one of these options should be set.
35
36 The SERVER\_PORT variable is set by setting the \textbf{serverport}.  If serverport is 
37 not specified, it is set to a default value of 5060.
38
39 Any user set for auto-provisioning in users.conf without a specified profile will be 
40 assumed to belong to the profile set with \textbf{default\_profile}.
41
42 \subsection{Creating phone profiles}
43
44 A phone profile is basically a list of files that a particular group of phones needs to 
45 function.  For most phone types there are files that are identical for all phones 
46 (firmware, for instance) as well as a configuration file that is specific to individual 
47 phones.  res\_phoneprov breaks these two groups of files into static files and dynamic 
48 files, respectively. A sample profile:
49
50 \begin{astlisting}
51 \begin{verbatim}
52 [polycom]
53 staticdir => configs/
54 mime_type => text/xml
55 setvar => CUSTOM_CONFIG=/var/lib/asterisk/phoneprov/configs/custom.cfg
56 static_file => bootrom.ld,application/octet-stream
57 static_file => bootrom.ver,plain/text
58 static_file => sip.ld,application/octet-stream
59 static_file => sip.ver,plain/text
60 static_file => sip.cfg
61 static_file => custom.cfg
62 ${TOLOWER(${MAC})}.cfg => 000000000000.cfg
63 ${TOLOWER(${MAC})}-phone.cfg => 000000000000-phone.cfg
64 config/${TOLOWER(${MAC})} => polycom.xml
65 ${TOLOWER(${MAC})}-directory.xml => 000000000000-directory.xml
66 \end{verbatim}
67 \end{astlisting}
68
69 A \textbf{static\_file} is set by specifying the file name, relative to 
70 \path{AST\_DATA\_DIR/phoneprov}.  The mime-type of the file can optionally be specified 
71 after a comma.  If \textbf{staticdir} is set, all static files will be relative to the 
72 subdirectory of AST\_DATA\_DIR/phoneprov specified.
73
74 Since phone-specific config files generally have file names based on phone-specifc data, 
75 dynamic filenames in res\_phoneprov can be defined with Asterisk dialplan function and 
76 variable substitution. In the above example, \$\{TOLOWER(\$\{MAC\})\}.cfg $\Rightarrow$ 
77 000000000000.cfg would define a relative URI to be served that matches the format of 
78 MACADDRESS.cfg, all lower case. A request for that file would then point to the template 
79 found at AST\_DATA\_DIR/phoneprov/000000000000.cfg. The template can be followed by a 
80 comma and mime-type. Notice that the dynamic filename (URI) can contain contain 
81 directories. Since these files are dynamically generated, the config file itself does not 
82 reside on the filesystem--only the template. To view the generated config file, open it 
83 in a web browser. If the config file is XML, Firefox should display it. Some browsers 
84 will require viewing the source of the page requested.
85
86 A default mime-type for the profile can be defined by setting \textbf{mime-type}.  If a 
87 custom variable is required for a template, it can be specified with \textbf{setvar}. 
88 Variable substitution on this value is done while building the route list, so 
89 \$\{USERNAME\} would expand to the username of the users.conf user that registers the 
90 dynamic filename.
91
92 NOTE: Any dialplan function that is used for generation of dynamic file names MUST be 
93 loaded before res\_phoneprov. Add "preload $\Rightarrow$ modulename.so" to 
94 \path{modules.conf} for required functions. In the example above, "preload $\Rightarrow$ 
95 func\_strings.so" would be required.
96
97 \section{Configuration of users.conf}
98
99 The asterisk-gui sets up extensions, SIP/IAX2 peers, and a host of other settings. 
100 User-specific settings are stored in users.conf. If the asterisk-gui is not being used, 
101 manual entries to users.conf can be made.
102
103 \subsection{The [general] section}
104
105 There are only two settings in the general section of \path{users.conf} that apply to 
106 phone provisioning: localextenlength which maps to template variable EXTENSION\_LENGTH 
107 and \textbf{vmexten} which maps to the VOICEMAIL\_EXTEN variable.
108
109 \subsection{Invdividual Users}
110
111 To enable auto-provisioning of a phone, the user in \path{users.conf} needs to have:
112
113 \begin{astlisting}
114 \begin{verbatim}
115 ...
116 autoprov=yes
117 macaddress=deadbeef4dad
118 profile=polycom
119 \end{verbatim}
120 \end{astlisting}
121
122 The profile is optional if a \textbf{default\_profile} is set in \path{phoneprov.conf}. 
123 The following is a sample users.conf entry, with the template variables commented next to 
124 the settings:
125
126 \begin{astlisting}
127 \begin{verbatim}
128 [6001]
129 callwaiting = yes
130 context = numberplan-custom-1
131 hasagent = no
132 hasdirectory = yes
133 hasiax = no
134 hasmanager = no
135 hassip = yes
136 hasvoicemail = yes
137 host = dynamic
138 mailbox = 6001
139 threewaycalling = yes
140 deletevoicemail = no
141 autoprov = yes
142 profile = polycom
143 canreinvite = no
144 nat = no
145 fullname = User Two ; ${DISPLAY_NAME}
146 secret = test ; ${SECRET}
147 username = 6001 ; ${USERNAME}
148 macaddress = deadbeef4dad ; ${MAC}
149 label = 6001 ; ${LABEL}
150 cid_number = 6001 ; ${CALLERID}
151 \end{verbatim}
152 \end{astlisting}
153
154 The variables above, are the user-specfic variables that can be substituted into dynamic 
155 filenames and config templates.
156
157 \section{Templates}
158
159 Configuration templates are a generic way to configure phones with text-based 
160 configuration files. Templates can use any loaded dialplan function and all of the 
161 variables created by \path{phoneprov.conf} and \path{users.conf}. A short example is the 
162 included 000000000000.cfg Polycom template:
163
164 \begin{astlisting}
165 \begin{verbatim}
166 <?xml version="1.0" standalone="yes"?>
167   <APPLICATION 
168     APP_FILE_PATH="sip.ld"
169     CONFIG_FILES="${IF($[${STAT(e|${CUSTOM_CONFIG})}] ? "custom.cfg, 
170 ")}config/${TOLOWER(${MAC})}, sip.cfg"
171     MISC_FILES="" LOG_FILE_DIRECTORY=""
172   />
173 \end{verbatim}
174 \end{astlisting}
175
176 This template uses dialplan functions, expressions, and a couple of variables to generate 
177 a config file to instruct the Polycom where to pull other needed config files. If a phone 
178 with MAC address 0xDEADBEEF4DAD requests this config file, and the filename that is 
179 stored in variable CUSTOM\_CONFIG does not exist, then the generated output would be:
180
181 \begin{astlisting}
182 \begin{verbatim}
183 <?xml version="1.0" standalone="yes"?>
184   <APPLICATION
185     APP_FILE_PATH="sip.ld"
186     CONFIG_FILES="config/deadbeef4dad, sip.cfg"
187     MISC_FILES="" LOG_FILE_DIRECTORY=""
188   />
189 \end{verbatim}
190 \end{astlisting}
191
192 The Polycom phone would then download both sip.cfg (which would be registered in 
193 \path{phoneprov.conf} as a static file) and config/deadbeef4dad (which would be 
194 registered as a dynamic file pointing to another template, polycom.xml). 
195
196 res\_phoneprov also registers its own dialplan function: PP\_EACH\_USER. This function 
197 was designed to be able to print out a particular string for each user that 
198 res\_phoneprov knows about. An example use of this function is the template for a Polycom 
199 contact directory:
200
201 \begin{astlisting}
202 \begin{verbatim}
203 <?xml version="1.0" standalone="yes"?>
204 <directory>
205   <item_list>
206     ${PP_EACH_USER(<item><fn>%{DISPLAY_NAME}</fn><ct>%{CALLERID}</ct><bw>1</bw></item>|${MAC})}
207   </item_list>
208 </directory>
209 \end{verbatim}
210 \end{astlisting}
211
212 PP\_EACH\_USER takes two arguments.  The first is the string to be printed for each user. 
213 Any variables that are to be substituted need to be in the format \%\{VARNAME\} so that
214 Asterisk doesn't try to substitute the variable immediately before it is passed to
215 PP\_EACH\_USER. The second, optional, argument is a MAC address to exclude from the list 
216 iterated over (so, in this case, a phone won't be listed in its own contact directory).
217
218 \section{Putting it all together}
219
220 Make sure that \path{manager.conf} has:
221
222 \begin{astlisting}
223 \begin{verbatim}
224 [general]
225 enabled = yes
226 webenabled = yes
227 \end{verbatim}
228 \end{astlisting}
229
230 and that \path{http.conf} has:
231
232 \begin{astlisting}
233 \begin{verbatim}
234 [general]
235 enabled = yes
236 bindaddr = 192.168.1.1 ; Your IP here ;-)
237 bindport = 8088 ; Or port 80 if it is the only http server running on the machine
238 \end{verbatim}
239 \end{astlisting}
240
241 With \path{phoneprov.conf} and \path{users.conf} in place, start Astersik. From the CLI, 
242 type "http show status". An example output:
243 \begin{astlisting}
244 \begin{verbatim}
245 HTTP Server Status:
246 Prefix: /asterisk
247 Server Enabled and Bound to 192.168.1.1:8088
248
249 Enabled URI's:
250 /asterisk/httpstatus => Asterisk HTTP General Status
251 /asterisk/phoneprov/... => Asterisk HTTP Phone Provisioning Tool
252 /asterisk/manager => HTML Manager Event Interface
253 /asterisk/rawman => Raw HTTP Manager Event Interface
254 /asterisk/static/... => Asterisk HTTP Static Delivery
255 /asterisk/mxml => XML Manager Event Interface
256
257 Enabled Redirects:
258   None.
259
260 POST mappings:
261 None.
262 \end{verbatim}
263 \end{astlisting}
264
265 There should be a phoneprov URI listed. Next, from the CLI, type "phoneprov show routes" 
266 and verify that the information there is correct. An example output for Polycom phones 
267 woud look like:
268
269 \begin{astlisting}
270 \begin{verbatim}
271 Static routes
272
273 Relative URI                              Physical location             
274 sip.ver                                   configs/sip.ver               
275 sip.ld                                    configs/sip.ld                
276 bootrom.ver                               configs/bootrom.ver           
277 sip.cfg                                   configs/sip.cfg               
278 bootrom.ld                                configs/bootrom.ld            
279 custom.cfg                                configs/custom.cfg            
280
281 Dynamic routes
282
283 Relative URI                              Template                      
284 deadbeef4dad.cfg                          000000000000.cfg              
285 deadbeef4dad-directory.xml                000000000000-directory.xml    
286 deadbeef4dad-phone.cfg                    000000000000-phone.cfg        
287 config/deadbeef4dad                       polycom.xml                   
288 \end{verbatim}
289 \end{astlisting}
290
291 With the above examples, the phones would be pointed to 
292 \url{http://192.168.1.1:8080/asterisk/phoneprov} for pulling config files. Templates 
293 would all be placed in AST\_DATA\_DIR/phoneprov and static files would be placed in 
294 AST\_DATA\_DIR/phoneprov/configs. Examples of valid URIs would be:
295
296 \begin{itemize}
297 \item http://192.168.1.1:8080/asterisk/phoneprov/sip.cfg
298 \item http://192.168.1.1:8080/asterisk/phoneprov/deadbeef4dad.cfg
299 \item http://192.168.1.1:8080/asterisk/phoneprov/config/deadbeef4dad
300 \end{itemize}
301