Skip to main content

CODESYS Virtual Safe Control SL per Kommandozeile verwalten

Für die Verwaltung und Bedienung der CODESYS Virtual Safe Control SL auf einem Linux-Gerät kann direkt über die Kommandozeile mit der VirtualControlAPI interagiert werden.

Die VirtualControlAPI ist ein Python-basiertes Kommandozeilenwerkzeug zur Verwaltung der CODESYS Virtual Safe Control SL auf Linux-Systemen und wird ebenfalls vom CODESYS Control SL Deploy Tool verwendet.

Vorraussetzungen

  • Ein Gerät mit Linux-basiertem Betriebssystem

  • Python 3 (>= 3.9)

  • Das Skript VirtualControlAPI.py

. Sie haben zwei Möglichkeiten, das Skript VirtualControlAPI.py zu erlangen:

  • Möglichkeit 1 (empfohlen):

    Installieren Sie, falls noch nicht geschehen, das Package CODESYS Virtual Control for Linux SL zu Ihrer CODESYS-Installation auf Windows hinzu. Danach finden Sie das Skript VirtualControlAPI.py im Verzeichnis <CODESYS installation directory>\CODESYS Virtual Control for Linux SL\Delivery\virtuallinux\VirtualControlAPI.py.

  • Möglichkeit 2:

    Laden Sie das Package CODESYS Virtual Control for Linux SL aus dem Store herunter und entpacken Sie das Package .package (beispielsweise CODESYS Virtual Control for Linux SL 4.18.0.0.package) mit einem beliebigen ZIP-Programm. Im entpackten Verzeichnis finden Sie das Skript VirtualControlAPI.py unter: Delivery\virtuallinux\VirtualControlAPI.py.

Bedienung

Das Python-Skript VirtualControlAPI.py muss gegebenenenfalls mit root-Privilegien ausgeführt werden. Mit dem Skript werden unter anderem Änderungen an Container-Registrys vorgenommen und Namensräume der Netzwerkadapter modifiziert.

sudo python3 VirtualControlAPI.py <command>

Über folgendes Kommando können Sie eine Hilfe zu allen möglichen Optionen, Parameter und Beschreibungen ausgeben:

sudo python3 VirtualControlAPI.py --help

Typischer Workflow

  1. Importieren eines Container-Images in die lokale Registry

    Um ein Image in die Registry zu laden, verwenden Sie den Befehl --import-image und übergeben den Namen der .tar.gz-Datei, in der sich das Image befindet. Dadurch wird das Image in die lokale Registry überführt.

    Beispiel 5. Beispiel:
    sudo python3 VirtualControlAPI.py --import-image Docker_codesyscontrol_virtuallinux_4.19.0.0_amd64.tar.gz


    Um zu sehen, welche Images bereits in der lokalen Registry vorhanden sind, verwenden Sie den Befehl:

    sudo python3 VirtualControlAPI.py --list-images

    Es werden nur Images angezeigt, die die Kriterien der VirtualControlAPI erfüllen.

  2. Erstellen einer Instanz

    Um eine Runtime-Instanz zu erzeugen, wird folgender Befehl verwendet:

    sudo python3 VirtualControlAPI.py --add-instance <instance name>

    Wenn Sie eine EdgeGateway-Instanz oder eine Safe-Runtime-Instanz erstellen wollen, geben Sie dies am Ende des Kommandos an.

    udo python3 VirtualControlAPI.py --add-instance <instance name> --safety
sudo python3 VirtualControlAPI.py --add-instance <instance name> --gateway

    Dies ist notwendig, da die verschiedenen Instanztypen mit unterschiedlichen Standardkonfigurationen und Standardparametern ausgestattet sind.

  3. Konfigurieren der Instanz

    Um die erstellte Instanz zu konfigurieren, ist es ratsam, zunächst die möglichen Konfigurationsparameter einzusehen. Hierfür stellt nachfolgender Befehl die Konfigurationsdatei in formatierter Form dar:

    sudo python3 VirtualControlAPI.py --get-configuration <instance name>

    Die unter CONFIG_KEY aufgelisteten Parameter sind in der Regel alle konfigurierbar und können mit dem nachfolgendem Befehl bearbeitet werden:

    sudo python3 VirtualControlAPI.py --configure <instance name> [set/add/remove] <CONFIG_KEY> <value>

    • set überschreibt den aktuellen Wert

    • add fügt Werte hinzu

    • remove enfernt den akutellen Wert

    In der Regel wird für einen ersten Start lediglich das Setzen des CONFIG_KEY-Image benötigt. Führen Sie dafür folgenden Befehl aus und ersetzen das Image durch das passende Image. Sie können alle Images mit dem Befehl --list-images anzeigen.

    Beispiel 6. Beispiel
    sudo python3 VirtualControlAPI.py --configure <instance name> set Image codesyscontrol_virtuallinux:4.19.0.0


    Wichtig

    Damit eine Instanz konfiguriert werden kann, muss sie sich im gestoppten Zustand befinden.

  4. Starten/Stoppen der Instanz

    Über die Option --run wird die Instanz gestartet werden, während sie mit --stop gestoppt wird.

    sudo python3 VirtualControlAPI.py --run <instance name>
