connector installation.md

Dropzone Connector Installation

Before proceeding, see the Dropzone Connector Overview for more information about when you would require the Dropzone Connector in your environment.

Enabling the Private Network Connector Client

Running the Private Network Connector Client requires a machine that meets the following requirements:

This may be a machine dedicated to this container, or a multi-use resource that meets your security policy.

Henceforth we will call this machine the connector-client-host.

To install the Private Network Connector Client, do the following:

Settings > System Info Dropdown

Click Enable Integration Connector

Enable the Integration Connector

System > Connectors Dropdown

"Main" Connector Tile

"Main" Connector Configuration

  connector-client-host$ sudo docker load -i connector.tar.gz

# Or, if sudo is not needed
  connector-client-host$ docker load -i connector.tar.gz

  connector-client-host$ sudo docker run --detach --name connector --env OPTIONS='--auth ...

# Or if sudo is not needed
  connector-client-host$ docker run --detach --name connector --env OPTIONS='--auth ...

  connector-client-host$ docker ps
  CONTAINER ID IMAGE     COMMAND      CREATED         STATUS       NAMES
  1c92972436d9 connector "/app/init"  3 seconds ago   Up 2 seconds dropzone-connector-client

Main Now Connected

When enabling Data and Alert sources that need on-prem access, be sure to specify this Private Network Connector Client.

Alternate Launch Options

The Dropzone UI System > Connector page provides a default docker run command that will work for most scenarios. This section describes alternate options for your docker run that may be appropriate for your environment.

Outbound HTTP Proxy

The Dropzone connector supports using an outbound HTTP proxy, such as Squid, a setup for locked down DMZs for example.

To use an explicit HTTP proxy, update the docker run provided by the Dropzone UI by passing the HTTPS_PROXY flag into the environment:


## Send the outbound tunnel request via http://proxy.example.com:3128 
## Replace with your actual proxy url/port
##
$ docker run ... --env HTTPS_PROXY=http://proxy.example.com:3128 ...

You will need to configure your proxy to allow outbound CONNECT to the host tenant-connector.dropzone.app port 443.

Troubleshooting

The following troubleshooting steps may be useful in conjunction with your Dropzone support team.

Restarting the Private Network Connector Container

It is always safe to delete and relaunch the connector, for example if it does not come back properly after a reboot or system failure.

$ docker stop connector
$ docker rm connector
$ docker run ...    <-- command you got from the Dropzone interface

Testing Internal Connectivity

The connector service runs in a docker container on a host in your network. If it is unable to reach to your internal systems then you will get an error when configuring your integration in the Dropzone UI such as Error 111 - Connection Refused.

Test from the Host

Testing from the host where you're running the connector is sufficient in almost all cases. Using tools such as curl, telnet, netcat (nc, ncat, etc), or openssl are good ways to test any network ACLs that may be preventing your traffic.

Examples:

# See if splunk is available
$ curl -k -v https://our-splunk.example.com

# Same, showing certificate
$ openssl sclient -connect our-splunk.example.com:443

# just test the port is open or not
$ telnet our-splunk.example.com:443
$ nc our-splunk.example.com:443

Test From Inside the Connector

It's possible your docker host can reach your targets, but the connector container cannot. this could be caused by DNS inconsistencies, or having an IP address range for your connector network (traditionally 172.17.0.0/16) that overlaps your target's networks. In these cases, it may be helpful to test from within the connector container directly.

The Dropzone connector container has a very minimal configuration and does not include tools such curl, telnet, netcat (nc, ncat, etc), however it does include openssl which can be used to help troubleshoot.

Here is an example of making a curl-like request for https://www.example.com:


$ host="www.example.com"
$ printf "GET / HTTP/1.0\nHost: $host\n\n" | \
    docker exec -i dropzone-connector-client   \
    openssl s_client -connect $host:443 -servername $host -quiet

If you see the expected HTML output, then the connector has network connectivity to the target.

Testing Outbound Network Connectivity

