User Guide 5/1553-AXM10104/1 Uen AM
[ Topics hidden with current filter selection ]

vMRF Configuration Management
Virtual Multimedia Resource Function

Contents


1 General vMRF Configuration

This section describes general vMRF configuration procedures.

1.1 Create a SignalingIpPool

This procedure describes how to create a SignalingIpPool MO for IP addresses reserved for the signaling interface.

Prerequisites

  • An Ericsson Command-Line Interface (ECLI) session in Exec mode is in progress.

Steps

  1. In the MOM, navigate to ManagedElement=1,Transport=1:
    >ManagedElement=1,Transport=1
  2. Enter Config mode:
    (ManagedElement=1,Transport=1)>configure
  3. Create a SignalingIpPool MO for the signaling network:
    (config-ManagedElement=1,Transport=1)>SignalingIpPool=1
  4. Define the starting value of the IP pool range:
    (config-ManagedElement=1,Transport=1,SignalingIpPool=1)>ipPoolRangeStart=<IP_Pool_Start_Address>
    Note: The IP pool range starting value can only be an IPv4 address.
  5. Define the ending value of the IP pool range:
    (config-ManagedElement=1,Transport=1,SignalingIpPool=1)>ipPoolRangeEnd=<IP_Pool_End_Address>
    Note: The IP pool range ending value can only be an IPv4 address.
  6. Add values for the following attributes of the SignalingIpPool MO:
    • gatewayAddress

    • ipPoolState

    • subnetMaskLength

  7. Commit the changes:
    (config-ManagedElement=1,Transport=1,SignalingIpPool=1)>commit

1.2 Create an MrfNetworkIpPool

This procedure describes how to create an MrfNetworkIpPool MO for IP addresses reserved for media interfaces.

Prerequisites

  • An Ericsson Command-Line Interface (ECLI) session in Exec mode is in progress.

Steps

  1. In the MOM, navigate to ManagedElement=1,MediaResourceFunction=1,MrfConfiguration=1, enter Config mode, and create a MrfNetworkIpPool MO:
    >ManagedElement=1,MediaResourceFunction=1,MrfConfiguration=1
    (ManagedElement=1,MediaResourceFunction=1,MrfConfiguration=1)>configure
    (config-ManagedElement=1,MediaResourceFunction=1,MrfConfiguration=1)>MrfNetworkIpPool=1
  2. Navigate to the ManagedElement=1,MediaResourceFunction=1,MrfConfiguration=1,MrfNetworkIpPool=1 MO and enter Config mode:
    ManagedElement=1,MediaResourceFunction=1,MrfConfiguration=1,MrfNetworkIpPool=1
    (ManagedElement=1,MediaResourceFunction=1,MrfConfiguration=1,MrfNetworkIpPool=1)>configure
  3. Define the starting value of the IP pool range:
    (config-ManagedElement=1,MediaResourceFunction=1,MrfConfiguration=1,MrfNetworkIpPool=1)>ipPoolRangeStart=<IP_pool_start_address>
    Note: The IP pool range starting value can be an IPv4 or an IPv6 address.
  4. Define the ending value of the IP pool range:
    (config-ManagedElement=1,MediaResourceFunction=1,MrfConfiguration=1,MrfNetworkIpPool=1)>ipPoolRangeEnd=<IP_pool_end_address>
    Note: The IP pool range ending value can be an IPv4 or an IPv6 address.
  5. Set the value of the ipPoolState attribute:
    (config-ManagedElement=1,MediaResourceFunction=1,MrfConfiguration=1,MrfNetworkIpPool=1)>ipPoolState=<value>
  6. Set the value of the nextHopAddress attribute:
    (config-ManagedElement=1,MediaResourceFunction=1,MrfConfiguration=1,MrfNetworkIpPool=1)>nextHopAddress=<IPv4_or_IPv6_nexthop_address>
  7. Set the value of the subnetMaskLength attribute:
    (config-ManagedElement=1,MediaResourceFunction=1,MrfConfiguration=1,MrfNetworkIpPool=1)>subnetMaskLength=<subnet_mask_length_value>
  8. Commit the changes:
    (config-ManagedElement=1,MediaResourceFunction=1,MrfConfiguration=1,MrfNetworkIpPool=1)>commit

2 Configure the Compression for Performance Management XML Files

Performance Management (PM) XML files created by the vMRF are not compressed by default. As they are replicated to all VMs, moving uncompressed files causes unnecessary load to the system. The use of uncompressed files also consumes lot more disk space. To avoid this, compression is recommended to be used for PM XML files.

Note: The maximum number of PM files stored by the system is 500. When this limit is reached, the VNF deletes the oldest file before creating a new one.

Compression of PM files created by existing PM jobs can be set by the following steps:

Note: Compression can be also set when creating new PM jobs. For more information on creating new PM jobs, see Operating Instructions Create Measurement Collection Job. After creating a new measurement collection job based on the document, apply Step 4 from the current document and return to the procedure in Create Measurement Collection Job.

