{"id":27940720,"url":"https://github.com/telecominfraproject/openlan-cgw","last_synced_at":"2025-08-18T03:32:34.402Z","repository":{"id":226093950,"uuid":"767687339","full_name":"Telecominfraproject/openlan-cgw","owner":"Telecominfraproject","description":null,"archived":false,"fork":false,"pushed_at":"2025-04-17T09:10:14.000Z","size":3481,"stargazers_count":6,"open_issues_count":1,"forks_count":5,"subscribers_count":62,"default_branch":"main","last_synced_at":"2025-06-28T08:47:17.809Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Rust","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,"zenodo":null}},"created_at":"2024-03-05T18:10:39.000Z","updated_at":"2025-03-24T14:59:23.000Z","dependencies_parsed_at":"2024-03-05T21:26:30.523Z","dependency_job_id":"cb8a9a9d-76d1-4eb0-ba2e-c61cf50c2066","html_url":"https://github.com/Telecominfraproject/openlan-cgw","commit_stats":null,"previous_names":["telecominfraproject/openlan-cgw"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/Telecominfraproject/openlan-cgw","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Telecominfraproject%2Fopenlan-cgw","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Telecominfraproject%2Fopenlan-cgw/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Telecominfraproject%2Fopenlan-cgw/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Telecominfraproject%2Fopenlan-cgw/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Telecominfraproject","download_url":"https://codeload.github.com/Telecominfraproject/openlan-cgw/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Telecominfraproject%2Fopenlan-cgw/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":270940377,"owners_count":24671669,"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","status":"online","status_checked_at":"2025-08-18T02:00:08.743Z","response_time":89,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":"2025-05-07T10:19:59.921Z","updated_at":"2025-08-18T03:32:34.382Z","avatar_url":"https://github.com/Telecominfraproject.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# openlan-cgw - What is it?\nCloud GateWay (CGW) is a Rust-based implementation of the uCentral-protocol-based Gateway layer (link).\nCGW, like OWGW, manages device (Access Points and OpenLan switches) that implement and abide the uCentral protocol.\nThe main reasoning behind a new implementation of the GW is the horizontal scalability.\n# Dependencies (runtime)\nCGW requires a set of tools and services to operate and function. Some of them are embedded into the application itself and require no external utilities,\nwhile others are required to be running for the CGW to operate. \n\n**NOTE**: while runtime CGW depends on services like kafka, redis and PGSQL, the *make* / *make all* targets\nwould build a complete out-of-the-box setup with default configs and container params: \n- Kafka, Redis, PGSQL containers would be created and attached to default - automatically created - *docker_cgw_multi_instances_network* network; \n  All three (and one additional - *init-broker-container* - needed for kafka topics initialization) are all part of single docker compose file. \n- CGW, while also part of the same docker compose file, yet is being partially generated. \n  The reason, is that multiple CGW instances can be created within single compose-file,\nand thus container details are being generated. \n\nMore information about the compose generation can be found in the\n'Automated multi-CGW instances start/stop with Docker Compose' topic.\n\n## gRPC\nCGW utilizes gRPC to communicate with other CGW instances (referred to as Shards). This functionality does not depend on some external thirdparty services.\n## Kafka\nCGW uses Kafka as a main North-Bound API layer for communication with NB services. CnC topic is used for commands and requests handling, CnC_Res is used to send replies/results back (CGW reads CnC and writes into CnC_Res).\n### Requirements\nIt's required for the Kafka to have the following topics premade upon CGW launch:\n1. \"CnC\"     - Kafka consumer topic\n2. \"CnC_Res\" - Kafka producer topic\n## PSQL\nApplication utilizes relational DB (PSQL) to store registered Infrastructure Groups as well as registered Infrastructures.\n### Requirements\n1. It's required for the PSQL to have the following tables premade upon CGW launch:\n```\nCREATE TABLE infrastructure_groups\n(\nid INT PRIMARY KEY,\nreserved_size INT,\nactual_size INT\n);\nCREATE TABLE infras\n(\nmac MACADDR PRIMARY KEY,\ninfra_group_id INT,\nFOREIGN KEY(infra_group_id) REFERENCES infrastructure_groups(id) ON DELETE CASCADE\n);\n```\n2. Default user 'cgw' and password '123' is assumed, but it can be changed through the env variables.\n## Redis\nfast in-memory DB that CGW uses to store all needed runtime information (InfraGroup assigned CGW id, remote CGW info - IP, gRPC port etc)\n# Building\n*NOTE:* The following target builds CGW and also starts up required services with default config and params\n```console\n$ make all\n```\nTwo new docker images will be generated on host system:\n**openlan_cgw** - image that holds CGW application itself\n**cgw_build_env** - building enviroment docker image that is used for generating openlan_cgw\n# Running\nThe following script can be used to launch the CGW app\n```console\n$ make\n```\nCommand creates and executed (starts) docker container group consisting of cgw services\nas well as thirdpart depending services (redis, kafka, pgsql) \n\nTo stop the container from running (remove it) use the following cmd:\n```console\n$ make stop\n```\nRunning application with default arguments might not be desired behavior.\nAnd thus the run script utilizes the following list of *enviroment* variables that you can define before running it to alternate behavior of the app.\nThe following list is a list of enviroment variables you can define to configure cgw-app behavior in certain way:\n```\nCGW_ID                            - Shard ID\nCGW_GROUPS_CAPACITY               - The CGW instance groups capacity\nCGW_GROUPS_THRESHOLD              - The CGW instance groups threshold\nCGW_GROUP_INFRAS_CAPACITY         - The devices capacity for group\nCGW_GRPC_LISTENING_IP             - IP to bind gRPC server to (listens for gRPC requests from remote CGWs)\nCGW_GRPC_LISTENING_PORT           - Port to bind gRPC server to (listens for gRPC requests from remote CGWs)\nCGW_GRPC_PUBLIC_HOST              - IP or hostname for Redis record (remote CGWs will connect to this particular shard through provided host record;\n                                    it's up to deployment config whether remote CGW#1 will be able to access this CGW#0, for example, through provided hostname/IP)\nCGW_GRPC_PUBLIC_PORT              - PORT for Redis record\nCGW_WSS_IP                        - IP to bind websocket server to (listens for incoming WSS connections from underlying devices - infrastructures)\nCGW_WSS_PORT                      - PORT to bind WSS server to\nCGW_WSS_CAS                       - Web socket CAS certificate file name\nCGW_WSS_CERT                      - Web socket server certificate file name\nCGW_WSS_KEY                       - Web socket server private key file name\nCGW_KAFKA_HOST                    - IP or hostname of remote KAFKA server to connect to (NB API)\nCGW_KAFKA_PORT                    - PORT of remote KAFKA server to connect to\nCGW_DB_HOST                       - IP or hostname of remote database server to connect to\nCGW_DB_PORT                       - PORT of remote database server to connect to\nCGW_DB_USER                       - PSQL DB username (credentials) to use upon connect to DB\nCGW_DB_PASS                       - PSQL DB password (credentials) to use upon connect to DB\nCGW_DB_TLS                        - Utilize TLS connection with DB server\nCGW_REDIS_HOST                    - IP or hostname of remote redis-db server to connect to\nCGW_REDIS_PORT                    - PORT of remote redis-db server to connect to\nCGW_REDIS_USERNAME                - REDIS username (credentials) to use upon connect to\nCGW_REDIS_PASSWORD                - REDIS password (credentials) to use upon connect to\nCGW_REDIS_TLS                     - Utilize TLS connection with REDIS server\nCGW_LOG_LEVEL                     - Log level to start CGW application with (debug, info)\nCGW_METRICS_PORT                  - PORT of metrics to connect to\nCGW_CERTS_PATH                    - Path to certificates located on host machine\nCGW_ALLOW_CERT_MISMATCH           - Allow client certificate CN and device MAC address mismatch (used for OWLS)\nCGW_NB_INFRA_CERTS_DIR            - Path to NB infrastructure (Redis, PostgreSQL) certificates located on host machine\nCGW_NB_INFRA_TLS                  - Utilize TLS connection with NB infrastructure (Redis, PostgreSQL)\n                                    If set enabled - the CGW_DB_TLS and CGW_REDIS_TLS values will be ignored and\n                                    the TLS connection will be used for Redis and PostgreSQL connection\nCGW_UCENTRAL_AP_DATAMODEL_URI     - Path to AP Config message JSON Validation schema:\n                                    1. URI in format: \"http[s]://\u003cpath\u003e\", e.g https://somewhere.com/schema.json\n                                    2. Path to local file: \"\u003cpath\u003e\", e.g /etc/host/schema.json\nCGW_UCENTRAL_SWITCH_DATAMODEL_URI - Path to Switch Config message JSON Validation schema\n```\n\nExample of properly configured list of env variables to start CGW:\n```console\n$ export | grep CGW\ndeclare -x CGW_DB_HOST=\"localhost\"\ndeclare -x CGW_DB_PORT=\"5432\"\ndeclare -x CGW_DB_USERNAME=\"cgw\"\ndeclare -x CGW_DB_PASS=\"123\"\ndeclare -x CGW_DB_TLS=\"no\"\ndeclare -x CGW_GRPC_LISTENING_IP=\"127.0.0.1\"\ndeclare -x CGW_GRPC_LISTENING_PORT=\"50051\"\ndeclare -x CGW_GRPC_PUBLIC_HOST=\"localhost\"\ndeclare -x CGW_GRPC_PUBLIC_PORT=\"50051\"\ndeclare -x CGW_ID=\"0\"\ndeclare -x CGW_KAFKA_HOST=\"localhost\"\ndeclare -x CGW_KAFKA_PORT=\"9092\"\ndeclare -x CGW_LOG_LEVEL=\"debug\"\ndeclare -x CGW_REDIS_HOST=\"localhost\"\ndeclare -x CGW_REDIS_PORT=\"6379\"\ndeclare -x CGW_REDIS_USERNAME=\"cgw\"\ndeclare -x CGW_REDIS_PASSWORD=\"123\"\ndeclare -x CGW_REDIS_TLS=\"no\"\ndeclare -x CGW_METRICS_PORT=\"8080\"\ndeclare -x CGW_WSS_IP=\"0.0.0.0\"\ndeclare -x CGW_WSS_PORT=\"15002\"\ndeclare -x CGW_WSS_CAS=\"cas.pem\"\ndeclare -x CGW_WSS_CERT=\"cert.pem\"\ndeclare -x CGW_WSS_KEY=\"key.pem\"\ndeclare -x CGW_CERTS_PATH=\"/etc/ssl/certs\"\ndeclare -x CGW_ALLOW_CERT_MISMATCH=\"no\"\ndeclare -x CGW_NB_INFRA_CERTS_PATH=\"/etc/nb_infra_certs\"\ndeclare -x CGW_NB_INFRA_TLS=\"no\"\ndeclare -x CGW_UCENTRAL_AP_DATAMODEL_URI=\"https://raw.githubusercontent.com/Telecominfraproject/wlan-ucentral-schema/main/ucentral.schema.json\"\ndeclare -x CGW_UCENTRAL_SWITCH_DATAMODEL_URI=\"https://raw.githubusercontent.com/Telecominfraproject/ols-ucentral-schema/main/ucentral.schema.json\"\ndeclare -x CGW_GROUPS_CAPACITY=1000\ndeclare -x CGW_GROUPS_THRESHOLD=50\ndeclare -x CGW_GROUP_INFRAS_CAPACITY=2000\n```\n# Certificates\nThe CGW uses two different sets of certificate configuration:\n1. AP/Switch connectivity (southbound)\n2. Infrastructure connectivity (northbound)\n\nThe AP/Switch connectivity uses a number of certificates to provide security (mTLS).\nThere are 2 types of certificates required for a normal deployment:\n1. Server certificates\n2. Client certificates\n\nThe certificates are accessible from CGW docker container via volume: [/etc/cgw/certs]\n\nThere are several environment variable to configure certificates path and names to be used within CGW:\n1. CGW_WSS_CERT - CGW WSS Certificate\n2. CGW_WSS_KEY - CGW WSS Private Key\n3. CGW_WSS_CAS - Chain certificates to validate client (root/issuer)\n4. CGW_CERTS_PATH - path to certificates located on host machine\n\nThe infrastructure connectivity use root certs store - the directory with trusted certificates\nThe environemt variable to configure certificates path:\n1. CGW_NB_INFRA_CERTS_PATH - path to certificates located on host machine\n\n# Automated Testing\nAutomated python-based tests are located inside the *tests* directory.\nCurrently, tests should be run manually by changin PWD to *tests* and launching helper script *run.sh*:\n```console\ncd ./test\n./run.sh\n```\nor using make target (added for convinience):\n```console\nmake run-tests\n```\n*NOTE:* currently, tests are not running inside a container.\nTo make sure tests can communicate with CGW-enviroment, tests are currently\nreaching environment through ports exposed to host system. \ne.g. for WSS - tests try to reach 'wss://localhost:15002' by default and so on.\n\n# Automated multi-CGW instances start/stop with Docker Compose\nAutomated multi-CGW start/stop based on \"docker-compose-template.yml.j2\" file located inside the *utils/docker* directory.\nTo bring-up multiple (minumum 1) CGW instances we use templated \"docker-compose-template.yml.j2\" file.\nThe \"StartMultiCGW.py\" script located inside the *utils/docker* directory used to:\n  1. Stop all running Docker Composes.\n  2. Update/generate certificates\n  3. Generate \"docker-compose-multi-cgw.yml\" Docker Compose file that includes:\n    - Kafka service\n    - Redis service\n    - PostgreSQL service\n    - [N] CGW instances\n  4. Start Docker Compose using generated \"docker-compose-multi-cgw.yml\" file.\n\nThe \"CGW_INSTANCES_NUM\" environment variable is used to specify number of CGW instances.\nMakefile has 2 targets to start/stop Docker Compose\n  - start-multi-cgw\n  - stop-multi-cgw\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftelecominfraproject%2Fopenlan-cgw","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftelecominfraproject%2Fopenlan-cgw","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftelecominfraproject%2Fopenlan-cgw/lists"}