Top

Virtual Machine Basic Concepts

Important Information on Virtual Machines

Note: It is not possible to modify the settings (RAM, name, etc.) once the virtual machine has been created. The only way to change the settings, is to delete the virtual machine and to create it once again.
Note: A maximum of 2 virtual machines can be added.

Top

RAM and SSD Sizes

Table 1.
Description Possible Values
RAM size 1
  • 0 - No DDR (slave device) (contact Media5 sales)
  • 1 - 2 GB DDR
  • 2 - 4 GB DDR
  • 3 - 8 GB DDR
  • 4 - 16 GB DDR (contact Media5 sales)
SSD size 2
  • 0 - No SSD (slave device) (contact Media5 sales)
  • 1 - 16 GB SSD
  • B - 32 GB SSD (20k erase cycle)
  • C - 64 GB SSD (20k erase cycle)
  • D - 128 GB SSD (20k erase cycle)
  • E - 256 GB SSD (20k erase cycle)

Top

RAM Allocation to Virtual Machines

To reduce the wear-and-tear of the Solid State Drive, make sure to allocate the maximum amount of RAM possible to the virtual machine.

Installed RAM on Mediatrix Units Available RAM for Virtual Machine
2 Gb 1.5 Gb
4 Gb 3.5 Gb
8 Gb 7 Gb ( 87.5% of available RAM)
16 Gb 10 Gb

Top

VM name

The name is set when adding a new virtual machine with the CreateVm command. The user cannot modify the name after.

When the CreateVm command is called without a name, the index is used to generate a unique name such as VM_Index.


Top

VM Memory

When adding a VM with the CreateVm command, the amount of allocated memory is set; this amount cannot be modified after adding the VM.

When the CreateVm command is called without an amount of allocated memory, a minimal value of 128 MB is set.

Depending on the total amount of volatile memory in the system, the amount of memory reserved for DGW is
  • a minimum of 512 MB, or
  • 12.5% of the total volatile memory capacity if more than 512 MB is available

Top

USB Usage

The VM config allows the user to associate none or all USB Ports to a virtual machine.

A USB port can be associated with one VM. The first VM that is configured with USB can use all available USB ports.

If an another VM tries to use a USB port already in use, the Vm service ignores this config and starts the VM as if it was configured with NONE, and sets its configuration status (ConfigStatus) to USBNotAvailable.


Top

Virtual Switch

Enabling the Virtual Switch with the Eth.Links.VirtualSwitch parameter grants network access to the VM. Once enabled, the virtual switch creates a bridge between the VM and the associated Ethernet link.

When the Virtual Switch is enabled, the Vm.Vm.NetworkAdapter parameter configures its virtualised network adapter.


Top

Behaviour on Factory Reset

The unit can be preinstalled with a factory-installed VM stored in the vm/images/factory folder. This folder can only be created in factory and must have the factory-installed VM files.

Two behaviors are possible for the VMs on a factory reset.
  • When one or more factory-installed VM is present, VM images and configurations are returned to their original factory state.
  • When no factory-installed VM is present, the VM images and configurations stay unchanged, i.e. the files present in vm/images/ are not erased.
When a factory-installed VM is present, the factory reset is performed as follows:
  • The files in the vm/images/ folder are erased, which removes the VM snapshots and all VMs created, modified, or installed by users.
    • Note: this is done even if the vm/images/factory folder exists and is empty.
  • For each factory-installed VM (visible in the vm/images/factory folder), the configuration file (.cfg) is copied in the vm/images folder and a snapshot of the VM image is also created in the vm/images folder. The snapshot file is given the .snapshot extension and is always in a QCOW2 format. When this VM is used, the snapshot file changes over time but the base image (located in vm/images/factory) is never modified, allowing the next factory reset to restore the factory VMs to their original state again.
  • The admin can use, configure, convert, and delete a VM with a snapshot image like any other VM, but after a factory reset, the snapshot image is deleted and a new one is created.
  • When a snapshot file is converted into a VM image file, the resulting file is a new image file combining the base VM plus the history contained in the snapshot file.
  • Users cannot add or delete files on the vm/images/factory folder. This can only be done in factory.
  • The VM images under vm/images/factory can have either the RAW or QCOW2 format.
  • The RestoreAfterFactory parameter in the VM configuration file is ignored. The factory-installed VMs are always restored.

In all cases, the content of /vm/drives is erased.


Top

How to Protect my VM against Spectre

