Chapter 2 Regional Broker Installation

Hosting Requirements

The easiest way to set up a regional EFM broker for DOT demo purposes is to have it accessible via the Internet. This could be something like a public VPS “Droplet” from DigitalOcean, or a self-hosted VM with static NAT for the connection .

TCP port 8443 is the only port that needs to be exposed to the Internet. This can even be mapped to an alternate port in the static NAT configuration if necessary as long as the IR829 upstream broker configuration matches the new port.

The recommended sizing for this demo is a system with 4 vCPU, 8GB RAM, and 80-160GB of storage. The OS should be a recent version of x86 64-bit Linux. This documentation was tested and validated on Ubuntu 16.04 LTS.

Install Prerequisite Software

1. SSH into the server as root or use sudo su - as an admin user
2. Install Java and unzip

apt install software-properties-common unzip python
add-apt-repository ppa:webupd8team/java
apt update
apt install oracle-java8-installer

Accept the Oracle Java license agreement when prompted

Set Up the EFM Environment

1. Add the EFM user with adduser efm

• Set the password to something secure and save it for future reference
• Full Name: EFM Admin
• Hit Enter to accept the defaults for the rest

2. Set up directories

mkdir -p /opt/cisco/kinetic
chown efm:efm /opt/cisco/kinetic
mkdir /var/log/parstream
chown efm:efm /var/log/parstream

3. Update the open file limits for ParStream

tee -a /etc/security/limits.conf << EOT
# Higher open file limit for Cisco Kinetic/Parstream
*             hard     nofile     131072
*             soft     nofile     131072
root          hard     nofile     131072
root          soft     nofile     131072
EOT

4. Exit the SSH session

Install EFM

1. Download the IOx EFM 1.2.0 bundle .zip file here
2. Unzip EFM-1.2.0.zip
3. SCP the EFM-1-2-0.zip in the unzipped EFM-1.2.0 folder to the EFM server into the efm user’s home directory

Pay attention to the spelling of EFM-1-2-0.zip This file is found inside the initial downloaded zip archive which is named EFM-1.2.0.zip. Noting this subtle difference will save you from unnecessarily sending the entire zip archive over to the server and having to run unzip twice.

4. SSH into the server as the efm user that was created above
5. Unzip EFM and install it

unzip EFM-1-2-0.zip
cd EFM-1-2-0
./efm-linux install

Select the defaults when prompted, except for the following

• Select y to reconfigure the EFM Message Broker server configuration
• Enter a secure efmAdmin password and save it for future reference

6. Update the EFM broker configuration file to only allow automatic connections from other EFM brokers with tokens and to quarantine EFM brokers without tokens

vi /opt/cisco/kinetic/efm_server/server.json

Edit these settings to match the following lines:

"quarantine": true,
"allowAllLinks": false,

7. Update the cert.pem and key.pem files in /opt/cisco/kinetic/efm_server/certs/ to use a valid SSL certificate
   1. Make sure to change the permissions so only the efm user can read the private key and the certificate itself is secure from being overwritten

chmod 444 /opt/cisco/kinetic/efm_server/certs/cert.pem
chmod 400 /opt/cisco/kinetic/efm_server/certs/key.pem
rm /opt/cisco/kinetic/efm_server/certs/server.csr

These custom SSL certificate steps are optional, but recommended. There is a valid wildcard SSL certificate for iotvehicle.net available that can be used for this purpose. Otherwise, any valid SSL certificate that matches the regional EFM server FQDN can be used. Make sure the files are in plaintext PEM format.

8. Add the ParStream environment variables to the efm user’s .bashrc file

tee -a ~/.bashrc << EOT
# ParStream Settings
export PARSTREAM_HOME=/opt/cisco/kinetic/parstream
export LD_LIBRARY_PATH=\$PARSTREAM_HOME/lib:\$LD_LIBRARY_PATH
export PATH=\$PARSTREAM_HOME/bin:\$PATH
EOT

9. Refresh the .bashrc changes with a source ~/.bashrc or log out and log in again before proceeding to the next section

Start EFM and ParStream

1. Start EFM

Note that this is only one command with no line breaks

/opt/cisco/kinetic/dart-sdk/bin/dart /opt/cisco/kinetic/efm_server/bin/daemon.dart start

2. Start ParStream

cd /opt/cisco/kinetic/parstream/examples/noauthentication
parstream-server first &

3. Exit the SSH session and the server will continue running

Stopping EFM and ParStream

This information is for future reference only. Don’t do this right now.

If you need to stop the host VPS or VM to perform maintenance or take a snapshot, you’ll want to gracefully shut down EFM and ParStream first. You can follow the steps above to start them again.

1. Stop EFM

Note that this is only one command with no line breaks

/opt/cisco/kinetic/dart-sdk/bin/dart /opt/cisco/kinetic/efm_server/bin/daemon.dart stop

2. Stop ParStream

Pause between each command to make sure it has finished before continuing.

pnc -p 9042
ALTER SYSTEM CLUSTER SHUTDOWN;
quit;

Create the ParStream Demo Tables

1. Download and extract the ParStream tables

cd
mkdir sql
cd sql
wget -O parstream_tables.zip -L 'https://cisco.box.com/shared/static/3u5v2s97se3oajkskfm356sewb4herv3.zip'
unzip parstream_tables.zip
rm parstream_tables.zip

2. Install the ParStream tables

pnc -p 9042 < rwis_data.sql
pnc -p 9042 < crash_data.sql

You should see messages that say Table 'rwis_data' successfully created. and Table 'crash_data' successfully created.

3. Exit the SSH session

On to Chapter 4 RWIS and Car Simulator