Troubleshooting – License

What will make my license stop working?
  • If you upgrade your software to the latest version without an active maintenance plan that covers that version.
  • If you change the CPU mother board. This includes cloning the image of the drive and restoring to a new PC.
  • If you remove all of the hard disks from the system that were present when the software was licensed.
  • With older OAS version 9 or less if you remove all of the Ethernet cards from the system that were present when the software was licensed.

Typical OAS Deployments

Each system configuration and customer requirements are unique, and the OAS Platform is flexible and can adapt to virtually any scenario. Yet, there are some deployment patterns that are common, and can be illustrated in order to help you understand the benefits of each. Click images to enlarge each diagram.

On-premise or closed network

On-premise or closed network

OAS can be installed on a server within a local, secure network for gathering, logging, and delivering data for internal applications. This configuration provides the highest level of security and data integrity by placing the OAS instance closest to the data source.

DMZ or public-facing subnet

DMZ or public-facing subnet

Using the Live Data Cloud feature of OAS, you can connect one or more instances of OAS on secure networks to an OAS instance in a DMZ. This allows you to keep your data and data sources secure, while exposing and aggregating the data you choose for external endpoints. All communications between OAS instances is compressed and encrypted. Additionally, you can also log data from any OAS instance, allowing you to maintain private logs at the data source and a public aggregate log for external clients.

Secure cloud-hosted OAS

Secure cloud-hosted OAS

Again, using the Live Data Cloud feature of OAS, you can connect one or more instances of OAS on secure networks to an OAS instance hosted on a public network in the cloud without the need for fixed IPs. All of the same features and capabilities are available in each OAS instance, including data logging, APIs for custom HMIs, Alarm notification, and more.

Secure communications diode

Secure communications diode

The OAS Platform can be configured to ensure data is one-way and read only for external clients, effectively creating a “communications diode”. This ensures no possible manipulation of source data from external clients for the most secure and flexible configuration in critical environments.

Multi-tenant deployment

Multi-tenant deployment

OEMs and System Integrators can securely connect and aggregate data from many customers in different locations, while still providing custom applications served from an external public network.

Raspberry Pi IoT Installation

Prerequisites

For any Linux installation, general knowledge of Linux server configuration is required.
This includes being comfortable with the following tasks:

  • managing user accounts
  • managing files and user permissions
  • transferring files between machines
  • networking configuration
  • configuring services (daemons in systemd)

While OAS is happy to support the OAS installation and any issues related to the product, support does not include managing Linux server configuration and administrative tasks.


OAS Platform Support on Raspberry Pi 4

The Open Automation Software platform can be installed on Raspberry Pi 4 systems with full support of all communication interfaces.

  • Modbus TCP, Modbus RTU, and Modbus ASCII for Master and Slave
  • Allen Bradley ControlLogix, CompactLogix, GuardLogix, Micro800, MicroLogix, SLC 500, and PLC-5
  • Siemens S7-200, S7-300, S7-400, S7-1200, and S7-1500
  • OPC UA Server and Client
  • MTConnect
  • MQTT Broker and Client
  • Azure IoT Data Hub
  • AWS IoT Gateway
  • Raspberry GPIO Pins
NOTE: Classic OPC DA is not included for Linux deployments, but it can be networked from a Windows system running OAS.

All OAS platform features are supported for Raspberry Pi 4.

  • Data logging and alarm logging to MSSQL Server and SQL Azure, Oracle, mySQL, MongoDB, MariaDB, PostgreSQL, Cassandra, SQLite, InfluxDB, and CSV files
  • Realtime and historical trending
  • Realtime and historical alarming
  • Alarm notification
  • Live visualization for web user interfaces
  • Live visualization for remote .NET applications
  • Full programmatic support of configuration, live, and historical data via REST API and .NET interface
NOTE: Automated reports are not support on Linux systems, but can be triggered over a network connection for execution from a Windows system.

 
NOTE: While running OAS on a RaspberryPi 4+ is fully supported, the default Raspbian OS is not. Please choose one of the supported Linux distributions HERE, making sure to install a server variant as opposed to a desktop variant. Extensive testing with Ubuntu Server has proven to be the most reliable and simplest to configure.

