# Deploying an Insight Point using the install script

Veza maintains a script you can use to quickly install and run an Insight Point with Docker. Follow these steps to set up your environment, run the latest install script, and manage the deployment.

The Insight Point installation script includes automatic features to reduce manual configuration steps:

* **Proxy Inheritance**: HTTP proxy settings from the host environment are automatically applied to new installations
* **Certificate Detection**: Host certificate bundles are automatically detected and mounted for new installations
* **Enhanced Connectivity Feedback**: Improved connectivity testing includes proxy information display and dedicated status scripts

> **Note**: Feature availability may vary by Veza release version. Some automatic features apply to new installations and may require reinstallation for existing Insight Points.

### Prerequisites

#### Time Synchronization

Ensure your host system has accurate time synchronization before installation:

```bash
# Verify time synchronization status
timedatectl status

# If NTP is not synchronized, enable it
sudo timedatectl set-ntp true
```

The Insight Point inherits time settings from the host system. Ensure the host maintains accurate time synchronization to prevent workflow timeouts or connectivity issues.

#### System Requirements

* Systemd
* Docker (or Podman with Docker compatibility)
* System resources meeting the [Insight Point requirements](/4yItIzMvkpAvMVFAamTf/integrations/connectivity/insight-point.md#system-requirements) (minimum: 2 CPU cores, 4 GB RAM)

#### Install Docker

{% tabs %}
{% tab title="Amazon Linux" %}

```shell
sudo dnf install -y docker
sudo systemctl enable docker
sudo systemctl start docker
```

{% endtab %}

{% tab title="Ubuntu" %}

```shell
sudo apt-get update
sudo apt-get install -y docker.io
```

{% endtab %}

{% tab title="Red Hat Enterprise Linux" %}

```shell
sudo dnf install -y podman-docker
```

{% endtab %}
{% endtabs %}

### Install

Generate an Insight Point key from the Veza **Integrations** > **Insight Point** page. Store it as an environment variable before downloading and executing the script:

```shell
INSIGHT_POINT_KEY="<key>" bash -c "$(curl -fsSL https://{tenant}.vezacloud.com/insightpoint/install.sh)"
```

or

```shell
export INSIGHT_POINT_KEY="<key>"
bash -c "$(curl -fsSL https://{tenant}.vezacloud.com/insightpoint/install.sh)"
```

#### Setting a custom instance ID for High Availability deployments

Instance ID is required in **High Availability deployments** where multiple instances of Insight Points are being installed with the same `INSIGHT_POINT_KEY`. Instance ID must be unique for each Insight Point instance. By default, the Insight Point uses "default" as the instance ID. To specify a custom instance ID, set the `INSTANCE_ID` environment variable:

```shell
INSIGHT_POINT_KEY="<key>" INSTANCE_ID="my-custom-id" bash -c "$(curl -fsSL https://{tenant}.vezacloud.com/insightpoint/install.sh)"
```

or

```shell
export INSIGHT_POINT_KEY="<key>"
export INSTANCE_ID="my-custom-id"
bash -c "$(curl -fsSL https://{tenant}.vezacloud.com/insightpoint/install.sh)"
```

#### Setting tags during installation

Tags are custom key-value labels that help organize and categorize your Insight Point instances. For an overview of tags, their use cases, and requirements, see [Tags](/4yItIzMvkpAvMVFAamTf/integrations/connectivity/insight-point.md#tags) in the main Insight Point documentation.

To set tags during installation, use the `INSIGHT_POINT_TAGS` environment variable with a comma-separated list of key:value pairs:

```shell
INSIGHT_POINT_KEY="<key>" INSIGHT_POINT_TAGS="environment:production,datacenter:us-west-1,team:platform-engineering" bash -c "$(curl -fsSL https://{tenant}.vezacloud.com/insightpoint/install.sh)"
```

or

```shell
export INSIGHT_POINT_KEY="<key>"
export INSIGHT_POINT_TAGS="environment:production,datacenter:us-west-1,team:platform-engineering"
bash -c "$(curl -fsSL https://{tenant}.vezacloud.com/insightpoint/install.sh)"
```

#### Post-Installation

The Insight Point automatically performs a connectivity test when the container starts. Recent enhancements provide improved feedback:

* HTTP proxy information is now included in connectivity test output for easier debugging
* Connectivity test results are available via the status script for streamlined troubleshooting

**Viewing Connectivity Results:**

```shell
# Use the status script (recommended)
/opt/veza-insight-point/bin/status

# Or check recent service logs
journalctl -u veza-insight-point.service -n 50
```

The connectivity test output includes connection status to your Veza tenant, HTTP proxy information (if configured), certificate bundle configuration status, and any connectivity issues or configuration recommendations.

### Remove

#### Uninstall

Uninstall will remove all components of the Insight Point but will not remove the configuration in /etc/veza-insight-point.

```shell
bash -c "$(curl -fsSL https://{tenant}.vezacloud.com/insightpoint/install.sh)" -- uninstall
```

#### Remove

Remove will remove all components of the Insight Point and the configuration in /etc/veza-insight-point. The Insight Point Key will be lost (if not backed up).

```shell
bash -c "$(curl -fsSL https://{tenant}.vezacloud.com/insightpoint/install.sh)" -- remove
```

### Advanced Configuration

#### Pull from a different registry

The Insight Point image must be pulled from a pull-through cache or private registry (where the image is mirrored). You can override the image repository with the `IMAGE_REPOSITORY` config setting.

Create or edit the configuration in `/etc/veza-insight-point/service.env` to set the `IMAGE_REPOSITORY configuration`:

```shell
IMAGE_REPOSITORY="registry.example.com/veza/insight-point"
```

If pulling some other image version than the default image tag (`latest`), you need to configure the override using the `IMAGE_TAG` option:

```sh
IMAGE_TAG="myversion1"
```

After the changes have been made and saved, restart the Insight Point service:

```shell
sudo systemctl restart veza-insight-point
```

Check that the service has started successfully by running the following command:

```shell
systemctl status veza-insight-point
```

#### Configuring Instance ID

To manually configure the instance ID after installation, create or edit the configuration file `/etc/veza-insight-point/config.env` and add:

```bash
DP_INSTANCE_ID="my-custom-instance-id"
```

After making configuration changes, restart the Insight Point service:

```shell
sudo systemctl restart veza-insight-point
```

#### Configuring Tags

To manually configure tags after installation, create or edit the configuration file `/etc/veza-insight-point/config.env` and add:

```bash
INSIGHT_POINT_TAGS="environment:production,datacenter:us-west-1,team:platform-engineering"
```

After making configuration changes, restart the Insight Point service:

```shell
sudo systemctl restart veza-insight-point
```

#### Removing abandoned Insight Point instances

When you install an Insight Point, it registers itself with the Veza control plane using the provided Insight Point Key and instance ID ("default" if not provided). This allows the control plane to track the instance's status and connectivity. You can list all instances for each configured Insight Point in the Veza **Integrations** > **Insight Point** page.

**Important**: If an Insight Point instance is abandoned (no longer in use and uninstalled), you should manually remove it from the Insight Point in the Veza **Integrations** > **Insight Point** page. This ensures the control plane stops tracking the instance's status and prevents it from affecting Insight Point's overall status your monitoring dashboard.

#### Using a proxy server

{% hint style="info" %}
**Proxy and security:** Traffic between the Insight Point and Veza cloud is encrypted end-to-end using TLS, regardless of the protocol used to connect to the proxy. The `http://` scheme in a proxy URL (such as `http://proxy.local:8080`) controls the connection to the proxy server itself — it does not affect the encryption of data in transit to Veza.
{% endhint %}

**Automatic Proxy Detection (Recommended)**

For new Insight Point installations, HTTP proxy settings are automatically inherited from the host system's `HTTP_PROXY` environment variable. This eliminates the need for manual proxy configuration in most environments.

To verify automatic proxy detection is working:

1. Ensure the host system has `HTTP_PROXY` set in the environment
2. Run the installation script
3. Check the connectivity test output for proxy information

**Manual Proxy Configuration**

If you need to use a different proxy configuration or disable automatic detection, you can manually configure proxy settings.

To disable automatic proxy inheritance, create or edit `/etc/veza-insight-point/config.env` and add:

```bash
# Set to 0 to disable automatic proxy detection, 1 to enable (default for new installations)
HTTP_PROXY_HOST_CONFIG=0
```

To manually configure proxy settings, add these lines to `/etc/veza-insight-point/config.env`:

```bash
HTTP_PROXY=http://proxy.local:8080
HTTPS_PROXY=http://proxy.local:8080
NO_PROXY=*.domain.local,*.domain2.local
```

**Proxy Information Display**

Connectivity tests display current proxy configuration details including:

* Current proxy configuration being used by the Insight Point
* Whether proxy settings were inherited from the host or manually configured
* Any proxy-related connectivity issues

To configure custom certificates, see the [Using custom certificates](#using-custom-certificates) section.

After making configuration changes, restart the Insight Point service:

```shell
sudo systemctl restart veza-insight-point
```

Check that the service has started successfully by running the following command:

```shell
systemctl status veza-insight-point
```

#### Configuring Insight Point to forward connections to Veza (early access)

An Insight Point can proxy connections to Veza, allowing you to send Open Authorization API (OAA) payloads to a locally accessible server within a VPC instead of directly over the internet.

When a proxy port is enabled in the configuration, applications can push to the Insight Point's internal network address (e.g., `http://localhost:8080/api/v1/providers/custom/...`), instead of making API calls directly to Veza's cloud service (`https://$VEZA_URL/api/v1/providers/custom/...`).

The proxy architecture eliminates direct internet connectivity requirements for client applications, allowing them to reach Veza's cloud service through the Insight Point's encrypted tunnel. This approach can simplify firewall configuration by consolidating external connections through a single, monitored egress point within your network infrastructure.

**Deployment Availability:**

* **Docker/External**: Proxy enabled by default (`DP_PROXY_ENABLED=true`)
* **Kubernetes**: Proxy disabled by default (`DP_PROXY_ENABLED=false`), can be overridden for clusters requiring corporate proxy traversal

Create or edit the configuration file `/etc/veza-insight-point/service.env` to set the proxy port:

```bash
PROXY_PORT=8080
```

Save the changes. Then, restart the Insight Point service:

```bash
sudo systemctl restart veza-insight-point
```

Proxy server is supported since Veza release 2025.5.x. For older Insight Points, you will need to reinstall before you can enable a proxy port:

```bash
bash -c "$(curl -fsSL https://{tenant}.vezacloud.com/insightpoint/install.sh)" -- reinstall
```

#### Using custom certificates

The Insight Point runs as a Docker container, which means it is isolated from the host operating system, including its truststore.

Certificates your host trusts (such as a Zscaler or corporate CA) are invisible to the container by default.

The certificate configuration below tells the Insight Point which certificate bundle to copy into the container at startup so it can trust your internal services and proxies.

**Automatic Certificate Bundle Detection (Recommended)**

For new Insight Point installations, the install script automatically detects and configures the host's CA certificate bundle. During installation, the script scans the following standard locations in order and uses the first file it finds:

| Path                                                | Distribution        |
| --------------------------------------------------- | ------------------- |
| `/etc/ssl/certs/ca-certificates.crt`                | Debian, Ubuntu      |
| `/etc/pki/tls/certs/ca-bundle.crt`                  | RHEL, CentOS        |
| `/etc/ssl/ca-bundle.pem`                            | OpenSUSE            |
| `/etc/pki/ca-trust/extracted/pem/tls-ca-bundle.pem` | RHEL (modern)       |
| `/etc/ssl/cert.pem`                                 | Other distributions |

When a bundle is detected, the install script reports the path and (in interactive mode) prompts you to confirm, override, or skip it. The chosen path is saved to `/etc/veza-insight-point/service.env` as `CA_BUNDLE_PATH`.

**Enterprise certificate management (Zscaler, etc.):** If your organization uses a tool like Zscaler, it typically injects its CA certificate into the host's system bundle at one of the paths above. As long as that bundle exists at a standard path and is current, automatic detection will pick it up with no extra configuration.

**Verifying certificate detection**

To confirm the certificate bundle is configured and being used:

```bash
# Check the configured path
grep CA_BUNDLE_PATH /etc/veza-insight-point/service.env
```

A non-empty result (e.g., `CA_BUNDLE_PATH=/etc/ssl/certs/ca-certificates.crt`) means the bundle is configured. When the service starts, you will also see this line in the logs:

```txt
[Insight Point Configuration] Using CA bundle from /etc/ssl/certs/ca-certificates.crt
```

If the line reads `Using default CA bundle` instead, no custom bundle is mounted — the container is using only its built-in certificates.

```bash
# Full status check including certificate configuration
/opt/veza-insight-point/bin/status
```

**Adding a certificate to a running Insight Point**

If the Insight Point is already running but a new CA certificate needs to be trusted, such as when an internal service starts using a new CA, or an enterprise proxy certificate is rotated, you can update the host's system truststore and restart the service. No changes to the Insight Point configuration are needed if `CA_BUNDLE_PATH` already points to the correct bundle file.

The Insight Point reads the bundle from `CA_BUNDLE_PATH` and copies it into the container on each service start. Restarting after updating the host bundle is all that is required.

**Step 1: Add the CA certificate to the host trust store**

{% tabs %}
{% tab title="Debian, Ubuntu" %}

```bash
sudo cp your-ca.crt /usr/local/share/ca-certificates/your-ca.crt
sudo update-ca-certificates
```

{% endtab %}

{% tab title="RHEL, CentOS" %}

```bash
sudo cp your-ca.crt /etc/pki/ca-trust/source/anchors/your-ca.crt
sudo update-ca-trust
```

{% endtab %}

{% tab title="OpenSUSE" %}

```bash
sudo cp your-ca.crt /etc/pki/trust/anchors/your-ca.crt
sudo update-ca-trust
```

{% endtab %}
{% endtabs %}

**Step 2: Restart the Insight Point**

```bash
sudo systemctl restart veza-insight-point
```

**Step 3: Confirm the updated bundle is in use**

```bash
journalctl -u veza-insight-point.service -n 20 | grep "CA bundle"
```

The output should show `Using CA bundle from <path>`. If TLS errors persist after restarting, re-run the truststore update command from Step 1 to confirm the certificate is present. On Debian and Ubuntu, the output will include `0 added, 0 removed; done` if the certificate is already in the store. On RHEL, CentOS, and OpenSUSE, `update-ca-trust` produces no output on success.

**Manual Certificate Configuration**

If automatic detection did not find the right bundle (e.g., your CA bundle is in a non-standard location), set `CA_BUNDLE_PATH` directly in `/etc/veza-insight-point/service.env`:

```bash
# Add or update this line in /etc/veza-insight-point/service.env
CA_BUNDLE_PATH=/path/to/your/ca-bundle.crt
```

For example, if your Zscaler or corporate CA bundle is at a custom path:

```bash
CA_BUNDLE_PATH=/usr/local/share/ca-certificates/corporate-ca.crt
```

After making configuration changes, restart the Insight Point service:

```shell
sudo systemctl restart veza-insight-point
```

Confirm the bundle is now being used by checking the startup log:

```shell
journalctl -u veza-insight-point.service -n 20 | grep "CA bundle"
```

**Disabling certificate mounting**

To run the Insight Point without mounting any custom certificate bundle (not recommended in environments with private CAs):

```bash
# In /etc/veza-insight-point/service.env, set to empty string
CA_BUNDLE_PATH=
```

#### Webhook Relay Configuration

The webhook relay service allows the Insight Point to forward webhook requests to destinations in your private network. For an overview of webhook relay, when to use it, security considerations, and supported host formats, see [Webhook Relay](/4yItIzMvkpAvMVFAamTf/integrations/connectivity/insight-point.md#webhook-relay) in the main Insight Point documentation.

**Configuration During Installation**

To enable webhook relay during initial installation, set the environment variables before running the install script:

```shell
export INSIGHT_POINT_KEY="<key>"
export WEBHOOK_RELAY_ENABLED=true
export WEBHOOK_RELAY_ALLOWED_HOSTS="webhook.site,*.example.com,172.17.0.0/24"
bash -c "$(curl -fsSL https://{tenant}.vezacloud.com/insightpoint/install.sh)"
```

Or in a single command:

```shell
INSIGHT_POINT_KEY="<key>" WEBHOOK_RELAY_ENABLED=true WEBHOOK_RELAY_ALLOWED_HOSTS="webhook.site,*.example.com,172.17.0.0/24" bash -c "$(curl -fsSL https://{tenant}.vezacloud.com/insightpoint/install.sh)"
```

**Manual Configuration**

To configure webhook relay on an existing Insight Point installation, edit the configuration file:

```bash
sudo vi /etc/veza-insight-point/config.env
```

Add or update the following lines:

```bash
WEBHOOK_RELAY_ENABLED=true
WEBHOOK_RELAY_ALLOWED_HOSTS=webhook.site,*.example.com,172.17.0.0/24
```

To disable webhook relay:

```bash
WEBHOOK_RELAY_ENABLED=false
```

After making configuration changes, restart the Insight Point service:

```shell
sudo systemctl restart veza-insight-point
```

**Verifying Webhook Relay Configuration**

To verify webhook relay is configured correctly:

1. Check the configuration file:

   ```bash
   cat /etc/veza-insight-point/config.env | grep WEBHOOK_RELAY
   ```
2. Inspect the container environment variables:

   ```bash
   docker inspect veza-insight-point --format='{{.Config.Env}}'
   ```
3. Use the status script:

   ```bash
   /opt/veza-insight-point/bin/status
   ```

If webhook relay is enabled but not working:

* Verify the allowed hosts are in the correct format
* Check that the destination is included in the allowed hosts list
* Review the Insight Point logs for validation or connection errors
* Ensure the destination is actually reachable from the Insight Point's network

### Credential files for integrations

Some integrations require credential files and environment variables to be present inside the Insight Point container at extraction time. Active Directory [Kerberos Token Authentication](/4yItIzMvkpAvMVFAamTf/integrations/integrations/active-directory.md#kerberos-token-authentication) is the primary example.

{% hint style="info" %}
The `/tmp` directory inside the Insight Point container is a Docker named volume (`veza-insight-point-tmp`), not the host's `/tmp`. Files placed on the host filesystem are not visible inside the container unless explicitly mounted using `CONTAINER_FLAGS`.
{% endhint %}

#### Set environment variables

Add the required environment variables to `/etc/veza-insight-point/config.env` on the Insight Point host. For example, for Kerberos Token Authentication:

```sh
KRB5_CONFIG=/tmp/krb5.conf
KRB5CCNAME=/tmp/krb5cc_go
LDAP_CERTIFICATE=/tmp/ldap_cert.pem
```

#### Mount credential files

Add volume mounts via `CONTAINER_FLAGS` in `/etc/veza-insight-point/service.env`. Each `--volume` flag maps a file on the host to a path inside the container:

```sh
CONTAINER_FLAGS="--volume=/path/to/krb5.conf:/tmp/krb5.conf:ro --volume=/path/to/ldap_cert.pem:/tmp/ldap_cert.pem:ro"
```

Restart the Insight Point to apply the changes:

```sh
sudo systemctl restart veza-insight-point
```

#### Run commands inside the container

To run commands that write to the container's `/tmp` volume (such as `kinit` to generate a Kerberos credential cache), use `docker exec`:

```sh
docker exec veza-insight-point kinit <username>@<REALM>
docker exec veza-insight-point klist
```

The credential cache saves to the named `/tmp` volume and persists while the container is running. Re-run `kinit` if the container restarts or when tickets expire.

### Troubleshooting

#### Status Script (Recommended)

The Insight Point installation includes a dedicated status script for health checking without requiring log inspection. This script is the recommended first step for troubleshooting.

Run the status script to check Insight Point health:

```shell
/opt/veza-insight-point/bin/status
```

The status script checks:

* **Service Status**: Whether the Insight Point service is running
* **Health Endpoint**: Whether the service is responding to health checks
* **Connectivity Test**: Network connectivity to your Veza tenant
* **Configuration**: Current proxy and certificate settings

This script provides immediate feedback on common issues and is ideal for iterative troubleshooting when making configuration changes.

#### Service Status

Retrieve the status of the Insight Point `systemd` service:

```shell
systemctl status veza-insight-point.service
```

#### Connectivity Testing

Connectivity test results are displayed in the terminal. For ongoing troubleshooting, use the status script above or check recent logs for connectivity information.

#### Logs

For detailed troubleshooting when the status script indicates issues, examine the service logs:

Retrieve last 500 log lines for the Insight Point service:

```shell
journalctl -n 500 -u veza-insight-point.service
```

Follow logs for the Insight Point service:

```shell
journalctl -u veza-insight-point.service -f
```

#### Reinstall

Reinstall will remove the currently installed Insight Point service and install it again. All configuration in /etc/veza-insight-point will be preserved.

```shell
bash -c "$(curl -fsSL https://{tenant}.vezacloud.com/insightpoint/install.sh)" -- reinstall
```

### Tips & Best Practices

#### Using the Status Script for Iterative Troubleshooting

When configuring proxy settings or troubleshooting connectivity issues, use the status script to quickly verify changes without examining logs:

```shell
# Make configuration changes
sudo systemctl restart veza-insight-point

# Check if the changes resolved the issue
/opt/veza-insight-point/bin/status
```

This approach is much faster than manually inspecting service logs and provides immediate feedback on whether configuration changes are working.

#### When Manual Configuration is Still Needed

While automatic features handle most scenarios, manual configuration may be required for:

* **Custom Proxy Settings**: When the desired proxy differs from the host's `HTTP_PROXY` setting
* **Specific Certificate Bundles**: When using certificates in non-standard locations
* **Enterprise Environments**: Where automatic detection may not work due to security policies
* **Legacy Installations**: Older Insight Points may not have all automatic features

#### Troubleshooting Automatic Features

If automatic proxy or certificate detection isn't working:

1. Check the connectivity test output for configuration details
2. Verify the host system's environment variables (`echo $HTTP_PROXY`)
3. Use the status script to see current configuration
4. Fall back to manual configuration if needed


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.veza.com/4yItIzMvkpAvMVFAamTf/integrations/connectivity/insight-point/insight-point-install-script.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.