ItemSense

This document describes the installation process for Impinj ItemSense.

Introduction

The Impinj 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.

The aufs storage driver for Docker is no longer supported and if found during the system requirements check, the installation will be blocked. See Installation Prerequisites. The aufs storage driver configured by default on some Docker releases has been observed to cause failures under load. The newer overlay2 storage driver is recommended. To check which Docker storage driver you have, execute the "docker info" command. If the reported value for "Storage Driver" is "aufs", you must first uninstall any previous version of ItemSense, if it exists, then uninstall Docker and reinstall with the "overlay2" driver option. (If necessary, your configuration for a previous version of ItemSense can be exported and then imported into the new setup.) 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.

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:
- Docker, version 18.09.2 or later
- Docker Compose, version 1.23.2 or later
- Linux operating system supported distributions:
  - Ubuntu 16.04 Server, with the latest kernel version for that distribution
  - Ubuntu 18.04 Server, with the latest kernel version for that distribution
  - Centos 7, with the latest kernel version for that distribution
- cURL: If on Ubuntu, the command is sudo apt-get install curl. On CentOS, the command is sudo yum install curl

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. Make a note of this user's login name and password as you will need it for most support-related procedures.
The setup package will require approximately 3GB of temporary space to extract the compressed images. Ensure that the target directory has at least this amount of free space available.
Ensure that the host has the required ItemSense ports open. See Requirements for more details.
Ensure that docker is not using aufs. The aufs storage driver configured by default on some Docker releases has been observed to cause failures under load. The newer overlay2 storage driver is recommended. To check which Docker storage driver you have, execute the "docker info" command. If the reported value for "Storage Driver" is "aufs", you must first uninstall any previous version of ItemSense, if it exists, then uninstall Docker and reinstall with the "overlay2" driver option. (If necessary, your configuration for a previous version of ItemSense can be exported and then imported into the new setup.) For more information about Docker storage drivers and storage driver configuration, please refer to the online documentation at the Docker website.

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:

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'
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.
Check that docker is installed and is at the version specified in Installation Prerequisites:

docker -v

Example output:

Docker version 18.09.2, build 23cf638
Check that docker-compose is installed and is at the version specified in Installation Prerequisites:

docker-compose -v

Example output:

docker-compose version 1.23.2, build c7bdf9e
Check that there is at least 8GB of available disk space:

df -h ~

Details:
- The setup package itself will require 500MB of space. This package can potentially be removed once the installation is complete
- The setup package will require approximately 1GB of temporary space to extract the compressed images. This space will be reclaimed automatically at the end of the installation
- The initial installation consumes approximately 1.5GB of space but will grow over time as ItemSense data and logs are written to disk
See our Resource Requirements Guide for more information about System Requirements.

Installation Instructions

To install ItemSensw, you will need to have already downloaded the setup package. This file will be named similar to the following: itemsense-2.3.0+XXX-setup.run

When the setup package file has been obtained:

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-2.3.0+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.
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.
Make the setup package file executable with the following command:

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

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

sudo ./itemsense-2.3.0+XXX-setup.run install

The installer provides the option to choose the location at which ItemSense is installed. At the start of the Installation, you will be prompted to:

Press enter to accept the default directory provided by ItemSense
Provide an absolute path to the directory in which you will install ItemSense
Type "exit" to quit

The default path is /opt, which creates the installation directory, /opt/impinj/itemsense/2_3_0. If you choose to create your own directory, be aware that ItemSense appends the path, impinj/itemsense/2_3_0, to your location 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.

Example output:

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

Path [/opt]:
INFO: Checking for available disk space.
About to install Impinj ItemSense into path "/opt".  The following directories will be created "impinj/itemsense/2_3_0"
Ready to proceed (y/n)? y
INFO: Generating compose file: /opt/impinj/itemsense/2_3_0/itemsense-prod.yml
INFO: Unpacking docker images
Loaded image: isreg/coordinator:3.0.42

...

INFO: Unpacking firmware images

...

INFO: Installation action complete using path: /opt/impinj/itemsense/2_3_0
INFO: Setting permissions on /opt/impinj/itemsense/2_3_0/containers
INFO: Waiting up to 120 seconds for the Impinj ItemSense Coordinator Service to initialize and respond
Testing Coordinator endpoint [==========>                                         ] 22/120s
INFO: Found Coordinator HTTP endpoint
INFO: Waiting up to 30 seconds for the Impinj ItemSense Management Console (IMC) to initialize and respond
Testing IMC endpoint [=>                                                  ] 0/30s
INFO: Found IMC HTTP endpoint
INFO: To open the Impinj ItemSense Management Console and complete the setup process,
  open a supported web browser and browse to http://:3010.
  For more information, consult the ItemSense Management Console section on the
  Impinj Developers Portal at https://platform.impinj.com/site/developer/itemsense.
