Skip to content

Adapter Hub

Adapter Hub is a software component for UIP that is required to run adapter hub services. It can also be used to run external adapters. Each adapter hub requires a license.

The software can be installed on the same machine as UIP if there is no requirement to run adapters on a separate machine.

The adapter hub software can be installed on an NEC provided hardware appliance, a virtual machine, or any customer provided hardware which satisfies the following requirements.

Hardware Requirements

The table below only lists the minimum resources needed for running the adapter hub application and its dependencies. Additional resources should be provisioned based on the expected workload of external adapters and adapter hub services that will be hosted by the adapter hub.

Hardware Minimum
Memory 4GB
Processor >=1.4GHz with >=2 Cores/Virtual Processors
Storage 30GB of available space

If your system is installed on a Hypervisor, it should meet the requirements of that system in addition to the requirements listed here.

NEC recommends using Ubuntu Server Certified Hardware. Refer to https://certification.ubuntu.com/server/ for more information.

Software Requirements

Supported Operating Systems

The following operating systems are supported for hosting an adapter hub:

It is recommended to install the operating system on a virtual machine hosted by a hypervisor. Taking a checkpoint before system updates is recommended to capture a restore point.

Important

To ensure a maximum degree of data protection and privacy, it is recommended to install Ubuntu Server with disk encryption support provided by LVM/LUKS.

Date/time settings

  • Use the Linux command timedatectl to verify that the system date, time, and time zone information is set correctly.
  • See Ubuntu Time Management for issues relating to your system's time settings.

Network Requirements

For details on setting up the network on Ubuntu, refer to Ubuntu network configuration

  • A network adapter which has internet access and an IPv4 address is required to install and update this software
  • During install and operation software must be downloaded from several websites. Adapter Hub does not transmit data your data to these sites.The sites listed below should be added to any necessary allow lists.
    • *.nec-downloads.com - download site for Adapter Hub software image registry
    • s3.us-east-2.amazonaws.com - download site for adapter type software images
    • *.ubuntu.com - download site used by "apt" for Ubuntu OS and its software updates
    • download.docker.com - download site for Docker software and its updates
  • If needed private DNS servers must be configured in Ubuntu
  • If used, HTTP or HTTPS web proxies must be configured in Ubuntu
  • Additional steps may be needed during the install of Adapter Hub if the following networks are used within your network environment:
    • 10.115.0.0/16 - default address pool for overlay Docker networks
      • "ingress" network is automatically created from this address pool when Docker Swarm is initialized
    • 172.17.0.0/16 - "bridge" default network used for Docker containers that are not assigned to a specific network such as the Setup Wizard used during UIP installation
    • 172.18.0.0/16 - "docker_gwbridge" bridge network that connects overlay networks (including the ingress network) to the host machine's physical network
  • Adapter Hub uses TCP port 443 to connect out to the UIP system.
  • Adapters may use other network ports to connect to other systems. These will be documented in the Adapter Type documentation.

Download Install Script

After connecting a terminal to the Adapter Hub machine, execute the following command to download the installation script. Note that the first command has capital letter "O" (not a zero digit) after the hyphen.

curl -Ofv https://nec-downloads.com/adapterhub/hub-install.sh

If you are unable to download the install script you may need to configure a http/https proxy in Ubuntu.

Run Install Script

The installation script will download and install a small number of required software packages on the target machine. Execute the following command with root privileges and monitor its progress.

sudo bash hub-install.sh

During the install you will be prompted to select a download region. Please select the number that best describes your NEC sales region.

