Impinj® ItemSense™ Installation Guide

This document describes the installation process for ItemSense.
Starting with ItemSense 2018r1, the software is provided in a setup package file with a name similar to itemsense-0.1.XXX-setup.run.

Earlier versions of ItemSense, including ItemSense 2017r1, were provided in an archive file format with a name similar to is.IT-BTIC-BUT.0.1.XXX.tar.bz2. Where the process differs, there are links referring to the Legacy Installation Guide.

Table of Contents

Introduction

The ItemSense software is provided in a setup package for customers who are installing the software within their company-managed network. The package contains a number of files, but the primary components are delivered as a series of docker containers.

Note: For customers that are using older versions of Docker, please be aware that the now-outdated aufs storage driver configured by default on some Docker releases has been observed to cause failures under load. The newer overlay2 storage driver, default on the current release, is recommended. To check which Docker storage driver you have, execute the "docker info" command. If, under "Storage Driver," aufs appear as being used, a clean install or upgrading using multiple hosts to a system with Docker installation configured to use the overlay2 storage driver should be considered. For more information about Docker storage drivers and storage driver configuration, please refer to the online documentation at the Docker website.

The following section describes the process for installing ItemSense using the setup package.

Note: This guide assumes a firm grasp of the Linux command line.

Installation Prerequisites

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

  • Obtain an ItemSense Instance ID from your Impinj representative.
  • Download the ItemSense setup package from the link in the welcome email.
  • Install the following software on the server where ItemSense will be installed
    • Linux operating system with ONLY these specific versions:
    • Ubuntu version 16.04 with the latest kernel for this distribution, or
    • Centos version 7 with the latest kernel version for this distribution
    • Docker, version 1.12 or later
    • Docker Compose, version 1.14 or later
  • 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 user installing ItemSense is a valid Linux user and has a home directory, as ItemSense will install under that user's home directory. Make a note of this user's login name and password as you will need it for most support-related procedures.
  • Ensure that the host has the required ItemSense ports open. See Requirements for more details.

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

Note: Some of these instructions involve changes that may conflict with the IT guidelines in place at your company. If you have any doubts about suggested changes, we recommend that you speak with your IT department.

Install ItemSense

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 ss -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

    If this command shows that some ItemSense docker images already exist, follow the Uninstall Itemsense Via Automated Process or the Uninstall Itemsense Via Manual Process 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.14.0, build c7bdf9e
    
  5. Check that there is at least 8GB of available disk space on the user's home directory:

    df -h ~

    Example output:

    Filesystem      Size  Used Avail Use% Mounted on
    /dev/sdb1        99G  7.0G   87G   8% /home
    

    Details:

    • The setup package itself will require 1.2GB of space. This package can potentially be removed once the installation is complete
    • The setup package will require approximately 3GB of temporary space to extract the compressed images. This space will be reclaimed automatically at the end of the installation
    • The docker images will require approximately 3GB of space once installed
    • The containers folder will require a minimum of 200MB to install. It will grow over time as ItemSense runs and item records are stored in the database

Installation Instructions

To install ItemSense 2018r2, you will need to have already downloaded the setup package. This file will be named similar to the following: itemsense-0.1.XXX-setup.run

As the file is 1.2GB, it may take some time to download.

Note: For versions of ItemSense older than 2017r1, refer to the Legacy Installation Guide.

When the setup package file has been obtained:

  1. Copy the file to the target server. The following is an example of copying the file from a Linux host to the target server.

    scp itemsense-0.1.XXX-setup.run USERNAME@TARGET_SERVER:.

    Where:

    • USERNAME is replaced with the user on the target server.
    • TARGET_SERVER is replaced with the hostname or IP address of the server on which you intend to install ItemSense.
  2. When the file transfer to the target server is complete, log on to the target server and navigate to the location where you placed 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 place the setup package, ItemSense is always installed to the home directory of the login name defined by the environment variable $SUDO_USER. This variable is set by the sudo command anytime it is invoked.

    The following command can be executed to see the value of $SUDO_USER.

    sudo bash -c 'echo $SUDO_USER'

  3. Make sure the setup package file is executable:

    chmod +x itemsense-0.1.XXX-setup.run

  4. From the same directory as the ItemSense setup package, run the setup package with the argument "install".

    During installation you will be asked to confirm if you would like to continue with the installation. Select y to continue with the installation or n to back out of the installation.

    Note: This script must 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 ./itemsense-0.1.XXX-setup.run install

    Example output:

    Note: Some output text has been omitted, denoted by a stand-alone ellipsis (...) line.

    [issupport@localhost ~]$ sudo ./itemsense-0.1.1118-setup.run install
    Verifying archive integrity...  100%   All good.
    Uncompressing ItemSense 2018r2 Build 1118 Setup Package  100%
    About to install ItemSense at path /home/issupport, Ready to proceed (y/n)? y
    INFO: Generating Prod compose file: /home/issupport/itemsense-prod-3.yml
    INFO: Unpacking docker container images
    
    …
    
    Loaded image: isreg/imc:1.0.523
    
    …
    
    Loaded image: isreg/is-mariadb:10.0.28-3
    
    …
    
    Loaded image: isreg/is-ntp:0.0.3
    
    …
    
    Loaded image: isreg/is-proxy:0.1.0
    
    …
    
    Loaded image: isreg/is-rabbitmq-runit:3.6.15-alpine
    
    …
    
    Loaded image: isv2:0.0.59-e740b050
    
    …
    
    Loaded image: isreg/itemsense:master-7850a
    INFO: Firmware images
    INFO: Installing nginx container configuration
    INFO: Installing rabbitmq container configuration
    INFO: Installing mariadb container configuration
    INFO: Installing ItemSense support tools
    INFO: Start the new docker compose file
    Creating issupport_is-ntp_1    ... done
    Creating issupport_isv2_1      ... done
    Creating issupport_nginx_1     ... done
    Creating issupport_is-db_1     ... done
    Creating issupport_imc_1       ... done
    Creating issupport_itemsense_1 ... done
    Creating issupport_is-rabbit_1 ... done
    INFO: Installation action complete using path: /home/issupport
    INFO: Setting permissions on /home/issupport/containers
    INFO: Waiting up to 300 seconds for the ItemSense services to initialize and respond
    Testing service endpoints [=============>                                      ] 74/300s
    INFO: ItemSense endpoints test passed
    INFO: Testing for IMC endpoint
    INFO: 0: Sending query to IMC endpoint
    INFO: ...Found IMC endpoint
    INFO: ItemSense install operation complete at path /home/issupport
    
    1. In a browser, navigate to the IMC using the server IP address or host name and port 3010:

    http://TARGET_SERVER:3010/

    Note: After ItemSense starts, it can take up to 5 minutes before the IMC is available

Upgrade ItemSense

Upgrade Using Separate Hosts (Preferred)

These instructions explain how to stand up a separate instance of ItemSense and run a migration script to copy over the configuration. This is the preferred method for upgrading ItemSense because it minimizes the chance of errors. Note that 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 Upgrade on the Same Host.

Note: For customers that are using older versions of Docker, please be aware that the now-outdated aufs storage driver configured by default on some Docker releases has been observed to cause failures under load. The newer overlay2 storage driver, default on the current release, is recommended. To check which Docker storage driver you have, execute the "docker info" command. If, under "Storage Driver," aufs appear as being used, a clean install or upgrading using multiple hosts to a system with Docker installation configured to use the overlay2 storage driver should be considered. For more information about Docker storage drivers and storage driver configuration, please refer to the online documentation at the Docker website.

Note: As of the 2018r2 release, ItemSense requires that the reader zone name matches the reader name. If the reader zone name differs from the reader name, it will be updated automatically during the upgrade process.

Prerequisites

  • Two servers, TARGET_SERVER_XXX and TARGET_SERVER_YYY are up and running as follows:

    • Your current ItemSense build has been installed and is up and running on TARGET_SERVER_XXX. Most commonly, this will be 2018r1 Build 954, but 2017r1 Limited Availability Build 544 and any later builds are valid.

    • ItemSense 2018r2 has been installed according to the Installation instructions, and is up and running on TARGET_SERVER_YYY

  • node.js version 8.9.4 or later has been installed (go to https://nodejs.org/en/download/ to download and install it)

Note: Upgrades from ItemSense versions prior to 2017r1 Limited Availability Build 544 are unsupported. To manually migrate, please call or contact Impinj Support and ensure that you have an active maintenance contract.

Instructions

  1. Install the latest version of the is-tool Node package on any host that has network access to both instances of ItemSense.

    sudo npm install -g is-tool

    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 2018r1 instance. The is-tool saves the configuration in the file specified by filename. TARGET_SERVER_XXX must be replaced with the hostname or the IP address of the server on which ItemSense 2018r1 is installed.

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

    1. Open the file you have created and copy its contents. Make sure you copy the beginning and ending brackets.

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

      http://TARGET_SERVER_YYY:3010/

      Note: after ItemSense starts it can take up to 5 minutes before the IMC will be available, after which you click through the out-of-box experience to access the IMC, using admin as the default user name and admindefault as the password.

    3. From the landing page navigation menu, click More→Configuration Import/Export

    4. On the Configuration Import/Export page, click in the Import Configuration text box and paste the content you copied.

    5. Select Overwrite and click the Import Configuration button.

  3. The is-tool saves all of the ItemSense configuration except for the current zone map configuration. The current zone map configuration must be manually migrated from the old instance to the new.

    1. Obtain the current zone map configuration from TARGET_SERVER_XXX. The current zone map configuration can be obtained using the API:

      curl -u<username>:<password> http://TARGET_SERVER_XXX/itemsense/control/v1/currentZoneMap/show/{facilityName}

      Note: This step requires permissions set for the role of ConfigManager, Admin, or JobRunner.

      If there is no current zone map set for that facility, the API will return the following data in the HTTP response (and there is no migration necessary for that facility):

      {"name":null,"status":"WAITING_FOR_ZONE_MAP"}
      
    2. Set this current zone configuration in the new instance. This can be done via the API (note that ItemSense infers the correct facility from the zone map name):

      curl -X POST -u<username>:<password> http://TARGET_SERVER_YYY/itemsense/control/v1/currentZoneMap/select/{zoneMapName}

  4. At this point all configuration has been migrated to the 2018r2 instance but the readers are still provisioned against the 2018r1 instance. You will need to go through the provisioning flow to associate the defined readers with the new 2018r2 instance.

    Note: Starting with upgrading from 2018r2, you will no longer need to go through this provisioning flow again.

    • Add a network
      • Find a network to add by looking at the Address field of a reader definition
      • In the navigation menu, click More→Admin Panel.
      • Click SCANNER CONFIG
    • Register readers
      • Click Readers in the navigation bar, to return to the Readers Definitions page.
      • From the Readers Definitions page, click the Scanner tab. This will take you to the Scanners Readers page. Click the DISCOVER READERS button.
      • Select only the readers flagged with the triangle exclamation point
      • Click the REGISTER SELECTED READERS button
    • Upgrade reader firmware
      • Return to the *Definitions" page. In the navigation menu, click More→Admin Panel.
      • Click SOFTWARE INSTALL.
      • In the Software Installation dialog, for Software to Install, choose Reader Firmware.
      • Select your set of readers to update
      • Click START INSTALLATION.

    The readers are now registered, upgraded, and ready to start jobs.

Upgrade on the Same Host

This installs the new release of ItemSense over an existing instance. The procedure is riskier but allows you to retain item, health and job data. Perform this upgrade if you need to retain historical data. Otherwise, please follow the instructions for Upgrade Using Separate Hosts.

Note: For customers that are using older versions of Docker, please be aware that the now-outdated aufs storage driver configured by default on some Docker releases has been observed to cause failures under load. The newer overlay2 storage driver, default on the current release, is recommended. To check which Docker storage driver you have, execute the "docker info" command. If, under "Storage Driver," aufs appear as being used, a clean install or upgrading using multiple hosts to a system with Docker installation configured to use the overlay2 storage driver should be considered. For more information about Docker storage drivers and storage driver configuration, please refer to the online documentation at the Docker website.

Note: As of the 2018r2 release, ItemSense requires that the reader zone name matches the reader name. If the reader zone name differs from the reader name, it will be updated automatically during the upgrade process.

Prerequisites

  • ItemSense 2018r2 setup package has been obtained

  • Your current ItemSense build has been installed and is up and running on TARGET_SERVER. Most commonly, this will be 2018r1 Build 954, but `2017r1 Limited Availability Build 544' and any later builds are valid.

    Note: Upgrades from ItemSense versions prior to 2017r1 Limited Availability Build 544 are unsupported. To manually migrate, please call or contact Impinj Support and ensure you have an active maintenance contract.

  • node.js version 8.9.4 or later has been installed (go to https://nodejs.org/en/download/ to download and install it).

Instructions

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

    • Connect to the existing ItemSense version via the ItemSense Management Console at: http://TARGET_SERVER:3010
    • Go to the Scanner Configuration page: (three dots in upper right)→Admin→Scanner config
    • Take a note of the networks that require migrating i.e. networks containing the readers that are being managed by the existing ItemSense version
  2. (Optional) As a precaution in case the upgrade fails, backup your configuration and database.

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

      npm install -g is-tool

      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 old instance. The is-tool saves the configuration in the file specified by filename.

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

    3. Backup the ItemSense database. The database is stored in: <ItemSense home folder>/containers/is-db

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

  3. Stop ItemSense and the database container. You must be in the home directory of the user that installed ItemSense, which is the location of the ItemSense docker-compose YAML file.

    Note: If you are upgrading from 2017r1, you need to change the file name in the example below to itemsense-prod-1.6.0.yml

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

    Example output:

    Stopping issupport_is-rabbit_1 ... done
    Stopping issupport_itemsense_1 ... done
    Stopping issupport_nginx_1     ... done
    Stopping issupport_is-db_1     ... done
    Stopping issupport_imc_1       ... done
    Removing issupport_is-rabbit_1 ... done
    Removing issupport_itemsense_1 ... done
    Removing issupport_nginx_1     ... done
    Removing issupport_is-db_1     ... done
    Removing issupport_imc_1       ... done 
    
  4. Copy the ItemSense setup package file to the target server. The following is an example of copying the file from a Linux host to the target server.

    scp itemsense-0.1.XXX-setup.run 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 to be installed
  5. When the file transfer to the target server has completed, log on to the target server and navigate to the location where you placed 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.

  6. Upgrade Docker Compose to version 1.14 or later. Instructions for installing Docker Compose can be found here.

  7. Make sure the setup package file is executable:

    chmod +x itemsense-0.1.XXX-setup.run

  8. Upgrade the existing docker containers using the setup package.

    Note: If you change the ItemSense hostname after upgrading, you must recreate and restart the docker containers in order to access the IMC. (If you are upgrading from 2017r1, you need to change the file name in the example below to itemsense-prod-1.6.0.yml).
    Use the following commands:

    sudo docker-compose -f itemsense-prod-3.yml down
    sudo docker-compose -f itemsense-prod-3.yml up -d

    During installation you will be asked to confirm if you would like to continue with the installation. Select 'y' to continue with the installation or 'n' to back out of the installation.

    sudo ./itemsense-0.1.XXX-setup.run upgrade

    Example output:

    Note: Some output text has been omitted, denoted by a stand-alone ellipsis (...) line.

    [issupport@localhost ~]$ sudo ./itemsense-0.1.1118-setup.run upgrade
    Verifying archive integrity...  100%   All good.
    Uncompressing ItemSense 2018r2 Build 1118 Setup Package  100%
    INFO: Found existing ItemSense installation: "2018r1 Build 954" at path /home/issupport
    About to upgrade ItemSense at path /home/issupport, Ready to proceed (y/n)? y
    INFO: Stopping and removing previous installation
    INFO: Removing container images from local docker registry
    INFO: ...Removing is-proxy:0.0.954
    Untagged: is-proxy:0.0.954
    
    …
    
    INFO: ...Removing isreg/is-mariadb:10.0.28
    Untagged: isreg/is-mariadb:10.0.28
    
    …
    
    
    INFO: ...Removing isreg/is-rabbitmq-runit:3.5.7r3
    Untagged: isreg/is-rabbitmq-runit:3.5.7r3
    
    …
    
    
    INFO: ...Removing isreg/imc:1.0.462
    Untagged: isreg/imc:1.0.462
    
    …
    
    
    INFO: ...Removing isreg/itemsense:master-ab378
    Untagged: isreg/itemsense:master-ab378
    
    …
    
    
    INFO: Backing up previous binaries
    INFO: Re-integrating previous data files for migration
    INFO: Generating Prod compose file: /home/issupport/itemsense-prod-3.yml
    INFO: Unpacking docker container images
    
    …
    
    Loaded image: isreg/imc:1.0.523
    
    …
    
    Loaded image: isreg/is-mariadb:10.0.28-3
    
    …
    
    Loaded image: isreg/is-ntp:0.0.3
    
    …
    
    Loaded image: isreg/is-proxy:0.1.0
    
    …
    
    Loaded image: isreg/is-rabbitmq-runit:3.6.15-alpine
    
    …
    
    Loaded image: isv2:0.0.59-e740b050
    
    …
    
    Loaded image: isreg/itemsense:master-7850a
    INFO: Firmware images
    INFO: Installing nginx container configuration
    INFO: Installing rabbitmq container configuration
    INFO: Installing mariadb container configuration
    INFO: Installing ItemSense support tools
    INFO: Start the new docker compose file
    Creating issupport_is-ntp_1    ... done
    Creating issupport_imc_1       ... done
    Creating issupport_is-rabbit_1 ... done
    Creating issupport_isv2_1      ... done
    Creating issupport_itemsense_1 ... done
    Creating issupport_is-db_1     ... done
    Creating issupport_nginx_1     ... done
    INFO: Installation action complete using path: /home/issupport
    INFO: Waiting for data migrations to resolve
    INFO: Restoring IMC config data
    INFO: Restoring ItemSense config store
    INFO: Restarting ItemSense to import config
    Restarting issupport_nginx_1     ... done
    Restarting issupport_itemsense_1 ... done
    Restarting issupport_is-db_1     ... done
    Restarting issupport_isv2_1      ... done
    Restarting issupport_is-rabbit_1 ... done
    Restarting issupport_imc_1       ... done
    Restarting issupport_is-ntp_1    ... done
    INFO: Upgrade action complete
    INFO: Setting permissions on /home/issupport/containers
    INFO: Waiting up to 300 seconds for the ItemSense services to initialize and respond
    Testing service endpoints [========>                                           ] 42/300s
    INFO: ItemSense endpoints test passed
    INFO: Testing for IMC endpoint
    INFO: 0: Sending query to IMC endpoint
    INFO: ...Found IMC endpoint
    INFO: ItemSense upgrade operation complete at path /home/issupport
    
  9. At this point all configuration has been migrated to the new instance but the readers are still provisioned against the old instance. You will need to go through the provisioning flow to associate the defined readers with the new instance.

    • Add a network
      • Find a network to add by looking at the Address field of a reader definition
      • In the navigation menu, click More→Admin Panel.
      • Click SCANNER CONFIG
    • Register readers
      • From the Definitions page, click the Scanner tab. This will take you to the SCANNER page.
      • Click the DISCOVER READERS button.
      • Select only the readers flagged with the triangle exclamation point
      • Click the REGISTER SELECTED READERS button
      • Upgrade reader firmware
      • Return to the *Definitions" page. In the navigation menu, click More→Admin Panel.
      • Click SOFTWARE INSTALL.
      • Under Software Installation, Software to Install, select Reader Firmware.
      • Select your set of readers to update
      • Click START INSTALLATION.

    The readers are now registered, upgraded, and ready to start jobs.

  10. If the upgrade was successful, remove the backups:

    sudo rm -rf ~/IS_DB_BACKUP

    rm is-<filename>

Upgrade Earlier Versions of ItemSense

If you are runnning a version of ItemSense that is older than 2017r1, please contact Impinj Support: support@impinj.com.

Uninstall ItemSense via Automated Process

For ItemSense build 2017r1, refer to the Legacy Installation Guide.

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

  1. Go to the directory where you put the ItemSense installer file.

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

    • Run the installer with the remove subcommand and -p option to remove the ItemSense software and purge all configuration and stored Item data:

      sudo ./itemsense-0.1.XXX-setup.run remove -p

      Example output:

      Note: Some output text has been omitted, denoted by a stand-alone ellipsis (...) line.

      [issupport@localhost ~]$ sudo ./itemsense-0.1.1118-setup.run remove -p    
      Verifying archive integrity...  100%   All good.
      Uncompressing ItemSense 2018r2 Build 1118 Setup Package  100%
      About to completely remove ItemSense containers and data at path /home/issupport, Ready to proceed (y/n)? y
      INFO: Stopping and deleting containers
      Stopping issupport_imc_1       ... done
      Stopping issupport_is-rabbit_1 ... done
      Stopping issupport_itemsense_1 ... done
      Stopping issupport_is-db_1     ... done
      Stopping issupport_nginx_1     ... done
      Stopping issupport_isv2_1      ... done
      Stopping issupport_is-ntp_1    ... done
      Removing issupport_imc_1       ... done
      Removing issupport_is-rabbit_1 ... done
      Removing issupport_itemsense_1 ... done
      Removing issupport_is-db_1     ... done
      Removing issupport_nginx_1     ... done
      Removing issupport_isv2_1      ... done
      Removing issupport_is-ntp_1    ... done
      INFO: Removing container images from local docker registry
      INFO: ...Removing isreg/is-proxy:0.1.0
      Untagged: isreg/is-proxy:0.1.0
      
      …
      
      INFO: ...Removing isreg/is-mariadb:10.0.28-3
      Untagged: isreg/is-mariadb:10.0.28-3
      
      …
      
      
      INFO: ...Removing isreg/is-ntp:0.0.3
      Untagged: isreg/is-ntp:0.0.3
      
      …
      
      
      INFO: ...Removing isreg/is-rabbitmq-runit:3.6.15-alpine
      Untagged: isreg/is-rabbitmq-runit:3.6.15-alpine
      
      …
      
      
      INFO: ...Removing isreg/imc:1.0.523
      Untagged: isreg/imc:1.0.523
      
      …
      
      
      INFO: ...Removing isv2:0.0.59-e740b050
      Untagged: isv2:0.0.59-e740b050
      
      …
      
      
      INFO: ...Removing isreg/itemsense:master-7850a
      Untagged: isreg/itemsense:master-7850a
      
      …
      
      
      INFO: ItemSense remove_and_purge operation complete at path /home/issupport
      

Uninstall ItemSense via Manual Process

To manually uninstall ItemSense, follow these steps:

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

    For example, this command should not show any output:

    sudo docker ps

    If you see seven containers listed like the following:

    CONTAINER ID        IMAGE                                   COMMAND                  CREATED             STATUS              PORTS               NAMES
    165601415c7e        isreg/is-proxy:0.1.0                    "/bin/sh -c /bin/d..."   13 minutes ago      Up 13 minutes                           issupport_nginx_1
    63d6bb6e4287        isreg/is-mariadb:10.0.28-3              "docker-entrypoint..."   13 minutes ago      Up 13 minutes                           issupport_is-db_1
    0c704cc5a15a        isv2:0.0.59-e740b050                    "/home/itemsense/i..."   13 minutes ago      Up 13 minutes                           issupport_isv2_1
    8f09717bf79c        isreg/itemsense:master-7850a            "/sbin/my_init"          13 minutes ago      Up 13 minutes                           issupport_itemsense_1
    411dd4d4b572        isreg/is-rabbitmq-runit:3.6.15-alpine   "docker-entrypoint..."   13 minutes ago      Up 13 minutes                           issupport_is-rabbit_1
    5fdf343d83ca        isreg/imc:1.0.523                       "/etc/sv/is-webapp..."   13 minutes ago      Up 13 minutes                           issupport_imc_1
    b88c7e88fc27        isreg/is-ntp:0.0.3                      "/bin/sh /usr/loca..."   13 minutes ago      Up 13 minutes                           issupport_is-ntp_1
    

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

    Note: If you are upgrading from 2017r1, you need to change the file name in the example below to itemsense-prod-1.6.0.yml

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

    Example output:

    Stopping issupport_nginx_1     ... done
    Stopping issupport_is-db_1     ... done
    Stopping issupport_isv2_1      ... done
    Stopping issupport_itemsense_1 ... done
    Stopping issupport_is-rabbit_1 ... done
    Stopping issupport_imc_1       ... done
    Stopping issupport_is-ntp_1    ... done
    Removing issupport_nginx_1     ... done
    Removing issupport_is-db_1     ... done
    Removing issupport_isv2_1      ... done
    Removing issupport_itemsense_1 ... done
    Removing issupport_is-rabbit_1 ... done
    Removing issupport_imc_1       ... done
    Removing issupport_is-ntp_1    ... done
    
  2. Remove the containers directory and the itemsense-prod-3.yml or itemsense-prod-1.6.0.yml file from the installation directory.

    Note: If you are uninstalling 2017r1, you need to change the file name in the example below to itemsense-prod-1.6.0.yml

    sudo rm -rf containers/

    sudo rm -f itemsense-prod-3.yml

  3. Find the ItemSense docker images

    sudo docker images

    Example output:

    REPOSITORY                TAG                                 IMAGE ID            CREATED             SIZE
    isreg/itemsense           master-7850a                        d12ecc5763d8        21 hours ago        768 MB
    isreg/imc                 1.0.523                             7d445ac28db4        41 hours ago        1.09 GB
    isv2                      0.0.59-e740b050                     c587254cc163        7 days ago          546 MB
    isreg/is-mariadb          10.0.28-3                           b46cf84d5e29        10 days ago         381 MB
    isreg/is-ntp              0.0.3                               ca74798da8b8        8 weeks ago         4.5 MB
    isreg/is-rabbitmq-runit   3.6.15-alpine                       edea4b0c92e4        4 months ago        39.3 MB
    isreg/is-proxy            0.1.0                               403b9e80c313        4 months ago        54.8 MB
    
  4. 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.28-3
    Deleted: sha256:b46cf84d5e294a0953254ca5e06e5aaac3752a9d366667671dcb3a7bdf23cb53
    Deleted: sha256:0d1e183a06690ee796292e74e57b0a24b13a2b068c1a4b3793af31e18e51cef6
    Deleted: sha256:cb28cd83346263cb6edb1f6f056c1b575b7d4013ffee8527144c4ef2950d32ce
    Deleted: sha256:5671e0f4505e12a9217c13f5dc4353b5cc25a3bff58591ea884addb200f63a9f
    Deleted: sha256:120c9add60e3fa4f42d3dbc465d6e783c94ba8a08f32de2985856c01e8038c92
    Deleted: sha256:b5a9489a383edacf6330dbc1e53a727f421b824778bfca65e0f69911bba7df8e
    Deleted: sha256:80c44837b8b4f546ccd99a8e348c65cd39610fbc2f9c4701388a8b3afca6fb0a
    Deleted: sha256:baa7a423070394fed311ccc47b6e6450a828062d8014cdb894cf8358e7dc67e7
    Deleted: sha256:d7852a97e12d6c3d318ec4af1a65c5898b55fdc3600430b3fa0fa807fb1bcc23
    Deleted: sha256:d5a98345467828bd6cfbebbddb88ed64b2b84304155774317505fdc389c62960
    Deleted: sha256:7f6799f430961cfd0adb6af81aa60bb66a7c42da081a5a844b2a6ec96f94c996
    Deleted: sha256:e85bddc133b6addb199a81941cf9f9a580d226180fccd71eac0c6c89dcc653ec
    Deleted: sha256:ca76ebbabd672ad4c5dd8ce3659dcd0794df9b11329359aa74d9461f15a47844
    Deleted: sha256:a3928699dfa0d33e65f302e3176d054aec7a50bbe5c2e7e0b53a68541b89dac5
    Deleted: sha256:23672a5ac8fb00f5963174353f4fea163a43b23b7814ba3d7efb8cf9803f7010
    Deleted: sha256:9042efb93af5246dbc36ffd103a8b87e8d39e797e06656fb5df053ca77378eb9
    Deleted: sha256:c08bac17c414ebfb8d22b46b79d4c1fc41d16a4452c924c306cbec673d215d43
    Deleted: sha256:30499d7d4e67556242cabe7be7b1bac2a94d7ff00972c6236475858a91b4b2a7
    Deleted: sha256:b6ca02dfe5e62c58dacb1dec16eb42ed35761c15562485f9da9364bb7c90b9b3
    

    Uninstall is now complete.

Clock Synchronization and NTP Configuration

The integrity of ItemSense's item data relies heavily on network clock synchronization. If a reader's clock is more than ten seconds out of sync with the ItemSense host's clock, that reader's reports will be ignored and a health event will be triggered (See the Health API in the Impinj API Reference).

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. Prior to collecting tag data from ItemSense for the first time, you should ensure that all of the RAIN RFID reader clocks are configured to synchronize with an NTP server.

If your network does not automatically provide an NTP source, you have a number of options to ensure that all reader clocks are configured to synchronize with an NTP server. The easiest method is through the ItemSense Management Console (IMC). The following steps install an NTP server on the host running ItemSense and configure the readers to use that host as their NTP source.

  1. Connect to ItemSense via the ItemSense Management Console at: http://TARGET_SERVER:3010.
  2. From the Home Page menu bar, click More|NTP Reader Sync.
  3. Click the NTP Reader Sync toggle button to enable or disable reader synchronization.

Alternatively, you can use the following instructions to manually configure each reader and the ItemSense host to use an external NTP server.

Configure a Reader to Use an external NTP Server

Perform the following steps to configure a reader to use an external 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 external NTP server hostname or IP address:

    config network ntp add <NTP Server hostname or IP>

  6. Re-enable NTP:

    config network ntp enable

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

    show network ntp

Note: 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.

Configure ItemSense 2018r2 to Use Encrypted TLS Communications for HTTPS and AMQPS

You can install your own certificate in the Itemsense server in order to secure communication between your clients and ItemSense. The only pre-requisite is a valid certificate and its corresponding private key. The two files must be accessible to the utility script which enables https and amqps in ItemSense.

A utility script named enable_tls.sh in the $HOME/itemsense_support folder assists you with installation of your certificate safely.

Assuming you have stored your certificate files named my-cert.crt and my-cert.key in the home folder of the user which installed ItemSense, the following command would set ItemSense to https and amqps:

sudo $HOME/itemsense_support/enable_tls.sh ./my-cert.crt ./my-cert.key

Note: Replace as necessary the certificate name and path to meet your certificate file locations.

The script will show some informational data and request whether you want to proceed. Once you accept, the script will switch ItemSense to https and amqps.

Note: Once ItemSense is in https, the IMC will still listen on port 3010 however you will need to use an https:// style url to reach it. As an example http://acme.com:3010 will change to https://acme.com:3010

Note: Even though ItemSense works in https, you will need to adjust the firewall on your host to block any incoming connection over the http port 80 to prevent further connections to ItemSense over this port.

Tailoring the Protocols to Encrypt

Should you need to tailor which communication protocols are to be encrypted and/or cause http to redirect to https, you can find more script options by executing:

sudo $HOME/itemsense_support/enable_tls.sh --advanced-help

Revert to HTTP and AMQP

If you encounter any problems setting up ItemSense to https and amqps you can switch ItemSense back to http and amqp by running the following command line:

sudo $HOME/itemsense_support/enable_tls.sh disable