{"id":38501735,"url":"https://github.com/rdkcentral/xconfserver","last_synced_at":"2026-01-17T06:01:07.110Z","repository":{"id":37089977,"uuid":"301693592","full_name":"rdkcentral/xconfserver","owner":"rdkcentral","description":"Xconf is an open source, web based, device configuration application allowing users to configure parameters such as firmware rules, templates and configuration for devices with different MAC address, environment and model.","archived":false,"fork":false,"pushed_at":"2023-08-04T19:38:10.000Z","size":1901,"stargazers_count":7,"open_issues_count":5,"forks_count":13,"subscribers_count":10,"default_branch":"main","last_synced_at":"2023-08-04T19:51:57.549Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/rdkcentral.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"COPYING","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2020-10-06T10:43:14.000Z","updated_at":"2023-08-04T19:51:57.550Z","dependencies_parsed_at":"2023-01-22T14:01:02.454Z","dependency_job_id":null,"html_url":"https://github.com/rdkcentral/xconfserver","commit_stats":null,"previous_names":[],"tags_count":38,"template":null,"template_full_name":null,"purl":"pkg:github/rdkcentral/xconfserver","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rdkcentral%2Fxconfserver","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rdkcentral%2Fxconfserver/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rdkcentral%2Fxconfserver/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rdkcentral%2Fxconfserver/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rdkcentral","download_url":"https://codeload.github.com/rdkcentral/xconfserver/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rdkcentral%2Fxconfserver/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28501424,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-17T04:31:57.058Z","status":"ssl_error","status_checked_at":"2026-01-17T04:31:45.816Z","response_time":85,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-01-17T06:01:06.866Z","updated_at":"2026-01-17T06:01:07.046Z","avatar_url":"https://github.com/rdkcentral.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Table of Contents\n\u003c!--ts--\u003e\n* [XConf Overview](#xconf-overview)\n* [Architecture](#architecture)\n* [Run application](#run-application)\n    * [Local run](#local-run)\n* [Configuration](#configuration)\n    * [mTLS support](#mtls-support)\n* [Endpoints](#endpoints)\n    * [XConf Primary API](#xconf-primary-api)\n    * [Device Configuration Manager](#device-configuration-manager-dcm)\n    * [RDK Feature Control](#rdk-feature-control-rfc)\n* [Examples](#examples)\n    * [Get STB firmware version](#get-stb-firmware-version)\n    * [Get STB settings](#get-stb-settings)\n    * [Get Feature Settings](#get-feature-settings)\n    * [Rule Structure](#rule-structure)\n\u003c!--te--\u003e\n\n\n#XConf Overview\n\n***Important Note about Licensing:\nThe XConf Server uses the Bootstrap framework.  When building XConf Server, Bootstrap and other modules are pulled in by NPM.  Bootstrap contains a small set of Glyphicons.  According to the Bootstrap license, Bootstrap and the included Glyphicons are available to use commercially for free.  However, any party building and using XConf Server should review the licenses and make their own determination.\n\nXconf is slated to be the single entity for managing firmware on set-top boxes both in the field and in various \nwarehouses and test environments.\n\nXconf's primary purpose is to tell set-top boxes (STBs) what version of firmware they should be running. \nXconf does not push firmware to the STB, nor is not involved in any way in the actual download / upgrade process. \nIt simply tells the STB which version to use. Xconf also tells STBs when, where (host), and how (protocol) to get the firmware.\n\nXconf consists of two web applications, Xconf DataService and Xconf Admin. \nXconf DataService is the app that the STBs talk to. Xconf Admin allows humans to enter all the information necessary \nfor Xconf to provide the correct information to STBs.\n\nThe interface between STBs and Xconf is simple. STBs make HTTP requests to Xconf sending information like MAC address, \nenvironment, and model. Xconf then applies various rules to determine which firmware information to return. \nThe information is returned in JSON format.\n\n## Architecture\nRepository contains both projects: admin and dataservice.\n\n* Java 8\n* Spring MVC\n* Angular 1\n* Cassandra DB\n\n## Run application\n### Local run\nRelated to `xconf-dataservice` and `xconf-angular-admin`\n1. Run cassandra DB and create a corresponding scheme using `schema.cql` file from `xconf-angular-admin` or `xconf-dataservice` module.\n2. Use sample.service.properties to add/override specific environments properties.\n3. Create service.properties file with needed application properties in `resources` folder. \n4. Build project:\n```shell\nmvn clean install\n```\n5. Run application with the following command:\n```shell\nmvn jetty:run -DappConfig=${path-to-service-properties} -f pom.xml\n```\n\nor using Intellij IDEA:\ncreate maven task, put following command line option:\n```shell\njetty:run -DappConfig=${path-to-service-properties} -f pom.xml\n```\n\nNOTE: XConf UI is compiled using `frontend-maven-plugin` during `run` and `install` phase\n\n## Configuration\n### mTLS support\nTo enable mTLS support to connect to cassandra endpoint following properties should be used:\n```\ncassandra.useSsl=true\nssl.truststore.path=/path/to/your/truststore/file\nssl.truststore=Base64 encoded truststore\nssl.truststore.password=truststore-password\nssl.keystore.path=/path/to/your/keystore/file\nssl.keystore=Base64 encoded keystore\nssl.keystore.password=keystore-password\n```\n`ssl.truststore.path` or `ssl.truststore` can be used at the same time. Priority is `ssl.truststore`.\nIf `ssl.truststore` is set `ssl.truststore.path` is ignored.\nThe same is applied for `ssl.keystore.path` and `ssl.keystore`. Priority is `ssl.keystore`.\nIf `ssl.keystore` is set `ssl.keystore.path` is ignored.\n## Endpoints\n\n### XConf Primary API\n\n| PATH | METHOD | MAIN QUERY PARAMETERS | DESCRIPTION |\n|------|--------|-----------------------|-------------|\n| `/xconf/swu/{applicationType}` | `GET/POST` |`eStbMac`,\u003cbr\u003e`ipAddress`,\u003cbr\u003e`env`,\u003cbr\u003e`model`,\u003cbr\u003e`firmwareVersion`,\u003cbr\u003e`partnerId`,\u003cbr\u003e`accountId`,\u003cbr\u003e`{tag name}` - any tag from Tagging Service,\u003cbr\u003e`controllerId`,\u003cbr\u003e`channelMapId`,\u003cbr\u003e`vodId`| Returns firmwareVersion to STB box \u003cbr\u003e `{applicationType}` - for now supported `stb`, `xhome`, `rdkcloud` |\n| `/xconf/swu/bse` | `GET/PUT/POST` | `ipAddress` - required | Returns BSE configuration |\n| `/estbfirmware/changelogs` | `GET/PUT/POST` | `mac` - required | Returns logs of the communication between xconf and the given stb where xconf instructed stb to get different firmware |\n| `/estbfirmware/lastlog` | `GET/PUT/POST` | `mac` - required | Returns log of the last communication between xconf and the given stb |\n| `/estbfirmware/checkMinimumFirmware` | `GET/PUT/POST` | `mac` - required | Return if device has Minimum Firmware version |\n| `/xconf/{applicationType}`\u003cbr\u003e`/runningFirmwareVersion/info` | `GET/PUT/POST` | `mac` - required | Return if device has Activation Minimum Firmware and Minimum Firmware version |\n\n#### Headers \nFor `/xconf/swu/{applictionType}` API: \u003cbr\u003e\n`HA-Haproxy-xconf-http` to indicate if connection is secure\n\n\n### Device Configuration Manager (DCM)\n\nRemote devices like set top boxes and DVRs have settings to control certain activities. For instance, STBs need to know when to upload log files, or when to check for a new firmware update. In order to remotely manage a large population of devices, we need a solution that lets support staff define instructions and get the instructions to the devices.\n\n| PATH | METHOD | MAIN QUERY PARAMETERS | DESCRIPTION |\n|------|--------|-----------------------|-------------|\n| `/loguploader/getSettings`\u003cbr\u003e`/{applicationType}` | `GET/POST` | `estbMacAddress`,\u003cbr\u003e`ipAddress`,\u003cbr\u003e`env`,\u003cbr\u003e`model`,\u003cbr\u003e`firmwareVersion`,\u003cbr\u003e`partnerId`,\u003cbr\u003e`accountId`,\u003cbr\u003e`{tag name}` - any tag from Tagging Service,\u003cbr\u003e`checkNow` - boolean,\u003cbr\u003e`version`,\u003cbr\u003e`settingsType`,\u003cbr\u003e`ecmMacAddress`,\u003cbr\u003e`controllerId`,\u003cbr\u003e`channelMapId`,\u003cbr\u003e`vodId` | Returns settings to STB box \u003cbr\u003e `{applicationType}` - for now supported `stb`, `xhome`, `rdkcloud`, \u003cbr\u003efield is optional and `stb` application is used by default |\n| `/loguploader/getT2Settings`\u003cbr\u003e`/{applicatoionType}` | `GET` | The same as a previous | Returns telemetry configuration in the new format. If the component name has been defined for an entry, \u003cbr\u003ethe response will be in the new format. The second and third columns for that entry will not be used in the response. \u003cbr\u003eThe content field comes from the fifth column (component name). The type field will be a constant string `\u003cevent\u003e` |\n| `/loguploader/getTelemetryProfiles`\u003cbr\u003e`/{applicationType}` | `GET` | The same as a previous | Returns Telemetry 2.0 profiles based on Telemetry 2.0 rules |\n\n### RDK Feature Control (RFC)\n\n| PATH | METHOD | MAIN QUERY PARAMETERS | DESCRIPTION |\n|------|--------|-----------------------|-------------|\n| `/featureControl/getSettings`\u003cbr\u003e`/{applicationType}` | `GET/POST` | `estbMacAddress`,\u003cbr\u003e`ipAddress`,\u003cbr\u003e`env`,\u003cbr\u003e`model`,\u003cbr\u003e`firmwareVersion`,\u003cbr\u003e`partnerId`,\u003cbr\u003e`accountId`,\u003cbr\u003e`{tag name}` - any tag from Tagging Service,\u003cbr\u003e`ecmMacAddress`,\u003cbr\u003e`controllerId`,\u003cbr\u003e`channelMapId`,\u003cbr\u003e`vodId`| Returns enabled/disable features \u003cbr\u003e `{applicationType}` - for now supported `stb`, `xhome`, `rdkcloud`, field is optional and `stb` application is used by default |\n\n#### Headers\n`HA-Haproxy-xconf-http` - indicate if connection is secure \u003cbr\u003e\n`configsethash` - hash of previous response to return `304 Not Modified` http status\n\n## Examples\n\n### Get STB firmware version\n#### Request\n```shell script\ncurl --location --request GET 'https://${xconfds-path}/xconf/swu/stb?eStbMac=AA:AA:AA:AA:AA:AA\u0026env=DEV\u0026model=TEST_MODEL\u0026ipAddress=10.10.10.10'\n```\n#### Positive response\n```json\n{\n    \"firmwareDownloadProtocol\": \"http\",\n    \"firmwareFilename\": \"FIRMWARE-NAME.bin\",\n    \"firmwareLocation\": \"http://ssr.ccp.xcal.tv/cgi-bin/x1-sign-redirect.pl?K=10\u0026F=stb_cdl\",\n    \"firmwareVersion\": \"FIRMWARE_VERSION\",\n    \"rebootImmediately\": true\n}\n```\n\n### Get STB settings\n#### Request\n```shell script\ncurl --location --request GET 'https://${xconfds-path}/loguploader/getSettings/stb?estbMacAddress=AA:AA:AA:AA:AA:AA\u0026env=DEV\u0026model=TEST_MODEL\u0026ipAddress=10.10.10.10'\n```\n#### Positive response\n```json\n{\n  \"urn:settings:GroupName\": \"TEST_GROUP_NAME_1\",\n  \"urn:settings:CheckOnReboot\": false,\n  \"urn:settings:CheckSchedule:cron\": \"19 7 * * *\",\n  \"urn:settings:CheckSchedule:DurationMinutes\": 180,\n  \"urn:settings:LogUploadSettings:Message\": null,\n  \"urn:settings:LogUploadSettings:Name\": \"LUS-NAME\",\n  \"urn:settings:LogUploadSettings:NumberOfDays\": 0,\n  \"urn:settings:LogUploadSettings:UploadRepositoryName\": \"TEST-NAME\",\n  \"urn:settings:LogUploadSettings:UploadRepository:URL\": \"https://upload-repository-url.com\",\n  \"urn:settings:LogUploadSettings:UploadRepository:uploadProtocol\": \"HTTP\",\n  \"urn:settings:LogUploadSettings:UploadOnReboot\": false,\n  \"urn:settings:LogUploadSettings:UploadImmediately\": false,\n  \"urn:settings:LogUploadSettings:upload\": true,\n  \"urn:settings:LogUploadSettings:UploadSchedule:cron\": \"8 20 * * *\",\n  \"urn:settings:LogUploadSettings:UploadSchedule:levelone:cron\": null,\n  \"urn:settings:LogUploadSettings:UploadSchedule:leveltwo:cron\": null,\n  \"urn:settings:LogUploadSettings:UploadSchedule:levelthree:cron\": null,\n  \"urn:settings:LogUploadSettings:UploadSchedule:DurationMinutes\": 420,\n  \"urn:settings:VODSettings:Name\": null,\n  \"urn:settings:VODSettings:LocationsURL\": null,\n  \"urn:settings:VODSettings:SRMIPList\": null,\n  \"urn:settings:TelemetryProfile\": {\n    \"id\": \"c34518e8-0af5-4524-b96d-c2efb1904458\",\n    \"telemetryProfile\": [\n      {\n        \"header\": \"MEDIA_ERROR_NETWORK_ERROR\",\n        \"content\": \"NETWORK ERROR(10)\",\n        \"type\": \"receiver.log\",\n        \"pollingFrequency\": \"0\"\n      }\n    ],\n    \"schedule\": \"*/15 * * * *\",\n    \"expires\": 0,\n    \"telemetryProfile:name\": \"RDKV_DEVprofile\",\n    \"uploadRepository:URL\": \"https://upload-repository-host.tv\",\n    \"uploadRepository:uploadProtocol\": \"HTTP\"\n  }\n}\n```\n\n### Get Feature Settings\n#### Request\n```shell\ncurl --location --request GET 'http://${xconfds-path}/featureControl/getSettings?estbMacAddress=AA:AA:AA:AA:AA:AA' \\\n--header 'Accept: application/json'\n```\n\n#### Positive Response\n```json\n{\n    \"featureControl\": {\n        \"features\": [\n            {\n                \"name\": \"TEST_INSPECTOR\",\n                \"effectiveImmediate\": false,\n                \"enable\": true,\n                \"configData\": {},\n                \"featureInstance\": \"TEST_INSPECTOR\"\n            }\n        ]\n    }\n}\n```\n\n### Rule Structure\nThere are 6 different rule types: FirmwareRule, DCM Rule (Formula), TelemetryRule, TelemetryTwoRule, SettingRule and FeatureRule (RFC Rule).\n\nExtended from `Rule` object: `DCM Rule`, `TelemetryRule`, `TelemetryTwoRule`. It means that rule object itself has rule structure, corresponding rule fields like `negated`, `condition`, `compoundParts` and `relation` are located in root json object itself.\n\nOtherwise there is rule field.\n\n`TelemetryRule` json extended by `Rule` object:\n\n```json\n{\n    \"negated\": false,\n    \"compoundParts\": [\n    {\n        \"negated\": false,\n        \"condition\":\n        {\n            \"freeArg\":\n            {\n                \"type\": \"STRING\",\n                \"name\": \"model\"\n            },\n            \"operation\": \"IS\",\n            \"fixedArg\":\n            {\n                \"bean\":\n                {\n                    \"value\":\n                    {\n                        \"java.lang.String\": \"TEST_MODEL1\"\n                    }\n                }\n            }\n        },\n        \"compoundParts\": []\n    },\n    {\n        \"negated\": false,\n        \"relation\": \"OR\",\n        \"condition\":\n        {\n            \"freeArg\":\n            {\n                \"type\": \"STRING\",\n                \"name\": \"model\"\n            },\n            \"operation\": \"IS\",\n            \"fixedArg\":\n            {\n                \"bean\":\n                {\n                    \"value\":\n                    {\n                        \"java.lang.String\": \"TEST_MODEL2\"\n                    }\n                }\n            }\n        },\n        \"compoundParts\": []\n    }],\n    \"boundTelemetryId\": \"ad10dd05-d2ff-4d00-8f52-b0ca6956cde6\",\n    \"id\": \"fb4210ac-8187-4cba-9301-eb8f27fcdaa8\",\n    \"name\": \"Arris_SVG\",\n    \"applicationType\": \"stb\"\n}\n```\n\n\n`FeatureRule` json, which contains `Rule` object\n```json\n{\n    \"id\": \"018bfb79-4aaf-426e-9e45-17e26d52ad49\",\n    \"name\": \"Test\",\n    \"rule\":\n    {\n        \"negated\": false,\n        \"condition\":\n        {\n            \"freeArg\":\n            {\n                \"type\": \"STRING\",\n                \"name\": \"estbMacAddress\"\n            },\n            \"operation\": \"IS\",\n            \"fixedArg\":\n            {\n                \"bean\":\n                {\n                    \"value\":\n                    {\n                        \"java.lang.String\": \"AA:AA:AA:AA:AA:AA\"\n                    }\n                }\n            }\n        },\n        \"compoundParts\": []\n    },\n    \"priority\": 13,\n    \"featureIds\": [\"68add112-cdc9-47be-ae3b-86e753c8d23e\"],\n    \"applicationType\": \"stb\"\n}\n```\n\n#### Rule Object\nThere are following fields there:\u003cbr\u003e\n`negated` - means condition is with `not` operand.\u003cbr\u003e\n`condition` - key and value statement.\u003cbr\u003e\n`compoundParts` - list with multiple conditions.\u003cbr\u003e\n`relation` - operation between multiple conditions, possible values `OR`, `AND`.\n\n#### Condition structure\nEach condition has `freeArg` and `fixedArg` field.\nfreeArg typed key.\nfixedArg value meaning.\n\nIf rule has only one condition there are no `compoundParts`, `relation` field is empty.\nIf there are more than one condition - they are located in `compoundParts` object. First condition does not have any relation, next one has a relation.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frdkcentral%2Fxconfserver","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frdkcentral%2Fxconfserver","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frdkcentral%2Fxconfserver/lists"}