{"id":27940719,"url":"https://github.com/telecominfraproject/ols-ucentral-client","last_synced_at":"2025-05-07T10:19:59.500Z","repository":{"id":218578757,"uuid":"694452615","full_name":"Telecominfraproject/ols-ucentral-client","owner":"Telecominfraproject","description":"OpenLAN/Shasta contribution repo","archived":false,"fork":false,"pushed_at":"2025-01-31T21:50:04.000Z","size":25599,"stargazers_count":4,"open_issues_count":8,"forks_count":1,"subscribers_count":70,"default_branch":"main","last_synced_at":"2025-01-31T22:27:56.803Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Telecominfraproject.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-09-21T03:00:40.000Z","updated_at":"2025-01-27T14:36:10.000Z","dependencies_parsed_at":null,"dependency_job_id":"c5054aa5-ca1e-4173-967c-109416a04c37","html_url":"https://github.com/Telecominfraproject/ols-ucentral-client","commit_stats":null,"previous_names":["telecominfraproject/ols-ucentral-client"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Telecominfraproject%2Fols-ucentral-client","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Telecominfraproject%2Fols-ucentral-client/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Telecominfraproject%2Fols-ucentral-client/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Telecominfraproject%2Fols-ucentral-client/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Telecominfraproject","download_url":"https://codeload.github.com/Telecominfraproject/ols-ucentral-client/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252856697,"owners_count":21814881,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":"2025-05-07T10:19:58.802Z","updated_at":"2025-05-07T10:19:59.490Z","avatar_url":"https://github.com/Telecominfraproject.png","language":"C","funding_links":[],"categories":[],"sub_categories":[],"readme":"# What is it?\nThis repo holds the source code for OLS (OpenLAN Switching) uCentral client implementation.\nIt implements both the ZTP Gateway discovery procedure (calling the ZTP Redirector and locating\nthe desired Gateway to connect to), as well as handlers to process the Gateway requests.  \nUpon connecting to the Gateway service, the device can be provisioned and controlled from the\ncloud in the same manner as uCentral OpenWifi APs do.  \n\n# Build System\nThe build system implements an automated dockerized-based build enviroment to produce a final\ndeb package that can be installed on the target Sonic NOS.  \n\nThe deb file includes the uCentral Client docker image, that runs uCentral application.  The\nuCentral application establishes a secure connection with a uCentral-schema compatible Gateway\ncloud service. The GW service can then provision the device via this secure channel, and the\nuCentral application applies the configuration to the underlying device.\n\n## Build intermediate steps include:\n- Generation (and tagging) of docker image that acts as a dockerized build\n  enviroment (library dependencies and the uCentral app are built inside\n  this build-env img);\n- Compilation of the uCentral app (and libraries) inside the dockerized build\n  enviroment img;\n- Generation of ucentral-client docker image (consists of libraries that the\n  application depends on and the uCentral app itself);\n- Generation of the final deb pkg that can be installed to the target Sonic NOS\n  based device (consists of the ucentral-client docker image and service scripts\n  etc);\n\n# How to use the build system (all-in-once step):\n1. Build \u003call\u003e target (takes a while):\n```\nmake all\n```\n2. Copy final deb pkg from output/ folder (ucentral-client_1.0_amd64.deb) to the\n   target device;\n```\nfile output/*deb\n  output/ucentral-client_1.0_amd64.deb: Debian binary package (format 2.0)\nscp output/*deb \u003cremote_device\u003e\n```\n3. Install deb on the target device (requires root priv; must run on the target\n   device):\n```\ncd \u003cfolder where .deb was copied to\u003e;  \ndpkg -i ./ucentral-client_1.0_amd64.deb  \n```\n4. uCentral service should be up and runnig (automatically initiates GW discovery,\n  GW connect; connection should be established and device should be present\n  in the device list on the \u003cgw-ui\u003e webpage;  \n\n **_NOTE:_** TIP certs are not part of either final build img nor the build system\n       itself; these should be mounted / installed manually, or be present upon\n       service start;\n       Detailed GUIDE on how-to create cert partition / install certs can be found under\n       \u003cCertificates\u003e topic below.\n\n## Makefile targets\n**all**:  \nBuild whole project (build-host-env, ucentral-app, ucentral-docker-img, final deb)  \n\n**build-host-env**:  \nBuild *ONLY* build-host-enviroment (docker image): install toolchain, host utils,\nclone / build library dependencies (e.g. cJSON, libwebsockets etc).  \n\nLater on, this docker image used to create a docker container that compiles\nthe uCentral application itself.  \n\nDepends on the root Dockerfile: img is tagged with stripped SHA of Dockerfile\nto prevent redundant rebuilds of host-env img;  \n\nAlso exports img to an archive file that can be also shared / installed on another PC.  \nIt can be found under the following folder:  \noutput/docker-ucentral-client-build-env-${IMG_TAG}.gz  \n\n**run-host-env**:  \nStart host-build-enviroment docker container (a simple helper target for active development)  \n\n**run-ucentral-docker-img**:  \nRun created uCentral docker image (and uCentral application) locally.\nFor development / debug purposes only.  \n\n**build-ucentral-app**:  \nBuild (using host-build-enviroment docker img) the uCentral application (with\nall the lib dependencies).  \nCopy compiled binary (and library-dependencies) to the src/docker folder.  \n\n**build-ucentral-docker-img**:  \nBuild docker image, that holds the uCentral application (also libs deps).  \nDocker image (ucentral-client) is also created locally, so it can be launched\non host system as well.  \n\n**build-final-deb**:  \nTechnically same as 'all'. Produces final .deb pkg that can be copied to target\nand installed as native deb pkg.  \n\n# Certificates\nTIP Certificates should be preinstalled upon launch of the service. uCentral\nclient uses certificates to establish a secure connection with both Redirector\n(firstcontact), as well as te GW itself.  \n\nIn order to create a partition, partition_script.sh (part of this repo)\ncan be used to do so, the steps are as follows (should be executed on device):\nEnter superuser mode\n```\n$ sudo su\n```\nCreate temp directory to copy certificates + script into, and unpack\nCopy both certificates and partition script to the device:\n```\n$ mkdir /tmp/temp\n$ cd /tmp/temp/\n$ scp \u003cremote_host\u003e:/certificates/\u003csome_mac\u003e.tar ./\n$ scp \u003cremote_host\u003e:/partition_script.sh ./\n$ tar -xvf ./\u003csome_mac\u003e.tar\n```\nAfter certificate files are being unpacked, launch this script with single argument being\nthe path to the certificates directory (please note that BASH interpreter should be used explicitly,\nit's done to make this script compatible with most ONIE builds as well, as they mostly\npack busybox / sh):\n```\nbash ./partition_script.sh ./\n```\n  \nOnce certificates are installed and partition is created, rebooting the device is required.\nAfter reboot and uCentral start, service creates \u003cTCA\u003e volume upon start based on physical partition\n(by-label provided by udev - /dev/disk/by-label/ONIE-TIP-CA-CERT) automatically.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftelecominfraproject%2Fols-ucentral-client","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftelecominfraproject%2Fols-ucentral-client","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftelecominfraproject%2Fols-ucentral-client/lists"}