Top

Configuration Scripts vs. Backup and Restore

Configuration Scripts

Configuration scripts are files containing textual commands that are sent from the ACS over the network to a Mediatrix unit.

Configuration scripts support all configuration parameters and can be created for a group of units or for a specific unit of the Network.

The automated importation of configuration scripts can be performed with the use of a Customer Profile or using a DHCP server indicating the location of the file server with options 66 or 67. The automated importation to a unit is what is referred to as zero-touch, as the unit is automatically updated with the latest configuration without manual intervention.

When the configuration scripts are received, the unit executes each command line in sequence. Script commands can assign values to configuration parameters, or execute configuration commands. Scripts are written by the system administrator and can be used to accomplish various tasks, such as automating recurrent configuration tasks or batch-applying configuration settings to multiple devices. They can also be scheduled to be executed when the Mediatrix unit restarts.

They can, for example, update the value of parameters, initiate a firmware upgrade, service restart, or unit reboot. The scripts can be imported by the unit in different situations:
  • When the unit is restarted
  • According to a pre-determined schedule
  • Initiated by a DHCP server indicating where the script files are located using options 66 and 67
Scripts can be sent using the following protocols:
  • FTP
  • TFTP
  • HTTP
  • HTTPS

The configuration script download feature allows updating the Mediatrix unit configuration by transferring a configuration script from a remote server or from the local file system. The Mediatrix unit is the session initiator, which allows NAT traversal. You can also configure the Mediatrix unit to automatically update its configuration or you can generate a configuration script from the running configuration of the Mediatrix unit.


Top

Configuration Backup and Restore

Performing a configuration backup allows you to have a copy of the entire configuration at the time the backup was performed.

The configuration backup can be used:
  • to revert the running configuration to a valid configuration when the running configuration generates error messages or no longer works;
  • to deploy a valid configuration on other units;
  • to revert to a known configuration when too many changes were made to the running configuration;
  • to deploy a backup configuration on a replacement unit.
The configuration backup includes every aspects of the configuration, i.e.
  • the status and configuration parameters;
  • the certificates;
  • the Rulesets.

But the configuration backup does not include the File service files, except for the Rulesets.

The configuration backup is an XML file and can, if necessary, be encrypted.
Note: Media5 corp strongly recommends to use a privacy algorithm (encryption) to protect certificates and passwords.
IMPORTANT: Do not edit the configuration image file as it may no longer work.
IMPORTANT: You can use a backup file on a unit with a newer or same firmware version than what is was taken from. A backup file can not be restored on an older firmware version than the one it was taken from.
IMPORTANT: The configuration image can only be restored on the same platform it was taken from.
Backup made on firmware version vX Unit firmware version Possible
Backup.v3 Firmware version 3 YES
Backup.v1 Firmware version 3 YES
Backup.v1 Firmware version 1 YES
Backup.v3 Firmware version 1 NO

The Configuration Back and Restore performed on Dgw v2.0.31 includes all Rulesets. However, starting on Dgw v.2.0.32 only the Rulesets modified by the user will be included in the configuration backup and restore. If a configuration backup is performed on Dgw v2.0.31 and restored on a newer version of DGW, all Rulesets existing in v2.0.31 will be copied as custom Rulesets i.e the system will not use the factory Rulesets of the newer version even if they were not modified.


Top

Configuration Scripts vs. Backup and Restore

  • Configuration scripts are files containing textual commands that are sent over the network to a Mediatrix unit. Upon receiving the file, the Mediatrix unit executes each command line in sequence. Script commands can assign values to configuration variables, or execute configuration commands.

    Scripts are written by the system administrator and can be used to execute several operations, such as automating recurrent configuration tasks or batch-applying configuration settings to multiple devices. Scripts can be executed once or periodically at a specified interval. They can also be scheduled to execute when the Mediatrix unit restarts.

  • The backup/restore feature is used to backup a specific Mediatrix unit's configuration for safety purposes. When needed, the configuration image file that is generated by a backup operation can be restored to put the unit back into the exact configuration it was when the backup was taken.

    Configuration image files contain a Mediatrix unit's configuration information. They are not intended to be edited and must not be confused with configuration scripts. When restoring a configuration image, the whole Mediatrix unit s current configuration is replaced with the configuration found in the configuration image file. Restoring a configuration image is therefore an operation that is completely different from executing a configuration script.


Top

Executing a Configuration Script

Configuring the FTP Server

Before you begin
If you are not familiar with the procedure on how to set the FTP root path, please refer to your FTP server's documentation.
Context

Perform this procedure if you plan to use the FTP transport protocol.

Steps
  1. Set an FTP service on the assigned server.
  2. Make sure the FTP server can be reached by the Mediatrix unit.
    Note: If the file server is located behind a firewall, make sure that TCP port 21 is open.

Top

Configuring the HTTP Server

Before you begin
If you are not familiar with the procedure on how to set the HTTP root path, refer to your HTTP server's documentation.
Context
Perform this procedure if you plan to use the HTTP transport protocol.
Steps
  1. Set an HTTP service on the assigned server.
  2. Make sure the HTTP server can be reached by the Mediatrix unit.
    Note: If the file server is located behind a firewall, make sure the TCP port 80 is open.

Top

Configuring the HTTPS Server

Before you begin
If you are not familiar with the procedure on how to set the HTTPS root path, please refer to your HTTPS documentation.

Make sure the unit is set to the proper date (refer to Configuring the Mediatrix Unit to Use an SNTP Server.

Context
Perform this procedure if you plan to use the HTTPS transport protocol.
Steps
  1. Set an HTTPS service on the assigned server.
  2. Make sure the HTTPS server can be reached by the Mediatrix unit.
    Note: If the file server is located behind a firewall, make sure the TCP port 443 is open.
  3. Make sure that in the Management/Certificates tab, in the Certificate Import Through Web Browser table, there is a certificate that authenticates the HTTPS server selected in the Path field, and that Other is selected in the Type field.
  4. Set the configuration parameters.

Top

Configuring the TFTP Server

Before you begin
If you are not familiar with the procedure on how to set the TFTP root path, please refer to your TFTP server's documentation.
Context
Perform this procedure if you plan to use the TFTP transport protocol.
Steps
  1. Set a TFTP service on the assigned server.
  2. Make sure the TFTP server can be reached by the Mediatrix unit.
    Note: If the file server is located behind a firewall, make sure the UDP port 69 is open.

Top

Executing Configuration Scripts from a File Server Periodically

Before you begin
Depending on the type of transport protocol used, one of the following procedures must be completed:

Mediatrix units do not all include a real time clock allowing them to maintain accurate time when they are shutdown. You must have a time server SNTP that is accessible and properly configured or the automatic configuration update feature may not work properly. Refer to Configuring the Mediatrix Unit to Use an SNTP Server.

Steps
  1. Go to Management/Configuration Scripts/Execute.
  2. In the Execute Scripts table, in the Generic File Name and/or Specific File Name field, indicate the name of the files you wish to import.
    Note: The file name is case sensitive, and may be replaced by a macro. For more details, refer to the Unit Macros section. Make sure to add the *.cfg. file extension.
  3. From the Transfer Protocol selection list, select the type of protocol you wish to use to transfer your script.
    Note: This must be consistent with the file server you have configured.
  4. In the Host Name field, enter the file server IP address or FQDN.
  5. In the Location field, enter the path relative to the root of the file server where the script is saved.
  6. If your server requires authentication, enter your username and password.
  7. If the files are encrypted, provide the privacy key in the Privacy Parameters section.
    Note: The privacy key must match the privacy key used to encrypt the file.
  8. Make sure the file server is started.
  9. In the Automatic Script Execution section, from the Execute Periodically selection list, choose Enable.
  10. Complete the Time Unit, Period and Time Range fields according to your needs.
    Note: The time range ( hh[:mm[:ss]] or hh[:mm[:ss]] - hh[:mm[:ss]]) is based on the Static Time Zone field, under the Network > Host page.
  11. As a best practice, enable the Allow Repeated Execution field.
  12. Click Apply.
Result
The configuration script will be imported from the file server at the specified time or at a random time within the specified interval and thereafter at the period defined by the Period field. Any change to the script will be applied to the running configuration. The unit configuration is only updated if at least one parameter value defined in the imported configuration scripts is different from the actual unit configuration. Keep in mind that if you import a generic and a specific file, the commands of the specific file will override the commands of the generic file.


Top

Executing Configuration Scripts from the Unit File Management System Each Time the Unit is Started

Before you begin
A configuration script must have been imported to the unit's file management system. Refer to Importing a Configuration Script to the Unit File Management System.
Steps
  1. Go to Management/Configuration Scripts/Execute.
  2. From the Execute Scripts table, in the Generic File Name and/or Specific File Name field, indicate the name of the files you wish to import or use the Suggestion selection list.
    Note: The file name is case sensitive, and may be replaced by a macro. For more details, refer to the Unit Macros section. Make sure to add the *.cfg. file extension.
  3. From the Transfer Protocol selection list, select File.
  4. If the files are encrypted, provide the privacy key in the Privacy Parameters section.
  5. In the Automatic Script Execution section, from the Execute on Startup selection list, choose Enable.
  6. As a best practice, enable the Allow Repeated Execution field.
  7. Click Apply.
Result
When the unit is restarted, the configuration script will be imported from the system's file management system, and any changes to the script will be applied to the running configuration. Keep in mind that if you import a generic and specific file, the commands of the specific file will override the commands of the generic file.


Top

Importing a Configuration Script to the Unit File Management System

Before you begin
This option is not available on the Mediatrix 4102S running a firmware version more recent than DGW 2.0.26.451
Steps
  1. Go to Management/File.
  2. If you are not using HTTPS, click Activate unsecure file importation from the Web browser located at the top of the page.
  3. In the Import File Through Web Browser table, from the Path selection list, select Conf/.
  4. Browse to the location of the configuration file.
  5. Click Import.
    Note: A factory reset will remove the file from the Internal file.
Result
The imported configuration file will appear in the Internal files table, under Management/File .


Top

Executing Configuration Scripts from the Unit File Management System Periodically

Before you begin

You must have a time server SNTP that is accessible and properly configured or the automatic configuration update feature may not work properly. Refer to Configuring the Mediatrix Unit to Use an SNTP Server. Configuration scripts files must be available in the unit's file management system. Refer to Importing a Configuration Script to the Unit File Management System.

A configuration script must have been imported to the unit's file management system. Refer to Importing a Configuration Script to the Unit File Management System.
Steps
  1. Go to Management/Configuration Scripts/Execute.
  2. In the Execute Scripts table, in the Generic File Name and/or Specific File Name field, indicate the name of the files you wish to import or use the Suggestion selection list.
    Note: The file name is case sensitive, and may be replaced by a macro. For more details, refer to the Unit Macros section. Make sure to add the *.cfg. file extension.
  3. From the Transfer Protocol selection list, select File.
  4. If the files are encrypted, provide the privacy key in the Privacy Key field.
    Note: The privacy key must match the privacy key used to encrypt the files.
  5. In the Automatic Script Execution section, from the Execute Periodically selection list, choose Enable.
  6. Complete the Time Unit, Period and Time Range fields according to your needs.
    Note: The time range ( hh[:mm[:ss]] or hh[:mm[:ss]] - hh[:mm[:ss]]) is based on the Static Time Zone field, under the Network > Host page.
  7. As a best practice, enable the Allow Repeated Execution field.
  8. Click Apply.
Result
The configuration script will be imported from the system's file management system at the specified time or at a random time within the specified interval and thereafter at the period defined by the Period field. Any change to the script will be applied to the running configuration. The unit configuration is only updated if at least one parameter value defined in the imported configuration scripts is different from the actual unit configuration. Keep in mind that if you import a generic and specific file, the commands of the specific file will override the commands of the generic file.


Top

Executing Configuration Scripts from a File Server Each Time the Unit is Started

Before you begin
Depending on the type of transport protocol used, one of the following procedures must be completed:
Steps
  1. Go to Management/Configuration Scripts/Execute.
  2. From the Execute Scripts table, in the Generic File Name and/or Specific File Name field, indicate the name of the files you wish to import.
    Note: The file name is case sensitive, and may be replaced by a macro. For more details, refer to the Unit Macros section. Make sure to add the *.cfg. file extension.
  3. From the Transfer Protocol selection list, select the type of protocol you wish to use to transfer your script.
    Note: This must be consistent with the file server you have configured.
  4. In the Host Name field, enter the file server IP address or FQDN.
  5. In the Location field, enter the path relative to the root of the file server where the script is saved.
  6. If your server requires authentication, enter your username and password.
  7. If the files are encrypted, provide the privacy key in the Privacy Parameters section.
    Note: The privacy key must match the privacy key used to encrypt the files.
  8. Make sure the file server is started.
  9. In the Automatic Script Execution section, from the Execute on Startup selection list, choose Enable.
  10. As a best practice, enable the Allow Repeated Execution field.
  11. Click Apply.
Result
When the unit is restarted, the configuration script will be imported from the file server, and any changes to the script will be applied to the running configuration. Keep in mind that if you import a generic and a specific file, the commands of the specific file will override the commands of the generic file.


Top

Configuring the Mediatrix Unit to Use an SNTP Server

Before you begin
Make sure there is an SNTP server available.
Context
Steps
  1. Go to Network/Host.
  2. In the SNTP Configuration table, from the Configuration Source selection list, select the connection type from which you wish to obtain the SNTP parameters.
    Note: Complete Step 3 only if you are using static SNTP server(s), otherwise go to Step 4.
  3. Provide an IP address or domain name and port numbers for each SNTP server you are using.
  4. If necessary, change the displayed default value of the Synchronisation Period.
  5. If necessary, change the displayed default value of the Synchronisation Period on Error.
  6. Click Apply.
Result
The SNTP host name and port will be displayed in the Host Status table under Network/Status.


Top

Sample Template Configuration Script

The following is a sample configuration script that can be used as a template to start building custom configuration scripts. It performs common configuration tasks on the Mediatrix unit.
################################################################################
#
# Copyright (c) Media5 Corporation
#
# This file contains sample script commands to help configure a Mediatrix 4000
# series unit.
#
# Please refer to "Technical Bulletin 0614 - Using Configuration Scripts to
# Automate Configuration for the Mediatrix C740 Series",
# available on the Mediatrix support portal
#(http://www.mediatrix.com/support.php), and to the Mediatrix unit's
# documentation for more information on using configuration scripts.
#
# This script reproduces the configuration described in "Configuration Note
# 245 - Mediatrix C740 VoIP Gateway PSTN Scenario", available on the Mediatrix
# support portal (http://www.mediatrix.com/support.php). It follows the order
# of the configuration steps from Configuration Note 245, so it is a good
# idea to read Configuration Note 245 along with the script
#
# USING THIS FILE: this file is intended to be used as a sample script to be the
# base of custom scripts developed by system administrators. Starting from this
# script, system administrators can build their own configuration scripts by
# replacing the sample statements and values with their own.
#
## NOTE: this script assumes tha the configuration is done from a "factory
# reset" state.
################################################################################# 
################################################################################
# Configuration Note 245 step1
#   Physical Connection of the Mediatrix C740 to the Network and PSTN
################################################################################ 
# No script commands 
################################################################################
# Configuration Note 245 step 2
#   IP Address Discovery or Configuration
################################################################################ 
# No script commands 
################################################################################
# Configuration Note 245 step 3
#   Web Interface Access
################################################################################ 
# No script commands 
################################################################################
# Configuration Note 245 step 4
#   SIP Configuration
#
#   SIP parameters configuration is done in the SipEp (SIP Endpoints)service
################################################################################ 
# Set the default registrarSipEp.DefaultStaticRegistrarServerHost="192.168.9.201" 
# Set the default proxySipEp.DefaultStaticProxyHomeDomainHost="192.168.9.201" 
################################################################################
# Configuration Note 245 step 5
#   ISDN Configuration
#
#   ISDN parameters configuration is done in the Isdn (Integrated Services
#   Digital Network) service
################################################################################ 
# Set the endpoint type for ports Bri1 and Bri2 to TE (option TE has numeric
# value 100)Isdn.BasicRateInterface.EndpointType[Name="Bri1"]="100"Isdn.BasicRateInterface.EndpointType[Name="Bri2"]="100" 
# Set the connection type forports Bri1 and Bri2 to Point To Point (option
# Point To Point has numeric value 100)Isdn.BasicRateInterface.ConnectionType[Name="Bri1"]="100"Isdn.BasicRateInterface.ConnectionType[Name="Bri2"]="100" 
# Restart the Isdn service because these parameters require a service restart in
# order to be correctly applied (command option "restart" has numeric value 10)Scm.ServiceCommands.Restart[Name="Isdn"]=10 
################################################################################
# Configuration Note 245 step6
#  Call routing configuration.
#
#   Call routing parameters configuration is done in the CRout (Call Routing)
#   service. After the configuration is done, do not forget to execute the
#   ApplyConfig command to apply the new parameters to the call router(next
#   call will be processed using the new parameters).
################################################################################ 
#
# Hunt groups
# 
# Empty the Hunt Groups table to make sure we create the first one CRout.Hunt.DeleteAllRows 
# Create a Hunt group and configure it CRout.InsertHuntCRout.Hunt.Name[Index="1"]="hunt_PSTN"CRout.Hunt.Destinations[Index="1"]="isdn-Bri1, isdn-Bri2" 
#
# Mappings
# 
# Empty the Mapping Types table to make sure we create the first one CRout.MappingType.DeleteAllRows 
# Create the first Mapping Type and configure it (option Called E164 has numeric
# value 300)CRout.InsertMappingTypeCRout.MappingType.Name[Index="1"]="From_PSTN"CRout.MappingType.Criteria[Index="1"]="300"CRout.MappingType.Transformation[Index="1"]="300" 
# Empty the Mapping Types table to make sure we create the first one CRout.MappingExpressions.DeleteAllRows 
# Create the first Mapping Expression and configure it CRout.InsertMappingExpressionCRout.MappingExpression.Name[Index="1"]="From_PSTN"CRout.MappingExpression.Criteria[Index="1"]="030(.+)"CRout.MappingExpression.Transformation[Index="1"]="\\1" 
# double backslash needed(escape) 
# Create the second Mapping Type and configure it (option Called E164 has
# numeric value 300)CRout.InsertMappingTypeCRout.MappingType.Name[Index="2"]="To_PSTN"CRout.MappingType.Criteria[Index="2"]="300"CRout.MappingType.Transformation[Index="2"]="300" 
# Create the second Mapping Expression and configure itCRout.InsertMappingExpressionCRout.MappingExpression.Name[Index="2"]="To_PSTN"CRout.MappingExpression.Criteria[Index="2"]=".+"CRout.MappingExpression.Transformation[Index="2"]="030\\0" 
#CRout.Route.DeleteAllRows
# Routes
# 
# Empty the Routes table to make sure we create the first one CRout.Route.DeleteAllRows 
# Create the first Route and configure it CRout.InsertRouteCRout.Route.SourceCriteria[Index="1"]="sip-default"CRout.Route.Destination[Index="1"]="hunt-hunt_PSTN"CRout.Route.Mappings[Index="1"]="To_PSTN" 
# Create the second Route and configure it CRout.InsertRouteCRout.Route.SourceCriteria[Index="2"]="isdn-Bri1"CRout.Route.Destination[Index="2"]="sip-default"CRout.Route.Mappings[Index="2"]="From_PSTN" 
# Create the third Route and configure it CRout.InsertRouteCRout.Route.SourceCriteria[Index="3"]="isdn-Bri2"CRout.Route.Destination[Index="3"]="sip-default"CRout.Route.Mappings[Index="3"]="From_PSTN" 
#
# Apply configuration
# 
# Apply the new parameters to the call router (next call will be processed using
# the new parameters)CRout.ApplyConfig 
################################################################################
# End
################################################################################

Top

Unit Macros

Macro Description
%mac% the MAC address of the unit
%version% the MFP version of the unit (firmware version)
%product% the Product name of the unit
%productseries% the Product series name of the unit.

Top

Online Help

If you are not familiar with the meaning of the fields and buttons, click Show Help, located at the upper right corner of the Web page. When activated, the fields and buttons that offer online help will change to green and if you hover over them, the description will bedisplayed.


Top

DGW Documentation

Mediatrix devices are supplied with an exhaustive set of documentation.

Mediatrix user documentation is available on the Media5 Documentation Portal.

Several types of documents were created to clearly present the information you are looking for. Our documentation includes:
  • Release notes: Generated at each GA release, this document includes the known and solved issues of the software. It also outlines the changes and the new features the release includes.
  • Configuration notes: These documents are created to facilitate the configuration of a specific use case. They address a configuration aspect we consider that most users will need to perform. However, in some cases, a configuration note is created after receiving a question from a customer. They provide standard step-by-step procedures detailing the values of the parameters to use. They provide a means of validation and present some conceptual information. The configuration notes are specifically created to guide the user through an aspect of the configuration.
  • Technical bulletins: These documents are created to facilitate the configuration of a specific technical action, such as performing a firmware upgrade.
  • Hardware installation guide: They provide the detailed procedure on how to safely and adequately install the unit. It provides information on card installation, cable connections, and how to access for the first time the Management interface.
  • User guide: The user guide explains how to customise to your needs the configuration of the unit. Although this document is task oriented, it provides conceptual information to help the user understand the purpose and impact of each task. The User Guide will provide information such as where and how TR-069 can be configured in the Management Interface, how to set firewalls, or how to use the CLI to configure parameters that are not available in the Management Interface.
  • Reference guide: This exhaustive document has been created for advanced users. It includes a description of all the parameters used by all the services of the Mediatrix units. You will find, for example, scripts to configure a specific parameter, notification messages sent by a service, or an action description used to create Rulesets. This document includes reference information such as a dictionary, and it does not include any step-by-step procedures.

Top

Copyright Notice

Copyright © 2023 Media5 Corporation.

This document contains information that is proprietary to Media5 Corporation.

Media5 Corporation reserves all rights to this document as well as to the Intellectual Property of the document and the technology and know-how that it includes and represents.

This publication cannot be reproduced, neither in whole nor in part, in any form whatsoever, without written prior approval by Media5 Corporation.

Media5 Corporation reserves the right to revise this publication and make changes at any time and without the obligation to notify any person and/or entity of such revisions and/or changes.