OHX Core

OHX is a modern Smart Home solution, embracing technologies like software containers for language agnostic extensibility. Written in Rust with an extensive test suite, OHX is fast, efficient, secure and fun to work on.

OHX Core consists of multiple services that work in tandem to form a vendor crossing device interconnect hub (ie connect a ZWave wall switch with a Zigbee light bulb) and Smart Home solution. Find the individual projects in their respective subdirectories. You usually want to use additional OHX Addons for specific device support.

For a ready to use operating system image for single board computers, regular PCs and virtual machines, you might also be interested in OHX OS.

OHX Core Services are safe to be exposed to the Internet and implement encryption, authentication various anti-abuse techniques like IP rate limiting, limited backpressure queues, limited input buffers and safe packet parsing.

!!! WARNING !!!

This is not yet an MVP. Only certain parts work and will break again during development.

Table of Contents

1. Download and Start up
2. Usage
3. OHX Services
4. Compile and Contribute
5. Security
   1. Report a security event or vulnerability
6. Maintainer: Core Deployment

Download and Start up

Please note that OHX can be run as standalone binaries. This option is helpful for development and debugging and explained in the OHX Developer Documentation book.

This section however explains how to run OHX via Docker containers.

About software containers: A software container can easily and in a standardized way be restricted in its resource usage (Memory, CPU, File Access, Network Access, limited Kernel API) to protect the host system from potential malicious Addons or just badly written Addons.

Prerequirement: You must have Docker or a Docker compatible (for example podman) command line tool installed.

Use the docker-compose.yml file to start all relevant containers. Alternatively use the start_containers.sh file if you do not have access to docker compose.

• By default OHX core services will try to start on http port 8080 and https port 8443. Docker port routing is used to expose OHX on port 80 and 443.
• OHX core service containers require a few mounted directories. The mentioned start up methods will use a "ohx_root_dir" directory within the current working directory.
• Use docker run -rm -it docker.pkg.github.com/openhab-nodes/core/ohx-core -h to print a list of command line options to adjust OHX's behaviour.

Usage

The Setup & Maintenance UI can be found on https://localhost/, if you are running OHX on the same system, and on https://ohx.local/ if you are using OHX OS. The pre-configured password for the administrative user is "ohxsmarthome".

You may also use the command line tool (find it in the releases zip file) ohx-cli to interact with OHX. Use ohx-cli --help to print all available commands and ohx-cli the_command --help to show command specific help.

Usually you first want to detect running OHX instances by calling ohx-cli detect and than select one of the found instances to be used for further calls: ohx-cli login 192.168.1.17:443.

OHX Services

In-depth explanations are given in the developer documentation. A quick run down on individual service responsibilities follows.

ohx-core is a thin supervisor for software containers (it uses the docker or podman CLI interface internally) to install, start and manage OHX Addons and access Addon logs.

• Core provides the interconnection service. This service reacts on Addon Thing property changes and sends corresponding Commands to Addons.
• Thing states are exposed via IOService Addons (for example Cloud Connector for Alexa support). Core provides IOServices with changed Addon Thing properties, if configured filters pass. Received Commands are routed back to core and to respective Addons if, again, the configured filters pass.
• ohx-core acts as a notification service. Addons can extend the service by providing additional notification channels.

ohx-backup executes backup strategies. It requires full read access to the ohx_root_dir and write access to a ohx_root_dir/backups directory.

• Backup strategies cannot be extended via Addons (yet?). Two strategies are provided:
  • Google Drive
  • Local files
• If the config directory is a git repository:
  • By default 24 hours after a change has been registered, a commit of all changes up to the current time is performed.
  • A user may create named configuration "snapshots" (git tags).
  • The service allows to restore configuration to a previous or more recent snapshot

ohx-serve is a static https file server for web-uis.

• It generates a self-signed https certificate if none is found at start up
• It redirects http requests to https. Always.
• It provides a REST-like access (GET/POST/PUT/DELETE) to ioservice and interconnection configurations, rules, scripts, and general configuration.
• Without ohx-serve there will be no http(s) server, so no Setup & Maintenance Web UI and no way to manipulate configurations, rules, scripts via a web API. You can still just alter the files for configuration.

ohx-ruleengine is an Event, Condition, Action rule engine.

• Addons can register additional "Events", "Conditions", "Actions" and "Transformations" types. Please check the Rust generated documentation as well as the more detailed rule engine readme.
• Without ohx-ruleengine scripts and rules are not enabled, but Addon interconnection does work. If you only require the interconnect functionality, just do not start up ohx-ruleengine.

ohx-auth is an Identity and Access Management service, based on OAuth with JWT tokens and OHX specific scopes.

• User accounts are stored in flat files.
• It also manages extern OAuth Tokens and token refreshing, like the https://openhabx.com cloud link for Amazon Alexa and Google Home support.
• Without ohx-auth you will not be able to login via the command line utility or the Setup & Maintenance Web UI.
• Initial access token generation for inter-service communication is done by ohx-auth.
• Periodic access token refreshment will not work without ohx-auth. As soon as core service and addon tokens have expired, ohx will come to a halt.

Compile and Contribute

OHX is written in Rust. You can develop for Rust in Jetbrains CLion, Visual Studio Code, Visual Studio and Eclipse. Compile with cargo build and for production binaries use cargo build --release.

Run with ./build_and_start.sh.

PRs are welcome.

• A PR is expected to be under the same license as the repository itself and must pass the test suite which includes being formatted with rustfmt.
• Newly introduced dependencies must be under any of the following licenses: MIT, Apache 2, BSD.
• OHX follows Semantic Versioning for versioning. Each service in this repository is versioned on its own.

Security

Despite everyone’s best efforts, security incidents are inevitable in an increasingly connected world. OHX is written in Rust to avoid common memory access and memory management pitfalls as well as user input parsing bugs, even for new contributors.

Industry standards like OAuth and https are used on the external interface level. Encryption and https certificate management is based on Rustls and Ring (based on boringssl), two well maintained Rust crates. No openSSL or C legacy involved.

Limited input buffers and bounded backpressure queues prevent abuse and denial of service attacks.

On Linux only: Modern operating system kernel features restrict internet provided executables ("Scripts", "Addons") via network user namespaces, cgroups and seccomp.

Report a security event or vulnerability

OHX maintainers are committed to provide a secure solution within the limits that are publicly documented. Should a serious security incident occur, OHX maintainers will:

• Communicate major risks via the websites news blog
• Issue a risk warning message via the cloudconnector Addon (if enabled)
• Fill a report on RustSec, so that automatic auditing tools know about vulnerable releases.

Report any findings to security@openhabx.com.

Maintainer: Core Deployment

Update the CHANGELOG file before releasing! Use scripts for deployment that are found in scripts/:

• build.sh: Cross compile for x86_64, armv7l, aarch64 as static musl binaries
• deploy.sh: Deploy to Github Releases as zipped distribution and to the Github Package Registry as Docker container, both including the latest revision of the Setup & Maintenance Web-UI.

---

David Gräff, 2019-2020