Steps

  1. List all active PM jobs using Operating Instructions List Performance Management Jobs.

Repeat the following steps for each job listed in Step 1.

  1. Navigate to the relevant PmJob MO:

    >dn ManagedElement=<VNF_Name>,SystemFunctions=1,Pm=1,PmJob=<Pm_Job_Name>

  2. Enter Config mode:

    (PmJob=1)>configure

  3. Set the compressionType attribute to GZIP:

    (config-PmJob=<Pm_Job_Name>)>compressionType=GZIP

  4. Commit the changes:

    (config-PmJob=<Pm_Job_Name>)>commit

3 vMRF Configuration Export and Import

This section describes exporting and importing vMRF configuration, as shown in Figure 1.

During the process, the following items are exported and imported from the Managed Object Management (MOM) model:
  • MO configuration data

  • certificates

  • credentials

The exported archive file includes the certificates and credentials installed under the CertM MO, with the appropriate metadata to reinstall them on import. The default format of the archive file is tar.gz.

Figure 1   Configuration Export and Import

3.1 Export vMRF Configuration

A configuration export of an existing VNF can be used for backup purposes or as a way of migrating the VNF configuration to a new VNF when performing an upgrade.

Prerequisites

  • A configured and operational vMRF VNF is available and you can log in to it as emergency user, using SSH.

Steps

  1. Open an SSH connection to the O&M IP address of the VNF instance using the following command:
    ssh <user_ID>@<O&M_IP_address>
  2. Export the configuration data in one of the following ways:
    Options Command and result

    Export the configuration data into a specified .tar.gz archive file (the default and recommended format)

    Use the following command:

    /opt/mrf_director/mrf_export_conf.py/ home/<user_ID>/<output_file_without_extension>

    The path to the output archive file is /home/<user_ID>/<output_file_without_extension>.tar.gz

    Export the configuration data with a time stamp as a file name

    Use the following command:

    /opt/mrf_director/mrf_export_conf.py /home/<user ID>/mrf_conf_{timestamp}

    The path to the output archive file is /home/<user_ID>/mrsv_conf_YYYY-MM-DD_hh-mm-ss.tar.gz


  3. If you want to use the exported configuration file in another VNF, copy it out of the file system of the VNF using, for example, the scp command:
    scp <user_ID>@<O&M_IP_address>:/home/<user_ID>/mrf_conf.tar.gz .

    Result: The example configuration file mrf_conf.tar.gz is copied to the current directory from the /home/<user_ID>/ folder in the file system of the vMRF VNF.

3.2 Import vMRF Configuration

A configuration import can be used for rapid deployment of new VNF instances when initial configuration has been prepared in advance or during an upgrade process to import a previously exported VNF configuration.

Prerequisites

  • An operational vMRF VNF is available and you can log in to it as emergency user, using SSH.

  • A file containing vMRF configuration data is available.

Steps

  1. If the configuration data file is not available in the file system of the VNF, copy a file to the VNF using, for example, the scp command:
    scp mrf_conf.tar.gz <user_ID>@<O&M_IP_address>:/home/<user_ID>

    Result: The configuration file mrf_conf.tar.gz is copied from the current directory to the /home/<user_ID>/ folder in the file system of the vMRF VNF.

  2. Open an SSH connection to the O&M IP address of the vMRF VNF instance using the following command:
    ssh <user_ID>@<O&M_IP_address>
  3. Run the following command:
    /opt/mrf_director/mrf_import_conf.py /home/<user ID>/mrf_conf.tar.gz

4 Auto-Healing

If Auto-Healing is configured, a faulty VM in the cluster and its resources are recreated automatically, according to alarm notifications sent to ENM. If the COM SA, CLM Cluster Node Unavailable alarm sent to ENM matches one of the configured autostart rules, the VNF-LCM starts a healing workflow instance with the specified parameters. The Auto-Healing autostart rule file must be activated so that VNF-LCM can pair the appropriate workflows to alarms automatically sent by ENM. For more information on activating the autostart rule file, see VNF Life Cycle Management.

5 Manual Scaling

This section describes how to perform manual scaling in the VNF cluster by increasing or decreasing the number of VMs in a cluster.
Note: Continue with these procedures only if the VNF cluster to be scaled-out or scaled-in was deployed manually.

5.1 Manual Scaling in OpenStack

This section describes how to perform manual scaling in OpenStack environment.

5.1.1 Scale-out Procedure

Prerequisites

  • The vMRF VMs to be scaled-out are configured as MRFP (Media Resource Function Processor) nodes in the MTAS.

    A vMRF VM identifies itself to the MTAS with a Message Id (MId) that contains the vMRF VM signaling IP address and SCTP port. Typically, the whole range of signaling IP addresses (the signaling subnet) configured in the OpenStack for the new vMRF VNF, is configured as MRFP nodes in the MTAS.

    For more information on adding an MRFP node in MTAS, see section Add MRFP in MTAS Media Control Management Guide.

