Skip to main content

Install, Configure, and Upgrade Guide for 26.x

Deploy Flowlink as a Linux Service

Note

Operating Flowlink as a service requires Flowlink version 2.0.0 or later.

Use this topic if you have already installed, or want to upgrade to, Flowlink version 2.0.0 or later. This topic includes Steps 4 and 5 specific to that deployment type and assume that you've already completed Steps 1–3 in Configure Flowlink.

You can deploy Illumio Flowlink either as a manually controlled application (pre-version 2.0.0) or as a Linux service. Beginning with Flowlink version 2.0.0, Flowlink installs as a Linux service by default, allowing it to automatically start after a system boot or restart.

Operating Flowlink as a service improves operational reliability, aligns with standard Linux service management practices, and is recommended for production environments.

Configuration Options for Flowlink version 2.0.0 or later

New Installation

Install Flowlink 2.0.0 or later as a Linux service that starts automatically after a system boot or restart. (Assumes that you've completed STEPS 1 - 3 in Configure Flowlink.)

Upgrade to Flowlink 2.0.0

To upgrade an existing Flowlink 1.x installation to service-based operation, uninstall the existing package and then install Flowlink 2.0.0 or later. (See Configure Flowlink installation steps.)

rpm -e illumio-flowlink

Revert to or preserve legacy Flowlink pre-v2.0.0 application-based behavior

Caution

Operating Flowlink with legacy (pre-v2.0.0) application-based behavior is not recommended for production environments.

Set the following environment variable before installation.

export NOT_AS_SERVICE=true
Installation Artifacts

When Flowlink is installed as a service, a dedicated service user is created and the following files and directories are installed:

  • ilo-flowlink user and group

  • /usr/local/illumio

  • /usr/local/bin/flowlink

  • /usr/local/bin/illumio-flowlink-ctl

  • /usr/local/bin/illumio-flowlink-monitor

  • /etc/illumio-flowlink/config.yaml

  • /var/lib/illumio-flowlink/data

  • /var/log/illumio-flowlink

  • /etc/init.d/illumio-flowlink

  • /etc/logrotate.d/flowlink-logrotate.conf

Remaining steps for configuring Flowlink as a Service

Perform these steps if you are deploying Flowlink 2.0.0 or later and have completed STEPS 1 - 3 in Configure Flowlink.

STEP 4: Configure a Flowlink YAML File (for version 2.0.0+)

Note

Before editing the configuration file, note that the installer has already created it at /etc/illumio-flowlink/config.yaml and pre-configured the data_directory (/var/lib/illumio-flowlink/data) and log file location (/var/log/illumio-flowlink). You don't need to set these parameters manually. Because the file is owned by the ilo-flowlink service user, you  must use sudo to edit it. At minimum, you must provide values for the following parameters: pce_addr, org_id (required for SaaS; optional for on-premises), api_key, and Destinations. All other parameters are optional and will use their defaults if not specified.

Configure Flowlink by defining its runtime parameters in a YAML file. The included JSON schema validates the configuration to ensure all parameters are complete, well‑formed, and supported.

Warning

You should not start Flowlink until the configuration file has been fully reviewed and updated for the target environment.

  1. Open the pre-installed configuration file using sudo:

    sudo vi /etc/illumio-flowlink/config.yaml

  2. Store the API key file in a location readable by the ilo-flowlink service user. The recommended location is /etc/illumio-flowlink/api_info. Set permissions so that only the service user can read it:

    sudo install -o ilo-flowlink -g ilo-flowlink -m 640 /dev/null /etc/illumio-flowlink/api_info
sudo -u ilo-flowlink bash -c 'echo "api_xxxxxxxxxxxxxx yyy..." > /etc/illumio-flowlink/api_info'

  3. Enter the parameters. (See Flowlink Key-Value Parameters for details).

Example configuration

The following configuration listens for NetFlow on UDP 2055 from any data source. The absolute path is:

/etc/illumio-flowlink/config.yaml

Note

The org_id key-value pair is required in SaaS PCE instances. To find your org_id in the PCE UI, look in your profile by clicking or hovering over the profile icon in the upper right corner.

pce_addr: mypce.example.com:8443
org_id: 8675309
api_key: $cat /etc/illumio-flowlink/api_info
data_directory: /var/lib/illumio-flowlink/data
aggregation_minutes: 10
Destinations:
  - name: netflow
    parser:
      type: netflow
    connectors:
      - type: udp
        properties:
          ports: '2055'
Flowlink Key-Value Parameters

This table details the key-value parameters in Flowlink's YAML configuration file.

Parameter

Required/Optional

Description

pce_kafka

Note: This parameter applies only to Flowlink version 2.0.0 and later.

Optional

Allows you to stream flows to Azure Event Hub (instead of directly to the PCE) for use in Insights and Segmentation, and to configure the parameters included in flow headers.

Note

Applies to Flowlink 2.0.0 and later: If you are configuring Flowlink as part of an integration with the PCE and Armis, make sure to add the following to your Flowlink YAML file at the root level:

  • pce_kafka:

    • installation_id: armis-site

For details, see About the Illumio and Netflow/sFlow Integration.

aggregation_minutes

Optional

The interval (in minutes) in which flows are aggregated and sent to the PCE.

  • Default interval: 10

  • Minimum allowed interval: 5

  • Maximum allowed interval: 60

For example:

aggregation_minutes: 10

api_key

Required

API key and secret of the PCE. This allows Flowlink to POST flows to the PCE. The API key and secret can be copied into a file. You can run a script to cat the contents of that file. In the example below, a file called api_info is created which contains the PCE API key and secret.

For example:

api_key: $cat /home/employee/api_info

Destinations

Required

A list of dictionaries. It requires a name, parser, and connector. Flowlink configuration supports one or many Destinations (flow types).

For more details about configuring the ingested flow types, see Ingested Flow Types.

data_directory

Required

The pathname of a directory where Flowlink can store any unsent data flow files or any restart information.

For example:

data_directory: /home/employee/

data_directory_size_mb

Optional

The maximum size (in Megabytes) of data that can be stored in the data directory before being pruned.

Default: 500

Minimum value: 100

For example:

data_directory_size_mb: 200

file_retention_hours

Optional

The maximum number of hours unsent data flow files will be stored before being pruned.

Default: 24

Minimum: 4

For example:

file_retention_hours: 8

metrics_print_seconds

Optional

The frequency (in seconds) at which the metrics information is printed.

Default: 60

Minimum: 15

For example:

metrics_print_seconds: 60

org_id

  • Required for SaaS

  • Optional for on-premises

The org id to which the flow data will be posted.

pce_addr

Required

FQDN of the PCE and port.

For example:

pce_addr: https://mypce.example.com:8443

STEP 5: Run Flowlink (for version 2.0.0+)

Important

This step applies to Flowlink version 2.0.0 or later. If you are deploying Flowlink pre-version 2.0.0, see STEP 5: Run Flowlink (pre-version 2.0.0) in Configure Flowlink.

There are three ways to manage the Flowlink service. Use the method that fits your situation.

Option 1 — Linux systemd (standard service management)

Use this on modern Linux systems that use systemd:

sudo systemctl start illumio-flowlink
  sudo systemctl stop illumio-flowlink
  sudo systemctl status illumio-flowlink
Option 2 — SysV-style service commands (alternative)

Use this on systems that use SysV init instead of systemd, or where the service command is preferred:

sudo service illumio-flowlink start
  sudo service illumio-flowlink stop
  sudo service illumio-flowlink status
Option 3 — Flowlink control utility (recommended for troubleshooting)

Use this as the preferred method when you need to view startup or runtime errors. Commands must be run as the ilo-flowlink service user:

sudo -u ilo-flowlink /usr/local/bin/illumio-flowlink-ctl start
  sudo -u ilo-flowlink /usr/local/bin/illumio-flowlink-ctl stop
  sudo -u ilo-flowlink /usr/local/bin/illumio-flowlink-ctl status

To run Flowlink in verbose debug mode, stop the service and restart it with verbose output enabled:

sudo -u ilo-flowlink /usr/local/bin/illumio-flowlink-ctl stop
  sudo -u ilo-flowlink /usr/local/bin/illumio-flowlink-ctl start -v

All Flowlink logs are in the /var/log/illumio-flowlink directory, including any archived logs.

Service Operation and Debugging

  • Edit the Flowlink configuration file before starting the service.

    sudo vi /etc/illumio-flowlink/config.yaml

    Warning

    You should not start Flowlink until the configuration file has been fully reviewed and updated for the target environment.

  • Manage the Flowlink service using standard Linux service management tools.

    sudo systemctl start illumio-flowlink
sudo systemctl stop illumio-flowlink
sudo systemctl status illumio-flowlink
        
    sudo service illumio-flowlink start
sudo service illumio-flowlink stop
sudo service illumio-flowlink status

  • Use the Flowlink control utility as the preferred method for managing the service and viewing startup or runtime errors.

    sudo -u ilo-flowlink /usr/local/bin/illumio-flowlink-ctl start
sudo -u ilo-flowlink /usr/local/bin/illumio-flowlink-ctl stop
sudo -u ilo-flowlink /usr/local/bin/illumio-flowlink-ctl status

  • To run Flowlink in verbose debug mode, stop the service and restart it with verbose output enabled.

    sudo -u ilo-flowlink /usr/local/bin/illumio-flowlink-ctl stop
sudo -u ilo-flowlink /usr/local/bin/illumio-flowlink-ctl start -v

    All Flowlink logs are in the /var/log/illumio-flowlink directory, including any archived logs.

Operational Notes

  • Flowlink runs under a dedicated non-root service account (ilo-flowlink) to reduce security risk.

  • Service-based operation ensures Flowlink automatically restarts after system reboots.

  • Debug mode should be used only for troubleshooting and should not remain enabled in production environments.