HOOC Connect E

Über das HOOC Embedded Gateway

Das HOOC Connect E (HOOC Embedded Gateway) richtet sich vor allem an Entwickler und Integratoren, welche die HOOC Lösung in eigene Hardware implementieren möchten. Dadurch kann die HOOC Lösung einfach und ohne zusätzliche Hardware verwendet werden. Aktuell werden die Plattformen Raspberry PI, Linux und MAC unterstützt.

Erste Schritte mit Debian

Nachdem im HOOC Managementportal eine Anlage erstellt wurde, erfolgt die Aktivierung nach untenstehenden Punkten:

  1. Linken des HOOC Gateways mit einer Anlage mittels Eingabe Seriennummer im HOOC Managementportal
  2. Navigation zu HOOC Gateway -> Konfiguration
  3. Auswahl Plattform / Prozessor und das HOOC Connect Binary ohne VPN-Zugangsdaten auf eigene Hardware herunterladen
  4. HOOC Connect Binary umbenennen in app_embeddedgateway mittels Kommando mv
  5. Mittels Kommando chmod +x das app_embeddedgateway ausführbar machen
  6. Starten des app_embeddedgateway mit Parameter hwid
  7. Kopieren des 64-Stelligen Hardware-Identifikations-Codes (Console Output app_embeddedgateway) in das entsprechende Feld im HOOC Managementportal und aktivieren.

Der Hardware-Identifikations-Code (hwid) ist ein eindeutiger Code, welcher die Hardware identifiziert. Dadurch wird sichergestellt, dass ein Lizenzschlüssel nur von der jeweiligen Hardware verwendet werden kann. Erst nach erfolgreicher Bestätigung des Hardware-Identifikations-Code kann das HOOC Connect Binary mit den VPN-Zugangsdaten der Anlage heruntergeladen werden.

  1. Auswahl Plattform / Prozessor und das HOOC Connect Binary mit VPN-Zugangsdaten auf eigene Hardware herunterladen
  2. HOOC Connect Binary umbenennen in app_embeddedgateway mittels Kommando mv
  3. Mittels Kommando chmod +x das app_embeddedgateway ausführbar machen
  4. Starten des app_embeddedgateway als root-user

Nun sollte der Console Output INFO[0000] Successfully connected to VPN... ersichtlich sein. Zudem wird der Status der VPN-Verbindung auf im HOOC Managementportal angezeigt.

Use Case Bridge

Das HOOC Connect Binary erstellt beim Starten das Netzwerkinterface hooc-tap0. Falls nun die selbe Funktionalität wie beispielsweise beim HOOC Connect H gewünscht ist, muss eine Brücke zwischen dem physikalischen Netzwerkinterface, beispielsweise eth0 und dem hooc-tap0 konfiguriert werden. Bei untenstehenden Konfigurationsbeispielen bezieht die Brücke per DHCP eine IP Adresse.

Falls Sie iptables verwenden, stellt der Befehl iptables -A FORWARD -j ACCEPT -i br-hooc -o br-hooc sicher, dass die Brücke Datenpakete korrekt weiterleitet. Falls Docker verwendet wird, muss dieser Befehl zwingend ausgeführt werden.

Nicht persistente Konfiguration

Die nicht persistente Konfiguration ist nach einem Neustart des Betriebssystems nicht mehr vorhanden. Stellen Sie sicher, dass die Pakete net-tools und bridge-utils installiert sind. Führen Sie untenstehende Befehle als root-user aus.

# Create the bridge br-hooc
brctl addbr br-hooc
# Add the physical eth0 to the br-hooc bridge
brctl addif br-hooc eth0
# Remove IP eth0
ifconfig eth0 0.0.0.0
# Bring eth0 up
ifconfig eth0 up
# Obtain IP from local DHCP-Server
dhclient br-hooc
# Start the embedded gateway as root user with the bridge parameter
./app_embeddedgateway --vpn.linux.bridge=br-hooc

Persistente Konfiguration

Die Netzwerkbrücke sowie das physikalische Netzwerkinterface in der entsprechenden Netzwerkkonfigurationsdatei anpassen:

iface eth0 inet manual
iface eth0 inet6 manual

auto br-hooc
iface br-hooc inet dhcp
    bridge_ports eth0

Falls dhcpcd verwendet wird, sollte in der Datei /etc/dhcpcd.conf folgende Anpassungen gemacht werden:

denyinterfaces eth0
interface br-hooc

Mittels Neustart des Geräts oder der Netzwerkschnittstellen wird die persistente Konfiguration übernommen.

Die obenstehende Konfiguration ist nur ein Beispiel für eine Konfiguration. Diese muss je nach Betriebssystem und Version individuell angepasst werden.

HOOC Embedded Gateway Command Line

Die Kommandozeilenparameter können durch das Flag --help aufgelistet werden.

Verwendung:
  app_embeddedgateway [Flags]  

