Docs

Install

Suggest Edits

☁️

To use NetoFuse modules deployed in the cloud as part of the Netography Fusion SaaS, add and configure them as Context Integrations. These instructions are only necessary if you want to deploy NetoFuse within your own environment. For more information, see About NetoFuse.

Deployment Options

NetoFuse is available as a container or Python package.

⚖️

Selecting a deployment option

Netography recommends deploying the container for most customers. Containers provide isolation that ensures NetoFuse will operate properly and simplifies the deployment process.

The Python package is available for advanced users and developers familiar with Python. This may be preferred if you are planning to modify existing NetoFuse modules, build new custom modules, or are unable to run a container.

Installing the NetoFuse Container

Using the Docker host setup script

This section provides step-by-step instructions on how to set up and run the NetoFuse container on a Docker host. The setup script simplifies the process of configuring and running the NetoFuse container. By default, it will write a docker run script to /usr/local/bin/netofuse that you can use to run NetoFuse commands.

Prerequisites

  • Docker installed on your host system.
  • The container image is built for the amd64 (x86-64) platform. It can also run on ARM platforms using the built-in emulation support in Docker (for Apple silicon Macs, for example).

Installation and Setup

  1. Download the NetoFuse Docker host setup script

https://neto-downloads.s3.amazonaws.com/netofuse/netofuse-docker-setup.sh

  1. Make the setup script executable

chmod +x netofuse-docker-setup.sh

  1. Run the setup script

Execute the setup script. With the default settings, you will need to execute it using sudo to write to system directories:

sudo netofuse-docker-setup.sh

The setup script will run the container and print the version of NetoFuse to indicate it is successfully working.

If you add the --currentdir option and run it in a directory you can write to (eg your home directory), sudo is not required as it will install all files relative to the current directory.

Advanced Setup Options

netofuse-docker-setup.sh command line options

The following command line options can be used when running the Docker host setup script:

  • --force: Overwrite existing files config and script files.
  • --debug: Adds set -x to the script to echo all the script output to stdout
  • --noconfig: Skip creating configuration files (will still create directories and write the run script).
  • --currentdir: Change settings to CONFIG_DIR=./netofuse/config, DATA_DIR=./netofuse/data, SCRIPT_PATH=./netofuse/bin/netofuse
  • --latest: Retrieve the version of the most recent container image released and use that version going forward
  • --checklatest : Print the version of the most recent release of the container image and exit
  • --upgrade : Update run script to use the most recent release of the container image

netofuse-docker-setup.shconfiguration settings

If you want to change any defaults, open the script in a text editor and update the variables at the top of the script:

  • TAG: The specific image tag to use (default: DOCKER_VERSION)
  • CONFIG_DIR: Docker host directory for configuration files (default:/etc/netofuse)
  • YAML_FILENAME: Configuration filename (default: netofuse.yml)
  • ENV_TEMPLATE_FILENAME: Environment settings template file (default: netofuse.env.template)
  • ENV_FILENAME: Environment settings file (default: .netofuse.env)
  • DATA_DIR: Docker host directory for data persistence (default:/var/netofuse)
  • SCRIPT_PATH: Path to the NetoFuse docker run script setup creates (default:usr/local/bin/netofuse)

Troubleshooting the setup script

  • Finding the problem: Re-run the setup script with the --debug option to see more details about where there may be an error. You may also need to add the --force option if it already saved at least one of the files.
  • Permission Issues: Ensure you have permissions for executing Docker commands and accessing necessary directories. If system directories are being used, ensure you are running the setup script with sudo.
  • Docker problems: Ensure Docker is properly running on your host and other containers can be pulled and run successfully. Docker must be running and accessible for the user logged in, not root. Even if you use sudo, the setup script will use your actual user to run Docker commands. Consult Docker's documentation for help with common issues.
  • Configuration Errors: Download a new copy of the setup script and try running it with the default settings. Isolate the configuration setting that created the problem by re-running the script with the --force option.

Upgrading to a new version of NetoFuse

Re-run the setup script, adding the --upgradecommand line option to rewrite only the netofuse run script to use the most recent release of the NetoFuse container image.

Alternatively, you can re-run the setup script, adding the --latest command line option to re-run the entire setup process using the most recent release of the NetoFuse container image. If you have not moved the existing files from a previous setup, you will also need to add --force to overwrite the existing files. Be careful not to overwrite files you have edited settings in already.

To see what the most recent release version is, you can run the setup script with the --checklatest command line option. This will retrieve and print the most recent release version and exit.

Using the Container - Technical Details

The Docker host setup script is simply a shortcut to a fully configured Docker host. You can use the technical details below to run the container without the setup script.

📘

Documentation is specific to Docker, but the container image is portable

For simplicity, all instructions in the NetoFuse documentation are specific to using Docker to pull and run the NetoFuse 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.

Container Image

The container image is hosted on Netography's public container registry at:

public.ecr.aws/netography/netofuse:DOCKER_VERSION

The most recent release of NetoFuse is always available using the latest tag:

public.ecr.aws/netography/netofuse:latest

Default configuration file

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

https://neto-downloads.s3.amazonaws.com/netofuse/netofuse.yml

Sample Docker run command

docker run --platform linux/amd64 \
-v /etc/netofuse:/app/netofuse/config \ 
-v /var/netofuse:/app/netofuse/data \
public.ecr.aws/netography/netofuse:DOCKER_VERSION \
--config /app/netofuse/config/netofuse.yml \  
--env /app/netofuse/config/.netofuse.env \
--dir /app/netofuse/data \
-v

Setting configuration in environment

NetoFuse uses a layered configuration that will read configuration from a YAML file, environment settings file, and the environment.

Run the container image with the command init --envfile /app/config/netofuse.env.template(assumes you have mounted a local volume to/app/netofuse/configwith the docker run -v option) to output the environment names and default values for all settings.

Copy the settings you want to set in the environment to the .netofuse.env file (or wherever you point to with the --env command line option for the container image. Or pass the environment variables directly to the container using -e with Docker run or equivalent.

See Configure for more details.

Installing Python Package

Prerequisites

Python 3.7 or higher is required.

Python Package

https://neto-downloads.s3.amazonaws.com/netofuse/netofuse-1.1.16.tar.gz

pip3 install https://neto-downloads.s3.amazonaws.com/netofuse/netofuse-1.1.16.tar.gz

SHA-256: c4e53146250306adca5570ab21cb275691f0685bab1f01f36c90aa73511a3c86 netofuse-1.1.16.tar.gz

Updated about 2 months ago