Steps

  1. Log in to the OpenStack CLI.
  2. Use the heat stack-update command to increase the size of the VNF, as shown below.
    heat stack-update <stack_name> -x -P payload_instance_count=<new_number_of_VMs>
    Note: This command only updates the payload_instance_count parameter, it is not required to specify the environment file.
  3. Log in to the dashboard and check that the VMs belonging to the VNF are visible in the Network Topology view.
  4. Check the status of the VNF by running the following command:

    verify_vmrf_cluster_status.py

Results

When a VM is added to the cluster during scale-out, the following VM-related MOs are created automatically:

5.1.2 Scale-in Procedure

Steps

  1. Use the following command to list all the VMs that are part of the scaling domain within the specific VNF:
    heat output-show <stack_name> resource_names

    Note the name of the VM to be deleted.

  2. Identify the UUID of the VM, by using one of the following options:
    • Open the OpenStack Dashboard. The UUID and name is shown for each VM.

    • Log in to the OpenStack CLI and use the nova list command. The UUID and name is shown for each VM in the printout.

  3. To minimize traffic impact, lock the MrfInstance MO that represents the VM by using the instructions described in Lock a VM.

    The MrfInstance MO that represents the VM has a reference to the ComputeResource MO with the UUID identified before.

  4. Clean up the VM-related configuration before the removal of the VM using the following command:
    /usr/bin/scale_in_node.sh <VM_UUID>
  5. Log in to the OpenStack CLI and use the heat stack-update command to decrease the size of the VNF by deleting the selected VM:
    Note: In VNF clusters with three or more VMs, scale in the VMs one by one (that is, using the option payload_instance_count=<current_value_minus_one>), or directly to two VMs (using the option payload_instance_count=<2>) in the cluster. The reason for this is that if all but one VMs are scaled-in in one operation in clusters with three or more VMs, the remaining VM is restarted.

    heat stack-update <stack_name> -x -P payload_instance_count=<new_number_of_VMs> -P payload_scaling_in_list=<Locked_VM_index>

    The <Locked_VM_index> is the last number in the name of the selected VM. For example, if the name of the VM is mrsv-3, the value of 3 must be used. If the payload_scaling_in_list parameter is not specified, the VM with the highest index is deleted automatically.

    Note: When using the heat stack-update command with option -x, the templates, parameters, and environment files of the current stack are used for stack update. The value provided for option -P overwrites the current parameter value in the stack.
  6. Log in to the dashboard and check that the VM is not visible in the Network Topology view anymore.

Results

When a VM is removed from the cluster during scale-in, the following VM related MOs are deleted automatically:

5.2 Manual Scaling in VMware

This section describes how to perform manual scaling in VMware® environments.

The procedures are described separately for pure vSphere® environment which is managed by vCenter®, and vCloud® environment which is managed by vCloud director

5.2.1 Scale-out Procedure in vCenter Environment

Steps

  1. Add a VM to the cluster in VMware® vApp, using the VM template created during the deployment procedure.
  2. If the vMRF VNF has been deployed by using the manual IP address allocation method, configure IP addresses for the VM.
  3. Power on the VM.
  4. Check the status of the VNF by running the following command:

    verify_vmrf_cluster_status.py

Results

When a VM is added to the cluster during scale-out, the following VM related MOs are created automatically:

5.2.2 Scale-in Procedure in vCenter Environment

  1. Shut down the guest OS of the VM from the cluster in VMware® vApp.
    Note: In VNF clusters with three or more VMs, scale in the VMs one by one to keep two VMs in the cluster. The reason for this is that if all but one VMs are scaled-in in one operation in clusters with three or more VMs, the remaining VM is restarted.

    Shutting down a VM can impact the traffic.

    To minimize the traffic impact, lock the VM to be deleted from the cluster. Lock the MrfInstance MO that represents the VM.

  2. Clean up the VM-related configuration before the removal of the VM using the following command:
    /usr/bin/scale_in_node.sh <VM_UUID>
  3. Delete the VM from the disk.

Results

When a VM is removed from the cluster during scale-in, the following VM related MOs are deleted automatically:

5.2.3 Scale-out Procedure in vCloud Environment

  1. Click on the vApp name on the My Cloud > vApps tab.
  2. Select Add VM to add VMs.
    1. Select the VM in the Catalog.
    2. Click Add to add new VMs.
    3. Click Next.
  3. Map networks to vNICs based on the settings of the existing VM, select IP address allocation method, and click Next.
    Note: If manual IP address allocation is used, provide IP addresses for the networks, and make sure that these IP addresses are not colliding with IP addresses configured in VM Guest Properties after scale-out but before power-on.

    IPv4, IPv6, or both addresses can be assigned to the user plane network towards media networks.

    IPv4 addresses must be assigned to the other networks.

    The networks must be mapped to vNICs according to the following table:

    vNIC

    Network Type

    vNIC0

    VNF-internal

    vNIC1

    O&M

    vNIC2

    Signaling

    vNIC3

    User plane towards media networks

  4. Power on the VM.

Results

When a VM is added to the cluster during scale-out, the following VM related MOs are created automatically:

5.2.4 Scale-in Procedure in vCloud Environment

  1. Click on the vApp name in My Cloud.
  2. In the left pane, click VMs.
  3. Select a VM, right-click it, and select Power Off.
  4. Power off the VM to be scaled in.
    Note: In VNF clusters with three or more VMs, scale in the VMs one by one to keep two VMs in the cluster. The reason for this is that if all but one VMs are scaled-in in one operation in clusters with three or more VMs, the remaining VM is restarted.

    Powering off a VM can impact the traffic.

    To minimize the traffic impact, lock the VM to be deleted from the cluster. Lock the MrfInstance MO that represents the VM.

  5. Clean up the VM-related configuration before the removal of the VM using the following command:
    /usr/bin/scale_in_node.sh <VM_UUID>
  6. Click on the vApp name on the My Cloud > vApps tab.
  7. Select a vApp, right-click it, and select Open.
  8. On the Virtual Machines tab, select a VM, right-click it, and select Delete.
  9. Click Yes.

Results

When a VM is removed from the cluster during scale-in, the following VM related MOs are deleted automatically:

6 Lock a VM

This procedure describes how to lock a VM.

Note: In the procedure below, after modifying the administrativeState attribute, the VMs are immediately locked and all ongoing traffic on the VMs stops.

Prerequisites

  • Other upgrade operations are not ongoing, for example, software upgrade.

  • An Ericsson Command-Line Interface (ECLI) session in Exec mode is in progress.

Steps

  1. Open an SSH connection to the O&M IP address of the vMRF VNF using the following command:
    ssh <user_ID>@<O&M_IP_address>
  2. Start a session by issuing the cliss command.
  3. Navigate to the MrfInstance MO that represents the VM and enter configure mode:
    >ManagedElement=1,MediaResourceFunction=1,MrfResource=1,MrfInstance=<mrfInstanceId>
    (MrfInstance=<mrfInstanceId>)>configure
  4. Modify the value of the administrativeState attribute:
    (config-MrfInstance=<mrfInstanceId>)>administrativeState=<LOCKED>
  5. Commit the changes:
    (config-MrfInstance=<mrfInstanceId>)>commit
    The VM is locked immediately and all ongoing traffic from the VM is lost.
    Note: When the administrativeState attribute is changed to LOCKED, the operationalState attribute of the MrfInstance is automatically changed to disabled.

7 Announcement Configuration

This section describes the procedures for announcement configuration. If the announcement service provided by vMRF is used, this is a mandatory configuration task.

7.1 Announcement Storage

The announcement files can be stored either in an external announcement storage server, or locally, in the vMRF VMs. The storage server solution is recommended for availability reasons. The local storage should be utilized when remote storage is not available.

7.1.1 Announcement Storage Server

The recommended solution for the storage for announcements is a directory placed in a storage server, which is accessible from each VM in the cluster. A vMRF VM connects to the server with sshfs (Secure SHell FileSystem), and mounts a specified directory path. The announcement files needed for playing the announcements are stored under this directory. The announcement storage is enabled by default for vMRF.

The prerequisites for the storage server are the following:

  • ssh connection support with public and private keys
  • authentication of the ssh connections from the vMRF VMs
  • defined user name and ssh public key
  • the public key is appended to the authorized keys file using the following command:

    cat .ssh/<public_key_file_name> >> .ssh/<authorized_keys_file_name>

  • path for the announcement files

Configuration of the announcement storage in the vMRF is performed during instantiation by filling in the relevant HOT template parameters. Following parameters must be defined:

  • user name for the announcement storage server
  • ssh private key for the username
  • IP address of the announcement storage server
  • server port of the announcement storage server
  • mount directory path
  • remote server ssh host key fingerprint

For more information on the HOT template configuration see the relevant deployment instructions.

7.1.2 Local Storage

If there is no storage server available in the cloud installation, the announcement files can also be stored locally in the vMRF VMs.

In this case, the HOT template parameters for announcement storage must not be defined at deployment. If the parameters are missing, the vMRF VMs automatically start up configured for local storage of announcement files. Announcement files can be added to the VMs by using the secure copy (scp) command to copy the files to the /cluster/storage/announcements directory on the active SC. The vMRF distributes the contents of this directory from the active SC to all VMs.

If local storage is used, the announcement files must be backed up and copied during the upgrade process manually, because they are not exported and are therefore deleted during redeployment.

7.2 Modify the Default Language Code

This procedure describes how to modify the default language code of announcements. The default language code is used as language code for the basic and variable announcements in case the H.248 (or SIP) message does not contain any language code for the requested announcement.

Prerequisites

  • An Ericsson Command-Line Interface (ECLI) session in Exec mode is open.

