Zebra-Weblink-Zertifikate per ~DYE installieren

Zebra Weblink / Cloud Connect

Weblink (neuer Zebra-Name: Cloud Connect) ist der HTTPS/WebSocket-Client in der Link-OS-Firmware der ZT-, ZD- und ZQ-Drucker. Der Drucker verbindet sich ausgehend mit der URL aus einem der beiden Slots (weblink.ip.conn1.location / weblink.ip.conn2.location) und hält die Verbindung offen. Druckjobs, SGD-Befehle und Konfiguration laufen darüber; ein eingehender Port ist nicht nötig.

Die Relay-Endpunkte von zplCloud sind weblink.zplcloud.com (Produktion) und weblink.test.zplcloud.com (Test-Stage). Für TLS braucht der Drucker drei Dateien je Domain + Drucker, erzeugt in der Plattform (Tab Zertifikate) oder per POST /api/certificates/generate: WEBLINK2_CA.NRD, WEBLINK2_CERT.NRD, WEBLINK2_KEY.NRD. Das Deploy-Skript installiert genau diese Dateien und setzt Slot 2.

Was das Skript macht

Lädt die drei NRD-Dateien (API-Key-geschützt) für Domain + Drucker.
Löscht vorhandene Dateien auf dem Drucker (SGD file.delete).
Lädt sie per ~DYE über TCP 9100 hoch.
Setzt weblink.ip.conn2.location, NTP-Server, Zeitzone und RTC-Datum/-Zeit.
Startet den Drucker neu (device.reset), damit die Konfiguration aktiv wird.

Das ändert die Druckerkonfiguration

Das Skript schreibt Zertifikate in den Druckerspeicher, setzt SGD-Variablen (Weblink-URL, NTP, RTC) und startet den Drucker neu. Nur auf eigenen oder freigegebenen Druckern ausführen, Parameter vorher prüfen, Konfiguration sichern (! U1 getvar "allcv") und mit einem Gerät testen, bevor mehrere ausgerollt werden. Netzwerk- und Firmware-Änderungen erfolgen in eigener Verantwortung (AGB, Abschnitt 14.3).

Voraussetzungen

Zertifikate für den Drucker in zplCloud erzeugt (Tab Zertifikate oder POST /api/certificates/generate).
API-Key mit Zugriff auf die Domain.
Drucker über TCP 9100 erreichbar (IP oder Hostname).

Parameter

Parameter	Pflicht	Bedeutung
hostname	ja	Druckername; bestimmt die NRD-Ablage (Domain-Ordner) und ist das Standard-TCP-Ziel.
apikey	ja	API-Key; autorisiert den NRD-Download. Serverseitig geprüft - ohne gültigen Key wird das Skript nicht ausgeliefert.
ip	nein	TCP-Ziel (IPv4 oder Hostname), falls abweichend von `hostname`. Wird der Hostname im Netz nicht aufgelöst? Kein Problem - einfach mit der IP deployen; `hostname` wählt weiterhin das Zertifikat.

Windows - PowerShell 5.1+

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

macOS / Linux / Raspberry Pi - bash

Benötigt bash und curl oder wget; nutzt /dev/tcp für die TCP-Verbindung und mktemp für temporäre Dateien. x64 und arm64.

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

Beide Skripte sind idempotent (alte Dateien werden vor dem Upload gelöscht) und protokollieren jede Datei und jede SGD-Antwort auf der Konsole; Fehler erscheinen als ERROR …. Alternative mit der CLI: zplcloud weblink setup (siehe CLI), registriert zusätzlich Seriennummer und Besitzer.

Ablauf

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>,,  + Dateibytes
   (gleich für CERT und KEY)

4) Slot + Uhr
   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  (vom ausführenden Rechner)

5) Reset
   ! U1 do "device.reset" ""

Fehlersuche

Keine Verbindung nach dem Reset: TCP-9100-Erreichbarkeit prüfen, ob die Zertifikate für diesen Hostnamen existieren und ob die Druckeruhr gesetzt ist (TLS-Gültigkeit).
Jeder SGD-Befehl muss mit CRLF enden; die Skripte tun das. Beim manuellen Test (z. B. ~HS über einen Raw-Socket) \r\n anhängen, sonst puffert der Drucker den Befehl und antwortet nie.
Verbindungsstatus: Plattform → Tab Weblink (letzter Connect, Keepalive, IP).

Sicherheit und Besitz

mTLS: Das Relay prüft das Client-Zertifikat des Druckers beim TLS-Handshake gegen die Domain-CA (printercerts-Registry). Nicht registrierte oder widerrufene Zertifikate können sich nicht verbinden.
Revoke by Serial: POST /api/certificates/revoke-by-serial/{serial} widerruft das Zertifikat und blockt alle damit provisionierten Drucker (printers.blocked); das Relay lehnt sie sofort ab.
Besitz: Der Drucker gehört dem API-Key, der das Zertifikat erzeugt hat (User / Team / Firma), und erscheint nur dort. zplcloud weblink setup speichert zusätzlich Seriennummer und Besitzer, damit Ersatzgeräte unter demselben Zertifikat nachvollziehbar bleiben.