# When something isn't allowed

> The steps to fix what stops you in VizTopo: tag an AWS resource, add an IAM or Proxmox permission, write mode, rules, roles, plans, and SSH sign-in problems.

Each section is one reason VizTopo, AWS or Proxmox refuses something, with the steps to fix it. In VizTopo, every such message links here, and where it can, shows the same steps filled in for that box or connection.

## Tag the resource for VizTopo

VizTopo's control and SSH policies let it act only on the AWS resources you tag `viztopo-control` = `true`. You choose which; the AWS console works with your own, wider permissions, so it doesn't need the tag.

1. In the AWS console, open the resource: **EC2 → Instances** (or **Security Groups**, or **VPC → Subnets**), then choose it.
2. Open the **Tags** tab and choose **Manage tags**.
3. Choose **Add new tag**. Key: `viztopo-control`, Value: `true`. Choose **Save**.
4. Back in VizTopo, choose **Refresh from AWS** on the resource so VizTopo sees the tag, then try again.

> **Note:** Or with the AWS CLI: `aws ec2 create-tags --region <region> --resources <id> --tags Key=viztopo-control,Value=true`. To take it back, delete the tag.

## Give VizTopo's AWS identity the permission

VizTopo signs in to AWS as its own IAM user (or role), and AWS refuses what that identity's policies don't allow. VizTopo can't grant itself anything: someone who may change IAM adds the policy.

