tom27052006
3 weeks ago
2 changed files with 3 additions and 205 deletions
@ -1,200 +0,0 @@ |
|||||
# Custom-role migration recovery |
|
||||
|
|
||||
Vaultwarden deliberately stops the Custom-role migration when the old database state cannot be |
|
||||
translated without either removing access or adding new management authority. A failed preflight |
|
||||
does not authorize Vaultwarden to choose between those outcomes. |
|
||||
|
|
||||
## Before doing anything |
|
||||
|
|
||||
1. Stop every Vaultwarden instance that uses the database. Do not perform this migration during a |
|
||||
rolling deployment. |
|
||||
2. Take and verify a full database backup. |
|
||||
3. Keep the complete startup error. It identifies the state that needs review. |
|
||||
4. Do not add or delete rows in `__diesel_schema_migrations` merely to bypass the preflight. |
|
||||
|
|
||||
The relevant versions are: |
|
||||
|
|
||||
| Version | Purpose | |
|
||||
|---|---| |
|
||||
| `2026-07-15-120000` | Mark that `2026-07-16` is pending in the same migration sequence | |
|
||||
| `2026-07-16-120000` | Add the three collection-permission columns | |
|
||||
| `2026-07-23-120000` | Reconcile legacy Manager/Custom membership permissions | |
|
||||
| `2026-07-24-120000` | Drop membership-level `access_all` | |
|
||||
| `2026-07-24-130000` | Add the three Custom Access permissions | |
|
||||
| `2026-07-24-140000` | Refuse a lossy Custom-role downgrade | |
|
||||
|
|
||||
Diesel stores these directory versions without punctuation in `__diesel_schema_migrations` (for |
|
||||
example, `2026-07-16-120000` is stored as `20260716120000`). |
|
||||
The immutable `2026-06-30-120000` migration is an earlier prerequisite; this table focuses on the |
|
||||
new marker/repair/drop/downgrade safety sequence. |
|
||||
|
|
||||
## Legacy User with membership `access_all` |
|
||||
|
|
||||
Find the affected memberships before the source column is dropped: |
|
||||
|
|
||||
```sql |
|
||||
SELECT uuid, user_uuid, org_uuid, status |
|
||||
FROM users_organizations |
|
||||
WHERE atype = 2 AND access_all = TRUE; |
|
||||
``` |
|
||||
|
|
||||
This state was accepted by older Vaultwarden versions. It has no exact representation in the new |
|
||||
nine-bit Custom-role model: |
|
||||
|
|
||||
- clearing `access_all` keeps the User role but removes organization-wide vault access; |
|
||||
- changing the member to Custom with all three collection permissions preserves broad vault access, |
|
||||
but also grants collection-management capabilities the old User role did not have. |
|
||||
|
|
||||
An organization owner must decide the intended role and permissions for each result. Make that |
|
||||
change on the backed-up pre-drop database and record the decision: |
|
||||
|
|
||||
- to keep the member a normal User, set that membership's `access_all` to false; |
|
||||
- to intentionally promote the member to Custom with Create/Edit/Delete-any authority, set that |
|
||||
membership's `atype` to the legacy Manager value `3` and keep `access_all` true. The repair copies |
|
||||
the bit to all three collection permissions before converting `atype` to `4`. |
|
||||
|
|
||||
Apply either change by exact membership UUID while all Vaultwarden instances are stopped. Do not |
|
||||
bulk-promote these records automatically. |
|
||||
|
|
||||
## Group-derived legacy collection management |
|
||||
|
|
||||
An organization-local `groups.access_all` relationship is safe when the membership has no direct |
|
||||
collection permissions. During a normal upgrade, the older `2026-07-16` migration temporarily |
|
||||
copies that relationship to the exact direct `create/edit/delete = 0/1/1` pattern. The new repair |
|
||||
recognizes the still-present, organization-bound source and deterministically resets the direct |
|
||||
Edit/Delete bits to false **only** when the durable `2026-07-15` marker proves that `2026-07-16` was |
|
||||
pending in the same migration sequence. Vault access remains group-derived, so removing the member |
|
||||
from the group also removes that access. |
|
||||
|
|
||||
The marker survives a process failure between `2026-07-16` and `2026-07-23`, allowing the next |
|
||||
startup to finish the deterministic repair. `2026-07-23` transactionally clears the marker row only |
|
||||
after all guards and data updates succeed. The empty internal bookkeeping table is intentionally |
|
||||
retained so MySQL does not introduce a DDL commit boundary. Do not create, remove, or populate |
|
||||
`__vw_custom_role_same_run_0716` manually. |
|
||||
|
|
||||
The preflight stops only when the three columns already exist and it finds a `0/1/1` pattern. At |
|
||||
that point the values may be either an intentional direct Edit+Delete grant or an older group |
|
||||
backfill whose source group was removed; the database has no provenance bit that can distinguish |
|
||||
them. |
|
||||
|
|
||||
For each stopped `0/1/1` membership, the owner must choose one of these executable outcomes: |
|
||||
|
|
||||
- **Group-derived or obsolete:** set `edit_any_collection` and `delete_any_collection` to false for |
|
||||
that exact membership. Leave the intended group relationship in place if access should remain |
|
||||
group-derived. The next preflight can then proceed. |
|
||||
- **Intentionally direct Edit+Delete:** while every server is stopped, temporarily set |
|
||||
`create_new_collections` to true for that exact membership. The unambiguous `1/1/1` state passes |
|
||||
the repair and is not treated as a group backfill. Run the migration in a maintenance instance |
|
||||
that is not reachable by clients, stop it as soon as all six recovery-sequence versions listed |
|
||||
above are recorded, then set `create_new_collections` back to false before normal service resumes. |
|
||||
This restores the explicitly reviewed direct `0/1/1` state after the repair marker exists. |
|
||||
|
|
||||
The organization boundary used to identify a current group source is: |
|
||||
|
|
||||
```sql |
|
||||
SELECT DISTINCT uo.uuid, uo.org_uuid, g.uuid AS group_uuid |
|
||||
FROM users_organizations AS uo |
|
||||
INNER JOIN groups_users AS gu ON gu.users_organizations_uuid = uo.uuid |
|
||||
INNER JOIN groups AS g ON g.uuid = gu.groups_uuid |
|
||||
WHERE uo.atype IN (3, 4) |
|
||||
AND uo.access_all = FALSE |
|
||||
AND g.organizations_uuid = uo.org_uuid |
|
||||
AND g.access_all = TRUE; |
|
||||
``` |
|
||||
|
|
||||
On MySQL, quote the table as `` `groups` ``. Review direct `0/1/1` records separately: |
|
||||
|
|
||||
```sql |
|
||||
SELECT uuid, user_uuid, org_uuid |
|
||||
FROM users_organizations |
|
||||
WHERE atype IN (3, 4) |
|
||||
AND access_all = FALSE |
|
||||
AND create_new_collections = FALSE |
|
||||
AND edit_any_collection = TRUE |
|
||||
AND delete_any_collection = TRUE; |
|
||||
``` |
|
||||
|
|
||||
Because an explicit Edit+Delete assignment has the same stored values as the historical derived |
|
||||
state, Vaultwarden cannot classify those records automatically. Never use the temporary Create bit |
|
||||
while a server is accepting client traffic. |
|
||||
|
|
||||
## The `access_all` column was already dropped |
|
||||
|
|
||||
If `2026-07-24-120000` is recorded but `2026-07-23-120000` is not, restore a backup from before the |
|
||||
drop and migrate again after resolving the cases above. The old membership bit is no longer present, |
|
||||
so a later migration cannot prove which members had it. |
|
||||
|
|
||||
If no such backup exists, perform a membership-by-membership authorization review using |
|
||||
administrative records before changing roles or flags. Only after the final state has been reviewed |
|
||||
may an operator mark the repair version as resolved. Vaultwarden intentionally provides no automatic |
|
||||
command for this irreversible case. |
|
||||
|
|
||||
## Historical MySQL partial `2026-07-16` migration |
|
||||
|
|
||||
An older branch revision could fail on the unquoted `groups` identifier after MySQL had already |
|
||||
committed all three `ADD COLUMN` statements. The migration version was not recorded, so a normal |
|
||||
retry then failed on duplicate columns. |
|
||||
|
|
||||
Vaultwarden automatically completes this state only when all of the following are true: |
|
||||
|
|
||||
- `2026-07-16-120000` is absent from the ledger; |
|
||||
- all three expected columns exist, are non-null booleans, and default to false; |
|
||||
- `access_all` still exists and `2026-07-24-120000` has not run; |
|
||||
- the stored values are either the untouched false defaults, the values produced by the canonical |
|
||||
membership-`access_all` copy, or exact `0/1/1` values accompanied by both the durable same-run |
|
||||
marker and a current same-organization `groups.access_all` source; and |
|
||||
- neither a legacy User/access-all case nor ambiguous group provenance exists. |
|
||||
|
|
||||
It then reapplies the canonical membership data copy and inserts the ledger row in one transaction. |
|
||||
For the narrowly accepted same-run `0/1/1` crash state, that copy first reconstructs `0/0/0`; the |
|
||||
pending canonical group backfill and `2026-07-23` repair then run normally. A missing group source, |
|
||||
any other partial column set, changed definition, or unexpected value stops startup. Preserve that |
|
||||
database and repair it manually from the verified backup; do not drop columns that may contain |
|
||||
independently changed permissions. |
|
||||
|
|
||||
## Verification after recovery |
|
||||
|
|
||||
After a successful start, verify: |
|
||||
|
|
||||
```sql |
|
||||
SELECT version |
|
||||
FROM __diesel_schema_migrations |
|
||||
WHERE version IN ( |
|
||||
'20260715120000', |
|
||||
'20260716120000', |
|
||||
'20260723120000', |
|
||||
'20260724120000', |
|
||||
'20260724130000', |
|
||||
'20260724140000' |
|
||||
) |
|
||||
ORDER BY version; |
|
||||
|
|
||||
SELECT COUNT(*) AS invalid_manager_types |
|
||||
FROM users_organizations |
|
||||
WHERE atype = 3; |
|
||||
``` |
|
||||
|
|
||||
All six versions must be present and `invalid_manager_types` must be zero. Then test a fresh login, |
|
||||
sync, collection read/edit/delete, and group removal for every membership that was reviewed. |
|
||||
|
|
||||
## Downgrade guard |
|
||||
|
|
||||
The old schema cannot encode nine independent permissions in its single membership `access_all` |
|
||||
bit. Even a state that currently happens to use only `0/0/0` or `1/1/1` could be changed after a |
|
||||
one-step guard was reverted and before a later incremental downgrade. A conditional guard would |
|
||||
therefore create false confidence. |
|
||||
|
|
||||
The newest migration always stops an automatic downgrade with a duplicate-key error in the |
|
||||
`__vw_custom_role_downgrade_guard` temporary table, before any production permission column or |
|
||||
migration-ledger row is removed. This mechanism is enforced by primary keys on SQLite, PostgreSQL, |
|
||||
MySQL 5.7+, and MariaDB; it does not rely on historically ignored MySQL `CHECK` constraints. This is |
|
||||
intentional. |
|
||||
|
|
||||
Rollback requires either: |
|
||||
|
|
||||
- restoring a verified database backup taken before the Custom-role upgrade; or |
|
||||
- an explicit offline transformation plan that exports all permissions, defines the accepted |
|
||||
semantic loss or role changes membership by membership, and is tested against a disposable copy |
|
||||
on the same database backend. |
|
||||
|
|
||||
Do not delete the `20260724140000` ledger row merely to bypass this protection. |
|
||||
Loading…
Reference in new issue