Typically, when the Formant agent is installed, it will create the following directories for use in data operations: /var/lib/formant and /usr/lib/formant.

This guide will teach you how to set custom directories for Formant agent data operations.

❗️

Changing these directories disables automatic updates to the Formant agent. After performing this procedure, your device will no longer update automatically, and you will have to to update the agent manually.

Only follow this guide if you must change these directories.

Step 1: Re-provision agent (required for existing devices)

Perform this step if you have already installed the Formant agent to your device and ingested data, and you want to maintain your device's identity in Formant after changing these directories.

Follow Steps 1 and 2 of Re-provisioning an agent to generate the re-provisioning script for your device, but do not run it yet. Proceed to Step 2.

Step 2: Run provided script

Start this process before installing the Formant agent to your device.

1. Copy and paste the following script to a new file on your device, and call it repackage-agent.sh:

#!/bin/bash

DOWNLOAD_DIR=/var/cache/apt/archives
REPACK_DIR=/tmp/formant-agent-repack


USR_DIR=$1
VAR_DIR=$2
DEB_PATH=$3


if [[ -z $USR_DIR ]] || [[ -z $VAR_DIR ]]; then
    echo "Please provide usr_dir and var_dir like /opt/formant/usr /opt/formant/var"
    echo "Usage: $0 <usr_dir> <var_dir>"
    exit 1;
fi
if [ "$USR_DIR" == "$VAR_DIR" ]; then
    echo "usr_dir and var_dir cannot be the same"
    exit 1
fi

## Main
if [ -z $DEB_PATH ]; then
    echo "No deb path provided, downloading latest formant-agent from apt"
    sudo apt update
    sudo apt install --download-only formant-agent
    # find the most recent formant agent in /var/cache/apt/archives/
    DEB_PATH=$(ls -t1 $DOWNLOAD_DIR/formant-agent* | head -1)
fi

if [ ! -f $DEB_PATH ]; then
    echo "Deb is missing at: $DEB_PATH"
    exit 1
fi

if [ -n $DEB_PATH ]; then
    echo "Re-packaging: $DEB_PATH ..."
    rm -rf $REPACK_DIR
    mkdir -p $REPACK_DIR

    CLEAN_USR_DIR=$REPACK_DIR/$(echo $USR_DIR |  sed 's#^/##g')
    ## we need fakeroot to preserve deb perms
    fakeroot sh -c "
        echo \"Unpacking ...\"
        dpkg-deb -R $DEB_PATH $REPACK_DIR
        echo \"Changing paths:\"
        echo \" - /usr/lib/formant -> $USR_DIR\"
        find $REPACK_DIR -type f -exec file --mime-type {} + | grep 'text' | cut -d ' ' -f1 | sed -E 's/://g' | xargs sed -i 's#/usr/lib/formant#$USR_DIR#g'
	echo \" - /var/lib/formant -> $VAR_DIR\"
	find $REPACK_DIR -type f -exec file --mime-type {} + | grep 'text' | cut -d ' ' -f1 | sed -E 's/://g' | xargs sed -i 's#/var/lib/formant#$VAR_DIR#g'
	echo \"Moving:\"
        echo \" - /usr/lib/formant -> $USR_DIR\"
        mkdir -p $CLEAN_USR_DIR
        mv $REPACK_DIR/usr/lib/formant/agent $CLEAN_USR_DIR/agent
        echo \"Re-packing ...\"
        dpkg-deb -b $REPACK_DIR ./formant-agent-repack.deb
    "
else
    echo "No formant-agent package found in $DOWNLOAD_DIR"
fi

2. Set the script to be executable via the following command:

chmod +x repackage-agent.sh

3. Execute the script with arguments for the new install locations, as follows:

./repackage-agent.sh usr_dir var_dir

📘

Your usr_dir and var_dir must be different directories.

Step 3: Create device (new devices)

Perform this step if you are installing the Formant agent to a new device.

If you generated a re-provisioning token in Step 1, skip this step and proceed to Step 4.

Follow Steps 1 and 2 of Getting Started: Create a device to generate a provisioning token:

Step 4: Install repackaged agent

Run the following set of commands to install the repackaged agent with custom directories:

# uninstall local agent
sudo apt remove formant-agent
# install repackaged agent
FORMANT_PROVISIONING_TOKEN=<provisioning token> sudo apt install ./formant-agent-repack.deb

Updating the agent

Once you have run this script, automatic agent updates will be disabled for your device. You will have to run this script again to manually update the Formant agent.

Resetting agent directories to default

To undo this configuration and reset agent directories to default:

1. Uninstall the Formant agent from your device via the following command:

sudo apt remove --purge formant-agent

2. Install the Formant agent as seen in Getting Started: Setting up your device.

👋

If you notice an issue with this page or need help, please reach out to us! Use the 'Did this page help you?' buttons below, or get in contact with our Customer Success team via the Intercom messenger in the bottom-right corner of this page, or at [email protected].