There are different mitigation techniques against Spectre:

  • Mitigation #1: A microcode update from the CPU vendor for better control over the branch speculation. Also need an updated kernel to enable these new features (IBRS and IBPB).
  • Mitigation #2: Different techniques (like "retpoline" and "LFENCE") that require recompiling the kernel, packages and applications.

As the time this document was written, Mitigation #1 could not be applied, as Intel had not yet released a microcode update for the CPU of the Sentinel 400.

If your Virtual Machine is vulnerable, Media5 recommends applying Mitigation #2. See https://en.wikipedia.org/wiki/Spectre_(security_vulnerability)#Mitigation for more details.
IMPORTANT: Mitigation techniques against Spectre may impact the performance of your Virtual Machine.

Top

How to Protect my VM against Meltdown

Linux kernels have a new feature called KPTI (previously known as KAISER) that protects against Meltdown.

If your Virtual Machine is vulnerable, Media5 recommends that you upgrade your kernel to a version that supports KPTI, and enable it.

For more information on KPTI: https://en.wikipedia.org/wiki/Kernel_page-table_isolation
IMPORTANT: Enabling KPTI may impact the performance of your Virtual Machine.

Top

Basic Virtual Machine Tasks

Stopping the Virtual Machine

Steps
  1. Go to System/VM.
  2. In the Virtual Machine Configuration table, click located on the same row as the VM you wish to stop.
Result
The virtual machine stops. In the Virtual Machine Status table, Stopped will be displayed under the State column.

Top

Stopping the Virtual Machine - Graceful Stop

Steps
  1. Open the VNC Client located on a computer located on the network connected to the unit.
    Note:

    UltraVNC Viewer, TightVNC Viewer and VNC Viewer are presently supported.

  2. Enter the Unit.IP.Address: VNCid .
  3. In the VNC console, shutdown the OS using the recommended OS method.

Top

Rebooting a VM

Context
If the virtual machine you wish to start requires resources equivalent to the available resources on the unit, then it will not be possible to start another virtual machine. It is only possible to start a virtual machine if there are enough resources on the unit.
Note: Rebooting a virtual machine does not have the same effect as Restarting the virtual machine.
Steps
  1. Go to System/VM.
  2. Click .
Result
The virtual machine is restarted. In the Virtual Machine Status, Started will be displayed under the State column.

Top

Rebooting a VM - Graceful Reboot

Context

Although the virtual machine can be rebooted via the Web page, rebooting the virtual machine using a VNC Client is the preferred way to reboot the virtual machine.

Note: Rebooting the virtual machine does not have the same effect as restarting the virtual machine.
Steps
  1. Open the VNC Client located on a computer located on the network connected to the unit.
    Note:

    UltraVNC Viewer, TightVNC Viewer and VNC Viewer are presently supported.

  2. Enter the Unit.IP.Address: 5900+VNCid .
  3. In the VNC console, shutdown the OS using the recommended OS method.
Result
The virtual machine is restarted. In the Virtual Machine Status, Started will be displayed under the State column.

Top

Deleting a VM

Steps
  1. Go to System/VM.
  2. In the Virtual Machine Configuration table, click located on the same row as the virtual machine you wish to delete.
Result
The virtual machine and its configuration are deleted.

Top

Setting the Virtual Machine to Automatic Start

Context

If the virtual machine you wish to start requires resources equivalent to the available resources on the unit, then it will not be possible to start another virtual machine. It is only possible to start a virtual if there are enough resources on the unit.

Steps
  1. Go to System/VM.
  2. In the Virtual Machine Configuration table, from the Startup dropdown list, select Auto.
  3. Click Apply.
Result
When the Vm Service is started, the virtual machine will also be started.


Top

Setting the Virtual Machine to Manual Start

Context
Manually starting the virtual machine can be useful when installing the virtual machine to check if the installation was done properly. However, on a day to day usage, the virtual machine should be set to start automatically. Refer to Setting the Virtual Machine to Automatic Start.
Note: If the virtual machine you wish to start requires resources equivalent to the available resources on the unit, then it will not be possible to start another virtual machine. It is only possible to start a virtual machine if there are enough resources available on the unit.
Steps
  1. Go to System/VM.
  2. In the Virtual Machine Configuration table, from the Startup dropdown list, select Manual.
  3. Click Apply.
Result
The virtual machine will be started only if it is started manually. In the Virtual Machine Status, Started will be displayed under the State column.


Top

Deleting a VM

Steps
  1. Go to System/VM.
  2. In the Virtual Machine Configuration table, click located on the same row as the virtual machine you wish to delete.
Result
The virtual machine and its configuration are deleted.

Top

Virtual Machine Installation

Adding a Virtual Machine

Before you begin
The VirtualSwitch parameter must be configured to enable the link you wish to use to contact the virtual machine. Refer to Configuring a Link as a Virtual Switch .

You must have a virtual machine licence and the VM service must be started.

Caution: It is a best practice to create the Virtual Machine in a test environment. If not enough memory is allocated and swap is disabled, the Virtual Machine will stop, and the installation will need to be restarted from the beginning.
Steps
  1. Go to System/VM.
  2. In the Virtual Machine Creation table, complete the Vm Name field.
    Note: Vm names must be unique.
  3. In the Ram(Mb) field, enter the amount of RAM required to run the virtual machine.
    Caution: To reduce the wear-and-tear of the Solid State Drive, make sure to allocate the maximum amount of RAM possible to the virtual machine.
    Note: For instance, 87.5% of the actual available RAM, or 1.5 Gb for units with 2 Gb of RAM, 3.5 Gb with 4 Gb of RAM and for 7 Gb with 8 Gb of RAM.
  4. Complete the Storage(Gb) field.
    Note: 10 Gb is the maximum value one can allocate in a typical Sentinel equipped with a 16 Gb Solid State Drive.
  5. From the Image Format selection list, choose the format of the image.
    Note:
    • Use QCOW2 for space efficiency and flexibility.
    • Use RAW for improved performance
  6. From the Nb Cores selection list, select the number of cores the virtual machine will be using.
    IMPORTANT: It is not possible to modify the settings (RAM, name, etc.) once the virtual machine has been created. The only way to change the settings, is to delete the virtual machine and to create it once again.
  7. Click .
    Note: A maximum of 2 virtual machines can be added.
Result
The virtual machine will be displayed in both the Virtual Machine Configuration and the Virtual Machine Status tables.


Top

Configuring a Link as a Virtual Switch

Steps
  1. Go to Network/Interfaces.
  2. In the Ethernet Link Configuration table, from the Virtual Switch selection list, select Enable located on the same row as the link you wish to enable for the virtual switch.
  3. Click Apply.
Result



Top

Importing an ISO Image Larger than 10mb to the Unit File Management System

Before you begin
Only the http and https protocols are supported to import the large files.
Steps
  1. Go to Management/File .
  2. In the Import File Through URL table, from the Destination selection list, select the destination directory on the unit where to save the file.
  3. In the URL field, indicate the file server's URL where the iso image to import is located.
    Note: For larger files you must use the http or https protocols. For example http://www.myserver.com/myfile
  4. Complete the User Name and Password fields if the file server requires authentication.
  5. Click Import.
Result
The ISO image file will be displayed in the VM Files table, under Management/File.


Top

Importing an ISO image to the Unit File Management System

Context

If the ISO Image is larger than 10mb, use the Importing an ISO Image Larger than 10mb to the Unit File Management System.

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 vm/drives/.
  4. Browse to the location of the ISO file containing the operating system (OS) to install on the virtual machine.
  5. Click Import.
    Note: A factory reset will remove the file from the Internal filestable.
Result
The imported ISO file will appear in the VM Files table, under Management/File.


Top

Configuring the VM Network Adapter (VirtIO)

Before you begin
Configuring the Network Adapter is optional. By default, it is set to E 1000 (Intel 82545EM emulated network interface card). However, for enhanced network performance, the network adapter can be set to VirtIO, provided it is supported by the guest OS as paravirtualised drivers are required.
Steps
  1. Go to System/VM.
  2. From the Network Adapter drop down list, select VirtIO.
    Note: Please refer to the OS documentation for specific information regarding VirtIO.
  3. Click Apply.
Result

The virtual machine Network Adapter will be set to VirtIO.




Top

Installing the OS on the Virtual Machine Using an ISO image