INFO: Impinj ItemSense install operation complete at path /opt/impinj/itemsense/2_3_0

In a browser, navigate to the IMC using the server IP address or host name and port 3010: http://TARGET_SERVER:3010/

Upgrade ItemSense

Upgrade Using Separate Hosts

These instructions explain how to stand up a separate instance of ItemSense and run a migration script to copy over the configuration. 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.

Side-by-Side Prerequisites

Your current ItemSense build has been installed and is up and running on TARGET_SERVER_XXX.
ItemSense-2.3.0 has been installed according to the Installation instructions, and is up and running on TARGET_SERVER_YYY

Side-by-Side Upgrade Instructions

As of ItemSense 2018r2, the configuration migration is executed through the ItemSense Management Console (IMC).

In a browser on TARGET_SERVER_XXX, navigate to the IMC using the server IP address or host name and port 3010:
From the landing page navigation menu, click More | Configuration Import/Export. This will take you to the Configuration Migration page.
Click the Export Configuration button.
Select and copy the exported configuration, including both the beginning and ending brackets.
Navigate to the IMC Configuration Migration page on TARGET_SERVER_YYY.

When ItemSense starts, the IMC can take up to 5 minutes to become available.
Click in the Import Configuration text box and paste the content you copied.
Select Overwrite and click the Import Configuration button.

After importing the configuration, you must also register your readers and upgrade your reader firmware. You can do this from within the ItemSense Management Console (IMC).

Add a network
1. Find the network address in the Address field of a reader definition.
2. In the navigation menu, click More | Admin Panel.
3. Click Scanner Configuration.
4. Click the Add New Network button.
5. Enter the Name and Subnet Range, then click the Submit button
Register readers
1. From the Scanner Configuration page, click Go to Reader Registration.
2. Select desired networks and click the Discover Readers.
3. Select the readers to register.
4. To set the facility of each reader, select from its Facility drop down menu, or optionally click the Bulk Set Facility button.
5. Click the Register button.
Upgrade reader firmware
1. In the navigation menu, click More | Admin Panel.
2. Click Software Management.
3. Click the Start New Update button.
4. In the Image Type field, select Reader Firmware.
5. Select your set of readers to update.
6. Click the Submit button.

Upgrade on the Same Host

This installs the new release of ItemSense over an existing instance.

In-Place Prerequisites

The Impinj ItemSense setup package has been obtained
Your current ItemSense build is up and running on TARGET_SERVER. ItemSense 2018r2 Limited Availability and any later builds are valid.
Docker, version 18.09.2 or later
Docker Compose, version 1.23.2 or later

In-Place Upgrade Instructions

(Optional) As a precaution, backup your configuration and database.
1. From the IMC navigation menu, click More | Configuration Import/Export
2. On the Configuration Import/Export page, click the Export Configuration button.
3. Select and copy the exported configuration, including both the beginning and ending brackets.
4. Backup the ItemSense database. The database is stored in: ~/containers/is-db
  
  sudo cp -r ~/containers/is-db ~/IS_DB_BACKUP
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-2.3.0+XXX-setup.run USERNAME@TARGET_SERVER:.

Where:
- USERNAME should be replaced with the designated user on the target server
- TARGET_SERVER should be replaced with the hostname or IP address of the server on which ItemSense will be installed
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 designated user.
Make the setup package file executable:

chmod +x itemsense-2.3.0+XXX-setup.run
From the same directory as the ItemSense setup package, run the setup package with the argument "upgrade".

This script must be run using sudo, as follows.

ItemSense 2.3.0 allows you to configure the maximum number of records you want to retain, in addition to the previous feature that retained records based on their age. The types of records affected by this new feature are:

items
- item history
- threshold transitions
- task
- health

The config.yml file provided with ItemSense 2.3.0 contains default values for maxAge and maxCount that have been performance tested and are recommended by Impinj. However, if applied, these new defaults can result in the loss of older data. During the upgrade, you will be warned about this feature and required to make a choice to:

Proceed using the recommended maximum row counts (y)
Proceed with the feature disabled (n)
Abort

To avoid losing data, we provide an alternative config.yml, in which you can customize the settings or effectively disable the new feature. For more information about these files and how they allow you to customize ItemSense, see Configuration and Logging Files.

If you are at all uncertain, please abort the upgrade and contact Impinj Customer Support.

As of ItemSense 2.1.0, Impinj provides the option to choose the location at which ItemSense is installed. At the start of the Installation, you will be prompted to:

Press enter to accept the default directory provided by ItemSense,
Provide an absolute path to the directory in which you will install ItemSense, or
Type "exit" to quit

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.

Example output:

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

Path [/opt]:
INFO: Checking for available disk space.
About to install Impinj ItemSense into path "/opt".  The following directories will be created "impinj/itemsense/2_3_0"
Ready to proceed (y/n)? y
INFO: Removing old Impinj ItemSense backups (if any)
INFO: Stopping and removing previous installation

...

INFO: Removing container images from local docker registry
INFO: ...Removing isreg/is-proxy:0.2.1
Untagged: isreg/is-proxy:0.2.1

...

INFO: ...Removing isreg/is-mariadb:2.1.1
Untagged: isreg/is-mariadb:2.1.1

...

INFO: ...Removing isreg/is-ntp:0.0.3

...

INFO: ...Removing rabbitmq:3.7.8-alpine
Untagged: rabbitmq:3.7.8-alpine

...

INFO: ...Removing isreg/imc:2.2.0.9
Untagged: isreg/imc:2.2.0.9

...

INFO: ...Removing isreg/isv2:0.0.111-d7c29b9e
Untagged: isreg/isv2:0.0.111-d7c29b9e

...

INFO: ...Removing isreg/is-health:1.0.36
Untagged: isreg/is-health:1.0.36

...

INFO: ...Removing isreg/coordinator:2.2.22
Untagged: isreg/coordinator:2.2.22

...

INFO: Copying data from your old Impinj ItemSense installation.  Depending on the size of your database, this can be a lengthy process.
INFO: Re-integrating previous data files for migration
INFO: Importing reader agent SSL certificates from previous installation
INFO: Restoring IMC config data
INFO: Migrating service configurations
INFO: Setting permissions on /opt/impinj/itemsense/2_3_0/containers
INFO: Generating compose file: /opt/impinj/itemsense/2_3_0/itemsense-prod.yml
INFO: Unpacking docker images
Loaded image: isreg/coordinator:3.0.42
Loaded image: isreg/imc:2.3.0.10
Loaded image: isreg/is-auth:1.0.59
Loaded image: isreg/is-health:1.0.41
Loaded image: isreg/is-mariadb:2.1.1
Loaded image: isreg/is-ntp:0.0.3
Loaded image: isreg/is-proxy:0.2.1
Loaded image: isreg/isv2:1.0.4
Loaded image: rabbitmq:3.7.8-alpine
INFO: Unpacking firmware images
INFO: Installing nginx container configuration
INFO: Installing rabbitmq container configuration
INFO: Installing Impinj ItemSense support tools
INFO: Starting the new docker composition
Creating network "2_3_0_itemsense" with driver "bridge"
Creating 2_3_0_imc_1       ... done
Creating 2_3_0_is-rabbit_1 ... done
Creating 2_3_0_itemsense_1 ... done
Creating 2_3_0_is-db_1     ... done
Creating 2_3_0_isv2_1      ... done
Creating 2_3_0_nginx_1     ... done
Creating 2_3_0_is-auth_1   ... done
Creating 2_3_0_is-health_1 ... done
Creating 2_3_0_is-ntp_1    ... done
INFO: Installation action complete using path: /opt/impinj/itemsense/2_3_0

...

INFO: Database migrations started.  Depending on the size of your database, this can be a lengthy process.
  Interrupting this may corrupt Impinj ItemSense and render your system unusable.
  Please allow the process to complete normally. If you believe it is taking too long, contact support.
INFO: Data migrations completed.
INFO: Migrating TLS settings from previous installation
INFO: Checking for previous TLS settings
INFO: Upgrading and Restoring Impinj ItemSense config store
INFO: Removing temporary files

...

INFO: upgrade action complete
INFO: Setting permissions on /opt/impinj/itemsense/2_3_0/containers
INFO: Waiting up to 120 seconds for the Impinj ItemSense Coordinator Service to initialize and respond