Installation Video

View the following video for easy to follow instructions to install OAS on a Raspberry Pi 4 device and see the Web HMI Dashboard hosted directly from the Raspberry Pi 4.

The same steps are also listed in the Linux Installation guide so you can follow along with the installation script.

Visit the Web HMI Dashboard for more detail on the self hosted web interface with dynamic user configuration.

OAS in Docker Containers

The OAS Platform is capable of running in Docker containers on both Windows and Linux, with only a slight variation in configuration. In this article we will walk through the necessary steps for basic containerization, but using these principles you can build your own images and configure them for your particular needs.

  • 00:00 – Introduction
  • 00:15 – Container Installation
  • 00:34 – Application Stack
  • 00:48 – Steps for running docker
  • 01:32 – Create a Docker Image
  • 04:04 – Set of Instructions
  • 05:10 – Commands
  • 05:45 – Run your Container
  • 10:26 – Configure the License Host
  • 14:19 – Remaining Steps
  • 18:06 – Configure Licensing
  • 18:55 – More Information

Prerequisites

The OAS Platform was designed to be a high performance IoT Gateway, Data Logging engine, data visualization server, and more. To benefit from these features, whether the server is running as a stand alone or in a container, be sure to consider the following:

  • Docker experience – this document assumes some familiarity with containerization concepts, specifically with Docker, and is not intended to be a tutorial on Docker or containers in general. To learn more about Docker, see the following: Docker-What is a Container?
  • Networking – the server must be able to reach external resources, and if being accessed by any of the OAS SDKs for visualization or programmatic configuration, the server must be accessible from external sources. This is easily accomplished by exposing the necessary ports. Port 58727 is the default port used for TCP communications when using .NET SDKs and the OAS Configuration application. Port 58725 is the default port used for Web Visualization tools as well as the REST API. Running stand alone, you are free to change these ports as needed. However, when running in a container, these default ports should not be changed (more on this later).
  • Memory and CPU – when running multiple instances of the OAS Platform in containers, expect memory and CPU utilization to increase as a result. The amount of each needed entirely depends on your individual configurations, such as how many Tags are being used in each container, data logging, alarming, etc. Be sure to size your deployment platform only after testing with your intended configurations to determine the footprint. You can refer to the following for suggested CPU and RAM hardware requirements based on Tags and features to be implemented: OAS Recommended Hardware

Containerization Options

Docker containers can be configured to run completely independently or they can run utilizing shared resources on the Host server. OAS supports both scenarios, allowing you to utilize self-contained configuration files or shared configuration files on a Host using mapped volumes. This allows for generic containers to be spun up with identical configurations, or simply to allow the management of configurations external to a container.

Comparison of OAS containers running self-contained and with shared configuration files on the host.

Installing an OAS Image

All Docker versions of the OAS Platform are available on Docker Hub and can be pulled into your local machine with a single command. This makes installation and upgrading extremely convenient. You can browse all OAS images at hub.docker.com/u/oasiot. Once you have chosen the image you would like to use, matching the OS/architecture (e.g. Linux/x64 or Windows/AMD64) execute the pull command, which is provided on the page for each image. For example, the pull command for Linux/x64 is:

docker pull oasiot/oas-linux

This will download the latest version of the image. So, if OAS releases a new version, simply re-run the pull command and you can always be up-to-date. If you would like to pull a specific version, you can use the version tag in the pull command. For example, pulling version 15.00.042 would use:

docker pull oasiot/oas-linux:15.00.042

Using a version tag in your workflow will allow you to keep your installations uniform and predictable.

Running your new container

To run an instance of this image in a container, execute the following command. This will spin up an instance and display the console output in the terminal window. The container can be stopped by hitting CTRL-C. By default, the docker runtime will provide a randomized unique name for the container.

docker run -it oasiot/oas-linux

