-
Notifications
You must be signed in to change notification settings - Fork 590
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Signed-off-by: Oriol Batalla <obatalla@fb.com>
- Loading branch information
Showing
149 changed files
with
21,166 additions
and
0 deletions.
There are no files selected for viewing
Large diffs are not rendered by default.
Oops, something went wrong.
28 changes: 28 additions & 0 deletions
28
docs/docusaurus/versioned_docs/version-1.7.0/basics/introduction.md
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,28 @@ | ||
--- | ||
id: version-1.7.0-introduction | ||
title: Introduction | ||
hide_title: true | ||
original_id: introduction | ||
--- | ||
# Introduction | ||
|
||
Magma is an open-source software platform that gives network operators an open, flexible and extendable mobile core network solution. Magma enables better connectivity by: | ||
|
||
- Allowing operators to offer cellular service without vendor lock-in with a modern, open source core network | ||
- Enabling operators to manage their networks more efficiently with more automation, less downtime, better predictability, and more agility to add new services and applications | ||
- Enabling federation between existing MNOs and new infrastructure providers for expanding rural infrastructure | ||
- Allowing operators who are constrained with licensed spectrum to add capacity and reach by using Wi-Fi and CBRS | ||
|
||
## Magma Architecture | ||
|
||
The figure below shows the high-level Magma architecture. Magma is designed to be 3GPP generation and access network (cellular or WiFi) agnostic. It can flexibly support a radio access network with minimal development and deployment effort. | ||
|
||
Magma has three major components: | ||
|
||
- **Access Gateway:** The Access Gateway (AGW) provides network services and policy enforcement. In an LTE network, the AGW implements an evolved packet core (EPC), and a combination of an AAA and a PGW. It works with existing, unmodified commercial radio hardware. | ||
|
||
- **Orchestrator:** Orchestrator is a cloud service that provides a simple and consistent way to configure and monitor the wireless network securely. The Orchestrator can be hosted on a public/private cloud. The metrics acquired through the platform allows you to see the analytics and traffic flows of the wireless users through the Magma web UI. | ||
|
||
- **Federation Gateway:** The Federation Gateway integrates the MNO core network with Magma by using standard 3GPP interfaces to existing MNO components. It acts as a proxy between the Magma AGW and the operator's network and facilitates core functions, such as authentication, data plans, policy enforcement, and charging to stay uniform between an existing MNO network and the expanded network with Magma. | ||
|
||
![Magma architecture diagram](assets/magma_overview.png?raw=true "Magma Architecture") |
246 changes: 246 additions & 0 deletions
246
docs/docusaurus/versioned_docs/version-1.7.0/basics/prerequisites.md
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,246 @@ | ||
--- | ||
id: version-1.7.0-prerequisites | ||
title: Prerequisites | ||
hide_title: true | ||
original_id: prerequisites | ||
--- | ||
|
||
# Prerequisites | ||
|
||
These are the prerequisites to setting up a full private LTE Magma deployment. | ||
Additional prerequisites for developers can be found in the [developer's guide](../contributing/contribute_onboarding.md). | ||
|
||
## Operating System | ||
|
||
Currently, the main development operating system (OS) is **macOS**. Documentation is mainly focused on that operating system. | ||
To develop on a **Linux OS**, the package manager (brew for macOS) will need to be replaced by the appropriate package manager for the respective Linux distribution (e.g. apt, yum, etc.). | ||
**Windows OS** is currently _not_ supported as developing environment, due to some dependencies on Linux-only tools during setup, such as Ansible or `fcntl`. You can try to use a [DevContainer setup](../contributing/contribute_vscode.md#open-a-devcontainer-workspace-with-github-codespaces) though. | ||
|
||
## Development Tools | ||
|
||
Development can occur from multiple OS's, where **macOS** and **Ubuntu** are **explicitly supported**, with additional polish for macOS. | ||
|
||
**Note:** If you still want to contribute from a different OS, you will need to figure out some workarounds to install the tooling. You might want to follow one of the guides, either macOS or Ubuntu, and replicate the steps in your preferred OS. | ||
|
||
### macOS | ||
|
||
1. Install the following tools | ||
|
||
1. [Docker](https://www.docker.com) and Docker Compose | ||
2. [Homebrew](https://brew.sh/) | ||
3. [VirtualBox](https://www.virtualbox.org/) | ||
4. [Vagrant](https://vagrantup.com) | ||
|
||
```bash | ||
brew install go@1.13 pyenv | ||
# NOTE: this assumes you're using zsh. | ||
# See the above pyenv install instructions if using alternative shells. | ||
echo 'export PATH="/usr/local/opt/go@1.13/bin:$PATH"' >> ~/.zshrc | ||
echo 'eval "$(pyenv init --path)"' >> ~/.zprofile | ||
echo 'eval "$(pyenv init -)"' >> ~/.zshrc | ||
exec $SHELL | ||
# IMPORTANT: close your terminal tab and open a new one before continuing | ||
pyenv install 3.8.10 | ||
pyenv global 3.8.10 | ||
pip3 install ansible fabric3 jsonpickle requests PyYAML | ||
vagrant plugin install vagrant-vbguest | ||
``` | ||
|
||
**Note**: In the case where installation of `fabric3` through pip was unsuccessful, | ||
try switching to other package installers. Try running `brew install fabric`. | ||
|
||
You should start Docker Desktop and increase the memory | ||
allocation for the Docker engine to at least 4GB (Preferences -> Resources -> | ||
Advanced). If you are running into build/test failures with Go that report | ||
"signal killed", you likely need to increase Docker's allocated resources. | ||
|
||
![Increasing docker engine resources](assets/docker-config.png) | ||
|
||
### Ubuntu | ||
|
||
1. Install the following tools | ||
1. [Docker](https://docs.docker.com/engine/install/ubuntu/) and [Docker Compose](https://docs.docker.com/compose/install/) | ||
2. [VirtualBox](https://www.virtualbox.org/wiki/Linux_Downloads) | ||
3. [Vagrant](https://www.vagrantup.com/downloads) | ||
2. Install golang version 13. | ||
|
||
1. Download the tar file. | ||
|
||
```bash | ||
wget https://golang.org/dl/go1.13.15.linux-amd64.tar.gz | ||
``` | ||
|
||
2. Extract the archive you downloaded into `/usr/local`, creating a Go tree in `/usr/local/go`. | ||
|
||
```bash | ||
sudo rm -rf /usr/local/go && sudo tar -C /usr/local -xzf go1.13.15.linux-amd64.tar.gz | ||
``` | ||
|
||
3. Add `/usr/local/go/bin` to the PATH environment variable. | ||
|
||
```bash | ||
export PATH=$PATH:/usr/local/go/bin | ||
``` | ||
|
||
4. Verify that you've installed Go by opening a command prompt and typing the following command | ||
|
||
```bash | ||
go version | ||
``` | ||
|
||
You should expect something like this | ||
|
||
```bash | ||
go version go1.13.15 linux/amd64 | ||
``` | ||
|
||
3. Install `pyenv`. | ||
|
||
1. Update system packages. | ||
|
||
```bash | ||
sudo apt update -y | ||
``` | ||
|
||
2. Install some necessary dependencies. **If you are using `zsh` instead of `bash`, replace** `.bashrc` **for** `.zshrc`. | ||
|
||
```bash | ||
apt install -y make build-essential libssl-dev zlib1g-dev libbz2-dev libreadline-dev libsqlite3-dev wget curl llvm libncurses5-dev libncursesw5-dev xz-utils tk-dev libffi-dev liblzma-dev python-openssl git | ||
``` | ||
|
||
3. Clone `pyenv` repository. | ||
|
||
```bash | ||
git clone https://github.com/pyenv/pyenv.git ~/.pyenv | ||
``` | ||
|
||
4. Configure `pyenv`. | ||
|
||
```bash | ||
echo 'export PYENV_ROOT="$HOME/.pyenv"' >> ~/.bashrc | ||
echo 'export PATH="$PYENV_ROOT/bin:$PATH"' >> ~/.bashrc | ||
echo -e 'if command -v pyenv 1>/dev/null 2>&1; then\n eval "$(pyenv init -) "\nfi' >> ~/.bashrc | ||
exec "$SHELL" | ||
``` | ||
|
||
5. Create python virtual environment version 3.7.3. | ||
|
||
```bash | ||
pyenv install 3.7.3 | ||
pyenv global 3.7.3 | ||
``` | ||
|
||
4. Install `pip3` and its dependencies. | ||
|
||
1. Install `pip3`. | ||
|
||
```bash | ||
sudo apt install python3-pip | ||
``` | ||
|
||
2. Install the following dependencies | ||
|
||
```bash | ||
pip3 install ansible fabric3 jsonpickle requests PyYAML | ||
``` | ||
|
||
5. Install `vagrant` necessary plugin. | ||
|
||
```bash | ||
vagrant plugin install vagrant-vbguest | ||
``` | ||
|
||
## Downloading Magma | ||
|
||
You can find Magma code on [Github](https://github.com/magma/magma). | ||
|
||
To download Magma current version, or a specific release do the following | ||
|
||
```bash | ||
git clone https://github.com/magma/magma.git | ||
cd magma | ||
|
||
# in case you want to use a specific version of Magma (for example v1.6) | ||
git checkout v1.6 | ||
|
||
# to list all available releases | ||
git tag -l | ||
``` | ||
|
||
## Deployment Tooling | ||
|
||
First, follow the previous section on [developer tools](#development-tools). Then, install some | ||
additional prerequisite tools. | ||
|
||
### macOS | ||
|
||
Install necessary dependencies and configure the aws cli | ||
|
||
```bash | ||
brew install aws-iam-authenticator kubectl helm terraform | ||
python3 -m pip install awscli boto3 | ||
aws configure | ||
``` | ||
|
||
### Ubuntu | ||
|
||
Install the following | ||
|
||
1. [aws-iam-authenticator for Linux](https://docs.aws.amazon.com/eks/latest/userguide/install-aws-iam-authenticator.html). | ||
2. [kubectl for Linux](https://kubernetes.io/docs/tasks/tools/install-kubectl-linux/#install-using-native-package-management). | ||
3. [Helm for Linux](https://helm.sh/docs/intro/install/). | ||
4. [Terraform for Linux](https://learn.hashicorp.com/tutorials/terraform/install-cli). | ||
5. awscli | ||
|
||
```bash | ||
sudo apt install awscli | ||
``` | ||
|
||
### Orchestrator and NMS | ||
|
||
Orchestrator deployment depends on the following components | ||
|
||
1. AWS account | ||
2. Registered domain for Orchestrator endpoints | ||
|
||
We recommend deploying the Orchestrator cloud component of Magma into AWS. | ||
Our open-source Terraform scripts target an AWS deployment environment, but if | ||
you are familiar with devops and are willing to roll your own, Orchestrator can | ||
run on any public/private cloud with a Kubernetes cluster available to use. | ||
The deployment documentation will assume an AWS deployment environment - if | ||
this is your first time using or deploying Orchestrator, we recommend that you | ||
follow this guide before attempting to deploy it elsewhere. | ||
|
||
Provide the access key ID and secret key for an administrator user in AWS | ||
(don't use the root user) when prompted by `aws configure`. Skip this step if | ||
you will use something else for managing AWS credentials. | ||
|
||
## Production Hardware | ||
|
||
### Access Gateways | ||
|
||
Access gateways (AGWs) can be deployed on to any AMD64 architecture machine | ||
which can support a Debian or Ubuntu 20.04 Linux installation. The basic system | ||
requirements for the AGW production hardware are | ||
|
||
1. 2+ physical Ethernet interfaces | ||
2. AMD64 dual-core processor around 2GHz clock speed or faster | ||
3. 4GB RAM | ||
4. 32GB or greater SSD storage | ||
|
||
In addition, in order to build the AGW, you should have on hand | ||
|
||
1. A USB stick with 2GB+ capacity to load a Debian Stretch ISO | ||
2. Peripherals (keyboard, screen) for your production AGW box for use during | ||
provisioning | ||
|
||
### RAN Equipment | ||
|
||
We currently have tested with the following EnodeB's | ||
|
||
1. Baicells Nova 233 TDD Outdoor | ||
2. Baicells Nova 243 TDD Outdoor | ||
3. Assorted Baicells indoor units (for lab deployments) | ||
|
||
Support for other RAN hardware can be implemented inside the `enodebd` service | ||
on the AGW, but we recommend starting with one of these EnodeBs. |
Oops, something went wrong.