We use cookies to remember your language choice. By using our website you accept this in accordance with the Cookie section in our Privacy Statement.
< Back to index

Virtual Application Installation Guide

1. Introduction

1.1 What is Remotix Gateway

Remotix Gateway is a server solution needed to connect Client and Agent. It consists of three parts: Gateway API server, Hub and Tunnel.

  • Agents and Clients maintain connections with the Gateway API server.
  • Hub is a web-based Agent management interface. It allows adjusting Agent settings remotely, performing maintenance actions, monitoring state and so on. It is also used to log in users in the Client apps with OAuth.
  • Tunnel performs negotiation of connection parameters between Clients and Agents. It also serves as a relay if Client and Agent cannot connect directly.

1.2 Parts of the On-Premise Remotix Gateway Solution

  • Internal components
    • Gateway API server – internally named “back
    • Hub server – “front
    • Relay server – “tunnel
    • maintenance page
  • External components
    • nginx (front proxy for HTTPS)
    • MariaDB (database server)
    • supervisor (process manager)
    • (optional) postfix
    • (optional) monitoring

The internal components are provided by Remotix. The external ones are third-party.

You’ll also need a valid TLS certificate for the Gateway to work over HTTPS. If you don’t have one, you may get it using Let’s Encrypt.

The relations between these entities are as follows:

On-premise relations chart

In this guide, we assume that back, front and tunnel are all hosted on the same machine.

1.3 Licensing

Remotix Gateway solution requires a file containing provisioning info to provide licensed access. To get the installation file, please contact our support. We’ll provide a temporary license so that you could ensure that everything works fine in your environment before the actual purchase.

2. Installation

2.1 Getting OVA

Contact us for the download link for the latest release.

2.2 Import OVA

You can either import the OVA file manually through the VMWare web interface or deploy it using a console tool.

2.2.1 Manual OVA deployment

  1. Go to VMWare web interface,
  2. Click the 'Create / Register VM' button to create a new virtual machine,
  3. On step 1, choose 'Deploy a virtual machine from an OVF or OVA file',
  4. Choose the file downloaded from the link you got from us at #2.1,
  5. Keep clicking Next with more or less default parameters until you get to the step named 'Additional settings',
  6. Set the following additional parameters here (for more information, check section 3):
    1. Address: the URL of your future Remotix server,
    2. Gateway API port: the unified port to access Remotix server (443 by default),
    3. Gateway URL: the full URL of your Remotix server, including http/https and port,
    4. Hub name: name of your Remotix server to be shown in Remotix Hub,
    5. TLS certificate URL: URL of a zip file containing TLS certificate chain and the private key inside,
    6. Provisioning file URL: URL of a provisioning file containing license information,
    7. OS root user password: password for the root user to access the VM operating system,
    8. Maintenance page user: username to access Remotix server's maintenance page,
    9. Maintenance page password: password to access Remotix server's maintenance page,
  7. Click 'Finish'.

2.3 Deploy with ovftool

If you have OVF Tool installed, you can also deploy the virtual machine by executing the following command in the console:

ovftool \ 
--allowExtraConfig \ 
--extraConfig:guestinfo.rxgw_address="rxgw.example.com" \ 
--extraConfig:guestinfo.rxgw_port="443" \ 
--extraConfig:guestinfo.rxgw_base_url="https://rxgw.example.com" \ 
--extraConfig:guestinfo.rxgw_hub_name="Camomile Ltd." \ 
--extraConfig:guestinfo.tls_cert_url="http://example.intra/ova_tls.zip" \ 
--extraConfig:guestinfo.provisioning_url="http://example.intra/provisioning.b64" \ 
--extraConfig:guestinfo.rxgw_maint_user="maint" \ 
--extraConfig:guestinfo.rxgw_maint_pass="m@1nt_p@ssw0rd" \ 
--extraConfig:guestinfo.os_root_pass="TheNewSecretP@ss" \ 
rxgw-onpremise-XX-vapp.ova \ 
vi://{{ EXSi_username }}:{{ ESXi_password }}@{{ ESXi_address }}

Note that all the placeholders shown in bold should be replaced with the correct info.

3. Configuration

At the first boot of the guest OS, the configurator script will read OVF properties and configure the Gateway accordingly.

