Extra configuration and maintenance tasks for the VMR self-service portal

This topic describes some additional configuration, customization and maintenance tasks for the VMR portal:

Upgrading to the latest version & release notes

To upgrade to the latest version we recommend that you:

  1. Power off your existing VMR portal.
  2. Perform a standard install of the new version
  3. Ensure the new version is working as expected, and then delete the old VM. If there are issues with the new version, you can power on the old versions to resume the previous service.

Release notes

Version 3 was released in October 2023.

  • Users can upload and apply their own branding packages to existing web app paths.

  • Updated user interface and features:

    • Ability to translate or modify all of the language strings displayed in the portal.
    • More flexibility over which VMR attributes can be modified via the portal.
    • Supports multiple users being able to manage the same VMR.
    • Keyboard navigation for accessibility.
    • Support for custom layouts.
  • The set of variables available to the aliases and join Jinja templates has been expanded to include any of the conference configuration resources.
  • The vmrportal service account now also requires May view system configuration and May modify system configuration permissions.
  • The underlying OS has been upgraded from Ubuntu 18.04 LTS to Ubuntu 22.04 LTS due to 18.04 being End Of Life. Note that the appliance does not support upgrades — you must redeploy to use this new version.
  • The background image file is now background.png (previously background.jpg).
  • Requires Pexip Infinity version 28 or later.
  • The installation process no longer reserves or uses the address range 172.17.0.0/28.
  • Hyper-V is no longer supported.

Version 2.1 of the VMR portal was released in May 2022. It contains the following new features:

  • New meeting layout options are now provided in your VMR settings. For information about changing your layout, go to Changing your VMR's settings.

Version 2 of the VMR portal was released in February 2021. It contains the following new features and fixes:

  • OpenLDAP support.
  • Hyper-V support.
  • Support for the Adaptive Composition layout (when used in conjunction with version 25 or later of Pexip Infinity) via a new layout option in the default layouts.template configuration. Note that resource usage on your platform's Conferencing Nodes could increase significantly if every user uses the Adaptive Composition layout simultaneously.
  • The vmrportal status maintenance command now provides more information such as network connectivity and certificate checks.
  • The Allow empty Host PINs configuration option is now respected when an end user changes their VMR's settings.
  • The VMR portal now performs case-insensitive matching of the VMR owner's email address against the LDAP mail attribute of the logged in user.

Rerunning the install wizard / customization steps

Many of the maintenance tasks to change the configuration of the VMR portal involve rerunning the installation wizard. However, if you only need to change the customizable options, you can just run the customization steps.

To rerun the installation wizard:

  1. Log in to the VMR portal through SSH or VMware console as user 'pexip'.

  2. You can run either the full installation wizard, or just the localization and customization options:

    • To rerun the full installation wizard:
      At the command prompt, run the installwizard command.
    • To run only the localization and customization options:
      At the command prompt, run the installwizard customize command.

  3. At each step the default values use the answers from the previous run (if they are still valid).

    Press ENTER to accept the default value, or enter the value you want to use instead.

  4. When all of the installation wizard steps have been completed, the appliance automatically reboots.

Customizing the language files (text localization)

You can customize the text strings that are displayed in the VMR portal to, for example, apply your own terminology or translate it to a different language.

When you install the VMR portal, step 5 of the installation allows you to refer to your own localization (locale) file. If you haven't prepared your own file at this stage you can perform a default installation and then rerun just the customization options later when your own file is ready.

The best way to prepare your own file is to base it on a copy of the existing default en_US.json file.

To create and upload your own locale file:

  1. Using the SCP file transfer protocol, download the default en_US.json file from /vmrportal/vmrportal/localization/en_US.json.
  2. Rename the file as appropriate and if required — for example en_ES.json for a Spanish translation. You do not have to rename the file, for example if you only want to apply your own terminology (in English).

    The language file contains a list of token and text string pairs. Text customizations are simply a matter of changing the text assigned to each token in your language file. To find the string to change, search in the language file for the text that needs to be changed, edit the text, and save your changes back to the same file. Do not change the token names or break the structure of the file. For example:

    "login_title": "Login" could be changed to "login_title": "Acceso"

    The language file must contain the complete set of tokens / text strings. If a token is missing the VMR portal will use the locale string in its place, e.g. "vmr_title" instead of "Virtual Meeting Room".

  3. Upload your new file to the /vmrportal/vmrportal/localization folder.
  4. Run the customize options wizard to refer to your new file.

