# Install NetoFlow (container)

Installing NetoFlow is part of the steps to [Ingest NetFlow/sFlow via the NetoFlow Connector](/ingest-network-traffic-logs/netflow-sflow/traffic-source-netoflow.md).

If you want to run the container without going through all the details and options, see: [🏁 Quickstart: Running the NetoFlow container](/netoflow-connector/quickstart.md).

## Deployment Options <a href="#deployment-options" id="deployment-options"></a>

NetoFlow is available as a Docker-compatible container or a Linux software package. To deploy the Linux software package, see: [Install NetoFlow (Linux package)](/netoflow-connector/install-linux.md).

### Supported Platforms <a href="#supported-platforms" id="supported-platforms"></a>

Docker-compatible **container** built for `linux/amd64`hosted on Netography's public container registry

The container can be run on other platforms using Docker's cross-platform compatibility (e.g. to run it locally on a Mac with Apple silicon). However, this has a significant performance impact, so it is not recommended for production deployments.

{% hint style="info" %}
**⚖️Selecting a deployment option**

Netography recommends deploying the container for most customers. Containers provide isolation that ensures NetoFlow will operate properly and simplifies the deployment process. The software package is best suited for organizations with a standard Linux build that meets your internal security and compliance requirements.
{% endhint %}

## Installing the NetoFlow Container <a href="#installing-the-netoflow-container" id="installing-the-netoflow-container"></a>

{% hint style="info" %}
**📘Documentation is specific to Docker, but the container image is portable**

For simplicity, all instructions in the NetoFlow documentation are specific to using Docker to pull and run the NetoFlow container. However, the container is portable across container orchestration systems. Follow the standard instructions for the container orchestration platform you are using to pull, configure, and execute in this case.
{% endhint %}

### Container Image <a href="#container-image" id="container-image"></a>

The container image is hosted on Netography's public container registry.

For a specific version:

`public.ecr.aws/netography/netoflow:VERSION_NUMBER`

For the most recently released version:

`public.ecr.aws/netography/netoflow:latest`

To get a listing of the available versions (tags) for this container image, go to:

<https://gallery.ecr.aws/netography/netoflow>

### Step 1. Pull the container image *(optional)* <a href="#step-1-pull-the-container-image-optional" id="step-1-pull-the-container-image-optional"></a>

*You don't need to pull the container image with **docker pull** unless you want to ensure it is downloaded or validate the container before running it.*

For a production deployment, you should use a specific version instead of `latest`. This ensures consistency and stability, as `latest` may change over time, while a versioned image guarantees the same environment across deployments.

### Step 2. Configure NetoFlow *(optional)* <a href="#step-2--configure-netoflow-optional" id="step-2--configure-netoflow-optional"></a>

*You can run NetoFlow with the default configuration, which should be sufficient for most deployments, and skip this step.*

NetoFlow uses a layered configuration that will read configuration from the `/etc/netoflow.conf` file, if it exists, and from environment variables next (environment variables take precedence).

