Overview

This page presents an brief overview about webPA 2.0 (xmidt) components required for a reference webPA standalone server & establish an end-to-end connection with CPE devices.

Setting up a standalone Webpa Server

System Requirement

Process flow diagram

WebPA Server components setup

Below is the list of components needed for a Xmidt (webPA 2.0) cluster setup. For a single node reference setup, few of the services are not mandatory hence not used.

Dependencies of Build system

Install golang

Required for compiling server components written in go language. (Required version >=1.23)

Preferred version go version go1.24.2 linux/amd64
For Manual Installation:
Follow Go official site https://go.dev/doc/install
$rm -rf /usr/local/go && tar -C /usr/local -xzf go1.24.2.linux-amd64.tar.gz


** Add Below Lines to the profile file (.bash_profile etc.)
export GOROOT=/usr/local/go
export GOPATH=$HOME/go
export PATH=$PATH:/usr/local/go/bin


Verify the version with below:
$ go version
go version go1.24.2 linux/amd64

Downloading the source code

1. create a directory in $HOME say webpa_modules
$ mkdir $HOME/webpa_modules && cd $HOME/webpa_modules

2. Checkout the components from GitHub repository.
$ git clone https://github.com/xmidt-org/talaria
$ git clone https://github.com/xmidt-org/scytale
$ git clone https://github.com/xmidt-org/tr1d1um

Building the components

1. cd $HOME/webpa_modules/<component-name>
  e.g. cd webpa_modules/talaria
2. Build the component from source
	$ go build .

Similarly build for other modules

Configuring the server components 

Prerequisite

Generating a auth token

WebPA server components as well as requesting application has to use a authorization token for bearer authentication. We can either use a basic authorization token or make use of a key server for obtaining a bearer token.

For example, a UI application needs to invoke some Preference setting or to obtain some diagnostics information on behalf of a MSO partner, deviceId, serviceAccountId or combination of the three. It will first obtain or use a predefined AUTH token, set it as a HTTP header and then invoke the GET/SET operation.

However in the standalone setup, we have used basic base64 encoded authorization token because SAT requires access to operator specific key servers. This auth token will be used when configuring different webPA components as well while performing GET/SET requests to the CPE from a 3rd party application.

We can use either of the below 2 methods to generate a basic authorization string. 

Note: For newer releases the basic auth token should be in username:password format.
1. Using openssl command to generate the base64 encoded token.
[root@webpa-node1 ~]# openssl enc -base64 <<< "user123:webpa@1234567890"
[OUTPUT] : dXNlcjEyMzp3ZWJwYUAxMjM0NTY3ODkwCg==
2. Using Linux coreutils tools to generate the base64 encoded token
[root@webpa-node1 ~]# echo "user123:webpa@1234567890"|base64
[OUTPUT] : dXNlcjEyMzp3ZWJwYUAxMjM0NTY3ODkwCg==

Talaria configuration

Edit the configuration file & modify port values if you need to run talaria service in a different port (default value is 6200).

Sample talaria configuration  https://github.com/xmidt-org/talaria/blob/main/talaria.yaml

Modify https://github.com/xmidt-org/talaria/blob/main/talaria.yaml#L9

"server"          : Listening IP address (using "localhost" will allow connections only from the current machine.)

"address"       : Modify port number if required     https://github.com/xmidt-org/talaria/blob/main/talaria.yaml#L51

"certificateFile",   : Enable this section and update with server certificate files, if there are multiple certs can be combined as crt bundles  https://github.com/xmidt-org/talaria/blob/main/talaria.yaml#L60

Scytale configuration

Sample scyatle configuration : https://github.com/xmidt-org/scytale/blob/main/scytale.yaml

Edit the configuration file under /etc/scytale and modify following values

"fqdn"             : Fully qualified domain name of the server
"server"          : Listening IP address (using "localhost" will allow connections only from the current machine.)

"certificateFile"  : Enable this section and update with server certificate files, if there are multiple certs can be combined as crt bundles https://github.com/xmidt-org/scytale/blob/main/scytale.yaml#L52

"endpoints"    : Under "fanout" section, change the IP / Port value to match to the one where Talaria service is listening.

"authHeader" : Auth token Use the auth token which was generated in previous section

"file"                : Under "log" section, change the value from "stdout" to a file name if we need to redirect debug messages to a separate log file.

Tr1d1um configuration

Sample tr1d1um configuration: https://github.com/xmidt-org/tr1d1um/blob/main/tr1d1um.yaml

Edit the configuration file from /etc/tr1d1um to set following parameters

"fqdn"             : Fully qualified domain name of server

"server"          : IP Address/DNS to which the service has to listen

"version"        : Current version of the service

"region"          : Region of deployment

"flavor"           : Development, Production etc.

"address"       : Under "primary" section, change the value to point to the port where tr1d1um service will listen for incoming requests.

"targetURL"   : Change to IP-Address:Port value where SCYTALE service is running.

"authHeader" : Auth token Use the auth token which was generated in previous section.

For https add this section after this https://github.com/xmidt-org/tr1d1um/blob/main/tr1d1um.yaml#L59

tls:

certificates:

 - certificateFile: "/etc/cl-certs/primary-public.pem" keyFile:

"/etc/cl-certs/primary-private.pem"

 minVersion: 771 # 0x0303, the TLS 1.2 version uint16

Enable the services at boot-up

Create a systemd service as below.

[Unit]
Description=The Xmidt API interface server.
After=network.target remote-fs.target nss-lookup.target

[Service]
Type=simple
PIDFile=/run/talaria.pid
ExecStartPre=/usr/bin/rm -f /run/talaria.pid
ExecStart=/usr/bin/talaria
ExecReload=/bin/kill -s HUP $MAINPID
TimeoutStopSec=10
KillMode=process
PrivateTmp=true
Restart=always

[Install]
WantedBy=multi-user.target

Ubuntu uses a systemd based boot-up mechanism. Hence below commands will enable the required services.

$ sudo systemctl enable talaria
$ sudo systemctl enable scytale
$ sudo systemctl enable tr1d1um

WebPA Client Setup

Parodus is the client-end service running on the RDK-V CPE devices which establishes a connection with webPA service on device boot-up and delivers request-response between the webPA server & CPE device services. Parodus provides following functionalities in a CPE device.

Websocket client: Nopoll library used as Websocket Client.  It allows building pure WebSocket solutions or to provide WebSocket support to existing TCP oriented applications. Nopoll handles all the messages coming from or to the server asynchronously.

Nanomsg Server: Parodus acts as Nanomsg server to distribute messages upstream and downstream.

Configuring Parodus

RDK Video Devices

Edit parodus startup script for enabling the CPE device to use local webPA server

--webpa-url       :  Set with IP Address and Port of talaria service

--force-ipv4       : Force use of IPv4 for communication.

vi /etc/partners_defaults.json
Update the webpa server URL
"Device.X_RDK_WebPA_Server.URL" : "https://webpa.rdkcentral.com:8080",

Restart the service after changes are done.

# systemctl restart parodus

RDK Broadband Devices

Edit parodus startup script for enabling the CPE device to use local webPA server

ServerURL       :  Set to IP Address and Port of talaria service.

--force-ipv4       : Force use of IPv4 for communication.

vi /etc/device.properties
ServerURL=http://<webpa-ip>:8080

start the service after changes are done.

# systemctl restart parodus

Debugging & log files

Log files

server logs

• WebPA server logs are distributed among following locations.
  • /var/log/<webpa-service>/ : keeps debug log files.
    • • supervisord.log : Log messages related to service boot-up & initialization
      • console.out       : console logs (debug message will appear here if "file": "stdout" is configured in <webpa-service>.json file
  • /var/run/<webpa-service>/ : keeps service specific debug messages
    • <service-name>Log.log : component specific debug messages will appear here if "file" : "fileName.log" is configured in <webpa-service>.json file

Client logs

Parodus service log file is located as /opt/logs/parodus.log, provides debug information such as connection details, service initialization, which protocols are enabled/disabled etc.

Use cases

Downstream request

[External Application --> CPE Device] (e.g. Query from a dashboard application to request for how long has a specific router been up):

1. 1. 1. External service request goes to tr1d1um service
      2. tr1d1um forwards the request to Scytale API server cluster
      3. Scytale sends request to talaria server cluster
      4. Talaria then sends request to appropriate WebPA device

Upstream request

[CPE Device --> external service] (e.g. WebPA client notifications to external services, for instance, at boot time):

1. 1. 1. Request is sent through the same web socket connection that is established to Talaria
      2. Talaria sends request upstream to Scytale
      3. Scytale sends request to external service.

Using console command

AUTH_TOKEN       : Basic base64 encoded auth token or SAT (if enabled).

WEBPA-URL          : URL of Tr1d1um service in IP:PORT format.

DEVICE_MAC        :  MAC address of the CPE device.

PARAMETER         : GET/SET Parameter that need to be requested.

$ curl -H ''Authorization:Basic <AUTH_TOKEN>' -i http://<WEBPA-URL>/api/v2/device/mac:<DEVICE_MAC>/config?names=<PARAMETER>
e.g.
$ curl -H 'Authorization:Basic d2VicGFAMTIzNDU2Nzg5MA==' -i http://<WEBPA_SERVER_IP:PORT>/api/v2/device/mac:84e058575831/config?names=Device.DeviceInfo.ModelName

$ curl -X PATCH https://<IP>:9003/api/v2/device/mac:<MAC>/config -d '{"parameters": [ {"dataType": 0, "name": "<TR181_PARAM>", "value": "<Value-to-Set>"}]}' -H 'Authorization:Basic <TOKEN>' e.g.
$ curl -X PATCH https://webpa.rdkcentral.com:9003/api/v2/device/mac:aabbccddeeff/config -d '{"parameters": [ {"dataType": 0, "name": "Device.WiFi.SSID.10001.SSID", "value": "Testing"}]}' -H 'Authorization:Basic d2VicGFAMTIzNDU2Nzg5MAo='

List of connected Devices

$ curl -H "<AUTH_TOKEN>" http://<IP>:8080/api/v2/devices
e.g. curl -H "Authorization: Basic d2VicGFAMTIzNDU2Nzg5MA==" https://<webpa_serverURL>:8080/api/v2/devices

Common TR181 parameters