Steps

  1. In the MOM, navigate to the Announcements MO and enter configure mode:

    >ManagedElement=1,MediaResourceFunction=1,Announcements=1

    (Announcements=1)>configure

  2. Modify the value of the defaultLanguageCode attribute:

    (config-Announcements=1)>defaultLanguageCode=<value>

    Note: The language code has the format of the RFC 5646 language tag.
  3. Commit the changes:

    (config-Announcements=1)>commit

7.3 Basic Announcements

Basic announcements are identified by the announcement ID and a language code. The combination of announcement ID and language code form a unique identity for the basic announcement. For multi-language announcements the announcement ID is the same in multiple instances of BasicAnnouncement MOs, but the language code is different.

The audio files must be available in the storage server or in the local storage before basic announcements are created. A separate BasicAnnouncement MO must be created for each audio file.

The file names and the file paths of the associated audio files are specified at basic announcement creation.

Note: The file names are case sensitive, and special characters, such as space, are not allowed.

7.3.1 Create a Basic Announcement

This procedure describes how to create a BasicAnnouncement MO, that represents a single audio announcement file.

Prerequisites

  • An Ericsson Command-Line Interface (ECLI) session in Exec mode is open.

  • The announcement files are available on the announcement storage server or in the local storage.

Steps

  1. In the MOM, navigate to ManagedElement=1,MediaResourceFunction=1,Announcements=1,BasicAnnouncements=1 and create a BasicAnnouncement MO for each audio announcement file.
  2. For each created BasicAnnouncement MO, define values for the following attributes:
    • announcementId

      An identity for the basic announcement. The combination of the announcementId and languageCode attributes form a unique identity for the basic announcement.

    • basicAnnouncementId

      The value component of the RDN.

    • fileName

      The name of the announcement file.

    • filePath

      The relative file path to the directory where the announcement file is stored. The value of this attribute is relative to the announcement_storage_server_path attribute in the deployment template. In case of local storage the value of the attribute is relative to /cluster/storage/announcements.

      Example: basic/en-GB

    • languageCode

      Language code of the basic announcement. The combination of the announcementId and languageCode attributes form a unique identity for the basic announcement.

      Language code has the format of an RFC 5646 language tag.

      Example: en-GB

    The following attributes are optional:
    • duration

      The amount of time the announcement is to be played in milliseconds. If the specified duration is greater than the overall length of the announcement, the announcement is repeated until the duration is elapsed. The playing time is also dependent on the value of the iteration attribute. The selected playing time is always the shortest possible alternative.

    • iteration

      The number of times the announcement is repeated when played to the user.

    • userLabel

      Label for free use.

    See table Basic Announcement Attributes for details.

7.4 Variable Announcements

Variable announcements are identified by the variable type and the language code. The combination of variable type and language code form a unique identity for the variable announcement. For multi-language announcements the variable type is the same in multiple instances of VariableAnnouncement MOs, but the language code is different.

The audio files and logic files have to be available in the storage server or in the local storage before variable announcements are created. A separate VariableAnnouncement MO must be created for each variable announcement logic file.

Note: It is not necessary to create BasicAnnouncement MOs for the audio files used for variable announcements.

The file names and the file paths of the associated logic files are specified at variable announcement creation.

Note: The file names are case sensitive, and special characters, such as space, are not allowed.

7.4.1 Logic File Type Examples

The following examples show how to create logic files in Lua for variable announcements.

Example Logic File for Variable Announcement Type Digits

Example Logic File for Announcement Type Date

Example Logic File for Announcement Type Time

Example Logic File for Announcement Type Number

Example Logic File for Announcement Type Money

7.4.2 Create Logic Files

A logic file contains the algorithm logic for a variable announcement in a form that can directly be interpreted. When a play request for a variable announcement is received by the Announcement Service, it uses the logic in the associated algorithm file, together with data sent along with the play request, to determine which output to generate.

As a service, Ericsson can provide logic files for variable announcements, or, optionally, they can be created using the Lua scripting language, based on the examples shown in Logic File Type Examples. The Lua version used in vMRF is 5.3.

For more information on the Lua scripting language, see http://www.lua.org.

Steps

  1. Create the logic file for the variable announcement type needed, based on the example files in Logic File Type Examples.
  2. Validate the logic file using the Logic File Validator (LFV) tool, by issuing the following commands for each logic file:
    • lua logic-file-validator --check-syntax <logic file name>

    • lua logic-file-validator --execute <logic file name>

    • lua logic-file-validator --execute <logic file name> <logic input>

    For more information on the LFV tool, see Logic File Validator Tool.

  3. Copy the logic file to the storage server.
    Note: The path of the logic files is needed during the creation of VariableAnnouncement MOs.

7.4.2.1 Lua Restrictions in Variable Logic Definition

