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

> 10 GB free space

Operating system	Ubuntu 24.04
Architecture	x86_64
Memory	> 2048 MB
Disk space

Tip
It is good to disable the firewall (iptables ) during initial setup for avoiding connection related confusions.

...

draw.io Diagram


diagramName	xmidt-basic-cluster.drawio
diagramWidth	1130
height	598
revision	13

WebPA Server components setup

...

Component	Type	Description	Used in current setup
Talaria	Server	Talaria maintains the secure websocket connections from the device and passes the messages from or to the device.	Yes
Scytale	Server	Scytale accepts the inbound requests and delivers the messages to the Talaria machines that could be hosting the device connection.	Yes
tr1d1um	Server	The Webpa micro-service that encode TR-181 requests.	Yes
petasos	Server	Petasos helps reduce the load on the Talaria machines by calculating which specific Talaria a device should connect to & redirecting the incoming request.	No
caduceus	Server	Caduceus provides the pub-sub message delivery (notification) mechanism for xmidt.	No
parodus	Client	Parodus is the light weight client that reaches out to the xmidt cloud to establish the connection from CPE devices.	Yes

...

"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

Reference talaria.yaml

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" endpoints" : Under "fanout" section, change the IP / Port value to match to the one where Talaria service is listening.

...

"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.Add the "aws" section with following values for suppressing few error messages Anchorfake-awsfake-aws

...

Reference scytale.yaml

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

Reference for yaml file tr1d1um.yaml

Enable the services at boot-up

Create a systemd service as below.

Code Block

