From 5b828b63f2e0adeaa7985aa719fc0b3955d7e175 Mon Sep 17 00:00:00 2001 From: Youssouf Drif Date: Sun, 22 Nov 2020 00:41:50 +0100 Subject: [PATCH] Update README.md --- README.md | 139 +++++++++++++++++++++++++++++++++++++++--------------- 1 file changed, 101 insertions(+), 38 deletions(-) diff --git a/README.md b/README.md index a58cf32..93350c2 100644 --- a/README.md +++ b/README.md @@ -1,73 +1,136 @@ -# A Simple CLI tool for free5GC +# Freecli - An interactive CLI for free5GC -**/!\ Still under development, use it at your own risks, no support provided yet** +![free5gc-cli](https://img.shields.io/badge/Freecli-5G-blue?logo=go) -![free5gc-cli](https://img.shields.io/badge/Golang-free5cli-blue?logo=go) +![freecli-interactive-cli](https://user-images.githubusercontent.com/41422704/99889610-220d3580-2c57-11eb-9133-f4a1daaa9258.gif) -- [Disclaimer](#disclaimer) -- [Installation](#installation) + +- [Description](#description) +- [Download and build](#download-and-build) - [Configuration](#configuration) -- [Usage](#usage) - - [Subscriber management](#subscriber-management) +- [Run Freecli](#run-freecli) +- [Modules](#modules) + - [Subscriber module](#subscriber-module) + - [Add a fixed number of subscribers](#add-a-fixed-number-of-subscribers) + - [Add a subscriber with a specific supi to a plmn](#add-a-subscriber-with-a-specific-supi-to-a-plmn) + - [List all the subscribers](#list-all-the-subscribers) + - [Delete a subscriber from a plmn](#delete-a-subscriber-from-a-plmn) + - [Flush the database from every subscriber](#flush-the-database-from-every-subscriber) + - [gNB module](#gnb-module) +- [Acknowledgment](#acknowledgment) + +## Description -## Disclaimer +Freecli is an interactive cli utility to manage free5gc. It currently includes the following modules: -This project provides an unofficial repository for the free5gc project as the official webconsole does not cover all use-cases. free5gc-cli is a simple cli utility to interact with free5gc. I use it mainly to manage subscribers when I can't have access to the WEBUI. This CLI is based on the webconsole and rely on free5gc lib. It is also subject to changes and further evolutions. +- Subscriber: manage the subscriber of free5gc in a fashion way +- 5G gNB: emulate a 5G gNB **/!\ Still under development** -## Installation +## Download and build -The cli works as a standalone CLI. Clone the repository and build the cli +To compile into a binary file ``` bash -git clone --recursive https://github.com/Srajdax/free5gc-cli.git +git clone https://github.com/Srajdax/free5gc-cli.git cd free5gc-cli go mod download go build -o freecli -x freecli.go ``` +or to run it like an interpreter would do + +``` bash +git clone https://github.com/Srajdax/free5gc-cli.git +cd free5gc-cli +go run freecli.go +``` + ## Configuration -The gNB `freecli.cfg` configuration file is located in `free5gc/config` folder. A sample is also present into `free5gc-cli/config` folder. +Freecli uses free5gc lib under the hood with some modifications. Each freecli module is located into the `module` folder. Each module has its own configuration files located in the `config` folder. Each module is described below. + +## Run Freecli + +Each module is independent in freecli, at launch you can load the module by typing their name, e.g. to load the subscriber module and access all its functionalities: -``` yaml -info: - version: 1.0.0 - description: free5gc-cli initial local configuration +```bash +./freecli -configuration: - mongodb: - name: free5gc - url: mongodb://localhost:27017 +# Load the module +freecli> subscriber +2020-11-21T23:22:41Z [INFO][Freecli][Freecli] Loading subscriber module... +2020-11-21T23:22:41Z [INFO][Freecli][Subscriber Module] Successfully load module configuration config/subscriber.yaml +2020-11-21T23:22:41Z [INFO][Freecli][Subscriber Module] Successfully load ue configuration config/subscriber_ue.yaml + +subscriber# The module is successfuly loaded + +# Exit the module +subscriber# exit +2020-11-22T00:41:12+01:00 [INFO][Freecli][Freecli] Exiting Module... ``` -## Usage +## Modules -``` bash -./freecli +### Subscriber module + +This module is used to add, delete and flush subscribers of free5gc database. It has 2 configuration files. `subscriber.yaml` holds the configuration of the module and `subsriber_ue.yaml` holds the global configuration of the subscribers to add. + +#### Add a fixed number of subscribers + +command +``` +subscriber# user random --range --plmn ``` -### Subscriber management +example +``` +subscriber# user random --range 10 --plmn 20893 +``` -Add a subscriber +#### Add a subscriber with a specific supi to a plmn -```bash -./freecli --add +command +``` +subscriber# user register --supi --plmn ``` -Remove a subscriber +example +``` +subscriber# user register --supi imsi-2089300000013 --plmn 20893 +``` -```bash -./freecli --remove +#### List all the subscribers + +command +``` +subscriber# user list ``` -Update a subscriber +Note: this will also populate the auto-complete for the delete command -```bash -./freecli --update +#### Delete a subscriber from a plmn + +command +``` +subscriber# user delete / ``` -Get all the subscribers +example +``` +subscriber# user delete imsi-2089300000000/20893 +``` -```bash -./freecli --subscribers -``` \ No newline at end of file +#### Flush the database from every subscriber + +command +``` +subscriber# user flush +``` + +### gNB module + +Currently under development + +## Acknowledgment + +Thanks to the free5gc team for their efforts and their open source 5G Core Network \ No newline at end of file