The container will now be running, and will be assigned an IP address only accessible from the host machine. If you want to map the container’s ports to ports on the host, allowing the container to be reached from external systems, you can use the -p or -P flags in the docker run command. For example this will map the host’s port 58727 to the container’s port 58727, so you can then reach the container from the host’s IP address on port 58727, allowing you use the OAS Configuration application remotely to connect into the container:

docker run -it -p 58727:58727 oasiot/oas-linux

To allow the Docker engine to assign random port mapping, you can use the following command. After doing this, just inspect the running container to see which ports have been assigned:

docker run -itP oasiot/oas-linux

Optional: Creating your own Image

Before any application can be run as a Docker container, it has to be bundled in an image. The process of creating an image involves the creation of a Dockerfile with configuration options, and calling docker build against the file. Whether the target platform for running the container is Linux or Windows, the process is the same, with some slight variations on the contents of the Dockerfile. For more information on Dockerfiles and their syntax, see the online documentation.

To containerize the OAS Platform we will take the following steps:

  • Ensure that Docker is installed properly on the target platform
  • Download and extract the OAS Platform distribution for Linux or Windows .NET Core depending on the chosen platform
  • Copy the contents to the target server in a directory, e.g. /oas-docker/oas-linux, /oas-docker/oas-win
  • Within the /oas-docker directory, create a text file called Dockerfile with the following contents. If you are familiar with crafting Dockerfiles, you can modify these settings to your preferences, as long as the default ports in the EXPOSE commands are not changed.

Linux Dockerfile

FROM mcr.microsoft.com/dotnet/runtime:6.0
EXPOSE 58725
EXPOSE 58727
EXPOSE 58728
EXPOSE 1338
EXPOSE 8338
EXPOSE 502
COPY /oas-linux/ /oas/
RUN chmod +x /oas/OASEngine
ENTRYPOINT ["./oas/OASEngine"]

Windows .NET Core Dockerfile

FROM mcr.microsoft.com/windows/nanoserver:1803
EXPOSE 58725
EXPOSE 58727
EXPOSE 58728
EXPOSE 1338
EXPOSE 8338
EXPOSE 502
COPY ./oas-win/ ./oas/
USER "NT Authority\System"
ENTRYPOINT ["/oas/OASEngine.exe"]

As you see, the Windows Dockerfile differs from the Linux version. The FROM entry references the nanoserver tag which is a bare bones Windows runtime host. The same ports are mapped in the EXPOSE lines. The COPY command copies the contents of the oas-win directory to the container’s oas directory. You’ll note the addition of the USER command, which specifies that the context the OAS Platform should run on is the System account with elevated privileges. This is required. Lastly, the ENTRYPOINT is modified to call the OASEngine.exe executable. Also, see the section below titled Windows Containers as you may run wither Linux or Windows applications in containers on the Windows platform.

  • Build the OAS container image with the following command. This creates and registers a reusable image that can be spun up as multiple side-by-side containers:
docker build --tag oas .
  • The OAS Platform allows you to customize which ports are used for configuration communications as well as for access with SDKs, the REST API, and WebHMI products. When using OAS within a container, it is important to use the defaults of 58727 for TCP communications and 58725 for HTTP calls. These can be mapped to fixed host ports within the Dockerfile, or mapped dynamically during the execution of “docker run”. The OAS LicenseHost relies on the default underlying ports to allow for license activation, but you may still map these to customized ports if you want to access the containers via localhost.

Options for running a container

Providing a custom name

If you run a Docker container with the previous command, the Docker runtime will assign a random name for that instance. You can provide a custom name for the container to more easily identify the container. This must be a unique name on the server since no two containers can have the same name. This example runs the container, giving it the name “oas_production”:

docker run -it --name oas_production oas

Mapping a host volume

In some cases, you may want several running OAS container instances to share the same configuration files so that when they spin up, they pick up the same settings. To do this, we’ll follow these steps:

  • Move the ConfigFiles directory to a location on the host machine
  • Build the docker image
  • Run the image using the -v host_dir:container_dir option to create a virtual directory in the container mapped to the host
