From cfb019421176f0d14350449f17f78b089b733723 Mon Sep 17 00:00:00 2001 From: Dave Hibberd Date: Sat, 30 Nov 2024 21:22:36 +0000 Subject: [PATCH] Add bpq migration guide --- docs/.CNAME.kate-swp | Bin 0 -> 282 bytes docs/install/bpq-migrate.md | 165 ++++++++++++++++++++++++++++++++++++ docs/install/bpq.md | 5 +- mkdocs.yml | 1 + 4 files changed, 168 insertions(+), 3 deletions(-) create mode 100644 docs/.CNAME.kate-swp create mode 100644 docs/install/bpq-migrate.md diff --git a/docs/.CNAME.kate-swp b/docs/.CNAME.kate-swp new file mode 100644 index 0000000000000000000000000000000000000000..88052e2695f8487f7492537a93d69d2881f9f4d3 GIT binary patch literal 282 zcmZQzU=Z?7EJ;-eE>A2_aLdd|RWQ;sU|?Vn`DC;s_}8t+J8ktA<({3v^!azhj~T&1 zKp7C=1Y%xSIF|z?gy6CRxf}>C8<5NH8te(AKmf#L%s}u#su?p8e2`&`NeDj3E@VCz nntE;!KM|px2gJ`q@OeReJp`W*#Lq|Y`9b_51YZEePj>|X5#c0i literal 0 HcmV?d00001 diff --git a/docs/install/bpq-migrate.md b/docs/install/bpq-migrate.md new file mode 100644 index 0000000..abbb85f --- /dev/null +++ b/docs/install/bpq-migrate.md @@ -0,0 +1,165 @@ +# BPQ Migration + +If you wish to migrate from a manual installation using binaries either self +built or downloaded directly from G8BPQ, the below should offer you an insight +into the best practises and things to look out for! + +There are a few key differences from how the version shipped in Hibbian works +from vanilla LinBPQ! This might require a slight shift in how you approach some +basic commands. + + 1. The config file lives in /etc with other system config files + 2. The working/state files live in /opt/oarc/bpq + 3. It is started/stopped with `systemd` instead of directly running the binary + 4. It runs as a dedicated user that you don't use day to day to allow for +better security. + +!!! tip + + /opt/oarc/bpq is a reflection of the [OARC](https://oarc.uk) where the + project grew from and I'm too scared at this point to move files out of + that folder! + +## Stop your existing LinBPQ + +Use whatever method you normally use to stop your BPQ. It is best not to move +files around while changes are happening! + +## Back everything up + +Copy it to a different place, stick it on a USB stick or on a different +machine, but make sure you have another location where everything is in its +current state. + +Have everything saved somewhere else so you can put it back in place and move +back to your current approach if you don't like the new one! + +## Make note of locations of files + +We're particularly interested in bpq32.cfg and the working files. This will be +the directory holding chatconfig.cfg, axipcache.cfg, BPQNODES.dat, DIRMES.SYS. +If you're using the plain binary of bpq I think it just puts all that stuff +beside it. + +## Install the Hibbian Repo + +Follow the instructions at [../repo](Repo guide) to set up the repo on your +computer. + +## Install LinBPQ + +To learn more about installing applications on Linux, please see +[../linux.md/#applications-and-repositories](the Linux Guide). + +### GUI + +Search linbpq in your computer's app store and install it + +### Terminal + +Run the below in your terminal to install the latest and greatest LinBPQ on +your system: + +!!!note "Terminal Command" + ``` + sudo apt install linbpq + ``` + +Once this has completed, we also need to stop linbpq so we can replace the +files I put in place for a new install: + +!!!note "Terminal Command" + ``` + sudo systemctl stop linbpq + ``` + +## Move your files into position +This will all need to be done as root via sudo + +### bpq32.cfg + +Copy `bpq32.cfg` from wherever it is to `/etc/bpq32.cfg` and update the +persmissions to ensure that the linbpq group can edit the config: + +!!! note "Terminal Commands" + ``` + sudo cp bpq32.cfg /etc/bpq32.cfg + sudo chown :linbpq /etc/bpq32.cfg + ``` + +### Working files + +Copy working files and folders from where they are to /opt/oarc/bpq/ and then +update them to be owned by the `linbpq` user and group. + +As an example, if all my files live in a bpq folder in my pi's home, + +!!! note "Terminal Commands" + ``` + sudo cp -rf /home/pi/bpq/* /opt/oarc/bpq/ + sudo chown -R linbpq:linbpq /opt/oarc/bpq/ + ``` + +### Start the new node! + +Start your new setup with the below command and see if anything explodes. + +The standard way to start your node is now: +!!!note "Terminal Command" + ``` + sudo systemctl start linbpq + ``` + +After a few seconds, I recommend checking to see if everything is running using + +!!!note "Terminal Command" + ``` + sudo systemctl status linbpq + ``` +This is the standard command to see if the system is alive, dead and how it +failed. + +If everything is good, it'll say `Active: active (running)` with terminal +output that looks like this: + +``` +hibby@gb7hib:/etc$ sudo systemctl status linbpq +● linbpq.service - Linbpq systemd service file + Loaded: loaded (/lib/systemd/system/linbpq.service; enabled; preset: +enabled) + Active: active (running) since Sat 2024-11-30 20:57:01 UTC; 5s ago + Main PID: 314200 (linbpq) + Tasks: 7 (limit: 4395) + Memory: 4.4M + CPU: 160ms + CGroup: /system.slice/linbpq.service + └─314200 /usr/sbin/linbpq -c /etc -d /opt/oarc/bpq -l /opt/oarc/bpq + +Nov 30 20:57:01 gb7hib linbpq[314200]: Config Processed +Nov 30 20:57:01 gb7hib LINBPQ[314200]: Resolving chatupdate.g8bpq.net +Nov 30 20:57:01 gb7hib LINBPQ[314200]: cant open forms dir +/opt/oarc/bpq/Standard_Templates 2 0 +Nov 30 20:57:01 gb7hib LINBPQ[314200]: cant open forms dir +/opt/oarc/bpq/Standard Templates 2 0 +Nov 30 20:57:01 gb7hib linbpq[314200]: Mail Started +Nov 30 20:57:01 gb7hib LINBPQ[314200]: cant open forms dir +/opt/oarc/bpq/Local_Templates 2 0 +Nov 30 20:57:01 gb7hib LINBPQ[314200]: Maint Clock 1733011200 NOW 1733000221 +Time to HouseKeeping 10979 +Nov 30 20:57:03 gb7hib LINBPQ[314200]: Trying APRSIS Host 56.244.0.0 (1) +aprsis1.he.fi +Nov 30 20:57:03 gb7hib LINBPQ[314200]: # aprsc 2.1.19-g730c5c0 +``` + +If not all is well, look a little deeper! Scroll the console output with: + +!!!note "Terminal Command" + ``` + sudo journalctl -xeu linbpq + ``` + +Have a read and see if there's anything failing noisily. + +Failing that, recheck you did the permissions step above, reach out for help +or, worst case, go back to the old system you've backed up and definitely not +deleted or modified! diff --git a/docs/install/bpq.md b/docs/install/bpq.md index 1fdf679..0e2dd4d 100644 --- a/docs/install/bpq.md +++ b/docs/install/bpq.md @@ -17,12 +17,11 @@ To install LinBPQ from the repo, run the below commands: We need to prepare the system and get configuration files in place. This must be run on the command line, it's simply the fastest way. -Copy these three lines, one-at-a-time into your terminal and hit enter after +Copy these two lines, one-at-a-time into your terminal and hit enter after each one. !!!note "Terminal Commands" ``` - sudo cp /usr/share/doc/linbpq/examples/bpq32.cfg /etc/bpq32.cfg sudo chown :linbpq /etc/bpq32.cfg sudo chmod 644 /etc/bpq32.cfg ``` @@ -116,7 +115,7 @@ Head back to the terminal and run `sudo systemctl start linbpq` This will tell the system you want to start the `linbpq` service. Navigate to -[http://127.0.0.1:8008](http://127.0.0.1:8008) if you are on the systme you've +[http://127.0.0.1:8008](http://127.0.0.1:8008) if you are on the system you've performed the install on and you should see a webpage like below: ![bpq welcome page](../static/img/node-main.png) diff --git a/mkdocs.yml b/mkdocs.yml index b76c1df..dbb2899 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -19,6 +19,7 @@ nav: - Node Setup: - software.md - install/bpq.md + - install/bpq-migrate.md - install/linux.md - install/xrouter.md - Node Configuration: