Importing and exporting configuration scripts allows you to modify in whole or in part
the configuration script used on your unit.
Configuration scripts are files containing textual commands that are sent over the network to a
Mediatrix unit. Upon receiving the file, the unit executes each command line in sequence. Script
commands can assign values to configuration variables, or execute configuration commands.
A configuration script can be used on any firmware version, regardless of the firmware version
it was exported from. It is possible to import a complete configuration script, a subset of the
configuration script or even a few lines of a configuration script.
Importing a configuration script can be useful to:
Change one or several script commands
Add new commands
Change parameter values
Add parameters
Replace the complete configuration script
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. Scripts can be executed once or periodically at a specified interval. They can
also be scheduled to be executed when the Mediatrix unit starts.
The Simple Network Time Protocol (SNTP) is used to update and synchronise the clock of
the Mediatrix unit (day, month, time) when it is restarted.
Mediatrix units do not all include a real time clock allowing them to maintain accurate time
when they are shutdown. Your system needs to have access to accurate time, for example if you are
using HTTPS or for the caller ID feature. The Mediatrix unit implements a SNTP client, which can
synchronise the local clock with remote NTP/SNTP servers. The configuration can be automatic
(through DHCP for example), with fallback, or static, with up to four servers.
The Mediatrix unit can be configured to automatically download new configuration scripts
upon receiving options 66 (tftp-server) or 67 (bootfile), or vendor-specific option 43 using
sub-options 66 and 67 in a DHCPv4 answer
A DHCP server answer includes both Bound and Renew. The contents of option 66, 67 or 43
defines which script to download. The unit's configuration is not used to download the script.
This allows the unit, for instance, to download a script from a server after a factory reset and
to reconfigure itself without a specific profile. If the imported configuration script is
identical to the last executed script, it will not be run again. The script retry mechanism is
not enabled for the DHCPv4 triggered scripts. If options 66, 67 and 43 are received, all scripts
are executed independently. The script defined by the tftp-server (option 66) option is executed
first. If you are using HTTPS to transfer scripts, you must have a time server SNTP that is
accessible and properly configured.
Perform this procedure if you plan to use the HTTPS transport protocol.
Steps
Set an HTTPS service on the assigned server.
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.
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.
Configuring the Mediatrix Unit to Use an SNTP Server
Before you begin
Make sure there is an SNTP server available.
Context
Steps
Go to Network/Host.
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.
Provide an IP address or domain name and port numbers for each SNTP
server you are using.
If necessary, change the displayed default value of the Synchronisation Period.
If necessary, change the displayed default value of the Synchronisation Period on Error.
Click Apply.
Result
The SNTP host name and port will be displayed in the Host Status table under Network/Status.
In the Export Script
table, from the Content selection list, choose if you wish to export only what is different from the
factory configuration script or the complete configuration.
From the Service Name
selection list, choose if you wish to export the configuration script of a
specific service or of all services.
In the Send To URL
field, enter the
protocol://[user[:password]@]hostname[:port]/[path/]filename
where to export the configuration file.
Note: This must be consistent with the file server you have configured. The file
name may be replaced by a macro. For more details, refer to the Unit Macros section. As a
best practice, add the *.cfg extension to the file name.
Note: Remember, if you have several units with several configurations and plan
to reuse the configuration on another unit, the name must be explicit.
Indicate the date of your script, the interfaces used, the device model,
etc.
If you wish to use encryption for transfer operations, enter a encryption key
in the Privacy Key
field.
Note: Media5 corp strongly recommends to use encryption to protect certificates
and passwords.
Make sure the file server is started.
Click Export and Download.
Result
The configuration script will be exported to the specified file server.
If you are not using HTTPS, click Activate unsecure
file importation from the Web browser located at the top of the page.
In the Download Script From Web
Browser
table, from the Content selection list, choose if you wish to export only what is different from the
factory configuration script or the complete configuration.
If you wish to use encryption for transfer operations, complete the Privacy Key field.
Note: Media5 strongly recommends to use encryption to protect certificates
and passwords.
Click Export and Download.
Result
The configuration script will be exported to your PC in the Downloads folder. The
system generates a macAddress.cfg file name.
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 on macros, refer to the Unit Macros section. Make
sure to add the *.cfg. file extension.
From the Transfer Protocol selection
list, select the type of protocol you wish to use to transfer your configuration
script.
Note: This must be consistent with the file server you have configured.
In the Host Name
field, enter the file server IP address or FQDN.
In the Location
field, enter the path relative to the root of the file server where the
configuration script is saved.
If your server requires authentication, enter your username and password.
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
file.
Make sure the file server is started.
Depending on your use case, set the Allow Repeated Execution
field to Enable or
Disable. This
parameter defines if the Mediatrix unit will execute a script or not, when it is
the same as the last executed script.",
Click Apply & Execute.
Result
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.
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.
From the Transfer Protocol selection
list, select File.
Note: This option is not available on the Mediatrix 4102S running a firmware
version more recent than DGW 2.0.26.451
If the file is encrypted, complete the Privacy Key field.
Note: The privacy key must match the privacy key used to encrypt the
file.
As a best practice, enable the Allow Repeated Execution
field.
Click Apply & Execute.
Result
The configuration script will be imported from the unit'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.
If you are not using HTTPS, click Activate unsecure
file importation from the Web browser.
In the Execute Inline Script table,
insert the configuration lines.
Click Execute.
Result
All the lines of the script will be transferred to the unit, executed in batch in
background, and applied to the running configuration. The Scripts Status Execute table
will display the current state and result of the execution.
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
Go to Management/Configuration Scripts/Execute.
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.
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.
In the Host Name
field, enter the file server IP address or FQDN.
In the Location
field, enter the path relative to the root of the file server where the script
is saved.
If your server requires authentication, enter your username and password.
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.
Make sure the file server is started.
In the Automatic Script
Execution
section, from the Execute Periodically
selection list, choose Enable.
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.
As a best practice, enable the Allow Repeated Execution
field.
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.
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.
From the Transfer Protocol selection
list, select File.
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.
In the Automatic Script
Execution
section, from the Execute Periodically
selection list, choose Enable.
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.
As a best practice, enable the Allow Repeated Execution
field.
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.
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.
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.
In the Host Name
field, enter the file server IP address or FQDN.
In the Location
field, enter the path relative to the root of the file server where the script
is saved.
If your server requires authentication, enter your username and password.
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.
Make sure the file server is started.
In the Automatic Script
Execution
section, from the Execute on Startup selection
list, choose Enable.
As a best practice, enable the Allow Repeated Execution
field.
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.
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.
From the Transfer Protocol selection
list, select File.
If the files are encrypted, provide the privacy key in the Privacy Parameters
section.
In the Automatic Script
Execution
section, from the Execute on Startup selection
list, choose Enable.
As a best practice, enable the Allow Repeated Execution
field.
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.
Configuring the DHCP to Trigger Configuration Script Execution
The Mediatrix unit can be configured to automatically import new configuration
scripts upon receiving options 66 (tftp-server) or 67 (bootfile), or vendor-specific option
43 using sub-options 66 and 67 in a DHCPv4 answer. A DHCP answer includes both Bound and
Renew.
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. If you are using HTTPS, you must have an SNTP
server 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.
In the Automatic Script
Execution
section, from the Allow DHCP to Trigger Scripts
Execution selection list, choose Enable.
Click Apply.
Result
The instructions sent FROM the DHCP server can be in different formats and will be
understood by the Mediatrix unit according to what was chosen for the
ScriptsDhcpOptionsFormat MIB parameter (not accessible via
Web page). Possible values with their respective formats are:
ServerHost: Allow one DHCP option to specify the IP address or FQDN of a file
server. Uses the path and filename specified in the ScriptLocation and
ScriptGenericFileName parameters, use the transfer protocol, username and
password specified in ScriptTransferProtocol, ScriptTransferUsername and
ScriptTransferPassword parameters.
AutoDetect: A value beginning with "Script=" is considered as "FullyQualified",
A value beginning with "[protocol]://" is considered as a URL. A value that
looks like an IPv4/IPv6 address or domain name is considered as a "ServerHost".
(default value)
When the unit starts, it will receive the location of the config script from the DHCP
response, as per the format defined by the
ScriptsDhcpOptionsFormat parameter. The unit will then
import and execute the configuration scripts from the specified location. Any
changes 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.
Although the services can be configured in great part in the Web browser, some
aspects of the configuration can only be completed with the configuration parameters by
:
using a MIB browser
using the CLI
creating a configuration script containing the configuration parameters
For more details on the following parameters, refer to the DGW Configuration Guide - Reference Guide
published on the Media5 Documentation Portal. The
Reference Guide contains all the parameters used in the DGW software with their
description, default values, and interactions.
Scripts Transfer Certificate Validation
Refer to Conf.
ScriptsTransferCertificateValidation.
Scripts Transfer Certificate Trust Level
Refer to Conf.
ScriptsTransferCertificateTrustLevel.
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.
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.
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.