Controlling web app path branding and VMR management via user groups

By default, the VMR portal allows a signed-in user to modify a VMR where their user’s email address is specified as the Owner’s email address on that VMR.

Version 3 of the VMR portal has an expanded authorization model that uses a concept of user groups to control which resources a nominated set of users are authorized to manage.

  • This is managed in Pexip Infinity via user groups that provide a many-to-many mapping between users and Pexip Infinity resources.
  • The controllable resources are VMR configuration (PINs, default layouts and so on), and web app branding paths.

When a user logs in to the VMR portal, it queries the Pexip Infinity management API for all the user groups that the user belongs to, and which resources those user groups contain. Those permitted resources then determine which VMRs the user is allowed to manage via the VMR portal (i.e. whether the VMR appears in the selection list of VMR Names), and whether the VMR portal allows the user to assign branding packages to web app branding paths (i.e. the set of paths that appear in the Branding Path selection list on the Manage Branding tab).

Note that the branding management feature does not apply branding to individual VMRs. It applies branding to the web app paths from where users enter the meeting ID/alias to join a VMR.

Using user groups to control access to VMR properties and branding requires v33 or later of Pexip Infinity. Note that users can still manage the properties of their own VMRs if they match the Owner’s email address on that VMR.

Creating user group mappings

User group mappings are configured in Pexip Infinity, where you can add one or more users to a user group and then associate that user group with one or more Pexip Infinity resources.

To create user group mappings:

  1. In the Pexip Infinity Administrator interface, go to the User Group page at https://<manageraddress>/admin/platform/usergroup/ (you have to enter the URL manually — there is no route to this page via the menus).
  2. Select Add User Group.
  3. Enter a Name and optional Description for the user group.

  4. From the list of Available Users, choose the users you want to include in the group.

    The users selected here are given increased privileges that are normally reserved for system administrators, including the ability to upload branding packages to Pexip Infinity. This means these users will have the power to attempt to upload malicious webapp packages.

  5. Add the associated resource In the User Group Mappings section:

    1. Select the Resource — either conference or webappalias.

      All resources are listed here, but the only resources currently supported in the VMR portal for user group mappings are conference and webappalias (a webappalias is a web app branding path).

    2. Specify the complete Resource URI.

      The Resource URI autofills with the path stem of that resource type (/api/admin/configuration/v1/conference/ or /api/admin/configuration/v1/webapp_alias/) but you need to specify the full resource ID of the conference (VMR) or webappalias (path) that you want to allow this user group to manage, by adding the resource object ID to the end of the URL.

      For example: /api/admin/configuration/v1/conference/12/ or /api/admin/configuration/v1/webapp_alias/3/

      The resource object IDs can be seen in the URL of the resource when you view it in the Administrator interface, for example: https://mgr.example.com/admin/platform/webappalias/3/change/.

    3. Enter an optional Description for the resource.

  6. If you want to associate another resource with the group, select Add another User Group Mapping, and repeat the previous step.

    If, for example, you want to allow the users in that group to manage three VMRs, you need to specify three mappings — one mapping (i.e. a resource URI) for each of the three VMRs.

  7. Select Save when you have completed adding all of the resource mappings.

You can return to this page later and add or remove users and resources for this group.

Additional maintenance commands

You can run a selection of maintenance commands against the VMR portal (for example to view troubleshooting information):

  1. Log in to the VMR portal server through SSH or VMware console as user 'pexip'.

  2. To view the available options run the command:

    sudo vmrportal

    and then run the desired command, for example:

    sudo vmrportal status

Viewing logs

Logs from the VMR portal service are located in /var/log/syslog.

You can view logs for just the VMR portal (rather than the whole syslog) with this command:

sudo journalctl -u vmrportal

Patching the operating system for the latest security bugs

We recommend that you keep the appliance's Operating System patched against the latest security bugs. The frequency with which you check for patches depends upon your local security policies but we recommend at least once per month, or whenever an important or critical CVE (Common Vulnerabilities and Exposures) has been resolved in Ubuntu.

