Docs / Weblink-Zertifikat-Deploy

Weblink-Zertifikat-Deploy

Installiere die Weblink-Zertifikate eines Druckers per Einzeiler - Windows mit PowerShell, macOS/Linux/Raspberry Pi mit bash.

Was ist „Cloud Connect“ bzw. „Weblink“ von Zebra?

Weblink (neuere Bezeichnung: Cloud Connect) ist die eingebaute Cloud-Konnektivität moderner Zebra-Industriedrucker (ZPL-Drucker ab der ZT/ZD- und ZQ-Serie). Der Drucker enthält dafür einen eigenen HTTPS/WebSocket-Client direkt in der Firmware und verbindet sich ausgehend mit einem zentralen Endpunkt - der „Location“-URL in seiner Weblink-Konfiguration. So ist der Drucker auch hinter NAT, Firmen-Firewalls oder im reinen WLAN erreichbar, ohne dass ein einziger eingehender Port geöffnet werden muss (TeamViewer-Prinzip, nur umgekehrt: der Drucker ist der Client).

Der Drucker wählt einen von zwei Konfigurations-Slots (weblink.ip.conn1.location / weblink.ip.conn2.location), in dem die Relay-URL hinterlegt ist, und meldet sich dort an. Über diese Verbindung können dann Druckaufträge, SGD-Befehle und Konfigurationsänderungen an den Drucker geschickt werden - die Verbindung bleibt dabei dauerhaft vom Drucker ausgehend offen.

Damit der Drucker den Relay-Server über TLS als vertrauenswürdig einstuft, muss das Zertifikat des Relays auf dem Drucker installiert sein. Genau dafür erzeugt zplCloud je Domain + Drucker die drei Dateien WEBLINK2_CA.NRD, WEBLINK2_CERT.NRD und WEBLINK2_KEY.NRD (Zertifikats-Tab bzw. POST /api/certificates/generate) - und genau diese Dateien installiert das Deploy-Skript unten auf dem Drucker.

zplClouds Weblink-Relay (z. B. weblink.zplcloud.com bzw. live.zplcloud.com) ist ein solcher Endpunkt: Deine Drucker verbinden sich ausgehend dorthin, und über die zplCloud-Plattform („Weblink“-Tab, Remote-Printers, CLI) kannst du sie danach wie lokale Geräte ansprechen - ZPL senden, Profile anwenden und den Verbindungsstatus live beobachten. Das hier dokumentierte Skript ist der letzte Schritt dieser Einrichtung: Es bringt die Zertifikate auf den Drucker und setzt die Weblink-Slot- Konfiguration (URL, NTP, Uhrzeit), damit die Verbindung starten kann.

Was macht dieses Skript und wofür ist es gut?

Damit ein Zebra-Drucker sich sicher per TLS mit deinem Weblink-Relay verbinden kann, braucht er drei Zertifikatsdateien (WEBLINK2_CA.NRD, WEBLINK2_CERT.NRD, WEBLINK2_KEY.NRD). Diese Dateien werden in zplCloud je Domain + Drucker verwaltet. Das Deploy-Skript holt sie per API-Key vom Backend und installiert sie direkt auf dem Drucker - komplett selbstenthalten, ohne zusätzliche Werkzeuge:

  • NRD-Dateien herunterladen (API-Key-geschützt) für Domain + Drucker.
  • Alte Dateien auf dem Drucker löschen (SGD file.delete).
  • Hochladen per ~DYE über TCP 9100 (Standard-Zebra-Upload).
  • Weblink-Slot + Uhr konfigurieren - weblink.ip.conn2.location, NTP-Server, Zeitzone, RTC-Datum/-Uhrzeit.
  • Drucker zurücksetzen (device.reset), damit die neue Konfiguration aktiv wird.

Voraussetzungen

  • Die Zertifikate für den Drucker müssen in zplCloud erzeugt worden sein (Zertifikats-Tab oder POST /api/certificates/generate).
  • Ein API-Key mit Zugriff auf die Domain.
  • Der Drucker muss per TCP 9100 erreichbar sein (IP oder Hostname).

Parameter

ParameterPflichtBedeutung
hostnamejaDruckername - bestimmt die NRD-Ablage (Domain-Ordner) und ist das Standard-TCP-Ziel.
apikeyjaAPI-Key (db.apikeys); autorisiert den Download der NRD-Dateien. Wird serverseitig validiert.
ipneinTCP-Ziel (IPv4 oder Hostname), das die Verbindung tatsächlich aufbaut. Default: hostname.

Windows - PowerShell (weblink-deploy.ps1)

Das Skript wird serverseitig für deinen Drucker generiert. Führe es direkt aus (PowerShell 5.1+):

powershell -c "irm https://zplcloud.com/weblink-deploy.ps1?hostname=printer01&apikey=sk_zplcloud_XXXX | iex"
# mit explizitem TCP-Ziel:
powershell -c "irm https://zplcloud.com/weblink-deploy.ps1?hostname=printer01&apikey=sk_zplcloud_XXXX&ip=10.0.0.5 | iex"

Der Befehl ist idempotent: alte Dateien werden vor dem Upload gelöscht, am Ende wird der Drucker zurückgesetzt.

macOS / Linux / Raspberry Pi - bash (weblink-deploy.sh)

Die gleiche Logik als bash-Skript (braucht nur bash + curl oder wget):

curl -fsSL "https://zplcloud.com/weblink-deploy.sh?hostname=printer01&apikey=sk_zplcloud_XXXX" | bash
# mit explizitem TCP-Ziel:
curl -fsSL "https://zplcloud.com/weblink-deploy.sh?hostname=printer01&apikey=sk_zplcloud_XXXX&ip=10.0.0.5" | bash

Unterstützt x64 und arm64 (auch Raspberry Pi / Pi OS), nutzt /dev/tcp für die TCP-Verbindung und mktemp für die temporären Dateien.

Was passiert im Detail (beide Varianten)

1) NRD-Dateien laden
   GET {api}/api/certificates/deploy/domain/{domain}/printer/{printer}/WEBLINK2_CA.NRD?apikey=...
   GET .../WEBLINK2_CERT.NRD?apikey=...
   GET .../WEBLINK2_KEY.NRD?apikey=...

2) Alte Dateien löschen
   ! U1 do "file.delete" "E:WEBLINK2_CA.NRD"   (und CERT/KEY)

3) Upload (~DYE, TCP 9100)
   ~DYE:WEBLINK2_CA.NRD,B,NRD,<len>,,  + Datei-Bytes
   (gleiches für CERT und KEY)

4) Weblink-Slot + Uhr konfigurieren
   setvar weblink.ip.conn2.location  {weblink-URL}
   setvar ip.ntp.enable on
   setvar ip.ntp.server  ptbtime1.ptb.de
   setvar rtc.time_zone  CET-1CEST,M3.5.0/2,M10.5.0/3
   setvar rtc.date / rtc.time  (von der ausführenden Maschine)

5) Drucker zurücksetzen (Konfiguration aktivieren)
   ! U1 do "device.reset" ""

Hinweise

  • Der API-Key steht im URL-Parameter - der Download ist dadurch autorisiert, das Skript selbst ist ohne Key nicht abrufbar (serverseitige Validierung).
  • Fehlermeldungen erscheinen im Skript-Output („ERROR …“); prüfe bei Problemen zuerst die TCP-Erreichbarkeit (Port 9100) und ob die Zertifikate erzeugt wurden.
  • Beide Skripte schreiben ihr Fortschritts-Log auf die Konsole - so siehst du jede Datei und jede SGD-Antwort.