Skip to main content

Install on Debian/Ubuntu

This guide covers installing nf-data-connector from a .deb package and running it as a systemd service. Packages are available for amd64 and arm64.

nf-data-connector is distributed from NetFoundry's private package repository. You will be issued a username and password by NetFoundry that authorize access. Use the NetFoundry installer script to register the repository and install the package in one step:

curl -fsSL https://get.netfoundry.io/linux-install.bash \
  | sudo bash -s -- --private --username "$USERNAME" --password "$PASSWORD" nf-data-connector

The installer adds the private APT repo (using the credentials you supply), refreshes the package index, and installs nf-data-connector via apt. Re-running the same command upgrades to the latest published version.

Keep your $USERNAME / $PASSWORD out of shell history — pass them via environment variables, a secrets manager, or your provisioning system rather than typing them inline.

Install from a downloaded .deb​

  1. Download the .deb for your architecture. {/* from where? */}

  2. Install it:

    sudo dpkg -i nf-data-connector_<version>_<arch>.deb

  3. If apt complains about missing dependencies:

    sudo apt install -f

What the package installs​

PathPurpose
/usr/bin/nf-data-connectorThe binary
/etc/nf-data-connector/config.yamlMain config (conffile — preserved on upgrade)
/etc/nf-data-connector/rules.yamlTrigger rules (conffile)
/lib/systemd/system/nf-data-connector.serviceSystemd unit
/var/lib/nf-data-connector/Working directory
/var/log/nf-data-connector/Log directory
/usr/share/doc/nf-data-connector/Example configs and README

A system user and group nf-data-connector are created. The service runs as this user with hardening (NoNewPrivileges, ProtectSystem=strict, PrivateTmp, etc.).

note

The service is enabled but not started on install. You must configure it first (see below), then start it manually.

Configure the connector​

1. Edit the main config​

Open the main config file:

sudo -e /etc/nf-data-connector/config.yaml

At minimum, set the controller host(s):

controller:
  hosts:
    - "ctrl-1.example.com:1280"
    - "ctrl-2.example.com:1280"   # optional HA nodes
  auth_method: "password"
  fetch_ca: true

Refer to the Configuration reference for all options.

2. Provide secrets via an environment file​

Store credentials in a systemd environment file to keep them out of config.yaml.

  1. Create the environment file:

    sudo install -m 0640 -o root -g nf-data-connector /dev/null /etc/nf-data-connector/env
    sudo tee /etc/nf-data-connector/env >/dev/null <<'EOF'
    ZITI_USERNAME=my-controller-user
    ZITI_PASSWORD=my-controller-password
    # Optional — only if using Elasticsearch subscriber:
    # ES_USERNAME=elastic
    # ES_PASSWORD=changeme
    # Optional — only if overriding the AWS credential chain for S3
    # (instance profile / task role is preferred when available):
    # AWS_ACCESS_KEY_ID=AKIA...
    # AWS_SECRET_ACCESS_KEY=...
    EOF

  2. Tell systemd to load it by creating a service override:

    sudo systemctl edit nf-data-connector.service

    Add:

    [Service]
    EnvironmentFile=/etc/nf-data-connector/env

  3. Save and exit. Systemd places the override at /etc/systemd/system/nf-data-connector.service.d/override.conf.

3. (Optional) Configure trigger rules​

If you want rule-based alerting, edit /etc/nf-data-connector/rules.yaml and enable triggers in config.yaml:

triggers:
  rules_file: "/etc/nf-data-connector/rules.yaml"
  default_webhook:
    url: "https://alerts.example.com/hooks/ziti"

See the Configuration reference for rule syntax.

Start the service​

Once the connector is configured, start it and verify it's running:

sudo systemctl start nf-data-connector
sudo systemctl status nf-data-connector

Operations​

Common tasks for managing the running service.

View logs​

  • Follow live output:

    sudo journalctl -u nf-data-connector -f

  • Show the last 200 lines:

    sudo journalctl -u nf-data-connector -n 200

  • Filter by time:

    sudo journalctl -u nf-data-connector --since yesterday

Restart after config changes​

After editing config.yaml or the environment file, restart to apply changes:

sudo systemctl restart nf-data-connector

Stop/disable​

To stop the service or prevent it from starting at boot:

sudo systemctl stop nf-data-connector
sudo systemctl disable nf-data-connector

Enable at boot (already enabled on install)​

The service is enabled at boot automatically on install. To re-enable it after disabling:

sudo systemctl enable nf-data-connector

Upgrade​

To upgrade to the latest published version:

sudo apt update
sudo apt install --only-upgrade nf-data-connector

The postinst script restarts the service automatically on upgrade. Your /etc/nf-data-connector/config.yaml and /etc/nf-data-connector/rules.yaml are preserved (they're declared as conffiles).

Uninstall​

To remove the package but keep your configuration files:

sudo apt remove nf-data-connector

To remove everything, including configs, the system user, and data directories:

sudo apt purge nf-data-connector

Troubleshoot​

Service won't start​

Check the logs first:

sudo journalctl -u nf-data-connector -n 100 --no-pager

Common causes:

SymptomLikely cause
authentication failed: auth failed with status 401Wrong ZITI_USERNAME / ZITI_PASSWORD
websocket dial failed: ... no such hostWrong controller.hosts or DNS not resolving
tls: failed to verify certificateSet fetch_ca: true or provide ca_file, or skip_verify: true for dev
no controller hosts configuredNeither host nor hosts is set in config.yaml
Service running but no events reaching subscribersCheck that a subscriber has enabled: true

Reset to a clean state​

Clears the working directory while preserving your configuration files:

sudo systemctl stop nf-data-connector
sudo rm -rf /var/lib/nf-data-connector/*
sudo systemctl start nf-data-connector

Verify the package contents​

  • List installed files:

    dpkg -L nf-data-connector

  • Show version and description:

    dpkg --status nf-data-connector

  • View the unit file with any overrides:

    systemctl cat nf-data-connector.service

More info​