# Upgrade-Hinweise: was sich für bestehende Installationen ändert

> Was beim Upgrade von ToolMesh zu prüfen ist: in v0.6.0 der optionale Command-Credential-Store, an Credentials und Hosts gebundene Backends, eine Bestätigung beim Login, vertrauenswürdige Proxys.

Canonical: https://www.toolmesh.io/de/upgrading/

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](https://github.com/DunkelCloud/ToolMesh/releases) nennen jede Änderung jedes Releases.

## 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](https://github.com/DunkelCloud/ToolMesh/releases/tag/v0.6.0) verweisen auf das Security Advisory.

### Checkliste

1. v0.6.0 starten, im Log nach `backend refused` suchen und die dort genannten Zeilen `credentials:` oder `allowed_hosts:` in die Einträge von `backends.yaml` übernehmen. Jeder REST-Eintrag braucht einen `name`.
2. Hinter einem Reverse-Proxy, der nicht auf demselben Host läuft, `TOOLMESH_TRUSTED_PROXIES` auf die eigene Adresse des Proxys setzen, nicht auf das Netz, das er mit ToolMesh teilt.
3. Skriptgesteuerte Logins so anpassen, dass sie `confirm_host` senden, und `TOOLMESH_OAUTH_REDIRECT_HOSTS` in Betracht ziehen.
4. `TOOLMESH_ISSUER` auf die öffentliche URL setzen, die Clients verwenden, falls die Variable noch ihren Standardwert hat.
5. Gate-Policies prüfen, die DADL-Parameter mit Strings wie `"false"` vergleichen: Sie sehen jetzt den deklarierten Typ.
6. Dashboards und Alerts anpassen, die ein Backend mit `_` im Namen über das gekürzte Label `backend` auswählen (siehe [Volle Backend-Namen in Audit, Telemetrie und Metriken](#volle-backend-namen-in-audit-telemetrie-und-metriken)).
7. 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](/de/authentication/#tokens-aus-der-zeit-vor-dem-upgrade)).

### 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](https://github.com/DunkelCloud/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](/de/configuration/#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

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](/de/configuration/#bindung-an-credentials-und-hosts).

### 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](/de/authentication/#die-login-seite).

### 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](/de/authentication/#tokens-aus-der-zeit-vor-dem-upgrade).

### 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](/de/authentication/#client-adresse) und [Proxy in einem Container](/de/authentication/#proxy-in-einem-container).

### 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](/de/authentication/#drosselung-von-api-keys).

### 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](/de/output-gate/#was-policies-sehen).

### 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](https://dadl.ai/spec/dadl-spec-v0.2) (§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

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

- Weiterleitungen zu einem anderen Origin verlieren Credentials, eigene Header, den `Referer` und 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_hosts` in einem Eintrag von `backends.yaml`, das die Hosts begrenzt, von denen vom Aufrufer übergebene `file_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](/de/dadl/#anfragen-an-rest-backends) und [MCP-Backends per HTTP](/de/configuration/#mcp-backends-per-http).

### 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

- Blobs kann nur der Benutzer löschen, der sie angelegt hat ([Datei-Broker](/de/configuration/#datei-broker)).
- `execute_code` führt höchstens `TOOLMESH_CODE_MAX_CONCURRENT` Skripte 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](/de/configuration/#code-mode)).
- Ohne Redis ist `/register` je Client-Adresse begrenzt, je Prozess.
- `TOOLMESH_ISSUER` lautet ohne eigenen Wert `https://toolmesh.invalid/`; die Variable sollte auf die öffentliche URL gesetzt werden, die Clients verwenden.
