Domain und Zertifikate

Ohne oder mit Domain#

Ohne Domain ist die Plattform nur direkt auf dem Server erreichbar, über ihre lokalen Ports, zum Beispiel den Chat unter http://localhost:3000. Es gibt keine Verschlüsselung und keinen Firmen-Login. Für einen ersten Test genügt das.

Mit Domain bekommt jeder Bereich eine eigene Adresse unter dieser Domain. Wir empfehlen eine eigene Subdomain für swaiz, zum Beispiel ki.firma.ch. Darunter entstehen Adressen wie:

• auth.ki.firma.ch für die Anmeldung
• chat.ki.firma.ch für den Chat
• protocol.ki.firma.ch für eine Erweiterung

Für die Domain selbst, also ki.firma.ch ohne Subdomain, richtet die Plattform keine Adresse ein.

Domain festlegen#

Die Installation fragt nach der Domain. Ein leeres Feld bedeutet: keine Domain. Ohne Terminal wird nichts gefragt, und die Plattform läuft nur über die lokalen Ports.

Für eine automatisierte Installation gibst du die Domain direkt mit:

sudo aictl install --base-domain ki.firma.ch --tls-mode auto --dns-provider cloudflare

Eine Domain nachträglich hinzufügen geht genauso: Führe install mit --base-domain erneut aus. Deine übrigen Einstellungen bleiben erhalten.

Gut zu wissen#

• Gib die Domain ohne https://, ohne Port und ohne Pfad an. Die interaktive Abfrage prüft das, die Option --base-domain nicht.
• --base-domain "" entfernt eine Domain nicht. Dazu musst du proxy.baseDomain in /etc/aictl/spec.yaml leeren und sudo aictl apply ausführen.
• Eine erneute Installation fragt nicht nochmals nach Domain und Zertifikat, sobald diese einmal eingerichtet sind. Hattest du keine Domain gewählt, fragt eine interaktive Neuinstallation erneut.

DNS einrichten#

Bei deinem DNS-Anbieter richtest du einen Eintrag ein, der alle Adressen unter deiner Domain auf den Server zeigt:

Ein solcher Platzhalter-Eintrag deckt nur eine Ebene ab. Bringt eine Erweiterung eine mehrstufige Adresse mit, zum Beispiel api.kb.ki.firma.ch, braucht diese einen eigenen Eintrag.

Automatische DNS-Einträge#

Am Ende von install, update, apply und restore sowie beim Einrichten einer Erweiterung prüft aictl, ob alle veröffentlichten Adressen auflösen. Fehlende Einträge legt es nur dann selbst an, wenn alle drei Bedingungen erfüllt sind:

• die Plattform ist öffentlich (nicht mit --internal installiert),
• der DNS-Anbieter ist cloudflare,
• der Schlüssel CF_DNS_API_TOKEN ist gespeichert.

Dann fragt aictl, welche Einträge es anlegen soll. Alle sind vorausgewählt, Esc legt keinen an. Ohne Terminal werden alle fehlenden Einträge automatisch angelegt.

In allen anderen Fällen gibt aictl die fehlenden Einträge aus, damit du sie selbst anlegen kannst.

Gut zu wissen#

• Als Ziel nimmt aictl die Adresse, auf die die Chat-Adresse zeigt. Löst diese noch nicht auf, nimmt es die öffentliche IP-Adresse des Servers. Steht der Server hinter einem Router mit privater Adresse, gibt es den Eintrag ohne Ziel aus. Trage das Ziel dann selbst ein.
• Ein vorhandener Eintrag mit einem anderen Wert wird nie überschrieben: «exists with a different value — left untouched, fix it by hand».
• Einträge für die Bereiche der Plattform werden nie gelöscht, auch nicht, wenn du einen Bereich verbirgst. Einträge für eine Erweiterung entfernt extension remove, solange sie noch unverändert sind.
• Kann der Server gerade keine DNS-Abfragen machen, überspringt aictl die Prüfung mit einem Hinweis.

Zertifikate: zwei Wege#

Mit einer Domain ist jede Verbindung verschlüsselt. Für das Zertifikat gibt es zwei Modi:

Die interaktive Installation bietet genau diese beiden Wege an. Eine Domain ohne Verschlüsselung ist nur über Optionen möglich, siehe Ohne Verschlüsselung.

Automatische Zertifikate#

Im Modus auto holt die Plattform ein Zertifikat für *.ki.firma.ch und ki.firma.ch, das alle einstufigen Adressen abdeckt. Mehrstufige Adressen von Erweiterungen bekommen je ein eigenes Zertifikat. Die Plattform erneuert alle Zertifikate selbstständig.

Die Bestätigung, dass dir die Domain gehört, läuft über deinen DNS-Anbieter. Deshalb:

• braucht die Domain eine öffentliche DNS-Zone bei einem unterstützten Anbieter,
• braucht die Plattform einen API-Schlüssel dieses Anbieters,
• braucht der Server ausgehenden Internetzugang zu Let's Encrypt und zum DNS-Anbieter,
• sind keine eingehenden Ports nötig. Der Modus funktioniert also auch für Plattformen, die nur im internen Netz erreichbar sind.

Bei der interaktiven Installation#

1. Du wählst deinen DNS-Anbieter aus einer durchsuchbaren Liste. Tippe einfach den Namen. Die erste Esc-Taste leert die Suche, die zweite bricht ab.
2. Du gibst optional eine E-Mail-Adresse für Let's Encrypt an. Leer lassen ist erlaubt.
3. Die Installation fragt verdeckt nach dem Zugangsschlüssel und speichert ihn sofort. Enter überspringt die Frage.

Für diese Anbieter kennt aictl die Namen der Schlüssel:

Bei allen anderen Anbietern zeigt die Installation einen Hinweis auf die Dokumentation des Anbieters. Speichere die nötigen Schlüssel dann selbst mit secret set.

Bei Cloudflare braucht der Schlüssel die Rechte «Zone:Read» und «DNS:Edit» für deine Domain. Am einfachsten verwendest du die Vorlage «Edit zone DNS».

Bei einer automatisierten Installation#

sudo aictl install --license LIC-XXXX-XXXX-XXXX-XXXX \
  --base-domain ki.firma.ch --tls-mode auto --dns-provider cloudflare --acme-email [email protected]
printf %s "$TOKEN" | sudo aictl secret set CF_DNS_API_TOKEN --stdin
sudo aictl apply

Den Schlüssel kannst du auch schon vor der Installation speichern. Dann ist er beim ersten Start da, und das apply am Ende entfällt.

Gut zu wissen#

• --dns-provider wird gegen die Liste der Anbieter geprüft. Ein Tippfehler bricht die Installation mit einem Hinweis auf die Liste ab.
• sudo aictl doctor prüft, ob die nötigen Schlüssel gespeichert sind. Bei Cloudflare prüft es zusätzlich, ob der Schlüssel die Zone deiner Domain verwalten darf.
• Zum Testen kannst du in /etc/aictl/spec.yaml unter proxy.tls.caServer die Testumgebung von Let's Encrypt eintragen, zum Beispiel https://acme-staging-v02.api.letsencrypt.org/directory. Dafür gibt es keine Option auf der Kommandozeile.
• Änderst du nur die Testumgebung, die E-Mail-Adresse oder den Anbieter, übernimmt das Gateway die Änderung möglicherweise erst nach einem Neustart der Plattform: sudo aictl restart.
• Automatische Zertifikate sind im Backup enthalten.

Eigenes Firmenzertifikat#

Im Modus provided liefert die Plattform dein eigenes Zertifikat aus. Hinterlegt wird es mit:

sudo aictl proxy set-cert --cert fullchain.pem --key privkey.pem
sudo aictl apply

Wir empfehlen ein Platzhalter-Zertifikat für *.ki.firma.ch, damit jede Adresse abgedeckt ist, auch die von später installierten Erweiterungen. Mehrstufige Adressen von Erweiterungen müssen im Zertifikat zusätzlich als eigener Name stehen. aictl prüft nicht, ob dein Zertifikat alle veröffentlichten Adressen abdeckt.

Unterstützte Formate#

Eine PFX-Datei erkennt aictl an der Endung .pfx oder .p12 oder daran, dass die Datei keinen PEM-Block enthält. Der Schlüssel muss zu einem Zertifikat in der Datei passen. Für verschlüsselte Schlüssel und PFX-Dateien muss auf dem Server das Programm openssl installiert sein.

Zertifikat aus einer eigenen Zertifizierungsstelle#

Nicht nur die Browser prüfen dein Zertifikat. Der Chat, die KI-Zentrale und die Erweiterungen rufen beim Anmelden den Firmen-Login über seine öffentliche Adresse auf und prüfen dabei ebenfalls das Zertifikat. Stammt es aus einer eigenen Zertifizierungsstelle, zum Beispiel aus den Active Directory Certificate Services, brauchen sie dafür deren Stammzertifikat.

• Enthält die PFX-Datei den ganzen Zertifizierungspfad, übernimmt aictl das Stammzertifikat daraus. Beim Export unter Windows heisst die Option «Wenn möglich, alle Zertifikate im Zertifizierungspfad einbeziehen».
• Sonst gibst du das Stammzertifikat mit --ca an, als PEM, DER (.cer) oder PKCS#7 (.p7b). Zwischenzertifikate in dieser Datei hängt aictl an die Kette an, die der Server ausliefert.

sudo aictl proxy set-cert --cert firma.pfx --ca firma-root.cer --password-stdin < pw.txt
sudo aictl apply

set-cert lehnt ein Zertifikat ab, das sich nicht bis zu einem vertrauenswürdigen Stammzertifikat prüfen lässt, und nennt die fehlende Zertifizierungsstelle. Nach dem Import zeigt es, welchen eigenen Stammzertifikaten die Dienste vertrauen. Das Stammzertifikat bleibt hinterlegt: Eine Erneuerung aus derselben Zertifizierungsstelle braucht --ca nicht noch einmal.

Die Dienste vertrauen danach denselben Zertifizierungsstellen wie der Server selbst und zusätzlich deinem Stammzertifikat. Ist es auf dem Server schon installiert, braucht es kein --ca. Neue Zertifizierungsstellen aus Updates des Betriebssystems übernimmt das nächste apply.

Passwort übergeben#

Gib genau eine dieser Quellen an:

Ein Zeilenumbruch am Ende wird entfernt. Beispiele:

printf %s "$PW" | sudo aictl proxy set-cert --cert fullchain.pem --key privkey.pem --password-stdin
sudo aictl proxy set-cert --cert bundle.pfx --password-stdin < pw.txt

Bei der interaktiven Installation#

Wählst du «Provide my own cert», fragt die Installation nach dem Pfad zum Zertifikat, zum Schlüssel (leer bei PFX) und verdeckt nach dem Passwort (leer, falls keines). Fehlt das Stammzertifikat einer eigenen Zertifizierungsstelle, fragt sie zusätzlich nach dessen Pfad. Schlägt der Import fehl, kannst du es erneut versuchen.

Bei einer automatisierten Installation#

Führe proxy set-cert vor der Installation aus. Sonst bricht die Installation ab mit: «proxy.tls.mode=provided but no certificate imported — run 'sudo aictl proxy set-cert --cert --key ' first».

Häufige Fehlermeldungen#

Nach erfolgreichem Import zeigt aictl den Inhaber, das Ablaufdatum und alle Namen im Zertifikat.

Ablauf und Erneuerung#

Ein eigenes Zertifikat erneuert sich nicht selbst. aictl status warnt 30 Tage vor dem Ablauf und meldet einen Fehler, sobald es abgelaufen ist. Erneuern heisst: neues Zertifikat mit proxy set-cert hinterlegen und sudo aictl apply ausführen.

Das eigene Zertifikat ist samt Schlüssel und Stammzertifikat im Backup und wird beim Restore wieder eingespielt. Bei einem älteren Backup ohne Zertifikat führst du proxy set-cert vor dem Restore aus.

Modus wechseln#

Den Modus wechselst du in /etc/aictl/spec.yaml unter proxy.tls.mode (auto oder provided) und übernimmst ihn mit sudo aictl apply. Für provided muss vorher ein Zertifikat hinterlegt sein, für auto ein DNS-Anbieter unter proxy.tls.dnsProvider.

Ohne Verschlüsselung#

Eine Domain ohne Zertifikat ist nur über Optionen möglich: --base-domain ohne --tls-mode und ohne --dns-provider. Dann laufen alle Adressen, auch der Firmen-Login, unverschlüsselt über http://. Wir raten davon ab.

Subdomains festlegen#

Welche Bereiche unter welcher Adresse erreichbar sind, bestimmst du mit:

sudo aictl proxy hostname
sudo aictl apply

Der Befehl braucht eine Domain und ein Terminal. Du siehst oben die Bereiche der Plattform und darunter die Erweiterungen. Jede Zeile zeigt, ob der Bereich veröffentlicht ist und unter welcher Adresse.

Für Skripte gibt es --set, beliebig oft wiederholbar:

sudo aictl proxy hostname --set chat=ki
sudo aictl proxy hostname --set protocol/app=notizen

<schlüssel>=- oder <schlüssel>= verbirgt einen Bereich.

Schlüssel und Standardwerte#

Für --set brauchst du den Schlüssel eines Bereichs. Die interaktive Auswahl zeigt ihn in jeder Zeile an. Für den Firmen-Login ist es auth, für den Chat chat und für Erweiterungen <erweiterung>/<dienst>.

Eine Subdomain ist ein einzelnes Wort aus Kleinbuchstaben, Ziffern und Bindestrichen, höchstens 63 Zeichen lang und weder mit einem Bindestrich beginnend noch endend. Bereiche einer Erweiterung dürfen auch mehrere solche Wörter mit Punkt verbinden, etwa api.notizen. Eine solche Adresse braucht einen eigenen DNS-Eintrag und ist nicht durch das Platzhalter-Zertifikat abgedeckt. Zwei veröffentlichte Bereiche dürfen nicht dieselbe Subdomain haben.

Nach dem Speichern zeigt der Befehl die neuen Adressen. Wirksam werden sie erst mit sudo aictl apply. Dabei bietet aictl auch an, fehlende DNS-Einträge anzulegen.

Warnungen beim Speichern#

• Benutzerverwaltung verborgen: Nach dem nächsten apply ist der Firmen-Login aus. Der Chat fällt auf lokale Konten zurück, und Automationen, Wissensspeicher und Websuche sind nicht mehr geschützt, solange sie veröffentlicht bleiben.
• KI-Zentrale veröffentlicht, aber dein Plan enthält keinen Zugang zur Programmschnittstelle: Die Adresse zeigt dann nur die Administrationsoberfläche, siehe unten.

Was «verbergen» bedeutet#

Ein verborgener Bereich bekommt keine öffentliche Adresse. Er läuft aber weiter:

• Er bleibt direkt auf dem Server über seinen lokalen Port erreichbar.
• Ein verborgener Dienst einer Erweiterung bleibt für die anderen Dienste derselben Erweiterung erreichbar.
• Ein verborgener Dienst einer Erweiterung bekommt keinen Firmen-Login, weil es keine Adresse gibt, zu der die Anmeldung zurückkehren könnte.
• DNS-Einträge, die aictl selbst angelegt hat, entfernt das nächste apply oder update wieder, sofern sich ihr Wert nicht geändert hat. Von Hand angelegte Einträge bleiben bestehen.

Achtung: Verbirgst du die Benutzerverwaltung (auth), schaltest du den Firmen-Login überall ab. Bleiben Automationen, Wissensspeicher oder Websuche veröffentlicht, sind sie danach ohne Anmeldung aus dem Netz erreichbar. proxy hostname, Installation, Update und apply warnen in diesem Fall und nennen die betroffenen Bereiche.

Nur im internen Netz#

Soll die Plattform nicht aus dem Internet erreichbar sein, installiere sie mit --internal. Das ändert genau drei Dinge:

1. aictl legt keine DNS-Einträge automatisch an, sondern gibt sie aus, damit du sie auf deinem internen DNS-Server einträgst.
2. Die Warnungen sprechen von «your network» statt «the INTERNET».
3. Die Zusammenfassung zeigt «internal-only» statt «public».

Die Zertifikate betrifft --internal nicht. Beide Modi funktionieren auch intern: auto, solange die Domain eine öffentliche DNS-Zone hat, oder provided mit dem Zertifikat deiner internen Zertifizierungsstelle.

Gut zu wissen#

• --internal allein bedeutet: keine Domain, nur lokale Ports. Sobald eine Option für Domain oder Zertifikat gesetzt ist, entfallen die Fragen. Kombiniere deshalb --internal mit --base-domain und --tls-mode.
• Zurück zur öffentlichen Plattform geht es mit sudo aictl install --external.
• Für den Zugriff von unterwegs empfehlen wir ein VPN.

Programmschnittstelle der KI-Zentrale#

Ob die Programmschnittstelle der KI-Zentrale von aussen nutzbar ist, hängt von deinem Plan ab. Enthält er keinen API-Zugang, zeigt die veröffentlichte Adresse der KI-Zentrale nur die Administrationsoberfläche. Programmaufrufe von aussen erhalten die Antwort 403. Chat, Automationen und Erweiterungen sind davon nicht betroffen, sie erreichen die KI-Zentrale intern.

Was dein Plan enthält, zeigt aictl license info in der Zeile «api». Nach einem Planwechsel übernimmt das Gateway die Änderung mit sudo aictl license renew sofort, sonst bei der nächsten automatischen Bestätigung.

Lokale Ports#

Neben dem Gateway hat jeder Bereich einen lokalen Port auf dem Server:

Die Ports der Bereiche sind standardmässig nur auf dem Server selbst erreichbar (127.0.0.1), zum Beispiel für Wartung über einen SSH-Tunnel. Das Gateway und der Hintergrunddienst lauschen immer auf allen Netzwerkschnittstellen.

Mit --bind-address änderst du, wo die lokalen Ports erreichbar sind:

sudo aictl apply --bind-address 0.0.0.0     # im ganzen Netzwerk
sudo aictl apply --bind-address 127.0.0.1   # nur auf dem Server (Standard)

Achtung: Mit 0.0.0.0 sind Chat, KI-Zentrale, Automationen, Wissensspeicher und Websuche ohne Anmeldung aus dem Netzwerk erreichbar, und der Firmen-Login wird umgangen, weil er nur am Gateway prüft. aictl warnt davor. Verwende das nur auf Testsystemen.

Gut zu wissen#

• Eine einzelne Adresse wie 10.0.0.5 macht die lokalen Ports nur auf dieser Netzwerkschnittstelle erreichbar, zum Beispiel nur im VPN. Die Plattform prüft sich dann selbst über diese Adresse, und die lokalen Adressen in ihren Ausgaben nennen sie.
• Eine Firewall auf dem Server (zum Beispiel ufw) filtert die lokalen Ports der Plattform nicht zuverlässig. Die richtige Stellschraube ist die Bindungsadresse.
• Ports änderst du in /etc/aictl/spec.yaml und übernimmst sie mit sudo aictl apply. Die Namen der Einstellungen stehen in der Entwicklerdokumentation im Kapitel «Stack anpassen». Jeder Port darf nur einmal vorkommen.
• Die Gateway-Ports 80 und 443 verlegst du, wie unter Gateway auf anderen Ports beschrieben.
• Belegt ein anderes Programm einen der Ports, brechen install, update und apply ab und nennen das Programm. Beende es oder verlege den Port.

Gateway auf anderen Ports#

Ist Port 443 auf dem Server schon belegt, legst du das Gateway in /etc/aictl/spec.yaml auf einen anderen Port, zum Beispiel proxy.httpsPort: 8443. Dann kommt es darauf an, wie dein Team die Plattform aufruft:

• Direkt auf dem neuen Port, also https://chat.ki.firma.ch:8443: Setze zusätzlich proxy.publicPort: 8443. Dann tragen alle Adressen, die die Plattform erzeugt, diesen Port, auch der Firmen-Login und die Umleitung von HTTP auf HTTPS.
• Über eine Portweiterleitung, etwa von Port 443 an der Firewall auf 8443 am Server: Die Adressen bleiben ohne Port. Setze proxy.publicPort: 443, um das zu bestätigen.

proxy:
  httpsPort: 8443
  publicPort: 8443

Übernimm die Änderung mit sudo aictl apply. Solange publicPort fehlt, weist aictl status unter Deployment auf den abweichenden Port hin. Ohne Verschlüsselung gilt dasselbe für proxy.httpPort und Port 80.

Sonderfälle#

• Kollision mit einer Erweiterung: Möchte eine Erweiterung eine Subdomain, die schon ein anderer Bereich nutzt, wird sie nicht eingerichtet. Wähle mit proxy hostname --set <erweiterung>/<dienst>=<subdomain> eine andere.
• Gateway-Zertifikat erscheint nicht: Automatische Zertifikate werden kurz nach dem Start ausgestellt. Warte ein paar Minuten und prüfe danach sudo aictl doctor. Hilfe zu weiteren Problemen findest du unter Fehlerbehebung.