The following restrictions apply for variable announcement logic files:
  • The functions defined in logic files are the following:

    get_file_list()  

    This function returns a table with all audio files that are used by the logic file.

    get_play_list(input)  

    This function returns a table with all audio files that are played for a specific input.

  • The execution environment for the variable logic is restricted to the following:

    • Basic library use is restricted to following functions:

      • pairs

      • ipars

      • tonumber

      • error

      • type

    • String manipulation library is fully available through the name string, for example:

      string.sub(input, 1, 2)

    • Table manipulation library is fully available through the name table, for example:

      table.insert(file list, "file2")

7.4.3 Logic File Validator Tool

The Logic File Validator (LFV) tool is used to validate logic files written by the operator without involving Ericsson in the process. It is available in the vMRF delivery package as a single file in the tools directory. The tool file name is logic-file-validator. In order to use the LFV tool, the Lua interpreter version 5.2 or higher needs to be downloaded and installed from http://www.lua.org.

To validate a logic file, the operator must verify that both the syntax and the behavior of the logic file is correct. A logic file that is validated by the LFV tool is compatible with the vMRF.

The LFV tool can be used by issuing the lua logic-file-validator command in the CLI.

Options without arguments:
-h, --help  

Prints the help message and exits the LFV tool.

Options with mandatory arguments:
--check-syntax <logic_file_name>  

This option checks whether the logic file syntax is correct and the mandatory functions get_file_list() and get_play_list(input) exist.

--execute <logic_file_name>  

This option tests logic file execution without input, and prints the list of audio files used by the logic file.

--execute <logic_file_name> <input>  
This option tests logic file execution with the given input. It also prints the list of audio files to be played for the given input.
Note: It is recommended to verify all inputs to test the entire code in the logic file.

In case of errors, an error message with specific information is printed.

7.4.3.1 Check Logic File Syntax

The following procedure describes how to check logic file syntax.

During logic file syntax validation, the LFV tool checks the following:
  • There are no Lua syntax errors in the logic file

  • The logic file contains mandatory functions required by vMRF

Steps

  1. Check logic file syntax with the LFV tool by issuing the following command: lua logic-file-validator --check-syntax <logic file name>

    Example

    The following example shows a successful syntax check:

    username@hostname:/home/username > lua logic-file-validator --check-syntax test/logicFiles/Digits_en-GB.lua
    SUCCESS
    

    Example

    The following example shows checking a logic file with a missing mandatory function:

    username@hostname:/home/username > lua logic-file-validator --check-syntax test/logicFiles/get_file_list_missing.lua
    lua: logic-file-validator:55: Function 'get_file_list()' not defined in logic file
    stack traceback:
            [C]: in function 'error'
            logic-file-validator:55: in function 'execute_action'
            logic-file-validator:132: in function 'main'
            logic-file-validator:148: in main chunk
            [C]: in ?
    

7.4.3.2 Verify Logic File Behavior

The following procedure describes how to check logic file behavior.

During logic file behavior check, the LFV tool prints the following information:
  • A list of audio files used in the logic file

  • A list of audio files to be played for the given input

  • Prohibited functions in the logic file, if any

Steps

  1. Verify that all audio files used in the logic file are listed in the output of the lua logic-file-validator --execute <logic file name> command.

    Example

    The example below shows the audio files used by the logic file.

    username@hostname:/home/username > lua logic-file-validator --execute test/logicFiles/Digits_en-GB.lua 
    basic/en-GB/0.wav
    basic/en-GB/1.wav
    basic/en-GB/2.wav
    basic/en-GB/3.wav
    basic/en-GB/4.wav
    basic/en-GB/5.wav
    basic/en-GB/6.wav
    basic/en-GB/7.wav
    basic/en-GB/8.wav
    basic/en-GB/9.wav
    
  2. Verify that the output of the lua logic-file-validator --execute <logic file name> <logic input> command contains all audio files used for the input.

    Example

    The example below shows the audio files used in the logic file only for the given input.

    username@hostname:/home/username > lua logic-file-validator --execute test/logicFiles/Number_en-GB.lua 234567
    234567
    basic/en-GB/2.wav
    basic/en-GB/100.wav
    basic/en-GB/30.wav
    basic/en-GB/4.wav
    basic/en-GB/1000.wav
    basic/en-GB/5.wav
    basic/en-GB/100.wav
    basic/en-GB/60.wav
    basic/en-GB/7.wav
    
  3. Verify that the logic file does not use prohibited functions.

    Example

    The following example shows validation error caused by a prohibited function in the logic file.

    username@hostname:/home/username > lua logic-file-validator --execute test/logicFiles/dofile_not_allowed.lua 123
    lua: logic-file-validator.lua:73: test/logicFiles/dofile_not_allowed.lua:31: attempt to call global 'dofile' (a nil value)
    stack traceback:
            [C]: in function 'error'
            logic-file-validator.lua:73: in function 'execute_action'
            logic-file-validator.lua:138: in function 'main'
            logic-file-validator.lua:148: in main chunk
            [C]: in ?
    