[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

Panel
Note

This will set AWS & SNS parameters with fake ones since we don't use actual keys and SNS (amazon simple notification service) in the current setup.

Code Block

title	Sample configuration [/etc/scytale/scytale.yaml]

---

########################################
#   Labeling/Tracing via HTTP Headers Configuration
########################################

# The unique fully-qualified-domain-name of the server.  It is provided to
# the X-Scytale-Server header for showing what server fulfilled the request
# sent.
# (Optional)
server: "xxx.xxx.xxx.xxx"

# Provides this build number to the X-Tr1d1um-Build header for
# showing machine version information.  The build number SHOULD
# match the scheme `version-build` but there is not a strict requirement.
# (Optional)
build: "0.1.4-1"

# Provides the region information to the X-Tr1d1um-Region header
# for showing what region this machine is located in.  The region
# is arbitrary and optional.
# (Optional)
region: "east"

# Provides the flavor information to the X-Tr1d1um-Flavor header
# for showing what flavor this machine is associated with.  The flavor
# is arbitrary and optional.
# (Optional)
flavor: "mint"


##############################################################################
# WebPA Service configuration
##############################################################################

# For a complete view of the service config structure,
# checkout https://godoc.org/github.com/Comcast/webpa-common/server#WebPA

########################################
#   Primary Endpoint Configuration
########################################

# primary provides the configuration for the main server for this application
primary:
  address: ":7000"

########################################
#   Health Endpoint Configuration
########################################

# health defines the details needed for the health check endpoint.  The
# health check endpoint is generally used by services (like AWS Route53
# or consul) to determine if this particular machine is healthy or not.
health:
  address: ":7001"

########################################
#   Debugging/Pprof Configuration
########################################

# pprof defines the details needed for the pprof debug endpoint.
# (Optional)
pprof:
  address: ":7002"

########################################
#   Metrics Configuration
########################################

# metric defines the details needed for the prometheus metrics endpoint
# (Optional)
metric:
  address: ":7082"
  metricsOptions:
    # namespace is the namespace of the metrics provided
    # (Optional)
    namespace: "webpa"

    # subsystem is the subsystem of the metrics provided
    # (Optional)
    subsystem: "scytale"

fanout:
  fanoutTimeout: "125s"
  clientTimeout: "45s"
  endpoints:
      - "http://localhost:8080/api/v2/device"
  authorization: <xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx>

########################################
#   Logging Related Configuration
########################################

# log configures the logging subsystem details
log:
  # file is the name of the most recent log file.  If set to "stdout" this
  # will log to os.Stdout.
  # (Optional) defaults to os.TempDir()
  file: "/var/log/scytale/scytale.log"

  # level is the logging level to use - INFO, DEBUG, WARN, ERROR
  # (Optional) defaults to ERROR
  level: "DEBUG"

  # maxsize is the maximum log file size in MB
  # (Optional) defaults to max 100MB
  maxsize: 50

  # maxage is the maximum number of days to retain old log files
  # (Optional) defaults to ignore age limit (0)
  maxage: 30

  # maxbackups is the maximum number of old log files to retain
  # (Optional) defaults to retain all (0)
  maxbackups: 10

  # json is a flag indicating whether JSON logging output should be used.
  # (Optional) defaults to false
  json: true
aws:
  accessKey: "fake-accessKey"
  secretKey: "fake-secretKey"
  env: "fake-env"
  sns:
    awsEndpoint: http://goaws:4100
    region: "ap-east-1"
    topicArn: "arn:aws:sns:ap-east-1:999999999991:fake-env"
    urlPath: "/api/v2/aws/sns"
waitForDns: 0
authHeader: ["xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"]
start:
  duration: 1
  apiPath: http://127.0.0.1:6300/hooks
  authHeader: <xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx>

Tr1d1um configuration

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

"fqdn" : Fully qualified domain name of server

"server" : IP Address 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.

"aws" : Add fake values as described previously.

Code Block

title	Sample configuration file [/etc/tr1d1um/tr1d1um.yaml]

---

########################################
#   Labeling/Tracing via HTTP Headers Configuration
########################################

# The unique fully-qualified-domain-name of the server.  It is provided to
# the X-Tr1d1um-Server header for showing what server fulfilled the request
# sent.
# (Optional)
server: "xxx.xxx.xxx.xxx"

# Provides this build number to the X-Tr1d1um-Build header for
# showing machine version information.  The build number SHOULD
# match the scheme `version-build` but there is not a strict requirement.
# (Optional)
build: "0.1.2-1"

# Provides the region information to the X-Tr1d1um-Region header
# for showing what region this machine is located in.  The region
# is arbitrary and optional.
# (Optional)
region: "east"

# Provides the flavor information to the X-Tr1d1um-Flavor header
# for showing what flavor this machine is associated with.  The flavor
# is arbitrary and optional.
# (Optional)
flavor: "mint"


##############################################################################
# WebPA Service configuration
##############################################################################

# For a complete view of the service config structure,
# checkout https://godoc.org/github.com/Comcast/webpa-common/server#WebPA

########################################
#   Primary Endpoint Configuration
########################################

# primary provides the configuration for the main server for this application
primary:
  address: ":9003"

########################################
#   Health Endpoint Configuration
########################################

# health defines the details needed for the health check endpoint.  The
# health check endpoint is generally used by services (like AWS Route53
# or consul) to determine if this particular machine is healthy or not.
health:
  address: ":9004"

########################################
#   Debugging/Pprof Configuration
########################################

# pprof defines the details needed for the pprof debug endpoint.
# (Optional)
pprof:
  address: ":9005"

########################################
#   Metrics Configuration
########################################

# metric defines the details needed for the prometheus metrics endpoint
# (Optional)
metric:
  address: ":9082"
  metricsOptions:
    # namespace is the namespace of the metrics provided
    # (Optional)
    namespace: "webpa"

    # subsystem is the subsystem of the metrics provided
    # (Optional)
    subsystem: "tr1d1um"

########################################
#   Logging Related Configuration
########################################

# log configures the logging subsystem details
log:
  # file is the name of the most recent log file.  If set to "stdout" this
  # will log to os.Stdout.
  # (Optional) defaults to os.TempDir()
  file: "/var/log/tr1d1um/tr1d1um.log"

  # level is the logging level to use - INFO, DEBUG, WARN, ERROR
  # (Optional) defaults to ERROR
  level: "DEBUG"

  # maxsize is the maximum log file size in MB
  # (Optional) defaults to max 100MB
  maxsize: 50

  # maxage is the maximum number of days to retain old log files
  # (Optional) defaults to ignore age limit (0)
  maxage: 30

  # maxbackups is the maximum number of old log files to retain
  # (Optional) defaults to retain all (0)
  maxbackups: 10

  # json is a flag indicating whether JSON logging output should be used.
  # (Optional) defaults to false
  json: true


##############################################################################
# Webhooks Related configuration
##############################################################################

# webhooksEnabled indicates whether or not the webhooks server should be started
# It is disabled for local testing
webhooksEnabled: false

# The unique fully-qualified-domain-name of the server.  The webhooks library uses it
# to know which host to use to confirm this service is ready to receive events
# (Optional if not running webhooks)
fqdn: "tr1d1um-local-instance-123.example.com"

# start contains configuration for the logic by which Tr1d1um can
# fetch the current WebPA webhooks without having to wait for SNS
# It does so by pinging the rest of the cluter at the specified apiPath
# More detaisl at https://godoc.org/github.com/Comcast/webpa-common/webhook#StartConfig
start:
  # duration is the max amount of time allowed to wait for webhooks data to be retrieved
  duration: "20s"

  # path used to query the existing webhooks
  apiPath: http://localhost:6100/hooks

########################################
# Webhooks DNS readiness Configuration
########################################

# WaitForDns is the duration the webhooks library will wait for this server's DNS record to be
# propagated. This waiting logic is important so AWS SNS webhook confirmations are not missed
waitForDns: "30s"

#soa stands for Start of Authority and it's a type of record in a DNS
soa:
  # provider is the SOA provider used to verify DNS record readiness of this service
  provider: "example-123.awsdns-00.com:17"

########################################
# Webhooks AWS SNS Configuration
########################################

# aws provides the AWS SNS configurations the webhooks library needs
aws:
  #AWS access key
  accessKey: "fake-accessKey"

  #AWS secret key
  secretKey: "fake-secretKey"

  env: local-dev

  sns:
    # awsEndpoint is the AWS endpoint
    # this must be left out in produ
    awsEndpoint: http://goaws:4100

    #region is the AWS SNS region
    region: "us-east-1"

    # topicArn describes the SNS topic this server needs to subscribe to
    topicArn: arn:aws:sns:us-east-1:000000000000:xmidt-local-caduceus

    #urlPath is the URL path SNS will use to confirm a subscription with this server
    urlPath: "/api/v2/aws/sns"


##############################################################################
# Testing Authorization Credentials
##############################################################################

# authHeader is a list of Basic Auth credentials intended to be used for local testing purposes
# WARNING! Be sure to remove this from your production config
authHeader: "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"


##############################################################################
# WRP and XMiDT Cloud configurations
##############################################################################

# targetURL is the base URL of the XMiDT cluster
targetURL: http://localhost:7000

# WRPSource is used as 'source' field for all outgoing WRP Messages
WRPSource: "dns:tr1d1um.xmidt.comcast.net"

# supportedServices is a list of endpoints we support for the WRP producing endpoints
# we will soon drop this configuration
supportedServices:
  - "config"


##############################################################################
# HTTP Transaction Configurations
##############################################################################

# clientTimeout is the timeout for the HTTP clients used to contact the XMiDT cloud
clientTimeout: "135s"

# respWaitTimeout is the max time Tr1d1um will wait for responses from the XMiDT cloud
respWaitTimeout: "129s"

# netDialerTimeout is the timeout used for the net dialer used within HTTP clients
netDialerTimeout: "5s"

# requestRetryInterval is the time between HTTP request retries against XMiDT
requestRetryInterval: "2s"

# requestMaxRetries is the max number of times an HTTP request is retried against XMiDT in
# case of ephemeral errors
requestMaxRetries: 2

Enable the services at boot-up

Create a systemd service as below.

Code Block

[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

Panel
Note: Copy the talaria, scytale, tr1d1um binaries to /usr/bin and respective yaml file to /etc directory. For talaria, yaml location is /etc/talaria/talaria.yaml similarly for scytale and tr1d1um.

...

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

...

.

Configuring Parodus

RDK -E Devices

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

...

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
  - - : console logs (debug message will appear here if "file": "
  - - stdout" is

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.

Common Errors

Service fails to start (Specific to older CentOS 6.x releases)

When we see an error similar to the below, it is related to zookeeper service failed to load or not running currently. restarting zookeeper & subsequent restart of other services solves the issue.

...

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

...

Code Block

language	java
title	SET Parameter

$ curl -X PATCH httphttps://<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 httphttps://35webpa.155rdkcentral.171.121com:9003/api/v2/device/mac:b827eb5681cdaabbccddeeff/config -d '{"parameters": [ {"dataType": 0, "name": "Device.WiFi.SSID.10001.SSID", "value": "Testing"}]}' -H 'Authorization:Basic d2VicGFAMTIzNDU2Nzg5MAo='

...

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

...

Panel

Device.DeviceInfo.Manufacturer
Device.DeviceInfo.ManufacturerOUI
Device.DeviceInfo.ModelName
Device.DeviceInfo.SerialNumber
Device.DeviceInfo.HardwareVersion
Device.DeviceInfo.SoftwareVersion
Device.DeviceInfo.UpTime
Device.DeviceInfo.ProcessorNumberOfEntries
Device.DeviceInfo.MemoryStatus.Total
Device.DeviceInfo.MemoryStatus.Free
Device.DeviceInfo.ProcessStatus.CPUUsage
Device.DeviceInfo.ProcessStatus.ProcessNumberOfEntries

For bringing up the webpa module as a container refer this page Webpa containerization

RDK Resources

[RDK Preferred]

Code Management Facility

RDK Forums

[RDK Conferences]

RDK Support

Archives

Versions Compared

Old Version 3

New Version Current

Key

Setting up a

standalone Webpa Server

System Requirement

WebPA Server components setup

Scytale configuration

Tr1d1um configuration

Enable the services at boot-up

Tr1d1um configuration

Enable the services at boot-up

Configuring Parodus

RDK Video Devices

Configuring Parodus

RDK -E Devices

Client logs

Common Errors

Service fails to start (Specific to older CentOS 6.x releases)

Client logs

Use cases

Downstream request

RDK Resources

[*RDK Preferred*]

Code Management Facility

RDK Forums

[RDK Conferences]

RDK Support

Archives

Page History

Versions Compared

Old Version 3

New Version Current

Key

Setting up a

standalone Webpa Server

System Requirement

WebPA Server components setup

Scytale configuration

Tr1d1um configuration

Enable the services at boot-up

Tr1d1um configuration

Enable the services at boot-up

Configuring Parodus

RDK Video Devices

Configuring Parodus

RDK -E Devices

Client logs

Common Errors

Service fails to start (Specific to older CentOS 6.x releases)

Client logs

Use cases

Downstream request

[RDK Preferred]