sudo python3 VirtualControlAPI.py --stop <instance name>

Für weitere Informationen zu den Optionen und Exitcodes führen Sie den Befehl sudo python3 VirtualControlAPI.py --help aus.

Beispiel Szenario "The Safe House" via Scripting

Die folgenden Teilskripte beschreiben unter anderem, wie das Szenario "The Safe House" über die VirtualControlAPI erreicht werden kann.

Wichtig

Im Artikel "The Safe House" werden weitere technische Aspkete beleuchtet, die für das Betreiben einer sicheren Steuerung relevant sind. Bitte konsultieren Sie diese Hilfeseite, sowie die Sicherheitsdokumentation des Herstellers des Gerätes für sämtliche Sicherheits- oder Zertifizierungsinformationen.

Vorbereitungen

Um das Skript VirtualControlAPI.py, sowie die aktuellsten Versionen der Images der CODESYS Virtual Control for Linux SL zu erhalten, folgen Sie den Anweisungen aus dem Schritt Vorraussetzungen aus dem vorherigem Kapitel. Wiederholen Sie Ihr Vorgehen für CODESYS Virtual Safe Control SL, um die Images für CODESYS Virtual Safe Control SL sowie CODESYS Virtual Safe Time Provider SL herunterzuladen. Die Container-Images finden Sie, je nach Methode, in folgenden Verzeichnissen:

  • Möglichkeit 1:

    Die Container-Images liegen als tar.gz-Datei in folgendem Verzeichnis:

    <CODESYS installation directory>\CODESYS Virtual Control for Linux SL\Delivery\<product>\

    <CODESYS installation directory>\CODESYS Virtual Safe Control SL\Delivery\<product>\

  • Möglichkeit 2:

    Die Container-Images liegen als tar.gz-Datei in folgendem Verzeichnis des CODESYS-Packages:

    Delivery\<product>\

  • Möglichkeit 3 - Scripting:

    Möglichkeit 2 kann auch durch die Verwendung von Skripten erreicht werden. Sehen Sie dazu folgendes Beispielskript zum Download und Entpacken des CODESYS-Package sowie zum Pushen der Images auf die Infrastruktur Ihrer Firma.

    Tipp

    Bitte beachten Sie die Lizenzbedingungen zur Nutzung einer CODESYS-Software.

    DownloadUnpackPush.cmd

    @echo off
setlocal EnableDelayedExpansion

REM ===== Configuration =====
set ZIP_URL_vControl=https://store.codesys.com/ftp_download/3S/VirtualLinuxSL/000138/4.18.0.0/CODESYS%%20Virtual%%20Control%%20for%%20Linux%%20SL%%204.18.0.0.package
set ZIP_URL_vSafe=https://store.codesys.com/ftp_download/3S/VirtualSafeSL/000139/4.18.0.0/CODESYS%%20Virtual%%20Safe%%20Control%%20SL%%204.18.0.0.package

set ZIP_FILE_vControl=%TEMP%\CODESYS Virtual Control for Linux SL 4.18.0.0.package
set ZIP_FILE_vSafe=%TEMP%\CODESYS Virtual Safe Control SL 4.18.0.0.package

set DEST_DIR=C:\ExtractedFiles
set "vControlDir=%DEST_DIR%\vControl"
set "vSafeDir=%DEST_DIR%\vSafe"

set "REGISTRY=example.registry.com"

REM ===== Create destination folder =====
if not exist "%vControlDir%" mkdir "%vControlDir%"
if not exist "%vSafeDir%" mkdir "%vSafeDir%"

REM ===== Download ZIP =====
curl -L --ssl-no-revoke --no-keepalive --retry 5 --retry-delay 2 -o "%ZIP_FILE_vControl%" "%ZIP_URL_vControl%"
curl -L --ssl-no-revoke --no-keepalive --retry 5 --retry-delay 2 -o "%ZIP_FILE_vSafe%" "%ZIP_URL_vSafe%"

REM ===== Extract ZIP =====
"C:\Program Files\7-Zip\7z.exe" x "%ZIP_FILE_vControl%" -o"%vControlDir%" -y
"C:\Program Files\7-Zip\7z.exe" x "%ZIP_FILE_vSafe%" -o"%vSafeDir%" -y

