# On-prem Gateway

Connect a cloud-hosted Zato environment to systems on a private network.

The On-prem Gateway connects a Zato environment running in a public cloud to systems that reside on a private network, such as databases, APIs and file servers.

The gateway is installed on a host on the private network and connects to the Zato container. Once it is connected, Zato accesses the on-prem systems as if it ran on the private network itself. The connection is always made from the private network outwards, so a deployment requires neither a VPN nor an inbound firewall rule.

The gateway runs on Linux hosts, and on Windows hosts under WSL2. Its installation is covered in [Installing the On-prem Gateway](https://zato.io/docs/admin/on-prem-gateway/install.html).

## Outgoing connections {#outgoing-connections}

An outgoing connection is configured with the host name and the port of the on-prem system, exactly as it would be if Zato ran on the private network:

```text
Host:     erp-db.corp.local
Port:     5432
Database: production
```

No property of an outgoing connection refers to the gateway. The same applies to every kind of outgoing connection, including SQL, REST, SOAP, AMQP, LDAP and SFTP. TLS certificates are validated as they are on a direct connection.

## Configuration {#configuration}

Gateways are configured in the Dashboard, under **System** and then **On-prem gateways**. A gateway has the following properties.

| Property | Description |
| --- | --- |
| Name | The name of the gateway |
| Active | Whether the gateway may connect |
| Require key resets | Whether a gateway that is already enrolled can be enrolled again only after **Reset key**, as described in [Re-enrollment](https://zato.io/docs/admin/on-prem-gateway/index.html#re-enrollment) |
| On-prem systems | The systems the gateway provides access to, one `host:port` per line |

A list of on-prem systems takes the following form:

```text
erp-db.corp.local:5432
crm.corp.local:443
mq.corp.local:1414
```

Only the systems on the list can be accessed through the gateway. The same `host:port` cannot be configured under two gateways, because two private networks may each have a different system under the same name and Zato would not know which one a connection is meant for.

### Port numbers {#port-numbers}

Note that each of the following port numbers can be used by only one on-prem system: 8183, 8184, 8185, 8186, 11223, 11224, 11553, 11554 and 17010.

The SSH port of the container, 22 by default, cannot be used by on-prem systems.

## Enrollment {#enrollment}

A gateway is connected to Zato with an enrollment token issued in the Dashboard.

To enroll a gateway:

1. In the Dashboard, open **System** and then **On-prem gateways**.
2. Click **Enrollment token** next to the gateway.
3. Click **Copy**.
4. Provide the token to the gateway on the on-prem host, as described in [Installing the On-prem Gateway](https://zato.io/docs/admin/on-prem-gateway/install.html).

A token is valid for 24 hours and can be used once. Issuing a new token for a gateway replaces any earlier token of that gateway that has not been used yet. After enrollment, the gateway authenticates with its own key, which is generated on the host and never leaves it. No further action is required when the Zato environment or the host is restarted, the gateway reconnects on its own.

## Gateway list {#gateway-list}

The list of gateways in the Dashboard is refreshed on its own and shows the following columns for each gateway.

| Column | Description |
| --- | --- |
| Status | The current state of the gateway, as described in [Status reference](https://zato.io/docs/admin/on-prem-gateway/index.html#status-reference) |
| Systems | The number of on-prem systems configured for the gateway |
| Connected since | How long the gateway has been connected |
| Remote address | The address the gateway connects from |
| Version | The version of the gateway running on the on-prem host |
| Platform | The operating system and the architecture of the on-prem host, e.g. `linux/amd64` |

## Status reference {#status-reference}

The Dashboard reports one of the following statuses for each gateway.

| Status | Description |
| --- | --- |
| Connected | The gateway is connected and the on-prem systems can be accessed. |
| Enrolled, offline | The gateway is enrolled but not connected. Either the gateway is not running or the host cannot reach the Zato environment. |
| Not enrolled | The gateway is configured in the Dashboard and no enrollment token has been used yet. |
| Not active | The gateway is inactive and may not connect. |

## Re-enrollment {#re-enrollment}

A gateway is enrolled again when the host is reinstalled or the gateway is moved to another host. To revoke the key of a gateway, click **Reset key** next to it. The gateway is disconnected and remains so until it is enrolled again.

The **Require key resets** setting determines how a new enrollment token is treated.

| Setting | Behavior |
| --- | --- |
| Enabled | A new enrollment token is accepted only after **Reset key**. This is the default. |
| Disabled | A new enrollment token is accepted directly and **Reset key** is not required. |

## Public address {#public-address}

An enrollment token contains the address the gateway connects to. By default, this is the host name the Dashboard is reached on, combined with the port of the load balancer of the Zato environment. When gateways are to use a different address, for instance one published by a Kubernetes ingress, set `Zato_On_Prem_Gateway_Public_Address` to that address, e.g. `https://api.example.com`.

## Configuration as code {#configuration-as-code}

Gateways are part of [enmasse](https://zato.io/docs/admin/enmasse.html) and are maintained in the same repository as the rest of an environment's configuration:

```yaml
on_prem_gateway:

  - name: head-office
    is_active: true
    is_key_reset_required: true
    hosts:
      - erp-db.corp.local:5432
      - crm.corp.local:443
```

Enrollment tokens and keys are not part of an exported file.