7.4.4 Create a Variable Announcement

This procedure describes how to create a VariableAnnouncement MO, that represents a single variable announcement type.

Prerequisites

  • An Ericsson Command-Line Interface (ECLI) session in Exec mode is open.

  • The announcement files are available on the announcement storage server or in the local storage.

Steps

  1. In the MOM, navigate to ManagedElement=1,MediaResourceFunction=1,Announcements=1,VariableAnnouncements=1 and create a VariableAnnouncement MO for each variable announcement type.
  2. For each created VariableAnnouncement MO, define values for the following attributes:
    • variableAnnouncementId

      The value component of the RDN.

    • logicFileName

      The name of the variable announcement logic file.

    • logicFilePath

      The relative file path to the directory where the variable announcement logic file is stored. The value of this attribute is relative to the announcement_storage_server_path in the deployment template. In case of local storage the value of attribute is relative to /cluster/storage/announcements.

      Recommended value: variable/<languageCode>/

      Example: variable/en-GB

    • languageCode

      The language code of the variable announcement.

      The combination of the variableAnnouncementType and languageCode attributes form a unique identity for the variable announcement.

      The language code has the format of an RFC 5646 language tag.

      Example: en-GB

    • variableAnnouncementType

      Type of the variable announcement.

      The combination of the variableAnnouncementType and languageCode attributes form a unique identity for the variable announcement.

    The following attribute is optional:
    • userLabel

      Label for free use.

    See table Variable Announcement Attributes for details.

7.5 Handling of Announcement Files

The audio announcement file is created by recording an announcement. The sample rate of the audio announcement has to be 16 kHz and the audio mode Mono. The audio announcement has to be encoded in 16 bit 16 kHz PCM and stored in Waveform Audio File Format (WAV).

When the audio files for basic and variable announcements are stored to the storage server, the recommended directory structure for the stored audio files in the storage server is the following:

/announcement_storage/basic/en-GB

When using local storage, a similar directory structure must be created locally to ensure that vMRF can locate announcement audio files:

/cluster/storage/announcements/basic/en-GB

When the logic files for variable announcements are stored to the storage server, the recommended directory structure for the stored logic files in the storage server is the following:

/announcement_storage/variable/en-GB

When using local storage, a similar directory structure must be created locally to ensure that vMRF can locate variable announcement logic files:

/cluster/storage/announcements/variable/en-GB

Note: The announcement audio files are stored to cache for announcement playing. The cache refresh time is 15 minutes. After storing a new audio file with the same file name to the announcement storage, it can take up to 15 minutes before the new audio file is taken into use for announcement playing.

7.6 Converting Existing Audio Files to vMRF Supported Format

