When something isn't allowed

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.

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.

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.

Each kind of change has its own small role: see Connect Proxmox VE 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.

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). 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.

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.

See 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.

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, 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.
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 Copy

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

For Red Hat and CentOS, AWS has its own packages: see AWS's guide. 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).

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.