From 458a2a5b79dce354b86a83a58992c7beb99d1734 Mon Sep 17 00:00:00 2001 From: Mark Nash Date: Sun, 21 Jul 2024 22:23:54 -0700 Subject: [PATCH] Adding info about librenms --- docs/contribute/contribute.md | 2 +- docs/infrastructure/.pages | 3 ++- docs/infrastructure/librenms/.pages | 4 ++++ docs/infrastructure/librenms/backup.md | 2 ++ docs/infrastructure/librenms/deploy.md | 24 ++++++++++++++++++++++++ docs/infrastructure/librenms/upgrade.md | 20 ++++++++++++++++++++ 6 files changed, 53 insertions(+), 2 deletions(-) create mode 100644 docs/infrastructure/librenms/.pages create mode 100644 docs/infrastructure/librenms/backup.md create mode 100644 docs/infrastructure/librenms/deploy.md create mode 100644 docs/infrastructure/librenms/upgrade.md diff --git a/docs/contribute/contribute.md b/docs/contribute/contribute.md index 098ec37..70a02f3 100644 --- a/docs/contribute/contribute.md +++ b/docs/contribute/contribute.md @@ -40,7 +40,7 @@ but it also allows you to connect to your own GitHub repo and pull/push. [MkDocs](https://www.mkdocs.org/) is pretty simple, just install it through pip then you can run `mkdocs serve` to locally view the website it will generate. ## Documentation Directory Structure -Each directory has a `.site` file that declares the order each file/folder in that directory will show up. +Each directory has a `.pages` file that declares the order each file/folder in that directory will show up. Children pages are implicit in the directory structure ## Static Files diff --git a/docs/infrastructure/.pages b/docs/infrastructure/.pages index 37c8ff6..3de0f81 100644 --- a/docs/infrastructure/.pages +++ b/docs/infrastructure/.pages @@ -6,4 +6,5 @@ nav: - librenms-setup.md - epc-setup.md - sas-setup.md - - proxmox-vaultwarden-deployment.md \ No newline at end of file + - proxmox-vaultwarden-deployment.md + - librenms \ No newline at end of file diff --git a/docs/infrastructure/librenms/.pages b/docs/infrastructure/librenms/.pages new file mode 100644 index 0000000..ea632fd --- /dev/null +++ b/docs/infrastructure/librenms/.pages @@ -0,0 +1,4 @@ +nav: + - deploy.md + - upgrade.md + - backup.md \ No newline at end of file diff --git a/docs/infrastructure/librenms/backup.md b/docs/infrastructure/librenms/backup.md new file mode 100644 index 0000000..1a01460 --- /dev/null +++ b/docs/infrastructure/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= > librenms.sql` \ No newline at end of file diff --git a/docs/infrastructure/librenms/deploy.md b/docs/infrastructure/librenms/deploy.md new file mode 100644 index 0000000..8c9a7f6 --- /dev/null +++ b/docs/infrastructure/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 + diff --git a/docs/infrastructure/librenms/upgrade.md b/docs/infrastructure/librenms/upgrade.md new file mode 100644 index 0000000..0b259b3 --- /dev/null +++ b/docs/infrastructure/librenms/upgrade.md @@ -0,0 +1,20 @@ +# Upgrading +Upgrading can be segmented into 2 parts. The container OSses and the service + +## OS +Each container runs an OS +- The Maria db container is based on ubuntu, so you can just do `sudo apt update` and `sudo apt upgrade` when executing bash on the container +- The Redis container for some reason only has an ash executable installed on the container. Also it runs on alpine so it can be updated using `apk update` and `apk upgrade` +- The libreNMS and the libreNMS dispatcher container is instantiaated on the same container which is on alpine, and uses bash. Update as usual for alpine installs. + +## Service +I think that libreNMS vends a script called daily.sh (librenms docs [here](https://docs.librenms.org/General/Updating/)) that is added to the cron, but cron is not running on docker containers since each container only runs one process. Even if we manually run daily.sh, there are errors. I think that the docs also give a manually manual way to update, by doing a git clone, but since the librenms files were not pulled using git, we cant use this way. I tried using rsync to overwrite the old files with the new files, but there are some issues. The nuclear option can be used, which is remove the containers, build new updated ones, and start that, but this will include a small outage + +1. Go to the compose directory and run `sudo docker compose down` to stop and remove all the containers. We store data (rrd files and the database) in a docker volume inside the compose directory anyway so we should not need to worry about removing containers removing any data +1. Go to the `librenms_image` directory, change the version of the image to the latest version [here](https://hub.docker.com/r/librenms/librenms/tags) +1. run `sudo docker build . -t scn-librenms`, which should build the new image +1. go to the `db_image` directory and update the Dockerfile's version to the latest version [here](https://hub.docker.com/_/mariadb/tags) +1. run `sudo docker build . -t scn_mariadb_librenms` +1. go to the compose directory and update the compose.yml file to use the latest redis release [here](https://hub.docker.com/_/redis/tags) +1. Then you should be able to start the service with a `sudo docker compose -f compose/compose.yml up -d` +1. The service should come up as it was before. If it does not, you may have to do a [./lnms migrate](https://docs.librenms.org/General/Updating/) \ No newline at end of file