From a5925346213e5fdd3baa4529b4c75d4ce24e261b Mon Sep 17 00:00:00 2001 From: stephb9959 Date: Fri, 24 Feb 2023 23:11:39 -0800 Subject: [PATCH] https://telecominfraproject.atlassian.net/browse/WIFI-12068 Signed-off-by: stephb9959 --- BUILDING.md | 191 ++++++++++++++++++++++++++++++++++++++++++++++++++++ README.md | 24 +++++-- 2 files changed, 209 insertions(+), 6 deletions(-) create mode 100644 BUILDING.md diff --git a/BUILDING.md b/BUILDING.md new file mode 100644 index 0000000..8b44d6d --- /dev/null +++ b/BUILDING.md @@ -0,0 +1,191 @@ +# Building from source + +In order to build the OWSEC, you will need to install its dependencies, which includes the following: +- cmake +- boost +- POCO 1.10.1 or later +- a C++17 compiler +- openssl +- libpq-dev (PortgreSQL development libraries) +- mysql-client (MySQL client) +- librdkafka +- cppkafka + +The build is done in 2 parts. The first part is to build a local copy of the framework tailored to your environment. This +framework is called [Poco](https://github.com/pocoproject/poco). The version used in this project has a couple of fixes +from the master copy needed for cmake. Please use the version of this [Poco fix](https://github.com/AriliaWireless/poco). Building +Poco may take several minutes depending on the platform you are building on. + +## Ubuntu +These instructions have proven to work on Ubuntu 20.4. +```bash +sudo apt install git cmake g++ libssl-dev libmariadb-dev +sudo apt install libpq-dev libaprutil1-dev apache2-dev libboost-all-dev +sudo apt install librdkafka-dev default-libmysqlclient-dev +sudo apt install nlohmann-json-dev + +cd ~ +git clone https://github.com/AriliaWireless/poco --branch poco-tip-v1 +cd poco +mkdir cmake-build +cd cmake-build +cmake .. +cmake --build . --config Release +sudo cmake --build . --target install + +cd ~ +git clone https://github.com/AriliaWireless/cppkafka --branch tip-v1 +cd cppkafka +mkdir cmake-build +cd cmake-build +cmake .. +cmake --build . --config Release +sudo cmake --build . --target install + +cd ~ +git clone https://github.com/AriliaWireless/valijson --branch tip-v1 +cd valijson +mkdir cmake-build +cd cmake-build +cmake .. +cmake --build . --config Release +sudo cmake --build . --target install + +git clone https://github.com/fmtlib/fmt --branch 9.0.0 /fmtlib +cd fmtlib +mkdir cmake-build +cd cmake-build +cmake .. +make +make install + +cd ~ +git clone https://github.com/Telecominfraproject/wlan-cloud-ucentralsec +cd wlan-cloud-ucentralsec +mkdir cmake-build +cd cmake-build +cmake .. +make -j 8 +``` + +## Fedora +The following instructions have proven to work on Fedora 33 +```bash +sudo yum install cmake g++ openssl-devel mysql-devel mysql apr-util-devel boost boost-devel +sudo yum install yaml-cpp-devel lua-devel +sudo dnf install postgresql.x86_64 librdkafka-devel +sudo dnf install postgresql-devel json-devel + +git clone https://github.com/AriliaWireless/poco --branch poco-tip-v1 +cd poco +mkdir cmake-build +cd cmake-build +cmake .. +cmake --build . --config Release +sudo cmake --build . --target install + +git clone https://github.com/AriliaWireless/cppkafka --branch tip-v1 +cd cppkafka +mkdir cmake-build +cd cmake-build +cmake .. +cmake --build . --config Release +sudo cmake --build . --target install + +cd ~ +git clone https://github.com/AriliaWireless/valijson --branch tip-v1 +cd valijson +mkdir cmake-build +cd cmake-build +cmake .. +cmake --build . --config Release +sudo cmake --build . --target install + +cd ~ +git clone https://github.com/Telecominfraproject/wlan-cloud-ucentralsec +cd wlan-cloud-ucentralsec +mkdir cmake-build +cd cmake-build +cmake .. +make +``` + +## macOS Build +The following instructions have proven to work on macOS Big Sur. You need to install [Homebrew](https://brew.sh/). You must also have installed [XCode for OS X](https://www.freecodecamp.org/news/how-to-download-and-install-xcode/). +```bash +brew install openssl \ + cmake \ + libpq \ + mysql-client \ + apr \ + apr-util \ + boost \ + yaml-cpp \ + postgresql \ + librdkafka \ + nlohmann-json \ + fmt + +git clone https://github.com/AriliaWireless/poco --branch poco-tip-v1 +pushd poco +mkdir cmake-build +push cmake-build +cmake -DOPENSSL_ROOT_DIR= -DENABLE_NETSSL=1 -DENABLE_JWT=1 -DENABLE_CRYPTO=1 .. +cmake --build . --config Release +sudo cmake --build . --target install +popd +popd + +git clone https://github.com/AriliaWireless/cppkafka --branch tip-v1 +pushd cppkafka +mkdir cmake-build +pushd cmake-build +cmake .. +cmake --build . --config Release +sudo cmake --build . --target install +popd +popd + +git clone https://github.com/AriliaWireless/valijson --branch tip-v1 +cd valijson +mkdir cmake-build +cd cmake-build +cmake .. +cmake --build . --config Release +sudo cmake --build . --target install +popd +popd + +git clone https://github.com/Telecominfraproject/wlan-cloud-ucentralsec +pushd wlan-cloud-ucentralsec +mkdir cmake-build +pushd cmake-build +cmake .. +make -j +popd +popd +``` + +## Raspberry +The build on a rPI takes a while. You can shorten that build time and requirements by disabling all the larger database +support. You can build with only SQLite support by not installing the packages for PostgreSQL, and MySQL by +adding -DSMALL_BUILD=1 on the cmake build line. + +```bash +sudo apt install git cmake g++ libssl-dev libaprutil1-dev apache2-dev libboost-all-dev libyaml-cpp-dev +git clone https://github.com/stephb9959/poco +cd poco +mkdir cmake-build +cd cmake-build +cmake .. +cmake --build . --config Release +sudo cmake --build . --target install + +cd ~ +git clone https://github.com/Telecominfraproject/wlan-cloud-ucentralsec +cd wlan-cloud-ucentralsec +mkdir cmake-build +cd cmake-build +cmake -DSMALL_BUILD=1 .. +make +``` diff --git a/README.md b/README.md index 773b27c..d91b8aa 100644 --- a/README.md +++ b/README.md @@ -4,16 +4,28 @@ # OpenWiFi Security (OWSEC) -The OpenWiFi Security Service (a.k.a. OWSEC) is the Authentication and Resource Policy Access service for the TIP -OpenWiFi Cloud SDK (OWSDK). In order to use the Cloud SDK you must have at least 1 OWSEC. OWSEC is the first point of contact -for the entire architecture. We strongly recommend using Docker to deploy all the OWSDK. If you would like to develop -and play with the source, please do. +## What is it? +The OWSEC is a service for the TIP OpenWiFi CloudSDK (OWSDK). +OWSEC is the Authentication and Resource Policy Access service for the TIP +OpenWiFi Cloud SDK (OWSDK). OWSEC, +like all other OWSDK microservices, is defined using an OpenAPI definition and uses the ucentral communication +protocol to interact with Access Points. To use the OWSUB, you either need to [build it](#building) or use the +[Docker version](#docker). + +## Building +To build the microservice from source, please follow the instructions in [here](./BUILDING.md) + +## Docker +To use the CLoudSDK deployment please follow [here](https://github.com/Telecominfraproject/wlan-cloud-ucentral-deploy) ## OpenAPI +You may get static page with OpenAPI docs generated from the definition on [GitHub Page](https://telecominfraproject.github.io/wlan-cloud-ucentralsec/). +Also, you may use [Swagger UI](https://petstore.swagger.io/#/) with OpenAPI definition file raw link (i.e. [latest version file](https://raw.githubusercontent.com/Telecominfraproject/wlan-cloud-ucentralsec/main/openapi/owsec.yaml)) to get interactive docs page. + +## Usage Like all other OWSDK services, OWSEC is defined through an OpenAPI. You can use this API to build your own applications or integration modules into your own systems. If all you need it to access the OWGW for example (the service that manages the APs), you will need to: - - get a token (`/oauth2`) - find the endpoints on the system (`/systemEndpoints`) - choose a microservice to manage (pick an endpoint that matches what you are trying to do by looking at its @@ -21,7 +33,7 @@ example (the service that manages the APs), you will need to: - make your calls (use the PublicEndPoint of the corresponding entry to make your calls, do not forget to add `/api/v1` as the root os the call) -The CLI for the [OWGW](https://github.com/telecominfraproject/wlan-cloud-ucentralgw/blob/main/test_scripts/curl/cli) has +The CLI for the [OWGW](https://github.com/telecominfraproject/wlan-cloud-ucentralsec/blob/main/test_scripts/curl/cli) has a very good example of this. Look for the `setgateway` function. You may get static page with OpenAPI docs generated from the definition on [GitHub Page](https://telecominfraproject.github.io/wlan-cloud-ucentralsec/).