Refer to [Configuring NetoFlow](https://docs.netography.com/netoflow-connector/configure) for details on configuration options.

#### Option A: Setting configuration in `netoflow.conf` <a href="#option-a-setting-configuration-in-netoflowconf" id="option-a-setting-configuration-in-netoflowconf"></a>

**1. Download the default configuration file: `netoflow.conf.example`**

The default configuration file for the latest version of NetoFlow is available at:

<https://neto-downloads.s3.amazonaws.com/netoflow/netoflow.conf.example>

To download:

`curl -O https://neto-downloads.s3.amazonaws.com/netoflow/netoflow.conf.example`

**2. Make a copy of the example conf file**

`cp netoflow.conf.example netoflow.conf`

**3. Modify `netoflow.conf`**

Edit configuration settings as appropriate. See [Configure NetoFlow](/netoflow-connector/configure.md) for more details on configuration settings.

**4. Map local `netoflow.conf` file to `/etc/netoflow.conf` in the container when running**

The `docker run` command provided in step 4 includes this argument to map the conf file into your container:

`--mount type=bind,source=$(pwd)/netoflow.conf,target=/etc/netoflow.conf $(pwd)/netoflow.conf:/etc/netoflow.conf`

#### Option B: Setting configuration in environment variables <a href="#option-b-setting-configuration-in-environment-variables" id="option-b-setting-configuration-in-environment-variables"></a>

{% hint style="danger" %}
**❗️You can not set the tees targets, flowfilter, or device sections in environment variables today**

These settings involve a list or array (ie multiple values), which is not parsed from environment variables today. If you are modifying these configuration settings, you must modify the `netoflow.conf` file.
{% endhint %}

**Environment variable naming convention**

Use this format for environment variables:\
`NETO__SECTION__KEY=value`

* `NETO` is the prefix for all configuration environment variables
* Replace `SECTION` with the configuration section name. This is the value in square brackets `[]` in the conf file above the setting. Valid section names are: `general, flow, syslog, api, sflow, tees, endpoint, proxy, filter, flowfilter, device`.
* Replace `KEY` with the name of the configuration setting.

{% hint style="info" %}
**ℹ️The separator used is two underscores \_\_. If you use one underscore \_ it won't work.**
{% endhint %}

**Environment variables mapping**

The correct environment variable names to set for each configuration item in the `netoflow.conf.example`file is shown below. You can copy these values into a local file`netoflow.env`, or pass these environment variables directly to the container when running it.

```
NETO__GENERAL__UDPBUFFER=1048576
NETO__GENERAL__STATSINTERVAL=60
NETO__GENERAL__FLUSHINTERVAL=5
NETO__GENERAL__FLUSHCOUNT=2000
NETO__GENERAL__RETRIES=5
NETO__GENERAL__RETRYINTERVAL=5
NETO__GENERAL__DUMPRECORDS=false
NETO__GENERAL__TEMPLATEDB="/var/tmp/netoflow.db"
NETO__GENERAL__DOWNSAMPLE=10
NETO__GENERAL__APIHOST="https://api-ingest.netography.com"
NETO__GENERAL__DEVICECREATIONURL="/api/v1/device"
NETO__GENERAL__AUDITHOST="https://api.netography.com"
NETO__GENERAL__AUDITURL="/api/v1/audit"
NETO__FLOW__LISTEN="0.0.0.0:2055"
NETO__FLOW__WORKERS=4
NETO__FLOW__QUEUE=100000
NETO__SYSLOG__LEVEL="info"
NETO__SYSLOG__SERVER="localhost:514"
NETO__API__ENABLED=true
NETO__API__PORT=8080
NETO__SFLOW__PAYLOAD=false
NETO__TEES__ENABLED=false
NETO__TEES__UPDATEINTERVAL=300
NETO__ENDPOINT__NETOSECRET=""
NETO__PROXY__ENABLED=false
NETO__PROXY__URL="http://10.0.0.1:3121"
NETO__FILTER__DEFAULT="allow"
NETO__FILTER__LOGDENY=false
```

**Use an env file containing your settings**

Use this `docker run` argument to read a file `netoflow.env` containing your environment variable settings (the complete `docker run` command to use is in step 4 below):

`--env-file netoflow.env`

**Set environment variables in the container when running**

Instead of using an env-file, you can individually pass each environment variable using the `-e` argument to `docker run` . Step 4 below contains examples of the complete `docker run` command to use.

`-e NETO__GENERAL__RETRIES=3 -e NETO__API__ENABLED=false`

If you have set these in your local environment:

`-e NETO__GENERAL__RETRIES=$NETO__GENERAL__RETRIES -e NETO__API__ENABLED=$NETO__API__ENABLED`

### Step 3. Create a Fusion API key <a href="#step-3--create-a-fusion-api-key" id="step-3--create-a-fusion-api-key"></a>

You will need to [Create a Netography API Key](https://docs.netography.com/settings/user-management/index/add-api-key) in the Fusion Portal, using the `neto_flow`role.

**Using a secrets vault is the most secure approach for storing this secret**

For production deployments, you should store this value in a secrets vault and pass it to the `NETO__ENDPOINT__NETOSECRET` environment variable for your container.

**Setting the secret in your local environment**

You can also set it to a local environment variable and then pass it to your running container.

```
NETOSECRET="REPLACEME"
export NETOSECRET
```

In your `docker run` command, pass this to the container environment using `-e NETO__ENDPOINT__NETOSECRET=$NETOSECRET`

**Setting the secret in the `/etc/netoflow.conf` file**

If you are running the container on a local system or for testing purposes, you can also set the netosecret value in the `/etc/netoflow.conf` file, in the `[endpoint]` section:

{% tabs %}
{% tab title="Shell" %}

```
[endpoint]
netosecret       = ""  # API key encoded as netosecret
```

{% endtab %}
{% endtabs %}

### Step 4. Run the container <a href="#step-4-run-the-container" id="step-4-run-the-container"></a>

The following configuration options are commonly used when running the container with `docker run`:

* `-p 2055:2055` - This maps the default port netoflow listens for NetFlow and sFlow from your container to your host so you can direct netflow to the host IP.
* `-p 8080:8080` - This maps the default port netoflow hosts the statistics API on for retrieving stats from netoflow. If you do not need anyone outside your host to access these statistics, you can omit this.
* `-e NETO__ENDPOINT__NETOSECRET=$NETOSECRET` - Assuming you have set the netosecret API secret on your host in the `NETOSECRET` environment variable, this will pass that value to the configuration setting it is read from by netoflow.
* `--mount type=bind,source=$(pwd)/netoflow.conf,target=/etc/netoflow.conf` - If you have modified the `netoflow.conf` file on your host, this will map that file in your current working directory to `/etc/netoflow.conf` in the container where it will be read for configuration.
* `--platform linux/amd64` - This can be used to run the container on non-x86 systems (eg to test it locally on a Mac with Apple silicon). Using platform emulation in Docker can significantly impact performance, so this is not recommended for production usage.
* `--name netoflow`- Gives the container a more easily accessible name. If you are initially configuring `netoflow`, you need to remove the container using `docker rm netoflow` after it exits before re-running it, or you can add the `--rm` argument to your docker run to have it automatically removed after it exits.
* `-e NETO__SECTION__KEY=value` - Sets the environment variable to a value, for passing individual configuration settings to the container via environment variables.
* `--env-file netoflow.conf` - Reads all the environment variables in the file `netoflow.conf` and sets them in the container.

#### `docker run` example: default configuration, pass secret from host `NETOSECRET` environment variable <a href="#docker-run-example-default-configuration-pass-secret-from-host-netosecret-environment-variable" id="docker-run-example-default-configuration-pass-secret-from-host-netosecret-environment-variable"></a>

```
docker run -e NETO__ENDPOINT__NETOSECRET="$NETOSECRET" \
  -p 2055:2055 -p 8080:8080 \
  --name netoflow \
  --platform linux/amd64 \
  public.ecr.aws/netography/netoflow:latest
```

#### `docker run` example: use `netoflow.conf` in current dir on host, pass secret from host `NETOSECRET` environment variable <a href="#docker-run-example--use--netoflowconf-in-current-dir-on-host-pass-secret-from-host-netosecret-enviro" id="docker-run-example--use--netoflowconf-in-current-dir-on-host-pass-secret-from-host-netosecret-enviro"></a>

```
docker run -e NETO__ENDPOINT__NETOSECRET="$NETOSECRET" \
  -p 2055:2055 -p 8080:8080 \
  --platform linux/amd64 \
  --name netoflow \
  --mount type=bind,source=$(pwd)/netoflow.conf,target=/etc/netoflow.conf \
  public.ecr.aws/netography/netoflow:latest
```

#### `docker run` example: all configuration is set in `netoflow.env` in your local directory <a href="#docker-run-example-all-configuration-is-set-in-netoflowenv-in-your-local-directory" id="docker-run-example-all-configuration-is-set-in-netoflowenv-in-your-local-directory"></a>

```
docker run \
  -p 2055:2055 -p 8080:8080 \
  --platform linux/amd64 \
  --name netoflow \
  --env-file netoflow.conf
  public.ecr.aws/netography/netoflow:latest
```


---

# 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.fusion.vectra.ai/netoflow-connector/install-container.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.