Available parameters and respective property names:

  • Address (rxgw_address)
    FQDN or IP. This will be used as a server name for the front proxy and will serve as a base address to generate endpoints for the tunnel.
  • Gateway API port (rxgw_port)
    Unified port for all HTTPS connections (Gateway API, Hub and Tunnel Websocket endpoint, usually 443). Other external ports are non-configurable: TCP/9021 and UDP/19997–19999 are used for other tunnel endpoints.
  • Hub base URL (rxgw_base_url)
    URL to be used to generate all Hub-related links. If you’re using defaults (HTTPS on 443 port), it will be just https://rxgw_hostname.
  • Hub site title (rxgw_hub_name)
    This string will be used as your Remotix Gateway title.
  • TLS certificate URL (tls_cert_url)
    URL to a zip file with TLS certificate chain and private key inside. They should be in PEM format and should be named tls_chain.pem and tls_privkey.pem.
  • Provisioning file URL (provisioning_url)
    URL to a file with license info.
  • Maintenance page user (rxgw_maint_user)
  • Maintenance page pass (rxgw_maint_pass)
    Maintenance page access credentials
  • Guest OS root pass (os_root_pass)

The configurator will change the root user password to the provided value.

When the virtual appliance starts, open the Remotix Server maintenance page at rxgw_base_url/maint, scroll down to the Admin Users section and add the first Remotix Hub administrator user:

  1. Click Add new admin user,
  2. Enter email and password,
  3. Click Add.
Maintenance - add user

Congratulations! Now your instance of Remotix Gateway is good to go. The next step is to set client and agent apps to use it.

4. Clients and Agents Configuration

Both client and agent use the Gateway URL to connect with Remotix Gateway. Your Gateway URL will be the same as rxgw_base_url (e.g. https://rxgw.example.com)

To apply this setting, take the same steps for both Client and Agent apps:

  1. Open the application,
  2. Navigate to Preferences > Network > Remotix Gateway,
  3. Click the Change button,
  4. Choose Custom,
  5. Enter your Gateway URL,
  6. Click the OK button.

To check that the app has connected to the custom Gateway successfully, open the main window and check the following:

  • Client
    • The Sign In tab contents load successfully,
    • When you sign in, the status is Ready.
  • Agent
    • Your gateway address is displayed in the window title,
    • and the status is Ready for connection.

5. Troubleshooting

To ensure that every part of your Remotix Gateway Server runs fine (or to find out what might have gone wrong if anything), go to the maintenance page located at rxgw_base_url/maint. When everything is fine, each module will have status Running.

5.1 If the maintenance page won’t open

First, check the configurator log: less /tmp/vapp_configure.log. If the configuration has been completed successfully, the log should end with the following messages:

Configs are ready, starting services... Configuration finished.

If it does not, please contact our support.

If the configuration seems to be fine, please check that the machine running the Remotix Gateway server is accessible (e.g., by pinging it).

If you can access the server but still cannot access the maintenance page, something is wrong with nginx. Please check the nginx logs that are located at /var/log/nginx/error.log on the target machine. If the file is empty, it may mean that nginx is set up incorrectly.

5.2 If some modules don’t run

If the status of any module differs from Running, check the related logs. Depending on the faulty module, check the following:

  • DB (database): Errors log,
  • Back or Front: first, check the Stdout log. If it didn’t help, check the Full one.
  • Tunnel: Full log.
Maintenance - logs section

You can also find the Supervisor log here if needed: /var/log/supervisor/supervisord.log

5.3 If apps won’t connect to the Gateway

If everything – including nginx – seems to be fine according to the logs, but neither Agent nor Client apps can connect to the Gateway, there still may some connectivity problem. Please ensure that all of the required ports are open on all of the machines involved in the process.

If not changed manually, client and agent apps should use port 443 to connect with the gateway server and ports 9021, 19996, 19997, 19998 while establishing the connection.

5.4 If the connection establishment takes too long

If everything else is OK, but the connection process takes longer than 15 seconds, it most likely means that the client consistently fails to establish a peer-to-peer connection. You can fix it either on the client’s or on the server’s side.

  • To disable peer-to-peer connections in the Client:
    1. Open Remotix preferences,
    2. Go to the Network pane,
    3. In the Cloud connections section, disable both Enable UDP and Enable local TCP options.
  • To fix peer-to-peer connectivity, ensure the following:
    • The UDP connections are permitted for both Client and Agent apps,
    • Both Clients and Agents can connect to each other on ports 9997–10020.

      If none of the above helps, please also check the tunnel logs.

5.5 Other

If you need any other assistance, please feel free to contact our support, and we’ll gladly help you.