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 uninstall your current version and then perform a standard install of the latest release.

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

Many of the maintenance tasks to change the configuration of the VMR portal involve rerunning the installation wizard. To do this:

  1. Log in to the VMR portal through SSH or VMware console as user 'pexip'.
  2. At the command prompt, run the installwizard 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.

Additional maintenance commands

You can run a selection of maintenance commands against the VMR portal (for example to stop or start the service):

  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 use journalctl -fu docker.service to tail just the docker (VMR portal) logs.

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 image and css resources are stored under /usr/share/nginx/html/pexip/static/ on the VMR portal.

  • Images are stored in the /img subfolder. These include background.jpg and background_small.jpg which are used as the background image to the sign in page; the browser's viewport size determines which of the two files is used.
  • 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 /usr/share/nginx/html/custom/static/ using the same subfolder structure as described above. For example, if you supply a replacement background.jpg file, it should be placed in /usr/share/nginx/html/custom/static/img/background.jpg.

If you place your modified files under the /pexip/static/ folder they will be reset to the default content if the VM is restarted.

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 /usr/share/nginx/html/custom/static/ 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.jpg image shown on the sign on page:

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

  2. Using the SCP file transfer protocol, upload the background.jpg 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.jpg 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.jpg /usr/share/nginx/html/custom/static/img/background.jpg

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

  4. You may also want to repeat the process for the background_small.jpg file as either image file may be used, depending on the viewport size.
  5. 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 /usr/share/nginx/html/pexip/static/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 /usr/share/nginx/html/custom/static/css/portal.css

    This moves the css file from the /tmp folder into the custom/static/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 panel

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

These are controlled by jinja2 templates that determine what is displayed. There are 2 templates: layouts.template and aliases.template, which are located in /pexip/si/apps/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", "Adaptive Composition"),
			("four_mains_zero_pips", "2 x 2"),
]
%}

{% if major_version >= 27 and minor_version >= 0 %}
			{{layouts.append(("nine_mains_zero_pips", "3 x 3"))}}
			{{layouts.append(("sixteen_mains_zero_pips", "4 x 4"))}}
			{{layouts.append(("twentyfive_mains_zero_pips", "5 x 5"))}}
			{{layouts.append(("one_main_thirtythree_pips", "1 + 33"))}}
{% endif %}

To change the available layouts:

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

  2. Run the following command:

    sudo nano /pexip/si/apps/vmrportal/vmrportal/templates/custom/layouts.template

  3. Edit the file as required to 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".
    • Do not break the syntax/structure of the file.
    • The default template only includes "five_mains_seven_pips" i.e. "Adaptive Composition" in the set of available layouts if the associated version of Pexip Infinity is v25 or later. If you customize the template please ensure that you do not include "five_mains_seven_pips" if you are running v24 or earlier.
  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 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 /pexip/si/apps/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
  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

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

    sudo systemctl restart nginx

    Note that sudo systemctl restart nginx will restart the VMR portal application and therefore interrupt the service briefly.

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. Place your CA certificates (one or more .pem 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 pem 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 .pem file (cacert.pem 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.pem pexip@10.0.0.10:/tmp

    2. After the .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 command:

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

  2. 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 service openntpd restart

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-14-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/pexapp.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?