1. In the IAM console, open **Users** (or **Roles**) and choose the identity VizTopo signs in as. VizTopo's **Permissions** page shows it, after "as".
2. On the **Permissions** tab, choose **Add permissions → Create inline policy**.
3. Choose **JSON**, replace everything in the editor with the policy VizTopo gives for it (on VizTopo's **Permissions** page, under **How to grant it**), and choose **Next**.
4. Name it `VizTopo` and choose **Create policy**.
5. Back in VizTopo, on **Permissions**, choose **Check again**, then try again. IAM takes a few seconds to apply it.

> **Note:** For the features on VizTopo's **Permissions** page, the exact policy is under **How to grant it**; otherwise, allow the action the message names. If AWS still refuses, an organization policy (SCP) or a permissions boundary denies it: ask your AWS admin.

## Give VizTopo a working AWS key

AWS refused the access key VizTopo signs in with: it was deleted, deactivated or rotated in AWS.

1. In the IAM console, open **Users** → the user VizTopo signs in as → **Security credentials**, and check its access key's status.
2. If it's gone or inactive, choose **Create access key**, use case **Application running outside AWS**, and copy both parts.
3. In VizTopo, open **Connections**, choose **Rotate secret** on the connection, and paste the new key. VizTopo tests it before it replaces the old one.
4. Then deactivate and delete the old key in AWS.

## Give VizTopo's Proxmox token the privilege

Proxmox refuses what VizTopo's API token hasn't been granted. A privilege-separated token gets only what both it and its user are granted, so the commands grant both.

1. Open a root shell on any node of the cluster: in Proxmox's web UI, **Datacenter → the node → Shell**, or SSH in as root.
2. Run the commands VizTopo shows for it: on **Permissions**, under the feature's **How to grant it**.
3. Back in VizTopo, on **Permissions**, choose **Check again**, then try again.

> **Note:** Each kind of change has its own small role: see [Connect Proxmox VE](https://viztopo.com/docs/connect-proxmox) for the list.

## Turn on write mode for the connection

Every connection starts read-only: VizTopo changes nothing until someone whose role includes **Control mode** (the owner and admins do) turns on write mode for it.

1. Open **Connections** and find the connection's card.
2. Choose **Enable write mode**, type the connection's name to confirm, and choose **Enable write mode**.
3. Try again. Each change still asks you to confirm it (unless its rule is Allow), and the audit log records it.

> **Note:** Don't see the button? Your role doesn't include Control mode: ask the workspace's owner or an admin (see [Get a role that allows it](https://viztopo.com/docs/fix-access#your-role)). The provider must also allow the change.

## Change the rule that denies it

Each connection has VizTopo rules per kind of action: Allow, Ask every time or Deny. Deny stops VizTopo even when the provider would let it.

1. Open **Permissions** and find the connection's card.
2. Under **What VizTopo may do (your rules)**, set the action to **Ask every time** (you confirm each one) or **Allow**.
3. Try again.

> **Note:** Changing rules takes a role with **Control mode** (the owner and admins have it).

## Get a role that allows it

Your role in this workspace decides what you can do in VizTopo. The workspace's owner, or anyone whose role includes **Manage people and roles**, can change it.

1. Ask the workspace's owner or an admin: **Team** lists everyone and their role.
2. They open **Team** and pick a role that allows it in the list next to your name, or, under **Roles**, tick what's missing on your role (the message names it) and save.
3. Reload VizTopo and try again.

## Make room in the plan

The plan covers a number of boxes. The ones VizTopo found first stay usable; the rest show blurred and can't be controlled.

1. The workspace's owner opens **Settings → Plan** and picks a plan with more boxes.
2. Or remove what you no longer need: connections, or boxes in the provider.

> **Note:** See [Pricing](https://viztopo.com/pricing) for what each plan covers.

## Sign in as the image's user

An EC2 instance only has the user its image (AMI) was built with. Signing in as another one is refused, even with the right key.

1. Set **User** in the sign-in form to the image's user: `ubuntu` on Ubuntu, `ec2-user` on Amazon Linux, Red Hat and SUSE, `admin` on Debian, `centos` on CentOS, `rocky` on Rocky Linux, `bitnami` on Bitnami.
2. Not sure? In the AWS console, open the instance and choose **Connect**: the **EC2 Instance Connect** tab shows the user AWS signs in as.
3. To make VizTopo always use it, tag the instance `viztopo-ssh-user` with that user, then choose **Refresh from AWS**.

## Sign in with the instance's key pair

AWS puts the key pair's public half on the instance when it launches. Its private half is the file downloaded when the key pair was created; AWS doesn't keep a copy.

1. In the sign-in form, choose **Private key**.
2. Choose **Load a key file** and pick the key pair's `.pem` file, or paste its contents.
3. If the key has a passphrase, type it, and choose **Connect**.

> **Note:** Lost the file? AWS can't give it back. Sign in once with the AWS console's Connect, add a new public key to the user's `~/.ssh/authorized_keys`, and use that key here.

## Make signing in without a key work

Without a key, VizTopo asks AWS to accept a one-time key for 60 seconds (EC2 Instance Connect). That needs three things: the permission, the tag if VizTopo's SSH policy is the one allowing it, and the Instance Connect agent on the instance.

1. The permission: VizTopo's AWS identity needs `ec2-instance-connect:SendSSHPublicKey`. See [Give VizTopo's AWS identity the permission](https://viztopo.com/docs/fix-access#aws-permission), with the policy from **Permissions → SSH without a key**.
2. The tag: that policy works only on instances tagged `viztopo-control` = `true`. See [Tag it for VizTopo](https://viztopo.com/docs/fix-access#tag-for-viztopo).
3. The agent: Amazon Linux 2 and 2023 and Ubuntu 20.04 or later come with it. To install it, sign in once with the key pair and run:

   On the instance:

   ```sh
   sudo apt-get install ec2-instance-connect   # Ubuntu
   sudo yum install ec2-instance-connect       # Amazon Linux
   ```

> **Note:** For Red Hat and CentOS, AWS has its own packages: see [AWS's guide](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-instance-connect-set-up.html). Debian and SUSE have none: sign in with the key pair.

## Let VizTopo's server reach port 22

VizTopo's server connects from its own address, not from your computer or from inside AWS, so a security group, network ACL or firewall that lets the AWS console in can still keep it out.

1. The security group: if VizTopo may change it, the sign-in form offers **Let VizTopo's server in on 22…**. Otherwise, in the AWS console: **EC2 → Security Groups** → the instance's group → **Edit inbound rules** → **Add rule**: Type **Custom TCP**, Port `22`, Source **Custom** VizTopo's server address (the sign-in form shows it), with `/32` → **Save rules**.
2. The network ACL, if the subnet's isn't the default: **VPC → Network ACLs** → the subnet's ACL: allow TCP `22` in from that address, and ports 1024-65535 back out.
3. The instance's own firewall, if it has one: for example `sudo ufw allow from <VizTopo's address> to any port 22 proto tcp`.
4. Choose **Check again** in the sign-in form, then connect.

## Give the instance a public address

On viztopo.com, VizTopo's server connects over the internet. The AWS console reaches instances from inside AWS (Session Manager, or an EC2 Instance Connect Endpoint), so it doesn't need one.

1. In the AWS console: **EC2 → Elastic IPs → Allocate Elastic IP address → Allocate**.
2. Select the new address, choose **Actions → Associate Elastic IP address**, pick the instance, and choose **Associate**.
3. Its subnet needs a route to the internet: in its route table, `0.0.0.0/0` to an internet gateway.
4. Back in VizTopo, choose **Refresh from AWS** on the instance, then connect, with SSH open to VizTopo's server (see [Let VizTopo's server reach port 22](https://viztopo.com/docs/fix-access#ssh-reach)).

> **Note:** AWS charges $0.005 an hour for each public IPv4 address, about $3.65 a month.

## Sign in to a Windows instance

Windows instances sign in over Remote Desktop, as Administrator, with a password AWS encrypts with the instance's key pair. They don't run SSH unless someone installed OpenSSH.

1. In VizTopo, on the box, choose **Connect…** and download its `.rdp` file.
2. In the AWS console, open the instance, choose **Connect → RDP client → Get password**, upload the key pair's `.pem` file, and choose **Decrypt password**.
3. Open the `.rdp` file and sign in as `Administrator` with that password. Port 3389 must be open to your own address.

---

Source: https://viztopo.com/docs/fix-access (updated 2026-10-24). Start free: https://viztopo.com/signup