Flags:
      --api.address string          Die Adresse, an die sich der API-Server binden soll (standardmässig
                                    "127.0.0.1").
      --api.enable                  Legt fest, ob der API-Server aktiviert werden soll oder nicht
                                    (standardmässig `true`).
      --api.port int                Der Port, an den sich der API-Server binden soll (standardmässig 1323).
  -h, --help                        Hilfe für das HOOC Binary.
      --log.file string             Pfad, in den die Logdaten geschrieben werden sollen, wenn nicht
                                    definiert, werden die Logdaten in den stdout geschrieben.
      --vpn.linux.bridge string     Der Name der Bridge-Schnittstelle, zu der das VPN hinzugefügt werden
                                    soll, falls nicht definiert, wird eine eigenständige TAP-Schnittstelle
                                    (hooc-tap0) erstellt.
      --vpn.linux.mac string        Die Mac-Adresse des TAP-Schnittstelle. Wenn nicht definiert, wird eine
                                    zufällige MAC-Adresse erzeugt oder wenn Bridge konfiguriert ist, wird
                                    diejenige der Bridge-Schnittstelle verwendet.
      --vpn.retryinterval duration  Wiederholungsintervall für die Wiederverbindung mit dem VPN-Server
                                    (standardmässig 15s).


Verfügbare Befehle:
  help        Hilfe für das HOOC Binary
  hwid        Generiert und zeigt die Hardwarekennung für die Aktivierung.

HOOC Embedded Gateway REST-API

Zur Kommunikation mit einer übergeordneten Anwendung stellt das HOOC Embedded Gateway eine REST-API zur Verfügung.

Die API Definition (V1) kann hier heruntergeladen werden.

Beispiele Linux (Debian)

Beispiel init.d Skript

Ein OS-spezifisches init.d-Skript wird benötigt, um die Binärdatei getrennt auszuführen.

  #! /bin/sh
  ### BEGIN INIT INFO
  # Provides:          app_embeddedgateway
  # Required-Start:    networking
  # Required-Stop:     networking
  # Default-Start:     2 3 4 5
  # Default-Stop:      0 1 6
  # Short-Description: This is app_embeddedgateway daemon
  # Description:       This is app_embeddedgateway daemon
  ### END INIT INFO
  
  # Using the lsb functions to perform the operations.
  . /lib/lsb/init-functions
  # Process name ( For display )
  NAME=app_embeddedgateway
  # Daemon name, where is the actual executable
  DAEMON=/usr/local/bin/app_embeddedgateway
  # pid file for the daemon
  PIDFILE=/var/run/app_embeddedgateway.pid
  # log file for the daemon
  LOGFILE=/var/log/app_embeddedgateway.log
  
  # If the daemon is not there, then exit.
  test -x $DAEMON || exit 5
  
  case $1 in
  start)
      # Checked the PID file exists and check the actual status of process
      if [ -e $PIDFILE ]; then
          status_of_proc -p $PIDFILE $DAEMON "$NAME process" && status="0" || status="$?"
          # If the status is SUCCESS then don't need to start again.
          if [ $status = "0" ]; then
              exit # Exit
          fi
      fi
      # Start the daemon.
      log_daemon_msg "Starting the process" "$NAME"
      # Start the daemon with the help of start-stop-daemon
      # Log the message appropriately
      if start-stop-daemon --start --quiet --oknodo --background --make-pidfile --pidfile $PIDFILE --exec $DAEMON -- --log.file $LOGFILE; then
          log_end_msg 0
      else
          log_end_msg 1
      fi
  ;;
  stop)
      # Stop the daemon.
      if [ -e $PIDFILE ]; then
          status_of_proc -p $PIDFILE $DAEMON "Stoppping the $NAME process" && status="0" || status="$?"
          if [ "$status" = 0 ]; then
              start-stop-daemon --stop --quiet --oknodo --pidfile $PIDFILE
              /bin/rm -rf $PIDFILE
          fi
      else
          log_daemon_msg "$NAME process is not running"
          log_end_msg 0
      fi
  ;;
  restart)
      # Restart the daemon.
      $0 stop && sleep 2 && $0 start
  ;;
  status)
      # Check the status of the process.
      if [ -e $PIDFILE ]; then
          status_of_proc -p $PIDFILE $DAEMON "$NAME process" && exit 0 || exit $?
      else
          log_daemon_msg "$NAME Process is not running"
          log_end_msg 0
      fi
  ;;
  *)
  # For invalid arguments, print the usage message.
  echo "Usage: $0 {start|stop|restart|status}"
  exit 2
  ;;
  esac

logrotate.d Datei

Wenn das Schreiben einer Logdatei aktiviert ist, wird empfohlen, die Logrotation einzurichten.

  /var/log/app_embeddedgateway.log {
    rotate 7
    daily
    missingok
    compress
    sharedscripts
    postrotate
        touch /var/log/app_embeddedgateway.log
    endscript
  }

Netzwerkschnittstelle

Betreffend Netzwerkschnittstelle git es folgendes zu beachten:

  • Wenn eine Brücke zu einem physikalischen Ethernet-Port gewünscht wird, muss die Brücke erstellt und als Parameter --vpn.linux.bridge.bridge übergeben werden.
  • Das HOOC Embedded Gateway benötigt NET_ADMIN Rechte. Entweder wird das Binary privilegiert ausgeführt oder des werden die Rechte mittels setcap erteilt.
  setcap cap_net_admin=+ep ./app_embeddedgateway