Note that some updates may need some of the system services to be restarted or require a reboot of the VM, so we recommend performing these updates when a potential temporary loss of service is acceptable.

To install the latest security patches:

  1. Take a VM snapshot of the appliance.
  2. Log in to the server through SSH or VMware console as user 'pexip'.

  3. Run the following command:

    sudo apt-get update && sudo apt-get dist-upgrade

  4. Delete the snapshot after 1-2 days, when it has been confirmed that the patches have not had any detrimental effect.

Additional customizations

In addition to the customization options provided via the installation wizard, you can perform other customizations, such as changing the splash screen graphic, the colors of the right-hand-side panel, the available layouts and the content of the join instructions panel. However, these involve direct manipulation of the installation files and requires knowledge of core web-design technologies such as HTML, JavaScript and CSS.

Changing the splash screen graphics and colors

You can change the splash screen graphics and the colors of the right-hand-side panel.

All of the default images (except for layout SVG images) and css resources are stored under /vmrportal/static/pexip on the VMR portal.

  • Images are stored in the /img subfolder. This includes background.png which is used as the background image to the sign in page.
  • CSS files are stored in the /css subfolder. The portal.css file contains the styles you are most likely to need to modify.

All of your customizations should be placed under /vmrportal/static/custom/ using the same subfolder structure as described above. For example, if you supply a replacement background.png file, it should be placed in /vmrportal/static/custom/img/background.png.

Note that if you are using an SCP tool to upload revised files, the pexip user does not have permissions to write directly into the /vmrportal/static/custom/ folders. Instead you can upload your revised files to /tmp/ and then copy them across via an SSH session.

Example: changing the image shown on the sign in page

To change the background.png image shown on the sign on page:

  1. Create your own replacement image file, named background.png. We recommend using the same size/resolution as the existing image.

  2. Using the SCP file transfer protocol, upload the background.png file to the /tmp folder of the VMR portal. This can be done using for instance WinSCP (www.winscp.net) or the ’scp’ command-line utility for Linux/macOS, using a command such as:

    scp background.png pexip@10.0.0.10:/tmp

  3. After the file has been transferred into the /tmp folder, connect over SSH to the VMR portal, log in as user pexip and run the following command:

    sudo mv /tmp/background.png /vmrportal/static/custom/img/background.png

    This moves the png file from the /tmp folder into the /img folder.

  4. The changes should take immediate effect although you may need to clear your browser's cache.

Example: changing the CSS such as the colors used on portal's web pages

To change the CSS:

  1. Using the SCP file transfer protocol, download the default CSS file, portal.css, from /vmrportal/static/pexip/css/portal.css.

  2. Edit the portal.css file as required.

    For example to change the background and text colors that are used in the sign in page sidepanel, you should modify the dark class:

    .dark {
  background-color: #0A2136!important;
  color: #ffffff;
}

    Ensure that you only modify the color values e.g. #0A2136 for the background color and #ffffff for the text color.

  3. Using the SCP file transfer protocol, upload the revised portal.css file to the /tmp folder of the VMR portal. This can be done using for instance WinSCP (www.winscp.net) or the ’scp’ command-line utility for Linux/macOS, using a command such as:

    scp portal.css pexip@10.0.0.10:/tmp

  4. After the file has been transferred into the /tmp folder, connect over SSH to the VMR portal, log in as user pexip and run the following command:

    sudo mv /tmp/portal.css /vmrportal/static/custom/css/portal.css

    This moves the css file from the /tmp folder into the /custom/css folder.

  5. The changes should take immediate effect although you may need to clear your browser's cache.

Changing the layout options and join information

You can modify the available layouts, and the content of the join link box and the join information panel.

These are controlled by jinja2 templates that determine what is displayed. There are 3 templates: layouts.template, aliases.template and join.template, which are located in /vmrportal/vmrportal/templates/custom.

Changing the available layouts for selection (layouts.template)

The default layouts.template contains:

{%
set layouts = [
    ("one_main_zero_pips", "1 + 0"),
    ("one_main_seven_pips", "1 + 7"),
    ("one_main_twentyone_pips", "1 + 21"),
    ("two_mains_twentyone_pips", "2 + 21"),
    ("five_mains_seven_pips", locale.vmr_layout_adaptive_composition),
    ("four_mains_zero_pips", "2 x 2"),
    ("nine_mains_zero_pips", "3 x 3"),
    ("sixteen_mains_zero_pips", "4 x 4"),
    ("twentyfive_mains_zero_pips", "5 x 5"),
    ("one_main_thirtythree_pips", "1 + 33"),
]
%}

{% if major_version >= 34 %}
    {{layouts.append(("two_mains_eight_around", "2 + 8"))}}
    {{layouts.append(("one_main_nine_around", "1 + 9"))}}
    {{layouts.append(("one_main_twelve_around", "1 + 12"))}}
{% endif %}

To change the available layouts:

  1. Connect over SSH to the VMR portal and log in as user pexip.
  2. We recommend that you make a backup copy of the current template file before proceeding.

  3. Run the following command:

    sudo nano /vmrportal/vmrportal/templates/custom/layouts.template

  4. Edit the file as required to add, remove, reinstate or reorder the available layout options.

    • Do not change the internal layout names e.g. "one_main_zero_pips".

    • You can change the labels that are displayed in the portal e.g. "1 + 0", or you can refer to a string in the localization file by using the format: locale.<token_name> where <token_name> is the name of an object in the localization file.

      For example, the layouts.template file refers to:

      ("five_mains_seven_pips", locale.vmr_layout_adaptive_composition),

      and the localization file contains the matching token and the description to display:
      "vmr_layout_adaptive_composition": "Adaptive Composition"

    • The block at the end of the template appends to the layouts list the two example custom layouts that are available in the base theme from version 34 onwards (they were technology preview only in version 33).

    • You may include your own custom layouts in the layouts list:

      • Use the layout name as specified in the custom layout's .json file, and add your own label for the layout (or refer to a string in a customized locale file). For example:

        ("my_custom_layout_name", "6 x 6"),

      • Create an .svg icon file representing the layout (this can be generated by the custom layout designer) with the same name and ending with the .svg extension. Place the .svg file in the folder /vmrportal/vmrportal/templates/svg.
    • Do not break the jinja syntax/structure of the file.
  5. Press Ctrl + O to save your changes.
  6. Press Ctrl + X to exit nano.

  7. Run the following command to restart the VMR portal:

    sudo vmrportal restart

Changing the join information panel (aliases.template)

The default aliases.template contains:

Alias information for {{ vmr }}.
{% if aliases %}
You can join the meeting room here: https://{{ webapp_url }}/webapp/#/?conference={{aliases[0]['alias']}}{{ '&pin='+vmr_guest_pin if vmr_guest_pin | length > 0}}

or dial one of the following aliases:
{%- for alias in aliases %}
{{ alias['alias'] }}
{%- endfor -%}
{% else %}
{{ vmr }} has no aliases.
{% endif %}

{% if vmr_guest_pin -%}
and enter the pin {{ vmr_guest_pin }}
{%- endif -%}

To change the content of the join information panel:

You should only attempt to change the script in this file if you are proficient at coding jinja2 templates.

  1. Connect over SSH to the VMR portal and log in as user pexip.

  2. Run the following command:

    sudo nano /vmrportal/vmrportal/templates/custom/aliases.template

  3. Edit the file as required. The following {{ variables }} are available:

    • vmr, vmr_description, vmr_pin, vmr_guest_pin, aliases, webapp_url
    • Any of the conference configuration fields listed under /api/admin/configuration/v1/conference/ in the conference schema (https://<manageraddress>/admin/platform/schema/). Note that this is the complete set of conference-related configuration fields and thus some of these fields may not be appropriate for VMRs.
  4. Press Ctrl + O to save your changes.
  5. Press Ctrl + X to exit nano.

  6. Run the following command to restart the VMR portal:

    sudo vmrportal restart

Changing the join link text box (join.template)

The default join.template contains:

{%- if aliases -%}
https://{{ webapp_url }}/${brandingPath}/#/?conference={{aliases[0]['alias']}}{{ '&pin='+vmr_guest_pin if vmr_guest_pin | length > 0}}
{%- else -%}
{{ vmr }} has no aliases
{%- endif -%}

This is a slimmed-down version of aliases.template and can be edited in the same manner as described above.

Replacing the default SSL certificate on the VMR portal

To replace the built-in X.509 SSL certificate on the VMR portal with a custom-created certificate:

  1. Create a text file called vmrportal.pem which contains the following items in this specific order:

    • server certificate
    • server private key (which must be unencrypted)
    • DH parameters (mandatory, 4096 bits); these parameters can be generated through the openssl dhparam command, for example:
      /usr/bin/openssl dhparam -out dhparam.pem 4096
    • one or more intermediate CA certificates (a server certificate will normally, but not always, have one or more intermediate CA certificates)

    Note that the contents MUST be in this specific order for the certificate to work properly.

    The first section with the server certificate should contain a single entry in the format:

    -----BEGIN CERTIFICATE-----
    <certificate>
    -----END CERTIFICATE-----

    The second section with the server private key should contain a single entry in the format (although it may instead show 'BEGIN RSA PRIVATE KEY'):

    -----BEGIN PRIVATE KEY-----
    <private key>
    -----END PRIVATE KEY-----

    The DH parameters section should contain a single entry in the format:

    -----BEGIN DH PARAMETERS-----
    <parameters>
    -----END DH PARAMETERS-----

    Finally, there will normally be one or more intermediate CA certificates, where each intermediate has a section in the following format:

    -----BEGIN CERTIFICATE-----
    <certificate>
    -----END CERTIFICATE-----

  2. Using the SCP file transfer protocol, upload the vmrportal.pem file to the /tmp folder of the VMR portal. This can be done using for instance WinSCP (www.winscp.net) or the ’scp’ command-line utility for Linux/macOS, using a command such as:

    scp vmrportal.pem pexip@10.0.0.10:/tmp

  3. After the vmrportal.pem file has been transferred into the /tmp folder, connect over SSH to the VMR portal, log in as user pexip and run the following commands, one at a time:

    sudo cp /etc/nginx/ssl/vmrportal.pem /etc/nginx/ssl/vmrportal.pem.backup

    sudo mv /tmp/vmrportal.pem /etc/nginx/ssl/vmrportal.pem

  4. Run the following command to check the new certificate:

    sudo nginx -t

    If the certificate is OK, the response should look like this:

    $ sudo nginx -t
[sudo] password for pexip: 
nginx: the configuration file /etc/nginx/nginx.conf syntax is ok
nginx: configuration file /etc/nginx/nginx.conf test is successful

    However, if the certificate is missing, the response will look similar to this:

    $ sudo nginx -t
[sudo] password for pexip: 
nginx: [emerg] cannot load certificate "/etc/nginx/ssl/vmrportal.pem": BIO_new_file() failed (SSL: error:80000002:system library::No such file or directory:calling fopen(/etc/nginx/ssl/vmrportal.pem, r) error:10000080:BIO routines::no such file)
nginx: configuration file /etc/nginx/nginx.conf test failed

  5. If the certificate is OK, you can run this command to apply the new certificate:

    sudo systemctl reload nginx

After these commands have been run, the VMR portal should now be operational and using the new certificate.

If any problem occurs with the replaced certificate, the previous certificate can be restored using the following commands:

sudo cp /etc/nginx/ssl/vmrportal.pem.backup /etc/nginx/ssl/vmrportal.pem

sudo systemctl restart nginx

If you rerun the installation wizard you are given the option Do you want to regenerate self-signed SSL certificates and DH parameters? Ensure that you answer "no" to this option if you want to preserve your own certificate.

Installing your own CA certificates

If you need to install your own CA certificates (e.g. to validate the LDAP server):

  1. If you have a .pem file you must first rename it to have a .crt extension.

  2. Place your CA certificates (one or more .crt files) in /usr/local/share/ca-certificates

    Note that as with replacing the default SSL certificate (described above), the pexip user does not have the necessary access rights to copy crt files directly to the /usr/local/share/ca-certificates folder so you must copy them via the /tmp folder of the VMR portal, then move them to the ca-certificates folder:

    1. Using the SCP file transfer protocol, upload the CA certificate .crt file (cacert.crt in this example) to the /tmp folder of the VMR portal using WinSCP or the ’scp’ command-line utility for Linux/macOS, using a command such as:

      scp cacert.crt pexip@10.0.0.10:/tmp

    2. After the .crt file has been transferred into the /tmp folder, connect over SSH to the VMR portal, log in as user pexip and run the following command:

      sudo mv /tmp/cacert.crt /usr/local/share/ca-certificates/cacert.crt

  3. Run the following command to apply the certificates:

    sudo update-ca-certificates

    The response should look like this:

    $ sudo update-ca-certificates
Updating certificates in /etc/ssl/certs...
1 added, 0 removed; done.
Running hooks in /etc/ca-certificates/update.d...
done.

  4. Run the following command to restart the VMR portal:

    sudo vmrportal restart

Configuring alternative NTP servers

To change the NTP servers used by the VMR portal:

  1. Connect over SSH to the VMR portal and log in as user pexip.

  2. Run the following command:

    sudo nano /etc/openntpd/ntpd.conf

  3. Edit the file as required to reference your preferred NTP servers.
  4. Press Ctrl + O to save your changes.
  5. Press Ctrl + X to exit nano.

  6. Run the following command to restart the NTP service:

    sudo systemctl restart openntpd

Configuring and monitoring the fail2ban service

Fail2ban, which is enabled by default, is an intrusion prevention framework that can protect the VMR portal from brute-force login attacks. It works by scanning the logs on the VMR portal for repeated failed login attempts from the same IP address, and then blocks the source IP address that is responsible for that activity.

By default, it blocks access for 300 seconds if 10 login failures via the web interface (or 5 login failures via SSH) are logged from the same IP address within a 300 second window. The blocked IP address will be unable to connect to the VMR portal for the duration of the ban.

Limitations

The fail2ban service won't deter a determined or well-resourced attacker who is prepared to conduct a brute force attack from multiple source IP addresses or ride out the ban duration repeatedly over a period of days, but it does make break-in harder.

All users that are behind the same NAT are seen as having the same source address. Therefore, if you have multiple users behind the same NAT who are accessing the VMR portal, we recommend caution in using fail2ban as they could block themselves out even if they never enter wrong login credentials.

Disabling and enabling fail2ban

Fail2ban is enabled by default on the VMR portal.

To disable fail2ban:

  1. Connect over SSH to the VMR portal and log in as user pexip.

  2. Run the following command to disable fail2ban:

    sudo systemctl disable fail2ban && sudo systemctl stop fail2ban

To enable fail2ban:

  1. Connect over SSH to the VMR portal and log in as user pexip.

  2. Run the following command to enable fail2ban:

    sudo systemctl enable fail2ban && sudo systemctl start fail2ban

Modifying the default fail2ban configuration

The default configuration of the fail2ban service is to block access for 300 seconds if it detects 10 failed logins from the same IP address within a 5 minute window.

You can modify each of these settings if required. To change the fail2ban configuration:

  1. Connect over SSH to the VMR portal and log in as user pexip.

  2. Run the following command to edit the fail2ban config file:

    sudo nano /etc/fail2ban/jail.local

  3. You can modify the following ban-related settings:

    Setting Purpose Default
    bantime
    (DEFAULT section)    		 The number of seconds that a host address is banned. 300
    findtime
    (DEFAULT section)    		 The time period in seconds that is monitored. 300

    maxretry

    (you must modify the maxretry value specified in the ldap jail)

    		 The number of failures that when reached will trigger the ban. A host is banned if it generates maxretry failures during the last findtime seconds. 10

  4. After editing and saving the file, run the following command to restart the fail2ban service:

    sudo systemctl restart fail2ban

For more information on advanced configuration, see https://www.digitalocean.com/community/tutorials/how-to-protect-an-nginx-server-with-fail2ban-on-ubuntu-22-04.

Checking the status of the fail2ban service

You can check the status of the fail2ban service by running the following command:

sudo fail2ban-client status ldap

which gives the following status:

pexip@vmrportal:/var/log$ sudo fail2ban-client status ldap
Status for the jail: ldap
|- filter
|  |- File list:    /var/log/nginx/api.access.log
|  |- Currently failed:    0
|  `- Total failed:    0
`- action
   |- Currently banned:    0
   |  `- IP list:    
   `- Total banned:    0

The failed and banned counts may be non-zero if the service has detected access failures.

If the service is not running you will see: ERROR Unable to contact server. Is it running?