From dd9b2d416df18d1b530edc54f84e022f25ddf93a Mon Sep 17 00:00:00 2001 From: Lucas Amaral Date: Thu, 17 Apr 2025 19:19:38 -0300 Subject: [PATCH 01/22] chore(docusaurus): rename siteConfig.js file to docusaurus.config.js Signed-off-by: Lucas Amaral --- docusaurus/{siteConfig.js => docusaurus.config.js} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename docusaurus/{siteConfig.js => docusaurus.config.js} (100%) diff --git a/docusaurus/siteConfig.js b/docusaurus/docusaurus.config.js similarity index 100% rename from docusaurus/siteConfig.js rename to docusaurus/docusaurus.config.js From 60acf1299fa0c9d0120a78946f987b60f194fbb2 Mon Sep 17 00:00:00 2001 From: Lucas Amaral Date: Thu, 17 Apr 2025 21:47:01 -0300 Subject: [PATCH 02/22] chore(docusaurus): prepare configfile for new docusaurus version Signed-off-by: Lucas Amaral --- docusaurus/docusaurus.config.js | 196 ++++++++++++++++++++++---------- 1 file changed, 134 insertions(+), 62 deletions(-) diff --git a/docusaurus/docusaurus.config.js b/docusaurus/docusaurus.config.js index e8cbf00..65a934b 100644 --- a/docusaurus/docusaurus.config.js +++ b/docusaurus/docusaurus.config.js @@ -1,5 +1,5 @@ /** - * Copyright 2020 The Magma Authors. + * Copyright 2025 The Magma Authors. * * This source code is licensed under the BSD-style license found in the * LICENSE file in the root directory of this source tree. @@ -13,7 +13,9 @@ // Ref: https://v1.docusaurus.io/docs/en/site-config -const url = process.env.DOCUSAURUS_URL || 'https://magmacore.org' +import {themes as prismThemes} from 'prism-react-renderer'; + +const url = process.env.DOCUSAURUS_URL || 'https://magma.github.io' const baseUrl = process.env.DOCUSAURUS_BASE_URL || '/' // Security note on visibility of this secret in the source code: the API key is @@ -25,81 +27,151 @@ const baseUrl = process.env.DOCUSAURUS_BASE_URL || '/' const algoliaApiKey = process.env.ALGOLIA_API_KEY || '7b4d4c984e53d3a746869d22ed9e983b'; -const mermaid = require('remark-mermaid') +const magmaGithubUrl = 'https://github.com/magma/magma' + +// Path to images for header/footer +const footerIcon = 'img/magma_icon.png' +const favicon = 'img/icon.png' +const magmaLogo = 'img/magma-logo.svg' -const siteConfig = { +/** @type {import('@docusaurus/types').Config} */ +const config = { title: 'Magma Documentation', - disableTitleTagline: true, - tagline: 'Bring more people online by enabling operators with open, flexible, and extensible network solutions', + tagline: 'Magma is an open-source software platform that gives network operators an open, flexible and extendable mobile core network solution.', + favicon: favicon, - projectName: 'magma', + url: url, // production url + baseUrl: baseUrl, // // pathname under which the site is served + + // GitHub pages deployment config. + // If you aren't using GitHub pages, you don't need these. organizationName: 'magma', - url: url, // full URL - baseUrl: baseUrl, // base URL - - headerLinks: [ - {href: 'https://magmacore.org', label: 'Magma Website'}, - {label: ' | '}, - {href: baseUrl, label: 'Docs'}, - {label: ' | '}, - {href: 'https://github.com/magma', label: 'Code'}, - {label: ' | '}, - {href: 'https://github.com/magma/magma/wiki/Contributor-Guide', label: 'Contributing'}, - {label: ' | '}, - {href: 'https://wiki.magmacore.org/', label: 'Wiki'}, - ], + projectName: 'magma', - // Path to images for header/footer - headerIcon: 'img/magma-logo.svg', - footerIcon: 'img/magma_icon.png', - favicon: 'img/icon.png', + onBrokenLinks: 'throw', + onBrokenMarkdownLinks: 'warn', - // Colors for website - colors: { - primaryColor: '#5602a4', - secondaryColor: '#5602a4', + i18n: { + defaultLocale: 'en', + locales: ['en', 'es', 'pt'], }, - // This copyright info is used in /core/Footer.js and blog RSS/Atom feeds. - copyright: `Copyright \u{00A9} ${new Date().getFullYear()} The Magma Authors`, + presets: [ + [ + 'classic', + /** @type {import('@docusaurus/preset-classic').Options} */ + ({ + docs: { + sidebarPath: './sidebars.js', + }, + theme: { + customCss: './src/css/custom.css', + }, + }), + ], + ], - // Highlight.js theme to use for syntax highlighting in code blocks. - highlight: { - theme: 'default', - }, + themeConfig: /** @type {import('@docusaurus/preset-classic').ThemeConfig} */ + ( + { + image: favicon, + navbar: { + title: 'Magma', + logo: { + alt: 'Magma Logo', + src: magmaLogo, + }, + items: [ + { + type: 'docsVersionDropdown', + sidebarId: 'versionSidebar', + position: 'left', + label: 'Tutorial', + }, + { + to: 'https://magmacore.org/', + label: 'Magma Website', + position: 'left' + }, + { + to: '/', + label: 'Docs', + position: 'left' + }, + { + to: magmaGithubUrl, + label: 'Code', + position: 'left' + }, + { + to: 'https://github.com/magma/magma/wiki/Contributor-Guide', + label: 'Contributing', + position: 'left' + }, + { + to: 'https://lf-magma.atlassian.net/wiki/spaces/HOME/overview?mode=global', + label: 'Wiki', + position: 'left' + }, + { + type: 'localeDropdown', + position: 'right', + }, + ], + }, + footer: { + style: 'dark', + links: [ + { + title: 'Community', + items: [ + { + label: 'Slack', + href: 'https://magmacore.slack.com/ssb/redirect', + }, + ], + }, + ], + logo: { + alt: 'Magma Logo', + src: footerIcon, + href: url, + height: 100, + width: 100, + }, + copyright: `Copyright \u{00A9} ${new Date().getFullYear()} Magma Project. Built with Docusaurus.`, + }, + prism: { + theme: prismThemes.github, + darkTheme: prismThemes.dracula, + defaultLanguage: 'bash', + // magicComments: [], + }, + colorMode: { + defaultMode: 'light', + disableSwitch: false, + respectPrefersColorScheme: true, + }, + + // Enable Algolia DocSearch Functionality within Docusaurus + algolia: { + appId: 'magma', + apiKey: algoliaApiKey, + indexName: 'magma', + }, + } + ), // Add custom scripts here that would be placed in - Magma - - - If you are not redirected automatically, follow this link. - - diff --git a/docusaurus/versioned_docs/version-1.0.0/basics/introduction.md b/docusaurus/versioned_docs/version-1.0.0/basics/introduction.md index 92fc506..78bc9f6 100644 --- a/docusaurus/versioned_docs/version-1.0.0/basics/introduction.md +++ b/docusaurus/versioned_docs/version-1.0.0/basics/introduction.md @@ -25,4 +25,4 @@ Magma has three major components: * **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") +![Magma architecture diagram](../../../../readmes/assets/magma_overview.png?raw=true "Magma Architecture") diff --git a/docusaurus/versioned_docs/version-1.0.0/basics/prerequisites.md b/docusaurus/versioned_docs/version-1.0.0/basics/prerequisites.md index c35d1a6..5755aa6 100644 --- a/docusaurus/versioned_docs/version-1.0.0/basics/prerequisites.md +++ b/docusaurus/versioned_docs/version-1.0.0/basics/prerequisites.md @@ -29,7 +29,7 @@ vagrant plugin install vagrant-vbguest If you are on MacOS, you should start Docker for Mac and increase the memory allocation for the Docker engine to at least 4GB (Preferences -> Advanced). -![Increasing docker engine resources](assets/docker-config.png) +![Increasing docker engine resources](../../../../readmes/assets/docker-config.png) ## Build/Deploy Tooling diff --git a/docusaurus/versioned_docs/version-1.0.0/basics/quick_start_guide.md b/docusaurus/versioned_docs/version-1.0.0/basics/quick_start_guide.md index 30725ba..1a9fdc2 100644 --- a/docusaurus/versioned_docs/version-1.0.0/basics/quick_start_guide.md +++ b/docusaurus/versioned_docs/version-1.0.0/basics/quick_start_guide.md @@ -171,3 +171,7 @@ After this, you will be able to access the UI by visiting [https://localhost](https://localhost), and using the email `admin@magma.test` and password `password1234`. If you see Gateway Error 502, don't worry, the NMS can take upto 60 seconds to finish starting up. + + + + diff --git a/docusaurus/versioned_docs/version-1.0.0/cwf/setup.md b/docusaurus/versioned_docs/version-1.0.0/cwf/setup.md index 3ba89cd..3ec24c7 100644 --- a/docusaurus/versioned_docs/version-1.0.0/cwf/setup.md +++ b/docusaurus/versioned_docs/version-1.0.0/cwf/setup.md @@ -26,10 +26,10 @@ Vagrant will bring up the VM, then Ansible will provision the VM. * Once the CWAG VM is up and provisioned, run the following commands: -``HOST:magma/cwf/gateway USER$ vagrant ssh cwag``
-``AGW:~ USER$ cd magma/cwf/gateway/docker``
+``HOST:magma/cwf/gateway USER$ vagrant ssh cwag``

+``AGW:~ USER$ cd magma/cwf/gateway/docker``

``AGW:~/magma/cwf/gateway/docker USER$ docker-compose build --parallel`` ``AGW:~/magma/cwf/gateway/docker USER$ docker-compose up -d`` -After this, all the CWAG docker containers should have been brought up +After this, all the CWAG docker containers should have been brought up successfully. diff --git a/docusaurus/versioned_docs/version-1.0.0/howtos/README_package.md b/docusaurus/versioned_docs/version-1.0.0/howtos/README_package.md index 86837dd..9a0bb62 100644 --- a/docusaurus/versioned_docs/version-1.0.0/howtos/README_package.md +++ b/docusaurus/versioned_docs/version-1.0.0/howtos/README_package.md @@ -31,9 +31,9 @@ You should always do this. In general, try your best not to release broken packages. 1. Build the release like you normally would. -2. Spin up a fresh prod VM or gateway machine and copy the magma_.deb +2. Spin up a fresh prod VM or gateway machine and copy the magma_.deb generated above. -3. Run `sudo apt-get install gdebi; sudo gdebi magma_.deb' +3. Run `sudo apt-get install gdebi; sudo gdebi magma_.deb' 4. A VM reload or gateway reboot will likely be required due to kernel upgrade. This will simulate the exact steps that apt-get performs in production. diff --git a/docusaurus/versioned_docs/version-1.0.0/lte/config_agw.md b/docusaurus/versioned_docs/version-1.0.0/lte/config_agw.md index 222c88e..c606f41 100644 --- a/docusaurus/versioned_docs/version-1.0.0/lte/config_agw.md +++ b/docusaurus/versioned_docs/version-1.0.0/lte/config_agw.md @@ -65,14 +65,14 @@ network. Otherwise, select "Create Network" from the network selection icon at the bottom of the left sidebar. Select `lte` as the network type and fill the other fields as you see fit. -![Creating a network](assets/nms/createnetwork.png) +![Creating a network](../../../../readmes/assets/nms/createnetwork.png) Go back to the network management app using the app selector in the bottom left of the screen, then go to "Configure" in the left sidebar, followed by the "Network Configuration" tab at the top of the screen. Configure your RAN and EPC parameters which are appropriate for your hardware setup. -![Configuring a network](assets/nms/configurenetwork.png) +![Configuring a network](../../../../readmes/assets/nms/configurenetwork.png) ## Registering and Configuring Your Access Gateway @@ -92,13 +92,13 @@ MHYwEAYHKoZIzj0CAQYFK4EEACIDYgAECMB9zEbAlLDQLq1K8tgCLO8Kie5IloU4QuAXEjtR19jt0KTk Navigate to "Gateways" on the NMS via the left navigation bar, hit "Add Gateway", and fill out the form using the hardware secrets from above: -![Creating a gateway](assets/nms/create_agw.png) +![Creating a gateway](../../../../readmes/assets/nms/createnetwork.png) After you create your gateway, hit the Edit icon in its table row, select the "LTE" tab, and configure your EPC/RAN parameters. Make sure you enable enodeB transmit. -![Configuring a gateway](assets/nms/configure_agw.png) +![Configuring a gateway](../../../../readmes/assets/nms/configurenetwork.png) At this point, you can validate the connection between your AGW and Orchestrator: diff --git a/docusaurus/versioned_docs/version-1.0.0/lte/enodebd.md b/docusaurus/versioned_docs/version-1.0.0/lte/enodebd.md index 95c9fc0..8eee6ef 100644 --- a/docusaurus/versioned_docs/version-1.0.0/lte/enodebd.md +++ b/docusaurus/versioned_docs/version-1.0.0/lte/enodebd.md @@ -63,7 +63,7 @@ On the NMS, navigate to "eNodeB Devices" in the sidebar, and hit "Add EnodeB". Configure the RAN parameters as necessary. Note that fields left blank will be inherited from either the network or gateway LTE parameters: -![Configuring an eNodeB](assets/nms/configure_enb.png) +![Configuring an eNodeB](../../../../readmes/assets/nms/configure_enb.png) Then, go back to the "Gateways" page and edit the LTE configuration of your AGW. Enter the serial number of the enodeB you just provisioned into the @@ -158,7 +158,7 @@ failure until you add the corresponding IMSI to the subscriber database. On the NMS, go to "Subscribers", then "Add Subscriber". The SIM secrets can be entered either in hex or base64-encoded binary: -![Adding a subscriber](assets/nms/add_sub.png) +![Adding a subscriber](../../../../readmes/assets/nms/add_sub.png) Subscriber information will eventually propagate to the AGW. You can verify using the CLI command `"subscriber_cli.py list"` diff --git a/docusaurus/versioned_docs/version-1.0.0/lte/setup.md b/docusaurus/versioned_docs/version-1.0.0/lte/setup.md index 94e7085..c257ea5 100644 --- a/docusaurus/versioned_docs/version-1.0.0/lte/setup.md +++ b/docusaurus/versioned_docs/version-1.0.0/lte/setup.md @@ -26,8 +26,8 @@ Vagrant will bring up the VM, then Ansible will provision the VM. * Once the Access Gateway VM is up and provisioned, run the following commands: -``HOST:magma/lte/gateway USER$ vagrant ssh magma``
-``AGW:~ USER$ cd magma/lte/gateway``
+``HOST:magma/lte/gateway USER$ vagrant ssh magma``

+``AGW:~ USER$ cd magma/lte/gateway``

``AGW:~/magma/lte/gateway USER$ make run`` Once the Access Gateway VM is running successfully, proceed to attaching the eNodeB. diff --git a/docusaurus/versioned_docs/version-1.0.0/orc8r/deploy_terraform.md b/docusaurus/versioned_docs/version-1.0.0/orc8r/deploy_terraform.md index 7d6dd17..6e60e52 100644 --- a/docusaurus/versioned_docs/version-1.0.0/orc8r/deploy_terraform.md +++ b/docusaurus/versioned_docs/version-1.0.0/orc8r/deploy_terraform.md @@ -34,7 +34,7 @@ worker nodes of the EKS cluster. This can be found in the EC2 dashboard under "Key Pairs". If you're creating a new key pair, make sure not to lose the private key, you won't be able to recover it from AWS. -![creating an AWS keypair](assets/keypair.png) +![creating an AWS keypair](../../../../readmes/assets/keypair.png) Next, create a `vars.tfvars` file in your directory, *add it to your source control's .ignore*, and specify your desired RDS password and the name of the diff --git a/docusaurus/versioned_docs/version-1.0.X/basics/introduction.md b/docusaurus/versioned_docs/version-1.0.X/basics/introduction.md index 28afc08..c87a8cb 100644 --- a/docusaurus/versioned_docs/version-1.0.X/basics/introduction.md +++ b/docusaurus/versioned_docs/version-1.0.X/basics/introduction.md @@ -25,4 +25,4 @@ Magma has three major components: * **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") +![Magma architecture diagram](../../../../readmes/assets/magma_overview.png?raw=true "Magma Architecture") diff --git a/docusaurus/versioned_docs/version-1.0.X/basics/prerequisites.md b/docusaurus/versioned_docs/version-1.0.X/basics/prerequisites.md index c80dc86..57a1b62 100644 --- a/docusaurus/versioned_docs/version-1.0.X/basics/prerequisites.md +++ b/docusaurus/versioned_docs/version-1.0.X/basics/prerequisites.md @@ -38,7 +38,7 @@ vagrant plugin install vagrant-vbguest If you are on MacOS, you should start Docker for Mac and increase the memory allocation for the Docker engine to at least 4GB (Preferences -> Advanced). -![Increasing docker engine resources](assets/docker-config.png) +![Increasing docker engine resources](../../../../readmes/assets/docker-config.png) ## Build/Deploy Tooling diff --git a/docusaurus/versioned_docs/version-1.0.X/cwf/setup.md b/docusaurus/versioned_docs/version-1.0.X/cwf/setup.md index 96a5cb5..cb521af 100644 --- a/docusaurus/versioned_docs/version-1.0.X/cwf/setup.md +++ b/docusaurus/versioned_docs/version-1.0.X/cwf/setup.md @@ -26,8 +26,8 @@ Vagrant will bring up the VM, then Ansible will provision the VM. * Once the CWAG VM is up and provisioned, run the following commands: -``HOST:magma/cwf/gateway USER$ vagrant ssh cwag``
-``AGW:~ USER$ cd magma/cwf/gateway/docker``
+``HOST:magma/cwf/gateway USER$ vagrant ssh cwag``

+``AGW:~ USER$ cd magma/cwf/gateway/docker``

``AGW:~/magma/cwf/gateway/docker USER$ docker-compose build --parallel`` ``AGW:~/magma/cwf/gateway/docker USER$ docker-compose up -d`` diff --git a/docusaurus/versioned_docs/version-1.0.X/howtos/README_package.md b/docusaurus/versioned_docs/version-1.0.X/howtos/README_package.md index 7ba477d..0f7175e 100644 --- a/docusaurus/versioned_docs/version-1.0.X/howtos/README_package.md +++ b/docusaurus/versioned_docs/version-1.0.X/howtos/README_package.md @@ -31,9 +31,9 @@ You should always do this. In general, try your best not to release broken packages. 1. Build the release like you normally would. -2. Spin up a fresh prod VM or gateway machine and copy the magma_.deb +2. Spin up a fresh prod VM or gateway machine and copy the magma_.deb generated above. -3. Run `sudo apt-get install gdebi; sudo gdebi magma_.deb' +3. Run `sudo apt-get install gdebi; sudo gdebi magma_.deb' 4. A VM reload or gateway reboot will likely be required due to kernel upgrade. This will simulate the exact steps that apt-get performs in production. diff --git a/docusaurus/versioned_docs/version-1.0.X/lte/config_agw.md b/docusaurus/versioned_docs/version-1.0.X/lte/config_agw.md index b92aef6..92e8202 100644 --- a/docusaurus/versioned_docs/version-1.0.X/lte/config_agw.md +++ b/docusaurus/versioned_docs/version-1.0.X/lte/config_agw.md @@ -65,14 +65,14 @@ network. Otherwise, select "Create Network" from the network selection icon at the bottom of the left sidebar. Select `lte` as the network type and fill the other fields as you see fit. -![Creating a network](assets/nms/createnetwork.png) +![Creating a network](../../../../readmes/assets/nms/createnetwork.png) Go back to the network management app using the app selector in the bottom left of the screen, then go to "Configure" in the left sidebar, followed by the "Network Configuration" tab at the top of the screen. Configure your RAN and EPC parameters which are appropriate for your hardware setup. -![Configuring a network](assets/nms/configurenetwork.png) +![Configuring a network](../../../../readmes/assets/nms/configurenetwork.png) ## Registering and Configuring Your Access Gateway @@ -92,13 +92,13 @@ MHYwEAYHKoZIzj0CAQYFK4EEACIDYgAECMB9zEbAlLDQLq1K8tgCLO8Kie5IloU4QuAXEjtR19jt0KTk Navigate to "Gateways" on the NMS via the left navigation bar, hit "Add Gateway", and fill out the form using the hardware secrets from above: -![Creating a gateway](assets/nms/create_agw.png) + After you create your gateway, hit the Edit icon in its table row, select the "LTE" tab, and configure your EPC/RAN parameters. Make sure you enable enodeB transmit. -![Configuring a gateway](assets/nms/configure_agw.png) + At this point, you can validate the connection between your AGW and Orchestrator: diff --git a/docusaurus/versioned_docs/version-1.0.X/lte/enodebd.md b/docusaurus/versioned_docs/version-1.0.X/lte/enodebd.md index 22ad52f..3b216a5 100644 --- a/docusaurus/versioned_docs/version-1.0.X/lte/enodebd.md +++ b/docusaurus/versioned_docs/version-1.0.X/lte/enodebd.md @@ -63,7 +63,7 @@ On the NMS, navigate to "eNodeB Devices" in the sidebar, and hit "Add EnodeB". Configure the RAN parameters as necessary. Note that fields left blank will be inherited from either the network or gateway LTE parameters: -![Configuring an eNodeB](assets/nms/configure_enb.png) +![Configuring an eNodeB](../../../../readmes/assets/nms/configure_enb.png) Then, go back to the "Gateways" page and edit the LTE configuration of your AGW. Enter the serial number of the enodeB you just provisioned into the @@ -158,7 +158,7 @@ failure until you add the corresponding IMSI to the subscriber database. On the NMS, go to "Subscribers", then "Add Subscriber". The SIM secrets can be entered either in hex or base64-encoded binary: -![Adding a subscriber](assets/nms/add_sub.png) +![Adding a subscriber](../../../../readmes/assets/nms/add_sub.png) Subscriber information will eventually propagate to the AGW. You can verify using the CLI command `"subscriber_cli.py list"` diff --git a/docusaurus/versioned_docs/version-1.0.X/lte/setup.md b/docusaurus/versioned_docs/version-1.0.X/lte/setup.md index 28b710e..348c21a 100644 --- a/docusaurus/versioned_docs/version-1.0.X/lte/setup.md +++ b/docusaurus/versioned_docs/version-1.0.X/lte/setup.md @@ -26,8 +26,8 @@ Vagrant will bring up the VM, then Ansible will provision the VM. * Once the Access Gateway VM is up and provisioned, run the following commands: -``HOST:magma/lte/gateway USER$ vagrant ssh magma``
-``AGW:~ USER$ cd magma/lte/gateway``
+``HOST:magma/lte/gateway USER$ vagrant ssh magma``

+``AGW:~ USER$ cd magma/lte/gateway``

``AGW:~/magma/lte/gateway USER$ make run`` Once the Access Gateway VM is running successfully, proceed to attaching the eNodeB. diff --git a/docusaurus/versioned_docs/version-1.0.X/orc8r/deploy_terraform.md b/docusaurus/versioned_docs/version-1.0.X/orc8r/deploy_terraform.md index 7d79304..6d47415 100644 --- a/docusaurus/versioned_docs/version-1.0.X/orc8r/deploy_terraform.md +++ b/docusaurus/versioned_docs/version-1.0.X/orc8r/deploy_terraform.md @@ -34,7 +34,7 @@ worker nodes of the EKS cluster. This can be found in the EC2 dashboard under "Key Pairs". If you're creating a new key pair, make sure not to lose the private key, you won't be able to recover it from AWS. -![creating an AWS keypair](assets/keypair.png) +![creating an AWS keypair](../../../../readmes/assets/keypair.png) Next, create a `vars.tfvars` file in your directory, *add it to your source control's .ignore*, and specify your desired RDS password and the name of the diff --git a/docusaurus/versioned_docs/version-1.1.X/basics/prerequisites.md b/docusaurus/versioned_docs/version-1.1.X/basics/prerequisites.md index f1ee242..35408de 100644 --- a/docusaurus/versioned_docs/version-1.1.X/basics/prerequisites.md +++ b/docusaurus/versioned_docs/version-1.1.X/basics/prerequisites.md @@ -38,7 +38,7 @@ vagrant plugin install vagrant-vbguest If you are on MacOS, you should start Docker for Mac and increase the memory allocation for the Docker engine to at least 4GB (Preferences -> Advanced). -![Increasing docker engine resources](assets/docker-config.png) +![Increasing docker engine resources](../../../../readmes/assets/docker-config.png) ## Build/Deploy Tooling diff --git a/docusaurus/versioned_docs/version-1.1.X/lte/config_agw.md b/docusaurus/versioned_docs/version-1.1.X/lte/config_agw.md index f28c0b9..3e84d22 100644 --- a/docusaurus/versioned_docs/version-1.1.X/lte/config_agw.md +++ b/docusaurus/versioned_docs/version-1.1.X/lte/config_agw.md @@ -70,14 +70,14 @@ network. Otherwise, select "Create Network" from the network selection icon at the bottom of the left sidebar. Select `lte` as the network type and fill the other fields as you see fit. -![Creating a network](assets/nms/createnetwork.png) +![Creating a network](../../../../readmes/assets/nms/createnetwork.png) Go back to the network management app using the app selector in the bottom left of the screen, then go to "Configure" in the left sidebar, followed by the "Network Configuration" tab at the top of the screen. Configure your RAN and EPC parameters which are appropriate for your hardware setup. -![Configuring a network](assets/nms/configurenetwork.png) +![Configuring a network](../../../../readmes/assets/nms/configurenetwork.png) ## Registering and Configuring Your Access Gateway @@ -97,13 +97,13 @@ MHYwEAYHKoZIzj0CAQYFK4EEACIDYgAECMB9zEbAlLDQLq1K8tgCLO8Kie5IloU4QuAXEjtR19jt0KTk Navigate to "Gateways" on the NMS via the left navigation bar, hit "Add Gateway", and fill out the form using the hardware secrets from above: -![Creating a gateway](assets/nms/create_agw.png) + After you create your gateway, hit the Edit icon in its table row, select the "LTE" tab, and configure your EPC/RAN parameters. Make sure you enable enodeB transmit. -![Configuring a gateway](assets/nms/configure_agw.png) + At this point, you can validate the connection between your AGW and Orchestrator: diff --git a/docusaurus/versioned_docs/version-1.1.X/lte/dev_notes.md b/docusaurus/versioned_docs/version-1.1.X/lte/dev_notes.md index dcdbcff..1c3ceb5 100644 --- a/docusaurus/versioned_docs/version-1.1.X/lte/dev_notes.md +++ b/docusaurus/versioned_docs/version-1.1.X/lte/dev_notes.md @@ -33,7 +33,7 @@ gateway and written here. This streamed config takes precedence over These configurations are local and are not exposed through the API. These include logging level, local network interface names, etc. - `/etc/magma/templates/.conf.template`: This contains the - structured template for the .conf file used as input to + structured template for the .conf file used as input to some services, such as Control-proxy, Dnsd, MME and Redis. - `/var/opt/magma/tmp/.conf`: The configuration file read by some services, such as Control-proxy, Dnsd, MME and Redis, at start-up. This diff --git a/docusaurus/versioned_docs/version-1.1.X/lte/enodebd.md b/docusaurus/versioned_docs/version-1.1.X/lte/enodebd.md index c3dfaf9..847a1fc 100644 --- a/docusaurus/versioned_docs/version-1.1.X/lte/enodebd.md +++ b/docusaurus/versioned_docs/version-1.1.X/lte/enodebd.md @@ -64,7 +64,7 @@ On the NMS, navigate to "eNodeB Devices" in the sidebar, and hit "Add EnodeB". Configure the RAN parameters as necessary. Note that fields left blank will be inherited from either the network or gateway LTE parameters: -![Configuring an eNodeB](assets/nms/configure_enb.png) +![Configuring an eNodeB](../../../../readmes/assets/nms/configure_enb.png) Then, go back to the "Gateways" page and edit the LTE configuration of your AGW. Enter the serial number of the enodeB you just provisioned into the @@ -159,7 +159,7 @@ failure until you add the corresponding IMSI to the subscriber database. On the NMS, go to "Subscribers", then "Add Subscriber". The SIM secrets can be entered either in hex or base64-encoded binary: -![Adding a subscriber](assets/nms/add_sub.png) +![Adding a subscriber](../../../../readmes/assets/nms/add_sub.png) Subscriber information will eventually propagate to the AGW. You can verify using the CLI command `"subscriber_cli.py list"` diff --git a/docusaurus/versioned_docs/version-1.1.X/lte/upgrade.md b/docusaurus/versioned_docs/version-1.1.X/lte/upgrade.md index ad72219..f633418 100644 --- a/docusaurus/versioned_docs/version-1.1.X/lte/upgrade.md +++ b/docusaurus/versioned_docs/version-1.1.X/lte/upgrade.md @@ -4,6 +4,7 @@ title: Upgrade to v1.1 sidebar_label: Upgrade to v1.1 hide_title: true original_id: agw_110_upgrade + --- # Upgrade to v1.1 @@ -21,7 +22,7 @@ the desired software version for that tier to `1.1.0-1589476391-5dbd6822`. The AGWs in this tier will pull this configuration and upgrade automatically. By default, we check for an upgrade every 5 minutes. -![1.1.0 upgrade](assets/agw_110_upgrade.png) +![1.1.0 upgrade](../../../../readmes/assets/agw_110_upgrade.png) When the gateway completes its upgrade, you should see that its reported software version in this tab has changed. If it hasn't changed, something diff --git a/docusaurus/versioned_docs/version-1.1.X/nms/grafana.md b/docusaurus/versioned_docs/version-1.1.X/nms/grafana.md index 0f972c3..3b26554 100644 --- a/docusaurus/versioned_docs/version-1.1.X/nms/grafana.md +++ b/docusaurus/versioned_docs/version-1.1.X/nms/grafana.md @@ -37,13 +37,13 @@ In the metrics page of the nms, there is now a tab called ‘Grafana’. When yo click on this link we have to do some book-keeping on the backend, so the initial load may take a few seconds. -![Grafana homepage](assets/nms/grafana_homepage.png) +![Grafana homepage](../../../../readmes/assets/nms/grafana_homepage.png) You’ll see three dashboards available to you from the start. These replicate the three dashboards in the NMS that are built-in. Go to one of the dashboards and you’ll now see a Grafana version of the NMS dashboard. -![Grafana variables](assets/nms/grafana_variables.png) +![Grafana variables](../../../../readmes/assets/nms/grafana_variables.png) These dashboards contain dropdown selectors to choose which network(s) and gateway(s) you want to look at. In the NMS dashboard you were only able to @@ -63,7 +63,7 @@ The simple way is to just click on the “+” icon on the left sidebar, then create a new dashboard. There is ample documentation about grafana dashboards online if you need help creating your dashboard. -![Grafana new dashboard](assets/nms/grafana_new_dashboard.png) +![Grafana new dashboard](../../../../readmes/assets/nms/grafana_new_dashboard.png) - Grafana documentation on creating dashboards: [Grafana Dashboards](https://grafana.com/docs/grafana/latest/features/dashboard/dashboards/) @@ -77,7 +77,7 @@ Your new dashboard will now have the gatewayID and networkID variables. An example of how to use these variables in your queries: -![Grafana query](assets/nms/grafana_query.png) +![Grafana query](../../../../readmes/assets/nms/grafana_query.png) Some technical details: You need to use `=~` when matching label names with these variables in order to see more than one network or gateway at a time. diff --git a/docusaurus/versioned_docs/version-1.1.X/nms/organizations.md b/docusaurus/versioned_docs/version-1.1.X/nms/organizations.md index c29a623..4b50897 100644 --- a/docusaurus/versioned_docs/version-1.1.X/nms/organizations.md +++ b/docusaurus/versioned_docs/version-1.1.X/nms/organizations.md @@ -45,18 +45,18 @@ Create one organization and give it access to all networks. This is essentially the same as v1.0 when there was no tenancy support. The only difference is that the NMS is accessible from the URL `magma-test.youdomain.com` -![Org with access to all networks](assets/nms/org_all_networks.png) +![Org with access to all networks](../../../../readmes/assets/nms/org_all_networks.png) ### Multiple Tenants Create a second organization and give it access to specific networks: -![List of organizations](assets/nms/org_multiple_list.png) +![List of organizations](../../../../readmes/assets/nms/org_multiple_list.png) Here, fb-test has access to all networks, while magma-test only has access to the network `mpk_test`. Create a user in this organization to use it: -![Add user to org](assets/nms/org_add_user.png) +![Add user to org](../../../../readmes/assets/nms/org_add_user.png) When you log in to `magma-test.youdomain.com` you will only be able to see the network `mpk_test`. If you log into `fb-test.yourdomain.com`, you will diff --git a/docusaurus/versioned_docs/version-1.2.X/basics/introduction.md b/docusaurus/versioned_docs/version-1.2.X/basics/introduction.md new file mode 100644 index 0000000..16b10f5 --- /dev/null +++ b/docusaurus/versioned_docs/version-1.2.X/basics/introduction.md @@ -0,0 +1,28 @@ +--- +id: version-1.2.X-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](../../../../readmes/assets/magma_overview.png?raw=true "Magma Architecture") diff --git a/docusaurus/versioned_docs/version-1.2.X/basics/prerequisites.md b/docusaurus/versioned_docs/version-1.2.X/basics/prerequisites.md index 86fcf51..f756afe 100644 --- a/docusaurus/versioned_docs/version-1.2.X/basics/prerequisites.md +++ b/docusaurus/versioned_docs/version-1.2.X/basics/prerequisites.md @@ -38,7 +38,7 @@ vagrant plugin install vagrant-vbguest If you are on MacOS, you should start Docker for Mac and increase the memory allocation for the Docker engine to at least 4GB (Preferences -> Advanced). -![Increasing docker engine resources](assets/docker-config.png) +![Increasing docker engine resources](../../../../readmes/assets/docker-config.png) ## Build/Deploy Tooling diff --git a/docusaurus/versioned_docs/version-1.2.X/faq/magma_faq.md b/docusaurus/versioned_docs/version-1.2.X/faq/magma_faq.md new file mode 100644 index 0000000..3ed286e --- /dev/null +++ b/docusaurus/versioned_docs/version-1.2.X/faq/magma_faq.md @@ -0,0 +1,108 @@ +--- +id: version-1.2.X-magma_faq +title: Frequently Asked Questions +hide_title: true +original_id: magma_faq +--- +# Frequently Asked Questions +This section lists some of the commonly asked questions related to Magma operation. + +## Access Gateway +### How can I check the status of eNodeB(s) connected on a particular gateway? + - Run `sudo enodebd_cli.py get_all_status` to check eNodeB(s) status. + - **NOTE:** Output of this command will only show eNodeB(s) configured with TR069 protocol. + +### How can I see different interfaces of gateway? + - Run `sudo ip addr` to see all configured interfaces. + - Commonly, interface `eth0` is used for internet connectivity and `eth1` is used for RAN connectivity. + - You may run `ping google.com -I eth0` to check AGW connectivity with internet. + - Also, you may run `ping -I eth1` to check AGW connectivity with eNodeB. You can get eNodeB IP from `enodeb_cli` as mentioned in above question. + +### How can I see attached subscribers list on a particular gateway and their browsing status? + - Run `sudo mobility_cli.py get_subscriber_table`, to see all attached subscribers. + - Note down the IP obtained by the user from above command, then run `sudo pipelined_cli.py debug display_flows | grep ` for packet flow info of that user. + +### How can I check services running on a gateway and their status? + - **Check all services:** `sudo service magma@* status`. + - **Check specific service:** `sudo service magma@ status`. e.g. `sudo service magma@enodebd status`. + +### How can I collect logs for a particular service? + - Run `sudo journalctl -fu magma@`, e.g. for enodeb service, run `sudo journalctl -fu magma@enodebd`. + +### How can I check the status of the OVS module on a gateway? + - Run `sudo ovs-vsctl show` to check. + +### How can I capture packets for troubleshooting? + - You can use general purpose tcpdump command to capture traffic at any of your interfaces. e.g. run `sudo tcpdump -i eth1 -w /tmp/capture.pcap` to capture packet at eth1 interface. + +### What are the common troubleshooting logs in gateway? + - **syslog:** `/var/log/syslogs`. + - **MME logs:** `/var/log/mme.log`. + - **eNodeB logs:** `/var/log/enodebd.log`. + +### Where can I find the configuration of a gateway? + - File `/var/opt/magma/configs/gateway.mconfig` is the configuration streamed down from Orchestrator. + - Any custom static configs will also be in directory `/var/opt/magma/configs` with a `.yml` extension. + - Default static configs are located at `/etc/magma/configs`. + - systemd unit files are located at `/etc/system/systemd`. + +### How can I restart gateway services? + - There are 2 options to restart gateway services. First from CLI and other from NMS UI. + - To restart services from CLI, login to AGW node, then perform below steps: + - Run `sudo service magma@* stop` to stop services. + - Then, run `sudo service magma@magmad restart` to restart services. + - To restart services from NMS UI, perform below steps: + - Login to NMS UI and go to **Gateways** option from left hand pane menu. + - Then, click on **edit** option against the gateway for which you wish to reboot services. + - From the popup window, select tab **COMMANDS**. Then, check section **Reboot**. + - Click on **Restart Services** to restart all AGW services. + +### How can I reboot the gateway? + - There are 2 options to reboot gateway. First from CLI and other from NMS UI. + - To reboot AGW from CLI, login to AGW node, then run `sudo init 6` to reboot whole AGW node. + - To reboot AGW from NMS UI, perform below steps: + - Login to NMS UI and go to **Gateways** option from left hand pane menu. + - Then, click on **edit** option against the gateway which you wish to reboot. + - From the popup window, select tab **COMMANDS**. Then, check section **Reboot**. + - Click on **Reboot** to reboot the AGW node. + +## Orchestrator +### How can I check production pods in Orchestrator running on Kubernetes? + - **For all pods:** `kubectl -n magma get pods`. + - **Logs of a particular pod:** `kubectl -n magma logs -f `. + - **NOTE:** In above commands, please use the actual namespace after `-n` you have chosen to install orc8r in. + +### How can I test Orchestrator connection with Gateway? + - Login to Gateway, then run `sudo checkin_cli.py`. + +### Where can I find API endpoint? + - If you have followed the [install guide](../orc8r/deploy_install), it'll be at `https://api.youdomain.com/apidocs/v1/` (the trailing slash is important). + - You will need to load the `admin_operator.pfx` certificate into your keychain/browser, otherwise, API access will be blocked. + +### How can I use Swagger UI to trigger API request? + - Open Swagger UI, then got to interested section, e.g. **EnodeBs**. + - Then click on API trigger action button e.g. **GET**, **PUT**, **DELETE** etc. + - Click on **Try it out** button on right hand side. + - Put in the required inputs and click **Execute**. + +## NMS +### What is an NMS (Network Management System)? + - NMS is a simple UI based solution provided to manage, configuring, and monitor the network effectively. You can monitor various network metrics, configure and monitor alerts, subscribers, gateways, eNodeBs etc. + +### How can I check various network metrics over NMS? + - Login to NMS UI, then click **Metrics** on the left hand side menu to check various network metrics available. + +### How can I configure an alert on NMS? + - Login to NMS UI, then click on **Alert** on left hand side menu. Go to tab **Alert Rules** to configure rule for alert. + +### How can I make sure Gateway is properly connected with NMS? + - Login to NMS and select **Gateway** from left hand side menu bar. + - You can see all the Gateways configured in NMS. + - Check for the Green light besides any particular Gateway, if it is green that means it is properly connected. + +### How can I restart eNodeB from NMS? + - Login to NMS UI and go to **Gateways** option from left hand pane menu. + - Then, click on **edit** option against the gateway with which eNodeB is connected. + - From the popup window, select tab **COMMANDS**. Then, check section **Reboot eNodeB**. + - Enter eNodeB serial ID of eNodeB and click on **Reboot** to reboot that particular eNodeB. + - **Note:**Only those eNodeBs can be rebooted in this manner which are configured with TR069 protocol. diff --git a/docusaurus/versioned_docs/version-1.2.X/feg/deploy_build.md b/docusaurus/versioned_docs/version-1.2.X/feg/deploy_build.md new file mode 100644 index 0000000..8af8aa6 --- /dev/null +++ b/docusaurus/versioned_docs/version-1.2.X/feg/deploy_build.md @@ -0,0 +1,24 @@ +--- +id: version-1.2.X-deploy_build +title: Building Federation Gateway +hide_title: true +original_id: deploy_build +--- + +# Building Federation Gateway Components + +Start up your Docker daemon, `cd` to where you've cloned Magma, then: + +```bash +cd magma/feg/gateway/docker +docker-compose build --parallel +``` + +If this is your first time building the FeG, this may take a while. When this +job finishes, upload these images to your image registry: + +```bash +../../../orc8r/tools/docker/publish.sh -r -i gateway_python +../../../orc8r/tools/docker/publish.sh -r -i gateway_go +../../../orc8r/tools/docker/publish.sh -r -i gateway_radius +``` diff --git a/docusaurus/versioned_docs/version-1.2.X/feg/deploy_install.md b/docusaurus/versioned_docs/version-1.2.X/feg/deploy_install.md new file mode 100644 index 0000000..12ef8b2 --- /dev/null +++ b/docusaurus/versioned_docs/version-1.2.X/feg/deploy_install.md @@ -0,0 +1,160 @@ +--- +id: version-1.2.X-deploy_install +title: Installing Federation Gateway +hide_title: true +original_id: deploy_install +--- +# Installing Federation Gateway + +## Prerequisites + +To install the Federation Gateway, there are three required files that are +deployment-specific. These are described below: + +* `rootCA.pem` - This file should match the `rootCA.pem` of the Orchestrator +that the Federation Gateway will connect to. + +* `control_proxy.yml` - This file is used to configure the `magmad` +and `control_proxy` services to point toward the appropriate Orchestrator. +A sample configuration is provided below. The `bootstrap_address`, +`bootstrap_port`, `controller_address`, and `controller_port` are the +parameters that will likely need to be modified. + +``` +# +# Copyright 2020 The Magma Authors. + +# This source code is licensed under the BSD-style license found in the +# LICENSE file in the root directory of this source tree. + +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +# nghttpx config will be generated here and used +nghttpx_config_location: /var/tmp/nghttpx.conf + +# Location for certs +rootca_cert: /var/opt/magma/certs/rootCA.pem +gateway_cert: /var/opt/magma/certs/gateway.crt +gateway_key: /var/opt/magma/certs/gateway.key + +# Listening port of the proxy for local services. The port would be closed +# for the rest of the world. +local_port: 8443 + +# Cloud address for reaching out to the cloud. +cloud_address: controller.magma.test +cloud_port: 443 + +bootstrap_address: bootstrapper-controller.magma.test +bootstrap_port: 443 + +# Option to use nghttpx for proxying. If disabled, the individual +# services would establish the TLS connections themselves. +proxy_cloud_connections: True + +# Allows http_proxy usage if the environment variable is present +allow_http_proxy: True +``` + +* `.env` - This file provides any deployment specific environment variables used +in the `docker-compose.yml` of the Federation Gateway. A sample configuration +is provided below: + +``` +# Copyright 2020 The Magma Authors. + +# This source code is licensed under the BSD-style license found in the +# LICENSE file in the root directory of this source tree. + +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +COMPOSE_PROJECT_NAME=feg +DOCKER_REGISTRY= +DOCKER_USERNAME= +DOCKER_PASSWORD= +IMAGE_VERSION=latest + +ROOTCA_PATH=/var/opt/magma/certs/rootCA.pem +CONTROL_PROXY_PATH=/etc/magma/control_proxy.yml +SNOWFLAKE_PATH=/etc/snowflake + +CERTS_VOLUME=/var/opt/magma/certs +CONFIGS_VOLUME=/var/opt/magma/configs + +# This section is unnecessary if using host networking +S6A_LOCAL_PORT=3868 +S6A_HOST_PORT=3868 +S6A_NETWORK=sctp + +SWX_LOCAL_PORT=3869 +SWX_HOST_PORT=3869 +SWX_NETWORK=sctp + +GX_LOCAL_PORT=3870 +GX_HOST_PORT=3870 +GX_NETWORK=tcp + +GY_LOCAL_PORT=3871 +GY_HOST_PORT=3871 +GY_NETWORK=tcp +``` + +## Installation + +The installation is done using the `install_gateway.sh` script located at +`magma/orc8r/tools/docker`. To install, copy that file and the three files +described above into a directory on the install host. Then + +```console +INSTALL_HOST [~/]$ sudo ./install_gateway.sh feg +``` + +After this completes, you should see: `Installed successfully!!` + +## Registration + +After installation, the next step is to register the gateway with the Orchestrator. +To do so: + +```console +INSTALL_HOST [~/]$ cd /var/opt/magma/docker +INSTALL_HOST [/var/opt/magma/docker]$ docker-compose exec magmad /usr/local/bin/show_gateway_info.py +``` + +This will output a hardware ID and a challenge key. This information must be +registered with the Orchestrator. At this time, NMS support for FeG +registration is still in-progress. + +To register the FeG, go to the Orchestrator's APIdocs in your browser. +**Note: It is highly encouraged to use V1 of the apidocs** +(i.e. https://controller.url.sample:9443/apidocs/v1/). + +Now, create a Federation Network. This is found at `/feg` under the +**Federation Networks** section. Then register the gateway under the +**Federation Gateway** section at `/feg/{network_id}/gateways` using the +network ID of the Federation Network and the hardware ID and challenge key +from the previous step. + +To verify that the gateway was correctly registered, run: + +```console +INSTALL_HOST [~/]$ cd /var/opt/magma/docker +INSTALL_HOST [/var/opt/magma/docker]$ docker-compose exec magmad /usr/local/bin/checkin_cli.py +``` + +## Upgrades + +The Federation Gateway supports NMS initiated upgrades. These can be triggered +from the NMS under the `Configure` section by updating the FeG's tier to the +appropriate `Software Version`. After triggering the upgrade from the NMS, +magmad on the gateway will pull down the specified docker images, +update any static configuration, and update the docker-compose file to the +appropriate version. diff --git a/docusaurus/versioned_docs/version-1.2.X/feg/deploy_intro.md b/docusaurus/versioned_docs/version-1.2.X/feg/deploy_intro.md new file mode 100644 index 0000000..a11b985 --- /dev/null +++ b/docusaurus/versioned_docs/version-1.2.X/feg/deploy_intro.md @@ -0,0 +1,17 @@ +--- +id: version-1.2.X-deploy_intro +title: Introduction +hide_title: true +original_id: deploy_intro +--- +# Deploying Federation Gateway: Introduction + +These pages will walk through the full process of deploying a +Federation Gateway, from building the various containers that you'll need +to installing them on either a Bare-Metal or VM host. This installation guide +targets *production* environments - if you aren't ready for this, the developer +documentation will be up shortly. + +If you want to get a head start on the development setup, you can build the +FeG containers following this guide and use docker-compose at +`magma/feg/gateway/docker` to spin up the local version of the FeG. diff --git a/docusaurus/versioned_docs/version-1.2.X/feg/legacy/FAQ.md b/docusaurus/versioned_docs/version-1.2.X/feg/legacy/FAQ.md new file mode 100644 index 0000000..d40a8db --- /dev/null +++ b/docusaurus/versioned_docs/version-1.2.X/feg/legacy/FAQ.md @@ -0,0 +1,25 @@ +--- +id: version-1.0.X-faq +title: FAQ +hide_title: true +original_id: faq +--- +# FAQ + +1. Do I need to run the federated gateway as an individual developer? + + - It is highly unlikely you'll need this component. Only those who plan + to integrate with a Mobile Network Operator will need the federated gateway. + +2. I'm seeing 500's in `/var/log/syslog`. How do I fix this? + + - Ensure your cloud VM is up and services are running + - Ensure that you've run `register_feg_vm` at `magma/feg/gateway` on your host machine + +3. I'm seeing 200's, but streamed configs at `/var/opt/magma/configs` aren't being updated? + + - Ensure the directory at `/var/opt/magma/configs` exists + - Ensure the gateway configs in NMS are created (see [link](https://github.com/magma/magma/blob/v1.1.0/docs/Magma_Network_Management_System.pdf) for more instructions) + - Ensure one of the following configs exist: + - [Federated Gateway Network Configs](https://127.0.0.1:9443/apidocs#/Networks/post_networks__network_id__configs_federation) + - [Federated Gateway Configs](https://127.0.0.1:9443/apidocs#/Gateways/post_networks__network_id__gateways__gateway_id__configs_federation) diff --git a/docusaurus/versioned_docs/version-1.2.X/feg/legacy/README.md b/docusaurus/versioned_docs/version-1.2.X/feg/legacy/README.md new file mode 100644 index 0000000..4398cfc --- /dev/null +++ b/docusaurus/versioned_docs/version-1.2.X/feg/legacy/README.md @@ -0,0 +1,45 @@ +--- +id: version-1.0.X-readme +title: Federated Gateway (FeG) +sidebar_label: Overview +hide_title: true +original_id: readme +--- +# Federated Gateway (FeG) +The federated gateway provides remote procedure call (GRPC) based interfaces to standard 3GPP components, such as +HSS (S6a, SWx), OCS (Gy), and PCRF (Gx). The exposed RPC interface provides versioning & backward compatibility, +security (HTTP2 & TLS) as well as support for multiple programming languages. The Remote Procedures below provide +simple, extensible, multi-language interfaces based on GRPC which allow developers to avoid dealing with the +complexities of 3GPP protocols. Implementing these RPC interfaces allows networks running on Magma to integrate +with traditional 3GPP core components. + +![Federated Gateway architecture diagram](https://github.com/facebookincubator/magma/blob/master/docs/readmes/assets/federated_gateway_diagram.png?raw=true "FeG Architecture") + +The Federated Gateway supports the following features and functionalities: + +1. Hosting centralized control plane interface towards HSS, PCRF, OCS and MSC/VLR on behalf of distributed AGW/EPCs. +2. Establishing diameter connection with HSS, PCRF and OCS directly as 1:1 or via DRA. +3. Establishing SCTP/IP connection with MSC/VLR. +4. Interfacing with AGW over GPRC interface by responding to remote calls from EPC (MME and Sessiond/PCEF) components, + converting these remote calls to 3GPP compliant messages and then sending these messages to the appropriate core network + components such as HSS, PCRF, OCS and MSC. Similarly the FeG receives 3GPP compliant messages from HSS, PCRF, OCS and MSC + and converts these to the appropriate GPRC messages before sending them to the AGW. + + + +Please see the **[Magma Product Spec](https://github.com/magma/magma/blob/v1.1.0/docs/Magma_Specs_V1.1.pdf)** for more detailed information. + +## Federated Gateway Services & Tools + +The following services run on the federated gateway: + - `s6a_proxy` - translates calls from GRPC to S6a protocol between AGW and HSS + - `session_proxy` - translates calls from GRPC to gx/gy protocol between AGW and PCRF/OCS + - `csfb` - translates calls from GRPC interface to csfb protocol between AGW and VLR + - `swx_proxy` - translates GRPC interface to SWx protocol between AGW and HSS + - `gateway_health` - provides health updates to the orc8r to be used for + achieving highly available federated gateway clusters (see **[Magma Product Spec](https://github.com/magma/magma/blob/v1.1.0/docs/Magma_Specs_V1.1.pdf)** + for more details) + - `radiusd` - fetches metrics from the running radius server and exports them + +Associated tools for sending requests and debugging issues can be found +at `magma/feg/gateway/tools`. diff --git a/docusaurus/versioned_docs/version-1.2.X/feg/legacy/docker_setup.md b/docusaurus/versioned_docs/version-1.2.X/feg/legacy/docker_setup.md new file mode 100644 index 0000000..5f705eb --- /dev/null +++ b/docusaurus/versioned_docs/version-1.2.X/feg/legacy/docker_setup.md @@ -0,0 +1,64 @@ +--- +id: version-1.0.X-docker_setup +title: FeG Docker Setup +hide_title: true +original_id: docker_setup +--- +# FeG Docker Setup + +The FeG runs each service in its own Docker container. +Production services are defined in `docker-compose.yml`. +Development services are defined in `docker-compose.override.yml`. +The development `test` service is used to run unit tests and regenerate Swagger/Protobuf code. +The development `test` service can also be used to perform other development-related procedures. + +## Requirements + +To run the FeG with docker, both docker and docker compose must be installed. +* Follow [these steps](https://docs.docker.com/install/) to install docker +* Follow [these steps](https://docs.docker.com/compose/install/) to install docker compose + +NOTE: If you are running the FeG on Mac, you will need to increase the memory +limit of the docker daemon to at least 4GB to build the images. Otherwise, +when building the Go image, you may see an error message similar to this: +`/usr/local/go/pkg/tool/linux_amd64/link: signal: killed`. + +The `rootCA.pem` certificate must be located in the `.cache/test_certs` folder, +so that it can be mounted into the appropriate containers from there. + +## Development + +Follow these steps to run the FeG services: +1. `cd magma/feg/gateway/docker` +2. `docker-compose build` +3. `docker-compose up -d` + +Each service should now be running in each of its containers. +By default, both production and development services should be running. +To place a shell into the test container, run the command: + +`docker-compose exec test /bin/bash` + +The test container contains the mounted source code and configuration settings. +The mounted source code and configuration settings can be changed externally +and the changes will be reflected inside the test container. +Run the command `make precommit` in the container before submitting a patch. + +To make changes to currently running FeG services, the containers must be rebuilt and restarted: +1. `docker-compose down` +2. `docker-compose build` +3. `docker-compose up -d` + +To manage the containers, the following commands are useful: +* `docker-compose ps` (get status of each container) +* `docker-compose logs -f` (tail logs of all containers) +* `docker-compose logs -f ` (tail logs of a particular service) +* `docker-compose down` (stop all services) + +## Publishing the images + +To push production images to a private docker registry, use the following script: +``` +[/magma/feg/gateway/docker]$ ../../../orc8r/tools/docker/publish.sh -r -i gateway_python +[/magma/feg/gateway/docker]$ ../../../orc8r/tools/docker/publish.sh -r -i gateway_go +``` diff --git a/docusaurus/versioned_docs/version-1.2.X/howtos/ue_metering.md b/docusaurus/versioned_docs/version-1.2.X/howtos/ue_metering.md index aae47dc..30c8ddc 100644 --- a/docusaurus/versioned_docs/version-1.2.X/howtos/ue_metering.md +++ b/docusaurus/versioned_docs/version-1.2.X/howtos/ue_metering.md @@ -20,7 +20,7 @@ This feature is currently built to enable post-pay charging. Metering information is available through our metrics REST endpoint. The metric name used is `ue_traffic`. -![Swagger REST API Endpoint](assets/ue_metering.png) +![Swagger REST API Endpoint](../../../../readmes/assets/ue_metering.png) ### Configuring Metering diff --git a/docusaurus/versioned_docs/version-1.2.X/lte/config_agw.md b/docusaurus/versioned_docs/version-1.2.X/lte/config_agw.md index 3bc5d38..fcd42b6 100644 --- a/docusaurus/versioned_docs/version-1.2.X/lte/config_agw.md +++ b/docusaurus/versioned_docs/version-1.2.X/lte/config_agw.md @@ -70,7 +70,7 @@ is a fresh Orchestrator install, you will be prompted to create your first network. Otherwise, select "Create Network" from the network selection icon at the bottom of the left sidebar. -![Creating a network](assets/nms/createnetwork_12.png) +![Creating a network](../../../../readmes/assets/nms/createnetwork_12.png) Fill out the network creation modal with the parameters that you want. There are 3 steps in the modal window, but the network will be created after you hit diff --git a/docusaurus/versioned_docs/version-1.2.X/lte/config_apn.md b/docusaurus/versioned_docs/version-1.2.X/lte/config_apn.md index 7d296cb..f373b15 100644 --- a/docusaurus/versioned_docs/version-1.2.X/lte/config_apn.md +++ b/docusaurus/versioned_docs/version-1.2.X/lte/config_apn.md @@ -38,7 +38,7 @@ will be impacted by these changes. button and filling out the requested fields. After saving these changes, the page should refresh with the new list of APNs and their configurations. -![Creating an APN Configuration](assets/nms/add_apnconfig.png) +![Creating an APN Configuration](../../../../readmes/assets/nms/add_apnconfig.png) ## Add APN Configurations to Subscriber Profiles @@ -52,7 +52,7 @@ field (screenshot below shows the view after clicking on the "Add Subscriber" button). Once you save the updated or new subscriber information, the APNs added to the subscriber profile will show be reflected on the page. -![Adding subscriber with APN](assets/nms/add_apn2subscriber.png) +![Adding subscriber with APN](../../../../readmes/assets/nms/add_apn2subscriber.png) ### Notes diff --git a/docusaurus/versioned_docs/version-1.2.X/lte/dev_notes.md b/docusaurus/versioned_docs/version-1.2.X/lte/dev_notes.md index 0690723..2cbbeb7 100644 --- a/docusaurus/versioned_docs/version-1.2.X/lte/dev_notes.md +++ b/docusaurus/versioned_docs/version-1.2.X/lte/dev_notes.md @@ -33,7 +33,7 @@ gateway and written here. This streamed config takes precedence over These configurations are local and are not exposed through the API. These include logging level, local network interface names, etc. - `/etc/magma/templates/.conf.template`: This contains the - structured template for the .conf file used as input to + structured template for the .conf file used as input to some services, such as Control-proxy, Dnsd, MME and Redis. - `/var/opt/magma/tmp/.conf`: The configuration file read by some services, such as Control-proxy, Dnsd, MME and Redis, at start-up. This diff --git a/docusaurus/versioned_docs/version-1.2.X/lte/enodebd.md b/docusaurus/versioned_docs/version-1.2.X/lte/enodebd.md index ae1e8d8..de64213 100644 --- a/docusaurus/versioned_docs/version-1.2.X/lte/enodebd.md +++ b/docusaurus/versioned_docs/version-1.2.X/lte/enodebd.md @@ -67,7 +67,7 @@ Configure the RAN parameters in the resulting multi-step modal as necessary. Note that fields left blank will be inherited from either the network or gateway LTE parameters: -![Configuring an eNodeB](assets/nms/configure_enb_12.png) +![Configuring an eNodeB](../../../../readmes/assets/nms/configure_enb_12.png) Then, go back to the "Gateways" page and click on the ID of the AGW that you registered in the gateway table. Click through to the "Config" tab of the @@ -75,7 +75,7 @@ AGW detail view, then hit "Edit" by the RAN configuration. Select the eNodeB that you just registered in the multi-select dropdown, then save the update. Make sure that transmit is enabled. -![Connecting an eNodeB](assets/nms/connect_enb.png) +![Connecting an eNodeB](../../../../readmes/assets/nms/connect_enb.png) ### Basic Troubleshooting After connecting your eNodeB(s) to the gateway through the `eth1` interface, you diff --git a/docusaurus/versioned_docs/version-1.2.X/lte/s1ap_tests.md b/docusaurus/versioned_docs/version-1.2.X/lte/s1ap_tests.md new file mode 100644 index 0000000..3cc2abe --- /dev/null +++ b/docusaurus/versioned_docs/version-1.2.X/lte/s1ap_tests.md @@ -0,0 +1,197 @@ +--- +id: version-1.2.X-s1ap_tests +title: S1AP Integration Tests +hide_title: true +original_id: s1ap_tests +--- +# S1AP Integration Tests +Current testing workflow for VM-only S1AP integration tests. We cover +gateway-only tests and some general notes. + + + +Our VM-only tests use 3 Vagrant-managed VMs hosted on the local device (laptop): + +- *magma*, i.e. magma-dev or gateway +- *magma_test*, i.e. s1ap_tester +- *magma_trfserver*, i.e. an Iperf server to generate uplink/downlink traffic + +## Gateway-only tests + +These tests use all 3 VMs listed above. The *magma_test* VM abstracts away the +UE and eNodeB, the *magma_trfserver* emulates the Internet, while the *magma* VM +acts as the gateway between *magma_test* and *magma_trfserver*. + +### Gateway VM setup + +Spin up and provision the gateway VM, then make and start its services: + +1. From `magma/lte/gateway` on the host machine: `vagrant up magma && vagrant ssh magma` +1. Now in the gateway VM: `cd $MAGMA_ROOT/lte/gateway && make run` + +### Test VM setup + +Spin up and provision the s1ap tester's VM, make, then make in the integ_tests directory. + +1. From `magma/lte/gateway` on the host machine: `vagrant up magma_test && vagrant ssh magma_test` +1. Now in the *magma_test* VM: + 1. `cd $MAGMA_ROOT/lte/gateway/python && make` + 1. `cd integ_tests && make` + +### Run tests + +From `$MAGMA_ROOT/lte/gateway/python/integ_tests` on the *magma_test* VM, run +either individual tests or the full suite of tests. A safe, non-flaky test to +run is `s1aptests/test_attach_detach.py`. + +* Individual test(s): `make integ_test TESTS=` +* All tests: `make integ_test` + +**Note**: The traffic tests will fail as traffic server is not running in this +setup. Look at the section below on running traffic tests. + +### Running uplink/downlink traffic tests + +1. On the *magma* VM, run, `disable-tcp-checksumming` + +1. On the *magma_test* VM, `disable-tcp-checksumming` + +1. Start the traffic server VM from the host, `vagrant up magma_trfserver && vagrant ssh magma_trfserver` + +1. From *magma_trfserver* VM, run `disable-tcp-checksumming && trfgen-server` + +Running `make integ_test` in *magma_test* VM should succeed now. + +## Testing stateless Access Gateway + +The Access Gateway by default runs a set of stateful services, which means that +whenever the services are restarted, all previous state of UEs and eNodeBs, and +they need to reconnect and re-register. Alternatively, we can switch the Access +Gateway to be stateless, as shown below, so that all UE state is preserved +across service restarts. + +Note that this is a feature in development, so some tests from the integ_test +suite may not pass. + +All the tests below assume you have completed the Gateway Setup and Test VM +Setup described above. + +### Testing one stateless service + +#### Stateless MME +This section describes how to test whether MME service is persisting state to Redis. + +On gateway VM: + +1. Disable Pipelined, Mobilityd, Sctpd and Sessiond from restarting when MME +restarts. + + `cd /etc/systemd/system` + + comment out the line `PartOf=magma@mme.service` from the following files + (you will need sudo privileges): + + magma@mobilityd.service, magma@pipelined.service, magma@sessiond.service and +sctpd.service + + `sudo systemctl daemon-reload` + +1. In `/etc/magma/mme.yml`, set `use_stateless` to true +1. Clean up all the state in redis: `redis-cli -p 6380 FLUSHALL`. This might +throw a "Could not connect" error if magma@redis service is not running. Start +the redis service with `sudo service magma@redis start` and then try again. +1. `cd $MAGMA_ROOT/lte/gateway; make restart` + +On test VM: +1. Basic attach/detach test where MME is restarted mid-way: + + `make integ_test TESTS=s1aptests/test_attach_detach_with_mme_restart.py` + +1. Attach with uplink UDP traffic, where MME is restarted while UDP traffic is +flowing: + + `make integ_test TESTS=s1aptests/test_attach_ul_udp_data_with_mme_restart.py` + + , make sure traffic server VM is running (as described in traffic tests above) and +TCP checksum is disabled on all VMs. + +#### Stateless Mobilityd +This section describes how to test whether Mobilityd service is persisting state to Redis. + +On gateway VM: + +1. Disable MME from restarting when Mobilityd restarts. + + comment out the line `PartOf=magma@mobilityd.service` from the MME system +service file `/etc/systemd/system/magma@mme.service` (you will need sudo privileges): + + `sudo systemctl daemon-reload` + +1. In `/etc/magma/mobilityd.yml`, set `persist_to_redis` to `true` + +1. Clean up all the state in redis: `redis-cli -p 6380 FLUSHALL`. This might +throw a "Could not connect" error if magma@redis service is not running. Start +the redis service with `sudo service magma@redis start` and then try again. + +1. `cd $MAGMA_ROOT/lte/gateway; make restart` + +On test VM: +1. `cd $MAGMA_ROOT/lte/gateway/python && make` +1. `cd integ_tests && make` +1. Basic attach/detach test where Mobilityd is restarted mid-way: + + `make integ_test TESTS=s1aptests/test_attach_detach_with_mobilityd_restart.py` + +1. Test IP blocks are maintained across service restart + + `make integ_test TESTS=s1aptests/test_attach_detach_multiple_ip_blocks_mobilityd_restart.py` + +#### Stateless Pipelined +This section describes how to test whether Pipelined service is persisting state to Redis. + +On gateway VM: + +1. Disable MME from restarting when Pipelined restarts. + + comment out the line `PartOf=magma@pipelined.service` from the MME system +service file `/etc/systemd/system/magma@mme.service` (you will need sudo privileges): + + `sudo systemctl daemon-reload` + +1. In `/etc/magma/pipelined.yml`, set `clean_restart` to `false` + +1. Clean up all the state in redis: `redis-cli -p 6380 FLUSHALL`. This might +throw a "Could not connect" error if magma@redis service is not running. Start +the redis service with `sudo service magma@redis start` and then try again. + +1. `cd $MAGMA_ROOT/lte/gateway; make restart` + +On test VM: +1. `cd $MAGMA_ROOT/lte/gateway/python && make` +1. `cd integ_tests && make` +1. UDP traffic test where Pipelined is restarted mid-way: + + `make integ_test TESTS=s1aptests/test_attach_ul_udp_data_with_pipelined_restart.py` + + +### Testing stateless gateway with all services + +To test the gateway with all services being stateless, + +1. On gateway VM, follow steps 1 and 2 for each of Stateless MME, Mobilityd and Pipelined as +listed above + +1. On test VM, you can run any of the test cases for individual service restarts +listed above. Further, you can test attach with uplink UDP traffic, where +multiple services are restarted while UDP traffic is flowing: + + `make integ_test TESTS=s1aptests/test_attach_ul_udp_data_with_multiple_service_restart.py` + + , make sure traffic server VM is running (as described in traffic tests above) and +TCP checksum is disabled on all VMs. + +## Notes + +- Restart the *magma* VM (`vagrant reload magma`) on an assertion error involving `ENB_S1_SETUP_RESP.` This is a known issue. +- See *[Bindings for Magma's REST API](https://fb.quip.com/4tmUAtlox4Oy)* for notes on the Python bindings for our REST API generated by [swagger-codegen](https://github.com/swagger-api/swagger-codegen). +- It may be cleaner to set the host using the [configuration class](https://github.com/swagger-api/swagger-codegen/blob/master/samples/client/petstore/python/petstore_api/configuration.py). This is also where we can set SSL options. diff --git a/docusaurus/versioned_docs/version-1.2.X/lte/tr069.md b/docusaurus/versioned_docs/version-1.2.X/lte/tr069.md new file mode 100644 index 0000000..753eb59 --- /dev/null +++ b/docusaurus/versioned_docs/version-1.2.X/lte/tr069.md @@ -0,0 +1,72 @@ +--- +id: version-1.2.X-tr069 +title: Adding TR-069 support for an eNodeB +hide_title: true +original_id: tr069 +--- +# Add eNB TR-069 Support +## enodebd Overview + +The enodebd service is responsible for any TR-069 management of eNodeB devices. +As such, you’ll only need to modify enodebd to add support for a new eNB. + +At a high level, enodebd brings up a server, the tr069_server, and when the +tr069_server receives an HTTP request, it translates the contained SOAP message +into the corresponding model representing the message, eg. Inform, +GetParameterRequest, etc. It takes the message, and passes it on to the +StateMachineManager. + +The StateMachineManager, as the name implies, manages different state machines. +One state machine is used for each eNB that the Magma AGW is managing. Using +the IP of the HTTP request, the StateMachineManager routes the request to the +correct state machine (also called ‘Handler’). + +Each EnodebAcsStateMachine contains a representation of the configuration that +we believe the eNB has. It also contains the configuration that we desire to +set on it. These are labeled as the ‘device configuration’ and ‘desired +configuration’. Each state machine will attempt to configure its corresponding +eNB to the desired configuration. + +Configuration through TR-069 is done in the ‘Provisioning Session’. The state +machine has a state for each step of the provisioning session, each with its +own logic for how to process the incoming TR-069 message, and how to construct +the TR-069 response. Most of these states are in +enodebd/state_machines/enb_acs_states.py, since the provisioning session +happens nearly the same way for most devices. There are differences though, +and so there is a different state machine for each supported eNB device model, +which can be found under enodebd/devices. + + +## Adding an eNB +To add TR-069 support, the TR-069 data model is needed for the device, as well +as the hardware model, and software version. A new state machine should be +created under enodebd/devices. + +For the data model, the same parameter will have different paths for different +devices, and may even have its value formatted differently. For these +formatting differences, the ‘transform’ functions should be added to transform +the parameter value from the formatting that the eNB uses, to the common +formatting that Magma enodebd understands, and vice-versa. + +For constructing the desired-configuration of the eNB, there will be +differences between devices. Attach a EnodebConfigurationPostProcessor to the +eNB state machine, and add any logic for modifying the desired-configuration +beyond the defaults that enodebd already does. + +The provisioning session can occur a little different for each eNB. The state +map attached to each state machine lets you customize the state machine for +differences between devices. Some devices require rebooting for parameter +changes to take effect, for example. You can add/remove behavior through this +map, and also add custom states. + +[An example pull request for adding an eNB](https://github.com/facebookincubator/magma/commit/e1d4564f7daa7a4c1be135e8dbffe7a10bfa4e34) + +## Testing +Make sure that the eNB is configured to reach out to +baiomc.cloudapp.net:48080, so that Magma’s DNS hijacking works, and routes +TR-069 messages through iptables to enodebd’s TR-069 server. Debugging can most +easily be done with tcpdump, and then viewing the SOAP messages through +Wireshark. + +Magma's dnsd service configures dnsmasq for DNS hijacking. See: dnsd.yml. You +can modify dnsd.yml and restart the service for further configuration. diff --git a/docusaurus/versioned_docs/version-1.2.X/lte/upgrade.md b/docusaurus/versioned_docs/version-1.2.X/lte/upgrade.md new file mode 100644 index 0000000..5324497 --- /dev/null +++ b/docusaurus/versioned_docs/version-1.2.X/lte/upgrade.md @@ -0,0 +1,43 @@ +--- +id: version-1.2.X-agw_110_upgrade +title: Upgrade to v1.1 +sidebar_label: Upgrade to v1.1 +hide_title: true +original_id: agw_110_upgrade + +--- +# Upgrade to v1.1 + +You can upgrade your access gateways remotely from the NMS or SSH directly +into them and run an `apt-get install`. + +The Access Gateway version needs to be equal to or less than the version + of your Orc8r. We recommend you update your Orc8r first. + +## NMS Autoupgrade + +Navigate to the "Configure" tab of the NMS and select the tab "Upgrade". Find +the tier that your target AGW is a member of (probably `default`), then set +the desired software version for that tier to `1.1.0-1589476391-5dbd6822`. +The AGWs in this tier will pull this configuration and upgrade automatically. +By default, we check for an upgrade every 5 minutes. + +![1.1.0 upgrade](../../../../readmes/assets/agw_110_upgrade.png) + +When the gateway completes its upgrade, you should see that its reported +software version in this tab has changed. If it hasn't changed, something +probably went wrong with the autoupgrade. You will probably have to SSH into +the AGW to troubleshoot the installation (see the next section). + +If you want to roll out an upgrade slowly to your fleet, you can segment your +AGWs into different tiers and upgrade tiers one-by-one. Use the NMS to create +new tiers and assign your AGWs to them. + +## Manual Upgrade + +SSH into your target AGW then: + +```bash +sudo apt-get update +sudo apt-get install magma=1.1.0-1589476391-5dbd6822 +``` diff --git a/docusaurus/versioned_docs/version-1.2.X/lte/upgrade_120.md b/docusaurus/versioned_docs/version-1.2.X/lte/upgrade_120.md index 1319ded..467b3c1 100644 --- a/docusaurus/versioned_docs/version-1.2.X/lte/upgrade_120.md +++ b/docusaurus/versioned_docs/version-1.2.X/lte/upgrade_120.md @@ -24,9 +24,9 @@ tier to `1.2.0-1600052642-41609608`. The AGWs in this tier will pull this configuration and upgrade automatically. By default, we check for an upgrade every 5 minutes. -![1.2.0 upgrade](assets/agw_120_1.png) +![1.2.0 upgrade](../../../../readmes/assets/agw_120_1.png) -![1.2.0 upgrade](assets/agw_120_2.png) +![1.2.0 upgrade](../../../../readmes/assets/agw_120_2.png) When the gateway completes its upgrade, you should see that its reported software version in. If it hasn't changed, something probably went wrong with diff --git a/docusaurus/versioned_docs/version-1.2.X/nms/dashboard.md b/docusaurus/versioned_docs/version-1.2.X/nms/dashboard.md index f4c42c4..367a731 100644 --- a/docusaurus/versioned_docs/version-1.2.X/nms/dashboard.md +++ b/docusaurus/versioned_docs/version-1.2.X/nms/dashboard.md @@ -7,7 +7,7 @@ original_id: nms_dashboard # NMS Main Dashboard ## Network -![lte_dashboard1](assets/nms/userguide/lte_dashboard1.png) +![lte_dashboard1](../../../../readmes/assets/nms/userguide/lte_dashboard1.png) The network tab contains the following components: * Chart displaying frequency of alerts and events over time. The chart and event table data is selected over a default time period of the last 3 days. This time period can be modified through the datetime selector on the top right hand corner of the dashboard. @@ -25,4 +25,4 @@ The network tab contains the following components: * We can filter specific events by searching for either event types or event tags. Examples of event tags include hardware_id of a gateway or imsi of a subscriber. -![imsi_filtering_eventtable](assets/nms/userguide/imsi_filtering_eventtable.png) +![imsi_filtering_eventtable](../../../../readmes/assets/nms/userguide/imsi_filtering_eventtable.png) diff --git a/docusaurus/versioned_docs/version-1.2.X/nms/equipment.md b/docusaurus/versioned_docs/version-1.2.X/nms/equipment.md index 97fb2b5..f94ebf1 100644 --- a/docusaurus/versioned_docs/version-1.2.X/nms/equipment.md +++ b/docusaurus/versioned_docs/version-1.2.X/nms/equipment.md @@ -10,7 +10,7 @@ original_id: nms_equipment ## Gateway Dashboard ### Gateway Overview -![gateway_overview2](assets/nms/userguide/gateway_overview2.png) +![gateway_overview2](../../../../readmes/assets/nms/userguide/equipment/gateway_overview2.png) * Chart to display gateway checkins. Using a time range selector, the gateway checkin chart can be filtered to view the frequency of checkins over the last 3 hours, 6 hours, 12 hours, 24 hours, 7 days, 14 days and 30 days. * Gateway specific KPIs including Max, Min and Average latency of the pings to a specific host(8.8.8.8) and % of healthy gateways. * Gateway overview table with a selector to view either **status** or **upgrade** view of the gateways in the network. @@ -22,7 +22,7 @@ original_id: nms_equipment Each gateway detail page comprises of overview, events, logs, alerts and config sections. Additionally, the gateway detail page has a reboot button at the right top corner of the page. ##### Overview page -![gateway_detail1](assets/nms/userguide/gateway_detail1.png) +![gateway_detail1](../../../../readmes/assets/nms/userguide/equipment/gateway_detail1.png) * Gateway specific information(name, gatewayID, hardwareID, version) * Status(Health, last checkin time, CPU usage %, event aggregation and log aggregation configuration) * Connected eNodeBs. List of eNodeBs connected to the specific gateway @@ -30,13 +30,13 @@ Each gateway detail page comprises of overview, events, logs, alerts and config * Smaller version of Event Table consisting of events which occurred during the last 3 hours. ##### Events -![gateway_detail2](assets/nms/userguide/gateway_detail2.png) +![gateway_detail2](../../../../readmes/assets/nms/userguide/equipment/gateway_detail2.png) * Event chart displays the count of gateway specific events in a bar graph. * Event table displays the time, event type and event description. It comes with a dropdown to provide a detailed event description. Additionally, it has a search button which can be used to filter specific event types. * Event page comes with a datetime selector which can be used to filter event chart and event table within a selected time window. ##### Logs -![gateway_detail3](assets/nms/userguide/gateway_detail3.png) +![gateway_detail3](../../../../readmes/assets/nms/userguide/equipment/gateway_detail3.png) * Log chart displays the count of gateway log events in a bar graph. * Log table displays the date, service, log type and log text. The log table comes with a search bar which can be used to search for arbitrary text within the logs. Regular expressions can also be used. For example, *001010000000001 can be used to filter all logs for a particular IMSI. * Log page comes with a datetime selector which can be used to filter log chart and log table within a selected time window. @@ -47,21 +47,21 @@ Each gateway detail page comprises of overview, events, logs, alerts and config * This page displays alerts tabbed by Critical, Major, Minor and Misc alerts filtered for that specific gateway. ##### Config page -![gateway_detail4](assets/nms/userguide/gateway_detail4.png) +![gateway_detail4](../../../../readmes/assets/nms/userguide/equipment/gateway_detail4.png) * Gateway section for viewing and editing information fields such as Name, Hardware ID, Description and Version * EPC section * Ran section * Aggregation section for enabling and disabling log aggregation and event aggregation for a specific gateway #### Upgrade Tiers Dialog -![upgrade_tiers1](assets/nms/userguide/upgrade_tiers1.png) +![upgrade_tiers1](../../../../readmes/assets/nms/userguide/equipment/upgrade_tiers1.png) * This dialog displays the tier table and supported versions (i.e. versions from a stable channel) * Tier table lists all the available tiers within the network and the versions they are associated with. The version field can be edited to select one of the supported versions. Any arbitrary version can be provided as well. ## eNodeB Dashboard ### eNodeB overview -![enodeb_overview1](assets/nms/userguide/enodeb_overview1.png) +![enodeb_overview1](../../../../readmes/assets/nms/userguide/equipment/enodeb_overview1.png) Chart to display the total throughput of all eNodeBs. It comes along with a datetime selector to filter the chart within a specific time window. * eNodeB overview table lists all the eNodeBs in the network. Table columns includes Name, Serial, Session state name, Health and Last reported time. Clicking individual eNodeB serial links opens the eNodeB detail page for the selected eNodeB. Each table row has an action menu to view, edit and remove the eNodeB. * Button to **add a new eNodeB** @@ -69,13 +69,13 @@ Chart to display the total throughput of all eNodeBs. It comes along with a date ### eNodeB detail eNodeB detail comprises of the following sections #### Overview page -![enodeb_detail1](assets/nms/userguide/enodeb_detail1.png) +![enodeb_detail1](../../../../readmes/assets/nms/userguide/equipment/enodeb_detail1.png) * Information (eNodeB name, serial) * Status KPIs including (Health, Gateway ID, Transmit Enabled and MME connected) * Throughput chart for the selected eNodeB - it comes with a date time selector to filter the chart within a specific time window. #### Config page -![enodeb_detail2](assets/nms/userguide/enodeb_detail2.png) +![enodeb_detail2](../../../../readmes/assets/nms/userguide/equipment/enodeb_detail2.png) * Information (eNodeB name, serial and description of eNodeB) * RAN section @@ -103,55 +103,55 @@ The same gateway configuration dialog is used for 'add' as well as 'edit'. The d ### Adding a new gateway As shown below, the Gateway add button is available on the Gateway Overview page. -![gateway_add_button](assets/nms/userguide/gateway_add_button.png) +![gateway_add_button](../../../../readmes/assets/nms/userguide/equipment/gateway_add_button.png) As the user clicks **save and continue** and proceeds to the next tab, the gateway configuration will be persisted. The user can either choose to configure all paramters at once or skip and configure them at a later point of time by editing the configuration from the gateway detail section. -![gateway_config1](assets/nms/userguide/gateway_config1.png) +![gateway_config1](../../../../readmes/assets/nms/userguide/equipment/gateway_config1.png) -![gateway_config2](assets/nms/userguide/gateway_config2.png) +![gateway_config2](../../../../readmes/assets/nms/userguide/equipment/gateway_config2.png) -![gateway_config3](assets/nms/userguide/gateway_config3.png) +![gateway_config3](../../../../readmes/assets/nms/userguide/equipment/gateway_config3.png) -![gateway_config4](assets/nms/userguide/gateway_config4.png) +![gateway_config4](../../../../readmes/assets/nms/userguide/equipment/gateway_config4.png) Once the gateway has been added, it will appear in the gateway table shown below. -![gateway_config5](assets/nms/userguide/gateway_config5.png) +![gateway_config5](../../../../readmes/assets/nms/userguide/equipment/gateway_config5.png) ### Editing an existing Gateway The Gateway can be edited from the gateway detail page as shown below. -![gateway_config6](assets/nms/userguide/gateway_config6.png) +![gateway_config6](../../../../readmes/assets/nms/userguide/equipment/gateway_config6.png) -![gateway_config7](assets/nms/userguide/gateway_config7.png) +![gateway_config7](../../../../readmes/assets/nms/userguide/equipment/gateway_config7.png) Once the user clicks 'save', the gateway detail section will be updated as shown below. -![gateway_config8](assets/nms/userguide/gateway_config8.png) +![gateway_config8](../../../../readmes/assets/nms/userguide/equipment/gateway_config8.png) ### Upgrading an existing gateway Each gateway is associated with a specific tier. This information is available through the upgrade view of the gateway page. The gateway tier can be edited as shown below. -![gateway_tier_edit](assets/nms/userguide/gateway_tier_edit.png) +![gateway_tier_edit](../../../../readmes/assets/nms/userguide/equipment/gateway_tier_edit.png) The versions associated with tier can be edited from the tier dialog as follows and saved by clicking the save button. -![upgrade_tiers_dialog](assets/nms/userguide/upgrade_tiers_dialog.png) +![upgrade_tiers_dialog](../../../../readmes/assets/nms/userguide/equipment/upgrade_tiers_dialog.png) -![upgrade_tiers](assets/nms/userguide/upgrade_tiers.png) +![upgrade_tiers](../../../../readmes/assets/nms/userguide/equipment/upgrade_tiers.png) As shown below, stable versions can be viewed by clicking the "supported versions" tab on the upgrade tiers dialog. -![supported_versions](assets/nms/userguide/supported_versions.png) +![supported_versions](../../../../readmes/assets/nms/userguide/equipment/supported_versions.png) ### Deleting a gateway A gateway can be deleted from the overview page as shown below: -![gateway_deletion1](assets/nms/userguide/gateway_deletion1.png) +![gateway_deletion1](../../../../readmes/assets/nms/userguide/equipment/gateway_deletion1.png) -![gateway_deletion2](assets/nms/userguide/gateway_deletion2.png) +![gateway_deletion2](../../../../readmes/assets/nms/userguide/equipment/gateway_deletion2.png) ## eNodeB Configuration @@ -168,20 +168,20 @@ The same eNodeB configuration dialog is used for 'add' as well as 'edit'. The di ### Adding a new eNodeB eNodeB add button is available on the eNodeB overview page similar to the gateway overview page shown above. -![enodeb_config1](assets/nms/userguide/enode_config1.png) -![enodeb_config2](assets/nms/userguide/enode_config2.png) +![enodeb_config1](../../../../readmes/assets/nms/userguide/equipment/enode_config1.png) +![enodeb_config2](../../../../readmes/assets/nms/userguide/equipment/enode_config2.png) Once the eNodeB is added, it will show up in the eNodeB overview table. ### Editing an existing eNodeB An existing eNodeB can be deleted as follows: -![enodeb_config3](assets/nms/userguide/enode_config3.png) +![enodeb_config3](../../../../readmes/assets/nms/userguide/equipment/enode_config3.png) -![enodeb_config4](assets/nms/userguide/enode_config4.png) +![enodeb_config4](../../../../readmes/assets/nms/userguide/equipment/enode_config4.png) -![enodeb_config5](assets/nms/userguide/enode_config5.png) +![enodeb_config5](../../../../readmes/assets/nms/userguide/equipment/enode_config5.png) ### Deleting an eNodeB Deleting an eNodeB will issue a warning. If the user chooses to override the warning, the eNodeB will be deleted. -![enodeb_config6](assets/nms/userguide/enode_config6.png) -![enodeb_config7](assets/nms/userguide/enode_config7.png) +![enodeb_config6](../../../../readmes/assets/nms/userguide/equipment/enode_config6.png) +![enodeb_config7](../../../../readmes/assets/nms/userguide/equipment/enode_config7.png) diff --git a/docusaurus/versioned_docs/version-1.2.X/nms/network.md b/docusaurus/versioned_docs/version-1.2.X/nms/network.md index 7c796dc..47ab371 100644 --- a/docusaurus/versioned_docs/version-1.2.X/nms/network.md +++ b/docusaurus/versioned_docs/version-1.2.X/nms/network.md @@ -6,7 +6,7 @@ original_id: nms_network --- # Network dashboard -![network_dashboard](assets/nms/userguide/network_dashboard.png) +![network_dashboard](../../../../readmes/assets/nms/userguide/network_dashboard.png) The network dashboard contains the following sections: * KPI grid displaying number of [eNodeBs, Gateways, Subscribers, Policies, APNs] * Information section to view/edit attributes such as name and description. @@ -28,20 +28,20 @@ The same network configuration dialog is used for add as well as edit. The dialo ## Adding a new LTE network A new network can be added by clicking on the button as shown below -![add_new_network](assets/nms/userguide/add_new_network.png) +![add_new_network](../../../../readmes/assets/nms/userguide/add_new_network.png) Add dialog is shown below. -![network_config1](assets/nms/userguide/network_config1.png) -![network_config2](assets/nms/userguide/network_config2.png) -![network_config3](assets/nms/userguide/network_config3.png) +![network_config1](../../../../readmes/assets/nms/userguide/network_config1.png) +![network_config2](../../../../readmes/assets/nms/userguide/network_config2.png) +![network_config3](../../../../readmes/assets/nms/userguide/network_config3.png) Once the new network has been added. It will show up in the network selector as shown below: -![network_selector_network](assets/nms/userguide/network_selector_network.png) +![network_selector_network](../../../../readmes/assets/nms/userguide/network_selector_network.png) ## Editing network configuration The network configuration can be edited by clicking on the edit button in the network overview page and editing as follows: -![network_config5](assets/nms/userguide/network_config5.png) +![network_config5](../../../../readmes/assets/nms/userguide/network_config5.png) diff --git a/docusaurus/versioned_docs/version-1.2.X/nms/organizations.md b/docusaurus/versioned_docs/version-1.2.X/nms/organizations.md index 9517afc..dbb52bd 100644 --- a/docusaurus/versioned_docs/version-1.2.X/nms/organizations.md +++ b/docusaurus/versioned_docs/version-1.2.X/nms/organizations.md @@ -56,18 +56,18 @@ Create one organization and give it access to all networks. This is essentially the same as v1.0 when there was no tenancy support. The only difference is that the NMS is accessible from the URL `magma-test.nms.yourdomain.com` -![Org with access to all networks](assets/nms/org_all_networks.png) +![Org with access to all networks](../../../../readmes/assets/nms/org_all_networks.png) ### Multiple Tenants Create a second organization and give it access to specific networks -![List of organizations](assets/nms/org_multiple_list.png) +![List of organizations](../../../../readmes/assets/nms/org_multiple_list.png) Here, `fb-test` has access to all networks, while `magma-test` only has access to the network `mpk_test`. Create a user in this organization to use it -![Add user to org](assets/nms/org_add_user.png) +![Add user to org](../../../../readmes/assets/nms/org_add_user.png) When you log in to `magma-test.nms.yourdomain.com` you will only be able to see the network `mpk_test`. If you log into `fb-test.nms.yourdomain.com`, you will diff --git a/docusaurus/versioned_docs/version-1.2.X/nms/overview.md b/docusaurus/versioned_docs/version-1.2.X/nms/overview.md index 8da6c3b..febe447 100644 --- a/docusaurus/versioned_docs/version-1.2.X/nms/overview.md +++ b/docusaurus/versioned_docs/version-1.2.X/nms/overview.md @@ -25,4 +25,4 @@ It also aims to simplify operating magma networks by providing: ## Navigation NMS provides an app sidebar with contextual icons to navigate to the main sections of the NMS. -![app_sidebar](assets/nms/userguide/app_sidebar.png) +![app_sidebar](../../../../readmes/assets/nms/userguide/app_sidebar.png) diff --git a/docusaurus/versioned_docs/version-1.2.X/nms/subscriber.md b/docusaurus/versioned_docs/version-1.2.X/nms/subscriber.md index 3725138..2f6bc76 100644 --- a/docusaurus/versioned_docs/version-1.2.X/nms/subscriber.md +++ b/docusaurus/versioned_docs/version-1.2.X/nms/subscriber.md @@ -8,31 +8,31 @@ original_id: nms_subscriber # Subscriber Dashboard ## Subscriber Overview -![subscriber_overview1](assets/nms/userguide/subscriber_overview1.png) +![subscriber_overview1](../../../../readmes/assets/nms/userguide/subscriber_overview1.png) The Subscriber Overview page contains a table listing all subscribers in the network. Columns include Name, IMSI, Service configuration(ACTIVE/INACTIVE), Current data usage, Average data usage and Last reported time(displayed if subscriber monitoring is enabled). The table contains an action menu to view, edit or delete an individual subscriber. ## Subscriber Detail Each Subscriber Detail page comprises of Overview, Events and Config sections. ### Overview -![subscriber_detail1](assets/nms/userguide/subscriber_detail1.png) +![subscriber_detail1](../../../../readmes/assets/nms/userguide/subscriber_detail1.png) * Information section displays Name and IMSI of the subscriber * Status KPIs display GatewayID, UE latency (if available), connection status (TBD) and eNodeB Serial (TBD) * Chart displays the upload and download data usage for the subscriber in stacked histograms. The chart shows the upload and download bytes used by the subscriber within the specified interval. The interval is chosen based on the time window selected by the user. The default time window is 3 hours. For a 3-hour window, data usage over a 15 minute interval is displayed as indicated below. -* ![stacked_barchart](assets/nms/userguide/stacked_barchart.png) +* ![stacked_barchart](../../../../readmes/assets/nms/userguide/stacked_barchart.png) * Data usage KPIs to show the data used by the subscriber in the last 1 hour, 1 day, 1 week and 1 month time range. * Event table displays the subscriber specific events in the last 3 hours. ### Events -![subscriber_detail2](assets/nms/userguide/subscriber_detail2.png) +![subscriber_detail2](../../../../readmes/assets/nms/userguide/subscriber_detail2.png) * Event chart displays the frequency of subscriber specific events in a histogram. * Event table displays the time, event type and event description. Detailed event description can be viewed by clicking the dropdown on the left. It comes with a search capability to filter events based on type. For example, the user can filter events based on session_creation event -![event_table_session_filtering](assets/nms/userguide/event_table_session_filtering.png) +![event_table_session_filtering](../../../../readmes/assets/nms/userguide/event_table_session_filtering.png) * Event page comes with a datetime selector which can be used to filter event chart and event table within a selected time window. ### Config contains -![subscriber_detail3](assets/nms/userguide/subscriber_detail3.png) +![subscriber_detail3](../../../../readmes/assets/nms/userguide/subscriber_detail3.png) Subscriber section to view/edit LTE service state, Data plan, Auth Key and Auth OPC and Active APN associated with the subscriber. # Subscriber Configuration @@ -41,7 +41,7 @@ entering the details manually or uploading them through a subscriber csv file. ## Adding new subscriber Clicking on the 'Add subscriber' button in the subscriber overview page opens the bulk subscriber configuration page. -![add_subscriber_button](assets/nms/userguide/add_subscriber_button.png) +![add_subscriber_button](../../../../readmes/assets/nms/userguide/add_subscriber_button.png) The bulk provisioning page opens up to an empty table. Rows can be added by clicking on the 'add row' button on the right. Each row contains columns including Subscriber Name, IMSI, Auth Key, Auth OPC, Service state, Data Plan, Active APN. @@ -49,26 +49,26 @@ auth key and auth_opc should be specified as hex. The service state can be eithe and active APN can be chosen based on what is available. For example, -John, IMSI001010000000079,,,ACTIVE,default,oai_ipv4 +John, IMSI001010000000079,,,ACTIVE,default,oai_ipv4 ### Provisioning -![subscriber_config1](assets/nms/userguide/subscriber_config1.png) +![subscriber_config1](../../../../readmes/assets/nms/userguide/subscriber_config1.png) -![subscriber_config2](assets/nms/userguide/subscriber_config2.png) +![subscriber_config2](../../../../readmes/assets/nms/userguide/subscriber_config2.png) ### Uploading a subscriber csv file -![subscriber_config3](assets/nms/userguide/subscriber_config3.png) +![subscriber_config3](../../../../readmes/assets/nms/userguide/subscriber_config3.png) -![subscriber_config4](assets/nms/userguide/subscriber_config4.png) +![subscriber_config4](../../../../readmes/assets/nms/userguide/subscriber_config4.png) ## Editing subscriber Subscriber information can be edited from the subscriber detail page. -![subscriber_config5](assets/nms/userguide/subscriber_config5.png) +![subscriber_config5](../../../../readmes/assets/nms/userguide/subscriber_config5.png) ## Deleting subscriber Subscriber can be deleted from the subscriber overview page as follows. -![subscriber_deletion1](assets/nms/userguide/subscriber_deletion1.png) +![subscriber_deletion1](../../../../readmes/assets/nms/userguide/subscriber_deletion1.png) -![subscriber_deletion1](assets/nms/userguide/subscriber_deletion2.png) +![subscriber_deletion1](../../../../readmes/assets/nms/userguide/subscriber_deletion2.png) diff --git a/docusaurus/versioned_docs/version-1.2.X/nms/traffic.md b/docusaurus/versioned_docs/version-1.2.X/nms/traffic.md index a880ef8..82e5452 100644 --- a/docusaurus/versioned_docs/version-1.2.X/nms/traffic.md +++ b/docusaurus/versioned_docs/version-1.2.X/nms/traffic.md @@ -9,37 +9,37 @@ original_id: nms_traffic ## Policy dashboard ### Policy Overview Table -![policy_dashboard](assets/nms/userguide/policy_dashboard.png) +![policy_dashboard](../../../../readmes/assets/nms/userguide/policy_overview.png) This table contains all the policies configured in the network. Columns include PolicyID, Flows, Priority, Number of subscribers, Monitoring key, Rating, Tracking type. Each row comes with an action menu to view, edit and delete the policy. ## APN dashboard ### APN Overview Table -![apn_dashboard](assets/nms/userguide/apn_dashboard.png) +![apn_dashboard](../../../../readmes/assets/nms/userguide/apn_overview.png) This table contains all the APNs configured in the network. Columns include ApnID, Description, Qos Profile, Added Date. Each row comes with an action menu to view, edit and delete the APN. # Traffic configuration ## Policy Configuration Currently, limited support is provided for configuring policies and APNs. Users can directly edit the JSON file and save the configuration. -![policy_config1](assets/nms/userguide/policy_config1.png) -![policy_config2](assets/nms/userguide/policy_config2.png) +![policy_config1](../../../../readmes/assets/nms/userguide/policy_configuration_1.png) +![policy_config2](../../../../readmes/assets/nms/userguide/policy_configuration_2.png) ### Deleting a policy Policies can be deleted from the policy overview page as follows: -![policy_deletion1](assets/nms/userguide/policy_deletion1.png) +![policy_deletion1](../../../../readmes/assets/nms/userguide/policy_remove_0.png) -![policy_deletion2](assets/nms/userguide/policy_deletion2.png) +![policy_deletion2](../../../../readmes/assets/nms/userguide/policy_remove_1.png) ## APN configuration -![apn_config1](assets/nms/userguide/apn_config1.png) -![apn_config2](assets/nms/userguide/apn_config2.png) +![apn_config1](../../../../readmes/assets/nms/userguide/apn_configuration.png) +![apn_config2](../../../../readmes/assets/nms/userguide/apn_configuration.png) ### Deleting an APN APN can be deleted from the APN overview page as follows: -![apn_deletion1](assets/nms/userguide/apn_deletion1.png) +![apn_deletion1](../../../../readmes/assets/nms/userguide/apn_remove_0.png) -![apn_deletion2](assets/nms/userguide/apn_deletion2.png) +![apn_deletion2](../../../../readmes/assets/nms/userguide/apn_remove_1.png) diff --git a/docusaurus/versioned_docs/version-1.2.X/nms/troubleshooting.md b/docusaurus/versioned_docs/version-1.2.X/nms/troubleshooting.md index dce71b3..f2d22c4 100644 --- a/docusaurus/versioned_docs/version-1.2.X/nms/troubleshooting.md +++ b/docusaurus/versioned_docs/version-1.2.X/nms/troubleshooting.md @@ -8,22 +8,22 @@ original_id: nms_how_to_guide 1. How to find all subscribers connected to a particular gateway ? Gateway detail screen displays the eNodeBs and subscribers connected to a particular gateway. -![gateway_detail1](assets/nms/userguide/gateway_detail1.png) +![gateway_detail1](../../../../readmes//assets/nms/userguide/equipment/gateway_detail1.png) 2. How to get list of recent events in a particular gateway -![event_debugging](assets/nms/userguide/event_debugging.png) +![event_debugging](../../../../readmes/assets/nms/userguide/event_debugging.png) 3. How to find all logs associated with a particular subscriber and export them ? -![log_viewer](assets/nms/userguide/log_viewer_out.gif) +![log_viewer](../../../../readmes/assets/nms/userguide/log_viewer_out.gif) 4. How to add configuration through JSON editor directly? Following screenshots display step by step way to enable_static_ip_assignments through JSON editor -![json_editing1](assets/nms/userguide/json_editing1.png) -![json_editing2](assets/nms/userguide/json_editing2.png) -![json_editing3](assets/nms/userguide/json_editing3.png) -![json_editing4](assets/nms/userguide/json_editing4.png) -![json_editing5](assets/nms/userguide/json_editing5.png) -![json_editing6](assets/nms/userguide/json_editing6.png) -![json_editing7](assets/nms/userguide/json_editing7.png) -![json_editing8](assets/nms/userguide/json_editing8.png) +![json_editing1](../../../../readmes/assets/nms/userguide/json_editing1.png) +![json_editing2](../../../../readmes/assets/nms/userguide/json_editing2.png) +![json_editing3](../../../../readmes/assets/nms/userguide/json_editing3.png) +![json_editing4](../../../../readmes/assets/nms/userguide/json_editing4.png) +![json_editing5](../../../../readmes/assets/nms/userguide/json_editing5.png) +![json_editing6](../../../../readmes/assets/nms/userguide/json_editing6.png) +![json_editing7](../../../../readmes/assets/nms/userguide/json_editing7.png) +![json_editing8](../../../../readmes/assets/nms/userguide/json_editing8.png) diff --git a/docusaurus/versioned_docs/version-1.2.X/orc8r/ue_metering.md b/docusaurus/versioned_docs/version-1.2.X/orc8r/ue_metering.md index aae47dc..30c8ddc 100644 --- a/docusaurus/versioned_docs/version-1.2.X/orc8r/ue_metering.md +++ b/docusaurus/versioned_docs/version-1.2.X/orc8r/ue_metering.md @@ -20,7 +20,7 @@ This feature is currently built to enable post-pay charging. Metering information is available through our metrics REST endpoint. The metric name used is `ue_traffic`. -![Swagger REST API Endpoint](assets/ue_metering.png) +![Swagger REST API Endpoint](../../../../readmes/assets/ue_metering.png) ### Configuring Metering diff --git a/docusaurus/versioned_docs/version-1.2.X/proposals/p002_scaled_prometheus_pipeline.md b/docusaurus/versioned_docs/version-1.2.X/proposals/p002_scaled_prometheus_pipeline.md index b703af7..1e5184a 100644 --- a/docusaurus/versioned_docs/version-1.2.X/proposals/p002_scaled_prometheus_pipeline.md +++ b/docusaurus/versioned_docs/version-1.2.X/proposals/p002_scaled_prometheus_pipeline.md @@ -54,7 +54,7 @@ Time to load grafana dashboard on prod NMS: **>15s **from click until all graphs ### Thanos Thanos is a very popular project which allows for easy and customizable scaling of prometheus monitoring pipelines. From the start, I believe this will be the easiest and most powerful solution to the problem. Thanos consists of several components, all of which can be used independently. The most relevant to us is the `Querier` which allows for the querying of data across multiple prometheus servers. A simple architecture diagram from Thanos shows how this works in a typical deployment: -![image.png](assets/proposals/p002_scaled_prometheus_pipeline/image.png)Here we see multiple prometheus servers with the Thanos `sidecar` attached. This allows for the rest of the thanos components to work together. Then, the `Querier` components are able to accept PromQL queries and retrieve data from any set of the prometheus servers. +![image.png](../../../../readmes/assets/proposals/p002_scaled_prometheus_pipeline/image.png)Here we see multiple prometheus servers with the Thanos `sidecar` attached. This allows for the rest of the thanos components to work together. Then, the `Querier` components are able to accept PromQL queries and retrieve data from any set of the prometheus servers. With this setup, we only need to deploy the Thanos `sidecar` and multiple `Querier` components, along with Object storage to achieve faster queries. @@ -71,11 +71,11 @@ In this solution, the flow of metrics is not changed until it gets to the promet Current metrics pipeline diagram: -![currentMetricsPipeline.png](assets/proposals/p002_scaled_prometheus_pipeline/currentMetricsPipeline.png) +![currentMetricsPipeline.png](../../../../readmes/assets/proposals/p002_scaled_prometheus_pipeline/currentMetricsPipeline.png) Proposed pipeline: -![newMetricsPipeline.png](assets/proposals/p002_scaled_prometheus_pipeline/proposedMetricsPipeline.png) +![newMetricsPipeline.png](../../../../readmes/assets/proposals/p002_scaled_prometheus_pipeline/proposedMetricsPipeline.png) ### Improving query times with Object Storage diff --git a/docusaurus/versioned_docs/version-1.3.X/basics/introduction.md b/docusaurus/versioned_docs/version-1.3.X/basics/introduction.md new file mode 100644 index 0000000..9ae26ff --- /dev/null +++ b/docusaurus/versioned_docs/version-1.3.X/basics/introduction.md @@ -0,0 +1,28 @@ +--- +id: version-1.3.X-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](../../../../readmes/assets/magma_overview.png?raw=true "Magma Architecture") diff --git a/docusaurus/versioned_docs/version-1.3.X/basics/prerequisites.md b/docusaurus/versioned_docs/version-1.3.X/basics/prerequisites.md new file mode 100644 index 0000000..191c8c4 --- /dev/null +++ b/docusaurus/versioned_docs/version-1.3.X/basics/prerequisites.md @@ -0,0 +1,112 @@ +--- +id: version-1.3.X-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. + +## Development Tools + +Install the following tools: + +1. [Docker](https://www.docker.com) and Docker Compose +2. [Homebrew](https://brew.sh/) *only* for MacOS users +3. [VirtualBox](https://www.virtualbox.org/) +3. [Vagrant](https://vagrantup.com) + +Replace `brew` with your OS-appropriate package manager as necessary, or see +the [pyenv installation instructions](https://github.com/pyenv/pyenv#installation). + +```bash +brew install pyenv + +# Replace .zshrc with your appropriate shell RC file +# IMPORTANT: Use .bash_profile, not .bashrc for bash +echo -e 'if command -v pyenv 1>/dev/null 2>&1; then\n eval "$(pyenv init -)"\nfi' >> ~/.zshrc +exec $SHELL +pyenv install 3.7.3 +pyenv global 3.7.3 + +pip3 install ansible fabric3 jsonpickle requests PyYAML +vagrant plugin install vagrant-vbguest +``` + +If you are on MacOS, you should start Docker for Mac and increase the memory +allocation for the Docker engine to at least 4GB (Preferences -> Advanced). + +![Increasing docker engine resources](../../../../readmes/assets/docker-config.png) + +## Build/Deploy Tooling + +We support building the AGW and Orchestrator on MacOS and Linux host operating +systems. Doing so on a Windows environment should be possible but has not been +tested. You may prefer to use a Linux virtual machine if you are on a Windows +host. + +First, follow the previous section on developer tools. Then, install some +additional prerequisite tools (replace `brew` with your OS-appropriate package +manager as necessary): + +```bash +brew install aws-iam-authenticator kubectl helm terraform +python3 -m pip install awscli boto3 +aws configure +``` + +### Orchestrator and NMS + +Orchestrator deployment depends on the following components + +1. AWS account +2. Docker image repository (e.g. Docker Hub, JFrog) +3. Helm chart repository (e.g. JFrog, Github)* +4. Registered domain for Orchestrator endpoints + +\* We describe setting up a private GitHub repository as a Helm repository in +the [building Orchestrator](../orc8r/deploy_build.md) section. + +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 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. 2GB RAM +4. 128GB-256GB 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. diff --git a/docusaurus/versioned_docs/version-1.3.X/basics/quick_start_guide copy.md b/docusaurus/versioned_docs/version-1.3.X/basics/quick_start_guide copy.md new file mode 100644 index 0000000..5af706d --- /dev/null +++ b/docusaurus/versioned_docs/version-1.3.X/basics/quick_start_guide copy.md @@ -0,0 +1,208 @@ +--- +id: version-1.3.X-quick_start_guide +title: Quick Start Guide +hide_title: true +original_id: quick_start_guide +--- +# Quick Start Guide + +The quick start guide is for developing on Magma or just trying it out. Follow +the deployment guides under Orchestrator and Access Gateway if you are +installing Magma for a production deployment. + +With the [prereqs](prerequisites.md) installed, we can now set up a minimal +end-to-end system on your development environment. In this guide, we'll start +by running the LTE access gateway and orchestrator cloud, and then +register your local access gateway with your local cloud for management. + +We will be spinning up a virtual machine and some docker containers for this +full setup, so you'll probably want to do this on a system with at least 8GB +of memory. Our development VM's are in the 192.168.60.0/24, 192.168.128.0/24 and +192.168.129.0/24 address spaces, so make sure that you don't have anything +running which hijacks those (e.g. VPN). + +In the following steps, note the prefix in terminal commands. `HOST` means to +run the indicated command on your host machine, and `MAGMA-VM` on the `magma` +vagrant machine under `lte/gateway`. + +## Provisioning the environment + +Go ahead and open up 2 fresh terminal tabs. Start in + +### Terminal Tab 1: Provision the AGW VM + +The development environment virtualizes the access gateway so you don't need +any production hardware on hand to test an end-to-end setup. +We'll be setting up the LTE AGW VM in this tab. + +```bash +HOST [magma]$ cd lte/gateway +HOST [magma/lte/gateway]$ vagrant up magma +``` + +This will take a few minutes to spin up the VM. While that runs, switch over +to... + +**Note**: If you are looking to test/develop the LTE features of AGW, without +cloud based network management, you can skip the rest of this guide and try the +[S1AP integration tests](../lte/s1ap_tests.md) now. + +### Terminal Tab 2: Build Orchestrator + +Here, we'll be building the Orchestrator docker containers. + +```bash +HOST [magma]$ cd orc8r/cloud/docker +HOST [magma/orc8r/cloud/docker]$ ./build.py -a +``` + +This will build all the docker images for Orchestrator. The `vagrant up` from +the first tab should finish before the image building, so you should switch +to that tab and move on for now. + +## Initial Run + +Once `vagrant up` in the first tab finishes: + +### Terminal Tab 1: Build AGW from Source + +We will kick off the initial build of the AGW from source here. + +```bash +HOST [magma/lte/gateway]$ vagrant ssh magma +MAGMA-VM [/home/vagrant]$ cd magma/lte/gateway +MAGMA-VM [/home/vagrant/magma/lte/gateway]$ make run +``` + +This will take a while (we have a lot of CXX files to build). With 2 extensive +build jobs running, now is a good time to grab a coffee or lunch. The first +build ever from source will take a while, but afterwards, a persistent ccache +and Docker's native layer caching will speed up subsequent builds +significantly. + +You can monitor what happens in the other tab now: + +### Terminal Tab 2: Start Orchestrator + +Once the Orchestrator build finishes, we can start the development Orchestrator +cloud for the first time. We'll also use this time to register the local +client certificate you'll need to access the local API gateway for your +development stack. + +To start Orchestrator (without metrics) is as simple as: + +```bash +HOST [magma/orc8r/cloud/docker]$ ./run.sh + +Creating orc8r_postgres_1 ... done +Creating orc8r_test_1 ... done +Creating orc8r_maria_1 ... done +Creating elasticsearch ... done +Creating fluentd ... done +Creating orc8r_kibana_1 ... done +Creating orc8r_proxy_1 ... done +Creating orc8r_controller_1 ... done +``` + +If you want to run everything, including metrics, run: + +```bash +HOST [magma/orc8r/cloud/docker]$ ./run.sh -all + +Creating orc8r_alertmanager_1 ... done +Creating orc8r_maria_1 ... done +Creating elasticsearch ... done +Creating orc8r_postgres_1 ... done +Creating orc8r_grafana_1 ... done +Creating orc8r_config-manager_1 ... done +Creating orc8r_test_1 ... done +Creating orc8r_prometheus-cache_1 ... done +Creating orc8r_prometheus_1 ... done +Creating orc8r_kibana_1 ... done +Creating fluentd ... done +Creating orc8r_proxy_1 ... done +Creating orc8r_controller_1 ... done +``` + +The Orchestrator application containers will bootstrap certificates on startup +which are cached for future runs. Watch the directory `magma/.cache/test_certs` +for a file `admin_operator.pfx` to show up (this may take a minute or 2), then: + +```bash +HOST [magma/orc8r/cloud/docker]$ ls ../../../.cache/test_certs + +admin_operator.key.pem bootstrapper.key controller.crt rootCA.key +admin_operator.pem certifier.key controller.csr rootCA.pem +admin_operator.pfx certifier.pem controller.key rootCA.srl + +HOST [magma/orc8r/cloud/docker]$ open ../../../.cache/test_certs +``` + +In the Finder window that pops up, double-click `admin_operator.pfx` to add the +local client cert to your keychain. *The password for the cert is magma*. +In some cases, you may have to open up the Keychain app in MacOS and drag-drop +the file into the login keychain if double-clicking doesn't work. + +If you use Firefox, you'll have to import this .pfx file into your browser's +installed client certificates. See [here](https://support.globalsign.com/customer/en/portal/articles/1211486-install-client-digital-certificate---firefox-for-windows) +for instructions. If you use Chrome or Safari, you may have to restart the +browser before the certificate can be used. + +### Connecting Your Local LTE Gateway to Your Local Cloud + +At this point, you will have built all the code in the LTE access gateway and +the Orchestrator cloud. All the services on the LTE access gateway and +orchestrator cloud are running, but your gateway VM isn't yet set up to +communicate with your local cloud. + +We have a fabric command set up to do this: + +```bash +HOST [magma]$ cd lte/gateway +HOST [magma/lte/gateway]$ fab -f dev_tools.py register_vm +``` + +This command will seed your gateway and network on Orchestrator with some +default LTE configuration values and set your gateway VM up to talk to your +local Orchestrator cloud. Wait a minute or 2 for the changes to propagate, +then you can verify that things are working: + +```bash +HOST [magma/lte/gateway]$ vagrant ssh magma + +MAGMA-VM$ sudo service magma@* stop +MAGMA-VM$ sudo service magma@magmad restart +MAGMA-VM$ sudo tail -f /var/log/syslog + +# After a minute or 2 you should see these messages: +Sep 27 22:57:35 magma-dev magmad[6226]: [2018-09-27 22:57:35,550 INFO root] Checkin Successful! +Sep 27 22:57:55 magma-dev magmad[6226]: [2018-09-27 22:57:55,684 INFO root] Processing config update g1 +Sep 27 22:57:55 magma-dev control_proxy[6418]: 2018-09-27T22:57:55.683Z [127.0.0.1 -> streamer-controller.magma.test,8443] "POST /magma.Streamer/GetUpdates HTTP/2" 200 7bytes 0.009s +``` + +## Using the NMS UI + +Magma provides an UI for configuring and monitoring the networks. To set up +the NMS to talk to your local Orchestrator: + +```bash +HOST [magma]$ cd symphony/app/packages/magmalte +HOST [magma/symphony/app/packages/magmalte] $ docker-compose build magmalte +HOST [magma/symphony/app/packages/magmalte] $ docker-compose up -d +HOST [magma/symphony/app/packages/magmalte] $ ./scripts/dev_setup.sh +``` + +After this, you will be able to access the UI by visiting +[https://magma-test.localhost](https://magma-test.localhost), and using the email `admin@magma.test` +and password `password1234`. We recommend Firefox or Chrome. If you see Gateway Error 502, don't worry, the +NMS can take upto 60 seconds to finish starting up. + +You will probably want to enable this organization (magma-test) to access all networks, +so go to [master.localhost](https://master.localhost) and login with the same credentials. +Once there, you can click on the organization and then select "Enable all networks". + +**Note**: If you want to test the access gateway VM with a physical eNB and UE, +refer to +the [Connecting a physical eNodeb and UE device to gateway +VM](../lte/dev_notes.md#connecting-a-physical-enodeb-and-ue-to-gateway-vm) +section. diff --git a/docusaurus/versioned_docs/version-1.3.X/faq/magma_faq.md b/docusaurus/versioned_docs/version-1.3.X/faq/magma_faq.md new file mode 100644 index 0000000..4f5ebd7 --- /dev/null +++ b/docusaurus/versioned_docs/version-1.3.X/faq/magma_faq.md @@ -0,0 +1,108 @@ +--- +id: version-1.3.X-magma_faq +title: Frequently Asked Questions +hide_title: true +original_id: magma_faq +--- +# Frequently Asked Questions +This section lists some of the commonly asked questions related to Magma operation. + +## Access Gateway +### How can I check the status of eNodeB(s) connected on a particular gateway? + - Run `sudo enodebd_cli.py get_all_status` to check eNodeB(s) status. + - **NOTE:** Output of this command will only show eNodeB(s) configured with TR069 protocol. + +### How can I see different interfaces of gateway? + - Run `sudo ip addr` to see all configured interfaces. + - Commonly, interface `eth0` is used for internet connectivity and `eth1` is used for RAN connectivity. + - You may run `ping google.com -I eth0` to check AGW connectivity with internet. + - Also, you may run `ping -I eth1` to check AGW connectivity with eNodeB. You can get eNodeB IP from `enodeb_cli` as mentioned in above question. + +### How can I see attached subscribers list on a particular gateway and their browsing status? + - Run `sudo mobility_cli.py get_subscriber_table`, to see all attached subscribers. + - Note down the IP obtained by the user from above command, then run `sudo pipelined_cli.py debug display_flows | grep ` for packet flow info of that user. + +### How can I check services running on a gateway and their status? + - **Check all services:** `sudo service magma@* status`. + - **Check specific service:** `sudo service magma@ status`. e.g. `sudo service magma@enodebd status`. + +### How can I collect logs for a particular service? + - Run `sudo journalctl -fu magma@`, e.g. for enodeb service, run `sudo journalctl -fu magma@enodebd`. + +### How can I check the status of the OVS module on a gateway? + - Run `sudo ovs-vsctl show` to check. + +### How can I capture packets for troubleshooting? + - You can use general purpose tcpdump command to capture traffic at any of your interfaces. e.g. run `sudo tcpdump -i eth1 -w /tmp/capture.pcap` to capture packet at eth1 interface. + +### What are the common troubleshooting logs in gateway? + - **syslog:** `/var/log/syslogs`. + - **MME logs:** `/var/log/mme.log`. + - **eNodeB logs:** `/var/log/enodebd.log`. + +### Where can I find the configuration of a gateway? + - File `/var/opt/magma/configs/gateway.mconfig` is the configuration streamed down from Orchestrator. + - Any custom static configs will also be in directory `/var/opt/magma/configs` with a `.yml` extension. + - Default static configs are located at `/etc/magma/configs`. + - systemd unit files are located at `/etc/system/systemd`. + +### How can I restart gateway services? + - There are 2 options to restart gateway services. First from CLI and other from NMS UI. + - To restart services from CLI, login to AGW node, then perform below steps: + - Run `sudo service magma@* stop` to stop services. + - Then, run `sudo service magma@magmad restart` to restart services. + - To restart services from NMS UI, perform below steps: + - Login to NMS UI and go to **Gateways** option from left hand pane menu. + - Then, click on **edit** option against the gateway for which you wish to reboot services. + - From the popup window, select tab **COMMANDS**. Then, check section **Reboot**. + - Click on **Restart Services** to restart all AGW services. + +### How can I reboot the gateway? + - There are 2 options to reboot gateway. First from CLI and other from NMS UI. + - To reboot AGW from CLI, login to AGW node, then run `sudo init 6` to reboot whole AGW node. + - To reboot AGW from NMS UI, perform below steps: + - Login to NMS UI and go to **Gateways** option from left hand pane menu. + - Then, click on **edit** option against the gateway which you wish to reboot. + - From the popup window, select tab **COMMANDS**. Then, check section **Reboot**. + - Click on **Reboot** to reboot the AGW node. + +## Orchestrator +### How can I check production pods in Orchestrator running on Kubernetes? + - **For all pods:** `kubectl -n magma get pods`. + - **Logs of a particular pod:** `kubectl -n magma logs -f `. + - **NOTE:** In above commands, please use the actual namespace after `-n` you have chosen to install orc8r in. + +### How can I test Orchestrator connection with Gateway? + - Login to Gateway, then run `sudo checkin_cli.py`. + +### Where can I find API endpoint? + - If you have followed the [install guide](../orc8r/deploy_install), it'll be at `https://api.youdomain.com/apidocs/v1/` (the trailing slash is important). + - You will need to load the `admin_operator.pfx` certificate into your keychain/browser, otherwise, API access will be blocked. + +### How can I use Swagger UI to trigger API request? + - Open Swagger UI, then got to interested section, e.g. **EnodeBs**. + - Then click on API trigger action button e.g. **GET**, **PUT**, **DELETE** etc. + - Click on **Try it out** button on right hand side. + - Put in the required inputs and click **Execute**. + +## NMS +### What is an NMS (Network Management System)? + - NMS is a simple UI based solution provided to manage, configuring, and monitor the network effectively. You can monitor various network metrics, configure and monitor alerts, subscribers, gateways, eNodeBs etc. + +### How can I check various network metrics over NMS? + - Login to NMS UI, then click **Metrics** on the left hand side menu to check various network metrics available. + +### How can I configure an alert on NMS? + - Login to NMS UI, then click on **Alert** on left hand side menu. Go to tab **Alert Rules** to configure rule for alert. + +### How can I make sure Gateway is properly connected with NMS? + - Login to NMS and select **Gateway** from left hand side menu bar. + - You can see all the Gateways configured in NMS. + - Check for the Green light besides any particular Gateway, if it is green that means it is properly connected. + +### How can I restart eNodeB from NMS? + - Login to NMS UI and go to **Gateways** option from left hand pane menu. + - Then, click on **edit** option against the gateway with which eNodeB is connected. + - From the popup window, select tab **COMMANDS**. Then, check section **Reboot eNodeB**. + - Enter eNodeB serial ID of eNodeB and click on **Reboot** to reboot that particular eNodeB. + - **Note:**Only those eNodeBs can be rebooted in this manner which are configured with TR069 protocol. diff --git a/docusaurus/versioned_docs/version-1.3.X/feg/deploy_build.md b/docusaurus/versioned_docs/version-1.3.X/feg/deploy_build.md new file mode 100644 index 0000000..4e0ce22 --- /dev/null +++ b/docusaurus/versioned_docs/version-1.3.X/feg/deploy_build.md @@ -0,0 +1,24 @@ +--- +id: version-1.3.X-deploy_build +title: Building Federation Gateway +hide_title: true +original_id: deploy_build +--- + +# Building Federation Gateway Components + +Start up your Docker daemon, `cd` to where you've cloned Magma, then: + +```bash +cd magma/feg/gateway/docker +docker-compose build --parallel +``` + +If this is your first time building the FeG, this may take a while. When this +job finishes, upload these images to your image registry: + +```bash +../../../orc8r/tools/docker/publish.sh -r -i gateway_python +../../../orc8r/tools/docker/publish.sh -r -i gateway_go +../../../orc8r/tools/docker/publish.sh -r -i gateway_radius +``` diff --git a/docusaurus/versioned_docs/version-1.3.X/feg/deploy_install.md b/docusaurus/versioned_docs/version-1.3.X/feg/deploy_install.md new file mode 100644 index 0000000..d8510ce --- /dev/null +++ b/docusaurus/versioned_docs/version-1.3.X/feg/deploy_install.md @@ -0,0 +1,160 @@ +--- +id: version-1.3.X-deploy_install +title: Installing Federation Gateway +hide_title: true +original_id: deploy_install +--- +# Installing Federation Gateway + +## Prerequisites + +To install the Federation Gateway, there are three required files that are +deployment-specific. These are described below: + +* `rootCA.pem` - This file should match the `rootCA.pem` of the Orchestrator +that the Federation Gateway will connect to. + +* `control_proxy.yml` - This file is used to configure the `magmad` +and `control_proxy` services to point toward the appropriate Orchestrator. +A sample configuration is provided below. The `bootstrap_address`, +`bootstrap_port`, `controller_address`, and `controller_port` are the +parameters that will likely need to be modified. + +``` +# +# Copyright 2020 The Magma Authors. + +# This source code is licensed under the BSD-style license found in the +# LICENSE file in the root directory of this source tree. + +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +# nghttpx config will be generated here and used +nghttpx_config_location: /var/tmp/nghttpx.conf + +# Location for certs +rootca_cert: /var/opt/magma/certs/rootCA.pem +gateway_cert: /var/opt/magma/certs/gateway.crt +gateway_key: /var/opt/magma/certs/gateway.key + +# Listening port of the proxy for local services. The port would be closed +# for the rest of the world. +local_port: 8443 + +# Cloud address for reaching out to the cloud. +cloud_address: controller.magma.test +cloud_port: 443 + +bootstrap_address: bootstrapper-controller.magma.test +bootstrap_port: 443 + +# Option to use nghttpx for proxying. If disabled, the individual +# services would establish the TLS connections themselves. +proxy_cloud_connections: True + +# Allows http_proxy usage if the environment variable is present +allow_http_proxy: True +``` + +* `.env` - This file provides any deployment specific environment variables used +in the `docker-compose.yml` of the Federation Gateway. A sample configuration +is provided below: + +``` +# Copyright 2020 The Magma Authors. + +# This source code is licensed under the BSD-style license found in the +# LICENSE file in the root directory of this source tree. + +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +COMPOSE_PROJECT_NAME=feg +DOCKER_REGISTRY= +DOCKER_USERNAME= +DOCKER_PASSWORD= +IMAGE_VERSION=latest + +ROOTCA_PATH=/var/opt/magma/certs/rootCA.pem +CONTROL_PROXY_PATH=/etc/magma/control_proxy.yml +SNOWFLAKE_PATH=/etc/snowflake + +CERTS_VOLUME=/var/opt/magma/certs +CONFIGS_VOLUME=/var/opt/magma/configs + +# This section is unnecessary if using host networking +S6A_LOCAL_PORT=3868 +S6A_HOST_PORT=3868 +S6A_NETWORK=sctp + +SWX_LOCAL_PORT=3869 +SWX_HOST_PORT=3869 +SWX_NETWORK=sctp + +GX_LOCAL_PORT=3870 +GX_HOST_PORT=3870 +GX_NETWORK=tcp + +GY_LOCAL_PORT=3871 +GY_HOST_PORT=3871 +GY_NETWORK=tcp +``` + +## Installation + +The installation is done using the `install_gateway.sh` script located at +`magma/orc8r/tools/docker`. To install, copy that file and the three files +described above into a directory on the install host. Then + +```console +INSTALL_HOST [~/]$ sudo ./install_gateway.sh feg +``` + +After this completes, you should see: `Installed successfully!!` + +## Registration + +After installation, the next step is to register the gateway with the Orchestrator. +To do so: + +```console +INSTALL_HOST [~/]$ cd /var/opt/magma/docker +INSTALL_HOST [/var/opt/magma/docker]$ docker-compose exec magmad /usr/local/bin/show_gateway_info.py +``` + +This will output a hardware ID and a challenge key. This information must be +registered with the Orchestrator. At this time, NMS support for FeG +registration is still in-progress. + +To register the FeG, go to the Orchestrator's APIdocs in your browser. +**Note: It is highly encouraged to use V1 of the apidocs** +(i.e. https://controller.url.sample:9443/apidocs/v1/). + +Now, create a Federation Network. This is found at `/feg` under the +**Federation Networks** section. Then register the gateway under the +**Federation Gateway** section at `/feg/{network_id}/gateways` using the +network ID of the Federation Network and the hardware ID and challenge key +from the previous step. + +To verify that the gateway was correctly registered, run: + +```console +INSTALL_HOST [~/]$ cd /var/opt/magma/docker +INSTALL_HOST [/var/opt/magma/docker]$ docker-compose exec magmad /usr/local/bin/checkin_cli.py +``` + +## Upgrades + +The Federation Gateway supports NMS initiated upgrades. These can be triggered +from the NMS under the `Configure` section by updating the FeG's tier to the +appropriate `Software Version`. After triggering the upgrade from the NMS, +magmad on the gateway will pull down the specified docker images, +update any static configuration, and update the docker-compose file to the +appropriate version. diff --git a/docusaurus/versioned_docs/version-1.3.X/feg/deploy_intro.md b/docusaurus/versioned_docs/version-1.3.X/feg/deploy_intro.md new file mode 100644 index 0000000..195d60c --- /dev/null +++ b/docusaurus/versioned_docs/version-1.3.X/feg/deploy_intro.md @@ -0,0 +1,17 @@ +--- +id: version-1.3.X-deploy_intro +title: Introduction +hide_title: true +original_id: deploy_intro +--- +# Deploying Federation Gateway: Introduction + +These pages will walk through the full process of deploying a +Federation Gateway, from building the various containers that you'll need +to installing them on either a Bare-Metal or VM host. This installation guide +targets *production* environments - if you aren't ready for this, the developer +documentation will be up shortly. + +If you want to get a head start on the development setup, you can build the +FeG containers following this guide and use docker-compose at +`magma/feg/gateway/docker` to spin up the local version of the FeG. diff --git a/docusaurus/versioned_docs/version-1.3.X/feg/federated_FWA_setup_guide.md b/docusaurus/versioned_docs/version-1.3.X/feg/federated_FWA_setup_guide.md index 0ae4d71..2a79fe6 100644 --- a/docusaurus/versioned_docs/version-1.3.X/feg/federated_FWA_setup_guide.md +++ b/docusaurus/versioned_docs/version-1.3.X/feg/federated_FWA_setup_guide.md @@ -24,13 +24,13 @@ When configuring an integration with LTE nodes, it is necessary to link these tw In the **Federated LTE** **Network**’s NMS page, the Federation config should be the **Federation** **Network**’s network ID. -![NMS-FederatedLTE-Config.png](assets/feg/NMS-FederatedLTE-Config.png) +![NMS-FederatedLTE-Config.png](../../../../readmes/assets/feg/NMS-FederatedLTE-Config.png) ### Associating Federation network to a FederatedLTE network In order to complete the association, we also need to modify the **Federation Network**‘s federation configuration. -![API-Federation-Network-Config.png](assets/feg/API-Federation-Network-Config.png) +![API-Federation-Network-Config.png](../../../../readmes/assets/feg/API-Federation-Network-Config.png) Ensure that the following field “served_network_ids” has the **Federated LTE** **Network** networkID. @@ -44,7 +44,7 @@ Ensure that the following field “served_network_ids” has the **Federated LTE In **Federated LTE** **Network**’s EPC configuration, ensure both of the relay flags are set to `true`. -![API-LTE-Network-EPC-Config.png](assets/feg/API-LTE-Network-EPC-Config.png) +![API-LTE-Network-EPC-Config.png](../../../../readmes/assets/feg/API-LTE-Network-EPC-Config.png) ``` "gx_gy_relay_enabled": true, "hss_relay_enabled": true, @@ -54,14 +54,14 @@ In **Federated LTE** **Network**’s EPC configuration, ensure both of the relay The NMS page for **Federated LTE Network** has the following policy configuration page. -![NMS-Policy-Config.png](assets/feg/NMS-Policy-Config.png) +![NMS-Policy-Config.png](../../../../readmes/assets/feg/NMS-Policy-Config.png) ### Configuring Omnipresent/Network-Wide Policies Omnipresent rules or Network-Wide polices are policies that do not require a PCRF to install. On Session creation, all network wide policies will be installed for the session along with any other policies configured by the PCRF. In the policy configuration’s edit dialogue, use the **Network Wide** check box to toggle the configuration. -![NMS-Network-Wide-Rules-Config.png](assets/feg/NMS-Network-Wide-Rules-Config.png) +![NMS-Network-Wide-Rules-Config.png](../../../../readmes/assets/feg/NMS-Network-Wide-Rules-Config.png) ## Advanced Configuration Steps @@ -70,7 +70,7 @@ In the policy configuration’s edit dialogue, use the **Network Wide** check bo In order to enable FUA-redirection support, enable the `redirectd` service in the magmad configuration. -![API-LTE-Magmad-Config.png](assets/feg/API-LTE-Magmad-Config.png) +![API-LTE-Magmad-Config.png](../../../../readmes/assets/feg/API-LTE-Magmad-Config.png) ``` "dynamic_services": ["eventd","td-agent-bit","redirectd"] ``` @@ -81,7 +81,7 @@ In order to enable FUA-redirection support, enable the `redirectd` service in th **DisableGx**: For PCRF-less deployments. In this setting, omnipresent policies must be added to the networks’ subscriber_config. If the rules contain a rating group, credit usage will be reported through the Gy interface. -![API-Federation-Network-Config.png](assets/feg/API-Federation-Network-Config.png) +![API-Federation-Network-Config.png](../../../../readmes/assets/feg/API-Federation-Network-Config.png) The relevant configurations for disabling Gx/Gy are: @@ -102,7 +102,7 @@ FEG allows filtering subscribers by PLMN id. If the subscriber does not belong t To enable this feature add a list `plmn_ids` to `s6a` and add a list of PLMN ids. The list can contain 5 digit or 6 digit PLMN ids. If the list is empty or null, s6a will send any IMSI request to HSS. -![API-Federation-Network-Config.png](assets/feg/API-Federation-Network-Config.png) +![API-Federation-Network-Config.png](../../../../readmes/assets/feg/API-Federation-Network-Config.png) ``` "s6a": { @@ -120,7 +120,7 @@ This feature is disabled by default (so any session request from any IMSI will b ### FeG -* Here are the steps to test the FeG <-> Gx/Gy/S6a connections +* Here are the steps to test the FeG < > Gx/Gy/S6a connections * Exec into `session_proxy` container: `docker exec -it session_proxy bash` * Run `/var/opt/magma/bin/gx_client_cli `with the following parameters * --commands=IT diff --git a/docusaurus/versioned_docs/version-1.3.X/howtos/ue_metering.md b/docusaurus/versioned_docs/version-1.3.X/howtos/ue_metering.md new file mode 100644 index 0000000..2bc84e9 --- /dev/null +++ b/docusaurus/versioned_docs/version-1.3.X/howtos/ue_metering.md @@ -0,0 +1,139 @@ +--- +id: version-1.3.X-ue_metering +title: UE Usage Metering +hide_title: true +original_id: ue_metering +--- + +*Last Updated: 07/31/2020* + +# UE Usage Metering + +Magma currently supports basic usage metering. This allows for real-time +monitoring of data usage specified with the following labels: +- `IMSI` +- `session_id` +- `traffic direction` + +This feature is currently built to enable post-pay charging. + +Metering information is available through our metrics REST endpoint. +The metric name used is `ue_traffic`. + +![Swagger REST API Endpoint](../../../../readmes/assets/ue_metering.png) + +### Configuring Metering + +As a pre-requisite, ensure you have the following: + +* a functional orc8r +* a configured LTE network +* a configured LTE gateway with eNodeB +* subscribers that can attach to your LTE gateway +* network running in un-federated mode + +In un-federated mode, the `policydb` service on the LTE gateway acts +as a lightweight PCRF, and federated support for metering is not currently +supported. + +To enable metering for a single subscriber, +the following steps need to be completed: + +1. A rating group configured with infinite, metered credit +2. A policy rule configured with the above rating group +3. Your policy rule assigned to the subscriber to be metered + +If you do not have a NMS setup with integration to Magma's REST API, the +details below should help. If your `orc8r` is functional, you should be able to +manually access the Swagger API. + +**Configuring Rating Group** + +`/networks/{network_id}/rating_groups` + +Configure with the following JSON as an example. Modify the ID as necessary. + +``` +{ + "id": 1, + "limit_type": "INFINITE_METERED" +} +``` + +**Configuring Policy Rule** + +`/networks/{network_id}/policies/rules` + +Configure with the following JSON as an example. Here, the flow list is set +to allow all traffic. A high priority is also set to override other rules. +You may need to modify the `rating_group` to match the ID of the rating group +you configured earlier. Here you also have a chance to directly assign the +policy to the subscriber you wish to meter for. + +``` +{ + "app_name": "NO_APP_NAME", + "app_service_type": "NO_SERVICE_TYPE", + "assigned_subscribers": [], + "flow_list": [ + { + "action": "PERMIT", + "match": { + "direction": "UPLINK", + "ip_proto": "IPPROTO_IP" + } + }, + { + "action": "PERMIT", + "match": { + "direction": "DOWNLINK", + "ip_proto": "IPPROTO_IP" + } + } + ], + "id": "metering_rule", + "priority": 10, + "qos": { + "max_req_bw_dl": 0, + "max_req_bw_ul": 0 + }, + "rating_group": 1, + "tracking_type": "ONLY_OCS" +} +``` + +**Assigning Policy to Subscriber** + +`/lte/{network_id}/subscribers` +`/networks/{network_id}/policies/rules/{rule_id}` + +Two endpoints can be used for assigning the metering policy to a subscriber. +Set the `assigned_subscribers` field for a policy rule, or set the +`active_policies` field for a subscriber. + + +### Verifying Metering + +It may take up to a minute for the update configurations to propagate to +the LTE gateway, where they should be received and stored by `policydb`. + +Check the metrics REST endpoint to verify that metering data is being recorded. + +### Debugging Metering + +On subscriber attach, `policydb` will provide the metered policy to install for +the subscriber. By tailing these logs, it is possible to verify that the +configurations are being received. +`journalctl -fu magma@policydb` + +`pipelined` is the service which is responsible for enforcement, by use of OVS. +By using the CLI tool, it is possible to verify that the policy rule is being +installed for the user. The policy id will be listed if installed, along with +tracked usage. +`pipelined_cli.py debug display_flows` +This command may need to be run as root. + +`sessiond` is responsible for aggregating metrics and sending metering through +our metrics pipeline. To check the tracked metrics for metering, and the +`sessiond` service, run the following: +`service303_cli.py metrics sessiond` diff --git a/docusaurus/versioned_docs/version-1.3.X/lte/config_agw.md b/docusaurus/versioned_docs/version-1.3.X/lte/config_agw.md new file mode 100644 index 0000000..18ad888 --- /dev/null +++ b/docusaurus/versioned_docs/version-1.3.X/lte/config_agw.md @@ -0,0 +1,113 @@ +--- +id: version-1.3.X-config_agw +title: AGW Configuration +sidebar_label: AGW Configuration +hide_title: true +original_id: config_agw +--- +# Access Gateway Configuration +## Prerequisites + +Before beginning to configure your Magma Access Gateway, you will need to make +sure that it is running all services without crashing. You will also need a +working Orchestrator setup. Please follow the instructions in +"[Deploying Orchestrator](../orc8r/deploy_intro)" for a +successful Orchestrator installation. + +You will need to set up a super-user in a valid NMS Organization in order to +use the NMS. See "[NMS Multitenancy](../nms/nms_organizations)" +to complete this step. + +You also should have completed all the steps in "[Access Gateway Setup (On Bare Metal)](setup_deb)". +For this part, we strongly recommend that you SSH into the AGW box from a host +machine instead of using the AGW directly. + +In this latest version, Magma Access Gateway no longer has a hardwired default Access Point Name (APN). Therefore, each UE must have a subscription profile that includes at least one APN to be able to attach to the network. Please follow the instructions in "[APN Configuration](config_apn)". + +## Access Gateway Configuration + +First, copy the root CA for your Orchestrator deployment into your AGW: + +```bash +HOST$ scp rootCA.pem magma@10.0.2.1:~ +HOST$ ssh magma@10.0.2.1 + +AGW$ sudo mkdir -p /var/opt/magma/tmp/certs/ +AGW$ sudo mv rootCA.pem /var/opt/magma/tmp/certs/rootCA.pem +``` + +Then, point your AGW to your Orchestrator: + +```bash +AGW$ sudo mkdir -p /var/opt/magma/configs +AGW$ cd /var/opt/magma/configs +AGW$ sudo vi control_proxy.yml +``` + +Put the following contents into the file: + +``` +cloud_address: controller.yourdomain.com +cloud_port: 443 +bootstrap_address: bootstrapper-controller.yourdomain.com +bootstrap_port: 443 + +rootca_cert: /var/opt/magma/tmp/certs/rootCA.pem +``` + +Then restart your services to pick up the config changes: + +```bash +AGW$ sudo service magma@* stop +AGW$ sudo service magma@magmad restart +``` + +## Creating and Configuring Your Network + +Navigate to your NMS instance, https://your-org.nms.yourdomain.com, and log in +with the superuser credentials you provisioned for this organization. If this +is a fresh Orchestrator install, you will be prompted to create your first +network. Otherwise, select "Create Network" from the network selection icon +at the bottom of the left sidebar. + +![Creating a network](../../../../readmes/assets/nms/createnetwork_12.png) + +Fill out the network creation modal with the parameters that you want. There +are 3 steps in the modal window, but the network will be created after you hit +"Save and Continue" on the first screen, so you can exit the modal and +reconfigure the network later after that. + +## Registering and Configuring Your Access Gateway + +You need to grab the hardware secrets off your AGW: + +```bash +AGW$ show_gateway_info.py +Hardware ID: +------------ +1576b8e7-91a0-4e8d-b19f-d06421ad72b4 + +Challenge Key: +----------- +MHYwEAYHKoZIzj0CAQYFK4EEACIDYgAECMB9zEbAlLDQLq1K8tgCLO8Kie5IloU4QuAXEjtR19jt0KTkRzTYcBK1XwA+C6ALVKFWtlxQfrPpwOwLE7GFkZv1i7Lzc6dpqLnufSlvE/Xlq4n5K877tIuNac3U/8un +``` + +Navigate to "Equipment" on the NMS via the left navigation bar, hit +"Add Gateway" on the upper right, and fill out the multi-step modal form. +Use the secrets from above for the "Hardware UUID" and "Challenge Key" fields. + +For now, you won't have any eNodeB's to select in the eNodeB dropdown under the +"Ran" tab. This is OK, we'll get back to this in a later step. + +At this point, you can validate the connection between your AGW and +Orchestrator: + +```bash +AGW$ journalctl -u magma@magmad -f +# Look for the following logs +# INFO:root:Checkin Successful! +# INFO:root:[SyncRPC] Got heartBeat from cloud +# INFO:root:Processing config update gateway_id +``` + +If everything looks OK, you can move on to configuring your eNodeB. diff --git a/docusaurus/versioned_docs/version-1.3.X/lte/config_apn.md b/docusaurus/versioned_docs/version-1.3.X/lte/config_apn.md new file mode 100644 index 0000000..a24c3d0 --- /dev/null +++ b/docusaurus/versioned_docs/version-1.3.X/lte/config_apn.md @@ -0,0 +1,112 @@ +--- +id: version-1.3.X-config_apn +title: APN Configuration +hide_title: true +original_id: config_apn +--- + +# Access Point Name (APN) Configuration + +Before any of your subscribers can attach to your network, you will first have +to provision at least one APN. + +UEs can successfully attach and connected to the Magma AGWs if they have a +valid APN configuration in their subscription profile on the network side. +Typically, UEs send APN information explicitly in their connection requests. +The AGW pulls APN information from subscription data synced down from +Orchestrator to verify that UEs have a valid subscription for the requested APN. +If APN information is missing from the connection request, the AGW picks the +first APN in the subscriber profile as the default APN and establishes a +connection session according to that default APN. Once APN information is +selected, Magma allocates IP address for the UE under that APN. + +## Define APN Configurations + +First, check that there is at least one APN provisioned for your network: + +- Navigate to your NMS instance and on the sidebar click on "Configure" button. + +- In the newly opened page, on the top bar select "APN CONFIGURATION". +If there are already APNs defined, it will show up on this page. + +- You can edit or delete any of the existing APN configurations. +Note that the updates and deletions will be reflected automatically in +subscriber profiles and any new attaches as well as PDN connection requests +will be impacted by these changes. + +- You can also add a new APN configuration by clicking on the "Add APN" +button and filling out the requested fields. After saving these changes, the +page should refresh with the new list of APNs and their configurations. + +![Creating an APN Configuration](../../../../readmes/assets/nms/add_apnconfig.png) + +## Add APN Configurations to Subscriber Profiles + +The next step is to add one or more APN configurations to subscriber profiles +so that UEs can start consuming network services based on their APNs: + +- For an existing subscriber, to update its subscription profile, click on the +edit field and perform a multi-select under the "Access Point Names". +- For a new subscriber, fill out the fields including the "Access Point Names" +field (screenshot below shows the view after clicking on the "Add Subscriber" +button). Once you save the updated or new subscriber information, the APNs +added to the subscriber profile will show be reflected on the page. + +![Adding subscriber with APN](../../../../readmes/assets/nms/add_apn2subscriber.png) + +### Notes + +- The first APN listed under "Active APNs" for each subscriber becomes the +default APN that will be used if the UE omits the APN information in its +connection requests. + +- The subscriber data is streamed down to AGWs periodically and the new configs +should be reflected on AGW with some lag (typically, 1-2 minutes). + +- To check if an AGW is already updated, on the AGW, you can run the following +command to retrieve local subscriber data: + +`subscriber_cli.py get IMSI<15 digit IMSI>` + +An example output for a hypothetical user with IMSI 001010000000001 and APNs +`internet`, `ims` is shown below: + +``` +sid { + id: "001010000000001" +} +lte { + state: ACTIVE + auth_key: "..." # not shown in this example +} +network_id { + id: "my_network" +} +state { +} +sub_profile: "default" +non_3gpp { + apn_config { + service_selection: "ims" + qos_profile { + class_id: 5 + priority_level: 9 + } + ambr { + max_bandwidth_ul: 100000 + max_bandwidth_dl: 100000 + } + } + apn_config { + service_selection: "internet" + qos_profile { + class_id: 9 + priority_level: 15 + } + ambr { + max_bandwidth_ul: 100000000 + max_bandwidth_dl: 200000000 + } + } +} +``` diff --git a/docusaurus/versioned_docs/version-1.3.X/lte/dev_notes.md b/docusaurus/versioned_docs/version-1.3.X/lte/dev_notes.md new file mode 100644 index 0000000..3b31404 --- /dev/null +++ b/docusaurus/versioned_docs/version-1.3.X/lte/dev_notes.md @@ -0,0 +1,217 @@ +--- +id: version-1.3.X-dev_notes +title: Developer Notes for Access Gateway +hide_title: true +original_id: dev_notes +--- +# Developer Notes for Access Gateway + +This section provides a guide for anyone testing existing features, +fixing a bug or adding a new feature to the Access Gateway. All developers are +highly encouraged to maintain this guide to make sure it is up to date and +continues to grow. + +## Configuration/system settings + +If you have a gateway running in a VM (as described in the [Quick Start +Guide](../basics/quick_start_guide)), the `magma` directory is shared between +the guest and host machine, so changes made on either system reflect on the +other. Exceptions to this rule are the systemd unit files and python scripts. +Changes to these files on the guest or host need to be manually synced. + +### Configuration files/directories + +- `/etc/magma/`: location of default configurations and templates for all + services +- `/etc/magma/gateway.mconfig`: main file that contains the configuration for + all services, as exposed via the Orc8r API +- `/var/opt/magma/configs/gateway.mconfig`: For gateways connected to an + orchestrator, the configuration from Orc8r is periodically streamed to the +gateway and written here. This streamed config takes precedence over +`/etc/magma/gateway.mconfig`. +- `/etc/magma/.yml`: Service configuration file, in YAML format. + These configurations are local and are not exposed through the API. These +include logging level, local network interface names, etc. +- `/etc/magma/templates/.conf.template`: This contains the + structured template for the .conf file used as input to +some services, such as Control-proxy, Dnsd, MME and Redis. +- `/var/opt/magma/tmp/.conf`: The configuration file read by + some services, such as Control-proxy, Dnsd, MME and Redis, at start-up. This +file is generated by mapping the configuration values from `gateway.mconfig` and +`` to the template defined in `.conf.template`. + +### Systemd unit configuration files + +- `/etc/systemd/system/magma@.service`: Systemd unit + files for Magma service. Note that these files are maintained under +`magma/lte/gateway/deploy/roles/magma/files/systemd/` and are copied into the +`/etc/systemd/system` directory of the VM at the time of provisioning. You need +to manually sync changes to these files between guest and host OS. + +### Python scripts to generate configs + +- `generate__config.py`: Scripts that generate the + `.conf` file for some services. These are executed every time +a service starts. +Note that these files are maintained under `magma/lte/gateway/python/scripts` +and copied to the `/usr/local/bin` directory in the guest host at the time of +provisioning. Changes to these scripts need to be manually synced between the +guest and host OS. + +## Testing + +### Connecting a physical eNodeB and UE to Gateway VM + +While the [S1ap integration tests](s1ap_tests.md) provide a simulated UE(s) and +eNodeB(s) to test your AGW VM while actively developing, one can extend the +testing to physical UE and eNodeB. +To connect a physical eNodeB to the gateway VM: + +1. Connect the eNodeB to a port on the host machine, say it is interface `en9`. +2. From the VirtualBox GUI, switch the Adapter 1 (for `eth1` interface) from +`Host-only` to `Bridged` mode and bridge it to interface `en9` from above. +3. In gateway VM, modify the `nat_iface` in `/etc/magma/pipelined.yml` from +`eth2` to `eth0`. Restart all services. +4. In the gateway VM, follow the steps in [EnodeB +Configuration](enodebd#basic-troubleshooting). Make sure the `earfcn` set in the +enodebd section of `gateway.mconfig` is the one that is supported by the eNodeB +under consideration. + +To connect a physical UE to the gateway VM, + +1. Use a programmable SIM which is provisioned with the LTE auth key that you +will use in the EPC. +2. On the gateway VM, add the subscriber using the CLI: +3. `magtivate` +4. `subscriber_cli.py add --lte-auth-key IMSI<15 digit +IMSI>` +5. On the UE, turn airplane mode on, then off, to trigger a fresh attach + +## Debugging + +### Logs + +To change the logging level for a particular service, please modify the +`log_level` in `/etc/magma/.yml` + +- `/var/log/syslog`: gives a good view of all the Magma services +running on the AGW. This is a good place to check whether the AGW is connecting +to the orchestrator, any GRPC errors or which service is causing a cascaded +crash (e.g. a crash in Sessiond can cause Mme service to terminate). + A good way to filter the logs from individual processes is with `journalctl`. +For example, to look at logs from SubscriberDb use: + `sudo journalctl -fu magma@subscriberdb` + +- `/var/log/mme.log` is a symbolic link that points to the latest log file +created by the MME service. The Mme service creates a new log file with name +`MME.magma-dev.root.log.INFO.-