Impinj® ItemSense™ Installation Guide

This document describes the installation procedure for the Impinj® ItemSense™ software platform.

Table of Contents

Introduction

The ItemSense software is provided as an archive file format for customers who are installing the software within their company managed network. In this archive file there are a number of files, but the primary components of ItemSense are delivered as a series of docker containers. This part of the document describes the process for installing ItemSense using the archive file.

Installing an ItemSense docker container instance is a two-step process:

  • The ItemSense archive file is copied onto the chosen server
  • The ItemSense installation script is run, which will automatically start ItemSense.

Note that this guide assumes a good grasp of the Linux command line.

Prerequisites

Before starting the ItemSense installation process, the following steps must be completed:

  • An ItemSense Instance ID must be requested from your Impinj representative
  • Upon receipt of your ItemSense Instance ID, download the ItemSense archive file from the link in the welcome email
  • The server onto which ItemSense will be installed should be prepared with the following:
    • Docker supported Linux OS installed with the latest kernel update for that distribution
    • Version 1.12 or higher of the docker tool should be installed
    • Version 1.8 or higher of the docker-compose tool should be installed
  • Ensure that all of the RAIN RFID readers are configured with an NTP server. See Clock Synchronization and NTP Configuration for more details.
  • Ensure that the $HOME directory environment variable is set, and points to the home directory of the user performing the installation

Instructions for installing docker can be found here and instructions for installing Docker Compose can be found here.

Install ItemSense on Ubuntu

The following instructions were written for installing ItemSense onto the Ubuntu Linux distribution. It is possible to install ItemSense on a number of distributions of Linux. While many of the commands should work when installing ItemSense on a Linux distribution other than Ubuntu, it may be necessary to modify the commands slightly for your distribution.

Pre-checks

Run the following commands in a terminal on the target server to confirm if the server is in the correct state to begin installation:

  1. Check that nothing is listening on port 80, 3010, 443 or 5672.

    For example, this command should not show any output:

    sudo netstat -tlnp | grep ':80\W\|:3010\W\|:443\W\|:5672\W'

  2. If this is a clean install and not an upgrade from an earlier ItemSense version, check that no previous docker images already exist.

    sudo docker images isreg/*

    If this command shows some ItemSense docker images already exist, follow the uninstall instructions below to remove them

  3. Check that docker is installed and is at the version specified in the prerequisites:

    docker -v

    Example output:

    Docker version 1.12.1, build 23cf638
    
  4. Check that docker-compose is installed and is at the version specified in the prerequisites:

    docker-compose -v

    Example output:

    docker-compose version 1.8.0, build 94f7016
    
  5. Check your kernel version is the latest recommend for your OS release. To see kernel version run:

    uname -r

    Example output:

    4.4.0-45-generic
    

Installation Instructions

To install ItemSense 2017r1, you will need to have already downloaded the archive file. This file will be named similar to the following: is.IT-BTIC-BUT.0.1.XX.tar.bz2 As the file is roughly 1.3Gb it may take a while to download, depending on your connection.

When the archive file has been obtained:

  1. Put the file on to the target server.

    scp is.IT-BTIC-BUT.0.1.XX.tar.bz2 USERNAME@TARGET_SERVER:.

    Where:

    • USERNAME should be replaced with the user on the target server.
    • TARGET_SERVER should be replaced with the hostname or IP address of the server on which you intend to install ItemSense.
  2. When the file has complete transferring to the target server, log on to the target server and navigate to the location where you copied the file. If you followed the command above, the file will be in the home directory of the user used to transfer the file on to the target server. Note: No matter where you extract the archive file to, ItemSense will always be installed to the home directory pointed to by the environment variable $HOME.

  3. From the same directory as the ItemSense archive file run the following to extract the archives contents:

    tar -xvjf is.IT-BTIC-BUT.0.1.XX.tar.bz2

    Example output:

    ./tarfile/
    ./tarfile/firmware/
    ./tarfile/firmware/firmware_speedway/
    ./tarfile/firmware/firmware_speedway/octane-5.8.1.240.upg
    ./tarfile/firmware/firmware_speedway_versions.json
    ./tarfile/firmware/cap_itemsense/
    ./tarfile/firmware/cap_itemsense/ii-cap-0.0.1.15-296.upg
    ./tarfile/firmware/cap_itemsense_versions.json
    ./tarfile/install_is_containers.sh
    ./tarfile/images/
    ./tarfile/images/is-mariadb.tar
    ./tarfile/images/is-container.tar
    ./tarfile/itemsense-prod-1.6.0.yml
    

    Note: this can take up to 2 minutes to complete, particularly the extraction of the is-container.tar file.

  4. Check that the file has extracted correctly:

    ls tarfile

    Output:

    firmware  images  install_is_containers.sh  itemsense-prod-1.6.0.yml
    
  5. Enter the tarfile directory:

    cd tarfile

  6. Run the installer script with the argument "install" or "upgrade" depending on the type of installation you are performing. Note: this script should be run either as the root user or with sudo. If run as the root user ItemSense will be installed in the root user's home directory (typically /root).

    sudo bash ./install_is_containers.sh install

    Example output:

    INFO: Installing/Upgrading Itemsense
    INFO: Unable to locate previously supported version of ItemSense. Performing new install under /home/is_support.
    INFO: Installing new files
    INFO: Unpacking docker container images
    fe4c16cbf7a4: Loading layer [==================================================>] 128.9 MB/128.9 MB
    f1621398948b: Loading layer [==================================================>] 344.6 kB/344.6 kB
    6ebad06b3e49: Loading layer [==================================================>]  4.32 MB/4.32 MB
    1bc74a039df4: Loading layer [==================================================>] 1.536 kB/1.536 kB
    3310797b3a3e: Loading layer [==================================================>] 14.77 MB/14.77 MB
    9b57cb0de8c4: Loading layer [==================================================>] 44.03 kB/44.03 kB
    9bb3d5b8bde2: Loading layer [==================================================>]  5.12 kB/5.12 kB
    7702d916a821: Loading layer [==================================================>]  5.12 kB/5.12 kB
    4718e4c50ba4: Loading layer [==================================================>] 200.4 MB/200.4 MB
    23ff69eb2af2: Loading layer [==================================================>] 8.192 kB/8.192 kB
    c6080284fae2: Loading layer [==================================================>] 7.168 kB/7.168 kB
    78535633caa2: Loading layer [==================================================>] 1.536 kB/1.536 kB
    db4a198f9fa3: Loading layer [==================================================>] 3.584 kB/3.584 kB
    9dfe48bfe0b2: Loading layer [==================================================>]  7.68 kB/7.68 kB
    Loaded image: isreg/is-mariadb:10.0.28
    6650225473f3: Loading layer [==================================================>] 197.2 MB/197.2 MB
    724e9db35fe0: Loading layer [==================================================>] 208.9 kB/208.9 kB
    3973e2de72ae: Loading layer [==================================================>] 4.608 kB/4.608 kB
    5f70bf18a086: Loading layer [==================================================>] 1.024 kB/1.024 kB
    0cd01e86530e: Loading layer [==================================================>] 56.32 kB/56.32 kB
    1ef215608c77: Loading layer [==================================================>]   123 MB/123 MB
    ebe3fd02e7e0: Loading layer [==================================================>] 107.5 kB/107.5 kB
    416f17772e10: Loading layer [==================================================>] 1.294 GB/1.294 GB
    4a25411a26ad: Loading layer [==================================================>] 3.072 kB/3.072 kB
    47d6276e098a: Loading layer [==================================================>] 3.072 kB/3.072 kB
    5cf819b5200c: Loading layer [==================================================>] 3.072 kB/3.072 kB
    8a6bad46e220: Loading layer [==================================================>] 3.072 kB/3.072 kB
    ee83b3cb399c: Loading layer [==================================================>] 3.072 kB/3.072 kB
    c1f406273bff: Loading layer [==================================================>] 3.072 kB/3.072 kB
    20f1f7e7d0eb: Loading layer [==================================================>] 4.608 kB/4.608 kB
    525ec7957f2f: Loading layer [==================================================>] 4.608 kB/4.608 kB
    e2367a8885bc: Loading layer [==================================================>] 6.656 kB/6.656 kB
    aee632822548: Loading layer [==================================================>] 6.656 kB/6.656 kB
    bad25e87ab04: Loading layer [==================================================>] 163.4 MB/163.4 MB
    1fc3e5a5aed7: Loading layer [==================================================>] 227.5 MB/227.5 MB
    4f26b41745e0: Loading layer [==================================================>] 623.2 MB/623.2 MB
    Loaded image: isreg/itemsense:develop-16f25
    INFO: Firmware images
    INFO: Start the new docker compose file
    Creating network "is_support_default" with the default driver
    Creating is_support_itemsense_1
    Creating is_support_is-db_1
    INFO: Installation complete
    
  7. After the installation script finishes, remove the tarfile directory but keep the ItemSense archive file. If you want to uninstall ItemSense via the automated process, you will need the installation script, which is contained in the archive file.

  8. In a browser, navigate to the IMC using the server IP address or host name and port 3010:

    http://serverIP:3010/

    Note: after ItemSense starts it can take a minute or so before the IMC will be available

Upgrade ItemSense

Upgrade from 2016r6 to 2017r1 using separate hosts

These instructions stand up a separate instance of ItemSense and run a migration script to copy over configuration. This is the preferred method for upgrading ItemSense as it minimizes the chances of errors.

Note: Historical item, health, and job data will be lost using this upgrade method. If you need to retain your historical item data across the upgrade, then please follow the instructions for installation on the same host.

Prerequisites

  • ItemSense 2016r6 Build 174 has been installed and is up and running
  • ItemSense 2017r1 has been installed (according to the installation steps above) and is up and running
  • node.js version 6.9.4 or later has been installed (go to https://nodejs.org/en/download/ to download and install it)

Instructions

  1. Install the is-tool version 0.3.0 Node package on any host that has network access to the 2016r6 instance of ItemSense.

    npm install -g is-tool@0.3.0

    The is-tool has its own set of documentation and prerequisites that can be found here: https://www.npmjs.com/package/is-tool

  2. Save the configuration from the 2016r6 instance. The is-tool saves the configuration in the file specified by filename. If you do not specify a filename, the is-tool generates one. The SERVER_2016r6 value must be replaced with the hostname or the IP address of the server on which ItemSense 2016r6 is installed.

    is-tool save -i SERVER_2016r6 -u admin -p admindefault <filename>

  3. Install the latest version of the is-tool Node package on any host that has network access to the 2017r1 instance of ItemSense.

    npm install -g is-tool

    Note: ItemSense 2016r6 and earlier require is-tool version 0.3.0, whereas ItemSense 2017r1 requires the latest version of is-tool.

  4. Load the saved 2016r6 configuration to the 2017r1 instance. The SERVER_2017r1 value must be replaced with the hostname or IP address of the server on which ItemSense 2017r1 is installed.

    is-tool load <filename> -i SERVER_2017r1 -u admin -p admindefault

    Example output:

    Reading my-saved-2016r6-configuration
    Loading configuration...
    Loading facilities
    Loading readerDefinitions
    Loading readerConfigurations
    Loading recipes
    Loading zoneMaps
    Loading users
    
  5. At this point all configuration has been migrated to the 2017r1 instance but the readers are still provisioned against the 2016r6 instance. You will need to go through the provisioning flow to associate the defined readers with the new 2017r1 instance.

    • Add a network
      • Find a network to add by looking at the Address field of a reader definition
      • Go to the Scanner Configuration page of the IMC: (three dots in upper right)→Admin→Scanner config
    • Register readers
      • readers→scanner→discover readers
      • Select only the readers flagged with the triangle exclamation point
      • Click on "REGISTER SELECTED READERS"
    • Upgrade reader firmware
      • (three dots in upper right)→Admin and then selected the "SOFTWARE UPDATES" tab
      • Select "Reader Firmware" under "Software to Install"
      • Select your set of readers to update
      • Click "START INSTALLATION"
    • Now the readers are registered and upgraded and you can start running jobs.

Upgrade from 2016r6 to 2017r1 on the same host

This installs the new release of ItemSense over an existing instance. This is a riskier procedure but does have the advantage of allowing you to retain item, health and job data. If retaining historical data is not a concern for you then please follow the instructions for an upgrade using separate hosts.

Prerequisites

  • ItemSense 2016r6 Build 174 has been installed and is up and running
  • ItemSense is running on TARGET_SERVER
  • node.js version 6.9.4 or later has been installed (go to https://nodejs.org/en/download/ to download and install it)

Instructions

  1. (Optional) As a precaution in case the upgrade fails, backup your configuration and database.

    1. Install the is-tool version 0.3.0 Node package. This tool can be installed on any host that has network access to the ItemSense host.

      npm install -g is-tool@0.3.0

      The is-tool has its own set of documentation and prerequisites that can be found here: https://www.npmjs.com/package/is-tool

    2. Save the configuration from the 2016r6 instance. The is-tool saves the configuration in the file specified by filename. If you do not specify a filename, the is-tool generates one.

      is-tool save -i TARGET_SERVER -u admin -p admindefault <filename>

    3. Back up the ItemSense database. All the database configuration is stored in: <ItemSense home folder>/containers/is-db/var/lib/mysql

      sudo cp -r ~/containers/is-db ~/IS_DB_BACKUP

  2. Take note of the registered networks for scanning, as these won't be migrated.

    • Go to the Scanner Configuration page of the IMC: (three dots in upper right)→Admin→Scanner config
    • Write down any networks you want to move over
  3. Copy the ItemSense 2017r1 installation binary on to the ItemSense host:

    scp is.IT-BTIC-BUT.0.1.XX.tar.bz2 USERNAME@TARGET_SERVER:.

    Where:

    • USERNAME should be replaced with the user on the target server.
    • TARGET_SERVER should be replaced with the hostname or IP address of the server on which ItemSense is installed
  4. When the file has complete transferring to the target server, log on to the target server and navigate to the location where you copied the file. If you followed the command above, the file will be in the home directory of the user used to transfer the file on to the target server.

  5. Create a new directory for the ItemSense 2017r1 binary e.g. upgrade:

    mkdir upgrade

  6. Copy the 2017r1 installation binary into this directory:

    cp s.IT-BTIC-BUT.0.1.XX.tar.bz2 upgrade

  7. Enter the new directory:

    cd upgrade

  8. Run the following to extract the archives contents:

    tar -xvjf is.IT-BTIC-BUT.0.1.XX.tar.bz2

    Example output:

    ./tarfile/
    ./tarfile/firmware/
    ./tarfile/firmware/firmware_speedway/
    ./tarfile/firmware/firmware_speedway/octane-5.8.1.240.upg
    ./tarfile/firmware/firmware_speedway_versions.json
    ./tarfile/firmware/cap_itemsense/
    ./tarfile/firmware/cap_itemsense/ii-cap-0.0.1.15-296.upg
    ./tarfile/firmware/cap_itemsense_versions.json
    ./tarfile/install_is_containers.sh
    ./tarfile/images/
    ./tarfile/images/is-mariadb.tar
    ./tarfile/images/is-container.tar
    ./tarfile/itemsense-prod-1.6.0.yml
    

    Note: this can take up to 2 minutes to complete, particularly the extraction of the is-container.tar file.

  9. Check that the file has extracted correctly:

    ls tarfile

    Example output:

    firmware  images  install_is_containers.sh  itemsense-prod-1.6.0.yml
    
  10. Enter the tarfile directory:

    cd tarfile

  11. Upgrade the existing docker containers using the 2017r1 install script:

    Note: the --force flag must be present on this command. If you fail to specify the --force flag and the upgrade fails, then re-running the upgrade with --force will not recover the upgrade, and you must uninstall the previous installation, and re-install the new one.

    sudo ./install_is_containers.sh upgrade --force

    Example output:

    INFO: Checking for existence of cat...Found
    INFO: Checking for existence of exit...Found
    INFO: Checking for existence of curl...Found
    INFO: Checking for existence of grep...Found
    INFO: Checking for existence of cd...Found
    INFO: Checking for existence of pwd...Found
    INFO: Checking for existence of mkdir...Found
    INFO: Checking for existence of mv...Found
    INFO: Checking for existence of cp...Found
    INFO: Checking for existence of chmod...Found
    INFO: Checking for existence of sleep...Found
    INFO: Checking for existence of rm...Found
    INFO: Checking for existence of sed...Found
    Ready to proceed (y/n)? y
    INFO: Upgrading Itemsense
    INFO: Found existing 2016r6 installation
    INFO: Stopping and removing previous installation
    Stopping itemsense_itemsense_1 ... done
    Stopping itemsense_is-db_1 ... done
    Removing itemsense_itemsense_1 ... done
    Removing itemsense_is-db_1 ... done
    Removing network itemsense_default
    
    ...
    
    INFO: 20: Sending query to imc endpoint
    INFO: ...Found imc endpoint
    INFO: install_is_containers.sh complete
    
  12. At this point all configuration has been migrated to the 2017r1 instance but the readers are still provisioned against the 2016r1 instance. You will need to go through the provisioning flow to associate the defined readers with the new 2017r1 instance.

    • Add a network
      • Add the networks made note of earlier
      • Go to the Scanner Configuration page of the IMC: (three dots in upper right)→Admin→Scanner config
    • Register readers
      • Readers→Scanner→Discover Readers
      • Select only the readers flagged with the triangle exclamation point
      • Click on "REGISTER SELECTED READERS"
      • Note: readers that have been secured with credentials other than the default must have their credentials supplied first. If there are multiple readers with non-default credentials, then they must be re-provisioned individually, or temporarily re-configured to use the default credentials (refer to the Troubleshooting Guide)
    • Upgrade reader firmware
      • (three dots in upper right)→Admin and then selected the "SOFTWARE UPDATES" tab
      • Select "Reader Firmware" under "Software to Install"
      • Select your set of readers to update
      • Click "START INSTALLATION"
    • Now the readers are registered and upgraded and you can start running jobs.
  13. If the upgrade was successful, cleanup the backups created:

    sudo rm -rf ~/IS_DB_BACKUP

    rm is-save*

Upgrade from 2016r4 to 2016r6

Prerequisites

  • Impinj Support (support@impinj.com) has provided the ItemSense key file
  • node.js version 6.9.4 or later has been installed (go to https://nodejs.org/en/download/ to download and install it)

Backup data

  1. After you have logged in, ensure you are in the ItemSense base directory. This is where the ItemSense YAML itemsense-prod-1.6.0.yml is located.

  2. Stop ItemSense.

    sudo docker-compose -f itemsense-prod-1.6.0.yml down

    Example output:

    Stopping issupport_ItemSense_1 ... done
    Removing issupport_ItemSense_1 ... done
    
  3. Copy the entire /home/is_support/containers/itemsense/var/lib/mysql folder to a remote host. There is not enough space on the VM to store the item data backups there.

  4. Restart ItemSense.

    sudo docker-compose -f itemsense-prod-1.6.0.yml up -d

    Example output:

    Starting issupport_ItemSense_1
    

Backup configuration

  1. Install the is-tool version 0.3.0 Node package on any host that has network access to the ItemSense instance.

    npm install -g is-tool@0.3.0

    The is-tool has its own set of documentation and prerequisites that can be found here: https://www.npmjs.com/package/is-tool

  2. Save the configuration from the 2016r4 instance. The is-tool saves the configuration in the file specified by filename. If you do not specify a filename, the is-tool generates one.

    is-tool save -i TARGET_SERVER -u admin -p admindefault <filename>

Installation

  1. Place the ItemSense key file in your ~/.ssh/ directory, where ~ is the home directory of the user performing the upgrade.

  2. Copy the installation archive to the ItemSense server:

    scp -i ~/.ssh/is_support1215_rsa is.IT-BTIC-BUT.0.1.93.tar.bz2 is_support@TARGET_SERVER:.

  3. Continue from step 2 of the Install Instructions section above.

Migrate data

  1. Convert your 2016r4 configuration data to 2016r6 format:

    is-tool convert <filename>

    The output file containing the converted configuration is placed in the same location as the input file except that its name has "-converted" appended to it.

  2. Load the converted configuration into the upgraded ItemSense server:

    is-tool load -i TARGET_SERVER <filename of converted configuration>

Uninstall ItemSense Via Automated Process

To uninstall ItemSense via the automated process, follow these steps:

  1. Go to the directory where you put the ItemSense archive file. From this directory, change to the tarfile directory.

    Note: This automated process uses the install_is_containers.sh installation script, which is located in the tarfile directory. If you removed the tarfile directory after you installed ItemSense, re-extract the archive contents to get the tarfile directory back:

    tar -xvjf is.IT-BTIC_BUT.0.1.XX.tar.bz2

  2. Determine whether the script supports the remove subcommand by running the installation script with the the -h option:

    sudo ./install_is_containers.sh -h

    The -h option displays information about the installation script. If remove is listed as a possible subcommand, it is supported and you can go to the next step; otherwise, you must manually uninstall ItemSense.

  3. Do one of the following steps to remove all or part of an ItemSense installation:

    • Run the installation script with the remove subcommand and -p option to remove the ItemSense software and all configuration and data files:

      sudo ./install_is_containers.sh remove -p

    • Run the installation script with the remove subcommand, omitting the -p option, to remove only the ItemSense software:

      sudo ./install_is_containers.sh remove

Uninstall ItemSense Via Manual Process

To manually uninstall ItemSense, follow these steps:

  1. Ensure that it is not running:

    sudo docker ps

    If you see two containers listed like the following:

    CONTAINER ID        IMAGE                           COMMAND                  CREATED             STATUS PORTS                                                                                                                                            NAMES
    fcfaa6ae9323        isreg/is-mariadb:10.0.28        "docker-entrypoint.sh"   2 minutes ago       Up 2 minutes        3306/tcp                                                                                                                                         is_support_is-db_1
    1f9c1ad9a0ea        isreg/itemsense:develop-cbbdf   "/sbin/my_init"          2 minutes ago       Up 2 minutes        0.0.0.0:80->80/tcp, 0.0.0.0:443->443/tcp, 4369/tcp, 0.0.0.0:3010->3010/tcp, 5671/tcp, 0.0.0.0:5672->5672/tcp, 25672/tcp, 0.0.0.0:161->5161/udp   is_support_itemsense_1
    

    Then navigate to the installation directory of ItemSense (which is your install user's home directory where the itemsense-prod-1.6.0.yml file is located) and run:

    sudo docker-compose -f itemsense-prod-1.6.0.yml down

    Example output:

    Stopping is_support_is-db_1 ... done
    Stopping is_support_itemsense_1 ... done
    Removing is_support_is-db_1 ... done
    Removing is_support_itemsense_1 ... done
    Removing network is_support_default
    
  2. Check that nothing is listening on port 80, 3010, 443 or 5672.

    For example, this command should not show any output:

    sudo netstat -tlnp | grep ':80\W\|:3010\W\|:443\W\|:5672\W'

  3. Remove the containers directory and the itemsense-prod-1.6.0.yml file from the installation directory.

    sudo rm -rf containers/ itemsense-prod-1.6.0.yml

  4. Find the ItemSense docker image

    sudo docker images isreg/*

    Example output:

    REPOSITORY          TAG                 IMAGE ID            CREATED             SIZE
    isreg/itemsense     develop-cbbdf       1d19344ef59a        4 days ago          2.474 GB
    isreg/is-mariadb    10.0.28             9624719527fa        5 days ago          340.1 MB
    
  5. Remove the ItemSense docker images.

    sudo docker rmi IMAGEID

    Where IMAGEID is the IMAGE ID listed in your output for step 4 above. Example output:

    Untagged: isreg/is-mariadb:10.0.26
    Deleted: sha256:a508035a211d57375900f72245b393bffddbe2872137882e89ca9da2122b19bc
    Deleted: sha256:3072cba1a714165df54ed726529c4a2e0b404468ec8fa38ac5061c8e85079f40
    Deleted: sha256:efb58d19e00aeb18010fb9601c5f62f09cf610419476daaaed06ee9beae0470e
    Deleted: sha256:efabfc431d66b9b0a7859801c6dd2f7ba605641c7d05d34a43ec17f828873897
    Deleted: sha256:9ec14a42a06dfd7850171fb132321ecff0127d01301558bd600a1cd3125ee4df
    Deleted: sha256:3e0c9f3e156f9023da43a81a3895be481aaf033276f89ea43e38636b198ad1de
    Deleted: sha256:999296679db0f300dc45049abd06b5fb2fa36e9bf2bc6e36a41ac1113f20769b
    Deleted: sha256:c4ab196dba32b87c738314772804c0ec7de555813569eb9003c011a95b484960
    Deleted: sha256:9f97ab89b9ab488e27508fd6aa77b2708cff70e951b9b722f4829b9e4d04b4d3
    Deleted: sha256:a84d248cd3348a36c71d1225af4cc665e7df9e4942b65c20908d2d7503b5eb9e
    Deleted: sha256:aeb73b812583e391c7fe4c9c3eb844a5caa92ec279efc75e59b0fddb42e0d496
    Deleted: sha256:c541a7d71d798e2324344f2835d45516e5175d2ba328982e222f39d1df0f1bdf
    Deleted: sha256:eba5b35e8997700eef3477910f12fcad1785e546007c15522520f09a1a4abd08
    Deleted: sha256:247b8d8b7534f9957c42f44dcc2c53303baa1715be93d76d495543d747f895a3
    Deleted: sha256:2f71b45e4e254ddceb187b1467f5471f0e14d7124ac2dd7fdd7ddbc76e13f0e5
    

Change Default Network Address

Once ItemSense has been installed, it is possible to change its container network configuration. By default, all networks created by the docker engine will have an address range allocated to it within the 172.16.0.0/20 address range. The containers assigned to the first (and default) network created (called docker0 traditionally) will have addresses in the range 172.17.0.0/16. Containers assigned to the next network will have addresses in the range of 172.18.0.0/16. And so on. Any address in the range 172.16.0.0/20 might be problematic for a particular installation as it may cause conflicts with existing addresses within a private network occupying the same range.

However, it is possible to modify the address range used to hand out IP addresses to containers. To do this:

  1. Log into the host in which ItemSense is installed.

  2. Change to a user with 'sudo' privileges. Example:

    su - is_support

  3. Edit the docker-compose configuration file in the ItemSense home directory. Typically, this is the home directory of the user used when installing ItemSense. This should be done as a sudo user. Example command:

    sudo vi /home/is_support/itemsense-prod-1.6.0.yml
    
  4. Navigate to the bottom of the file and enter:

    networks:
      default:
        ipam:
          config:
            - subnet: IP_ADDRESS_RANGE
              gateway: IP_ADDRESS_GATEWAY
    

    Where:

    • IP_ADDRESS_RANGE is the range of the addresses which should be handed out to the docker managed networks. Example: 192.168.111/24
    • IP_ADDRESS_GATEWAY is the the name of the gateway address of the ranges. Typically, this is the first IP address in a network range. Example: 192.169.111.1
  5. Save the docker-compose configuration file.

  6. Now restart the containers:

    docker-compose -f itemsense-prod-1.6.0.yml down

    docker-compose -f itemsense-prod-1.6.0.yml up -d

  7. Ensure the containers restarted with an IPv4 address from the new range:

    docker network inspect issupport_default

    Example output:

    $ 00:15:02 > docker network inspect issupport_default
    [
        {
            "Name": "issupport_default",
            "Id": "c26013dcdedd1f1dd3ccc3f8d97d2c6f888733e910df0eddb32251b5eb7796ba",
            "Scope": "local",
            "Driver": "bridge",
            "EnableIPv6": false,
            "IPAM": {
                "Driver": "default",
                "Options": null,
                "Config": [
                    {
                        "Subnet": "192.168.111.0/24",
                        "Gateway": "192.168.111.1"
                    }
                ]
            },
            "Internal": false,
            "Containers": {
                "3f5a6ba0b23cd0323d8776d31a6814469c5a316065c427324e48cf8beb90ff4c": {
                    "Name": "issupport_itemsense_1",
                    "EndpointID": "246f72defdf364e571a41d8f20e24cd6735f531c85a7798a300635f3e7c2a893",
                    "MacAddress": "02:42:c0:a8:6f:03",
                    "IPv4Address": "192.168.111.3/24",
                    "IPv6Address": ""
                },
                "6d0a04a191a48d68876e8cbb02a4be2b989f69c4f7882c4f2fe529e487e09243": {
                    "Name": "issupport_is-db_1",
                    "EndpointID": "6fc529ff7abb0624e0c402fd7b7a2ecc53c66e80b3cfe9b79f3468e004a87f93",
                    "MacAddress": "02:42:c0:a8:6f:02",
                    "IPv4Address": "192.168.111.2/24",
                    "IPv6Address": ""
                }
            },
            "Options": {},
            "Labels": {}
        }
    ]
    

Note: Any changes you make to the docker-compose configuration file (itemsense-prod-x.x.x.yml) will need to be reapplied after an upgrade of ItemSense. This is because during the upgrade process the old docker-compose file will be moved to a backup location:

ITEMSENSE_HOME/.itemsense.bak/DATE/.

Where:

  • ITEMSENSE_HOME is the home directory of the user used when installing ItemSense.
  • DATE is the date the upgrade took place in the form YYYYMMDDHHmmSS e.g. 20170215003652.

Clock Synchronization and NTP Configuration

The integrity of ItemSense's item data relies heavily on network clock synchronization. In order for readers to generate reliable reports, all of the readers being utilized in a job must be synchronized with each other, and with ItemSense.

In fact, if a reader's clock is too far out of sync with the ItemSense host's clock, that reader's reports will be ignored and a health event will be triggered (See Health API).

This means that it is necessary, prior to collecting tag data from ItemSense for the first time, to ensure that all of the RAIN RFID reader clocks are configured with an NTP server with which they should synchronize.

By default, all readers use DHCP to discover their NTP server. However, it is possible to add up to six statically configured NTP servers. Note that configuring the NTP server of the reader can't yet be done via ItemSense. Please refer to the Impinj RShell Reference Manual for more information on how to configure NTP on a reader. This guide can be found on support.impinj.com.

A recommended pattern is to set up the ItemSense host as an NTP server and specify it as the NTP server for each reader along with an appropriate backup NTP server if necessary. Then, the ItemSense server must synchronize its clock with another NTP server. This could be inside or outside the network.

NOTE: The instructions specified in the following two sections are specific to the Ubuntu Linux distribution. While the commands should work on a Linux distribution other than Ubuntu, it may be necessary to modify the commands slightly for your distribution.

Set up the ItemSense server as an NTP server

Perform the following steps to set up the ItemSense server as an NTP server:

  1. Log into the ItemSense server.

  2. Configure NTP. Use the following steps to edit the NTP configuration file.

    1. Open the NTP configuration file:

      sudo vi /etc/ntp.conf

    2. Add as many NTP servers as possible. A minimum of two is recommended. Servers are listed from top to bottom in order of priority.

      Example:

      server 0.ubuntu.pool.ntp.org
      server 1.ubuntu.pool.ntp.org
      server 2.ubuntu.pool.ntp.org
      server 3.ubuntu.pool.ntp.org
      
      server ntp.ubuntu.com
      
      server 127.127.1.0
      

      NOTE: The last server address (127.127.1.0) is used if the other servers aren't available. It tells NTP to synchronize with itself. This is required for an offline installation of ItemSense with no other NTP servers on the network.

    3. Allow other machines to synchronize with this one by adding or removing restrictions:

      restrict <network base address> mask <mask> <one or more flags>

      Example:

      restrict 10.200.35.0 mask 255.255.255.0 nomodify notrap
      

      This will allow servers on that network to synchronize with this server but deny modification (via the protocol) of the NTP settings. For details about this, see the manual page for ntp.conf.

    4. Save and exit the ntp.conf file.

  3. (Optional) Edit the DHCP configuration file to prevent Ubuntu from requesting NTP servers from DHCP. Use the following steps to edit the file.

    1. Open the DHCP configuration file:

      sudo vi /etc/dhcp/dhclient.conf

    2. Remove the ntp-servers parameter and its trailing comma from the request command:

      request subnet-mask, broadcast-address, time-offset, routers, domain-name, domain-name-servers, domain-search, host-name, dhcp6.name-servers, dhcp6.domain-search, netbios-name-servers, netbios-scope, interface-mtu, rfc3442-classless-static-routes, ntp-servers, dhcp6.fqdn, dhcp6.sntp-servers;
      
    3. Save the DHCP configuration file and exit.

    4. Remove the generated NTP DHCP configuration file if it exists:

      sudo rm /var/lib/ntp/ntp.conf.dhcp

  4. Set NTP to be allowed in the Ubuntu firewall:

    sudo ufw allow ntp

  5. Restart the NTP service:

    sudo service ntp restart

  6. Verify that ntpd comes back up:

    sudo pgrep ntpd

    There should be a response with a process ID number.

  7. Verify that NTP is working properly:

    ntpq -pn

    The command displays information about the peer servers specified in the NTP configuration file. Sample output is shown below. A * or + symbol at the beginning of the line indicates that the peer can be used for synchronization. If no peer is marked by a * or a +, NTP is not operating properly.

    Information displayed when NTP is working properly

Configure a reader to use the ItemSense server as its NTP server

Perform the following steps on the ItemSense server to configure a reader to use ItemSense as its NTP server:

  1. Log in to the reader rshell command prompt using SSH.

  2. Disable NTP:

    config network ntp disable

  3. (Optional) Prevent the reader from dynamically configuring its NTP servers through DHCP:

    config network ntp dynamicservers disable

  4. Delete any configured NTP servers:

    config network ntp delall

  5. Add the ItemSense IP address as a statically configured NTP server:

    config network ntp add <ItemSense IP>

  6. Re-enable NTP:

    config network ntp enable

  7. Check that the reader synchronizes (this can take a little while):

    show network ntp