docker run -v /OASConfigs:/oas/ConfigFiles --name oas1 oas
  • Mapping host directories can also be useful if you are logging data to a SQLite database, as they are file-system based and you would not want data lost when you spin down a container.
  • You can map multiple volumes for such a configuration, combined with the command above:
docker run -v /OASConfigs:/oas/ConfigFiles -v /SQLiteData:/oas/SQLiteData --name oas1 oas

Then, in your SQLite logging configuration, you would use /oas/SQLiteData as the path for the database.

Licensing

A stand-alone installation of the OAS Platform is licensed directly my using the OAS Configuration application. You select Configure > License, select the machine (typically localhost if working on the current machine) and are presented with a unique License Code for the machine. This is sent to OAS and you will then be provided an encoded License Key that will activate the features you have purchased.

Running the OAS Platform in containers, licensing is handled slightly differently. On the container host machine, you install and run the License Host application, which communicates with all running containers to activate product features, and recognizes new containers as they spin up. When purchasing a license from OAS, you will select product features to enable along with a number of tags, and if deploying OAS within containers, you also select the maximum number of containers you will be running on the host.

Standalone installations of the OAS Platform are licensed directly.
Containers acquire their license from the LicenseHost installed on the host

Installing the License Host

Linux

On a Linux system, the installation and execution of the License Host is similar to installing the OAS Platform itself. From the product downloads page, locate the License Host for Linux and download the ZIP archive. Unzip this file and move the contents to your preferred location, then execute the following command on the Linux server to make the application executable:

sudo chmod +x LicenseHost

You can now run the LicenseHost application directly with the ./LicenseHost command, or configure it to be started with the system when it boots up. You can follow the directions for setting up an application as a daemon on Linux from Step 3 of our online documentation, replacing the name and path of the OASEngine with that of the LicenseHost, where applicable.

Windows

On Windows, the LicenseHost installer registers it as a Windows Service. Download and install the License Host and start the service either manually in the Windows Services control panel, or using the OAS License Host application from the Start menu, which acts as a service control for just the License Host. The service is named “OAS License Host” if you choose to start it manually

Managing Licenses with the License Host

After starting the License Host on the container host server, you can connect to it from the OAS Configuration Application to apply or modify a license for that server. Select Configure > Container License from the main dropdown menu and enter the IPAddress of the host server.

Note that the LicenseHost will communicate on port 58729 so the host machine must allow TCP communications on that port so adjust your firewall rules accordingly. If you choose to change this port, locate the appsettings.json file in the distribution of the LicenseHost application and change the port number within it. You can also use this file to secure the License Host by adding a username/password combination.

Configuring the license on the container host is identical to configuring a license on a stand alone installation of the OAS Platform. Your License Code is used to acquire a License Key from OAS Support, and the key contains information about the product features to enable along with the maximum number of containers it will support.

For more information on licensing an OAS server, see the following Knowledge Base article: OAS License Activation

Testing your installation

Once your containerized OAS installation is running, you can connect to the individual containers with the OAS Configuration application and inspect Tags or any other feature. You will need to connect using the container’s assigned IP address, found by inspecting the Host Docker service. If you have not mapped the custom ports to the defaults of 58725 and 58727, you can use these directly with the containers’ IPAddress. If you have mapped ports, you can use the host’s IP address (or localhost on the host itself) with the custom ports.

Considerations for Windows Containers

Assuming you are running Docker Desktop on Windows, you first need to make sure to switch to “Windows Containers”. By default, Docker Desktop assumes you will be using Linux containers with Hyper-V. To make the switch, you can go to the Docker Desktop tool and select “Switch to Windows containers…”

Alternatively, you can use the following Windows PowerShell script to switch:

& $Env:ProgramFiles\Docker\Docker\DockerCli.exe -SwitchDaemon .

NOTE: Switching to Windows containers requires a minimum of Windows 10 Pro or Windows Server. Windows Home is not supported.

Watch Window

Below is a video tutorial detailing how to use the Watch Window:

The Watch Window is a feature of the OAS Configure Application that allows you to view the value of multiple tags at one time.   You can use it to view multiple tags from one Service installation or from multiple Service Installations at the same time.

It is free to use with the demo license or an active license for at least any one product feature.

