# uip admin integrations vpn

> Syntax and options for `uip admin integrations vpn`, which manages VPN gateways and site-to-site connections that let cloud and serverless robots reach on-prem networks privately.

`uip admin integrations vpn` manages VPN gateways and their site-to-site connections. A VPN gateway lets cloud and serverless robots reach on-prem networks privately over a site-to-site IPsec tunnel, hosted in a network whose address space you provide at create time. A gateway can have multiple connections, each peering the gateway with one on-prem network.

This command tree is implemented by the separately-published `@uipath/admin-vpngateway-commands` package, one of several packages composed into `uip admin` (see the [`uip admin` overview](./uip-admin.md)) — it owns no top-level CLI verb of its own; `integrations` is a shared parent namespace other admin integration tools may register under later.

## Concepts

- **Asynchronous operations.** Every mutating verb (`create`, `edit`, `redeploy`, `delete`, `refresh`) returns as soon as the task is *enqueued*, not once it's applied. Poll `gateways get <key>` / `connections get <key>` until `state` reaches a terminal value (`Deployed` for a gateway, anything other than `Connecting`/`Updating` for a connection) before issuing the next mutation. Concurrent mutations on the same gateway return HTTP 409 — wait a few seconds and retry.
- **Destructive verbs require `--confirm`.** `gateways delete` and `connections delete` refuse to run without it, specifically so non-interactive callers can't trigger deletion by accident. `connections edit` also requires `--confirm` on every call, since most edits cause a brief tunnel renegotiation and connectivity drop.
- **List-replace semantics on `edit`.** For both `gateways edit` and `connections edit`, list-shaped flags (`--dns-server`, `--apipa-address`, `--trusted-cert`, `--target-address-space`) *replace* the existing list wholesale when passed — re-pass every entry you want to keep. Each has a matching `--clear-*` flag to empty the list explicitly, mutually exclusive with the populated form.
- **`connections edit` always requires `--shared-key`.** Even when you're not changing it, you must re-supply the current pre-shared key on every edit call — the backend has no partial-update path for it.
- **IPsec policy is all-or-nothing.** If you set any of the 8 IPsec/IKE flags (`--ipsec-sa-lifetime`, `--ipsec-sa-data-size`, `--ipsec-encryption`, `--ipsec-integrity`, `--ike-encryption`, `--ike-integrity`, `--dh-group`, `--pfs-group`), you must set all 8. A GCMAES `--ipsec-encryption` variant requires an identical GCMAES `--ipsec-integrity`. `connections edit` preserves the existing policy by default; pass all 8 flags to replace it, or `--clear-ipsec` to remove it (mutually exclusive with the 8 flags).
- **BGP pairing convention.** `--bgp-peer-address` (the on-prem device's BGP endpoint) must be the `/30` partner of an address in the gateway's `--apipa-address` pool, both drawn from `169.254.21.0/24` or `169.254.22.0/24`. Convention: the gateway takes the higher usable address of the `/30` (e.g. `.10`), the on-prem peer takes the lower (e.g. `.9`). Enabling BGP on a connection that wasn't BGP-enabled before requires passing both `--asn` and `--bgp-peer-address` together — the CLI rejects the edit upfront otherwise.
- **`--vnet-address-space` is immutable after `gateways create`** and must be a CIDR with prefix between `/8` and `/27`; the `169.254.0.0/16` APIPA range is rejected because it collides with the BGP APIPA blocks used internally.

## Synopsis

```text
uip admin integrations vpn gateways list [--tenant <name>]
uip admin integrations vpn gateways get <key> [--tenant <name>]
uip admin integrations vpn gateways tenant-config [--tenant <name>]
uip admin integrations vpn gateways create --name <name> --vnet-address-space <cidr> [--description <text>] [--dns-server <ip>]... [--apipa-address <ip>]... [--trusted-cert <name=base64>]... [--tenant <name>]
uip admin integrations vpn gateways edit <key> [--name <name>] [--description <text>] [--dns-server <ip>]... [--clear-dns-servers] [--apipa-address <ip>]... [--clear-apipa-addresses] [--trusted-cert <name=base64>]... [--clear-trusted-certs] [--tenant <name>]
uip admin integrations vpn gateways redeploy <key> [--tenant <name>]
uip admin integrations vpn gateways delete <key> --confirm [--tenant <name>]

uip admin integrations vpn connections get <key> [--tenant <name>]
uip admin integrations vpn connections create <gateway-key> --name <name> --shared-key <key> --target-ip <ip> [--target-address-space <cidr>]... [--bgp-enabled --asn <num> --bgp-peer-address <ip>] [ipsec flags...] [--tenant <name>]
uip admin integrations vpn connections edit <key> --shared-key <key> --confirm [options...]
uip admin integrations vpn connections refresh <key> [--tenant <name>]
uip admin integrations vpn connections delete <key> --confirm [--tenant <name>]
```

`--tenant <name>` is available on every verb in both groups (defaults to the tenant in your login context).

## uip admin integrations vpn gateways

### uip admin integrations vpn gateways list

List all VPN gateways for the current tenant — key, name, state, type, SKU, VNet, location, public IP, connection count.

#### Options

| Long | Value | Description |
|---|---|---|
| `--tenant <name>` | string | Target tenant. Defaults to your login context. |

#### Example

```bash
uip admin integrations vpn gateways list
```

#### Data shape (--output json)

```json
{
  "Code": "VpnGatewayList",
  "Data": {
    "count": 1,
    "value": [
      {
        "key": "00000000-0000-0000-0000-000000000001",
        "name": "prod-gw",
        "state": "Deployed",
        "gatewayType": "Vpn",
        "sku": "Basic",
        "vnetAddressSpace": "10.0.0.0/24",
        "location": "westus",
        "publicIp": "20.0.0.1",
        "connections": []
      }
    ]
  }
}
```

### uip admin integrations vpn gateways get

Fetch a gateway and its connections by key.

#### Arguments

| Name | Required | Purpose |
|---|---|---|
| `<key>` | yes | VPN gateway key (GUID). |

#### Example

```bash
uip admin integrations vpn gateways get 00000000-0000-0000-0000-000000000001
```

#### Data shape (--output json)

```json
{
  "Code": "VpnGatewayGet",
  "Data": {
    "key": "00000000-0000-0000-0000-000000000001",
    "name": "prod-gw",
    "state": "Deployed",
    "gatewayType": "Vpn",
    "sku": "Basic",
    "vnetAddressSpace": "10.0.0.0/24",
    "location": "westus",
    "publicIp": "20.0.0.1",
    "connections": [
      { "key": "11111111-1111-1111-1111-111111111111", "name": "site-a", "state": "Connected", "targetIpAddress": "203.0.113.10" }
    ],
    "trustedCertificates": [
      { "name": "corp-root-ca", "publicCertificateData": "MIIDazCCAlOgAwIBAgIUHs9..." }
    ]
  }
}
```

### uip admin integrations vpn gateways tenant-config

Check whether the current tenant is allowed to provision a VPN gateway.

#### Example

```bash
uip admin integrations vpn gateways tenant-config
```

#### Data shape (--output json)

```json
{ "Code": "VpnGatewayTenantConfig", "Data": { "canCreateVpnGateway": true } }
```

`Data` also carries `validationError` when `canCreateVpnGateway` is `false`.

### uip admin integrations vpn gateways create

Provision a new VPN gateway. Asynchronous — track state with `gateways get`/`list`; on `Failed`, use `gateways redeploy`.

#### Options

| Long | Value | Required | Description |
|---|---|---|---|
| `--name <name>` | string | **yes** | Gateway name. |
| `--vnet-address-space <cidr>` | CIDR, `/8`–`/27` | **yes** | VNet address space. Immutable after create. Rejects the `169.254.0.0/16` APIPA range. |
| `--description <text>` | string | no | Free-form description. |
| `--dns-server <ip>` | IPv4, repeatable, max 3 | no | DNS server IP. |
| `--apipa-address <ip>` | IPv4 in `169.254.21.0/24` or `169.254.22.0/24`, repeatable, max 2 | no | APIPA BGP peering address. |
| `--trusted-cert <cert-name=base64>` | `<name>=<base64-X509>`, repeatable, max 10 | no | Trusted root certificate. |
| `--tenant <name>` | string | no | Target tenant. |

#### Examples

```bash
uip admin integrations vpn gateways create --name prod-gw --vnet-address-space 10.0.0.0/24
```

```bash
# Full lifecycle: provision, wait for Deployed, then attach a BGP connection
ROOT=$(cat root.b64); INTER=$(cat inter.b64)
GW_KEY=$(uip admin integrations vpn gateways create \
  --name prod-gw \
  --vnet-address-space 10.0.0.0/24 \
  --dns-server 172.23.0.105 --dns-server 172.23.2.89 \
  --apipa-address 169.254.21.10 \
  --trusted-cert "Root=$ROOT" --trusted-cert "Inter=$INTER" \
  --output-filter Data.key --output plain)
until uip admin integrations vpn gateways get $GW_KEY \
  --output-filter Data.state --output plain | grep -q Deployed; do
  sleep 30
done
uip admin integrations vpn connections create $GW_KEY \
  --name site-a --shared-key "MyS3cr3tP4ssphr4se" \
  --target-ip 203.0.113.10 \
  --bgp-enabled --asn 65001 --bgp-peer-address 169.254.21.9
```

#### Data shape (--output json)

```json
{
  "Code": "VpnGatewayCreated",
  "Data": {
    "key": "00000000-0000-0000-0000-000000000001",
    "name": "prod-gw",
    "state": "Provisioning",
    "gatewayType": "Vpn",
    "sku": "Basic",
    "vnetAddressSpace": "10.0.0.0/24"
  }
}
```

### uip admin integrations vpn gateways edit

Update a gateway's mutable fields. Scalars you don't pass are preserved; lists you pass replace the existing list wholesale (see [Concepts](#concepts)). Fails if no edit field is provided.

#### Arguments

| Name | Required | Purpose |
|---|---|---|
| `<key>` | yes | VPN gateway key (GUID). |

#### Options

| Long | Value | Description |
|---|---|---|
| `--name <name>` | string | Rename the gateway. |
| `--description <text>` | string | Update description. |
| `--dns-server <ip>` | IPv4, repeatable, max 3 | Replace the DNS server list. Mutually exclusive with `--clear-dns-servers`. |
| `--clear-dns-servers` | flag | Remove all DNS servers. |
| `--apipa-address <ip>` | IPv4, repeatable, max 2 | Replace the APIPA address list. Mutually exclusive with `--clear-apipa-addresses`. |
| `--clear-apipa-addresses` | flag | Remove all APIPA BGP addresses. |
| `--trusted-cert <cert-name=base64>` | repeatable, max 10 | Replace the trusted certificate list. Mutually exclusive with `--clear-trusted-certs`. |
| `--clear-trusted-certs` | flag | Remove all trusted certificates. |
| `--tenant <name>` | string | Target tenant. |

#### Examples

```bash
uip admin integrations vpn gateways edit 00000000-0000-0000-0000-000000000001 --name new-name
```

```bash
uip admin integrations vpn gateways edit 00000000-0000-0000-0000-000000000001 --clear-dns-servers
```

#### Data shape (--output json)

```json
{
  "Code": "VpnGatewayEdited",
  "Data": { "key": "00000000-0000-0000-0000-000000000001", "name": "new-name" }
}
```

`Data` only echoes back the fields that changed.

### uip admin integrations vpn gateways redeploy

Retry the last background task on a gateway whose previous deployment attempt didn't complete cleanly. Rejected if the gateway is frozen, has a task in flight, or is in an unsupported state.

#### Arguments

| Name | Required | Purpose |
|---|---|---|
| `<key>` | yes | VPN gateway key (GUID). |

#### Example

```bash
uip admin integrations vpn gateways redeploy 00000000-0000-0000-0000-000000000001
```

#### Data shape (--output json)

```json
{ "Code": "VpnGatewayRedeployRequested", "Data": { "Key": "00000000-0000-0000-0000-000000000001" } }
```

### uip admin integrations vpn gateways delete

Delete the gateway and all related infrastructure. Destructive and irreversible.

#### Arguments

| Name | Required | Purpose |
|---|---|---|
| `<key>` | yes | VPN gateway key (GUID). |

#### Options

| Long | Value | Required | Description |
|---|---|---|---|
| `--confirm` | flag | **yes** | Required — the command refuses without it. |
| `--tenant <name>` | string | no | Target tenant. |

#### Example

```bash
uip admin integrations vpn gateways delete 00000000-0000-0000-0000-000000000001 --confirm
```

#### Data shape (--output json)

```json
{ "Code": "VpnGatewayDeleted", "Data": { "Key": "00000000-0000-0000-0000-000000000001" } }
```

## uip admin integrations vpn connections

Site-to-site connections attached to a VPN gateway. Each connection peers one on-prem network with the gateway.

### uip admin integrations vpn connections get

#### Arguments

| Name | Required | Purpose |
|---|---|---|
| `<key>` | yes | VPN gateway connection key (GUID). |

#### Example

```bash
uip admin integrations vpn connections get 00000000-0000-0000-0000-000000000001
```

#### Data shape (--output json)

```json
{
  "Code": "VpnGatewayConnectionGet",
  "Data": {
    "key": "00000000-0000-0000-0000-000000000001",
    "name": "site-a",
    "state": "Connected",
    "targetIpAddress": "203.0.113.10",
    "targetAddressSpaces": ["192.168.1.0/24"],
    "bgpEnabled": false
  }
}
```

### uip admin integrations vpn connections create

Attach a new site-to-site connection to a gateway.

#### Arguments

| Name | Required | Purpose |
|---|---|---|
| `<gateway-key>` | yes | Parent VPN gateway key (GUID). |

#### Options

| Long | Value | Required | Description |
|---|---|---|---|
| `--name <name>` | string | **yes** | Connection name. |
| `--shared-key <key>` | string, ≤128 printable ASCII chars, no spaces/dashes/tildes | **yes** | Pre-shared key. |
| `--target-ip <ip>` | IPv4 | **yes** | On-prem VPN device public IP. |
| `--target-address-space <cidr>` | CIDR, repeatable | conditionally | **Required (at least one)** when `--bgp-enabled` is not set. `0.0.0.0/0` is rejected. |
| `--bgp-enabled` | flag | no | Use BGP for dynamic routing. |
| `--asn <num>` | positive integer | conditionally | **Required** with `--bgp-enabled`. `65515` and `64512` are reserved. |
| `--bgp-peer-address <ip>` | IPv4 | conditionally | **Required** with `--bgp-enabled`. Must be the on-prem `/30` partner of a gateway `--apipa-address`. |
| `--ipsec-sa-lifetime <seconds>` | integer, min 300 | no | IPsec SA lifetime. All-or-nothing with the 7 flags below. |
| `--ipsec-sa-data-size <kb>` | integer, `0` or `1024`–`2147483647` | no | IPsec SA data size. |
| `--ipsec-encryption <alg>` | `None`\|`AES128`\|`AES192`\|`AES256`\|`GCMAES128`\|`GCMAES192`\|`GCMAES256` | no | IPsec encryption algorithm. |
| `--ipsec-integrity <alg>` | `MD5`\|`SHA1`\|`SHA256`\|`SHA384`\|`GCMAES128`\|`GCMAES256` | no | Must match a GCMAES `--ipsec-encryption` exactly. |
| `--ike-encryption <alg>` | `AES128`\|`AES192`\|`AES256`\|`GCMAES128`\|`GCMAES256` | no | IKE encryption algorithm. |
| `--ike-integrity <alg>` | `MD5`\|`SHA1`\|`SHA256`\|`SHA384`\|`GCMAES128`\|`GCMAES256` | no | IKE integrity algorithm. |
| `--dh-group <group>` | `None`\|`DHGroup1`\|`DHGroup2`\|`DHGroup14`\|`DHGroup24`\|`DHGroup2048`\|`ECP256`\|`ECP384` | no | Diffie-Hellman group. |
| `--pfs-group <group>` | `None`\|`PFS1`\|`PFS2`\|`PFS14`\|`PFS24`\|`PFS2048`\|`ECP256`\|`ECP384`\|`PFS` | no | Perfect Forward Secrecy group. |
| `--tenant <name>` | string | no | Target tenant. |

#### Examples

```bash
# Static routes, no BGP
uip admin integrations vpn connections create 00000000-0000-0000-0000-0000000000aa \
  --name site-a --shared-key 'MyS3cr3tP4ssphr4se' \
  --target-ip 203.0.113.10 --target-address-space 192.168.1.0/24
```

```bash
# With BGP
uip admin integrations vpn connections create 00000000-0000-0000-0000-0000000000aa \
  --name site-a --shared-key 'MyS3cr3tP4ssphr4se' \
  --target-ip 203.0.113.10 --bgp-enabled --asn 65001 --bgp-peer-address 169.254.21.1
```

#### Data shape (--output json)

```json
{
  "Code": "VpnGatewayConnectionCreated",
  "Data": {
    "key": "00000000-0000-0000-0000-000000000001",
    "name": "site-a",
    "state": "Connecting",
    "targetIpAddress": "203.0.113.10",
    "bgpEnabled": true,
    "asn": 65001
  }
}
```

### uip admin integrations vpn connections edit

Update a connection's mutable fields. `--shared-key` and `--confirm` are required on every call regardless of what else changes (see [Concepts](#concepts)).

#### Arguments

| Name | Required | Purpose |
|---|---|---|
| `<key>` | yes | VPN gateway connection key (GUID). |

#### Options

| Long | Value | Required | Description |
|---|---|---|---|
| `--shared-key <key>` | string | **yes** | Re-supply the current pre-shared key on every edit. |
| `--confirm` | flag | **yes** | Acknowledge the brief connectivity drop most edits cause. |
| `--name <name>` | string | no | Rename the connection. |
| `--target-ip <ip>` | IPv4 | no | On-prem VPN device public IP. |
| `--target-address-space <cidr>` | repeatable | no | Replace the on-prem CIDR list. `0.0.0.0/0` rejected. Mutually exclusive with `--clear-target-address-spaces`. |
| `--clear-target-address-spaces` | flag | no | Remove all target address spaces. A non-BGP connection with none is misconfigured. |
| `--bgp-enabled` / `--no-bgp-enabled` | flag | no | Enable/disable BGP. Enabling on a previously-non-BGP connection requires `--asn` and `--bgp-peer-address` together. |
| `--asn <num>` | integer | no | BGP ASN. |
| `--bgp-peer-address <ip>` | IPv4 | no | BGP peer address. |
| `--ipsec-sa-lifetime`, `--ipsec-sa-data-size`, `--ipsec-encryption`, `--ipsec-integrity`, `--ike-encryption`, `--ike-integrity`, `--dh-group`, `--pfs-group` | see `connections create` | no | Pass all 8 to replace the IPsec policy; omit all 8 to preserve it. |
| `--clear-ipsec` | flag | no | Remove the IPsec policy. Mutually exclusive with the 8 IPsec/IKE flags. |
| `--tenant <name>` | string | no | Target tenant. |

#### Examples

```bash
uip admin integrations vpn connections edit 00000000-0000-0000-0000-000000000001 \
  --shared-key 'MyS3cr3tP4ssphr4se' --name new-name --confirm
```

```bash
uip admin integrations vpn connections edit 00000000-0000-0000-0000-000000000001 \
  --shared-key 'MyS3cr3tP4ssphr4se' --no-bgp-enabled --confirm
```

#### Data shape (--output json)

```json
{
  "Code": "VpnGatewayConnectionEdited",
  "Data": { "key": "00000000-0000-0000-0000-000000000001", "name": "new-name" }
}
```

### uip admin integrations vpn connections refresh

Queue a background refresh of the connection's state from Azure — connections also refresh automatically on a periodic job; use this only when you don't want to wait for the next cycle. Rejected if another operation is in flight.

#### Arguments

| Name | Required | Purpose |
|---|---|---|
| `<key>` | yes | VPN gateway connection key (GUID). |

#### Example

```bash
uip admin integrations vpn connections refresh 00000000-0000-0000-0000-000000000001
```

#### Data shape (--output json)

```json
{ "Code": "VpnGatewayConnectionRefreshRequested", "Data": { "Key": "00000000-0000-0000-0000-000000000001" } }
```

### uip admin integrations vpn connections delete

Delete the connection. Destructive and irreversible — the on-prem peer must reconnect to a recreated connection afterward.

#### Arguments

| Name | Required | Purpose |
|---|---|---|
| `<key>` | yes | VPN gateway connection key (GUID). |

#### Options

| Long | Value | Required | Description |
|---|---|---|---|
| `--confirm` | flag | **yes** | Required — the command refuses without it. |
| `--tenant <name>` | string | no | Target tenant. |

#### Example

```bash
uip admin integrations vpn connections delete 00000000-0000-0000-0000-000000000001 --confirm
```

#### Data shape (--output json)

```json
{ "Code": "VpnGatewayConnectionDeleted", "Data": { "Key": "00000000-0000-0000-0000-000000000001" } }
```

## See also

- [`uip admin` overview](./uip-admin.md)
- [Global options](./global-options.md)
- [Exit codes](./exit-codes.md)