If there are existing audio files which needs to be migrated from native MRF nodes to be used in vMRF, for example in PCMA or PCMU encoded headerless format, they can be converted to vMRF supported WAV 16 bit 16 kHz PCM audio format files using for example Sound eXchange (SoX) audio editing software. SoX is available in many Linux distributions and also for macOS and Windows (https://sourceforge.net/projects/sox/).

Note: Conversion of PCMA or PCMU encoded (NB quality) audio files with SoX to WAV 16 bit 16 kHz PCM (WB quality) audio format files does not improve the audio quality from NB to WB. To achieve WB quality announcements, the announcements must be recorded in WB quality, and encoded and stored to WAV 16 bit 16 kHz PCM audio format.

An example using SoX from the command line in linux, macOS, or Windows for converting one headerless PCMA audio file to WAV 16 bit 16 kHz PCM audio format file:

#sox -c 1 -r 8000 -t al <INPUT_alaw> -r 16000 -b 16 -t wav <OUTPUT_linear_s16_16k>.wav

An example using SoX in linux and macOS converting all headerless PCMA audio files in a directory to WAV 16 bit 16 kHz PCM audio format files:

#for i in *; do sox -c 1 -r 8000 -t al ./$i -r 16000 -b 16 -t wav $i.wav; done

An example for linux and macOS for removing all non-WAV format files in the directory, after conversion of audio files to WAV 16 bit 16 kHz PCM audio format files:

#fdel . -type f -not -name '*.wav' -print0 | xargs -0 rm

Note: This command removes all files in the directory that do not have the wav file extension.

An example using SoX in Windows for converting all headerless PCMA audio files in a directory to WAV 16 bit 16 kHz PCM audio format files:

#for %i in (*) do sox -c 1 -r 8000 -t al .\%i -r 16000 -b 16 -t wav %i.wav

An example for removing all files without file extension in the directory, after conversion of audio files to WAV 16 bit 16 kHz PCM audio format files:

#del *.

Note: This command removes all files in the directory that do not have any file extension.

8 Modify Tone Parameters

The TsTone MO represents a tone as used by the Tone Sender (TS) service in the vMRF. An instance of this MO exists for each tone type supported by the VNF. The MO instances are created automatically by the system when the ToneSenderService MO instance is created. The TsTone parameters, for example, tone type, tone duration, frequencies, levels, play and pause times, can be changed. All parameters belonging to the TsTone MO, their value ranges and default values can be found under the TsTone MO in the MOM.

Prerequisites

An Ericsson Command-Line Interface (ECLI) session in Exec mode is in progress.

Steps

  1. In the MOM, navigate to the TsTone MO and enter configure mode:

    >ManagedElement=1,MediaResourceFunction=1,MsProcessing=1,ToneSenderService=1,TsTone=<toneId>

    (TsTone=<toneId>)>configure

  2. Modify the relevant attributes of the TsTone MO:

    (config-TsTone=<toneId>)><attribute>=<value>

  3. Commit the changes:

    (config-TsTone=<toneId>)>commit

9 Codec Configuration

9.1 Configure EVS

EVS configuration consists of the following activities:
  • Configuring EVS bandwidth and bit rate

9.1.1 Configure EVS Bandwidth and Bit Rate

This procedure describes how to configure allowed bandwidth range and maximum allowed bit rate for EVS to control EVS codec configuration and negotiation.

EVS codec negotiation is affected by bandwidth and bit rate configurations according to the following scenarios:
  • For incoming SDP offer, the common subset of the configured bandwidth and bit rate values, and the bandwidth and bit rate values received in the offer, are sent back in the SDP answer. The bandwidth and bit rate sent in the SDP answer are used for the media stream.

  • For outgoing SDP offer, the configured bandwidth and bit rate values are sent in the SDP offer. The bandwidth and bit rate values received in the SDP answer are used for the media stream.

Table 1   EVS Bandwidth and Bit Rate Combinations

Bandwidth

Bit Rate

Narrowband (300 – 3400 Hz)

5.9 kbps, 7.2 kbps, 8 kbps, 9.6 kbps, 13.2 kbps, 16.4 kbps, 24.4 kbps

Wideband (50 – 7000 Hz)

5.9 kbps, 7.2 kbps, 8 kbps, 9.6 kbps, 13.2 kbps, 16.4 kbps, 24.4 kbps, 32 kbps, 48 kbps, 64 kbps, 96 kbps, 128 kbps

Super-wideband (50 – 14000 Hz)

9.6 kbps, 13.2 kbps, 16.4 kbps, 24.4 kbps, 32 kbps, 48 kbps, 64 kbps, 96 kbps, 128 kbps

Fullband (20 – 20000 Hz)

16.4 kbps, 24.4 kbps, 32 kbps, 48 kbps, 64 kbps, 96 kbps, 128 kbps

Prerequisites

  • An ECLI session in Exec mode is open.

Steps

  1. Navigate to the MrfConfiguration MO and enter configure mode:
    >ManagedElement=1,MediaResourceFunction=1,MrfConfiguration=1
    (MrfConfiguration=1)>configure
  2. Create an MrfData MO:
    (config-MrfConfiguration=1)>MrfData=1
  3. Navigate to the EvsService MO and enter configure mode:
    >ManagedElement=1,MediaResourceFunction=1,MsProcessing=1,EvsService=1
    (EvsService=1)>configure
  4. Create an EvsConfData MO.
    (config-EvsService=1)>EvsConfData=1
  5. Set the supported bandwidth range:
    (config-EvsConfData=1)>supportedBwRange=<supported_bandwidth_range>
  6. Set the minimum value for the supported bit rate range:
    (config-EvsConfData=1)>supportedBitRatesRangeBegin=<value>
  7. Set the maximum value for the supported bit rate range:
    (config-EvsConfData=1)>supportedBitRatesRangeEnd=<value>
  8. Commit the changes:
    (config-EvsConfData=1)>commit
  9. Navigate to the MrfData MO in which the configuration changes are needed and enter configure mode:
    >ManagedElement=1,MediaResourceFunction=1,MrfConfiguration=1,MrfData=<1>
    (MrfData=1)>configure
  10. Modify the value of the attribute evsConfDataMoRef so that it refers to the EvsConfData created in Step 4.
    (config-MrfData=1)>evsConfDataMoRef="ManagedElement=1,MediaResourceFunction=1,MsProcessing=1,EvsService=1,EvsConfData=1"
  11. Commit the changes:
    (config-MrfData=1)>commit
  12. Navigate to the MrfH248Interface MO in which the configuration changes are needed, and enter configure mode:
    >ManagedElement=1,MediaResourceFunction=1,MrfH248Control=1,MrfH248Interface=1
    (MrfH248Interface=1)>configure
  13. Modify the mrfDataMoRef attribute of the MrfH248Interface MO so that it refers to the MrfData MO that contains a reference to the EvsConfData created in Step 4.
    (config-MrfH248Interface=1)>mrfDataMoRef="ManagedElement=1,MediaResourceFunction=1,MrfConfiguration=1,MrfData=1"
  14. Commit the changes:
    (config-MrfH248Interface=1)>commit