fixed typos. changed some chapter titles infrastructure->tutorials an…

…d sas-setup->enb-setup
Local-Connectivity-Lab · Aug 20, 2024 · da3255c · da3255c
1 parent 3d67c97
commit da3255c
Show file tree

Hide file tree

Showing 13 changed files with 1,017 additions and 0 deletions.
diff --git a/docs/tutorials/.pages b/docs/tutorials/.pages
@@ -0,0 +1,10 @@
+nav:
+  - hardware.md
+  - software.md
+  - peering.md
+  - librenms-manager-setup.md
+  - librenms-setup.md
+  - epc-setup.md
+  - enb-setup.md
+  - proxmox-vaultwarden-deployment.md
+  - librenms
diff --git a/docs/tutorials/enb-setup.md b/docs/tutorials/enb-setup.md
diff --git a/docs/tutorials/epc-setup.md b/docs/tutorials/epc-setup.md
@@ -0,0 +1,9 @@
+---
+title: Step 1. LTE Core Network Setup
+---
+
+# Step 1: CoLTE/EPC (LTE Core Network) Setup
+
+Our core networks use the [CoLTE project](https://github.com/uw-ictd/colte) maintained by the [UW ICTD Lab](https://ictd.cs.washington.edu/).
+
+For information on how to install and configure CoLTE, visit the [tutorial](https://docs.colte.network/tutorials/epc-setup.html) we wrote with them!
diff --git a/docs/tutorials/hardware.md b/docs/tutorials/hardware.md
@@ -0,0 +1,76 @@
+---
+title: Hardware Overview
+---
+
+# Our Hardware
+
+This page will be an overview of some of the core pieces of hardware that we use to deploy our sites.
+
+This page is in development, please contact us at lcl@seattlecommunitynetwork.org if you would like to learn more about the hardware we use.
+
+**TODO**
+=======
+## Network Site Equipment
+
+### Base Station (eNodeB)
+![Baicells Nova 233 Base Station Marketing Image](https://www.doubleradius.com/images/Nova-233-3-5GHz-1W-Gen2-mBS1105_02.jpg?resizeid=3&resizeh=1000&resizew=1000)
+
+Baicells Nova 233 3.5GHz 1W Gen2
+
+More info [here](https://www.doubleradius.com/baicells-nova-233-gen-2-enodeb-outdoor-base-station)
+
+### Panel Antennas (eNodeB)
+![Alpha Wireless Antenna Marketing Image](https://www.lastmilegear.com/wp-content/uploads/2017/12/aw3014.jpg)
+
+Alpha Wireless, 3.3-3.8GHz, 2x2 MIMO, 18dBi, +/-45°, 65°
+
+More info [here](https://www.lastmilegear.com/shop/alpha-aw3014/)
+
+### Core Network Computer (EPC)
+![Qotom Mini PC Marketing Image](https://www.qotom.net/upload/thumb_src/400_400/1526031726.jpg)
+
+Qotom Mini PC Q190G4N S07
+
+Key features:
+- 4 ethernet ports
+- designed to be run 24/7
+- small and quiet
+- cheap
+
+More info [here](https://www.qotom.net/product/36.html)
+
+## User Access Devices
+
+### LTE Consumer Premises Equipment (CPE)
+![Baicells Atom CPE Marketing Image](https://www.lastmilegear.com/wp-content/uploads/2018/02/Baicells-Atom-eg8035L.jpg)
+
+Baicells Atom OD04 3.5GHz 14dBi
+
+More info [here](https://www.lastmilegear.com/shop/atom-od04-3-5ghz-14dbi-gen2/)
+
+### Outdoor WiFi Router
+![Mikrotik OmniTIK 5 PoE ac Marketing Image](https://www.wifi-stock.com/full/omnitik_5ac.jpg?size=10)
+
+Mikrotik OmniTIK 5 PoE ac
+
+Outdoor router of choice for NYC Mesh, so it has been tried and tested. Good balance of quality and price.
+
+More info [here](https://mikrotik.com/product/rbomnitikpg_5hacd)
+
+### Home WiFi Router
+![TP-Link Archer A5 Router Marketing Image](https://m.media-amazon.com/images/I/51R2a9p-vNL._AC_SS450_.jpg)
+
+TP-Link Archer A5 Router
+
+More info [here](https://www.tp-link.com/us/home-networking/wifi-router/archer-a5/)
+
+### CBRS-Compatible Unlocked Smartphone
+
+We purchase refurbished Google Pixel 4 smartphones because they are affordable, provide all
+necessary smartphone features, and are CBRS-compatible.
+
+Note that purchasing CBRS-compatible phones can be a logistical challenge. We've experienced trouble purchasing
+from vendors that send incorrect models of phones that don't support CBRS band and we had to go back and forth.
+Test your phones before distributing them!
+
+Here is [one spot](https://www.backmarket.com/search?q=pixel%204&ga_search=pixel%204) to purchase refurbished phones.
diff --git a/docs/tutorials/librenms-manager-setup.md b/docs/tutorials/librenms-manager-setup.md
@@ -0,0 +1,150 @@
+---
+title: Network Monitoring 1. LibreNMS Network Manager Configuration
+---
+
+# LibreNMS Network Manager Configuration
+
+Seattle Community Networks uses SNMP to monitor network nodes. LibreNMS is used for Network Management, Dashboard generation and Alerting.
+
+## LibreNMS Manager Installation:
+[Install LibreNMS](https://docs.librenms.org/Installation/Install-LibreNMS/)
+[Install and Configure LibreNMS on Ubuntu with nginx](https://computingforgeeks.com/how-to-install-and-configure-librenms-on-ubuntu-with-nginx/)
+
+## Network-Specific Configuration:
+Change active user to librenms:
+```sudo su - librenms```
+
+Edit /opt/librenms/config.php:
+
+```php
+<?php
+
+$config['user'] = 'librenms';
+$config['base_url'] = "/";
+$config['snmp']['community'] = array('<SNMP COMMUNITY STRING>');
+$config['auth_mechanism'] = "mysql"; # default, other options: ldap, http-auth
+$config['nets'][] = "10.0.0.0/24"; # Replace with your Management Network Subdomain
+$config['rrd_purge'] = 0;
+$config['enable_billing'] = 1;
+$config['show_services'] = 1;
+```
+
+As user 'librenms', run /opt/librenms/snmp-scan.php, to scan the configured network for snmp hosts
+
+## Adding Baicells OS configuration to LibreNMS
+
+As user 'librenms' on the librenms server, create the following files and update their contents accordingly:
+* For OS detection, ~librenms/includes/definitions/rts.yaml:
+```
+	os: rts
+		text: 'Baicells RTS'
+		type: network
+		icon: rts
+		over:
+		- { graph: device_bits, text: 'Device Traffic' }
+		- { graph: device_processor, text: 'CPU Usage' }
+		- { graph: device_mempool, text: 'Memory Usage' }
+		discovery:
+		- sysDescr:
+			- 'CELL'
+```
+
+* For defining custom RTS OS sensors, ~librenms/includes/definitions/discovery/rts.yaml:
+
+```
+mib: BAICELLS-MIB
+modules:
+	os:
+    	hardware: BAICELLS-MIB::hardwareVersion.0
+    	serial: BAICELLS-MIB::sn.0
+    	version: BAICELLS-MIB::softwareVersion.0
+	sensors:
+    	count:
+        	data:
+            	-
+                	oid: ulThroughput
+                	num_oid: '.1.3.6.1.4.1.53058.190.7.{{ $index }}'
+                	descr: 'Upload Throughput'
+                	group: 'Throughput'
+                	index: 'ulthroughput.{{ $index }}'
+            	-
+                	oid: dlThroughput
+                	num_oid: '.1.3.6.1.4.1.53058.190.8.{{ $index }}'
+                	descr: 'Download Throughput'
+                	group: 'Throughput'
+                	index: 'dlThroughput.{{ $index }}'
+            	-
+                	oid: ulPrbUtilization
+                	num_oid: '.1.3.6.1.4.1.53058.190.9.{{ $index }}'
+                	descr: 'Upload PRB Utilization'
+                	group: 'Utilization'
+                	index: 'ulPrbUtilization{{ $index }}'
+            	-
+                	oid: dlPrbUtilization
+                	num_oid: '.1.3.6.1.4.1.53058.190.10.{{ $index }}'
+                	descr: 'Download PRB Utilization'
+                	group: 'Utilization'
+                	index: 'dlPrbUtilization.{{ $index }}'
+    	frequency:
+        	data:
+            	-
+                	oid: carrierBwMhz
+                	num_oid: '.1.3.6.1.4.1.53058.100.7.{{ $index }}'
+                	divisor: 5
+                	descr: 'Carrier Bandwidth'
+                	index: 'carrierBwMhz.{{ $index }}'
+    	percent:
+        	data:
+            	-
+                	oid: eRABEstablishSuccessRate
+                	num_oid: '.1.3.6.1.4.1.53058.190.3.{{ $index }}'
+                	descr: 'ERAB Establishment Success Rate'
+                	group: 'LTE'
+                	index: 'eRABEstablishSuccessRate.{{ $index }}'
+            	-
+                	oid: hoSuccInterEnbS1Rate
+                	num_oid: '.1.3.6.1.4.1.53058.190.4.{{ $index }}'
+                	descr: 'Inter MME S1 Handover Success Rate'
+                	group: 'LTE'
+                	index: 'heSuccInterEnbS1Rate.{{ $index }}'
+            	-
+                	oid: hoSuccInterEnbRate
+                	num_oid: '.1.3.6.1.4.1.53058.190.5.{{ $index }}'
+                	descr: 'Inter MME Handover Success Rate'
+                	group: 'LTE'
+                	index: 'hoSuccInterEnbRate.{{ $index }}'
+            	-
+                	oid: rrcBuildSuccessRate
+                	num_oid: '.1.3.6.1.4.1.53058.190.6.{{ $index }}'
+                	descr: 'RRC Build Success Rate'
+                	group: 'LTE'
+                	index: 'rrcBuildSuccessRate.{{ $index }}'
+```
+
+* For defining a custom OS class to use Wireless sensors, ~librenms/LibreNMS/OS/Rts.php (note: pay attention to capitalization)
+
+```php
+<?php
+namespace LibreNMS\OS;
+
+use LibreNMS\Device\WirelessSensor;
+use LibreNMS\Interfaces\Discovery\Sensors\WirelessClientsDiscovery;
+use LibreNMS\Interfaces\Discovery\Sensors\WirelessUtilizationDiscovery;
+use LibreNMS\OS;
+
+class Rts extends OS implements WirelessClientsDiscovery
+{
+	public function discoverWirelessClients()
+	{
+    	$oid = '.1.3.6.1.4.1.53058.100.11.0'; //BAICELLS-MIB::ueConnections.0
+    	return array(
+        	new WirelessSensor('clients', $this->getDeviceId(), $oid, 'rts', 1, 'UE Connections')
+    	);
+	}
+}
+```
+
+* A nice looking logo, ~librenms/html/images/os/rts.png
+[Download an example Baicells Logo Here](https://imgur.com/9AOohPr.png)
+
+* Download the baicells mib from [this link](https://na.baicells.com/download/RTS%203.6%20BAICELLS-MIB.mib), and save it to ~librenms/mibs/BAICELLS-MIB (note: no file extension)
diff --git a/docs/tutorials/librenms-setup.md b/docs/tutorials/librenms-setup.md
@@ -0,0 +1,111 @@
+---
+title: Network Monitoring 2. LibreNMS Agent Configuration
+---
+
+# LibreNMS Agent Configuration
+
+## Adding a New Node to LibreNMS
+
+Both the eNodeB and the EPC must be configured individually in order for them to report statistics to the SNMP Manager. Since the eNodeB is not directly accessible from the management VPN, we configure an SNMP proxy on the EPC to pass SNMP statistics to the Management host.
+
+## EPC SNMP Configuration
+
+* Install snmpd to the EPC node:
+``` $ sudo apt install snmpd ```
+
+* Modify /etc/snmp/snmpd.conf:
+
+```
+sysLocation 	<SITE NAME STRING>
+sysContact  	lcl@seattlecommunitynetwork.org
+sysServices 	72
+master      	agentx
+agentAddress	udp:161
+com2sec readonly <SNMP Manager IP Address> <SNMP COMMUNITY STRING>
+com2sec -Cn ctx_baicells readonly <SNMP Manager IP Address> enodeb
+group readonlygroup v2c readonly
+view all included .1
+access readonlygroup "" v2c noauth exact all none none
+access readonlygroup ctx_baicells v2c noauth prefix all none none
+proxy -Cn ctx_baicells -v 2c -c private 192.168.151.1 .1.3
+```
+
+This configuration allows us to access SNMP data on the EPC with the standard community string (refer to internal standards documentation). but will proxy the Baicells SNMP data when we send the community string ‘enodeb’
+
+* Update the snmpd service file to automatically restart snmpd on crash:
+   * Edit /lib/systemd/system/snmpd.service, modify the 'ExecStart' line, and add the 'ExecReload', 'Restart', and 'RestartSec' lines:
+
+```
+[Unit]
+Description=Simple Network Management Protocol (SNMP) Daemon.
+After=network.target
+ConditionPathExists=/etc/snmp/snmpd.conf
+
+[Service]
+Type=simple
+ExecStartPre=/bin/mkdir -p /var/run/agentx
+ExecStart=/usr/sbin/snmpd -LO2w -u Debian-snmp -g Debian-snmp -I -smux,mteTrigger,mteTriggerConf -f -p /run/snmpd.pid
+ExecReload=/bin/kill -HUP $MAINPID
+Restart=on-failure
+RestartSec=5s
+
+[Install]
+WantedBy=multi-user.target
+```
+
+* Enable and restart snmpd:
+```
+Sudo systemctl daemon-reload
+sudo systemctl enable snmpd
+sudo systemctl restart snmpd
+```
+
+## Baicells SNMP configuration
+* Log into the Baicells configuration console:
+```https://<Baicells IP Address>```
+
+* From the left menu, select System
+
+* Select SNMP
+![Example Screenshot: enabling SNMP in the Baicells Console](https://i.imgur.com/YanPtMs.png)
+   * Under ‘SNMP Switch,’ select ‘Enable’
+   * Configure the following options:
+      * Community String: private
+      * Contact: lcl@seattlecommunitynetwork.org
+      * Location: \<SITE NAME STRING\> (String should not have any spaces)
+      * Source: Any
+
+## Adding the Node to LibreNMS
+* If the EPC is running, librenms should be able to auto-discover it. Run this command from a shell on the management host:
+```sudo -u librenms lnms scan```
+
+* LibreNMS should print a status message that it was able to add a new device.
+
+* When first discovered, the EPC will show up generically as it’s ip address. Edit the hostname, but clicking ‘Edit Device’ (gear icon):
+   * Click the red pencil icon, and change the ip address to the hostname
+   * Fill ‘Overwrite IP’ with the EPC IP address
+      * *Note: If the IP is not changed to the hostname, you will not be able to add the eNodeB by it’s IP address*
+![Example Screenshot: Updating EPC Hostname in LibreNMS](https://i.imgur.com/LHeL3Zq.png)
+
+* The Baicells eNB needs to be added manually: From LibreNMS, select Devices and click “Add Device”
+![Example Screenshot: Manually adding eNodeB to LibreNMS](https://i.imgur.com/Tlqpbh3.png)
+
+* Add a new device, with the following configurations:
+   * Hostname: <IP Address of the site’s EPC>
+   * Community: ‘enodeb’
+   * Force Add: On
+
+* *Note: If you receive an error message stating that a device with the specified IP already exists, make sure that you have* successfully changed the eNodeB’s hostname per the previous step.
+
+* Once the device is added, click the ‘Edit Device’ icon (gear icon) and update the following values:
+   * Display name: \<eNB Cell Name\>
+   * Overwrite device contact: lcl@seattlecommunitynetwork.org
+
+## Other helpful notes:
+
+* [Baicells eNB config guide](https://img.baicells.com//Upload/20210810/FILE/195c7e84-47d9-4acb-aa00-cba0e080d885.pdf)
+
+* How to SSH into Baicells eNB:
+   * SSH using port 27149 (username same as normal web-based login)
+   * Convert the MAC address of this eNB to link local address: http://www.sput.nl/internet/ipv6/ll-mac.html
+
diff --git a/docs/tutorials/librenms/.pages b/docs/tutorials/librenms/.pages
@@ -0,0 +1,4 @@
+nav:
+  - deploy.md
+  - upgrade.md
+  - backup.md
diff --git a/docs/tutorials/librenms/backup.md b/docs/tutorials/librenms/backup.md
@@ -0,0 +1,2 @@
+# Backing Up
+In the future when we want to back up the rrd folder of a docker install, you just need to copy the compose/librenms/rrd folder. If you want to back up the database, you need to go into the container called `librenms_db` and do a mysqldump with the user `librenms` with the database librenms and whatever password you set, probably in the environment variables of the compose file of the deployment This means something like `mysqldump librenms -u librenms --password=<your_password> > librenms.sql`
diff --git a/docs/tutorials/librenms/deploy.md b/docs/tutorials/librenms/deploy.md
@@ -0,0 +1,24 @@
+# Deploying
+I wrote a script to deploy libreNMS with the configuration that SCN uses. The repo is [here](https://github.com/abacef/scn-librenms-deploy-script/tree/main)
+
+## Software requirements
+Only tested on debian and ubuntu. Not sure what else it works on but it could work on other linux distros
+
+
+## Steps
+1. Install docker if it is not installed already
+1. Install docker compose if it is not installed already
+1. Instal unzip if it is not installed already
+1. Check out this repo
+1. If you want to restore a previous install, provide a sqldump named `librenms.sql` flat in this checked out repo. There is a helper script called `get_database_from_currently_running_server.sh` to get the database off of the non dockerized install (needs ssh access to the server)
+   1. If you want to restore the graphs too, you can provide a file named `rrd.zip` flat in the checked out repo which is just the rrd folder ziped up.  There is a helper script called `get_rrd_zip_from_currently_running_server.sh` to get the rrd zip from the non dockerized install (needs ssh access to the server)
+1. Run `./deploy.sh`
+   1. builds the librenms image
+   1. builds the database image with/without the backup
+   1. Starts the service using `docker compose`. This creates 2 shared volumes in the `compose` directory
+      1. The `librenms` folder is for the librenms docker images to share configuration data including rrd files
+      1. The `db` volume is the database
+   1. unzips the rrd folder in the rrd directory of the shared `librenms` volume
+
+The UI will run on port 8000
+