English

Template erstellen

Zweck

Ein Template anlegen. Ein Template ist ein vollständiger, in sich geschlossener Satz von Einstellungen: keine Ebenen, keine Vererbung, keine Basisschicht. Alles, was ein Gerät bekommt, steht in dem einen Template, das ihm zugewiesen ist.

Voraussetzungen

• Sie sind angemeldet, siehe Anmelden.
• Die Rolle Org Admin oder Editor.
• Ihre Zielplattform:
  • Pallax: Ihre Pallax-Workspace-ID und der Gateway-Typ (lorawan oder mioty). Fragen Sie den Support, wenn Sie beides nicht haben. Sie tragen beides am Gerät ein, nicht im Template, siehe Pallax-Ziel.
  • Generic: vom Betreiber Ihres Brokers Hostnamen und Port des Brokers und die drei Dateien des Zertifikats: das Client-Zertifikat, seinen privaten Schlüssel (ohne Passwortschutz) und die CA-Kette.

Schritte

1. Öffnen Sie Config templates. Gibt es noch kein Template, klicken Sie auf Create template, sonst oben rechts auf New template.

   

2. Geben Sie im Dialog New template unter NAME einen Namen ein, der in Ihrer Organisation eindeutig ist. Unter diesem Namen erscheint das Template auf allen anderen Seiten.

3. Klicken Sie unter TARGET PLATFORM auf Generic oder Pallax.
4. Freiwillig: Tragen Sie unter KEYS Einstellungen ein. Klicken Sie auf Add key, geben Sie den Namen des Eintrags und seinen Wert als JSON ein (Text in Anführungszeichen: "info"; Zahlen ohne: 300). Oder klicken Sie auf Paste JSON instead, fügen Sie ein JSON-Objekt mit allen Einträgen ein und klicken Sie auf Apply to rows. Einträge können Sie auch später einzeln im Template-Editor ergänzen (siehe Template bearbeiten).
   • Bei Pallax fügen Sie keinen Eintrag _target hinzu: Pallax-Workspace und Gateway-Typ gehören zum jeweiligen Gerät und werden dort gesetzt, siehe Pallax-Ziel. Die Konsole speichert kein Pallax-Template, das _target enthält.

5. Klicken Sie auf Create.

   

6. Nur bei Generic: Tragen Sie den Broker ein und laden Sie das Zertifikat hoch, wie in den nächsten beiden Abschnitten beschrieben.

Broker eintragen (nur Generic)

1. Klicken Sie in der Liste Templates auf Ihr neues Template. Unter seinen Einträgen sehen Sie zwei Karten: Broker und Broker credential. Auf der Zertifikatskarte steht No credential yet (1) (noch kein Zertifikat).

   

2. Geben Sie in der Karte Broker unter Host (1) den Hostnamen ein, zum Beispiel broker.example.com. Nur den Namen: kein mqtts:// davor und kein :8883 dahinter.

3. Prüfen Sie Port (2). Vorbelegt ist 8883, der übliche Port für MQTT über TLS. Ändern Sie ihn nur, wenn der Betreiber Ihres Brokers Ihnen einen anderen genannt hat.
4. Freiwillig: Geben Sie unter Topic prefix (optional) (3) ein Topic-Präfix ein, zum Beispiel customer/site-a, wenn der Betreiber Ihres Brokers Ihnen eines genannt hat. Sonst lassen Sie das Feld leer.
5. Klicken Sie auf Save broker (4). Neben der Schaltfläche steht „Saved as version vN.“ (als Version vN gespeichert).

Zertifikat hochladen (nur Generic)

1. Klicken Sie in der Karte Broker credential auf Upload credential. Der Dialog „Upload credential — “ mit dem Namen Ihres Templates öffnet sich, bei „Step 1 of 3“ (Schritt 1 von 3).
2. Der Dialog nennt die drei Dateien, die Sie brauchen. Klicken Sie auf I have the files.
3. Füllen Sie die drei Felder: Client certificate (1), Private key — never displayed again (2) und CA chain — issuing CA first, root CA last (3). Klicken Sie bei jedem Feld auf Choose file… und wählen Sie die Datei (.pem, .crt, .cer, .key oder .txt), oder fügen Sie den Text der Datei in das Feld ein. Ein als Datei gewählter Schlüssel zeigt nur seinen Dateinamen und „Loaded“ (geladen); Clear entfernt ihn.
4. Lesen Sie jeden Hinweis, der unter einem Feld erscheint, bevor Sie weitermachen (siehe Häufige Fehler).
5. Klicken Sie auf Upload and check (4). Die Schaltfläche bleibt grau, bis alle drei Felder gefüllt sind.

Ergebnis

Der Dialog schließt sich, und das neue Template steht in der Liste Templates, mit seiner Zielplattform und 0 devices. Es ist mit nichts verbunden, bis Sie es einem Gerät zuweisen, siehe Template zuweisen.

Die Markierung unter dem Namen zeigt den Stand des Zertifikats:

Markierung	Bedeutung
No credential — devices will fail check-in	Ein Generic-Template, das noch kein Zertifikat hat. Das Zuweisen an ein Gerät wird abgelehnt, bis Sie das Zertifikat hochgeladen haben (Punkt 6 oben).
No credential on record	Ein Pallax-Template. Es braucht kein eigenes Zertifikat.
Certificate · N d left	Das Template hat ein Zertifikat, das in N Tagen abläuft. Ein Streifen oben auf der Seite bietet Replace certificate an (siehe unten).

Bei Generic nach Upload and check „Step 3 of 3“ mit vier Prüfungen (1): Files are readable (Dateien lesbar), Key matches certificate (Schlüssel passt zum Zertifikat), Chain complete to a root CA (Kette vollständig bis zur Root-CA) und Not expired (nicht abgelaufen). Jede zeigt Pass (bestanden) oder Fail (nicht bestanden).

Sind alle vier bestanden, zeigt der Dialog Fingerprint (SHA-256), Subject, Issuer und Valid until des Zertifikats (2) und: „Stored as template version vN. The private key is stored securely and cannot be shown again — only replaced. Devices pick up the change at their next check-in.“ (Als Template-Version vN gespeichert. Der private Schlüssel ist sicher gespeichert und kann nie wieder angezeigt, nur ersetzt werden. Die Geräte übernehmen die Änderung bei ihrem nächsten Check-in.) Klicken Sie auf Done. Erscheint ein roter Kasten „Check this credential“ (3), ist das Zertifikat trotzdem gespeichert; lesen Sie dann Häufige Fehler.

Ist eine Prüfung nicht bestanden, steht im Dialog „Not uploaded“ und „Nothing was stored.“ (nicht hochgeladen, nichts gespeichert). Die nicht bestandene Prüfung ist markiert (1), und ein Satz sagt, was nicht stimmt (2). Suchen Sie diesen Satz unter Häufige Fehler, korrigieren Sie die Datei und klicken Sie auf Fix and upload again.

Nach Done zeigt die Karte Broker credential die Angaben zum Zertifikat (1) und nur eine Aktion, Replace (2). Den privaten Schlüssel zeigt sie nie. In der Liste Templates ist „No credential — devices will fail check-in“ verschwunden. Das Template kann jetzt zugewiesen werden, siehe Template zuweisen.

Das Zertifikat ersetzen

Das Zertifikat eines Generic-Templates läuft ab, meist nach einem Jahr. Mit einem abgelaufenen Zertifikat können Gateways mit diesem Template nicht eingerichtet werden. Besorgen Sie vorher beim Betreiber Ihres Brokers ein neues Zertifikat und klicken Sie in der Karte Broker credential des Templates auf Replace (oder auf dem Streifen oben unter Config templates auf Replace certificate; er erscheint, wenn das Zertifikat bald abläuft). Der Dialog hat dieselben drei Schritte wie beim ersten Hochladen: die Dateien, die drei Felder Client certificate, Private key — never displayed again und CA chain — issuing CA first, root CA last, und die vier Prüfungen. Das bisherige Zertifikat bleibt in Gebrauch, bis das neue alle Prüfungen bestanden hat. Den privaten Schlüssel zeigt die Plattform nach dem Hochladen nie wieder an. Sobald das neue Zertifikat hinterlegt ist, wird der private Schlüssel des alten aus dem Speicher gelöscht; von ihm bleibt nichts zurück.

Vor dem Ablauf zeigt Config templates die Warnung „The certificate on … expires in N days. Upload a replacement before then, or N devices can no longer receive their configuration.“

Nach dem Hochladen prüft die Plattform, ob das Zertifikat zum Broker dieses Templates passt. Erscheint ein roter Kasten „Check this credential“, siehe Häufige Fehler.

Häufige Fehler

Beim Anlegen des Templates

Was Sie sehen	Was es bedeutet	Was Sie tun
NAME_TAKEN (409)	In Ihrer Organisation gibt es schon ein Template mit diesem Namen.	Wählen Sie einen anderen Namen, oder bearbeiten Sie das vorhandene, siehe Template bearbeiten.
Create bleibt grau	Der Name ist leer, oder ein Eintrag unter KEYS hat keinen Namen oder einen ungültigen Wert.	Geben Sie einen Namen ein. Prüfen Sie die Einträge: Text braucht Anführungszeichen, zum Beispiel "info".
„Every key needs a unique name and a valid JSON value.“	Ein Wert ist kein gültiges JSON (Text braucht Anführungszeichen), oder zwei Einträge haben denselben Namen.	Korrigieren Sie den Wert. Fügen Sie einem Pallax-Template keinen Eintrag _target hinzu: Das Ziel wird am Gerät gesetzt.
„Must be valid JSON.“ / „Must be a JSON object, e.g. {}.“ nach Apply to rows	Der eingefügte Text ist nicht ein einzelnes JSON-Objekt in geschweiften Klammern.	Fügen Sie ein einzelnes JSON-Objekt ein, zum Beispiel {"log_level": "info"}.
Weder Create template noch New template ist da	Ihre Rolle ist Viewer.	Bitten Sie einen Org Admin um die Rolle Editor.

Beim Eintragen des Brokers

Neben Save broker:

Was Sie sehen	Was es bedeutet	Was Sie tun
„Enter the broker's host name, for example broker.example.com.“	Host ist leer.	Geben Sie den Hostnamen ein, den Ihnen der Betreiber Ihres Brokers genannt hat.
„Enter the host name only, for example broker.example.com. The port has its own box.“	Unter Host steht mehr als der Name, zum Beispiel mqtts:// davor oder :8883 dahinter.	Löschen Sie alles außer dem Hostnamen. Den Port tragen Sie unter Port ein.
„The host name can contain only letters, digits, dots and hyphens.“	Unter Host steht ein anderes Zeichen, zum Beispiel ein Leerzeichen oder ein Unterstrich.	Prüfen Sie den Hostnamen auf Tippfehler und entfernen Sie das Zeichen.
„The port must be a number from 1 to 65535. MQTT over TLS usually uses 8883.“	Port ist leer oder keine Zahl in diesem Bereich.	Geben Sie den Port ein, den Ihnen der Betreiber Ihres Brokers genannt hat, meist 8883.
„The topic prefix cannot contain # or +.“	# und + sind Platzhalter und in einem Präfix nicht erlaubt.	Entfernen Sie sie, zum Beispiel customer/site-a. Oder lassen Sie das Feld leer.

Beim Hochladen des Zertifikats

„Fragen“ heißt unten: den Betreiber Ihres Brokers fragen.

Was Sie sehen	Ursache und Abhilfe
„Set the broker first, so the upload can be checked against it.“	Noch kein Broker. Tragen Sie zuerst den Broker ein und klicken Sie dann auf Upload credential.
Upload and check bleibt grau	Ein Feld ist leer. Füllen Sie alle drei.
„That looks like a private key, not a certificate.“	Felder vertauscht. Eine Datei je Feld: Zertifikat, Schlüssel, Kette.
„More than one certificate here — this field is the leaf certificate only.“	Die Datei enthält auch CA-Zertifikate. Lassen Sie unter Client certificate nur das erste; fügen Sie die übrigen ins Feld für die CA-Kette ein.
„Only one certificate in the chain. […]“	Nur ein Hinweis; Sie können hochladen. Bei einer Zwischen-CA diese zuerst einfügen, die Root-CA zuletzt. Hat eine Root-CA direkt signiert, machen Sie weiter.
Files are readable: Fail, „The certificate box / key box / CA chain box does not hold a readable …“	Falscher Inhalt oder falsches Format. Wählen Sie die Datei erneut. Klappt es wieder nicht, fragen Sie nach dem Zertifikat als Text, der mit -----BEGIN CERTIFICATE----- beginnt (Schlüssel: -----BEGIN, mit PRIVATE KEY).
Files are readable: Fail, „The private key is password-protected.“	Nicht verwendbar. Exportieren Sie ihn ohne Passwort und laden Sie erneut hoch.
Files are readable: Fail, „The certificate uses a key type that is not supported.“	Nur RSA und EC funktionieren. Fragen Sie nach einem solchen Zertifikat.
Key matches certificate: Fail, „The private key does not belong to this certificate.“	Kein Paar, zum Beispiel ein alter Schlüssel zu einem neuen Zertifikat. Wählen Sie den passenden Schlüssel.
Chain complete to a root CA: Fail, „The CA chain does not start with the CA that signed your certificate.“	Setzen Sie die ausstellende CA an den Anfang oder fragen Sie danach.
Chain complete to a root CA: Fail, „The CA chain is in the wrong order.“	Ausstellende CA zuerst, Root-CA zuletzt.
Chain complete to a root CA: Fail, „The CA chain is incomplete: the root CA is missing.“	Fügen Sie das Zertifikat der Root-CA am Ende an.
Not expired: Fail, „The certificate has already expired.“ / „A certificate in the CA chain has expired.“	Fragen Sie nach einem neuen Zertifikat oder einer aktuellen CA-Kette.
Roter Kasten „Check this credential“, „It is signed by a test CA. […]“	Ein Testzertifikat: gespeichert, aber echte Broker lehnen es ab. Besorgen Sie das echte und klicken Sie auf Replace.
Roter Kasten „Check this credential“, „The certificate names a different host than this template's broker. […]“	Trotzdem gespeichert. Prüfen Sie Host in der Karte Broker auf Tippfehler. Stimmt er, fragen Sie nach dem Zertifikat für diesen Broker und klicken Sie auf Replace.
„No credential — devices will fail check-in“ nach angenommenem Hochladen	Alter Seitenstand. Laden Sie die Seite neu.