Upgrading a Legacy Namespace
A namespace created before identity-based access is legacy: a public key grants access through its device ACL, firewall rules restrict it, and a device enrolls with the namespace’s tenant ID alone. A namespace created today is new: identities and access policies decide access, and a device enrolls by pairing or with a provisioning key.
Moving across is an upgrade you make once, when you are ready, and it cannot be undone. This page is what to do before you click it.
What changes
| Legacy | Identity | |
|---|---|---|
| Proves who you are | A public key registered in the namespace | An identity bound to a person or an automation |
| Decides what you reach | The key’s device ACL, plus firewall rules | Access policies |
| An unlisted device | Reachable unless a rule blocks it | Unreachable until a policy grants it |
| Source IP | A firewall rule can grant on it | Only narrows a grant; never grants |
| Revoking one person | Find and remove their key everywhere it applies | Revoke the identity, in one place |
| Audit trail names | The key | The person |
| A device enrolls by | TENANT_ID alone, then someone accepts it |
Pairing or a provisioning key, and the deprecated TENANT_ID |
| Password login | Allowed | Refused, in the web terminal too |
After the upgrade the firewall checks are bypassed entirely. The rules stay stored and manageable, and are never consulted. Devices already enrolled, accepted or still pending, keep authenticating with the tenant they persisted, and a device that enrolls with the tenant alone still lands pending.
Before you upgrade
The upgrade takes effect on the next connection, so do the mapping first.
1. Inventory who actually connects. List the public keys in the namespace and work out who holds each one. The keys nobody can account for are the reason this migration is worth doing — do not carry them across.
2. Turn each key into an identity. Add the ones you are keeping on the SSH Identities page, each bound to the right member. An automation’s key goes on the API key instead, from its SSH access on the Team page; see SSH Access. Doing this before the upgrade means nobody sits through a first-use approval.
3. Translate your firewall rules. A deny rule usually becomes a deny policy. An allow rule that grants on source IP has no direct equivalent — source IP in a policy only narrows, so the policy needs a real subject, with the addresses as a restriction on top. This is the sharpest semantic difference in the migration, and anyone relying on IP-based grants will feel it.
4. Write the allows. Start from roles rather than individuals, so the grant keeps working as people join and leave. Access policies select devices by tag only, not by hostname pattern — a firewall rule that filtered by hostname needs the matching devices tagged before you can carry it across.
5. Decide where re-authentication belongs. Production and privileged logins are the usual candidates. Off is the default and the right choice nearly everywhere else.
6. Plan how new devices will enroll. A device presenting only TENANT_ID still enrolls, and
lands pending for somebody to accept. Images and scripts that bake the tenant in keep working, but
a provisioning key accepts and tags a fleet without that
queue, and a Docker connector takes it as SHELLHUB_PROVISIONING_KEY.
7. Check the agent versions. The upgrade does not change which agents may connect. That is the separate Device signature enforcement setting, off in a namespace that predates it and on in one created after. If you move a fleet with agents older than 0.27 into a new namespace instead of upgrading this one, turn the setting off there first, or update the agents: an old agent cannot sign the server’s challenge and is refused. A refused agent whose device the namespace does not have shows up at Pending devices with the reason.
Upgrading
Click Upgrade on the namespace’s SSH settings. The confirmation spells out what changes and asks for the namespace’s name, because there is no way back.
If the namespace has no policies at the moment you upgrade, ShellHub seeds one, Owner access, which grants the owner every login on every device, so default deny cannot lock the owner out.
Every other member starts with no access. That is why the mapping above matters: anyone you did not write a policy for loses access the moment you upgrade.
After the upgrade
Public keys and firewall rules remain visible but decide nothing. Leave them until you are confident, then remove them — a stale key that grants nothing here is still a key somebody might try elsewhere.
Watch for refusals in the first days. no policy grants "<login>" on this device means a mapping
was missed. See Connection Denied.
Where to go next
- How Authorization Works — The model you are moving to.
- Access Policies — Writing the rules.
- Public Keys — The model you are leaving.
- Provisioning Keys — How new devices enroll from here on.