Before you begin
The Importing an ISO image to the Unit File Management System procedure must be completed. When downloading an OS that provides architecture choices you need to choose either AMD64 (64 bit OS) or i386/i686 (32 bit OS). Basically you need to choose the architecture for an INTEL processor
Steps
  1. Go to System/VM.
  2. In the Virtual Machine Configuration, in the Iso Name field, indicate the name of the ISO file containing the OS.
  3. In the Vnc Id field, indicate the unique id used with the VNC Client to connect to the virtual machine console.
  4. From the Usb field, select None.
  5. Click .
  6. Open the VNC Client located on a computer of the network connected to the unit.
    Note:

    UltraVNC Viewer, TightVNC Viewer and VNC Viewer are presently supported.

  7. Enter the IPAddressOftheUnit:VNCid.
    Note: For example 192.168.0.12:1
  8. Follow the on-screen instructions.
    Caution:
    To reduce the wear-and-tear of the Solid State Drive,
    • On Linux OS, disable memory swapping or at least set swappiness to 0.
    • On Windows OS, disable the virtual memory.
    Note: If the Solid State Drive fails because it is inadequately used by a third party software or the operating system, the warranty of the Mediatrix unit will no longer be valid.
    Note: The installation can take more than an hour depending on the image you are installing.
Result
The virtual machine will be started only if it is started manually.


Top

Installing the Virtual Machine OS using a USB External Device

Before you begin
Make sure your USB external device contains the Operating System installation media, is bootable, and is connected. When downloading an OS that provides architecture choices you need to choose either AMD64 (64 bit OS) or i386/i686 (32 bit OS). Basically you need to choose the architecture for an INTEL processor.
Steps
  1. Go to System/VM.
  2. In the Virtual Machine Configuration table, in the Vnc Id field, indicate the unique id of the virtual machine.
  3. From the Usb field, select All.
  4. Click .
  5. Open the VNC Client located on a computer of the network connected to the unit.
    Note: UltraVNC Viewer, TightVNC Viewer and VNC Viewer are presently supported.
  6. Enter the IPAddressOftheUnit:VNCid
    Note: For example 192.168.0.12:1
  7. From the VNC client, wait for the following message to display "Press F12 for boot menu". If too late, restart the VM by clicking the button.
  8. Press F12, then select the USB device.
  9. Follow the on-screen instructions.
    Caution:
    To reduce the wear-and-tear of the Solid State Drive:
    • On Linux OS, disable memory swapping or at least set swappiness to 0.
    • On Windows OS, disable the virtual memory.
    Note: If the Solid State Drive fails because it is inadequately used by a third party software or the operating system, the warranty of the Mediatrix unit will no longer be valid.
    Note: The installation can take more than an hour depending on the image you are installing.
Result

The virtual machine will be started only if it is started manually




Top

Importing an ISO image to the Unit File Management System

Context

If the ISO Image is larger than 10mb, use the Importing an ISO Image Larger than 10mb to the Unit File Management System.

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 vm/drives/.
  4. Browse to the location of the ISO file containing the operating system (OS) to install on the virtual machine.
  5. Click Import.
    Note: A factory reset will remove the file from the Internal filestable.
Result
The imported ISO file will appear in the VM Files table, under Management/File.


Top

Disabling Swap on Linux

Context
Disabling swapping in the Operating System will optimise the virtual machine in such a way to reduce the wear-and-tear of the Solid State Drive.
Note: If the Solid State Drive fails because it is inadequately used by a third-party software or the operating system, the warranty of the Mediatrix unit will no longer be valid.
Steps
  1. Open the VNC Client located on a computer of the network connected to the unit.
    Note: UltraVNC Viewer, TightVNC Viewer and VNC Viewer are presently supported.
  2. Open .../etc/sysctl.conf file
  3. Add vm.swappiness = 0 to the file.
  4. Open ... /etc/fstab.
  5. Add noatime to the following lines
    1. § UUID=32b414c0-This-is-an-example / ext4 defaults, noatime 1 1
    2. § UUID=b4598e44-This-is-an-example /boot ext4 defaults, noatime 1 2
  6. Comment out
    1. § # UUID=72355f7a-497d-This-is-an-example swap swap defaults 0 0
  7. Use the Shutdown command and then restart the Virtual Machine.
    IMPORTANT: Do no use the Linux reboot command as the filesystem may not get mounted properly.

Top

Virtual Machine Modification

Modifying the Virtual Machine Configuration

Steps
  1. Go to System/VM.
  2. In the Virtual Machine Configuration table, modify the fields as required.
  3. Click Apply.
Result
The next time the virtual machine will be used, the new parameter values will be applied.

Top

Parameters

Although the services can be configured in great part in the web browser, some aspects of the configuration can only be completed with the MIB parameters by:
  • using a MIB browser, such as the Mediatrix Unit Manager Network (UMN);
  • using the CLI;
  • creating a configuration script containing the configuration parameters.

Top

Top

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.

To access the configuration notes, go to Configuration notes.

Top

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 © 2022 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.

1 a minimum of 4 GB is required to use a VM
2 a minimum of 32 GB is required to use a VM