Auto-Provisioning Mediatrix units May 31, 2011 Proprietary 2011 Media5 Corporation
Table of Contents Introduction... 3 Application Scenario... 3 Overview of the Server Configuration... 4 Preparing Windows Web Server (IIS) for Auto-Provisioning... 4 Preparing the Pumpkin TFTP Server for Auto-Provisioning... 4 Example... 5 Configuration Scripts... 6 Creating a Configuration Script... 6 Encryption... 7 Preparation of the Configuration Files and Firmware... 8 Firmware... 8 Configuration of the Mediatrix Unit... 8 Configuration Script Fetching using the Administration Web Page (Method 1)... 9 How to Automatically Configure your Mediatrix Units (Method 4)... 10 DHCP Configuration... 10 Page 2 of 11
Introduction This configuration describes how to use the Mediatrix units functionality that allows it to fetch the firmware and configuration files automatically from a provisioning server by using FTP, TFTP, HTTP or HTTPS. This Configuration Notes can be used to configure the Mediatrix 4100 series, Mediatrix 4400 series and Mediatrix 3000 series (DGW v2.0). Application Scenario This Configuration Note refers to the following scenario as an example throughout the document. New Firmware New Config. Script IP Server Mediatrix 4102 Figure 1. Network Diagram This document covers: Overview of the server setup Configuration required on the Mediatrix unit Preparation of the configuration files and firmware How to automatically configure your Mediatrix units Page 3 of 11
Overview of the Server Configuration Preparing Windows Web Server (IIS) for Auto-Provisioning If you are using Windows, ensure that the HTTP Server functionality is activated and that the configuration files and binaries are located under (default location): C:\Inetpub\wwwroot Media5 recommends that the administrator creates a subdirectory for the firmware and another subdirectory for the configuration files under the Web Server root directory: For example: Configuration files are located under the C:\Inetpub\wwwroot\Mediatrix_ConfigFiles folder. Firmware files and folders are located under the C:\Inetpub\wwwroot\Mediatrix_Firmware folder. Preparing the Pumpkin TFTP Server for Auto-Provisioning If you are using the Pumpkin TFTP server, ensure that it allows proper permission. For the PumpKIN TFTP server, please make sure that the options are selected as shown in the figure below. In the figure, the PumpKIN TFTP Server root directory is C:\PumpKIN. The TFTP root directory is where the firmware and configuration folders and binaries will be located. Media5 recommends that the administrator creates a subdirectory for the firmware and another subdirectory for the configuration files under TFTP root. For example: Configuration files are located under C:\PumpKIN\Mediatrix_ConfigFiles Firmware files and folders are located under C:\PumpKIN\Mediatrix_Firmware Page 4 of 11
Example For the example scenario, here is what each folder would look like: <TFTP or Web root>\mediatrix_configfiles Configuration Notes 275 <TFTP or Web root>\mediatrix_firmware The use of each files and folders are explained later in this document. Page 5 of 11
Configuration Scripts Generic and Specific Configuration Scripts download IP Server Request Generic and Specific Configuration Scripts Mediatrix 4102 The auto-provisioning feature on the Mediatrix units can fetch two types of files: Generic configuration script Specific configuration script The Generic configuration script contains parameters that can be applied to all Mediatrix units in the field. For example, generic parameters such as SIP Proxy server address or voice codec can be specified in this file. This means that all Mediatrix units in the field will point to the same SIP Proxy Server and use the same codec. The Specific configuration script contains parameters that are specific to each Mediatrix unit. For example, specific parameters are SIP username and SIP authentication parameters. To add flexibility, Media5 created macros that allow the Mediatrix units to fetch the generic and specific script using its MAC address (%mac%), its product name (%product%), its product series (%productseries%) or its version (%version%) as filename. For example: For a Mediatrix 4102 with MAC address 0090F8XXXXXX: The Mediatrix unit could be configured to fetch a generic script called %product%.cfg. The generic configuration script on the server would be named Mediatrix 4102.cfg. The Mediatrix unit could be configured to fetch a specific script called: %mac%.cfg. The specific configuration script on the server would be named 0090F8XXXXXX.cfg. Creating a Configuration Script A configuration script that can be used with the auto-provisioning feature can be generated by using the unit s configuration web page. Before proceeding to the steps below, you can manually configure your unit to the desired configuration to export a script that would reproduce the current unit s configuration. 1. Once you have gained access to the administration web page, access the Management Section. 2. In the Configuration Scripts sub section, locate the Export Script section. 3. Select if you want to export the entire configuration or only the modified configuration in the Content dropdown list. 4. Click the (download) link and save the configuration script. Configuration scripts share the same syntax, variables and command as the command-line interface (CLI). Please refer to the DGW v2.0 Configuration Reference document included with your DGW v2.0 documentation for more information on the script language and available variables and commands. Page 6 of 11
Encryption Mediatrix 4102 SIP IP Codecs MIBs 0110101 1001001 011001 Server Configuration scripts are decrypted by the Mediatrix 4102. Configuration scripts is encrypted. The file is useless if intercepted. Media5 provides an encryption tool (MxCryptFile) to secure the configuration scripts on the server. Once the file is encrypted, the transfer of the information over the network is secure. The encryption tool uses symmetric block cipher to encrypt data. The encryption key supported by the tool can be up to 128-bits with increment of 8-bits. This encryption key must be configured on the Mediatrix units in order to decipher the information. The tool provided by Media5 can be used on Windows, Linux or Unix operating systems. The following is an example of the tool running on Windows: The following are some examples of MxCryptFile commands: MxCryptFile.exe in Mediatrix 4102_unencrypted.cfg out Mediatrix 4102.cfg k 12345678 Page 7 of 11
MxCryptFile.exe in 0090F8XXXXXX_unencrypted.cfg out 0090F8XXXXXX.cfg k 89bb6758ac895f56 Ensure that the Mediatrix unit is configured with the correct key in order to decipher the information. Without the proper key, the parameters in the encrypted script would not be applied to the Mediatrix unit. Preparation of the Configuration Files and Firmware Firmware Server Firmware download IP Request Configuration Scripts and then request firmware Mediatrix 4102 Mediatrix units can be upgraded by using configuration scripts. The FPU.install command is used to start the upgrade process with the currently configured variables (host name, version, etc). A typical upgrade can be configured as follow : Fpu.MfpSelection[Index=0].MfpName = "Dgw" Fpu.MfpVersion="2.0.12.230" Fpu.MfpLocation="Mediatrix_Firmware" Fpu.MfpTransferProtocol = "Tftp" Fpu.MfpTransferUsername="" Fpu.MfpTransferPassword="" Fpu.MfpTransferSrvHostname="192.168.0.2" Fpu.AutomaticRestartEnable = "Enable" Fpu.Install In this example, the unit would automatically upgrade to DGW version 2.0.12.230. The unit would fetch the firmware on the TFTP server 192.168.0.2 in the Mediatrix_Firmware folder. The unit would also reboot automatically at the end of the upgrade to finish the installation. Configuration of the Mediatrix Unit You can configure the auto-provisioning in four ways: 1. Using the Administration web page 2. Using the CLI 3. Using Unit Manager Network 4. Using automatically fetched configuration script This document describes method one and four in length and presents method two with screenshots throughout this section. If you wish to use method 2 or 3, use the variable names that are in parenthesis. Page 8 of 11
Configuration Script Fetching using the Administration Web Page (Method 1) Configuration Notes 275 1. Once you have gained access to the Management web page (Method 1), access the Configuration Scripts section : 2. Run Scripts section: Configure the Generic File Name (ScriptGenericFileName). If you wish, you can use one of the macros mentioned in the Configuration Scripts section. Configure the Specific File Name (ScriptSpecificFileName). If you wish, you can use one of the macros mentioned in the Configuration Scripts section. Configure the Location (ScriptsLocation). This path should lead to the folder that contains the configuration files. Configure the Transfer Protocol (ScriptsTransferProtocol) a. When using FTP, HTTP or HTTPS, you can configure a User Name (ScriptsTransferUsername) and Password (ScriptsTransferPassword) if your server requires basic or digest authentication. Configure the IP address or FQDN (and the port separated by a colon) of the file server in the Host Name field (ScriptsTransferSrvHostname). When using the special port 0, port 80 will be used for a HTTP server, port 21 for a FTP server and port 69 for a TFTP server. When using encryption, configure the Privacy Key (ScriptsSecretKey). This key should be the same as the one used with the MXCryptFile to encrypt the configuration script. Configure the Allow Repeated Execution (ScriptsAllowRepeatedExecution). This variable can be set to Disable to prevent the unit from running the same script twice. 3. Automatic update configuration: Configure the Update On Restart (ScriptsTransferOnRestartEnable) if you wish the unit to check for new script at each start. Configure the Update Periodically (ScriptsTransferPeriodicEnable) if you wish the unit to check for new script periodically. o If you have enabled the periodic update, you can configure the frequency with three parameters: Time Unit (ScriptsTransferPeriodicTimeUnit) Period (ScriptsTransferInterval) Time of day (ScriptsTransferTimeOfDay) Configure the DHCP Download Enable (ScriptsDhcpDownloadEnable) variable. This variable allows the unit to run a script provided using a DHCP option. (See section How to automatically configure your Mediatrix units (Method 4)) 4. The following is what the configured interface would look like for method 1. In this example, a Mediatrix 4102 with MAC address 0090F8XXXXXX will download two configuration scripts every day at 1h00 (24h format) on the HTTP server httpserver.media5corp.com. The unit will fetch the files Mediatrix 4102.cfg and 0090F8XXXXXX.cfg in the Mediatrix_ConfigFiles folder. If one of configuration script has changed, the unit will execute the modified script. Page 9 of 11
Method 1: How to Automatically Configure your Mediatrix Units (Method 4) With the auto-provisioning feature, it was explained how to configure the Mediatrix units to automatically fetch configuration scripts. However, as explained, this feature requires the Mediatrix units to be manually configured. By using DHCP option, it is possible to have the Mediatrix units automatically execute a configuration script. Mediatrix units, by default, send DHCP requests to acquire an IP address. If one of the options 66 (tftp-server) or 67 (bootfile) is found in the server s answer, the Mediatrix unit will execute the specified script. DHCP Configuration The value of the option 66 (tftp-server) or 67 (bootfile) needs to be formatted for the unit to understand the option. Please refer to your DHCP server documentation on how to add options to DHCP answers. The format of the option is the following: FileType : Script <FileType>=<Protocol>://[<Username>[:<Password>]@]<Server>[/<Path>]/<File> Protocol : http, https, ftp, tftp Username: Optional. If username is not provided, the ScriptTransferUsername (CLI) is used. Password: Optional. If password is not provided, the ScriptTransferPassword (CLI) is used. Page 10 of 11
Server: IP address or FQDN. Path: Location of the file. The macros %mac%, %version%, %product% and %productseries% are allowed File : The macros %mac%, %version%, %product% and %productseries% are allowed. Example : Script=http://httpserver.media5corp.com/Mediatrix_ConfigFiles/%product%.cfg DHCP triggered scripts ignore the ScriptsAllowRepeatedExecution value. A given DHCP triggered script will not be executed twice without a factory reset or the download of a new generic script. The script is only executed if it is different than the last executed script. DHCP triggered scripts are always considered generic scripts. Page 11 of 11