The Watch Window is accessible from the Configure Tags screen. It can be opened by clicking the Watch Window button on the top menu bar.

Watch Window
To add a tag to the Watch Window,  select any tag and right click on it.  Then choose Add to Watch from the context menu.

Watch Window

The tag you selected will then appear in the Watch Window.

Watch Window

To resize the Watch Window, grab it by the bottom right corner and drag it to the size you would like.

You can also add a Tag Group to the Watch Window.  To do this, select the Tag Group, right click on it and choose Add to Watch.

Note: that it won’t add the tags in nested groups, if you want to do that, you must add the sub groups individually as well.

To delete Tags from the Watch Window, simply select the tags you want to delete and click the delete button.  You can hold the shift key to select multiple non-adjoining tags and the control key to select multiple adjoining tags.

You can save the current configuration in your Watch Window if you’d like.  Choose Save from the top menu and then save the file to a location on your file system.

The configuration files are saved in CSV format so you can open them in Excel and edit them yourself manually.  You can specify the Network Node and then the Tag Name right in Excel.

You can create and save multiple configurations for different purposes.  It is a very useful feature.

The Watch List feature is free to use with OAS with either the demo license or an active license for at least any one product feature.

If you want to run two separate Watch Windows, you can do that by opening a second instance of the OAS configure application and then open the second Watch Window there.  You can see now that I have two separate Watches running independently of each other.

IIoT Private Label

You can private label Open Automation Software to deploy as your own IIoT software product quickly and easily.  Edit the file OEMSettings.csv to include your company name, product name, support email, and web links.  The settings will update the Configure OAS application, OAS Service application, and messages from the OAS Engine.

Prerequisite: OAS version 14.00.0017 or later must be used to support the OEM Settings. 

OEMSettings.csv

The OEMSettings.csv file should be places in the same directory where the OAS Configuration.exe file, OAS_Service_Control.exe file, and OASEngine.exe service is deployed.  The OEM Settings will update both the Windows version and Linux version of the OAS Engine, the file is identical for both versions.

The default location for Windows installation is C:\Program Files\Open Automation Software\OAS\ where you will find the example file.  If editing directly in the installation folder launch your editor to Run As Administrator.  As an alternative copy the file to another location for editing and copy back to the installation directory.

The default location for Linux installation is in the oas-linux root.

The OEMSettings.csv contains 2 columns, Item Name and Value.  The item names must remain as the default names as these names are used as the identifier.  The values will be changed to match your desired names and links.

Following are default values of the OEMSettings.csv file.

“Item Name”,”Value”
“Company Name”,”Open Automation Software”
“Product Name”,”Open Automation Software”
“Short Product Name”,”OAS”
“Help Web Page”,”/knowledge-base/getting-started-with-oas/”
“Videos Web Page”,”/videos/”
“License Key Generation Web Page”,”/manual-license-key-generator/”
“Classic OPC Server Troubleshoot Web Page”,”/knowledge-base/overview-opc-troubleshooting/”
“Access Remote Mapped Drive Web Page”,”/ufaqs/logging-ms-access-remote-mapped-drive-get-error-data-logging/”
“Contact Company for Maintenance Renewal”,”Contact Open Automation Software at https://openautomationsoftware.com or reseller for renewal or install previous version.”
“Support Email”,”support @ oasiot.com”
“OPC UA Session Name”,”Open Automation Software”
“OPC UA Application Name”,”Open Automation Software@localhost”
“OPC UA Application Uri”,”urn:localhost:OpenAutomationSoftware:OpenAutomationSoftware”
“OPC UA Product Name”,”urn:OpenAutomationSoftware”
“OPC UA Certificate Subject Name”,”CN=Open Automation Software@localhost/O=Open Automation Software”
“ProgramData Folder”,”OpenAutomationSoftware”
“AppData Folder”,”Open Automation Software”
“Tag Prefix”,”Open Automation Software”
“Service Prefix”,”OAS”
“Engine Service”,”OAS Engine”
“Framwork 4.6.1 Service”,”OAS Framework 4.6.1 Service”
“Reports Service”,”OAS Reports Service”
“Classic OPC Service”,”OAS OPC Service”
“Config App Image Path”,”Custom\Logo.ico”

