====== IP Phone Mass Deployment ====== Regardless if your AstLinux system supports only a few SIP phones or 50 or more, the process of coordinating the provisioning of SIP phones and the Asterisk configuration can be a tedious and time consuming process. Described below are tools to assist in the task of mass deployment of SIP phones. The provided templates will most likely require some customization for your installation, but once you have your custom template defined, adding, deleting, and changing phones is a straightforward process. First time users may find this quick overview helpful: **[[userdoc:tt_ip_phoneprov_howto|IP Phone Provisioning Getting Started]]** If you have not already, create the ''/mnt/kd/phoneprov/'' directory. See Below: **[[#ip_phone_provisioning|IP Phone Provisioning]]** !!Warning ->!! When the ''/mnt/kd/phoneprov/'' directory exists, HTTP/HTTPS is served with URL paths beginning with ''/phoneprov/'' . Be sure to consider restricting ''/phoneprov/'' access. See Below: **[[#restricting_provisioning_access|Restricting Provisioning Access]]** ===== Mass Deployment Configuration (GUI) ===== !!Note: AstLinux 1.1.6 or later is required!! Regardless if the web interface (GUI) or command-line interface (CLI) is used for the configuration, the core set of files are the **template** files that contain Asterisk dialplan and SIP configurations, as well as phone specific provisioning data. Example template files are located at ''/stat/etc/phoneprov/templates/*.conf''. The actual template files must be located at ''/mnt/kd/phoneprov/templates/*.conf'' (unless with an alternate path using the ''PHONEPROV_BASE_DIR'' system variable). For the template syntax, see below: **[[#phone_template_syntax|Phone Template Syntax]]** For the sake of this GUI discussion, it is assumed the template files have been customized as required for your installation. Select the PhoneProv Tab in the web interface.\\ {{:userdoc:phoneprov-phoneprov-tab.png?nolink|PhoneProv Tab}} Define your phones starting with it's MAC address in the form: ff:ff:ff:ff:ff:ff {{:userdoc:phoneprov-configure.jpg?nolink|Phone Provisioning}} The Template menu has an entry for every ''*.conf'' file in the ''/mnt/kd/phoneprov/templates/'' directory. The entries and "menu_name" can all be customized. An example Template menu is below: {{:userdoc:phoneprov-template-menu.jpg?nolink|Template Menu}} Use the "Gateway Interface:" option to specify which interface the phones are connected to. (This defines the ''PHONEPROV_GW_IF'' system variable.) After all your phones have been defined, or after any changes, you can generate all the related output files via the template(s) and phone configuration data by clicking **Generate Files**: {{:userdoc:phoneprov-generate.png?nolink|Generate Files}} Additionally, if you want to also reload the Asterisk dialplan and SIP configurations, check the "Reload Dialplan/SIP" option: {{:userdoc:phoneprov-generate-reload.png?nolink|Generate Files and Reload}} !!Note ->!! **Generate Files** may take a few, to many seconds to complete, so be patient. !!Tip ->!! A text file backup of the most recent **Generate Files** configuration file is saved at ''/mnt/kd/webgui-massdeployment.conf'' . The Prefs Tab has an option to control how many Extension / CID Name(s) are displayed, a value of 1 to 6, the default is 2: {{:userdoc:phoneprov-prefs-options.png?nolink|PhoneProv Prefs Options}} ===== Mass Deployment Configuration (CLI) ===== !!Note: AstLinux 1.1.6 or later is required!! For reference the files in the ''/stat/etc/phoneprov/'' directory can be used as examples. If you wish you can copy all these files into the ''/mnt/kd/phoneprov/'' directory with the command: cp -a /stat/etc/phoneprov/* /mnt/kd/phoneprov/ Of course only do this once, as you will be customizing the ''/mnt/kd/phoneprov/massdeployment.conf'' and ''/mnt/kd/phoneprov/templates/*.conf'' files (unless with an alternate path using the ''PHONEPROV_BASE_DIR'' system variable). The ''massdeployment.conf'' file is where your phones will be defined, one per line as per the comments in that file. As usual, comments are lines beginning with the "''#''" character. !!Tip ->!! The ''massdeployment.conf'' file is not required to be located at any specific location. You may want to use ''/mnt/kd/massdeployment.conf'' so a basic backup and restore would apply. Additionally, using ''/mnt/kd/massdeployment.conf'' will keep the file from being accessed via HTTP/HTTPS in the ''/phoneprov/'' directory. Example ''massdeployment.conf'' file entries are: ## Format: ## template mac_addr extension[/CID_Name][;ext2[/cid2];...] password [ account ] ## snom320 00:04:13:11:33:21 201 secret yealink 00:15:65:22:44:12 301/Front_Desk supersecret yealink_4412_301 yealink-2line 00:15:65:22:44:23 210/Office;310/Help_Line superdupersecret The ''/mnt/kd/phoneprov/templates/*.conf'' files are used to generate the output files. Note that the left-most entries of the ''massdeployment.conf'' file define the "''template''" which then refers to which "''template.conf''" file in the ''templates'' directory that is used to generate files for that phone and extension. For the template syntax, see below: **[[#phone_template_syntax|Phone Template Syntax]]** The CLI ''phoneprov-massdeployment'' command: Usage: phoneprov-massdeployment [options...] in_file Options: -a, --auto-pass Automatically generate missing password(s) -A, --only-pass Same as "-a, --auto-pass" without further processing -f, --force-overwrite Overwrite existing files -h, --help Show this help text -i, --if-name Interface Name: INTIF, INT2IF, INT3IF, EXTIF, ethN, brN Defaults to config variable PHONEPROV_GW_IF -p, --partial Partial input, append "dialplan" and "sip" entries to existing -r, --auto-reload Automatically reload Asterisk "dialplan" and "sip" on success -R, --only-reload Same as "-r, --auto-reload" without further processing Example ''massdeployment.conf'', using ''snom320.conf'' and ''yealink.conf'' templates: ## Format: ## template mac_addr extension[/CID_Name][;ext2[/cid2];...] password [ account ] ## snom320 00:04:13:11:33:21 201 yealink 00:15:65:22:44:12 301/Front_Desk Note the required SIP passwords are missing, the ''-A'' option will automatically add them: # phoneprov-massdeployment -A massdeployment.conf Auto-generating password(s): Missing password(s) were added to input file. Now ''massdeployment.conf'' contains all the required passwords: ## Format: ## template mac_addr extension[/CID_Name][;ext2[/cid2];...] password [ account ] ## snom320 00:04:13:11:33:21 201 2uAHicirH0avgJAA yealink 00:15:65:22:44:12 301/Front_Desk nxQWqPrRf2vRFIIy Of course you can also manually define your own SIP passwords. Finally, generate the output provisioning files: # phoneprov-massdeployment -i INT2IF massdeployment.conf Generating Phone Provisioning files: ..Done !!Note ->!! If any of the output files exist, the ''-f'' option will be required to overwrite any files. The ''INT2IF'' interface name represents the 2nd LAN Interface, the network the phones are connected to, adjust for your configuration. Alternatively, setting the config variable, PHONEPROV_GW_IF="INT2IF" will define the default phoneprov gateway interface to INT2IF. ===== Phone Template Syntax ===== The phone template is a single file per phone type that contains Asterisk dialplan and SIP configurations, as well as phone specific provisioning data. The ''/mnt/kd/phoneprov/templates/*.conf'' files are used to generate the output files. Note that the left-most entries of the ''massdeployment.conf'' file define the "''template''" which then refers to which "''template.conf''" file in the ''templates'' directory that is used to generate files for that phone and extension. ^ Template Syntax, lines beginning with: ^^ | ''#'' | Specify a comment | | ''[...]'' | Specify a context of type: [general], [dialplan], [sip], [pjsip] or [phoneprov] | | ''\#'' | not a comment, a literal '#' | | ''\['' | not a context, a literal '[' | | ''#text'' | '#' is deleted for matching extension 'ext', resulting in 'text', \\ otherwise treated as a comment | | ''#text'' | '#' is deleted for non-matching extension 'ext', resulting in 'text', \\ otherwise treated as a comment. Multiple extensions may be \\ separated by a ! character, example: '#text' | A template definition must contain a [general] context and optionally any or all of [dialplan], [sip], [phoneprov] contexts. ^ The [general] context may contain any of the following variable definitions: ^^ | ''macaddress_case='' | Either 'upper' or 'lower' which defines ''@MAC@'' | | ''model='' | Defines ''@MODEL@'', defaults to ''@TEMPLATE@'' | | ''vendor='' | Defines ''@VENDOR@'', defaults to ''@MODEL@'' | | ''auto_account_prefix='' | Defines prefix for auto-generated ''@ACCOUNT@'' names | | ''auto_account_suffix='' | Defines suffix for auto-generated ''@ACCOUNT@'' names | | ''auto_account_case='' | Either 'upper' or 'lower' which qualifies auto-generated ''@ACCOUNT@'' names | | ''prov_path='' | Generated provisioning file location, defaults to ''/mnt/kd/phoneprov/@VENDOR@'' | | ''prov_file='' | Generated provisioning file name, defaults to ''@MAC@.cfg'' | | ''dialplan_path='' | Generated dialplan file location, defaults to ''/mnt/kd/asterisk/includes'' | | ''dialplan_file='' | Generated dialplan file name, defaults to ''astlinux-phoneprov-exten.conf'' | | ''dialplan_context='' | Optional Asterisk dialplan context, defaults to no Asterisk context added | | ''sip_path='' | Generated sip file location, defaults to ''/mnt/kd/asterisk/includes'' | | ''sip_file='' | Generated sip file name, defaults to ''astlinux-phoneprov-sip.conf'' | | ''pjsip_path='' | Generated pjsip file location, defaults to ''/mnt/kd/asterisk/includes'' | | ''pjsip_file='' | Generated pjsip file name, defaults to ''astlinux-phoneprov-pjsip.conf'' | | ''sql_enable='' | Either 'yes' or 'no' to automatically create 'phoneprov' SQLite3 table, defaults to ''yes'' | | ''sip_driver='' | Either 'sip' or 'pjsip' to define a column in 'phoneprov' SQLite3 table, defaults to ''sip'' | ^ The [general] context advanced user variable definitions: ^^ | ''dialplan2-6_file='' | Generated dialplan2-6 file name, defaults to ''astlinux-phoneprov-exten2-6.conf'' \\ Requires any of [dialplan2], [dialplan3], ... [dialplan6] context(s) to be defined | | ''dialplan2-6_context='' | Optional Asterisk dialplan2-6 context, defaults to no Asterisk context added \\ Requires any of [dialplan2], [dialplan3], ... [dialplan6] context(s) to be defined | ^ The "global" section (before contexts) may contain the following variable definition: ^^ | ''menu_name='' | Used by the PhoneProv tab in the web interface, Template menu description | The template context's can use the following special variables that get merged for each phone definition. ^ Merged Template variables: ^^ | ''@TEMPLATE@'' | Template name, as defined in ''massdeployment.conf'', using ''@TEMPLATE@.conf'' template file | | ''@MODEL@'' | Phone model, as defined in the template file. | | ''@VENDOR@'' | Phone vendor, as defined in the template file. | | ''@MAC_ADDR@'' | MAC address in ''00:11:22:33:44:55'' format as defined in ''massdeployment.conf'' | | ''@MAC@'' | MAC address without colons and upper or lower case per the ''macaddress_case='' setting | | ''@MAC4@'' | The last 4 digits of ''@MAC@'' | | ''@MAC6@'' | The last 6 digits of ''@MAC@'' | | ''@EXT@'' | Extension as defined in ''massdeployment.conf'' | | ''@CID_NAME@'' | CallerID name optionally defined in ''massdeployment.conf'', defaults to ''@EXT@'' | | ''@CID_NUM@'' | CallerID num optionally defined in ''massdeployment.conf'' as a '''' suffix in ''@CID_NAME@'', defaults to ''@EXT@'' (e.g. ''201/Alice_DECT<101>'') | | ''@PASSWORD@'' | SIP password as defined in ''massdeployment.conf'' | | ''@ACCOUNT@'' | SIP account as defined in ''massdeployment.conf'' or auto-generated | | ''@USERNAME@'' | Synonym for ''@ACCOUNT@'' | | ''@SIP_SERVER_IPV4@'' | The AstLinux IPv4 address determined from the command line ''-i'' interface, \\ the interface defaults to the ''PHONEPROV_GW_IF'' system config variable | | ''@EXT1-6@'' | ''@EXT1@'' matches ''@EXT@'' above, ''@EXT2@'' to ''@EXT6@'' are defined using a \\ semi-colon delimited extension/cid_name in ''massdeployment.conf'' | | ''@CID_NAME1-6@'' | ''@CID_NAME1@'' matches ''@CID_NAME@'' above, ''@CID_NAME2@'' to ''@CID_NAME6@'' are defined using a \\ semi-colon delimited extension/cid_name in ''massdeployment.conf'' | | ''@CID_NUM1-6@'' | ''@CID_NUM1@'' matches ''@CID_NUM@'' above, ''@CID_NUM2@'' to ''@CID_NUM6@'' are defined using a \\ '''' suffix in ''@CID_NAME@'' in ''massdeployment.conf'' | | ''@PASSWORD1-6@'' | ''@PASSWORD1@'' matches ''@PASSWORD@'' above, ''@PASSWORD2@'' to ''@PASSWORD6@'' default to ''@PASSWORD@'' \\ or are defined using a semi-colon delimited password in ''massdeployment.conf'' | | ''@ACCOUNT1-6@'' | ''@ACCOUNT1@'' matches ''@ACCOUNT@'' above, ''@ACCOUNT2@'' to ''@ACCOUNT6@'' default to auto-generated \\ or are defined using a semi-colon delimited account in ''massdeployment.conf'' | | ''@USERNAME1-6@'' | Synonym for ''@ACCOUNT1-6@'' | !!Note ->!! The optional CID_Name in ''massdeployment.conf'' must NOT contain quotes or spaces, use underscores "_", they will be mapped to spaces. !!Note ->!! For the optional CID_NUM variable(s) !!AstLinux 1.4.3 or later!! is required. It let's you override the ''CALLERID(num)'' independant from the extension with a '''' suffix in ''CID_NAME'' and it stored in the SQL database as ''cid_num''. !!Note ->!! Auto-generated account names, with optional ''auto_account_case'' case, result in the format: auto_account_prefix + extension(1-6) + auto_account_suffix \\ The concept of defining the [dialplan], [sip] and [phoneprov] contexts is quite simple. The simplest example is for the dialplan: # Dialplan File entries [dialplan] exten => @EXT@,1,Dial(SIP/@ACCOUNT@) As each phone definition is processed the above template has ''@EXT@'' and ''@ACCOUNT@'' merged and appended to your chosen ''dialplan_file'' setting. The same idea applies to the [sip] and [phoneprov] contexts. Note that the [dialplan] and [sip] contexts are sequentially appended to their respective files, while the [phoneprov] context creates a standalone file. So basically, you probably already have the data sitting around to define a custom template, simply replace some of the key data fields with the special merge variables above. !!Tip ->!! Many phone models support provisioning both via a global phoneprov file (ex. MAC is 000000000000) and a MAC specific phoneprov file. Generally in that situation the [phoneprov] context would only generate an extension specific, partial configuration counting on the manually generated global phoneprov file for the remainder. Of course the MAC specific phoneprov file could contain the global and extension specific configuration all in the [phoneprov] context if desired. !!Advanced ->!! The use of the additional [dialplan2-6] contexts can be useful to auto-generate BLF hints, FOP2 ''buttons.cfg'', etc. . Following is a simple example of an Asterisk context ''provisioned-blf'' in a separate file containing 'hints': [general] ... dialplan2_file=astlinux-phoneprov-exten-hints.conf dialplan2_context=provisioned-blf ... [dialplan2] exten => @EXT@,hint,SIP/@ACCOUNT@ ===== Reload Action Script (optional) ===== !!Note: AstLinux 1.2.2 or later is required!! The optional "''/mnt/kd/phoneprov-reload.script''" action script will be called when "Reload Dialplan/SIP" is checked. By default, when "''/mnt/kd/phoneprov-reload.script''" does not exist, and when "Reload Dialplan/SIP" is checked, the following commands are executed: asterisk -rx "dialplan reload" >/dev/null asterisk -rx "sip reload" >/dev/null You can customize these actions by creating a "''/mnt/kd/phoneprov-reload.script''" script. For example the following script will replicate the default action: #!/bin/sh asterisk -rx "dialplan reload" >/dev/null asterisk -rx "sip reload" >/dev/null If you require reloading ''fop2'' or pjsip related asterisk modules, you can do that with this custom script. !!Note ->!! Be sure to make your "''/mnt/kd/phoneprov-reload.script''" executable using the ''chmod'' command via the CLI. ===== IP Phone Provisioning ===== !!Note: AstLinux 1.0.3 or later is required!! Most modern IP Phones allow automatic provisioning from a central location. Described here are AstLinux features and configuration tips to provision phones. Create the ''/mnt/kd/phoneprov/'' directory. After a reboot, both HTTP and HTTPS will be served from that directory provided the URL directory path begins with ''/phoneprov/''. This directory is not effected by the root directory of the general HTTP/HTTPS server configuration, which is independent, though the listing and logging options also apply to ''/phoneprov/''. Next, edit the ''/mnt/kd/dnsmasq.static'' file to utilize DHCP to instruct the phone where the provisioning files are located. The following examples show how the vendor ID from the MAC address can be matched to locate provisioning files organized by vendor.\\ //(Change ''pbx'' in the examples to your AstLinux hostname or IP address.)// # SNOM https provisioning dhcp-mac=set:snom,00:04:13:*:*:* #dhcp-option=tag:snom,option:tftp-server,"https://pbx/phoneprov/snom/snom-{mac}.xml" dhcp-option=tag:snom,option:tftp-server,"https://pbx/phoneprov/snom/" !!Note ->!! Above, in the first (commented - https) snom example the phones look only for "snom-{mac}.xml" files, in the next (uncommented - https) example for a global "snom320.htm" and a MAC-specific "snom320-{mac}.htm" file. # Yealink https provisioning dhcp-mac=set:yealink,00:15:65:*:*:* dhcp-option=tag:yealink,option:tftp-server,"https://pbx/phoneprov/yealink/" Restart **DNS & DHCP** (dnsmasq) and reboot the IP Phone to apply any ''/mnt/kd/dnsmasq.static'' file changes. !!Tip ->!! If your IP Phone does not support the DHCP "option-66" (tftp-server) feature, you must manually define the provisioning URL in the phone's web interface. Some vendors like Cisco are using additional custom DHCP options like 159 + 160. !!Tip ->!! If you need to use a different DHCP server (tested with a Windows Server 2008R2), you could also try to test DHCP option 60 (Vendor Class Identifier - sent by the phone (e.g. ''snom300'' or ''yealink'')) and option 43 (sent by the server) which can encapsulate the option 66 setting. The phones must be able to send option 60 and understand option 43 though (tested with Snom 300 phones with newer firmware and Yealink phones!).\\ [[http://www.ingmarverheij.com/microsoft-vendor-specific-dhcp-options-explained-and-demystified/|Link]] ((Windows-only program to encapsulate the string => at the bottom of the page)), e.g. [[http://wiki.snom.com/Features/Auto_Provisioning/DHCP/Options|Snom options]] !!Tip ->!! If your IP Phone does not support HTTP/HTTPS provisioning, TFTP may be used by placing the provisioning files in the ''/mnt/kd/tftpboot/'' directory. In this case sub-directories within ''tftpboot'' like with HTTP mostly don't work!. ===== Restricting Provisioning Access ===== !!Note: AstLinux 1.0.6 or later is required!! The IP Phone provisioning data can contain access credentials, such that the average user on the LAN should not have access to. Using the firewall to restrict this access is not practical since both HTTP and HTTPS is supported for ''/phoneprov/'' and access to parts of the web interface by LAN users using the same services is often desired. The solution is to restrict access via the web server itself for only the ''/phoneprov/'' access. Using the **Network** tab in the web interface... **Network** -> Network Services: {{:userdoc:tt_ip_phone_provisioning1.png?nolink|Network Tab}} In the above example only the IP addresses that begin with ''10.10.50.'' with a wildcard ''*'' match for the remainder, will have access to ''/phoneprov/'' . Note the matching is performed via a regular expression, not CIDR syntax, so 10.10.50.0/24 will not work in this case. The default is to allow all IP's with no Allowed IP's specified. Another Example: ''10.1.2.* 2001:db8:1:* 192.168.101.20'' Showing both IPv4 and IPv6 address are supported, as well as single IP addresses, each separated by a space character.