Upgrade-Hinweise: was sich für bestehende Installationen ändert
Diese Seite führt auf, was ein Upgrade für eine bereits laufende Installation ändert und was dabei zu tun ist. Die Release Notes auf GitHub nennen jede Änderung jedes Releases.
Upgrade auf v0.6.0
Abschnitt betitelt „Upgrade auf v0.6.0“ToolMesh v0.6.0 holt die Credentials aus der .env: Der neue Credential-Store command hält sie nur im Arbeitsspeicher. Das Release steht durchgehend im Zeichen der Sicherheit. Es bindet jedes REST-Backend an die Credentials und Hosts seines Eintrags in backends.yaml, lässt die OAuth-Login-Seite nennen, wohin eine Autorisierung geht, und prüft Tokens gegen die aktuelle Benutzerkonfiguration. Manche dieser Änderungen brauchen in einer bestehenden Installation eine Zeile Konfiguration; vor einem Upgrade von 0.5.x sollte dieser Abschnitt deshalb gelesen werden. Die Release Notes zu v0.6.0 verweisen auf das Security Advisory.
Checkliste
Abschnitt betitelt „Checkliste“- v0.6.0 starten, im Log nach
backend refusedsuchen und die dort genannten Zeilencredentials:oderallowed_hosts:in die Einträge vonbackends.yamlübernehmen. Jeder REST-Eintrag braucht einenname. - Hinter einem Reverse-Proxy, der nicht auf demselben Host läuft,
TOOLMESH_TRUSTED_PROXIESauf die eigene Adresse des Proxys setzen, nicht auf das Netz, das er mit ToolMesh teilt. - Skriptgesteuerte Logins so anpassen, dass sie
confirm_hostsenden, undTOOLMESH_OAUTH_REDIRECT_HOSTSin Betracht ziehen. TOOLMESH_ISSUERauf die öffentliche URL setzen, die Clients verwenden, falls die Variable noch ihren Standardwert hat.- Gate-Policies prüfen, die DADL-Parameter mit Strings wie
"false"vergleichen: Sie sehen jetzt den deklarierten Typ. - Dashboards und Alerts anpassen, die ein Backend mit
_im Namen über das gekürzte Labelbackendauswählen (siehe Volle Backend-Namen in Audit, Telemetrie und Metriken). - Bei Verdacht auf eine missbrauchte Sitzung ihre Tokens widerrufen oder die gespeicherten Tokens löschen und danach das Passwort ändern (siehe Tokens aus der Zeit vor dem Upgrade).
Credentials raus aus der .env, optional
Abschnitt betitelt „Credentials raus aus der .env, optional“Der neue Credential-Store command (CREDENTIAL_STORE=command) führt einen Befehl wie sops -d oder vault kv get aus und hält, was dieser ausgibt, nur im Arbeitsspeicher, also nicht in der .env, nicht in der Umgebung des Containers und nicht im Log. Mit ergosum wird der Schlüssel, der die Credentials öffnet, nur auf der Maschine freigegeben, an die er gebunden ist. Stdio-Backends erhalten dann nur die Variablen, die ihr neuer credential_env-Eintrag nennt. Siehe Credential-Stores.
Der Store ist optional. Ohne CREDENTIAL_STORE=command liest der Embedded Store CREDENTIAL_* wie bisher aus der Umgebung, und es ist nichts zu ändern. Die Bindung an Credentials und Hosts weiter unten gilt mit beiden Stores.
Backends können beim Laden abgewiesen werden
Abschnitt betitelt „Backends können beim Laden abgewiesen werden“Ein REST-Backend liest nur die Credentials im Namensraum seines Eintrags, CREDENTIAL_<ENTRY>_*, wobei ein Credential dem längsten passenden Eintragsnamen gehört, dazu das, was der Eintrag unter env: oder im neuen Feld credentials: aufführt. Credentials, Token-Anfragen und Session-Logins schickt es nur an Host und Port seiner base_url, an andere Hosts derselben registrierbaren Domain auf dem Standardport und an die Hosts im neuen Feld allowed_hosts:; eine https-base_url bleibt bei https. Ein Backend, dessen DADL weiter reicht, wird beim Laden abgewiesen, beim Start wie bei jedem Reload, und die Logzeile backend refused nennt die genauen Zeilen, die zu ergänzen sind. Die übrigen Backends laufen weiter.
DADLs mit Credential-Namen aus anderen Zeichen als Buchstaben, Ziffern und _, mit einem Parameter-Default credential:<name> oder mit einem Platzhalter in Schema, Host oder Port eines absoluten Tool-Pfads werden schon beim Parsen abgewiesen; eine solche DADL muss in der Datei selbst geändert werden. REST-Einträge ohne name werden abgewiesen. Siehe Bindung an Credentials und Hosts.
Die Login-Seite bittet um Bestätigung
Abschnitt betitelt „Die Login-Seite bittet um Bestätigung“Die OAuth-Login-Seite nennt den Client und den Host seiner Redirect-URI und verlangt ein Häkchen zur Bestätigung dieses Hosts. Skriptgesteuerte Logins müssen confirm_host=<redirect host> senden. TOOLMESH_OAUTH_REDIRECT_HOSTS schränkt die Redirect-Hosts auf Wunsch ein, zum Beispiel auf claude.ai,claude.com. Redirect-URIs mit Fragment, ohne Host oder mit einem Host aus Nicht-ASCII-Zeichen werden abgewiesen; Clients, die sich mit einer solchen URI registriert haben, registrieren sich neu. Siehe Die Login-Seite.
Tokens folgen der aktuellen Benutzerkonfiguration
Abschnitt betitelt „Tokens folgen der aktuellen Benutzerkonfiguration“Jeder Refresh und jedes Access-Token wird gegen die Benutzer geprüft, wie sie beim Start geladen wurden. Nach einem Neustart verlieren entfernte Benutzer sofort den Zugang, auch in laufenden Sitzungen, und geänderte Rollen und Pläne gelten für bestehende Tokens; im Single-Password-Modus beendet eine Änderung von TOOLMESH_AUTH_USER die bestehenden Sitzungen. Eine Passwortänderung beendet die Sitzungen des Benutzers. POST /revoke widerruft ein Token-Paar. Ein Refresh-Token wird nach Ablauf seiner sieben Tage abgewiesen; sein Redis-Schlüssel und das Aufwärmen nach einem Neustart verlängern seine Laufzeit nicht mehr. Änderungen an users.yaml wirken weiterhin erst nach einem Neustart.
Tokens, die vor dem Upgrade ausgestellt wurden, werden bei ihrem nächsten Refresh an das Passwort gebunden; eine Passwortänderung nach dem Upgrade beendet sie also noch nicht. Wie sich solche Sitzungen beenden lassen, steht unter Tokens aus der Zeit vor dem Upgrade.
Client-Adresse nur von vertrauenswürdigen Proxys
Abschnitt betitelt „Client-Adresse nur von vertrauenswürdigen Proxys“X-Forwarded-For wird nur von den Adressen in TOOLMESH_TRUSTED_PROXIES beachtet, standardmäßig nur von Loopback. Hinter einem Reverse-Proxy in einem anderen Container, auf einer anderen Maschine oder hinter einem CDN gehört die Adresse des Proxys dort hinein. Bis dahin teilen sich alle Clients die Adresse des Proxys für die Limits von Login, Registrierung und API-Keys, und ToolMesh warnt davor. Ein Proxy-Container bekommt eine feste Adresse im Compose-Netz, und nur diese Adresse wird eingetragen, nicht das Netz: Zum Netz gehört sein Gateway, und mit Docker Desktop, Rootless Docker oder einem Userland-Proxy kommen direkte Verbindungen zum veröffentlichten Port von ToolMesh von diesem Gateway. Steht ein Proxy-Container vor ToolMesh, wird der Port von ToolMesh nur auf 127.0.0.1 veröffentlicht oder gar nicht. Hinter einem vertrauenswürdigen Proxy werden Einträge mit Port (203.0.113.7:51234, [2001:db8::7]:51234) oder in eckigen Klammern als Client-Adresse gelesen; ein Eintrag, der keine Adresse ist (unknown, leer), beendet die Auswertung beim letzten vertrauenswürdigen Proxy. Siehe Client-Adresse und Proxy in einem Container.
Fehlgeschlagene API-Keys werden gedrosselt
Abschnitt betitelt „Fehlgeschlagene API-Keys werden gedrosselt“Nach 50 fehlgeschlagenen Bearer-Credentials von einer Client-Adresse im Zählfenster der Login-Limits (TOOLMESH_APIKEY_MAX_FAILURES_PER_IP) bekommen weitere Credentials von dieser Adresse für den Rest des Fensters 429, auch ein richtiger Key. Siehe Drosselung von API-Keys.
DADL-Argumente werden vor den Policies geprüft
Abschnitt betitelt „DADL-Argumente werden vor den Policies geprüft“Argumente von REST-Tools werden vor dem Gate gegen ihre deklarierten Typen geprüft. "true" oder "false" als String für einen Boolean, Brüche oder nicht numerische Strings für einen Integer und Skalare für Arrays oder Objekte werden mit invalid_input abgewiesen. Numerische Strings für numerische Parameter gehen als Zahlen hinaus (aus "007" wird 7), und Policies sehen die DADL-Defaults eingesetzt. Eine Zahl oder ein Boolean für einen Parameter vom Typ string erreicht die Policies als genau der Text, den die API bekommt, auch im JSON-Body ("42" statt 42); Arrays, Objekte und andere Werte ohne Textform werden für solche Parameter mit invalid_input abgewiesen. Siehe Was Policies sehen.
Wiederholt werden nur die Status aus retry_on
Abschnitt betitelt „Wiederholt werden nur die Status aus retry_on“Ein REST-Aufruf wird nur wiederholt, wenn sein Status in retry_on der DADL steht, wie es die DADL-Spezifikation (§8) verlangt. Bisher wurde jeder 5xx wiederholt. Die meisten veröffentlichten DADLs führen [429, 502, 503, 504] auf, ein 500 wird also nicht mehr wiederholt. Eine DADL, die einen 500 wiederholt haben möchte, nimmt ihn in retry_on auf. Ein Tool mit eigenem errors-Block braucht ein eigenes retry_on, weil dieser Block die Vorgaben des Backends ersetzt.
Volle Backend-Namen in Audit, Telemetrie und Metriken
Abschnitt betitelt „Volle Backend-Namen in Audit, Telemetrie und Metriken“Backends mit Unterstrich im Namen, etwa web_search, erscheinen im Audit-Trail, in der Telemetrie und in den Metriken toolmesh_tool_calls_total und toolmesh_tool_call_duration_seconds mit vollem Namen. Bisher wurde der Name am ersten Unterstrich abgeschnitten (web). Dashboards und Alerts, die ein solches Backend über das gekürzte Label backend auswählen, brauchen den vollen Namen. Tools, die keinem Backend gehören, werden unter dem Backend unknown gezählt.
Anfragen bleiben, wo die Konfiguration hinzeigt
Abschnitt betitelt „Anfragen bleiben, wo die Konfiguration hinzeigt“- Weiterleitungen zu einem anderen Origin verlieren Credentials, eigene Header, den
Refererund Session-Cookies, führen nie von https zu http und senden keinen Request-Body erneut. - OAuth-Token-Anfragen und Session-Logins folgen keinen Weiterleitungen.
- Die Pfadparameter-Werte
.und..werden abgewiesen. - Transportfehler nennen nur Schema und Host.
file_url_allowed_hostsin einem Eintrag vonbackends.yaml, das die Hosts begrenzt, von denen vom Aufrufer übergebenefile_url-Werte geholt werden, gilt für jede Weiterleitung eines solchen Abrufs, nicht nur für die übergebene URL. Leitet eine erlaubte Quelle auf einen CDN- oder Storage-Host weiter, gehört dieser Host in die Liste.- MCP-Backends per HTTP bleiben beim Origin ihrer konfigurierten URL: Eine Weiterleitung oder ein älterer SSE-Endpunkt, der woandershin zeigt, wird abgewiesen.
Siehe Anfragen an REST-Backends und MCP-Backends per HTTP.
Private Adressen
Abschnitt betitelt „Private Adressen“Mit allow_private_url sind private Adressen nur an den Zielen erreichbar, die die Konfiguration nennt (base_url, token_url, absolute Tool-Pfade), nicht als Ziel einer Weiterleitung. Ohne die Option zählen auch Carrier-Grade-NAT-Adressen (darunter Tailscale-Adressen) sowie Benchmarking-, Dokumentations-, Multicast-, reservierte, NAT64- und 6to4-Bereiche als privat. IPv6-Adressen mit Zonen-Suffix und eine base_url auf der unspezifizierten Adresse werden abgewiesen.
Kleinere Änderungen
Abschnitt betitelt „Kleinere Änderungen“- Blobs kann nur der Benutzer löschen, der sie angelegt hat (Datei-Broker).
execute_codeführt höchstensTOOLMESH_CODE_MAX_CONCURRENTSkripte gleichzeitig aus (Standard 16), ein Benutzer höchstens die Hälfte davon. Weitere Läufe warten bis zu 10 Sekunden und schlagen dann fehl (Code Mode).- Ohne Redis ist
/registerje Client-Adresse begrenzt, je Prozess. TOOLMESH_ISSUERlautet ohne eigenen Werthttps://toolmesh.invalid/; die Variable sollte auf die öffentliche URL gesetzt werden, die Clients verwenden.