OAS Configuration Application Icon

You can define the application icon using InstallShield or other install builder using the Shortcuts item.  In InstallShield project go to Shortcuts and select the shortcut for the OAS Configuration application.  There you can set the Icon property to your desired .ico file.

 

OAS File Locations

Following is where you can find the locations of the Open Automation Software options, license, and other default files.

Config Files Folder

The Config Files Folder is a specific folder in the operating where the OAS options, license, custom objects files are located.

Linux operating system there is a ConfigFiles sub-directory located in the directory you have deployed the OAS Engine.

Note: If moving the OAS Engine folder in Linux make sure all files in the ConfigFiles sub-directory are moved with the OAS Engine.

Windows operating system this is C:\ProgramData\OpenAutomationSoftware\ConfigFiles\

Note: ProgramData is by default a hidden directory in Windows and you can use Windows Explorer to show hidden folders.

To view ProgramData follow these steps.

  • open File Explorer options from Control Panel
  • Then to View Tab.
  • Uncheck “Hide protected Operating system files” and click on “Show hidden files and folders”
  • Press Yes and then OK.

 

OAS.Options

The OAS.Options file contains all settings defined under Configure-Options of the Configure OAS application.

OAS.license

The OAS.license file will be updated with an activation with the OAS Serial Number to enable product features and the number of tags in the license.

OAS.GUID

The OAS.GUID file will be generated the first time the OAS Engine starts on a new operating system.  This contains a unique identifier for store and forward functionality after a system restart.

OAS.CustomObjects

The OAS.CustomObjects file is generated any time a custom object is programmatically assigned using the OASConfig or OPCSystems component.  This is also the file that will persist all user changes for the Web HMI Dashboard.


OAS Options

All options can be set using the Configure OAS application with Configure-Options or programmatically with the OASConfig .NET component,  OPCSystems .NET component, or REST API for OAS.  All options are persisted in the OAS.options file in the ConfigFiles sub-directory.

Default Configuration Files

Use the Configure OAS application with Configure-Options-Default Files to specify the file path of the default configuration files to load when the operating system restarts. These settings are stored with the OAS.options file.

System Logging

Use the Configure OAS application with Configure-Options-System Logging to specify the file path of the OAS System Errors, Communication Errors, and Transaction Logs. These settings are stored with the OAS.options file.

Store and Forward Folder

Use the Configure OAS application with Configure-Options-Data Buffer to specify the folder to use for data logging and alarm logging store and forward feature. This setting is stored with the OAS.options file.

Retain Values on System Restart

Use the Configure OAS application with Configure-Options-Retain Values to specify the file path to retain Values and Alarm Limit changes, Time On and Counts, Realtime Trending, and Realtime Alarms. These settings are stored with the OAS.options file.

File Data Source

Use the Configure OAS application with Configure-Options-File Data Source to specify the file path for files when Tags are set to a Data Source of File-Text, Binary, or XML. This setting is stored with the OAS.options file.


OPC UA Trusted Certificates

If the OPC UA Server you are connecting to has security restriction using Certificates you can move the rejected certificates to the trusted certificates under following paths.

Linux operating system there will be a pki sub-directory created under the directory where the OAS Engine is located.

Windows operating system this is C:\ProgramData\OpenAutomationSoftware\pki\

C:\ProgramData\OpenAutomationSoftware\pki\rejected\certs
C:\ProgramData\OpenAutomationSoftware\pki\trusted\certs

Linux Installation

Prerequisites

For any Linux installation, general knowledge of Linux server configuration is required.
This includes being comfortable with the following tasks:

  • managing user accounts
  • managing files and user permissions
  • transferring files between machines
  • networking configuration
  • configuring services (daemons in systemd)

While OAS is happy to support the OAS installation and any issues related to the product, support does not include managing Linux server configuration and administrative tasks.


Deployment

Copy OASEngine files to Linux server/device

