These are quickstart notes on how to install pmgrpcd.py and all of its
dependencies. CONFIG-KEYS.pmgrpcd provides the documentation for all of
pmgrpcd.py configuration parameters.

Install pmgrpcd.py
===================

shell> mkdir -p /opt/pkg/
shell> git clone https://github.com/pmacct/pmacct.git /opt/pkg/pmacct
shell> ln -s /opt/pkg/pmacct/telemetry/decoders/v3 /opt/pkg/pmgrpcd
shell> chmod 700 /opt/pkg/pmgrpcd/pmgrpcd.py

Install protoc
--------------
Install system dependencies:

shell> sudo yum install tar wget autoconf libtool automake gcc-c++ make git bzip2 curl unzip zlib zlib-devel -y [CentOS/RHEL]
shell> sudo apt-get install tar wget autoconf libtool automake g++ make git bzip2 curl unzip zlib1g-dev [Debian/Ubuntu]

Obtain and compile GPB code:

shell> git clone https://github.com/protocolbuffers/protobuf.git /opt/pkg/protobuf
shell> cd /opt/pkg/protobuf
shell> ./autogen.sh
shell> ./configure
shell> make
shell> make install
shell> ldconfig

shell> protoc --version

Python interpreter
------------------
It is recommended to use Python >= 3.7 although the code would work
with less recent Python 3 interpreters (ie. 3.5 and 3.6). The Command
Line examples in the remainder of this document will assume the use of
python3.7.

Install Python dependencies
---------------------------
shell> python3.7 -m pip install -r requirements.txt

Setup PYTHONPATH
----------------
This is an environment variable which you can set to add additional
directories where python will look for modules and packages. Setting
PYTHONPATH is required (for the time being) to look for .py files in
sub-directories. The following example is based on bash shell:

shell> PYTHONPATH=/opt/pkg/pmgrpcd/protos:/opt/pkg/pmgrpcd/zmq_modules:/opt/pkg/pmgrpcd/kafka_modukes:/opt/pkg/pmgrpcd/file_modules:/etc/pmacct/telemetry/pblib
shell> export PYTHONPATH

Compile grpc libs (L1)
----------------------
shell> mkdir -p /etc/pmacct/telemetry/pblib

Copy gRPC .proto file(s) (ie. huawei-grpc-dialout.proto) to
/etc/pmacct/telemetry/pblib (some sample .proto files for testing
purposes are available in the protos/ directory and can be copied
over).

shell> cd /etc/pmacct/telemetry/pblib/
shell> python3.7 -m grpc_tools.protoc -I. --python_out=. --grpc_python_out=. huawei-grpc-dialout.proto
shell> python3.7 -m grpc_tools.protoc -I. --python_out=. --grpc_python_out=. cisco_grpc_dialout.proto

Compile PB libs (L2/3)
----------------------
shell> cd /etc/pmacct/telemetry/pblib/
shell> /usr/local/bin/protoc -I=. --python_out=. ./huawei-grpc-dialout.proto
shell> /usr/local/bin/protoc -I=. --python_out=. ./cisco_grpc_dialout.proto
shell> /usr/local/bin/protoc -I=. --python_out=. ./huawei-telemetry.proto
shell> /usr/local/bin/protoc -I=. --python_out=. ./huawei-ifm.proto
shell> /usr/local/bin/protoc -I=. --python_out=. ./huawei-devm.proto
shell> /usr/local/bin/protoc -I=. --python_out=. ./openconfig-interfaces.proto

First Run pmgrpcd.py
--------------------
shell> cd /opt/pkg/pmgrpcd && python3.7 ./pmgrpcd.py -h

Scenario 1: ZMQ output to pmtelemetryd
--------------------------------------
Export of JSON-encoded Streaming Telemetry data to pmtelemetryd allows
to quickly access all daemon features, ie. save to files, produce to
Kafka, stream/log data out or dump at regular intervals, etc.

The default configuration in config_files/telemetry.conf is suitable
for this scenario. If collecting from Cisco 'cisco = True' should be
set; if collecting from Huawei 'huawei = True' should be set. The
configuration instructs pmgrpcd to listen for Streaming Telemetry data
on port 10000 and export it via ZMQ on port 50000:

shell> python3.7 ./pmgrpcd.py -N

pmtelemetryd can be configured as follows to read data from a ZeroMQ on
port 50000 and stream/log it to local files:

telemetry_daemon_zmq_address: 127.0.0.1:50000
telemetry_daemon_decoder: json
!
telemetry_daemon_msglog_file: /path/to/spool/telemetry-msglog-$peer_src_ip.json
telemetry_daemon_msglog_output: json

Or pmtelemetryd can be configured as follows to read data from a ZeroMQ
on port 50000 and produce it to a Kafka broker:

telemetry_daemon_zmq_address: 127.0.0.1:50000
telemetry_daemon_decoder: json
!
telemetry_dump_kafka_broker_host: <Kafka broker IP address/hostname>
telemetry_dump_kafka_broker_port: 9092
telemetry_dump_kafka_topic: pmacct.streaming-telemetry.test
telemetry_dump_refresh_time: 60

Concluding notes
----------------
The default config being read is config_files/telemetry.conf .
To learn more about all configuration directives see the document
CONFIG-KEYS.pmgrpcd .