REM ===== load images to docker and push to registry =====

for /f "tokens=3 delims=: " %%I in ('docker load -i "%vControlDir%\Delivery\virtuallinux\Docker_codesyscontrol_virtuallinux_4.18.0.0_amd64.tar.gz"')
    do (
    docker tag %%I %REGISTRY%/%%I
    docker push %REGISTRY%/%%I
)
for /f "tokens=3 delims=: " %%I in ('docker load -i "%vControlDir%\Delivery\edgeamd64\Docker_codesysedge_edgeamd64_4.18.0.0_amd64.tar.gz"')
     do (
    docker tag %%I %REGISTRY%/%%I
    docker push %REGISTRY%/%%I
)

for /f "tokens=3 delims=: " %%I in ('docker load -i "%vSafeDir%\Delivery\linuxsafei386\Docker_codesyssafecontrol_linuxsafei386_4.18.0.0_i386.tar.gz"')
     do (
    docker tag %%I %REGISTRY%/%%I
    docker push %REGISTRY%/%%I
)
for /f "tokens=3 delims=: " %%I in ('docker load -i "%vSafeDir%\Delivery\linuxsafetimeprovider\Docker_codesyssafetimeprovider_linuxsafetimeprovider_4.18.0.0_amd64.tar.gz"')
     do (
    docker tag %%I %REGISTRY%/%%I
    docker push %REGISTRY%/%%I
)

echo Done.
endlocal
pause

Zusätzliche Vorbereitung:

Laden Sie auf gleichem Weg die Packages für CODESYS License Server for Linux SL und CODESYS CodeMeter for Linux SL herunter.

Da CODESYS Virtual Control for Linux SL nur über eine Netzwerklizenzierung lizensiert werden kann, werden diese beiden Packages für die Lizenzierung benötigt. Für einen Testaufbau ist dieser Schritt nicht notwendig, aber empfohlen und in den folgenden Skripten berücksichtigt.

Übertragen des Skriptes, der debian-Pakete und der Container-Images auf die Steuerung

Für eine Einzelanwendung können Sie die einzelnen Dateien aus den CODESYS-Packages direkt auf die Zielgeräte übertragen. Beispielsweise mit pscp:

pscp -pw password <PathToDockerImage.tar.gz> user@<IP>:~/

Wenn die Container-Images, VirtualControlAPI.py und gegebenenfalls nötige debian-Packages auf einem internen Server oder eine interne Container-Registry geladen wurden, können Sie diese auch direkt von dort beziehen.

#!/bin/bash docker pull example.registry.com/codesyscontrol_virtuallinux:4.18.0.0
docker pull example.registry.com/codesyssafecontrol_linuxsafei386:4.18.0.0
docker pull example.registry.com/codesysedge_edgeamd64:4.18.0.0

curl my-server-url/VirtualControlAPI.py -o VirtualControlAPI.py

Skript für automatisches Setup des Szenarios "The Safe House"

Anmerkung

Folgende Skripte dienen lediglich als Beispiel. Sie müssen gegebenenfalls Anpassungen an der Version, den Netzwerkadaptern, der IP-Addressen, etc. machen.

In den folgenden Beispielen wird angenommen, dass die einzelnen Dateien nach dem Entpacken aus dem CODESYS-Package direkt auf die Steuerung übertragen wurden. Passen Sie die Skripte entsprechend Ihres Anwendungsfalles an.

Linux-Host-PC 2

Navigieren Sie in das Verzeichnis, in dem sich die VirtualControlAPI.py sowie die .tar.gz-komprimierten Container-Images befinden. Passen Sie das folgende Skript an Ihre Gegebenheiten an und führen Sie es aus.

SetupExample_LinuxHostPC2.sh

#!/bin/bash

# load images into registry
docker load -i Docker_codesyssafetimeprovider_linuxsafetimeprovider_4.18.0.0_amd64.tar.gz

# create timeprovider instance and configure
python3 VirtualControlAPI.py -a timeprovider --timeprovider
python3 VirtualControlAPI.py -c timeprovider set Image codesyssafetimeprovider_linuxsafetimeprovider:4.18.0.0
python3 VirtualControlAPI.py -c timeprovider set GenericCommands -e TARGET_IP=10.0.0.4 -e TARGET_PORT=60000

python3 VirtualControlAPI.py -r timeprovider

Linux-Host-PC

Navigieren Sie in das Verzeichnis, in dem sich die VirtualControlAPI.py sowie die .tar.gz-komprimierten Container-Images befinden. Passen Sie das folgende Skript an Ihre Gegebenheiten an und führen Sie es aus.

SetupExample_LinuxHostPC.sh

#!/bin/bash