You will also be prompted to enter your repository credentials to allow access to the download.

  • NECAM/LATAM Region Users
    • Username: necam/emailuser@company.com
      • Use NEC Anytime account email address prefixed with necam/ (all lower-case)
    • Password: password
      • Use the "Password for NEC Applications" configured under My Account for the specified NEC Anytime account. This will be different from the password used to log into the NEC Anytime website.
  • NECJ Region Users
    • Username: necj/loginname
      • Use NEC Software Activation License Center username prefixed with necj/ (all lower-case)
    • Password: password
      • Use the password for the specified NEC Software Activation License Center account
  • NECEMEA Region Users
    • Username: necemea/loginname
    • Password: password
      • Use the password for the specified NEC BusinessNet account
  • NECASIA Region Users
    • Username: necasia/loginname
      • Use NEC Product Activation License Portal (LMS) username prefixed with necasia/ (all lower-case)
    • Password: password
      • Use the password for the specified NEC Product Activation License Portal (LMS) account
  • NECAU/NZ Region Users
    • Username: necaunz/loginname
      • Use NEC Product Activation License Portal (LMS) username prefixed with necaunz/ (all lower-case)
    • Password: password
      • Use the password for the specified NEC Product Activation License Portal (LMS) account

The script will prompt you for details about your UIP configuration.

  • UIP Server URL is the websocket connection to your UIP server
    • Enter wss://FQDNofSERVER if UIP is configured for HTTPS access (strongly recommended)
    • Enter ws://FQDNofSERVER if UIP is configured for HTTP access (not recommended)
  • UIP Workflow Secret should match the External Adapter Secret configured in UIP.
    • See the Administration -> Workflow page in UIP
  • Adapter Hub Token must match the external token configured for this specific Adapter Hub on the Adapter Hub configuration page in UIP that identifies this specific hub.

After the script is finished running, go to the Adapter Hubs page of UIP to verify that the adapter hub software was able to connect successfully.

Importing a Trusted CA for Adapter Hub

Follow this section if your Adapter Hub must connect to a UIP system which use a certificate that is not signed by a widely-trusted Certificate Authority (CA). Often this is called an Enterprise CA or self-signed CA.

This procedure requires the Administrator to copy a file to the Adapter Hub server. Copying this file securely is beyond the scope of this document but the administrator could use tools such as scp or sftp. If the CA certificate has been imported into the UIP Trusted CA page it can be copied from the folder /var/lib/docker/volumes/ca-certs/_data/ on the UIP machine.

CA certificate files must comply with the following rules in order to be work with Adapter Hub:

  • Must use Base64 PEM certificate format. Certificate files with binary format (DER) are not supported.
  • Must have a .crt file extension.
  • Must not be expired or premature
  • Version field value must be V3 or higher
  • Basic Constraints field value property for Subject Type must be CA

Copy the CA certificate .crt file to the directory /etc/wfadapterhub/cacerts on the Adapter Hub server. Doing so will require escalated privileges using the sudo command. In the following example UIP and Adapter Hub are installed on the same machine and the root CA certificate for UIP has been installed into its Trusted CA page.

sudo cp /var/lib/docker/volumes/ca-certs/_data/myrootCA.crt /etc/wfadapterhub/cacerts/myrootCA.crt

After the CA certificate has been copied restart the Adapter Hub service by killing its active container.

sudo docker kill $(sudo docker ps -q -f name=wfadhub_wfadapterhub)

This same procedure must be used if the CA certificate expires or UIP is modified to use a certificate issued by a different untrusted CA.

Adapter Hub UIP configuration

Adapter Hubs have 4 parameters

  • Name - The name used for this hub
  • Enabled - Used to enable/disable the Adapter Hub connection
  • Token - This token is used to uniquely identify each Adapter Hub
  • Description - Used to add a description for this hub

Reconfiguring Adapter Hub Connection To UIP

If the UIP server URL, External Adapter Secret, or Adapter Hub Token are changed the software for Adapter Hub must be reconfigured to use the new connection details. This is done by re-executing the hub-install.sh installation script with an additional "config" argument.

sudo bash hub-install.sh config

The script will once again prompt you for details about your UIP configuration.

After the script is finished running, go to the Adapter Hubs page of UIP to verify that the adapter hub software was able to connect successfully.

Adapter Hub Upgrade

The adapter Hub software only needs to be upgraded when a security issue is corrected or new feature is released. See Release Notes for more information. If a new installation script is needed it will be noted in the Release Notes. To upgrade log in to the Adapter Hub and re-run the install script

sudo bash hub-install.sh