After downloading the Linux OAS Engine from the OAS Downloads page extract the contents of the .ZIP file (e.g. oas-linux.zip) to any directory of the Linux operating system.  The contents can be copied to the target Linux machine directly, or you can copy the .ZIP archive and unzip on the Linux machine itself.


Installation Script

Note: Perform the installation on your Linux system using root access or with an account with sudo privileges.

The following are instructions for using the included installation script. This script has been thoroughly tested on Ubuntu, but may not work properly in all Linux distributions. For example some scripted operations are blocked on Debian and Debian variants such as Raspbian. If you experience issues running the script or if the OAS server does not start after running the script, we suggest using the Manual Installation method.

View the following video to view the following steps implemented with Ubuntu on a Raspberry Pi device.

Run the installation script to properly configure the OASEngine

Log into your Linux machine with an account that has root or sudo permissions. Either connect to the machine from an SSH session, or open a terminal on the machine itself, if you’re using a GUI.

Navigate to the daemon directory within the installation path and locate the oas_install.sh script. In this example, we’re using the ARM64 installation on a Raspberry Pi 4 running Ubuntu, but the same instructions and commands apply to any Linux distribution.

 

Ensure the installation script is executable, then run the installation using the following commands:

sudo chmod +x oas_install.sh
sudo ./oas_install.sh

NOTE: When you execute any script on Linux and receive an error such as “No such file or directory”, this may be resolved by converting the file to unix-type line breaks. This can be done with the command dos2unix which is installed using the following command on many Linux distributions:

sudo apt update
sudo apt install -y dos2unix

You will be prompted to enter the password for the root or administrator currently logged in if you don’t currently have sudo permissions.

The installation script will next walk you through the following:

  • Creating or selecting a user account for the OASEngine service. Using the defaults, an account called oasuser will be created.
  • Installing the service in the selected user’s account
  • Optionally starting the newly installed service
Step 1: run the installation and select a user account to host the OASEngine. If the user does not exist, you will be prompted to create a password for the new user.
Step 2: the installation completes and prompts to be started
Step 3: Installation completed and service started.rol
 

The OASEngine is now installed as a user service or daemon under the account selected or created (default: oasuser). This service is managed by systemd and can be controlled or monitored like any systemd service. By default, the OASEngine is now configured to start up when the machine reboots.

On a Windows PC, open the OAS Configuration Application and connect to the running Linux service for configuring and controlling the server. Ensure that the PC Firewall allows TCP communication on port 58727. For more information on configuring an OAS installation see the documentation for the OAS Configuration Manager application.


Manual Installation

Unless noted, all operations below must be performed under the root account, or using an account with sudo permissions.

Create a Service User Account

The following commands will create a user named oasuser, however you can use any valid username. If not using the default oasuser name, be sure to use that name in further instructions where oasuser is mentioned.

sudo useradd -m oasuser
sudo loginctl enable-linger oasuser
sudo passwd oasuser

The passwd command will prompt you to enter and confirm a password for this user. Be sure to store this password securely as it will be needed for logging in and managing the OAS Service.

Copy OAS Service files to Service User’s home

Copy the unzipped installation directory to the OAS Service user’s home. Then set ownership of the installation directory and contents to the OAS Service user. In this example, the install directory is oas-linux, but depending on the version being used, this may also be oas-linux-arm or oas-linux-arm64.

sudo chown -R oasuser:oasuser /home/oasuser/oas-linux

Configure OAS Service to start on boot

Edit the oas-engine.service file located in the daemon directory within the installation path using nano, vi or your favorite text editor on Linux. Modify the file by changing references to oasuser to your OAS Service username if you have chosen another, and modify the oas-linux path to oas-linux-arm or oas-linux-arm64 if you are using either of those versions. Make all modifications necessary for the file to resemble the one below:

[Unit]
Description=Open Automation Software Engine

[Service]
ExecStart=/home/oasuser/oas-linux/OASEngine
WorkingDirectory=/home/oasuser/oas-linux
SyslogIdentifier=oas-engine
PrivateTmp=false
KillMode=process

[Install]
WantedBy=default.target