# load images into registry
docker load -i Docker_codesyscontrol_virtuallinux_4.18.0.0_amd64.tar.gz
docker load -i Docker_codesysedge_edgeamd64_4.18.0.0_amd64.tar.gz
docker load -i Docker_codesyssafecontrol_linuxsafei386_4.18.0.0_i386.tar.gz
dpkg -i codemeter-lite_8.30.6885.501_amd64.deb
dpkg -i codesyslicenseserver_licenseserver_4.18.0.0_all.deb

# create runtime instance and configure
python3 VirtualControlAPI.py -a vPLC
python3 VirtualControlAPI.py -c vPLC set Image codesyscontrol_virtuallinux:4.18.0.0
python3 VirtualControlAPI.py -c vPLC set Ipc shareable
python3 VirtualControlAPI.py -c vPLC set LicenseServer 10.0.0.4

# create edge gateway instance and configure
python3 VirtualControlAPI.py -a vGateway --gateway
python3 VirtualControlAPI.py -c vGateway set Image codesysedge_edgeamd64:4.18.0.0

# create safe runtime instance and configure
python3 VirtualControlAPI.py -a vSafePLC --safety
python3 VirtualControlAPI.py -c vSafePLC set Image codesyssafecontrol_linuxsafei386:4.18.0.0
python3 VirtualControlAPI.py -c vSafePLC set Ipc container:vPLC
python3 VirtualControlAPI.py -c vSafePLC set Dependencies vPLC

python3 VirtualControlAPI.py --run-all

Nach Ausführung der Skripte auf den jeweiligen Rechnern sind die Instanzen nach dem Vorbild des Szenarios konfiguriert und befinden sich im Zustand Running. Damit sind alle notwendigen Geräte fertig vorbereitet. Die weiteren Schritte zur Erstellung eines Projekts und Einbindung von PROFIsafe sind in der Dokumentation CODESYS Safety Extension beschrieben.

Skript für Update der Laufzeitinstanzen

Für ein Versionsupgrade der einzelnen Instanzen sind nur wenige Befehle erforderlich. Durch das Stoppen, Ändern des Container-Images und erneute Starten der Instanzen bleiben sämtliche anderen Einstellungen erhalten. Sie profitieren jedoch von allen Neuheiten und Verbesserungen der neuen Version.

Stellen Sie die Images so auf dem Gerät bereit, wie Sie es in den vorherigen Schritten getan haben.

UpgradeVersions.sh

#!/bin/bash

# load images into registry
docker load -i Docker_codesyscontrol_virtuallinux_4.19.0.0_amd64.tar.gz
docker load -i Docker_codesysedge_edgeamd64_4.19.0.0_amd64.tar.gz
docker load -i Docker_codesyssafecontrol_linuxsafei386_4.19.0.0_i386.tar.gz

# stop all instances. If only selective instances should be upgraded, use python3 VirtualControlAPI.py -s <instance name> to only stop specific instances
python3 VirtualControlAPI.py --stop-all

# configure new images for instances
python3 VirtualControlAPI.py -c vPLC set Image codesyscontrol_virtuallinux:4.19.0.0
python3 VirtualControlAPI.py -c vGateway set Image codesysedge_edgeamd64:4.19.0.0
python3 VirtualControlAPI.py -c vSafePLC set Image codesyssafecontrol_linuxsafei386:4.19.0.0

# start all instances
python3 VirtualControlAPI.py --run-all

Fehlerbehebung

Fehler

Symptom

Ursache

Lösung

Permission denied / Zugriffsfehler

Fehlermeldung: PermissionError: [Errno 13] Permission denied

Das Skript benötigt erhöhte Rechte, beispielsweise für Zugriff auf Container Registry, Systempfade und Änderungen am Namespacing der Netzwerkadapter.

Führen Sie den Befehl mit sudo erneut aus.

sudo python3 VirtualControlAPI.py <command>

Image wird nicht in der Registry angezeigt

--list-images zeigt nicht das erwartete Image

Das Image ist nicht kompatibel.

Nur Images, die bestimmte CODESYS-Kriterien erfüllen, werden angezeigt.

Prüfen Sie, ob es ein offizielles CODESYS Virtual Control SL Image ist.

Der Import wurde abgebrochen.

Führen Sie den Import erneut durch.

sudo python3 VirtualControlAPI.py --import-image

Falscher Dateiname / beschädigte Datei

Validieren, ob tar.gz vollständig und lesbar ist.

Instanz bleibt beim Start hängen

Timeout oder endloser Startversuch

Fehlkonfiguration der Netzwerke

Image prüfen

Fehlendes oder inkorrekter Image-Tag

Konfiguration validieren

Container Runtime (beispielsweise Podman/Docker) nicht gestartet

Container-Umgebung neu starten

In diesem Abschnitt: