> ## Documentation Index
> Fetch the complete documentation index at: https://docs.neoagent.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Connecting VMware vSphere to Neo

> Save your vCenter address and a vCenter user for Neo

## Before you start

* Neo needs **vCenter Server 8.0 Update 1 or later**, the first release with the vSphere JSON API. Neo connects to vCenter, not to a standalone ESXi host.
* Neo reaches vCenter over the internet. Its API must answer on **HTTPS** with a certificate from a public certificate authority, at a public address. If a firewall or reverse proxy limits who can reach it, allow [Neo's addresses](/integrations/ip-whitelisting) to reach `/sdk/vim25/`.

### If vCenter is only on your internal network

Most vCenters are. Publish only the API, never the whole vCenter. Put a reverse proxy at your network edge that:

* answers on a public name over HTTPS, with a certificate from a public certificate authority;
* forwards only paths under `/sdk/vim25/` to your vCenter, and refuses every other path;
* accepts connections only from [Neo's addresses](/integrations/ip-whitelisting);
* passes the `vmware-api-session-id` header through in both directions.

Save the proxy's public address in Neo.

## 1. Make a vCenter user for Neo

<Steps>
  <Step title="Create the user">
    In the vSphere Client, open **Administration → Single Sign On → Users and Groups** and add a user for Neo in your vCenter's domain, such as `neo@vsphere.local`, with a strong password.
  </Step>

  <Step title="Give it a role where Neo works">
    Open **Administration → Access Control → Roles** and pick or make a role with the privileges your agents need: **Read-only** for an agent that only reads; **Virtual machine** privileges (inventory, configuration, interaction, provisioning, snapshot management) to create and manage VMs; **Datastore → Allocate space** and **Resource → Assign virtual machine to resource pool** to create one. Then add a permission for Neo's user with that role on the objects Neo should reach, such as each client's VM folder, and tick **Propagate to children**.
  </Step>
</Steps>

Neo can do only what this user may do, whatever the agent's access profile says.

<Warning>
  If the password expires or you lock the user, Neo loses access until you save the new password here.
</Warning>

## 2. Add the user in Neo

<Steps>
  <Step title="Open Integrations">
    In the Neo Dashboard, open [**Integrations** → **VMware vSphere**](https://dashboard.neoagent.io/integrations?open=vsphere), under Networking.
  </Step>

  <Step title="Save the address, user name and password">
    Enter the address of your vCenter (for example `https://vcenter.example.com`), Neo's user name and its password, then click **Save settings**. Neo reads your vCenter's version and signs in before saving, so a wrong address, an older vCenter or a refused password is rejected straight away.
  </Step>
</Steps>

## 3. Turn vSphere on per agent

Open the agent, go to the Integrations section, and configure the VMware vSphere block. Agents see only what Neo's vCenter user can see.

### Pick an access profile

<CardGroup cols={2}>
  <Card title="Read Only" icon="magnifying-glass">
    Read VMs, hosts, datastores, networks, alarms and events. Nothing is changed.
  </Card>

  <Card title="Helpdesk" icon="headset">
    Acknowledge alarms without approval. Creating, powering, snapshotting or changing a VM, and running a program in a guest, wait on a technician. Everything else is read only.
  </Card>

  <Card title="IT Admin" icon="user-gear">
    VMs, hosts, storage, networking and alarms change without approval, except the changes that always ask. Guest operations, host firewall and services, users and permissions, and licenses, certificates and settings wait on a technician.
  </Card>

  <Card title="Full Automation" icon="bolt">
    Every change runs without approval, except the [changes that always ask a technician](#changes-that-always-ask-a-technician).
  </Card>
</CardGroup>

### Or set each area by hand

| Area | Notes |
| - | - |
| **Inventory and Search** | Datacenters and folders, finding objects by name, IP, DNS name or UUID, views and the property collector that list objects, custom attributes. Agents use it to find the object behind a ticket; each object's own properties follow its area. |
| **Virtual Machines** | VMs, templates, vApps, snapshots, guest customization specifications and OVF deployment: create, clone, change, power, snapshot, move and delete. |
| **Guest Operations** | Programs, processes, files and the Windows registry inside a guest, through VMware Tools. |
| **Hosts and Clusters** | ESXi hosts, clusters, resource pools and host profiles: maintenance mode, reboot, DRS and HA, patches. |
| **Host Firewall and Services** | A host's firewall, its services such as SSH, and SNMP. |
| **Storage and Datastores** | Datastores, files and virtual disks, storage devices, vSAN, storage policies and iSCSI. |
| **Networking** | Networks and port groups, distributed switches, host networking and IP pools. |
| **Alarms, Events and Tasks** | Alarms, events, tasks, scheduled tasks and performance counters. |
| **Users, Roles and Permissions** | Roles and permissions, sessions, host local accounts, lockdown mode, Active Directory membership and guest aliases. Every change here waits on a technician. |
| **Licenses, Certificates and Settings** | Advanced settings, licenses, extensions, certificates, encryption keys, logs, vCenter HA and the ESX Agent Manager. |

Each area can be Disabled, Read Only or Read/Write, and has its own technician approval setting.

### Changes that always ask a technician

These wait on a technician under every profile, whatever the area's own approval setting:

* Deleting or unregistering an inventory object (a VM, vApp, host, cluster or network) or encryption keys, uninstalling software, a patch or an agency's agents, and turning off a VM's fault tolerance. Neo never deletes a folder, a datacenter, a resource pool or a vApp, which would delete or move everything inside. A VM change that deletes or replaces a disk's file asks too.
* In **Storage and Datastores**, any change that deletes or removes something: a datastore, a file or virtual disk, a vSAN object, disk or file share, a storage policy, or a storage setting such as an iSCSI target.
* Any change to users, roles, permissions, sessions, host local accounts, lockdown mode or Active Directory membership.
* Any change to alarms or scheduled tasks (creating, changing, enabling, disabling, removing or running one) other than acknowledging or clearing a triggered alarm, because vCenter runs their actions later with no one in front, and a removed alarm stops watching. Neo never creates an alarm or scheduled task whose action calls a method or runs a script, and never runs a scheduled task.
* Any change to certificates, encryption keys, key providers or vCenter extensions, and turning encryption on or off or changing the key of a host, cluster, VM or disk, which also needs Licenses, Certificates and Settings enabled.
* Any change that stores a credential: a password, a key, an SNMP community, a credential setting, or the user name and password in a URL. The guest account in a guest operation is used for that call only, so it does not ask on its own.

## Troubleshooting

| Error when you save | What to check |
| - | - |
| No vSphere JSON API answered | The address, and that your vCenter runs 8.0 Update 1 or later. Open `<address>/sdk/vim25/8.0.1.0/ServiceInstance/ServiceInstance/content` in a browser: vCenter answers it. |
| ... is an ESXi host | Enter the vCenter address, not a host's. |
| This vCenter runs API version ... | Upgrade to vCenter 8.0 Update 1 or later. |
| vCenter rejected the user name or password | The user name with its domain, such as `neo@vsphere.local`, and the password. |
| vCenter accepted the user but gave it no access | Add a permission for Neo's user on the objects it should reach. |
| A web server in front of vCenter refused Neo | Allow Neo's addresses to reach `/sdk/vim25/`. |
| Could not reach vCenter | The address, that it is public, and that its certificate comes from a public certificate authority. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.