Save and copy the oas-engine.service file to the .config directory using the commands below, again replacing oas-linux in the path as necessary:

sudo mkdir /home/oasuser/.config/systemd/user/
sudo cp /home/oasuser/oas-linux/daemon/oas-engine.service /home/oasuser/.config/systemd/user

Log out and log back in as the OAS Service user (oasuser) to complete the installation.

Enable and start the OAS Service

systemctl --user enable oas-engine
systemctl --user start oas-engine

Uninstall

Included with the OAS installation script is an uninstaller, as well. This file is oas_uninstall.sh and located in the same directory as the installation script. Similarly, you will need to mark this file for execution before running it. Only use this script if the installation script was successful. Use the following commands to mark for execution and then start the uninstaller:

sudo chmod +x oas_uninstall.sh
sudo ./oas_uninstall.sh

The uninstaller script will attempt to back out the installation by performing the following actions.

  • Stop the OASEngine service
  • Remove all installation files
  • Remove user account created for running the service (optional)
    When prompted to remove the OAS user account, you can choose ‘no’ to keep the account intact.

For manually uninstalling the OAS Service:

Log into the account created for running the OAS Service

Stop the OASEngine

systemctl --user stop oas-engine

Disable the systemd service

systemctl --user disable oas-engine

You can optionally remove the entire installation directory from the Service User account home or leave it in place if you plan on using OAS again at some point.


Service Control

Confirm that the service is running

Log into the Linux machine using the credential created during the installation. By default this is oasuser. Then, execute the following command to determine the oas-engine status:

systemctl --user status

This should return something similar to:

State: running
Jobs: 0 queued
Failed: 0 units
Since: Mon 2021-03-01 16:34:33 UTC; 3 weeks 6 days ago
CGroup: /user.slice/user-1001.slice/user@1001.service
├─oas-engine.service
│ └─2214 /home/oasuser/oas-linux-arm64/OASEngine

If you do not see the oas-engine.service listed as running, you can begin troubleshooting by attempting to run the OASEngine manually and checking for errors on startup in the console. To do this, locate the OASEngine executable within the installation directory for the user. This will be in the user’s home directory and named oas-linux, oas-linux-arm, or oas-linux-arm64 depending on the version installed. Within this directory, execute the following:

./OASEngine

This will directly start an instance of the service and output feedback on status. If any errors are reported on startup, make note of them and contact OAS Support for more information.

Managing the Service Installation

The installation script created a service configuration file that can be modified with any additional parameters, such as restart behavior. This is particularly useful if you want to automatically restart the OASEngine in the unlikely event that the process is killed or interrupted. You can locate the service configuration file on following path when logged in as the selected user:

~/.config/systemd/user/oas-engine.service

The contents of the file are the following, with the paths adjusted for the specific user and depending on the specific Linux distribution you are using:

[Unit]
Description=Open Automation Software Engine

[Service]
ExecStart=/home/oasuser/oas-linux-arm64/OASEngine
WorkingDirectory=/home/oasuser/oas-linux-arm64
SyslogIdentifier=oas-engine
PrivateTmp=false
KillMode=process

[Install]

Once you log into the Linux machine as the selected user, you can gracefully stop and start the service using the following commands:

Stop the service:

systemctl --user stop oas-engine

Start the service:

systemctl --user start oas-engine

Troubleshooting

The installation script throws errors or returns a ‘No such file or directory’ message

The file may contain incompatible line endings for Linux – see the instructions above for fixing this using the dos2linux command.

The Linux distribution you are using (e.g. Debian and variants) may be incompatible with the installation script. Follow the Manual Installation instructions.

The service does not start on reboot

Ensure that the service is enabled. Log into the server with the OAS Service account created or referenced during the installation – by default this is oasuser. Then execute the following command:

systemctl --user enable oas-engine

Also, be sure that the OAS Service user can run unattended and does not require a login session for services to run. Logged in as root or sudo user, execute the following command:

sudo loginctl enable-linger oasuser

Any other issues?

Contact support@oasiot.com and we will evaluate your configuration and determine the cause.