...

INFO: Found IMC HTTP endpoint
INFO: To open the Impinj ItemSense Management Console and complete the setup process,
  open a supported web browser and browse to http://:3010.
  For more information, consult the ItemSense Management Console section on the
  Impinj Developers Portal at https://platform.impinj.com/site/developer/itemsense.
INFO: Impinj ItemSense upgrade operation complete at path /opt/impinj/itemsense/2_3_0

Upgrade reader firmware
1. In the navigation menu, click More | Admin Panel.
2. Click Software Management.
3. Click the Start New Update button.
4. In the Image Type field, select Reader Firmware.
5. Select your set of readers to update.
6. Click the Submit button.
Update ItemSense agent
1. Again, click the Start New Update button.
2. Under Image Type, select ItemSense Agent.
3. In the Version field, the latest version will appear as the default. Enter a different version if necessary.
4. Under Max Parallel Readers, enter the maximum number of readers that can upgrade in parallel.
5. Select readers to update.
6. Click the Submit button.

The readers are now registered, upgraded, and ready to start jobs, and the agent has been updated. If the upgrade was successful, remove the backups:

sudo rm -rf ~/IS_DB_BACKUP
rm is-<filename>

If you change the ItemSense hostname after upgrading, you must recreate and restart the docker containers in order to access the IMC. Use the following commands:
sudo docker-compose -f itemsense-prod.yml down
sudo docker-compose -f itemsense-prod.yml up -d

Upgrade Earlier Versions of ItemSense

If you are runnning a version of ItemSense that is older than 2018r2, please contact Impinj support.

Uninstall ItemSense via Automated Process

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

Go to the directory where you put the ItemSense installer file.
Run the installer with the remove subcommand to remove the ItemSense software:

sudo ./itemsense-2.3.0+XXX-setup.run remove

Example output:

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


    [issupport@localhost ~]$ sudo ./itemsense-2.3.0+XXX-setup.run remove
    Verifying archive integrity...  100%   All good.

    ItemSense 2.3.0 Build 1661 Setup Package  100%

    ...

    About to completely remove Impinj ItemSense containers, backups, and data from path /opt/impinj/itemsense/2_3_0.
    Ready to proceed (y/n)? y
    INFO: Stopping and removing containers
    Stopping 2_3_0_is-rabbit_1 ... done
    Stopping 2_3_0_isv2_1      ... done
    Stopping 2_3_0_itemsense_1 ... done
    Stopping 2_3_0_imc_1       ... done
    Stopping 2_3_0_nginx_1     ... done
    Stopping 2_3_0_is-ntp_1    ... done
    Stopping 2_3_0_is-db_1     ... done
    Removing 2_3_0_is-rabbit_1 ... done
    Removing 2_3_0_isv2_1      ... done
    Removing 2_3_0_itemsense_1 ... done
    Removing 2_3_0_imc_1       ... done
    Removing 2_3_0_nginx_1     ... done
    Removing 2_3_0_is-ntp_1    ... done
    Removing 2_3_0_is-db_1     ... done
    Removing network 2_3_0_itemsense
    INFO: Removing container images from local docker registry
    INFO: ...Removing isreg/is-proxy:0.2.3
    Untagged: isreg/is-proxy:0.2.3

    …

    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: Impinj ItemSense remove operation complete at path...

Uninstall ItemSense via Manual Process

To manually uninstall ItemSense, follow these steps:

Check that nothing is listening on port 80, 3010, 443 or 5672. For example, the following 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                    "/opt/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 and run:

sudo docker-compose -f itemsense-prod.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

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

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

Find the ItemSense docker images

sudo docker images

Example output:

REPOSITORY                TAG                                 IMAGE ID            CREATED             SIZE
isreg/itemsense           2.3.0_1661-26c6a4de                 452fbdaede7d        6 days ago          421MB
isreg/imc                 2.3.0.743                           92db33343fb7        6 days ago          131MB
isreg/isv2                0.0.108-a0f0d84b                    1bfe9846efa9        2 weeks ago         122MB
isreg/is-mariadb          2.3.1                               22e7e735e86c        3 weeks ago         200MB
isreg/is-proxy            0.2.3                               661688be09b6        5 weeks ago         16.9MB
rabbitmq                  3.7.8-alpine                        b84c00eb4aee        8 months ago        46.8MB
isreg/is-ntp              0.0.3                               ca74798da8b8        12 months ago       4.5MB

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.