If the connector fails to connect there could be a network issue or an IPS device that is preventing it from establishing the websocket connection. Running the following from the host where the connector runs can help identify this situation:

# the first part of your tenant hostname, e.g. "mycompany"
# if your tenant is https://mycompany.dropzone.app
$ tenant=mytenant

$ curl --http1.1 -i -N \
    -A "Go-http-client/1.1" \
    -H "Connection: Upgrade" \
    -H "Upgrade: websocket" \
    -H "Host: $tenant-connector.dropzone.app:443" \
    -H "Sec-WebSocket-Key: AAAAAAAAAAAAAAAAAAAAAA==" \
    -H "Sec-WebSocket-Protocol: chisel-v3" \
    -H "Sec-WebSocket-Version: 13" \
    "https://$tenant-connector.dropzone.app:443"

When successful, you should see an HTTP handshake and websocket upgrade like this:

HTTP/1.1 101 Switching Protocols
Upgrade: websocket
Connection: Upgrade
Sec-WebSocket-Accept: ICX+Yqv66kxgM0FcWaLWlFLwTAI=

SSH-chisel-v3-server

If your network requires an HTTP Proxy for outbound connectivity to the connector server, add an -x option to your curl command above. For example if you use squid on squid.example.com port 3128, you'd add -x squid.example.com:3128 to the command.

Any device along the path that is interfering will likely provide feedback when this command is run.

EDR/Firewall/IPS Considerations

The Dropzone Connector Client establishes outbound encrypted connections to your Dropzone SaaS environment which contain reverse tunnels to your on-prem systems. Unfortunately, because this traffic pattern can resemble a Command and Control (C2) client/server setup, some EDR, firewall, or networking tools may flag or block this traffic.

Your security tools should allow you to allowlist the Connector Client binary or associated network traffic. Make the related changes and it should be able to support a reliable connection for your on prem services.

Connector Healthchecks

The default Dropzone Private Network Connector Client docker run command is set to automatically restart the container if it fails. However here are additional ways you can healthcheck the container.

External Healthcheck

From outside the container you can use curl or other web tools to hit the /ping endpoint. For example, assuming the connector has received IP address 172.17.0.3, you would use the following

$ curl -i 172.17.0.3:8000/ping
HTTP/1.1 204 No Content
Date: Sat, 19 Apr 2025 11:43:00 GMT
Server: Python/3.11 aiohttp/3.12.13

Similarly, you could use nsenter to run curl from your host within the container network:

$ sudo nsenter -t $(docker inspect --format '{{ .State.Pid }}' dropzone-connector-client ) -n curl -v http://127.0.0.1:8000/ping`

Internal Healthcheck

From within the container (e.g. if you are using docker compose) you can use python to healthcheck the /ping endpoint.

python3 -c "import http.client, sys; c=http.client.HTTPConnection('127.0.0.1',8000,timeout=5); c.request('GET','/ping'); sys.exit(0 if c.getresponse().status==204 else 1)"

Upgrading the Private Network Connector Client

Dropzone updates the connector client infrequently to improve reliability, performance, or security.

Follow these steps to upgrade.

# Verify it not running
$ docker ps | grep dropzone
CONTAINER ID  IMAGE                COMMAND          NAMES
44726f707a6f  dropzone-connector   "/app/main.py"   dropzone-connector-client

# Stop and remove it
$ docker stop dropzone-connector-client
$ docker rm dropzone-connector-client

# Verify it is not running
$ docker ps | grep dropzone
CONTAINER ID  IMAGE                COMMAND          NAMES

Disabling the Private Network Connector Client

You may disable the Private Network Connector Client at any time. This is typically done when you are migrating the Connector Client to a different host virtual machine.

To disable it, simply run the necessary docker commands.

# Stop and remove it
$ docker stop dropzone-connector-client
$ docker rm dropzone-connector-client

# Verify it is not running
$ docker ps | grep dropzone
CONTAINER ID  IMAGE                COMMAND          NAMES

As soon as the container is stopped the remote access is instantly terminated. You can verify by going to System > Connectors.