Connect to ItemSense via the ItemSense Management Console at: http://TARGET_SERVER:3010.
From the Home Page menu bar, click More|NTP Reader Sync.
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:

Log in to the reader RShell command prompt using SSH.
Disable NTP:

config network ntp disable
(Optional) Prevent the reader from dynamically configuring its NTP servers through DHCP:

config network ntp dynamicservers disable
Delete any configured NTP servers:

config network ntp delall
Add the external NTP server hostname or IP address:

config network ntp add <NTP Server hostname or IP>
Re-enable NTP:

config network ntp enable
Check that the reader synchronizes (this can take a little while):

show network ntp

Configure ItemSense to Use Encrypted TLS Communications for HTTPS, AMQPS, and MQTTS

You can install your own certificate in the ItemSense server to secure communication between your clients and ItemSense. The only prerequisite is a valid certificate and its corresponding private key. The two files must be accessible to the utility script that enables https, amqps, and mqtts in ItemSense.

A utility script named enable_tls.sh in the itemsense_support folder helps you safely install your certificate.

Assuming the certificate files, my-cert.crt and my-cert.key, are stored in the itemsense_support folder, the following command sets ItemSense to https, amqps, and mqtts:

sudo ${BASE_LOCATION}/impinj/itemsense/2_3_0//itemsense_support/enable_tls.sh ./my-cert.crt ./my-cert.key

The script asks you whether you want to proceed. If yes, the script switches ItemSense to https, amqps, and mqtts.

Once ItemSense is in https, the IMC still listens on port 3010, but you need to use an https:// style url to reach it. For example, http://acme.com:3010 becomes https://acme.com:3010

Impinj ItemSense supports TLS 1.1, TLS 1.2, and TLS 1.3. Following are basic settings to set your host firewall for specific configurations, whether running in TLS or in non-TLS mode.

Configure Ports to Use HTTP

Port	Setting	Use
80/tcp	enable	API
443/tcp	enable	Must be enabled for readers to connect, whether using HTTP or HTTPS. In both cases, readers connect via HTTPS.
1883/tcp	enable	MQTT
3010/tcp	enable	ItemSense Management Console (IMC)
5672/tcp	enable	AMQP
123/udp	enable	NTP

Configure Ports to Use HTTPS

Port	Setting	Use
80/tcp	disable	API
443/tcp	enable	Readers connect to ItemSense via HTTPS in either case
1883/tcp	disable	MQTT
3010/tcp	enable	ItemSense Management Console (IMC) -- HTTPS
5671/tcp	enable	AMQPS
5672/tcp	disable	AMQP
8883/tcp	enable	MQTTS
123/udp	enable	NTP

Configure Ports to Migrate from HTTP to HTTPS

Port	Setting	Use
80/tcp	disable	API
1883/tcp	disable	MQTT
5671/tcp	enable	AMQPS
5672/tcp	disable	AMQP
8883/tcp	enable	MQTTS

Tailor the Communication Protocols

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

sudo ${BASE_LOCATION}/impinj/itemsense/2_3_0/containers/itemsense_support/enable_tls.sh --advanced-help

Revert to HTTP, AMQP, and MQTT

If you encounter any problems setting up ItemSense to https, amqps and mqtts you can switch ItemSense back to http, amqp and mqtt with the following command:

sudo ${BASE_LOCATION}/impinj/itemsense/2_3_0/itemsense_support/enable_tls.sh disable

Configuration and Logging Files

The config.yml and logback.xml files have been externalized to make them more accessible to users. These files can be found at:

{BASE_LOCATION}/impinj/itemsense/2_3_0/containers

To edit these files, you must first escalate the permissions using either chmod, chmod +x config.yml or sudo, sudo gedit config.yml.

The log configuration file, logback.xml, manages ItemSense system log files and is a useful diagnostic tool when working with Impinj Support. It is important to note that incorrect changes to the format of this file could cause a loss of logging altogether. ItemSense will still run, but it could affect your system's performance and disk usage.

The most common use of the config.yml file is management of the pruning configurations. This file contains default values for maxAge and maxCount that have been tested and are recommended by Impinj to preserve performance. However, if you have a large quantity of data in your previous ItemSense installation, applying these new default values may result in the loss of older data. To avoid this, you can set the maxCount values to the largest possible value, which effectively disables pruning.

Be aware that if incorrect changes are made to config.yml, ItemSense will not run.