Sea of Fate - User contributions [en]

Minecraft

2026-05-16T13:14:24Z

Wikisailor: /* Software installation */

==Introduction==

We are to have some Minecraft servers on the '''[[Home Lab]]''''. The general setup will be to have a Velocity server in front several Minecraft host '''[[Virtual Machines]]'''. Velocity works in a similar way to a Nginx reverse proxy whereby Pfsense forwards all Minecraft traffic to the Velocity server including the SNI and Velocity redirects traffic to the required hostname based on the DNS name. Cloudflare does not reverse proxy Minecraft traffic on the free tier and as we do not want to have to deal with random bots from the east so we will not leave the port open on the edge or Pfsense to random bots with port scanners. So we will use grey cloud at Cloudflare but DNS will point to a service like TCPShield and our firewalls only accept Minecraft traffic from their IP addresses and Velocity will only accept named servers and drop any unknown DNS names.

==Installation==

The installation will be in some distinct stages to enable each step to be proved to be working before proceeding to the next stage. First we setup a simple vanilla Minecraft server and set the firewall to port forward to it directly. Once that is proven to be working we will setup a Velocity server that will receive all 25565 traffic and forward it to the working Minecraft host. The next phase after the first host is getting traffic forwarded is to setup a second host and make sure velocity can forward to each, included in this step will be hardening the Velocity server with whatever security measures that it has available. When we are sure that Velocity is working properly we can work on the remote access stage, where we use TCPShield to proxy the service and have Cloudflare DNS only names setup with cherry.seaoffate.net and apple.seaoffate.net etc. From this point forward any new Minecraft servers will simply follow the same setup procedure.

===The First Minecraft Host Configuration===

The first Minecraft host needs to have enough resources to run the JVM and the server but as it just a vanilla server the specification does not need to be excessive. The table shows the highlights.

{| class="wikitable"
|+
|-
! Item !! Value !! Notes
|-
|CPU || 2 ||
|-
|RAM || 4GB ||
|-
|Swap || 16gb || Additional disk allocated from Lexar SSD
|-
|Storage || 96GB || Initially set at 32gb
|-
|Base OS || Debian 13.3 || Server version
|-
|Hostname || Cherry ||
|-
|IP Address || 192.168.100.30 ||
|}

====Hardware Configuration====
The Cherry host was created as a clone of the Debian template and then the basic specifications were improved so we will need to configure these extra items in the OS. First we need to identify the harddrive to use as the swap file
lsblk
The result is likely to show that the disk is likely to be /dev/sdb so we can set the swap space and enable it with
sudo mkswap /dev/sdb
sudo swapon /dev/sdb
To make the swap file persistent we edit the fstab
sudo nano /etc/fstab
Add the line:
/dev/sdb none swap sw 0 0
and remove or comment out the line that refers to
/dev/sda3
Before the storage sda main partition can be expanded to the full 96GB we have to remove the swap that is in the way so disable the existing swap with
sudo swapoff /dev/sda3
Open the disk utility to modify sda
sudo fdisk /dev/sda
Delete the swap partition with the option d, then type 3 to delete partition 3, then w to save and exit. The next thing to do is expand the Primary Root Partition so open fdisk again:
sudo fdisk /dev/sda
Delete the root partition:
* Type d (Delete)
* Type 2 (this only deletes the table entry, not the data).
* Type n (Create a new partition)
* Type p (Primary Partition)
* Type 2 (For Partition number 2)
* Type enter (Use default values for start sector)
* Type enter (Use default values for end sectors to fill the 96GB)
* CRITICAL: When asked if you want to remove the signature, type N.
* Type w (Save and exit)
To finalize Storage reboot to refresh the kernel partition table:
sudo systemctl reboot
When the VM reboots expand the filesystem into the new space:
sudo resize2fs /dev/sda2
We can verify the new swap and new sda size with
df -h
Now that the hardware is setup and configured we can proceed to the software installation

====Software Installation====

The software installation consists of updates, install the JVM and then install the Minecraft server. So to start as we do on most hosts with updates
sudo apt update
sudo apt upgrade
Install Necessary Utilities:
sudo apt install htop screen wget curl -y
Install Java 25:
sudo apt install openjdk-25-jre-headless -y
Verify Java Installation (Ensure it reports OpenJDK 25)
java -version
Now we install the Minecraft server

Create the Server Directory:
mkdir ~/minecraft_server && cd ~/minecraft_server
Download the Server Software:
wget -O server.jar [https://piston-data.mojang.com/v1/objects/97ccd4c0ed3f81bbb7bfacddd1090b0c56f9bc51/server.jar](https://piston-data.mojang.com/v1/objects/97ccd4c0ed3f81bbb7bfacddd1090b0c56f9bc51/server.jar)
Assuming the file downloaded we need an initial run to generate the file:
java -Xms1G -Xmx1G -jar server.jar nogui
When the file is first created it will not run until we Accept the EULA with the command:
sed -i 's/eula=false/eula=true/' eula.txt
We can create the Start Script:
nano start.sh
Paste in the following
<nowiki> #!/bin/bash
while true
do
echo "--- Starting Minecraft Server ---"
java -Xms3G -Xmx3G \
--enable-native-access=ALL-UNNAMED \
-XX:+UseG1GC \
-XX:MaxGCPauseMillis=200 \
-XX:+UnlockExperimentalVMOptions \
-XX:+DisableExplicitGC \
-XX:+AlwaysPreTouch \
-jar server.jar nogui
echo "--- Server stopped. Restarting in 5 seconds (Ctrl+C to cancel) ---"
sleep 5
done</nowiki>
Set the script to execute with
chmod +x start.sh
We can start the server with
./start.sh
'''Note''' we can type the command stop in the terminal and the server will save the world and stop it for 5 seconds during the 5 seconds, if we type ctrl+c it will end the script or if we just leave it the server will restart.

====Enable External Access====

We will need to access the server from outside world so we should forward the Minecraft port 25565 to the IP address of cherry. To make the port forward rules in Pfsense easier to understand we add an alias for cherry's IP address and a port alias for 25565. We add a port forward rule to Pfsense that says source IP 192.168.0.0/16 and any port, destination this firewall (self) Destination port Minecraft_standard, redirect IP_cherry port Minecraft_standard.

====Testing====

With this configuration loading a Minecraft client and setting the destination server to the WAN port IP address it will connect to the cherry host.

As part of the wider LAN setup we added a Adguard LXC to manage DNS. Part of the Adguard configuration was made to avoid the hairpin network access so a DNS redirect was made to forward *.seaoffate.net to Pfsense WAN and as the default domain name was set to seaoffate.net. So now when we have a destination of cherry Adguard will translate the hostname to cherry.seaoffate.net and redirect it to Pfsense, Pfsense will then forward to the relevant server. If that does not work as expected the next test would be to set the destination to cherry.seaoffate.net which should be redirected by Adguard.

===Velocity Installation===

The Velocity server VM does not need to be especially high because all it needs to do is accept connections and forward them on to the relevant host and any associated functions like handle logon, bans and etc. Unlike the cherry host that we just setup the base specification from the Debian template needs to be cut down a bit and does not need a extra swap file or anything special.

{| class="wikitable"
|+
|-
! Item !! Value !! Notes
|-
|CPU || 1 ||
|-
|RAM || 1GB ||
|-
|Storage || 32GB ||
|-
|Base OS || Debian 13.3 || Server version
|-
|Hostname || Vangueria ||
|-
|IP Address || 192.168.100.29 ||
|}
====Software Installation====

As there is no additions to the VM's specification there is no hardware to configure so we can get straight to the software installation. So the well known update/upgrade and the packages can be installed with
sudo apt update && sudo apt upgrade -y
sudo apt install -y openjdk-25-jre-headless htop screen wget jq curl
Once the dependencies are installed, we create a dedicated application directory and use an automated script to identify the most recent build of Velocity 3.4.0. This ensures we are not relying on hardcoded links that may expire.
mkdir ~/velocity && cd ~/velocity
export PROJECT="velocity"
export VERSION="3.4.0-SNAPSHOT"
export LATEST_BUILD=$(curl -s https://api.papermc.io/v2/projects/${PROJECT}/versions/${VERSION} | jq '.builds[-1]')
wget -O ~/velocity/velocity.jar "https://api.papermc.io/v2/projects/${PROJECT}/versions/${VERSION}/builds/${LATEST_BUILD}/downloads/${PROJECT}-${VERSION}-${LATEST_BUILD}.jar"
The initial boot of Velocity is performed to generate the necessary configuration files. We launch it with a 512MB heap size and then shut it down gracefully using the end command once the prompt appears.
java -Xms512M -Xmx512M -jar velocity.jar

====Proxy Configuration and Routing====

The primary configuration for the proxy is handled within the velocity.toml file. This file dictates how the proxy listens for incoming traffic and how it maps domain names to internal IP addresses. We edit this file to ensure the proxy is listening on all interfaces and that it is using the modern forwarding protocol.
nano ~/velocity/velocity.toml
Modify these specific lines:
* Bind Address: bind = "0.0.0.0:25565" (Allows it to hear traffic from pfSense).
* Forwarding Mode: player-info-forwarding-mode = "modern" (This is the most secure protocol for 2026).
* ping-passthrough should be set to ALL. This is to ensure the server list on the Minecraft client correctly displays the status and version of the backend servers
* Server List: Scroll down to the [servers] section:
<nowiki>[servers]
cherry = "192.168.100.30:25565"
apple = "192.168.100.35:25565"

[servers]
try = [
"cherry"
]</nowiki>
* Forced Hosts: This tells the proxy which server to pick based on the URL the player typed:
<nowiki>[forced-hosts]
"cherry.seaoffate.net" = ["cherry"]
"apple.seaoffate.net" = ["apple"]</nowiki>
Save and close the file. next we need a start.sh file for Velocity
nano ~/velocity/start.sh
copy the following into the file
<nowiki> #!/bin/bash
while true
do
echo "--- Starting Vangueria Proxy ---"
java -Xms512M -Xmx512M \
-XX:+UseG1GC \
-XX:MaxGCPauseMillis=200 \
-XX:+UnlockExperimentalVMOptions \
-XX:+DisableExplicitGC \
-XX:+AlwaysPreTouch \
-jar velocity.jar
echo "--- Proxy stopped. Restarting in 5s ---"
sleep 5
done</nowiki>
To make the script executable
chmod +x ~/velocity/start.sh
At this point the since Vangueria is now set to Modern Forwarding, Cherry will reject all connections until it has the forwarding.secret. the secret can be obtained with the command
cat ~/velocity/forwarding.secret
Copy the code to a safe location because we will need it to setup cherry (and apple). then we should be able to finally start the proxy with the start.sh
./start.sh
Now we move to cherry to setup it's ability to receive connections from Vangueria.

====Configuring Cherry To Accept Proxied Connections====

To complete the integration between the proxy and the backend, Cherry must be transitioned from a standalone Vanilla server to a "Proxy-Aware" host. Because Vanilla Minecraft does not natively support Velocity’s Modern Forwarding (the security handshake), we use the Fabric Loader as a lightweight wrapper. This allows us to install a bridge mod that validates the secret key without changing the gameplay experience.The transition of Cherry involves three main phases: installing the Fabric environment, adding the bridge mods, and configuring the security handshake to match Vangueria.

First, we must stop the existing server and install the Fabric transition layer. This replaces the standard Mojang launcher with a version capable of loading the security bridge. We need to download the Fabric Installer and then Install Fabric for the 1.21.1 environment.
cd ~/minecraft_server
wget https://maven.fabricmc.net/net/fabricmc/fabric-installer/1.0.1/fabric-installer-1.0.1.jar
java -jar fabric-installer-1.0.1.jar server -mcversion 1.21.1 -downloadMinecraft
Once complete, the installer will have created a new file named fabric-server-launch.jar. This is now the primary entry point for the server.

To install the Security Bridge we require two specific components in the mods folder: the Fabric API (the library that allows mods to interact with the game engine) and FabricProxy-Lite (the specific mod that handles the Velocity secret key). It is vital to use version-matched JARs for 1.21.1 to ensure stability.
mkdir -p ~/minecraft_server/mods
wget -O ~/minecraft_server/mods/FabricProxy-Lite.jar https://github.com/OKTW-Network/FabricProxy-Lite/releases/download/v2.10.1/FabricProxy-Lite-2.10.1.jar
wget -O ~/minecraft_server/mods/fabric-api.jar https://github.com/FabricMC/fabric-api/releases/download/0.116.11%2B1.21.1/fabric-api-0.116.11+1.21.1.jar

To configure the handshake after placing the mods, we must run the server once to generate the configuration structure, then shut it down to inject the secret.
Update start.sh to point to fabric-server-launch.jar instead of server.jar
sed -i 's/server.jar/fabric-server-launch.jar/' start.sh
Initial run to generate config (Type 'stop' once the 'Done' message appears)
./start.sh
Now, we create the configuration file and link it to Vangueria. This is where we ensure the backend only trusts traffic coming from our proxy.
mkdir -p ~/minecraft_server/config
nano ~/minecraft_server/config/FabricProxy-Lite.toml
Paste the following configuration into the file, ensuring the secret matches the one obtained from Vangueria:
enabled = true
hackOnlineMode = true
secret = "PASTE_YOUR_VANGUERIA_SECRET_HERE"
The final step is to adjust the server.properties file. Because Vangueria handles the official Mojang authentication at the "front door," the backend server must be set to offline mode to allow the proxy to pass the authenticated user data through.
sed -i 's/online-mode=true/online-mode=false/' server.properties
With the configuration complete, the server should be launched inside a named screen session to ensure it remains active.
screen -S minecraft ./start.sh
We should now change the Pfsense port forward rule to forward traffic to the 192.168.100.29 (IP address of Vangueria) and then connecting a client from a laptop outside of Pfsense and using the address cherry.seaoffate.net, we can try using the IP address of the Pfsense WAN port but it may not work (if the default server is set to cherry it may connect)

===Additional Options===

There are a few additional considerations that will make the servers run more reliably. The first is thing that needs to be done is to run the server in a screen so that there does not need to be a SSH session to be running. The following will start a screen called minecraft and will execute the start.sh command.
screen -S minecraft ./start
To exit the minecraft screen and return to the main SSH type ctrl + a and then d, the minecraft screen can be reloaded with the command
screen -r minecraft
The next thing that we will need to do is to have the minecraft server start whenever the host reboots. So we need to add a cron tab to the start.sh
crontab -e
Select nano if asked then add the line
@reboot screen -dmS minecraft /home/nigel/minecraft_server/start.sh

The next thing is not a minecraft helper exactly but it will be useful as a reminder in the future. When a user logs on to the host the message of the day will be displayed to add simple notes to the message we can simply edit the motd with the command
sudo nano /etc/motd

===Adding a second Minecraft server Apple===

Now that we have the basic setup with potential for multiple hosts we will need to create at least one more so that we can prove the proxy works as intended. The next server will be a different version with some mods. As soon as we start adding mods to a Minecraft world they will use more resources so we will need the next host to be a bit better specified.

{| class="wikitable"
|+
|-
! Item !! Value !! Notes
|-
|CPU || 5 ||
|-
|RAM || 12GB ||
|-
|Swap || 16gb || Additional disk allocated from Lexar SSD
|-
|Storage || 150GB || Initially set at 32gb
|-
|Base OS || Debian 13.3 || Server version
|-
|Hostname || Apple||
|-
|IP Address || 192.168.100.35 ||
|}

====Hardware Configuration====

As we did with the cherry host earlier we need to configure the hardware changes that have been made on the basic specification like adding the Lexar HD as the swap file. We must stop using the swap partition on the primary drive so we can move it out of the way. Turn off all swap.
sudo swapoff -a
Since your swap partition (sda3) is at the end of the disk, it acts as a "blocker." We need to delete it and the root partition, then recreate the root partition to fill the entire space.
sudo fdisk /dev/sda
* Type p to print the table (confirming sda2 is root and sda3 is swap).
* Type d then 3 to delete the swap partition.
* Type d then 2 to delete the root partition (Don't worry, the data stays in the blocks).
* Step B: Recreate and Expand
* Type n for a new partition.
* Type p for Primary. Note if disk is using a GPT (GUID Partition Table) there will be no P option, primary partitions only exist in the old MBR style of disks
* Type 2 for Partition number 2.
* Press Enter for the default Start Sector (it must match the old start sector of sda2).
* Press Enter for the default End Sector (this will now jump to the end of the 150GB disk).
* CRITICAL: When it asks "Do you want to remove the signature?", type N.
* Type w to write changes and exit.
Now, reboot to make sure the kernel is looking at the new 150GB table entry.
sudo systemctl reboot
Once you log back in, expand the actual data "container" (the ext4 filesystem) to fill that new partition:
sudo resize2fs /dev/sda2
Now that the main drive is expanded, let's get that high-speed swap set up on your 16GB secondary disk.
sudo mkswap /dev/sdb
sudo swapon /dev/sdb
We need to update /etc/fstab so your VM knows where to find its memory "safety net" on every boot.
sudo nano /etc/fstab
Look for the line that mentions the old swap (it likely mentions sda3 or a long UUID string). Delete that line or put a # at the start of it. Add this new line at the bottom:
/dev/sdb none swap sw 0 0
Save and exit. Then to confirm the changes have been made use the following commands to show the new sda2 disk size and the swap disk
df -h
free -h

====Software installation====

Since Apple is a fresh VM, we need to ensure the underlying Debian OS is fully patched and has the necessary build tools and repositories before we drop a massive modpack into it. Modern modpacks like FTB University rely heavily on Java 21 or Java 25, so we will set that foundation now. First, we refresh the local package index and upgrade any existing system components. Update package lists and upgrade system and install essential utilities for file management and monitoring
sudo apt update && sudo apt upgrade -y
sudo apt install -y htop screen wget curl jq unzip zip
Install Java 25 and verify the version to ensure it's active
sudo apt install -y openjdk-25-jre-headless
java -version
with the JRE installed we can now pull the explicit API endpoint for the FTB University installer. We will use the -JLO flags with curl. This tells it to follow redirections, process headers properly, and save the binary with its true system filename so the metadata doesn't drop.
mkdir ~/ftb_university
cd ~/ftb_university
curl -JLO "https://api.feed-the-beast.com/v1/modpacks/public/modpack/108/latest/server/linux"
When the file finirm ~/ftb_university/serverinstall_108_*shes downloading, it will have a specific auto-generated string name based on the pack ID. Let's make it executable and kick off the automated build process
chmod +x serverinstall_108_*
./serverinstall_108_* --auto
Assuming the automated build script successfully assembled the library trees, we can clear the raw installation binaries to save block space.
rm ~/ftb_university/serverinstall_108_*
We need to generate the basic runtime parameters so the engine treats your backend initialization correctly. We need accept the core EULA agreement before the server can start and Disable Mojang online lookup to yield authentication control to Vangueria.
echo "eula=true" > ~/ftb_university/eula.txt
printf "online-mode=false\nmotd=FTB University Home\nallow-flight=true\nmax-tick-time=180000" > ~/ftb_university/server.properties
We will launch the first server loop. Forge will map out the dimensions and establish the baseline mod settings.
./run.sh
Since this is a clean workspace, the installer script will start downloading the specific runtime libraries. Watch the console scroll past the mod registry logs. Let the text settle completely until it opens up the standard interactive game prompt (>). Once you see that prompt, type stop and hit Enter to close down the thread cleanly. This will finalize our asset paths so we can secure the proxy sync.

Minecraft

2026-05-16T10:58:43Z

Wikisailor: /* Software installation */

Minecraft

2026-05-13T08:21:45Z

Wikisailor: /* Software installation */

==Introduction==

We are to have some Minecraft servers on the '''[[Home Lab]]''''. The general setup will be to have a Velocity server in front several Minecraft host '''[[Virtual Machines]]'''. Velocity works in a similar way to a Nginx reverse proxy whereby Pfsense forwards all Minecraft traffic to the Velocity server including the SNI and Velocity redirects traffic to the required hostname based on the DNS name. Cloudflare does not reverse proxy Minecraft traffic on the free tier and as we do not want to have to deal with random bots from the east so we will not leave the port open on the edge or Pfsense to random bots with port scanners. So we will use grey cloud at Cloudflare but DNS will point to a service like TCPShield and our firewalls only accept Minecraft traffic from their IP addresses and Velocity will only accept named servers and drop any unknown DNS names.

==Installation==

The installation will be in some distinct stages to enable each step to be proved to be working before proceeding to the next stage. First we setup a simple vanilla Minecraft server and set the firewall to port forward to it directly. Once that is proven to be working we will setup a Velocity server that will receive all 25565 traffic and forward it to the working Minecraft host. The next phase after the first host is getting traffic forwarded is to setup a second host and make sure velocity can forward to each, included in this step will be hardening the Velocity server with whatever security measures that it has available. When we are sure that Velocity is working properly we can work on the remote access stage, where we use TCPShield to proxy the service and have Cloudflare DNS only names setup with cherry.seaoffate.net and apple.seaoffate.net etc. From this point forward any new Minecraft servers will simply follow the same setup procedure.

===The First Minecraft Host Configuration===

The first Minecraft host needs to have enough resources to run the JVM and the server but as it just a vanilla server the specification does not need to be excessive. The table shows the highlights.

{| class="wikitable"
|+
|-
! Item !! Value !! Notes
|-
|CPU || 2 ||
|-
|RAM || 4GB ||
|-
|Swap || 16gb || Additional disk allocated from Lexar SSD
|-
|Storage || 96GB || Initially set at 32gb
|-
|Base OS || Debian 13.3 || Server version
|-
|Hostname || Cherry ||
|-
|IP Address || 192.168.100.30 ||
|}

====Hardware Configuration====
The Cherry host was created as a clone of the Debian template and then the basic specifications were improved so we will need to configure these extra items in the OS. First we need to identify the harddrive to use as the swap file
lsblk
The result is likely to show that the disk is likely to be /dev/sdb so we can set the swap space and enable it with
sudo mkswap /dev/sdb
sudo swapon /dev/sdb
To make the swap file persistent we edit the fstab
sudo nano /etc/fstab
Add the line:
/dev/sdb none swap sw 0 0
and remove or comment out the line that refers to
/dev/sda3
Before the storage sda main partition can be expanded to the full 96GB we have to remove the swap that is in the way so disable the existing swap with
sudo swapoff /dev/sda3
Open the disk utility to modify sda
sudo fdisk /dev/sda
Delete the swap partition with the option d, then type 3 to delete partition 3, then w to save and exit. The next thing to do is expand the Primary Root Partition so open fdisk again:
sudo fdisk /dev/sda
Delete the root partition:
* Type d (Delete)
* Type 2 (this only deletes the table entry, not the data).
* Type n (Create a new partition)
* Type p (Primary Partition)
* Type 2 (For Partition number 2)
* Type enter (Use default values for start sector)
* Type enter (Use default values for end sectors to fill the 96GB)
* CRITICAL: When asked if you want to remove the signature, type N.
* Type w (Save and exit)
To finalize Storage reboot to refresh the kernel partition table:
sudo systemctl reboot
When the VM reboots expand the filesystem into the new space:
sudo resize2fs /dev/sda2
We can verify the new swap and new sda size with
df -h
Now that the hardware is setup and configured we can proceed to the software installation

====Software Installation====

The software installation consists of updates, install the JVM and then install the Minecraft server. So to start as we do on most hosts with updates
sudo apt update
sudo apt upgrade
Install Necessary Utilities:
sudo apt install htop screen wget curl -y
Install Java 25:
sudo apt install openjdk-25-jre-headless -y
Verify Java Installation (Ensure it reports OpenJDK 25)
java -version
Now we install the Minecraft server

Create the Server Directory:
mkdir ~/minecraft_server && cd ~/minecraft_server
Download the Server Software:
wget -O server.jar [https://piston-data.mojang.com/v1/objects/97ccd4c0ed3f81bbb7bfacddd1090b0c56f9bc51/server.jar](https://piston-data.mojang.com/v1/objects/97ccd4c0ed3f81bbb7bfacddd1090b0c56f9bc51/server.jar)
Assuming the file downloaded we need an initial run to generate the file:
java -Xms1G -Xmx1G -jar server.jar nogui
When the file is first created it will not run until we Accept the EULA with the command:
sed -i 's/eula=false/eula=true/' eula.txt
We can create the Start Script:
nano start.sh
Paste in the following
<nowiki> #!/bin/bash
while true
do
echo "--- Starting Minecraft Server ---"
java -Xms3G -Xmx3G \
--enable-native-access=ALL-UNNAMED \
-XX:+UseG1GC \
-XX:MaxGCPauseMillis=200 \
-XX:+UnlockExperimentalVMOptions \
-XX:+DisableExplicitGC \
-XX:+AlwaysPreTouch \
-jar server.jar nogui
echo "--- Server stopped. Restarting in 5 seconds (Ctrl+C to cancel) ---"
sleep 5
done</nowiki>
Set the script to execute with
chmod +x start.sh
We can start the server with
./start.sh
'''Note''' we can type the command stop in the terminal and the server will save the world and stop it for 5 seconds during the 5 seconds, if we type ctrl+c it will end the script or if we just leave it the server will restart.

====Enable External Access====

We will need to access the server from outside world so we should forward the Minecraft port 25565 to the IP address of cherry. To make the port forward rules in Pfsense easier to understand we add an alias for cherry's IP address and a port alias for 25565. We add a port forward rule to Pfsense that says source IP 192.168.0.0/16 and any port, destination this firewall (self) Destination port Minecraft_standard, redirect IP_cherry port Minecraft_standard.

====Testing====

With this configuration loading a Minecraft client and setting the destination server to the WAN port IP address it will connect to the cherry host.

As part of the wider LAN setup we added a Adguard LXC to manage DNS. Part of the Adguard configuration was made to avoid the hairpin network access so a DNS redirect was made to forward *.seaoffate.net to Pfsense WAN and as the default domain name was set to seaoffate.net. So now when we have a destination of cherry Adguard will translate the hostname to cherry.seaoffate.net and redirect it to Pfsense, Pfsense will then forward to the relevant server. If that does not work as expected the next test would be to set the destination to cherry.seaoffate.net which should be redirected by Adguard.

===Velocity Installation===

The Velocity server VM does not need to be especially high because all it needs to do is accept connections and forward them on to the relevant host and any associated functions like handle logon, bans and etc. Unlike the cherry host that we just setup the base specification from the Debian template needs to be cut down a bit and does not need a extra swap file or anything special.

{| class="wikitable"
|+
|-
! Item !! Value !! Notes
|-
|CPU || 1 ||
|-
|RAM || 1GB ||
|-
|Storage || 32GB ||
|-
|Base OS || Debian 13.3 || Server version
|-
|Hostname || Vangueria ||
|-
|IP Address || 192.168.100.29 ||
|}
====Software Installation====

As there is no additions to the VM's specification there is no hardware to configure so we can get straight to the software installation. So the well known update/upgrade and the packages can be installed with
sudo apt update && sudo apt upgrade -y
sudo apt install -y openjdk-25-jre-headless htop screen wget jq curl
Once the dependencies are installed, we create a dedicated application directory and use an automated script to identify the most recent build of Velocity 3.4.0. This ensures we are not relying on hardcoded links that may expire.
mkdir ~/velocity && cd ~/velocity
export PROJECT="velocity"
export VERSION="3.4.0-SNAPSHOT"
export LATEST_BUILD=$(curl -s https://api.papermc.io/v2/projects/${PROJECT}/versions/${VERSION} | jq '.builds[-1]')
wget -O ~/velocity/velocity.jar "https://api.papermc.io/v2/projects/${PROJECT}/versions/${VERSION}/builds/${LATEST_BUILD}/downloads/${PROJECT}-${VERSION}-${LATEST_BUILD}.jar"
The initial boot of Velocity is performed to generate the necessary configuration files. We launch it with a 512MB heap size and then shut it down gracefully using the end command once the prompt appears.
java -Xms512M -Xmx512M -jar velocity.jar

====Proxy Configuration and Routing====

The primary configuration for the proxy is handled within the velocity.toml file. This file dictates how the proxy listens for incoming traffic and how it maps domain names to internal IP addresses. We edit this file to ensure the proxy is listening on all interfaces and that it is using the modern forwarding protocol.
nano ~/velocity/velocity.toml
Modify these specific lines:
* Bind Address: bind = "0.0.0.0:25565" (Allows it to hear traffic from pfSense).
* Forwarding Mode: player-info-forwarding-mode = "modern" (This is the most secure protocol for 2026).
* ping-passthrough should be set to ALL. This is to ensure the server list on the Minecraft client correctly displays the status and version of the backend servers
* Server List: Scroll down to the [servers] section:
<nowiki>[servers]
cherry = "192.168.100.30:25565"
apple = "192.168.100.35:25565"

[servers]
try = [
"cherry"
]</nowiki>
* Forced Hosts: This tells the proxy which server to pick based on the URL the player typed:
<nowiki>[forced-hosts]
"cherry.seaoffate.net" = ["cherry"]
"apple.seaoffate.net" = ["apple"]</nowiki>
Save and close the file. next we need a start.sh file for Velocity
nano ~/velocity/start.sh
copy the following into the file
<nowiki> #!/bin/bash
while true
do
echo "--- Starting Vangueria Proxy ---"
java -Xms512M -Xmx512M \
-XX:+UseG1GC \
-XX:MaxGCPauseMillis=200 \
-XX:+UnlockExperimentalVMOptions \
-XX:+DisableExplicitGC \
-XX:+AlwaysPreTouch \
-jar velocity.jar
echo "--- Proxy stopped. Restarting in 5s ---"
sleep 5
done</nowiki>
To make the script executable
chmod +x ~/velocity/start.sh
At this point the since Vangueria is now set to Modern Forwarding, Cherry will reject all connections until it has the forwarding.secret. the secret can be obtained with the command
cat ~/velocity/forwarding.secret
Copy the code to a safe location because we will need it to setup cherry (and apple). then we should be able to finally start the proxy with the start.sh
./start.sh
Now we move to cherry to setup it's ability to receive connections from Vangueria.

====Configuring Cherry To Accept Proxied Connections====

To complete the integration between the proxy and the backend, Cherry must be transitioned from a standalone Vanilla server to a "Proxy-Aware" host. Because Vanilla Minecraft does not natively support Velocity’s Modern Forwarding (the security handshake), we use the Fabric Loader as a lightweight wrapper. This allows us to install a bridge mod that validates the secret key without changing the gameplay experience.The transition of Cherry involves three main phases: installing the Fabric environment, adding the bridge mods, and configuring the security handshake to match Vangueria.

First, we must stop the existing server and install the Fabric transition layer. This replaces the standard Mojang launcher with a version capable of loading the security bridge. We need to download the Fabric Installer and then Install Fabric for the 1.21.1 environment.
cd ~/minecraft_server
wget https://maven.fabricmc.net/net/fabricmc/fabric-installer/1.0.1/fabric-installer-1.0.1.jar
java -jar fabric-installer-1.0.1.jar server -mcversion 1.21.1 -downloadMinecraft
Once complete, the installer will have created a new file named fabric-server-launch.jar. This is now the primary entry point for the server.

To install the Security Bridge we require two specific components in the mods folder: the Fabric API (the library that allows mods to interact with the game engine) and FabricProxy-Lite (the specific mod that handles the Velocity secret key). It is vital to use version-matched JARs for 1.21.1 to ensure stability.
mkdir -p ~/minecraft_server/mods
wget -O ~/minecraft_server/mods/FabricProxy-Lite.jar https://github.com/OKTW-Network/FabricProxy-Lite/releases/download/v2.10.1/FabricProxy-Lite-2.10.1.jar
wget -O ~/minecraft_server/mods/fabric-api.jar https://github.com/FabricMC/fabric-api/releases/download/0.116.11%2B1.21.1/fabric-api-0.116.11+1.21.1.jar

To configure the handshake after placing the mods, we must run the server once to generate the configuration structure, then shut it down to inject the secret.
Update start.sh to point to fabric-server-launch.jar instead of server.jar
sed -i 's/server.jar/fabric-server-launch.jar/' start.sh
Initial run to generate config (Type 'stop' once the 'Done' message appears)
./start.sh
Now, we create the configuration file and link it to Vangueria. This is where we ensure the backend only trusts traffic coming from our proxy.
mkdir -p ~/minecraft_server/config
nano ~/minecraft_server/config/FabricProxy-Lite.toml
Paste the following configuration into the file, ensuring the secret matches the one obtained from Vangueria:
enabled = true
hackOnlineMode = true
secret = "PASTE_YOUR_VANGUERIA_SECRET_HERE"
The final step is to adjust the server.properties file. Because Vangueria handles the official Mojang authentication at the "front door," the backend server must be set to offline mode to allow the proxy to pass the authenticated user data through.
sed -i 's/online-mode=true/online-mode=false/' server.properties
With the configuration complete, the server should be launched inside a named screen session to ensure it remains active.
screen -S minecraft ./start.sh
We should now change the Pfsense port forward rule to forward traffic to the 192.168.100.29 (IP address of Vangueria) and then connecting a client from a laptop outside of Pfsense and using the address cherry.seaoffate.net, we can try using the IP address of the Pfsense WAN port but it may not work (if the default server is set to cherry it may connect)

===Additional Options===

There are a few additional considerations that will make the servers run more reliably. The first is thing that needs to be done is to run the server in a screen so that there does not need to be a SSH session to be running. The following will start a screen called minecraft and will execute the start.sh command.
screen -S minecraft ./start
To exit the minecraft screen and return to the main SSH type ctrl + a and then d, the minecraft screen can be reloaded with the command
screen -r minecraft
The next thing that we will need to do is to have the minecraft server start whenever the host reboots. So we need to add a cron tab to the start.sh
crontab -e
Select nano if asked then add the line
@reboot screen -dmS minecraft /home/nigel/minecraft_server/start.sh

The next thing is not a minecraft helper exactly but it will be useful as a reminder in the future. When a user logs on to the host the message of the day will be displayed to add simple notes to the message we can simply edit the motd with the command
sudo nano /etc/motd

===Adding a second Minecraft server Apple===

Now that we have the basic setup with potential for multiple hosts we will need to create at least one more so that we can prove the proxy works as intended. The next server will be a different version with some mods. As soon as we start adding mods to a Minecraft world they will use more resources so we will need the next host to be a bit better specified.

{| class="wikitable"
|+
|-
! Item !! Value !! Notes
|-
|CPU || 5 ||
|-
|RAM || 12GB ||
|-
|Swap || 16gb || Additional disk allocated from Lexar SSD
|-
|Storage || 150GB || Initially set at 32gb
|-
|Base OS || Debian 13.3 || Server version
|-
|Hostname || Apple||
|-
|IP Address || 192.168.100.35 ||
|}

====Hardware Configuration====

As we did with the cherry host earlier we need to configure the hardware changes that have been made on the basic specification like adding the Lexar HD as the swap file. We must stop using the swap partition on the primary drive so we can move it out of the way. Turn off all swap.
sudo swapoff -a
Since your swap partition (sda3) is at the end of the disk, it acts as a "blocker." We need to delete it and the root partition, then recreate the root partition to fill the entire space.
sudo fdisk /dev/sda
* Type p to print the table (confirming sda2 is root and sda3 is swap).
* Type d then 3 to delete the swap partition.
* Type d then 2 to delete the root partition (Don't worry, the data stays in the blocks).
* Step B: Recreate and Expand
* Type n for a new partition.
* Type p for Primary. Note if disk is using a GPT (GUID Partition Table) there will be no P option, primary partitions only exist in the old MBR style of disks
* Type 2 for Partition number 2.
* Press Enter for the default Start Sector (it must match the old start sector of sda2).
* Press Enter for the default End Sector (this will now jump to the end of the 150GB disk).
* CRITICAL: When it asks "Do you want to remove the signature?", type N.
* Type w to write changes and exit.
Now, reboot to make sure the kernel is looking at the new 150GB table entry.
sudo systemctl reboot
Once you log back in, expand the actual data "container" (the ext4 filesystem) to fill that new partition:
sudo resize2fs /dev/sda2
Now that the main drive is expanded, let's get that high-speed swap set up on your 16GB secondary disk.
sudo mkswap /dev/sdb
sudo swapon /dev/sdb
We need to update /etc/fstab so your VM knows where to find its memory "safety net" on every boot.
sudo nano /etc/fstab
Look for the line that mentions the old swap (it likely mentions sda3 or a long UUID string). Delete that line or put a # at the start of it. Add this new line at the bottom:
/dev/sdb none swap sw 0 0
Save and exit. Then to confirm the changes have been made use the following commands to show the new sda2 disk size and the swap disk
df -h
free -h

====Software installation====

Since Apple is a fresh VM, we need to ensure the underlying Debian OS is fully patched and has the necessary build tools and repositories before we drop a massive modpack into it. Modern modpacks like ATM10 (Minecraft 1.21.1) rely heavily on Java 21 or Java 25, so we will set that foundation now. First, we refresh the local package index and upgrade any existing system components. Update package lists and upgrade system and install essential utilities for file management and monitoring
sudo apt update && sudo apt upgrade -y
sudo apt install -y htop screen wget curl jq unzip zip
Install Java 25 and verify the version to ensure it's active
sudo apt install -y openjdk-25-jre-headless
java -version
Now that the system is ready, we can create the home for Apple. Create the Modpack Directory
mkdir ~/atm_server && cd ~/atm_server
We now need the server file ServerFiles-6.6.zip but it would appear that the curseforge website don't allow wget downloads so the best way to get the file is to download via http and scp it to the atm-server directory. When the .zip file is in the atm directory we unzip it
unzip ServerFiles-6.6.zip
Make the installer executable
chmod +x startserver.sh
Run the installer
./startserver.sh
Wait for completion: This will download the NeoForge runtime libraries. Once it finishes, it will usually create a run.sh or simply exit back to the prompt after preparing the environment. Immediately after it finishes, we need to apply the "tried and tested" security and performance settings. Note that it may have to be stopped and then do a ctrl + c to close it completely so we can accept the eula.
sed -i 's/eula=false/eula=true/' eula.txt
The final Steps to get Apple Online now that you have accepted the EULA, follow these final steps to link it to Vangueria and give it the power it needs.

Set the Memory (Critical for ATM10)
If you don't do this, the server will try to run on 2GB or 4GB and will crash during world generation.
nano ~/atm_server/user_jvm_args.txt
Find the memory lines and change them to 10G (leaving 2GB for Debian):
-Xms10G
-Xmx10G
Save and exit. Since we have already unzipped the files, the bridge mod is already in the mods folder, but we need to give Apple the "password" to trust Vangueria. Create the secret file and paste your Vangueria secret string
nano ~/atm_server/forwarding.secret
Save and close. Next we disable Online Mode
sed -i 's/online-mode=true/online-mode=false/' ~/atm_server/server.properties
We are now ready to launch the Beast. Start it in a named screen. Be patient: ATM10 will take 5 to 10 minutes to boot the first time while it processes those ~500 mods.
screen -S apple ./startserver.sh
to prove that it works we will have connect a client. The goo news is that there should be no extra configuration to manage because the traffic is just being redirected from Vangueria like cherry.

To keep the Apple server automated and robust, you need a string that launches a detached screen session immediately upon the VM booting up. On the Apple VM, run:
crontab -e
Scroll to the very bottom of the file and paste this exact string:
@reboot screen -dmS apple /home/nigel/atm_server/startserver.sh

Minecraft

2026-05-12T22:37:35Z

Wikisailor: /* Software installation */

==Introduction==

We are to have some Minecraft servers on the '''[[Home Lab]]''''. The general setup will be to have a Velocity server in front several Minecraft host '''[[Virtual Machines]]'''. Velocity works in a similar way to a Nginx reverse proxy whereby Pfsense forwards all Minecraft traffic to the Velocity server including the SNI and Velocity redirects traffic to the required hostname based on the DNS name. Cloudflare does not reverse proxy Minecraft traffic on the free tier and as we do not want to have to deal with random bots from the east so we will not leave the port open on the edge or Pfsense to random bots with port scanners. So we will use grey cloud at Cloudflare but DNS will point to a service like TCPShield and our firewalls only accept Minecraft traffic from their IP addresses and Velocity will only accept named servers and drop any unknown DNS names.

==Installation==

The installation will be in some distinct stages to enable each step to be proved to be working before proceeding to the next stage. First we setup a simple vanilla Minecraft server and set the firewall to port forward to it directly. Once that is proven to be working we will setup a Velocity server that will receive all 25565 traffic and forward it to the working Minecraft host. The next phase after the first host is getting traffic forwarded is to setup a second host and make sure velocity can forward to each, included in this step will be hardening the Velocity server with whatever security measures that it has available. When we are sure that Velocity is working properly we can work on the remote access stage, where we use TCPShield to proxy the service and have Cloudflare DNS only names setup with cherry.seaoffate.net and apple.seaoffate.net etc. From this point forward any new Minecraft servers will simply follow the same setup procedure.

===The First Minecraft Host Configuration===

The first Minecraft host needs to have enough resources to run the JVM and the server but as it just a vanilla server the specification does not need to be excessive. The table shows the highlights.

{| class="wikitable"
|+
|-
! Item !! Value !! Notes
|-
|CPU || 2 ||
|-
|RAM || 4GB ||
|-
|Swap || 16gb || Additional disk allocated from Lexar SSD
|-
|Storage || 96GB || Initially set at 32gb
|-
|Base OS || Debian 13.3 || Server version
|-
|Hostname || Cherry ||
|-
|IP Address || 192.168.100.30 ||
|}

====Hardware Configuration====
The Cherry host was created as a clone of the Debian template and then the basic specifications were improved so we will need to configure these extra items in the OS. First we need to identify the harddrive to use as the swap file
lsblk
The result is likely to show that the disk is likely to be /dev/sdb so we can set the swap space and enable it with
sudo mkswap /dev/sdb
sudo swapon /dev/sdb
To make the swap file persistent we edit the fstab
sudo nano /etc/fstab
Add the line:
/dev/sdb none swap sw 0 0
and remove or comment out the line that refers to
/dev/sda3
Before the storage sda main partition can be expanded to the full 96GB we have to remove the swap that is in the way so disable the existing swap with
sudo swapoff /dev/sda3
Open the disk utility to modify sda
sudo fdisk /dev/sda
Delete the swap partition with the option d, then type 3 to delete partition 3, then w to save and exit. The next thing to do is expand the Primary Root Partition so open fdisk again:
sudo fdisk /dev/sda
Delete the root partition:
* Type d (Delete)
* Type 2 (this only deletes the table entry, not the data).
* Type n (Create a new partition)
* Type p (Primary Partition)
* Type 2 (For Partition number 2)
* Type enter (Use default values for start sector)
* Type enter (Use default values for end sectors to fill the 96GB)
* CRITICAL: When asked if you want to remove the signature, type N.
* Type w (Save and exit)
To finalize Storage reboot to refresh the kernel partition table:
sudo systemctl reboot
When the VM reboots expand the filesystem into the new space:
sudo resize2fs /dev/sda2
We can verify the new swap and new sda size with
df -h
Now that the hardware is setup and configured we can proceed to the software installation

====Software Installation====

The software installation consists of updates, install the JVM and then install the Minecraft server. So to start as we do on most hosts with updates
sudo apt update
sudo apt upgrade
Install Necessary Utilities:
sudo apt install htop screen wget curl -y
Install Java 25:
sudo apt install openjdk-25-jre-headless -y
Verify Java Installation (Ensure it reports OpenJDK 25)
java -version
Now we install the Minecraft server

Create the Server Directory:
mkdir ~/minecraft_server && cd ~/minecraft_server
Download the Server Software:
wget -O server.jar [https://piston-data.mojang.com/v1/objects/97ccd4c0ed3f81bbb7bfacddd1090b0c56f9bc51/server.jar](https://piston-data.mojang.com/v1/objects/97ccd4c0ed3f81bbb7bfacddd1090b0c56f9bc51/server.jar)
Assuming the file downloaded we need an initial run to generate the file:
java -Xms1G -Xmx1G -jar server.jar nogui
When the file is first created it will not run until we Accept the EULA with the command:
sed -i 's/eula=false/eula=true/' eula.txt
We can create the Start Script:
nano start.sh
Paste in the following
<nowiki> #!/bin/bash
while true
do
echo "--- Starting Minecraft Server ---"
java -Xms3G -Xmx3G \
--enable-native-access=ALL-UNNAMED \
-XX:+UseG1GC \
-XX:MaxGCPauseMillis=200 \
-XX:+UnlockExperimentalVMOptions \
-XX:+DisableExplicitGC \
-XX:+AlwaysPreTouch \
-jar server.jar nogui
echo "--- Server stopped. Restarting in 5 seconds (Ctrl+C to cancel) ---"
sleep 5
done</nowiki>
Set the script to execute with
chmod +x start.sh
We can start the server with
./start.sh
'''Note''' we can type the command stop in the terminal and the server will save the world and stop it for 5 seconds during the 5 seconds, if we type ctrl+c it will end the script or if we just leave it the server will restart.

====Enable External Access====

We will need to access the server from outside world so we should forward the Minecraft port 25565 to the IP address of cherry. To make the port forward rules in Pfsense easier to understand we add an alias for cherry's IP address and a port alias for 25565. We add a port forward rule to Pfsense that says source IP 192.168.0.0/16 and any port, destination this firewall (self) Destination port Minecraft_standard, redirect IP_cherry port Minecraft_standard.

====Testing====

With this configuration loading a Minecraft client and setting the destination server to the WAN port IP address it will connect to the cherry host.

As part of the wider LAN setup we added a Adguard LXC to manage DNS. Part of the Adguard configuration was made to avoid the hairpin network access so a DNS redirect was made to forward *.seaoffate.net to Pfsense WAN and as the default domain name was set to seaoffate.net. So now when we have a destination of cherry Adguard will translate the hostname to cherry.seaoffate.net and redirect it to Pfsense, Pfsense will then forward to the relevant server. If that does not work as expected the next test would be to set the destination to cherry.seaoffate.net which should be redirected by Adguard.

===Velocity Installation===

The Velocity server VM does not need to be especially high because all it needs to do is accept connections and forward them on to the relevant host and any associated functions like handle logon, bans and etc. Unlike the cherry host that we just setup the base specification from the Debian template needs to be cut down a bit and does not need a extra swap file or anything special.

{| class="wikitable"
|+
|-
! Item !! Value !! Notes
|-
|CPU || 1 ||
|-
|RAM || 1GB ||
|-
|Storage || 32GB ||
|-
|Base OS || Debian 13.3 || Server version
|-
|Hostname || Vangueria ||
|-
|IP Address || 192.168.100.29 ||
|}
====Software Installation====

As there is no additions to the VM's specification there is no hardware to configure so we can get straight to the software installation. So the well known update/upgrade and the packages can be installed with
sudo apt update && sudo apt upgrade -y
sudo apt install -y openjdk-25-jre-headless htop screen wget jq curl
Once the dependencies are installed, we create a dedicated application directory and use an automated script to identify the most recent build of Velocity 3.4.0. This ensures we are not relying on hardcoded links that may expire.
mkdir ~/velocity && cd ~/velocity
export PROJECT="velocity"
export VERSION="3.4.0-SNAPSHOT"
export LATEST_BUILD=$(curl -s https://api.papermc.io/v2/projects/${PROJECT}/versions/${VERSION} | jq '.builds[-1]')
wget -O ~/velocity/velocity.jar "https://api.papermc.io/v2/projects/${PROJECT}/versions/${VERSION}/builds/${LATEST_BUILD}/downloads/${PROJECT}-${VERSION}-${LATEST_BUILD}.jar"
The initial boot of Velocity is performed to generate the necessary configuration files. We launch it with a 512MB heap size and then shut it down gracefully using the end command once the prompt appears.
java -Xms512M -Xmx512M -jar velocity.jar

====Proxy Configuration and Routing====

The primary configuration for the proxy is handled within the velocity.toml file. This file dictates how the proxy listens for incoming traffic and how it maps domain names to internal IP addresses. We edit this file to ensure the proxy is listening on all interfaces and that it is using the modern forwarding protocol.
nano ~/velocity/velocity.toml
Modify these specific lines:
* Bind Address: bind = "0.0.0.0:25565" (Allows it to hear traffic from pfSense).
* Forwarding Mode: player-info-forwarding-mode = "modern" (This is the most secure protocol for 2026).
* ping-passthrough should be set to ALL. This is to ensure the server list on the Minecraft client correctly displays the status and version of the backend servers
* Server List: Scroll down to the [servers] section:
<nowiki>[servers]
cherry = "192.168.100.30:25565"
apple = "192.168.100.35:25565"

[servers]
try = [
"cherry"
]</nowiki>
* Forced Hosts: This tells the proxy which server to pick based on the URL the player typed:
<nowiki>[forced-hosts]
"cherry.seaoffate.net" = ["cherry"]
"apple.seaoffate.net" = ["apple"]</nowiki>
Save and close the file. next we need a start.sh file for Velocity
nano ~/velocity/start.sh
copy the following into the file
<nowiki> #!/bin/bash
while true
do
echo "--- Starting Vangueria Proxy ---"
java -Xms512M -Xmx512M \
-XX:+UseG1GC \
-XX:MaxGCPauseMillis=200 \
-XX:+UnlockExperimentalVMOptions \
-XX:+DisableExplicitGC \
-XX:+AlwaysPreTouch \
-jar velocity.jar
echo "--- Proxy stopped. Restarting in 5s ---"
sleep 5
done</nowiki>
To make the script executable
chmod +x ~/velocity/start.sh
At this point the since Vangueria is now set to Modern Forwarding, Cherry will reject all connections until it has the forwarding.secret. the secret can be obtained with the command
cat ~/velocity/forwarding.secret
Copy the code to a safe location because we will need it to setup cherry (and apple). then we should be able to finally start the proxy with the start.sh
./start.sh
Now we move to cherry to setup it's ability to receive connections from Vangueria.

====Configuring Cherry To Accept Proxied Connections====

To complete the integration between the proxy and the backend, Cherry must be transitioned from a standalone Vanilla server to a "Proxy-Aware" host. Because Vanilla Minecraft does not natively support Velocity’s Modern Forwarding (the security handshake), we use the Fabric Loader as a lightweight wrapper. This allows us to install a bridge mod that validates the secret key without changing the gameplay experience.The transition of Cherry involves three main phases: installing the Fabric environment, adding the bridge mods, and configuring the security handshake to match Vangueria.

First, we must stop the existing server and install the Fabric transition layer. This replaces the standard Mojang launcher with a version capable of loading the security bridge. We need to download the Fabric Installer and then Install Fabric for the 1.21.1 environment.
cd ~/minecraft_server
wget https://maven.fabricmc.net/net/fabricmc/fabric-installer/1.0.1/fabric-installer-1.0.1.jar
java -jar fabric-installer-1.0.1.jar server -mcversion 1.21.1 -downloadMinecraft
Once complete, the installer will have created a new file named fabric-server-launch.jar. This is now the primary entry point for the server.

To install the Security Bridge we require two specific components in the mods folder: the Fabric API (the library that allows mods to interact with the game engine) and FabricProxy-Lite (the specific mod that handles the Velocity secret key). It is vital to use version-matched JARs for 1.21.1 to ensure stability.
mkdir -p ~/minecraft_server/mods
wget -O ~/minecraft_server/mods/FabricProxy-Lite.jar https://github.com/OKTW-Network/FabricProxy-Lite/releases/download/v2.10.1/FabricProxy-Lite-2.10.1.jar
wget -O ~/minecraft_server/mods/fabric-api.jar https://github.com/FabricMC/fabric-api/releases/download/0.116.11%2B1.21.1/fabric-api-0.116.11+1.21.1.jar

To configure the handshake after placing the mods, we must run the server once to generate the configuration structure, then shut it down to inject the secret.
Update start.sh to point to fabric-server-launch.jar instead of server.jar
sed -i 's/server.jar/fabric-server-launch.jar/' start.sh
Initial run to generate config (Type 'stop' once the 'Done' message appears)
./start.sh
Now, we create the configuration file and link it to Vangueria. This is where we ensure the backend only trusts traffic coming from our proxy.
mkdir -p ~/minecraft_server/config
nano ~/minecraft_server/config/FabricProxy-Lite.toml
Paste the following configuration into the file, ensuring the secret matches the one obtained from Vangueria:
enabled = true
hackOnlineMode = true
secret = "PASTE_YOUR_VANGUERIA_SECRET_HERE"
The final step is to adjust the server.properties file. Because Vangueria handles the official Mojang authentication at the "front door," the backend server must be set to offline mode to allow the proxy to pass the authenticated user data through.
sed -i 's/online-mode=true/online-mode=false/' server.properties
With the configuration complete, the server should be launched inside a named screen session to ensure it remains active.
screen -S minecraft ./start.sh
We should now change the Pfsense port forward rule to forward traffic to the 192.168.100.29 (IP address of Vangueria) and then connecting a client from a laptop outside of Pfsense and using the address cherry.seaoffate.net, we can try using the IP address of the Pfsense WAN port but it may not work (if the default server is set to cherry it may connect)

===Additional Options===

There are a few additional considerations that will make the servers run more reliably. The first is thing that needs to be done is to run the server in a screen so that there does not need to be a SSH session to be running. The following will start a screen called minecraft and will execute the start.sh command.
screen -S minecraft ./start
To exit the minecraft screen and return to the main SSH type ctrl + a and then d, the minecraft screen can be reloaded with the command
screen -r minecraft
The next thing that we will need to do is to have the minecraft server start whenever the host reboots. So we need to add a cron tab to the start.sh
crontab -e
Select nano if asked then add the line
@reboot screen -dmS minecraft /home/nigel/minecraft_server/start.sh

The next thing is not a minecraft helper exactly but it will be useful as a reminder in the future. When a user logs on to the host the message of the day will be displayed to add simple notes to the message we can simply edit the motd with the command
sudo nano /etc/motd

===Adding a second Minecraft server Apple===

Now that we have the basic setup with potential for multiple hosts we will need to create at least one more so that we can prove the proxy works as intended. The next server will be a different version with some mods. As soon as we start adding mods to a Minecraft world they will use more resources so we will need the next host to be a bit better specified.

{| class="wikitable"
|+
|-
! Item !! Value !! Notes
|-
|CPU || 5 ||
|-
|RAM || 12GB ||
|-
|Swap || 16gb || Additional disk allocated from Lexar SSD
|-
|Storage || 150GB || Initially set at 32gb
|-
|Base OS || Debian 13.3 || Server version
|-
|Hostname || Apple||
|-
|IP Address || 192.168.100.35 ||
|}

====Hardware Configuration====

As we did with the cherry host earlier we need to configure the hardware changes that have been made on the basic specification like adding the Lexar HD as the swap file. We must stop using the swap partition on the primary drive so we can move it out of the way. Turn off all swap.
sudo swapoff -a
Since your swap partition (sda3) is at the end of the disk, it acts as a "blocker." We need to delete it and the root partition, then recreate the root partition to fill the entire space.
sudo fdisk /dev/sda
* Type p to print the table (confirming sda2 is root and sda3 is swap).
* Type d then 3 to delete the swap partition.
* Type d then 2 to delete the root partition (Don't worry, the data stays in the blocks).
* Step B: Recreate and Expand
* Type n for a new partition.
* Type p for Primary. Note if disk is using a GPT (GUID Partition Table) there will be no P option, primary partitions only exist in the old MBR style of disks
* Type 2 for Partition number 2.
* Press Enter for the default Start Sector (it must match the old start sector of sda2).
* Press Enter for the default End Sector (this will now jump to the end of the 150GB disk).
* CRITICAL: When it asks "Do you want to remove the signature?", type N.
* Type w to write changes and exit.
Now, reboot to make sure the kernel is looking at the new 150GB table entry.
sudo systemctl reboot
Once you log back in, expand the actual data "container" (the ext4 filesystem) to fill that new partition:
sudo resize2fs /dev/sda2
Now that the main drive is expanded, let's get that high-speed swap set up on your 16GB secondary disk.
sudo mkswap /dev/sdb
sudo swapon /dev/sdb
We need to update /etc/fstab so your VM knows where to find its memory "safety net" on every boot.
sudo nano /etc/fstab
Look for the line that mentions the old swap (it likely mentions sda3 or a long UUID string). Delete that line or put a # at the start of it. Add this new line at the bottom:
/dev/sdb none swap sw 0 0
Save and exit. Then to confirm the changes have been made use the following commands to show the new sda2 disk size and the swap disk
df -h
free -h

====Software installation====

Since Apple is a fresh VM, we need to ensure the underlying Debian OS is fully patched and has the necessary build tools and repositories before we drop a massive modpack into it. Modern modpacks like ATM10 (Minecraft 1.21.1) rely heavily on Java 21 or Java 25, so we will set that foundation now. First, we refresh the local package index and upgrade any existing system components. Update package lists and upgrade system and install essential utilities for file management and monitoring
sudo apt update && sudo apt upgrade -y
sudo apt install -y htop screen wget curl jq unzip zip
Install Java 25 and verify the version to ensure it's active
sudo apt install -y openjdk-25-jre-headless
java -version
Now that the system is ready, we can create the home for Apple. Create the Modpack Directory
mkdir ~/atm_server && cd ~/atm_server
We now need the server file ServerFiles-6.6.zip but it would appear that the curseforge website don't allow wget downloads so the best way to get the file is to download via http and scp it to the atm-server directory. When the .zip file is in the atm directory we unzip it
unzip ServerFiles-6.6.zip
Make the installer executable
chmod +x startserver.sh
Run the installer
./startserver.sh
Wait for completion: This will download the NeoForge runtime libraries. Once it finishes, it will usually create a run.sh or simply exit back to the prompt after preparing the environment. Immediately after it finishes, we need to apply the "tried and tested" security and performance settings. Note that it may have to be stopped and then do a ctrl + c to close it completely so we can accept the eula.
sed -i 's/eula=false/eula=true/' eula.txt
The final Steps to get Apple Online now that you have accepted the EULA, follow these final steps to link it to Vangueria and give it the power it needs.

Set the Memory (Critical for ATM10)
If you don't do this, the server will try to run on 2GB or 4GB and will crash during world generation.
nano ~/atm_server/user_jvm_args.txt
Find the memory lines and change them to 10G (leaving 2GB for Debian):
-Xms10G
-Xmx10G
Save and exit. Since we have already unzipped the files, the bridge mod is already in the mods folder, but we need to give Apple the "password" to trust Vangueria. Create the secret file and paste your Vangueria secret string
nano ~/atm_server/forwarding.secret
Save and close. Next we disable Online Mode
sed -i 's/online-mode=true/online-mode=false/' ~/atm_server/server.properties
We are now ready to launch the Beast. Start it in a named screen. Be patient: ATM10 will take 5 to 10 minutes to boot the first time while it processes those ~500 mods.
screen -S apple ./startserver.sh
to prove that it works we will have connect a client. The goo news is that there should be no extra configuration to manage because the traffic is just being redirected from Vangueria like cherry.

Minecraft

2026-05-12T21:57:33Z

Wikisailor: /* Adding a second Minecraft server Apple */

==Introduction==

We are to have some Minecraft servers on the '''[[Home Lab]]''''. The general setup will be to have a Velocity server in front several Minecraft host '''[[Virtual Machines]]'''. Velocity works in a similar way to a Nginx reverse proxy whereby Pfsense forwards all Minecraft traffic to the Velocity server including the SNI and Velocity redirects traffic to the required hostname based on the DNS name. Cloudflare does not reverse proxy Minecraft traffic on the free tier and as we do not want to have to deal with random bots from the east so we will not leave the port open on the edge or Pfsense to random bots with port scanners. So we will use grey cloud at Cloudflare but DNS will point to a service like TCPShield and our firewalls only accept Minecraft traffic from their IP addresses and Velocity will only accept named servers and drop any unknown DNS names.

==Installation==

The installation will be in some distinct stages to enable each step to be proved to be working before proceeding to the next stage. First we setup a simple vanilla Minecraft server and set the firewall to port forward to it directly. Once that is proven to be working we will setup a Velocity server that will receive all 25565 traffic and forward it to the working Minecraft host. The next phase after the first host is getting traffic forwarded is to setup a second host and make sure velocity can forward to each, included in this step will be hardening the Velocity server with whatever security measures that it has available. When we are sure that Velocity is working properly we can work on the remote access stage, where we use TCPShield to proxy the service and have Cloudflare DNS only names setup with cherry.seaoffate.net and apple.seaoffate.net etc. From this point forward any new Minecraft servers will simply follow the same setup procedure.

===The First Minecraft Host Configuration===

The first Minecraft host needs to have enough resources to run the JVM and the server but as it just a vanilla server the specification does not need to be excessive. The table shows the highlights.

{| class="wikitable"
|+
|-
! Item !! Value !! Notes
|-
|CPU || 2 ||
|-
|RAM || 4GB ||
|-
|Swap || 16gb || Additional disk allocated from Lexar SSD
|-
|Storage || 96GB || Initially set at 32gb
|-
|Base OS || Debian 13.3 || Server version
|-
|Hostname || Cherry ||
|-
|IP Address || 192.168.100.30 ||
|}

====Hardware Configuration====
The Cherry host was created as a clone of the Debian template and then the basic specifications were improved so we will need to configure these extra items in the OS. First we need to identify the harddrive to use as the swap file
lsblk
The result is likely to show that the disk is likely to be /dev/sdb so we can set the swap space and enable it with
sudo mkswap /dev/sdb
sudo swapon /dev/sdb
To make the swap file persistent we edit the fstab
sudo nano /etc/fstab
Add the line:
/dev/sdb none swap sw 0 0
and remove or comment out the line that refers to
/dev/sda3
Before the storage sda main partition can be expanded to the full 96GB we have to remove the swap that is in the way so disable the existing swap with
sudo swapoff /dev/sda3
Open the disk utility to modify sda
sudo fdisk /dev/sda
Delete the swap partition with the option d, then type 3 to delete partition 3, then w to save and exit. The next thing to do is expand the Primary Root Partition so open fdisk again:
sudo fdisk /dev/sda
Delete the root partition:
* Type d (Delete)
* Type 2 (this only deletes the table entry, not the data).
* Type n (Create a new partition)
* Type p (Primary Partition)
* Type 2 (For Partition number 2)
* Type enter (Use default values for start sector)
* Type enter (Use default values for end sectors to fill the 96GB)
* CRITICAL: When asked if you want to remove the signature, type N.
* Type w (Save and exit)
To finalize Storage reboot to refresh the kernel partition table:
sudo systemctl reboot
When the VM reboots expand the filesystem into the new space:
sudo resize2fs /dev/sda2
We can verify the new swap and new sda size with
df -h
Now that the hardware is setup and configured we can proceed to the software installation

====Software Installation====

The software installation consists of updates, install the JVM and then install the Minecraft server. So to start as we do on most hosts with updates
sudo apt update
sudo apt upgrade
Install Necessary Utilities:
sudo apt install htop screen wget curl -y
Install Java 25:
sudo apt install openjdk-25-jre-headless -y
Verify Java Installation (Ensure it reports OpenJDK 25)
java -version
Now we install the Minecraft server

Create the Server Directory:
mkdir ~/minecraft_server && cd ~/minecraft_server
Download the Server Software:
wget -O server.jar [https://piston-data.mojang.com/v1/objects/97ccd4c0ed3f81bbb7bfacddd1090b0c56f9bc51/server.jar](https://piston-data.mojang.com/v1/objects/97ccd4c0ed3f81bbb7bfacddd1090b0c56f9bc51/server.jar)
Assuming the file downloaded we need an initial run to generate the file:
java -Xms1G -Xmx1G -jar server.jar nogui
When the file is first created it will not run until we Accept the EULA with the command:
sed -i 's/eula=false/eula=true/' eula.txt
We can create the Start Script:
nano start.sh
Paste in the following
<nowiki> #!/bin/bash
while true
do
echo "--- Starting Minecraft Server ---"
java -Xms3G -Xmx3G \
--enable-native-access=ALL-UNNAMED \
-XX:+UseG1GC \
-XX:MaxGCPauseMillis=200 \
-XX:+UnlockExperimentalVMOptions \
-XX:+DisableExplicitGC \
-XX:+AlwaysPreTouch \
-jar server.jar nogui
echo "--- Server stopped. Restarting in 5 seconds (Ctrl+C to cancel) ---"
sleep 5
done</nowiki>
Set the script to execute with
chmod +x start.sh
We can start the server with
./start.sh
'''Note''' we can type the command stop in the terminal and the server will save the world and stop it for 5 seconds during the 5 seconds, if we type ctrl+c it will end the script or if we just leave it the server will restart.

====Enable External Access====

We will need to access the server from outside world so we should forward the Minecraft port 25565 to the IP address of cherry. To make the port forward rules in Pfsense easier to understand we add an alias for cherry's IP address and a port alias for 25565. We add a port forward rule to Pfsense that says source IP 192.168.0.0/16 and any port, destination this firewall (self) Destination port Minecraft_standard, redirect IP_cherry port Minecraft_standard.

====Testing====

With this configuration loading a Minecraft client and setting the destination server to the WAN port IP address it will connect to the cherry host.

As part of the wider LAN setup we added a Adguard LXC to manage DNS. Part of the Adguard configuration was made to avoid the hairpin network access so a DNS redirect was made to forward *.seaoffate.net to Pfsense WAN and as the default domain name was set to seaoffate.net. So now when we have a destination of cherry Adguard will translate the hostname to cherry.seaoffate.net and redirect it to Pfsense, Pfsense will then forward to the relevant server. If that does not work as expected the next test would be to set the destination to cherry.seaoffate.net which should be redirected by Adguard.

===Velocity Installation===

The Velocity server VM does not need to be especially high because all it needs to do is accept connections and forward them on to the relevant host and any associated functions like handle logon, bans and etc. Unlike the cherry host that we just setup the base specification from the Debian template needs to be cut down a bit and does not need a extra swap file or anything special.

{| class="wikitable"
|+
|-
! Item !! Value !! Notes
|-
|CPU || 1 ||
|-
|RAM || 1GB ||
|-
|Storage || 32GB ||
|-
|Base OS || Debian 13.3 || Server version
|-
|Hostname || Vangueria ||
|-
|IP Address || 192.168.100.29 ||
|}
====Software Installation====

As there is no additions to the VM's specification there is no hardware to configure so we can get straight to the software installation. So the well known update/upgrade and the packages can be installed with
sudo apt update && sudo apt upgrade -y
sudo apt install -y openjdk-25-jre-headless htop screen wget jq curl
Once the dependencies are installed, we create a dedicated application directory and use an automated script to identify the most recent build of Velocity 3.4.0. This ensures we are not relying on hardcoded links that may expire.
mkdir ~/velocity && cd ~/velocity
export PROJECT="velocity"
export VERSION="3.4.0-SNAPSHOT"
export LATEST_BUILD=$(curl -s https://api.papermc.io/v2/projects/${PROJECT}/versions/${VERSION} | jq '.builds[-1]')
wget -O ~/velocity/velocity.jar "https://api.papermc.io/v2/projects/${PROJECT}/versions/${VERSION}/builds/${LATEST_BUILD}/downloads/${PROJECT}-${VERSION}-${LATEST_BUILD}.jar"
The initial boot of Velocity is performed to generate the necessary configuration files. We launch it with a 512MB heap size and then shut it down gracefully using the end command once the prompt appears.
java -Xms512M -Xmx512M -jar velocity.jar

====Proxy Configuration and Routing====

The primary configuration for the proxy is handled within the velocity.toml file. This file dictates how the proxy listens for incoming traffic and how it maps domain names to internal IP addresses. We edit this file to ensure the proxy is listening on all interfaces and that it is using the modern forwarding protocol.
nano ~/velocity/velocity.toml
Modify these specific lines:
* Bind Address: bind = "0.0.0.0:25565" (Allows it to hear traffic from pfSense).
* Forwarding Mode: player-info-forwarding-mode = "modern" (This is the most secure protocol for 2026).
* ping-passthrough should be set to ALL. This is to ensure the server list on the Minecraft client correctly displays the status and version of the backend servers
* Server List: Scroll down to the [servers] section:
<nowiki>[servers]
cherry = "192.168.100.30:25565"
apple = "192.168.100.35:25565"

[servers]
try = [
"cherry"
]</nowiki>
* Forced Hosts: This tells the proxy which server to pick based on the URL the player typed:
<nowiki>[forced-hosts]
"cherry.seaoffate.net" = ["cherry"]
"apple.seaoffate.net" = ["apple"]</nowiki>
Save and close the file. next we need a start.sh file for Velocity
nano ~/velocity/start.sh
copy the following into the file
<nowiki> #!/bin/bash
while true
do
echo "--- Starting Vangueria Proxy ---"
java -Xms512M -Xmx512M \
-XX:+UseG1GC \
-XX:MaxGCPauseMillis=200 \
-XX:+UnlockExperimentalVMOptions \
-XX:+DisableExplicitGC \
-XX:+AlwaysPreTouch \
-jar velocity.jar
echo "--- Proxy stopped. Restarting in 5s ---"
sleep 5
done</nowiki>
To make the script executable
chmod +x ~/velocity/start.sh
At this point the since Vangueria is now set to Modern Forwarding, Cherry will reject all connections until it has the forwarding.secret. the secret can be obtained with the command
cat ~/velocity/forwarding.secret
Copy the code to a safe location because we will need it to setup cherry (and apple). then we should be able to finally start the proxy with the start.sh
./start.sh
Now we move to cherry to setup it's ability to receive connections from Vangueria.

====Configuring Cherry To Accept Proxied Connections====

To complete the integration between the proxy and the backend, Cherry must be transitioned from a standalone Vanilla server to a "Proxy-Aware" host. Because Vanilla Minecraft does not natively support Velocity’s Modern Forwarding (the security handshake), we use the Fabric Loader as a lightweight wrapper. This allows us to install a bridge mod that validates the secret key without changing the gameplay experience.The transition of Cherry involves three main phases: installing the Fabric environment, adding the bridge mods, and configuring the security handshake to match Vangueria.

First, we must stop the existing server and install the Fabric transition layer. This replaces the standard Mojang launcher with a version capable of loading the security bridge. We need to download the Fabric Installer and then Install Fabric for the 1.21.1 environment.
cd ~/minecraft_server
wget https://maven.fabricmc.net/net/fabricmc/fabric-installer/1.0.1/fabric-installer-1.0.1.jar
java -jar fabric-installer-1.0.1.jar server -mcversion 1.21.1 -downloadMinecraft
Once complete, the installer will have created a new file named fabric-server-launch.jar. This is now the primary entry point for the server.

To install the Security Bridge we require two specific components in the mods folder: the Fabric API (the library that allows mods to interact with the game engine) and FabricProxy-Lite (the specific mod that handles the Velocity secret key). It is vital to use version-matched JARs for 1.21.1 to ensure stability.
mkdir -p ~/minecraft_server/mods
wget -O ~/minecraft_server/mods/FabricProxy-Lite.jar https://github.com/OKTW-Network/FabricProxy-Lite/releases/download/v2.10.1/FabricProxy-Lite-2.10.1.jar
wget -O ~/minecraft_server/mods/fabric-api.jar https://github.com/FabricMC/fabric-api/releases/download/0.116.11%2B1.21.1/fabric-api-0.116.11+1.21.1.jar

To configure the handshake after placing the mods, we must run the server once to generate the configuration structure, then shut it down to inject the secret.
Update start.sh to point to fabric-server-launch.jar instead of server.jar
sed -i 's/server.jar/fabric-server-launch.jar/' start.sh
Initial run to generate config (Type 'stop' once the 'Done' message appears)
./start.sh
Now, we create the configuration file and link it to Vangueria. This is where we ensure the backend only trusts traffic coming from our proxy.
mkdir -p ~/minecraft_server/config
nano ~/minecraft_server/config/FabricProxy-Lite.toml
Paste the following configuration into the file, ensuring the secret matches the one obtained from Vangueria:
enabled = true
hackOnlineMode = true
secret = "PASTE_YOUR_VANGUERIA_SECRET_HERE"
The final step is to adjust the server.properties file. Because Vangueria handles the official Mojang authentication at the "front door," the backend server must be set to offline mode to allow the proxy to pass the authenticated user data through.
sed -i 's/online-mode=true/online-mode=false/' server.properties
With the configuration complete, the server should be launched inside a named screen session to ensure it remains active.
screen -S minecraft ./start.sh
We should now change the Pfsense port forward rule to forward traffic to the 192.168.100.29 (IP address of Vangueria) and then connecting a client from a laptop outside of Pfsense and using the address cherry.seaoffate.net, we can try using the IP address of the Pfsense WAN port but it may not work (if the default server is set to cherry it may connect)

===Additional Options===

There are a few additional considerations that will make the servers run more reliably. The first is thing that needs to be done is to run the server in a screen so that there does not need to be a SSH session to be running. The following will start a screen called minecraft and will execute the start.sh command.
screen -S minecraft ./start
To exit the minecraft screen and return to the main SSH type ctrl + a and then d, the minecraft screen can be reloaded with the command
screen -r minecraft
The next thing that we will need to do is to have the minecraft server start whenever the host reboots. So we need to add a cron tab to the start.sh
crontab -e
Select nano if asked then add the line
@reboot screen -dmS minecraft /home/nigel/minecraft_server/start.sh

The next thing is not a minecraft helper exactly but it will be useful as a reminder in the future. When a user logs on to the host the message of the day will be displayed to add simple notes to the message we can simply edit the motd with the command
sudo nano /etc/motd

===Adding a second Minecraft server Apple===

Now that we have the basic setup with potential for multiple hosts we will need to create at least one more so that we can prove the proxy works as intended. The next server will be a different version with some mods. As soon as we start adding mods to a Minecraft world they will use more resources so we will need the next host to be a bit better specified.

{| class="wikitable"
|+
|-
! Item !! Value !! Notes
|-
|CPU || 5 ||
|-
|RAM || 12GB ||
|-
|Swap || 16gb || Additional disk allocated from Lexar SSD
|-
|Storage || 150GB || Initially set at 32gb
|-
|Base OS || Debian 13.3 || Server version
|-
|Hostname || Apple||
|-
|IP Address || 192.168.100.35 ||
|}

====Hardware Configuration====

As we did with the cherry host earlier we need to configure the hardware changes that have been made on the basic specification like adding the Lexar HD as the swap file. We must stop using the swap partition on the primary drive so we can move it out of the way. Turn off all swap.
sudo swapoff -a
Since your swap partition (sda3) is at the end of the disk, it acts as a "blocker." We need to delete it and the root partition, then recreate the root partition to fill the entire space.
sudo fdisk /dev/sda
* Type p to print the table (confirming sda2 is root and sda3 is swap).
* Type d then 3 to delete the swap partition.
* Type d then 2 to delete the root partition (Don't worry, the data stays in the blocks).
* Step B: Recreate and Expand
* Type n for a new partition.
* Type p for Primary. Note if disk is using a GPT (GUID Partition Table) there will be no P option, primary partitions only exist in the old MBR style of disks
* Type 2 for Partition number 2.
* Press Enter for the default Start Sector (it must match the old start sector of sda2).
* Press Enter for the default End Sector (this will now jump to the end of the 150GB disk).
* CRITICAL: When it asks "Do you want to remove the signature?", type N.
* Type w to write changes and exit.
Now, reboot to make sure the kernel is looking at the new 150GB table entry.
sudo systemctl reboot
Once you log back in, expand the actual data "container" (the ext4 filesystem) to fill that new partition:
sudo resize2fs /dev/sda2
Now that the main drive is expanded, let's get that high-speed swap set up on your 16GB secondary disk.
sudo mkswap /dev/sdb
sudo swapon /dev/sdb
We need to update /etc/fstab so your VM knows where to find its memory "safety net" on every boot.
sudo nano /etc/fstab
Look for the line that mentions the old swap (it likely mentions sda3 or a long UUID string). Delete that line or put a # at the start of it. Add this new line at the bottom:
/dev/sdb none swap sw 0 0
Save and exit. Then to confirm the changes have been made use the following commands to show the new sda2 disk size and the swap disk
df -h
free -h

====Software installation====

Since Apple is a fresh VM, we need to ensure the underlying Debian OS is fully patched and has the necessary build tools and repositories before we drop a massive modpack into it. Modern modpacks like ATM10 (Minecraft 1.21.1) rely heavily on Java 21 or Java 25, so we will set that foundation now. First, we refresh the local package index and upgrade any existing system components. Update package lists and upgrade system and install essential utilities for file management and monitoring
sudo apt update && sudo apt upgrade -y
sudo apt install -y htop screen wget curl jq unzip zip
Install Java 25 and verify the version to ensure it's active
sudo apt install -y openjdk-25-jre-headless
java -version
Now that the system is ready, we can create the home for Apple. Create the Modpack Directory
mkdir ~/atm_server && cd ~/atm_server
We now need the server file ServerFiles-6.6.zip but it would appear that the curseforge website don't allow wget downloads so the best way to get the file is to download via http and scp it to the atm-server directory. When the .zip file is in the atm directory we unzip it
unzip ServerFiles-6.6.zip
Make the installer executable
chmod +x startserver.sh
Run the installer
./startserver.sh

Minecraft

2026-05-12T21:57:06Z

Wikisailor: /* Software installation */

==Introduction==

We are to have some Minecraft servers on the '''[[Home Lab]]''''. The general setup will be to have a Velocity server in front several Minecraft host '''[[Virtual Machines]]'''. Velocity works in a similar way to a Nginx reverse proxy whereby Pfsense forwards all Minecraft traffic to the Velocity server including the SNI and Velocity redirects traffic to the required hostname based on the DNS name. Cloudflare does not reverse proxy Minecraft traffic on the free tier and as we do not want to have to deal with random bots from the east so we will not leave the port open on the edge or Pfsense to random bots with port scanners. So we will use grey cloud at Cloudflare but DNS will point to a service like TCPShield and our firewalls only accept Minecraft traffic from their IP addresses and Velocity will only accept named servers and drop any unknown DNS names.

==Installation==

The installation will be in some distinct stages to enable each step to be proved to be working before proceeding to the next stage. First we setup a simple vanilla Minecraft server and set the firewall to port forward to it directly. Once that is proven to be working we will setup a Velocity server that will receive all 25565 traffic and forward it to the working Minecraft host. The next phase after the first host is getting traffic forwarded is to setup a second host and make sure velocity can forward to each, included in this step will be hardening the Velocity server with whatever security measures that it has available. When we are sure that Velocity is working properly we can work on the remote access stage, where we use TCPShield to proxy the service and have Cloudflare DNS only names setup with cherry.seaoffate.net and apple.seaoffate.net etc. From this point forward any new Minecraft servers will simply follow the same setup procedure.

===The First Minecraft Host Configuration===

The first Minecraft host needs to have enough resources to run the JVM and the server but as it just a vanilla server the specification does not need to be excessive. The table shows the highlights.

{| class="wikitable"
|+
|-
! Item !! Value !! Notes
|-
|CPU || 2 ||
|-
|RAM || 4GB ||
|-
|Swap || 16gb || Additional disk allocated from Lexar SSD
|-
|Storage || 96GB || Initially set at 32gb
|-
|Base OS || Debian 13.3 || Server version
|-
|Hostname || Cherry ||
|-
|IP Address || 192.168.100.30 ||
|}

====Hardware Configuration====
The Cherry host was created as a clone of the Debian template and then the basic specifications were improved so we will need to configure these extra items in the OS. First we need to identify the harddrive to use as the swap file
lsblk
The result is likely to show that the disk is likely to be /dev/sdb so we can set the swap space and enable it with
sudo mkswap /dev/sdb
sudo swapon /dev/sdb
To make the swap file persistent we edit the fstab
sudo nano /etc/fstab
Add the line:
/dev/sdb none swap sw 0 0
and remove or comment out the line that refers to
/dev/sda3
Before the storage sda main partition can be expanded to the full 96GB we have to remove the swap that is in the way so disable the existing swap with
sudo swapoff /dev/sda3
Open the disk utility to modify sda
sudo fdisk /dev/sda
Delete the swap partition with the option d, then type 3 to delete partition 3, then w to save and exit. The next thing to do is expand the Primary Root Partition so open fdisk again:
sudo fdisk /dev/sda
Delete the root partition:
* Type d (Delete)
* Type 2 (this only deletes the table entry, not the data).
* Type n (Create a new partition)
* Type p (Primary Partition)
* Type 2 (For Partition number 2)
* Type enter (Use default values for start sector)
* Type enter (Use default values for end sectors to fill the 96GB)
* CRITICAL: When asked if you want to remove the signature, type N.
* Type w (Save and exit)
To finalize Storage reboot to refresh the kernel partition table:
sudo systemctl reboot
When the VM reboots expand the filesystem into the new space:
sudo resize2fs /dev/sda2
We can verify the new swap and new sda size with
df -h
Now that the hardware is setup and configured we can proceed to the software installation

====Software Installation====

The software installation consists of updates, install the JVM and then install the Minecraft server. So to start as we do on most hosts with updates
sudo apt update
sudo apt upgrade
Install Necessary Utilities:
sudo apt install htop screen wget curl -y
Install Java 25:
sudo apt install openjdk-25-jre-headless -y
Verify Java Installation (Ensure it reports OpenJDK 25)
java -version
Now we install the Minecraft server

Create the Server Directory:
mkdir ~/minecraft_server && cd ~/minecraft_server
Download the Server Software:
wget -O server.jar [https://piston-data.mojang.com/v1/objects/97ccd4c0ed3f81bbb7bfacddd1090b0c56f9bc51/server.jar](https://piston-data.mojang.com/v1/objects/97ccd4c0ed3f81bbb7bfacddd1090b0c56f9bc51/server.jar)
Assuming the file downloaded we need an initial run to generate the file:
java -Xms1G -Xmx1G -jar server.jar nogui
When the file is first created it will not run until we Accept the EULA with the command:
sed -i 's/eula=false/eula=true/' eula.txt
We can create the Start Script:
nano start.sh
Paste in the following
<nowiki> #!/bin/bash
while true
do
echo "--- Starting Minecraft Server ---"
java -Xms3G -Xmx3G \
--enable-native-access=ALL-UNNAMED \
-XX:+UseG1GC \
-XX:MaxGCPauseMillis=200 \
-XX:+UnlockExperimentalVMOptions \
-XX:+DisableExplicitGC \
-XX:+AlwaysPreTouch \
-jar server.jar nogui
echo "--- Server stopped. Restarting in 5 seconds (Ctrl+C to cancel) ---"
sleep 5
done</nowiki>
Set the script to execute with
chmod +x start.sh
We can start the server with
./start.sh
'''Note''' we can type the command stop in the terminal and the server will save the world and stop it for 5 seconds during the 5 seconds, if we type ctrl+c it will end the script or if we just leave it the server will restart.

====Enable External Access====

We will need to access the server from outside world so we should forward the Minecraft port 25565 to the IP address of cherry. To make the port forward rules in Pfsense easier to understand we add an alias for cherry's IP address and a port alias for 25565. We add a port forward rule to Pfsense that says source IP 192.168.0.0/16 and any port, destination this firewall (self) Destination port Minecraft_standard, redirect IP_cherry port Minecraft_standard.

====Testing====

With this configuration loading a Minecraft client and setting the destination server to the WAN port IP address it will connect to the cherry host.

As part of the wider LAN setup we added a Adguard LXC to manage DNS. Part of the Adguard configuration was made to avoid the hairpin network access so a DNS redirect was made to forward *.seaoffate.net to Pfsense WAN and as the default domain name was set to seaoffate.net. So now when we have a destination of cherry Adguard will translate the hostname to cherry.seaoffate.net and redirect it to Pfsense, Pfsense will then forward to the relevant server. If that does not work as expected the next test would be to set the destination to cherry.seaoffate.net which should be redirected by Adguard.

===Velocity Installation===

The Velocity server VM does not need to be especially high because all it needs to do is accept connections and forward them on to the relevant host and any associated functions like handle logon, bans and etc. Unlike the cherry host that we just setup the base specification from the Debian template needs to be cut down a bit and does not need a extra swap file or anything special.

{| class="wikitable"
|+
|-
! Item !! Value !! Notes
|-
|CPU || 1 ||
|-
|RAM || 1GB ||
|-
|Storage || 32GB ||
|-
|Base OS || Debian 13.3 || Server version
|-
|Hostname || Vangueria ||
|-
|IP Address || 192.168.100.29 ||
|}
====Software Installation====

As there is no additions to the VM's specification there is no hardware to configure so we can get straight to the software installation. So the well known update/upgrade and the packages can be installed with
sudo apt update && sudo apt upgrade -y
sudo apt install -y openjdk-25-jre-headless htop screen wget jq curl
Once the dependencies are installed, we create a dedicated application directory and use an automated script to identify the most recent build of Velocity 3.4.0. This ensures we are not relying on hardcoded links that may expire.
mkdir ~/velocity && cd ~/velocity
export PROJECT="velocity"
export VERSION="3.4.0-SNAPSHOT"
export LATEST_BUILD=$(curl -s https://api.papermc.io/v2/projects/${PROJECT}/versions/${VERSION} | jq '.builds[-1]')
wget -O ~/velocity/velocity.jar "https://api.papermc.io/v2/projects/${PROJECT}/versions/${VERSION}/builds/${LATEST_BUILD}/downloads/${PROJECT}-${VERSION}-${LATEST_BUILD}.jar"
The initial boot of Velocity is performed to generate the necessary configuration files. We launch it with a 512MB heap size and then shut it down gracefully using the end command once the prompt appears.
java -Xms512M -Xmx512M -jar velocity.jar

====Proxy Configuration and Routing====

The primary configuration for the proxy is handled within the velocity.toml file. This file dictates how the proxy listens for incoming traffic and how it maps domain names to internal IP addresses. We edit this file to ensure the proxy is listening on all interfaces and that it is using the modern forwarding protocol.
nano ~/velocity/velocity.toml
Modify these specific lines:
* Bind Address: bind = "0.0.0.0:25565" (Allows it to hear traffic from pfSense).
* Forwarding Mode: player-info-forwarding-mode = "modern" (This is the most secure protocol for 2026).
* ping-passthrough should be set to ALL. This is to ensure the server list on the Minecraft client correctly displays the status and version of the backend servers
* Server List: Scroll down to the [servers] section:
<nowiki>[servers]
cherry = "192.168.100.30:25565"
apple = "192.168.100.35:25565"

[servers]
try = [
"cherry"
]</nowiki>
* Forced Hosts: This tells the proxy which server to pick based on the URL the player typed:
<nowiki>[forced-hosts]
"cherry.seaoffate.net" = ["cherry"]
"apple.seaoffate.net" = ["apple"]</nowiki>
Save and close the file. next we need a start.sh file for Velocity
nano ~/velocity/start.sh
copy the following into the file
<nowiki> #!/bin/bash
while true
do
echo "--- Starting Vangueria Proxy ---"
java -Xms512M -Xmx512M \
-XX:+UseG1GC \
-XX:MaxGCPauseMillis=200 \
-XX:+UnlockExperimentalVMOptions \
-XX:+DisableExplicitGC \
-XX:+AlwaysPreTouch \
-jar velocity.jar
echo "--- Proxy stopped. Restarting in 5s ---"
sleep 5
done</nowiki>
To make the script executable
chmod +x ~/velocity/start.sh
At this point the since Vangueria is now set to Modern Forwarding, Cherry will reject all connections until it has the forwarding.secret. the secret can be obtained with the command
cat ~/velocity/forwarding.secret
Copy the code to a safe location because we will need it to setup cherry (and apple). then we should be able to finally start the proxy with the start.sh
./start.sh
Now we move to cherry to setup it's ability to receive connections from Vangueria.

====Configuring Cherry To Accept Proxied Connections====

To complete the integration between the proxy and the backend, Cherry must be transitioned from a standalone Vanilla server to a "Proxy-Aware" host. Because Vanilla Minecraft does not natively support Velocity’s Modern Forwarding (the security handshake), we use the Fabric Loader as a lightweight wrapper. This allows us to install a bridge mod that validates the secret key without changing the gameplay experience.The transition of Cherry involves three main phases: installing the Fabric environment, adding the bridge mods, and configuring the security handshake to match Vangueria.

First, we must stop the existing server and install the Fabric transition layer. This replaces the standard Mojang launcher with a version capable of loading the security bridge. We need to download the Fabric Installer and then Install Fabric for the 1.21.1 environment.
cd ~/minecraft_server
wget https://maven.fabricmc.net/net/fabricmc/fabric-installer/1.0.1/fabric-installer-1.0.1.jar
java -jar fabric-installer-1.0.1.jar server -mcversion 1.21.1 -downloadMinecraft
Once complete, the installer will have created a new file named fabric-server-launch.jar. This is now the primary entry point for the server.

To install the Security Bridge we require two specific components in the mods folder: the Fabric API (the library that allows mods to interact with the game engine) and FabricProxy-Lite (the specific mod that handles the Velocity secret key). It is vital to use version-matched JARs for 1.21.1 to ensure stability.
mkdir -p ~/minecraft_server/mods
wget -O ~/minecraft_server/mods/FabricProxy-Lite.jar https://github.com/OKTW-Network/FabricProxy-Lite/releases/download/v2.10.1/FabricProxy-Lite-2.10.1.jar
wget -O ~/minecraft_server/mods/fabric-api.jar https://github.com/FabricMC/fabric-api/releases/download/0.116.11%2B1.21.1/fabric-api-0.116.11+1.21.1.jar

To configure the handshake after placing the mods, we must run the server once to generate the configuration structure, then shut it down to inject the secret.
Update start.sh to point to fabric-server-launch.jar instead of server.jar
sed -i 's/server.jar/fabric-server-launch.jar/' start.sh
Initial run to generate config (Type 'stop' once the 'Done' message appears)
./start.sh
Now, we create the configuration file and link it to Vangueria. This is where we ensure the backend only trusts traffic coming from our proxy.
mkdir -p ~/minecraft_server/config
nano ~/minecraft_server/config/FabricProxy-Lite.toml
Paste the following configuration into the file, ensuring the secret matches the one obtained from Vangueria:
enabled = true
hackOnlineMode = true
secret = "PASTE_YOUR_VANGUERIA_SECRET_HERE"
The final step is to adjust the server.properties file. Because Vangueria handles the official Mojang authentication at the "front door," the backend server must be set to offline mode to allow the proxy to pass the authenticated user data through.
sed -i 's/online-mode=true/online-mode=false/' server.properties
With the configuration complete, the server should be launched inside a named screen session to ensure it remains active.
screen -S minecraft ./start.sh
We should now change the Pfsense port forward rule to forward traffic to the 192.168.100.29 (IP address of Vangueria) and then connecting a client from a laptop outside of Pfsense and using the address cherry.seaoffate.net, we can try using the IP address of the Pfsense WAN port but it may not work (if the default server is set to cherry it may connect)

===Additional Options===

There are a few additional considerations that will make the servers run more reliably. The first is thing that needs to be done is to run the server in a screen so that there does not need to be a SSH session to be running. The following will start a screen called minecraft and will execute the start.sh command.
screen -S minecraft ./start
To exit the minecraft screen and return to the main SSH type ctrl + a and then d, the minecraft screen can be reloaded with the command
screen -r minecraft
The next thing that we will need to do is to have the minecraft server start whenever the host reboots. So we need to add a cron tab to the start.sh
crontab -e
Select nano if asked then add the line
@reboot screen -dmS minecraft /home/nigel/minecraft_server/start.sh

The next thing is not a minecraft helper exactly but it will be useful as a reminder in the future. When a user logs on to the host the message of the day will be displayed to add simple notes to the message we can simply edit the motd with the command
sudo nano /etc/motd

===Adding a second Minecraft server Apple===

Now that we have the basic setup with potential for multiple hosts we will need to create at least one more so that we can prove the proxy works as intended. The next server will be a different version with some mods. As soon as we start adding mods to a Minecraft world they will use more resources so we will need the next host to be a bit better specified.

{| class="wikitable"
|+
|-
! Item !! Value !! Notes
|-
|CPU || 5 ||
|-
|RAM || 14GB ||
|-
|Swap || 16gb || Additional disk allocated from Lexar SSD
|-
|Storage || 150GB || Initially set at 32gb
|-
|Base OS || Debian 13.3 || Server version
|-
|Hostname || Apple||
|-
|IP Address || 192.168.100.35 ||
|}

====Hardware Configuration====

As we did with the cherry host earlier we need to configure the hardware changes that have been made on the basic specification like adding the Lexar HD as the swap file. We must stop using the swap partition on the primary drive so we can move it out of the way. Turn off all swap.
sudo swapoff -a
Since your swap partition (sda3) is at the end of the disk, it acts as a "blocker." We need to delete it and the root partition, then recreate the root partition to fill the entire space.
sudo fdisk /dev/sda
* Type p to print the table (confirming sda2 is root and sda3 is swap).
* Type d then 3 to delete the swap partition.
* Type d then 2 to delete the root partition (Don't worry, the data stays in the blocks).
* Step B: Recreate and Expand
* Type n for a new partition.
* Type p for Primary. Note if disk is using a GPT (GUID Partition Table) there will be no P option, primary partitions only exist in the old MBR style of disks
* Type 2 for Partition number 2.
* Press Enter for the default Start Sector (it must match the old start sector of sda2).
* Press Enter for the default End Sector (this will now jump to the end of the 150GB disk).
* CRITICAL: When it asks "Do you want to remove the signature?", type N.
* Type w to write changes and exit.
Now, reboot to make sure the kernel is looking at the new 150GB table entry.
sudo systemctl reboot
Once you log back in, expand the actual data "container" (the ext4 filesystem) to fill that new partition:
sudo resize2fs /dev/sda2
Now that the main drive is expanded, let's get that high-speed swap set up on your 16GB secondary disk.
sudo mkswap /dev/sdb
sudo swapon /dev/sdb
We need to update /etc/fstab so your VM knows where to find its memory "safety net" on every boot.
sudo nano /etc/fstab
Look for the line that mentions the old swap (it likely mentions sda3 or a long UUID string). Delete that line or put a # at the start of it. Add this new line at the bottom:
/dev/sdb none swap sw 0 0
Save and exit. Then to confirm the changes have been made use the following commands to show the new sda2 disk size and the swap disk
df -h
free -h

====Software installation====

Since Apple is a fresh VM, we need to ensure the underlying Debian OS is fully patched and has the necessary build tools and repositories before we drop a massive modpack into it. Modern modpacks like ATM10 (Minecraft 1.21.1) rely heavily on Java 21 or Java 25, so we will set that foundation now. First, we refresh the local package index and upgrade any existing system components. Update package lists and upgrade system and install essential utilities for file management and monitoring
sudo apt update && sudo apt upgrade -y
sudo apt install -y htop screen wget curl jq unzip zip
Install Java 25 and verify the version to ensure it's active
sudo apt install -y openjdk-25-jre-headless
java -version
Now that the system is ready, we can create the home for Apple. Create the Modpack Directory
mkdir ~/atm_server && cd ~/atm_server
We now need the server file ServerFiles-6.6.zip but it would appear that the curseforge website don't allow wget downloads so the best way to get the file is to download via http and scp it to the atm-server directory. When the .zip file is in the atm directory we unzip it
unzip ServerFiles-6.6.zip
Make the installer executable
chmod +x startserver.sh
Run the installer
./startserver.sh

Minecraft

2026-05-12T20:43:17Z

Wikisailor: /* Hardware Configuration */

==Introduction==

We are to have some Minecraft servers on the '''[[Home Lab]]''''. The general setup will be to have a Velocity server in front several Minecraft host '''[[Virtual Machines]]'''. Velocity works in a similar way to a Nginx reverse proxy whereby Pfsense forwards all Minecraft traffic to the Velocity server including the SNI and Velocity redirects traffic to the required hostname based on the DNS name. Cloudflare does not reverse proxy Minecraft traffic on the free tier and as we do not want to have to deal with random bots from the east so we will not leave the port open on the edge or Pfsense to random bots with port scanners. So we will use grey cloud at Cloudflare but DNS will point to a service like TCPShield and our firewalls only accept Minecraft traffic from their IP addresses and Velocity will only accept named servers and drop any unknown DNS names.

==Installation==

The installation will be in some distinct stages to enable each step to be proved to be working before proceeding to the next stage. First we setup a simple vanilla Minecraft server and set the firewall to port forward to it directly. Once that is proven to be working we will setup a Velocity server that will receive all 25565 traffic and forward it to the working Minecraft host. The next phase after the first host is getting traffic forwarded is to setup a second host and make sure velocity can forward to each, included in this step will be hardening the Velocity server with whatever security measures that it has available. When we are sure that Velocity is working properly we can work on the remote access stage, where we use TCPShield to proxy the service and have Cloudflare DNS only names setup with cherry.seaoffate.net and apple.seaoffate.net etc. From this point forward any new Minecraft servers will simply follow the same setup procedure.

===The First Minecraft Host Configuration===

The first Minecraft host needs to have enough resources to run the JVM and the server but as it just a vanilla server the specification does not need to be excessive. The table shows the highlights.

{| class="wikitable"
|+
|-
! Item !! Value !! Notes
|-
|CPU || 2 ||
|-
|RAM || 4GB ||
|-
|Swap || 16gb || Additional disk allocated from Lexar SSD
|-
|Storage || 96GB || Initially set at 32gb
|-
|Base OS || Debian 13.3 || Server version
|-
|Hostname || Cherry ||
|-
|IP Address || 192.168.100.30 ||
|}

====Hardware Configuration====
The Cherry host was created as a clone of the Debian template and then the basic specifications were improved so we will need to configure these extra items in the OS. First we need to identify the harddrive to use as the swap file
lsblk
The result is likely to show that the disk is likely to be /dev/sdb so we can set the swap space and enable it with
sudo mkswap /dev/sdb
sudo swapon /dev/sdb
To make the swap file persistent we edit the fstab
sudo nano /etc/fstab
Add the line:
/dev/sdb none swap sw 0 0
and remove or comment out the line that refers to
/dev/sda3
Before the storage sda main partition can be expanded to the full 96GB we have to remove the swap that is in the way so disable the existing swap with
sudo swapoff /dev/sda3
Open the disk utility to modify sda
sudo fdisk /dev/sda
Delete the swap partition with the option d, then type 3 to delete partition 3, then w to save and exit. The next thing to do is expand the Primary Root Partition so open fdisk again:
sudo fdisk /dev/sda
Delete the root partition:
* Type d (Delete)
* Type 2 (this only deletes the table entry, not the data).
* Type n (Create a new partition)
* Type p (Primary Partition)
* Type 2 (For Partition number 2)
* Type enter (Use default values for start sector)
* Type enter (Use default values for end sectors to fill the 96GB)
* CRITICAL: When asked if you want to remove the signature, type N.
* Type w (Save and exit)
To finalize Storage reboot to refresh the kernel partition table:
sudo systemctl reboot
When the VM reboots expand the filesystem into the new space:
sudo resize2fs /dev/sda2
We can verify the new swap and new sda size with
df -h
Now that the hardware is setup and configured we can proceed to the software installation

====Software Installation====

The software installation consists of updates, install the JVM and then install the Minecraft server. So to start as we do on most hosts with updates
sudo apt update
sudo apt upgrade
Install Necessary Utilities:
sudo apt install htop screen wget curl -y
Install Java 25:
sudo apt install openjdk-25-jre-headless -y
Verify Java Installation (Ensure it reports OpenJDK 25)
java -version
Now we install the Minecraft server

Create the Server Directory:
mkdir ~/minecraft_server && cd ~/minecraft_server
Download the Server Software:
wget -O server.jar [https://piston-data.mojang.com/v1/objects/97ccd4c0ed3f81bbb7bfacddd1090b0c56f9bc51/server.jar](https://piston-data.mojang.com/v1/objects/97ccd4c0ed3f81bbb7bfacddd1090b0c56f9bc51/server.jar)
Assuming the file downloaded we need an initial run to generate the file:
java -Xms1G -Xmx1G -jar server.jar nogui
When the file is first created it will not run until we Accept the EULA with the command:
sed -i 's/eula=false/eula=true/' eula.txt
We can create the Start Script:
nano start.sh
Paste in the following
<nowiki> #!/bin/bash
while true
do
echo "--- Starting Minecraft Server ---"
java -Xms3G -Xmx3G \
--enable-native-access=ALL-UNNAMED \
-XX:+UseG1GC \
-XX:MaxGCPauseMillis=200 \
-XX:+UnlockExperimentalVMOptions \
-XX:+DisableExplicitGC \
-XX:+AlwaysPreTouch \
-jar server.jar nogui
echo "--- Server stopped. Restarting in 5 seconds (Ctrl+C to cancel) ---"
sleep 5
done</nowiki>
Set the script to execute with
chmod +x start.sh
We can start the server with
./start.sh
'''Note''' we can type the command stop in the terminal and the server will save the world and stop it for 5 seconds during the 5 seconds, if we type ctrl+c it will end the script or if we just leave it the server will restart.

====Enable External Access====

We will need to access the server from outside world so we should forward the Minecraft port 25565 to the IP address of cherry. To make the port forward rules in Pfsense easier to understand we add an alias for cherry's IP address and a port alias for 25565. We add a port forward rule to Pfsense that says source IP 192.168.0.0/16 and any port, destination this firewall (self) Destination port Minecraft_standard, redirect IP_cherry port Minecraft_standard.

====Testing====

With this configuration loading a Minecraft client and setting the destination server to the WAN port IP address it will connect to the cherry host.

As part of the wider LAN setup we added a Adguard LXC to manage DNS. Part of the Adguard configuration was made to avoid the hairpin network access so a DNS redirect was made to forward *.seaoffate.net to Pfsense WAN and as the default domain name was set to seaoffate.net. So now when we have a destination of cherry Adguard will translate the hostname to cherry.seaoffate.net and redirect it to Pfsense, Pfsense will then forward to the relevant server. If that does not work as expected the next test would be to set the destination to cherry.seaoffate.net which should be redirected by Adguard.

===Velocity Installation===

The Velocity server VM does not need to be especially high because all it needs to do is accept connections and forward them on to the relevant host and any associated functions like handle logon, bans and etc. Unlike the cherry host that we just setup the base specification from the Debian template needs to be cut down a bit and does not need a extra swap file or anything special.

{| class="wikitable"
|+
|-
! Item !! Value !! Notes
|-
|CPU || 1 ||
|-
|RAM || 1GB ||
|-
|Storage || 32GB ||
|-
|Base OS || Debian 13.3 || Server version
|-
|Hostname || Vangueria ||
|-
|IP Address || 192.168.100.29 ||
|}
====Software Installation====

As there is no additions to the VM's specification there is no hardware to configure so we can get straight to the software installation. So the well known update/upgrade and the packages can be installed with
sudo apt update && sudo apt upgrade -y
sudo apt install -y openjdk-25-jre-headless htop screen wget jq curl
Once the dependencies are installed, we create a dedicated application directory and use an automated script to identify the most recent build of Velocity 3.4.0. This ensures we are not relying on hardcoded links that may expire.
mkdir ~/velocity && cd ~/velocity
export PROJECT="velocity"
export VERSION="3.4.0-SNAPSHOT"
export LATEST_BUILD=$(curl -s https://api.papermc.io/v2/projects/${PROJECT}/versions/${VERSION} | jq '.builds[-1]')
wget -O ~/velocity/velocity.jar "https://api.papermc.io/v2/projects/${PROJECT}/versions/${VERSION}/builds/${LATEST_BUILD}/downloads/${PROJECT}-${VERSION}-${LATEST_BUILD}.jar"
The initial boot of Velocity is performed to generate the necessary configuration files. We launch it with a 512MB heap size and then shut it down gracefully using the end command once the prompt appears.
java -Xms512M -Xmx512M -jar velocity.jar

====Proxy Configuration and Routing====

The primary configuration for the proxy is handled within the velocity.toml file. This file dictates how the proxy listens for incoming traffic and how it maps domain names to internal IP addresses. We edit this file to ensure the proxy is listening on all interfaces and that it is using the modern forwarding protocol.
nano ~/velocity/velocity.toml
Modify these specific lines:
* Bind Address: bind = "0.0.0.0:25565" (Allows it to hear traffic from pfSense).
* Forwarding Mode: player-info-forwarding-mode = "modern" (This is the most secure protocol for 2026).
* ping-passthrough should be set to ALL. This is to ensure the server list on the Minecraft client correctly displays the status and version of the backend servers
* Server List: Scroll down to the [servers] section:
<nowiki>[servers]
cherry = "192.168.100.30:25565"
apple = "192.168.100.35:25565"

[servers]
try = [
"cherry"
]</nowiki>
* Forced Hosts: This tells the proxy which server to pick based on the URL the player typed:
<nowiki>[forced-hosts]
"cherry.seaoffate.net" = ["cherry"]
"apple.seaoffate.net" = ["apple"]</nowiki>
Save and close the file. next we need a start.sh file for Velocity
nano ~/velocity/start.sh
copy the following into the file
<nowiki> #!/bin/bash
while true
do
echo "--- Starting Vangueria Proxy ---"
java -Xms512M -Xmx512M \
-XX:+UseG1GC \
-XX:MaxGCPauseMillis=200 \
-XX:+UnlockExperimentalVMOptions \
-XX:+DisableExplicitGC \
-XX:+AlwaysPreTouch \
-jar velocity.jar
echo "--- Proxy stopped. Restarting in 5s ---"
sleep 5
done</nowiki>
To make the script executable
chmod +x ~/velocity/start.sh
At this point the since Vangueria is now set to Modern Forwarding, Cherry will reject all connections until it has the forwarding.secret. the secret can be obtained with the command
cat ~/velocity/forwarding.secret
Copy the code to a safe location because we will need it to setup cherry (and apple). then we should be able to finally start the proxy with the start.sh
./start.sh
Now we move to cherry to setup it's ability to receive connections from Vangueria.

====Configuring Cherry To Accept Proxied Connections====

To complete the integration between the proxy and the backend, Cherry must be transitioned from a standalone Vanilla server to a "Proxy-Aware" host. Because Vanilla Minecraft does not natively support Velocity’s Modern Forwarding (the security handshake), we use the Fabric Loader as a lightweight wrapper. This allows us to install a bridge mod that validates the secret key without changing the gameplay experience.The transition of Cherry involves three main phases: installing the Fabric environment, adding the bridge mods, and configuring the security handshake to match Vangueria.

First, we must stop the existing server and install the Fabric transition layer. This replaces the standard Mojang launcher with a version capable of loading the security bridge. We need to download the Fabric Installer and then Install Fabric for the 1.21.1 environment.
cd ~/minecraft_server
wget https://maven.fabricmc.net/net/fabricmc/fabric-installer/1.0.1/fabric-installer-1.0.1.jar
java -jar fabric-installer-1.0.1.jar server -mcversion 1.21.1 -downloadMinecraft
Once complete, the installer will have created a new file named fabric-server-launch.jar. This is now the primary entry point for the server.

To install the Security Bridge we require two specific components in the mods folder: the Fabric API (the library that allows mods to interact with the game engine) and FabricProxy-Lite (the specific mod that handles the Velocity secret key). It is vital to use version-matched JARs for 1.21.1 to ensure stability.
mkdir -p ~/minecraft_server/mods
wget -O ~/minecraft_server/mods/FabricProxy-Lite.jar https://github.com/OKTW-Network/FabricProxy-Lite/releases/download/v2.10.1/FabricProxy-Lite-2.10.1.jar
wget -O ~/minecraft_server/mods/fabric-api.jar https://github.com/FabricMC/fabric-api/releases/download/0.116.11%2B1.21.1/fabric-api-0.116.11+1.21.1.jar

To configure the handshake after placing the mods, we must run the server once to generate the configuration structure, then shut it down to inject the secret.
Update start.sh to point to fabric-server-launch.jar instead of server.jar
sed -i 's/server.jar/fabric-server-launch.jar/' start.sh
Initial run to generate config (Type 'stop' once the 'Done' message appears)
./start.sh
Now, we create the configuration file and link it to Vangueria. This is where we ensure the backend only trusts traffic coming from our proxy.
mkdir -p ~/minecraft_server/config
nano ~/minecraft_server/config/FabricProxy-Lite.toml
Paste the following configuration into the file, ensuring the secret matches the one obtained from Vangueria:
enabled = true
hackOnlineMode = true
secret = "PASTE_YOUR_VANGUERIA_SECRET_HERE"
The final step is to adjust the server.properties file. Because Vangueria handles the official Mojang authentication at the "front door," the backend server must be set to offline mode to allow the proxy to pass the authenticated user data through.
sed -i 's/online-mode=true/online-mode=false/' server.properties
With the configuration complete, the server should be launched inside a named screen session to ensure it remains active.
screen -S minecraft ./start.sh
We should now change the Pfsense port forward rule to forward traffic to the 192.168.100.29 (IP address of Vangueria) and then connecting a client from a laptop outside of Pfsense and using the address cherry.seaoffate.net, we can try using the IP address of the Pfsense WAN port but it may not work (if the default server is set to cherry it may connect)

===Additional Options===

There are a few additional considerations that will make the servers run more reliably. The first is thing that needs to be done is to run the server in a screen so that there does not need to be a SSH session to be running. The following will start a screen called minecraft and will execute the start.sh command.
screen -S minecraft ./start
To exit the minecraft screen and return to the main SSH type ctrl + a and then d, the minecraft screen can be reloaded with the command
screen -r minecraft
The next thing that we will need to do is to have the minecraft server start whenever the host reboots. So we need to add a cron tab to the start.sh
crontab -e
Select nano if asked then add the line
@reboot screen -dmS minecraft /home/nigel/minecraft_server/start.sh

The next thing is not a minecraft helper exactly but it will be useful as a reminder in the future. When a user logs on to the host the message of the day will be displayed to add simple notes to the message we can simply edit the motd with the command
sudo nano /etc/motd

===Adding a second Minecraft server Apple===

Now that we have the basic setup with potential for multiple hosts we will need to create at least one more so that we can prove the proxy works as intended. The next server will be a different version with some mods. As soon as we start adding mods to a Minecraft world they will use more resources so we will need the next host to be a bit better specified.

{| class="wikitable"
|+
|-
! Item !! Value !! Notes
|-
|CPU || 5 ||
|-
|RAM || 14GB ||
|-
|Swap || 16gb || Additional disk allocated from Lexar SSD
|-
|Storage || 150GB || Initially set at 32gb
|-
|Base OS || Debian 13.3 || Server version
|-
|Hostname || Apple||
|-
|IP Address || 192.168.100.35 ||
|}

====Hardware Configuration====

As we did with the cherry host earlier we need to configure the hardware changes that have been made on the basic specification like adding the Lexar HD as the swap file. We must stop using the swap partition on the primary drive so we can move it out of the way. Turn off all swap.
sudo swapoff -a
Since your swap partition (sda3) is at the end of the disk, it acts as a "blocker." We need to delete it and the root partition, then recreate the root partition to fill the entire space.
sudo fdisk /dev/sda
* Type p to print the table (confirming sda2 is root and sda3 is swap).
* Type d then 3 to delete the swap partition.
* Type d then 2 to delete the root partition (Don't worry, the data stays in the blocks).
* Step B: Recreate and Expand
* Type n for a new partition.
* Type p for Primary. Note if disk is using a GPT (GUID Partition Table) there will be no P option, primary partitions only exist in the old MBR style of disks
* Type 2 for Partition number 2.
* Press Enter for the default Start Sector (it must match the old start sector of sda2).
* Press Enter for the default End Sector (this will now jump to the end of the 150GB disk).
* CRITICAL: When it asks "Do you want to remove the signature?", type N.
* Type w to write changes and exit.
Now, reboot to make sure the kernel is looking at the new 150GB table entry.
sudo systemctl reboot
Once you log back in, expand the actual data "container" (the ext4 filesystem) to fill that new partition:
sudo resize2fs /dev/sda2
Now that the main drive is expanded, let's get that high-speed swap set up on your 16GB secondary disk.
sudo mkswap /dev/sdb
sudo swapon /dev/sdb
We need to update /etc/fstab so your VM knows where to find its memory "safety net" on every boot.
sudo nano /etc/fstab
Look for the line that mentions the old swap (it likely mentions sda3 or a long UUID string). Delete that line or put a # at the start of it. Add this new line at the bottom:
/dev/sdb none swap sw 0 0
Save and exit. Then to confirm the changes have been made use the following commands to show the new sda2 disk size and the swap disk
df -h
free -h

====Software installation====

Minecraft

2026-05-12T20:07:02Z

Wikisailor: /* Adding a second Minecraft server Apple */

==Introduction==

We are to have some Minecraft servers on the '''[[Home Lab]]''''. The general setup will be to have a Velocity server in front several Minecraft host '''[[Virtual Machines]]'''. Velocity works in a similar way to a Nginx reverse proxy whereby Pfsense forwards all Minecraft traffic to the Velocity server including the SNI and Velocity redirects traffic to the required hostname based on the DNS name. Cloudflare does not reverse proxy Minecraft traffic on the free tier and as we do not want to have to deal with random bots from the east so we will not leave the port open on the edge or Pfsense to random bots with port scanners. So we will use grey cloud at Cloudflare but DNS will point to a service like TCPShield and our firewalls only accept Minecraft traffic from their IP addresses and Velocity will only accept named servers and drop any unknown DNS names.

==Installation==

The installation will be in some distinct stages to enable each step to be proved to be working before proceeding to the next stage. First we setup a simple vanilla Minecraft server and set the firewall to port forward to it directly. Once that is proven to be working we will setup a Velocity server that will receive all 25565 traffic and forward it to the working Minecraft host. The next phase after the first host is getting traffic forwarded is to setup a second host and make sure velocity can forward to each, included in this step will be hardening the Velocity server with whatever security measures that it has available. When we are sure that Velocity is working properly we can work on the remote access stage, where we use TCPShield to proxy the service and have Cloudflare DNS only names setup with cherry.seaoffate.net and apple.seaoffate.net etc. From this point forward any new Minecraft servers will simply follow the same setup procedure.

===The First Minecraft Host Configuration===

The first Minecraft host needs to have enough resources to run the JVM and the server but as it just a vanilla server the specification does not need to be excessive. The table shows the highlights.

{| class="wikitable"
|+
|-
! Item !! Value !! Notes
|-
|CPU || 2 ||
|-
|RAM || 4GB ||
|-
|Swap || 16gb || Additional disk allocated from Lexar SSD
|-
|Storage || 96GB || Initially set at 32gb
|-
|Base OS || Debian 13.3 || Server version
|-
|Hostname || Cherry ||
|-
|IP Address || 192.168.100.30 ||
|}

====Hardware Configuration====
The Cherry host was created as a clone of the Debian template and then the basic specifications were improved so we will need to configure these extra items in the OS. First we need to identify the harddrive to use as the swap file
lsblk
The result is likely to show that the disk is likely to be /dev/sdb so we can set the swap space and enable it with
sudo mkswap /dev/sdb
sudo swapon /dev/sdb
To make the swap file persistent we edit the fstab
sudo nano /etc/fstab
Add the line:
/dev/sdb none swap sw 0 0
and remove or comment out the line that refers to
/dev/sda3
Before the storage sda main partition can be expanded to the full 96GB we have to remove the swap that is in the way so disable the existing swap with
sudo swapoff /dev/sda3
Open the disk utility to modify sda
sudo fdisk /dev/sda
Delete the swap partition with the option d, then type 3 to delete partition 3, then w to save and exit. The next thing to do is expand the Primary Root Partition so open fdisk again:
sudo fdisk /dev/sda
Delete the root partition:
* Type d (Delete)
* Type 2 (this only deletes the table entry, not the data).
* Type n (Create a new partition)
* Type p (Primary Partition)
* Type 2 (For Partition number 2)
* Type enter (Use default values for start sector)
* Type enter (Use default values for end sectors to fill the 96GB)
* CRITICAL: When asked if you want to remove the signature, type N.
* Type w (Save and exit)
To finalize Storage reboot to refresh the kernel partition table:
sudo systemctl reboot
When the VM reboots expand the filesystem into the new space:
sudo resize2fs /dev/sda2
We can verify the new swap and new sda size with
df -h
Now that the hardware is setup and configured we can proceed to the software installation

====Software Installation====

The software installation consists of updates, install the JVM and then install the Minecraft server. So to start as we do on most hosts with updates
sudo apt update
sudo apt upgrade
Install Necessary Utilities:
sudo apt install htop screen wget curl -y
Install Java 25:
sudo apt install openjdk-25-jre-headless -y
Verify Java Installation (Ensure it reports OpenJDK 25)
java -version
Now we install the Minecraft server

Create the Server Directory:
mkdir ~/minecraft_server && cd ~/minecraft_server
Download the Server Software:
wget -O server.jar [https://piston-data.mojang.com/v1/objects/97ccd4c0ed3f81bbb7bfacddd1090b0c56f9bc51/server.jar](https://piston-data.mojang.com/v1/objects/97ccd4c0ed3f81bbb7bfacddd1090b0c56f9bc51/server.jar)
Assuming the file downloaded we need an initial run to generate the file:
java -Xms1G -Xmx1G -jar server.jar nogui
When the file is first created it will not run until we Accept the EULA with the command:
sed -i 's/eula=false/eula=true/' eula.txt
We can create the Start Script:
nano start.sh
Paste in the following
<nowiki> #!/bin/bash
while true
do
echo "--- Starting Minecraft Server ---"
java -Xms3G -Xmx3G \
--enable-native-access=ALL-UNNAMED \
-XX:+UseG1GC \
-XX:MaxGCPauseMillis=200 \
-XX:+UnlockExperimentalVMOptions \
-XX:+DisableExplicitGC \
-XX:+AlwaysPreTouch \
-jar server.jar nogui
echo "--- Server stopped. Restarting in 5 seconds (Ctrl+C to cancel) ---"
sleep 5
done</nowiki>
Set the script to execute with
chmod +x start.sh
We can start the server with
./start.sh
'''Note''' we can type the command stop in the terminal and the server will save the world and stop it for 5 seconds during the 5 seconds, if we type ctrl+c it will end the script or if we just leave it the server will restart.

====Enable External Access====

We will need to access the server from outside world so we should forward the Minecraft port 25565 to the IP address of cherry. To make the port forward rules in Pfsense easier to understand we add an alias for cherry's IP address and a port alias for 25565. We add a port forward rule to Pfsense that says source IP 192.168.0.0/16 and any port, destination this firewall (self) Destination port Minecraft_standard, redirect IP_cherry port Minecraft_standard.

====Testing====

With this configuration loading a Minecraft client and setting the destination server to the WAN port IP address it will connect to the cherry host.

As part of the wider LAN setup we added a Adguard LXC to manage DNS. Part of the Adguard configuration was made to avoid the hairpin network access so a DNS redirect was made to forward *.seaoffate.net to Pfsense WAN and as the default domain name was set to seaoffate.net. So now when we have a destination of cherry Adguard will translate the hostname to cherry.seaoffate.net and redirect it to Pfsense, Pfsense will then forward to the relevant server. If that does not work as expected the next test would be to set the destination to cherry.seaoffate.net which should be redirected by Adguard.

===Velocity Installation===

The Velocity server VM does not need to be especially high because all it needs to do is accept connections and forward them on to the relevant host and any associated functions like handle logon, bans and etc. Unlike the cherry host that we just setup the base specification from the Debian template needs to be cut down a bit and does not need a extra swap file or anything special.

{| class="wikitable"
|+
|-
! Item !! Value !! Notes
|-
|CPU || 1 ||
|-
|RAM || 1GB ||
|-
|Storage || 32GB ||
|-
|Base OS || Debian 13.3 || Server version
|-
|Hostname || Vangueria ||
|-
|IP Address || 192.168.100.29 ||
|}
====Software Installation====

As there is no additions to the VM's specification there is no hardware to configure so we can get straight to the software installation. So the well known update/upgrade and the packages can be installed with
sudo apt update && sudo apt upgrade -y
sudo apt install -y openjdk-25-jre-headless htop screen wget jq curl
Once the dependencies are installed, we create a dedicated application directory and use an automated script to identify the most recent build of Velocity 3.4.0. This ensures we are not relying on hardcoded links that may expire.
mkdir ~/velocity && cd ~/velocity
export PROJECT="velocity"
export VERSION="3.4.0-SNAPSHOT"
export LATEST_BUILD=$(curl -s https://api.papermc.io/v2/projects/${PROJECT}/versions/${VERSION} | jq '.builds[-1]')
wget -O ~/velocity/velocity.jar "https://api.papermc.io/v2/projects/${PROJECT}/versions/${VERSION}/builds/${LATEST_BUILD}/downloads/${PROJECT}-${VERSION}-${LATEST_BUILD}.jar"
The initial boot of Velocity is performed to generate the necessary configuration files. We launch it with a 512MB heap size and then shut it down gracefully using the end command once the prompt appears.
java -Xms512M -Xmx512M -jar velocity.jar

====Proxy Configuration and Routing====

The primary configuration for the proxy is handled within the velocity.toml file. This file dictates how the proxy listens for incoming traffic and how it maps domain names to internal IP addresses. We edit this file to ensure the proxy is listening on all interfaces and that it is using the modern forwarding protocol.
nano ~/velocity/velocity.toml
Modify these specific lines:
* Bind Address: bind = "0.0.0.0:25565" (Allows it to hear traffic from pfSense).
* Forwarding Mode: player-info-forwarding-mode = "modern" (This is the most secure protocol for 2026).
* ping-passthrough should be set to ALL. This is to ensure the server list on the Minecraft client correctly displays the status and version of the backend servers
* Server List: Scroll down to the [servers] section:
<nowiki>[servers]
cherry = "192.168.100.30:25565"
apple = "192.168.100.35:25565"

[servers]
try = [
"cherry"
]</nowiki>
* Forced Hosts: This tells the proxy which server to pick based on the URL the player typed:
<nowiki>[forced-hosts]
"cherry.seaoffate.net" = ["cherry"]
"apple.seaoffate.net" = ["apple"]</nowiki>
Save and close the file. next we need a start.sh file for Velocity
nano ~/velocity/start.sh
copy the following into the file
<nowiki> #!/bin/bash
while true
do
echo "--- Starting Vangueria Proxy ---"
java -Xms512M -Xmx512M \
-XX:+UseG1GC \
-XX:MaxGCPauseMillis=200 \
-XX:+UnlockExperimentalVMOptions \
-XX:+DisableExplicitGC \
-XX:+AlwaysPreTouch \
-jar velocity.jar
echo "--- Proxy stopped. Restarting in 5s ---"
sleep 5
done</nowiki>
To make the script executable
chmod +x ~/velocity/start.sh
At this point the since Vangueria is now set to Modern Forwarding, Cherry will reject all connections until it has the forwarding.secret. the secret can be obtained with the command
cat ~/velocity/forwarding.secret
Copy the code to a safe location because we will need it to setup cherry (and apple). then we should be able to finally start the proxy with the start.sh
./start.sh
Now we move to cherry to setup it's ability to receive connections from Vangueria.

====Configuring Cherry To Accept Proxied Connections====

To complete the integration between the proxy and the backend, Cherry must be transitioned from a standalone Vanilla server to a "Proxy-Aware" host. Because Vanilla Minecraft does not natively support Velocity’s Modern Forwarding (the security handshake), we use the Fabric Loader as a lightweight wrapper. This allows us to install a bridge mod that validates the secret key without changing the gameplay experience.The transition of Cherry involves three main phases: installing the Fabric environment, adding the bridge mods, and configuring the security handshake to match Vangueria.

First, we must stop the existing server and install the Fabric transition layer. This replaces the standard Mojang launcher with a version capable of loading the security bridge. We need to download the Fabric Installer and then Install Fabric for the 1.21.1 environment.
cd ~/minecraft_server
wget https://maven.fabricmc.net/net/fabricmc/fabric-installer/1.0.1/fabric-installer-1.0.1.jar
java -jar fabric-installer-1.0.1.jar server -mcversion 1.21.1 -downloadMinecraft
Once complete, the installer will have created a new file named fabric-server-launch.jar. This is now the primary entry point for the server.

To install the Security Bridge we require two specific components in the mods folder: the Fabric API (the library that allows mods to interact with the game engine) and FabricProxy-Lite (the specific mod that handles the Velocity secret key). It is vital to use version-matched JARs for 1.21.1 to ensure stability.
mkdir -p ~/minecraft_server/mods
wget -O ~/minecraft_server/mods/FabricProxy-Lite.jar https://github.com/OKTW-Network/FabricProxy-Lite/releases/download/v2.10.1/FabricProxy-Lite-2.10.1.jar
wget -O ~/minecraft_server/mods/fabric-api.jar https://github.com/FabricMC/fabric-api/releases/download/0.116.11%2B1.21.1/fabric-api-0.116.11+1.21.1.jar

To configure the handshake after placing the mods, we must run the server once to generate the configuration structure, then shut it down to inject the secret.
Update start.sh to point to fabric-server-launch.jar instead of server.jar
sed -i 's/server.jar/fabric-server-launch.jar/' start.sh
Initial run to generate config (Type 'stop' once the 'Done' message appears)
./start.sh
Now, we create the configuration file and link it to Vangueria. This is where we ensure the backend only trusts traffic coming from our proxy.
mkdir -p ~/minecraft_server/config
nano ~/minecraft_server/config/FabricProxy-Lite.toml
Paste the following configuration into the file, ensuring the secret matches the one obtained from Vangueria:
enabled = true
hackOnlineMode = true
secret = "PASTE_YOUR_VANGUERIA_SECRET_HERE"
The final step is to adjust the server.properties file. Because Vangueria handles the official Mojang authentication at the "front door," the backend server must be set to offline mode to allow the proxy to pass the authenticated user data through.
sed -i 's/online-mode=true/online-mode=false/' server.properties
With the configuration complete, the server should be launched inside a named screen session to ensure it remains active.
screen -S minecraft ./start.sh
We should now change the Pfsense port forward rule to forward traffic to the 192.168.100.29 (IP address of Vangueria) and then connecting a client from a laptop outside of Pfsense and using the address cherry.seaoffate.net, we can try using the IP address of the Pfsense WAN port but it may not work (if the default server is set to cherry it may connect)

===Additional Options===

There are a few additional considerations that will make the servers run more reliably. The first is thing that needs to be done is to run the server in a screen so that there does not need to be a SSH session to be running. The following will start a screen called minecraft and will execute the start.sh command.
screen -S minecraft ./start
To exit the minecraft screen and return to the main SSH type ctrl + a and then d, the minecraft screen can be reloaded with the command
screen -r minecraft
The next thing that we will need to do is to have the minecraft server start whenever the host reboots. So we need to add a cron tab to the start.sh
crontab -e
Select nano if asked then add the line
@reboot screen -dmS minecraft /home/nigel/minecraft_server/start.sh

The next thing is not a minecraft helper exactly but it will be useful as a reminder in the future. When a user logs on to the host the message of the day will be displayed to add simple notes to the message we can simply edit the motd with the command
sudo nano /etc/motd

===Adding a second Minecraft server Apple===

Now that we have the basic setup with potential for multiple hosts we will need to create at least one more so that we can prove the proxy works as intended. The next server will be a different version with some mods. As soon as we start adding mods to a Minecraft world they will use more resources so we will need the next host to be a bit better specified.

{| class="wikitable"
|+
|-
! Item !! Value !! Notes
|-
|CPU || 5 ||
|-
|RAM || 14GB ||
|-
|Swap || 16gb || Additional disk allocated from Lexar SSD
|-
|Storage || 150GB || Initially set at 32gb
|-
|Base OS || Debian 13.3 || Server version
|-
|Hostname || Apple||
|-
|IP Address || 192.168.100.35 ||
|}

====Hardware Configuration====

As we did with the cherry host earlier we need to configure the hardware changes that have been made on the basic specification like adding the Lexar HD as the swap file. The fast config of the swap is to initialize the partition as swap, enable the swap immediately and add to /etc/fstab for persistence

Minecraft

2026-05-12T18:50:56Z

Wikisailor: /* Adding a second Minecraft server Apple */

==Introduction==

We are to have some Minecraft servers on the '''[[Home Lab]]''''. The general setup will be to have a Velocity server in front several Minecraft host '''[[Virtual Machines]]'''. Velocity works in a similar way to a Nginx reverse proxy whereby Pfsense forwards all Minecraft traffic to the Velocity server including the SNI and Velocity redirects traffic to the required hostname based on the DNS name. Cloudflare does not reverse proxy Minecraft traffic on the free tier and as we do not want to have to deal with random bots from the east so we will not leave the port open on the edge or Pfsense to random bots with port scanners. So we will use grey cloud at Cloudflare but DNS will point to a service like TCPShield and our firewalls only accept Minecraft traffic from their IP addresses and Velocity will only accept named servers and drop any unknown DNS names.

==Installation==

The installation will be in some distinct stages to enable each step to be proved to be working before proceeding to the next stage. First we setup a simple vanilla Minecraft server and set the firewall to port forward to it directly. Once that is proven to be working we will setup a Velocity server that will receive all 25565 traffic and forward it to the working Minecraft host. The next phase after the first host is getting traffic forwarded is to setup a second host and make sure velocity can forward to each, included in this step will be hardening the Velocity server with whatever security measures that it has available. When we are sure that Velocity is working properly we can work on the remote access stage, where we use TCPShield to proxy the service and have Cloudflare DNS only names setup with cherry.seaoffate.net and apple.seaoffate.net etc. From this point forward any new Minecraft servers will simply follow the same setup procedure.

===The First Minecraft Host Configuration===

The first Minecraft host needs to have enough resources to run the JVM and the server but as it just a vanilla server the specification does not need to be excessive. The table shows the highlights.

{| class="wikitable"
|+
|-
! Item !! Value !! Notes
|-
|CPU || 2 ||
|-
|RAM || 4GB ||
|-
|Swap || 16gb || Additional disk allocated from Lexar SSD
|-
|Storage || 96GB || Initially set at 32gb
|-
|Base OS || Debian 13.3 || Server version
|-
|Hostname || Cherry ||
|-
|IP Address || 192.168.100.30 ||
|}

====Hardware Configuration====
The Cherry host was created as a clone of the Debian template and then the basic specifications were improved so we will need to configure these extra items in the OS. First we need to identify the harddrive to use as the swap file
lsblk
The result is likely to show that the disk is likely to be /dev/sdb so we can set the swap space and enable it with
sudo mkswap /dev/sdb
sudo swapon /dev/sdb
To make the swap file persistent we edit the fstab
sudo nano /etc/fstab
Add the line:
/dev/sdb none swap sw 0 0
and remove or comment out the line that refers to
/dev/sda3
Before the storage sda main partition can be expanded to the full 96GB we have to remove the swap that is in the way so disable the existing swap with
sudo swapoff /dev/sda3
Open the disk utility to modify sda
sudo fdisk /dev/sda
Delete the swap partition with the option d, then type 3 to delete partition 3, then w to save and exit. The next thing to do is expand the Primary Root Partition so open fdisk again:
sudo fdisk /dev/sda
Delete the root partition:
* Type d (Delete)
* Type 2 (this only deletes the table entry, not the data).
* Type n (Create a new partition)
* Type p (Primary Partition)
* Type 2 (For Partition number 2)
* Type enter (Use default values for start sector)
* Type enter (Use default values for end sectors to fill the 96GB)
* CRITICAL: When asked if you want to remove the signature, type N.
* Type w (Save and exit)
To finalize Storage reboot to refresh the kernel partition table:
sudo systemctl reboot
When the VM reboots expand the filesystem into the new space:
sudo resize2fs /dev/sda2
We can verify the new swap and new sda size with
df -h
Now that the hardware is setup and configured we can proceed to the software installation

====Software Installation====

The software installation consists of updates, install the JVM and then install the Minecraft server. So to start as we do on most hosts with updates
sudo apt update
sudo apt upgrade
Install Necessary Utilities:
sudo apt install htop screen wget curl -y
Install Java 25:
sudo apt install openjdk-25-jre-headless -y
Verify Java Installation (Ensure it reports OpenJDK 25)
java -version
Now we install the Minecraft server

Create the Server Directory:
mkdir ~/minecraft_server && cd ~/minecraft_server
Download the Server Software:
wget -O server.jar [https://piston-data.mojang.com/v1/objects/97ccd4c0ed3f81bbb7bfacddd1090b0c56f9bc51/server.jar](https://piston-data.mojang.com/v1/objects/97ccd4c0ed3f81bbb7bfacddd1090b0c56f9bc51/server.jar)
Assuming the file downloaded we need an initial run to generate the file:
java -Xms1G -Xmx1G -jar server.jar nogui
When the file is first created it will not run until we Accept the EULA with the command:
sed -i 's/eula=false/eula=true/' eula.txt
We can create the Start Script:
nano start.sh
Paste in the following
<nowiki> #!/bin/bash
while true
do
echo "--- Starting Minecraft Server ---"
java -Xms3G -Xmx3G \
--enable-native-access=ALL-UNNAMED \
-XX:+UseG1GC \
-XX:MaxGCPauseMillis=200 \
-XX:+UnlockExperimentalVMOptions \
-XX:+DisableExplicitGC \
-XX:+AlwaysPreTouch \
-jar server.jar nogui
echo "--- Server stopped. Restarting in 5 seconds (Ctrl+C to cancel) ---"
sleep 5
done</nowiki>
Set the script to execute with
chmod +x start.sh
We can start the server with
./start.sh
'''Note''' we can type the command stop in the terminal and the server will save the world and stop it for 5 seconds during the 5 seconds, if we type ctrl+c it will end the script or if we just leave it the server will restart.

====Enable External Access====

We will need to access the server from outside world so we should forward the Minecraft port 25565 to the IP address of cherry. To make the port forward rules in Pfsense easier to understand we add an alias for cherry's IP address and a port alias for 25565. We add a port forward rule to Pfsense that says source IP 192.168.0.0/16 and any port, destination this firewall (self) Destination port Minecraft_standard, redirect IP_cherry port Minecraft_standard.

====Testing====

With this configuration loading a Minecraft client and setting the destination server to the WAN port IP address it will connect to the cherry host.

As part of the wider LAN setup we added a Adguard LXC to manage DNS. Part of the Adguard configuration was made to avoid the hairpin network access so a DNS redirect was made to forward *.seaoffate.net to Pfsense WAN and as the default domain name was set to seaoffate.net. So now when we have a destination of cherry Adguard will translate the hostname to cherry.seaoffate.net and redirect it to Pfsense, Pfsense will then forward to the relevant server. If that does not work as expected the next test would be to set the destination to cherry.seaoffate.net which should be redirected by Adguard.

===Velocity Installation===

The Velocity server VM does not need to be especially high because all it needs to do is accept connections and forward them on to the relevant host and any associated functions like handle logon, bans and etc. Unlike the cherry host that we just setup the base specification from the Debian template needs to be cut down a bit and does not need a extra swap file or anything special.

{| class="wikitable"
|+
|-
! Item !! Value !! Notes
|-
|CPU || 1 ||
|-
|RAM || 1GB ||
|-
|Storage || 32GB ||
|-
|Base OS || Debian 13.3 || Server version
|-
|Hostname || Vangueria ||
|-
|IP Address || 192.168.100.29 ||
|}
====Software Installation====

As there is no additions to the VM's specification there is no hardware to configure so we can get straight to the software installation. So the well known update/upgrade and the packages can be installed with
sudo apt update && sudo apt upgrade -y
sudo apt install -y openjdk-25-jre-headless htop screen wget jq curl
Once the dependencies are installed, we create a dedicated application directory and use an automated script to identify the most recent build of Velocity 3.4.0. This ensures we are not relying on hardcoded links that may expire.
mkdir ~/velocity && cd ~/velocity
export PROJECT="velocity"
export VERSION="3.4.0-SNAPSHOT"
export LATEST_BUILD=$(curl -s https://api.papermc.io/v2/projects/${PROJECT}/versions/${VERSION} | jq '.builds[-1]')
wget -O ~/velocity/velocity.jar "https://api.papermc.io/v2/projects/${PROJECT}/versions/${VERSION}/builds/${LATEST_BUILD}/downloads/${PROJECT}-${VERSION}-${LATEST_BUILD}.jar"
The initial boot of Velocity is performed to generate the necessary configuration files. We launch it with a 512MB heap size and then shut it down gracefully using the end command once the prompt appears.
java -Xms512M -Xmx512M -jar velocity.jar

====Proxy Configuration and Routing====

The primary configuration for the proxy is handled within the velocity.toml file. This file dictates how the proxy listens for incoming traffic and how it maps domain names to internal IP addresses. We edit this file to ensure the proxy is listening on all interfaces and that it is using the modern forwarding protocol.
nano ~/velocity/velocity.toml
Modify these specific lines:
* Bind Address: bind = "0.0.0.0:25565" (Allows it to hear traffic from pfSense).
* Forwarding Mode: player-info-forwarding-mode = "modern" (This is the most secure protocol for 2026).
* ping-passthrough should be set to ALL. This is to ensure the server list on the Minecraft client correctly displays the status and version of the backend servers
* Server List: Scroll down to the [servers] section:
<nowiki>[servers]
cherry = "192.168.100.30:25565"
apple = "192.168.100.35:25565"

[servers]
try = [
"cherry"
]</nowiki>
* Forced Hosts: This tells the proxy which server to pick based on the URL the player typed:
<nowiki>[forced-hosts]
"cherry.seaoffate.net" = ["cherry"]
"apple.seaoffate.net" = ["apple"]</nowiki>
Save and close the file. next we need a start.sh file for Velocity
nano ~/velocity/start.sh
copy the following into the file
<nowiki> #!/bin/bash
while true
do
echo "--- Starting Vangueria Proxy ---"
java -Xms512M -Xmx512M \
-XX:+UseG1GC \
-XX:MaxGCPauseMillis=200 \
-XX:+UnlockExperimentalVMOptions \
-XX:+DisableExplicitGC \
-XX:+AlwaysPreTouch \
-jar velocity.jar
echo "--- Proxy stopped. Restarting in 5s ---"
sleep 5
done</nowiki>
To make the script executable
chmod +x ~/velocity/start.sh
At this point the since Vangueria is now set to Modern Forwarding, Cherry will reject all connections until it has the forwarding.secret. the secret can be obtained with the command
cat ~/velocity/forwarding.secret
Copy the code to a safe location because we will need it to setup cherry (and apple). then we should be able to finally start the proxy with the start.sh
./start.sh
Now we move to cherry to setup it's ability to receive connections from Vangueria.

====Configuring Cherry To Accept Proxied Connections====

To complete the integration between the proxy and the backend, Cherry must be transitioned from a standalone Vanilla server to a "Proxy-Aware" host. Because Vanilla Minecraft does not natively support Velocity’s Modern Forwarding (the security handshake), we use the Fabric Loader as a lightweight wrapper. This allows us to install a bridge mod that validates the secret key without changing the gameplay experience.The transition of Cherry involves three main phases: installing the Fabric environment, adding the bridge mods, and configuring the security handshake to match Vangueria.

First, we must stop the existing server and install the Fabric transition layer. This replaces the standard Mojang launcher with a version capable of loading the security bridge. We need to download the Fabric Installer and then Install Fabric for the 1.21.1 environment.
cd ~/minecraft_server
wget https://maven.fabricmc.net/net/fabricmc/fabric-installer/1.0.1/fabric-installer-1.0.1.jar
java -jar fabric-installer-1.0.1.jar server -mcversion 1.21.1 -downloadMinecraft
Once complete, the installer will have created a new file named fabric-server-launch.jar. This is now the primary entry point for the server.

To install the Security Bridge we require two specific components in the mods folder: the Fabric API (the library that allows mods to interact with the game engine) and FabricProxy-Lite (the specific mod that handles the Velocity secret key). It is vital to use version-matched JARs for 1.21.1 to ensure stability.
mkdir -p ~/minecraft_server/mods
wget -O ~/minecraft_server/mods/FabricProxy-Lite.jar https://github.com/OKTW-Network/FabricProxy-Lite/releases/download/v2.10.1/FabricProxy-Lite-2.10.1.jar
wget -O ~/minecraft_server/mods/fabric-api.jar https://github.com/FabricMC/fabric-api/releases/download/0.116.11%2B1.21.1/fabric-api-0.116.11+1.21.1.jar

To configure the handshake after placing the mods, we must run the server once to generate the configuration structure, then shut it down to inject the secret.
Update start.sh to point to fabric-server-launch.jar instead of server.jar
sed -i 's/server.jar/fabric-server-launch.jar/' start.sh
Initial run to generate config (Type 'stop' once the 'Done' message appears)
./start.sh
Now, we create the configuration file and link it to Vangueria. This is where we ensure the backend only trusts traffic coming from our proxy.
mkdir -p ~/minecraft_server/config
nano ~/minecraft_server/config/FabricProxy-Lite.toml
Paste the following configuration into the file, ensuring the secret matches the one obtained from Vangueria:
enabled = true
hackOnlineMode = true
secret = "PASTE_YOUR_VANGUERIA_SECRET_HERE"
The final step is to adjust the server.properties file. Because Vangueria handles the official Mojang authentication at the "front door," the backend server must be set to offline mode to allow the proxy to pass the authenticated user data through.
sed -i 's/online-mode=true/online-mode=false/' server.properties
With the configuration complete, the server should be launched inside a named screen session to ensure it remains active.
screen -S minecraft ./start.sh
We should now change the Pfsense port forward rule to forward traffic to the 192.168.100.29 (IP address of Vangueria) and then connecting a client from a laptop outside of Pfsense and using the address cherry.seaoffate.net, we can try using the IP address of the Pfsense WAN port but it may not work (if the default server is set to cherry it may connect)

===Additional Options===

There are a few additional considerations that will make the servers run more reliably. The first is thing that needs to be done is to run the server in a screen so that there does not need to be a SSH session to be running. The following will start a screen called minecraft and will execute the start.sh command.
screen -S minecraft ./start
To exit the minecraft screen and return to the main SSH type ctrl + a and then d, the minecraft screen can be reloaded with the command
screen -r minecraft
The next thing that we will need to do is to have the minecraft server start whenever the host reboots. So we need to add a cron tab to the start.sh
crontab -e
Select nano if asked then add the line
@reboot screen -dmS minecraft /home/nigel/minecraft_server/start.sh

The next thing is not a minecraft helper exactly but it will be useful as a reminder in the future. When a user logs on to the host the message of the day will be displayed to add simple notes to the message we can simply edit the motd with the command
sudo nano /etc/motd

===Adding a second Minecraft server Apple===

Now that we have the basic setup with potential for multiple hosts we will need to create at least one more so that we can prove the proxy works as intended. The next server will be a different version with some mods. As soon as we start adding mods to a Minecraft world they will use more resources so we will need the next host to be a bit better specified.

{| class="wikitable"
|+
|-
! Item !! Value !! Notes
|-
|CPU || 5 ||
|-
|RAM || 14GB ||
|-
|Swap || 16gb || Additional disk allocated from Lexar SSD
|-
|Storage || 150GB || Initially set at 32gb
|-
|Base OS || Debian 13.3 || Server version
|-
|Hostname || Apple||
|-
|IP Address || 192.168.100.35 ||
|}

Minecraft

2026-05-12T18:24:58Z

Wikisailor: /* Adding a second Minecraft server Apple */

==Introduction==

We are to have some Minecraft servers on the '''[[Home Lab]]''''. The general setup will be to have a Velocity server in front several Minecraft host '''[[Virtual Machines]]'''. Velocity works in a similar way to a Nginx reverse proxy whereby Pfsense forwards all Minecraft traffic to the Velocity server including the SNI and Velocity redirects traffic to the required hostname based on the DNS name. Cloudflare does not reverse proxy Minecraft traffic on the free tier and as we do not want to have to deal with random bots from the east so we will not leave the port open on the edge or Pfsense to random bots with port scanners. So we will use grey cloud at Cloudflare but DNS will point to a service like TCPShield and our firewalls only accept Minecraft traffic from their IP addresses and Velocity will only accept named servers and drop any unknown DNS names.

==Installation==

The installation will be in some distinct stages to enable each step to be proved to be working before proceeding to the next stage. First we setup a simple vanilla Minecraft server and set the firewall to port forward to it directly. Once that is proven to be working we will setup a Velocity server that will receive all 25565 traffic and forward it to the working Minecraft host. The next phase after the first host is getting traffic forwarded is to setup a second host and make sure velocity can forward to each, included in this step will be hardening the Velocity server with whatever security measures that it has available. When we are sure that Velocity is working properly we can work on the remote access stage, where we use TCPShield to proxy the service and have Cloudflare DNS only names setup with cherry.seaoffate.net and apple.seaoffate.net etc. From this point forward any new Minecraft servers will simply follow the same setup procedure.

===The First Minecraft Host Configuration===

The first Minecraft host needs to have enough resources to run the JVM and the server but as it just a vanilla server the specification does not need to be excessive. The table shows the highlights.

{| class="wikitable"
|+
|-
! Item !! Value !! Notes
|-
|CPU || 2 ||
|-
|RAM || 4GB ||
|-
|Swap || 16gb || Additional disk allocated from Lexar SSD
|-
|Storage || 96GB || Initially set at 32gb
|-
|Base OS || Debian 13.3 || Server version
|-
|Hostname || Cherry ||
|-
|IP Address || 192.168.100.30 ||
|}

====Hardware Configuration====
The Cherry host was created as a clone of the Debian template and then the basic specifications were improved so we will need to configure these extra items in the OS. First we need to identify the harddrive to use as the swap file
lsblk
The result is likely to show that the disk is likely to be /dev/sdb so we can set the swap space and enable it with
sudo mkswap /dev/sdb
sudo swapon /dev/sdb
To make the swap file persistent we edit the fstab
sudo nano /etc/fstab
Add the line:
/dev/sdb none swap sw 0 0
and remove or comment out the line that refers to
/dev/sda3
Before the storage sda main partition can be expanded to the full 96GB we have to remove the swap that is in the way so disable the existing swap with
sudo swapoff /dev/sda3
Open the disk utility to modify sda
sudo fdisk /dev/sda
Delete the swap partition with the option d, then type 3 to delete partition 3, then w to save and exit. The next thing to do is expand the Primary Root Partition so open fdisk again:
sudo fdisk /dev/sda
Delete the root partition:
* Type d (Delete)
* Type 2 (this only deletes the table entry, not the data).
* Type n (Create a new partition)
* Type p (Primary Partition)
* Type 2 (For Partition number 2)
* Type enter (Use default values for start sector)
* Type enter (Use default values for end sectors to fill the 96GB)
* CRITICAL: When asked if you want to remove the signature, type N.
* Type w (Save and exit)
To finalize Storage reboot to refresh the kernel partition table:
sudo systemctl reboot
When the VM reboots expand the filesystem into the new space:
sudo resize2fs /dev/sda2
We can verify the new swap and new sda size with
df -h
Now that the hardware is setup and configured we can proceed to the software installation

====Software Installation====

The software installation consists of updates, install the JVM and then install the Minecraft server. So to start as we do on most hosts with updates
sudo apt update
sudo apt upgrade
Install Necessary Utilities:
sudo apt install htop screen wget curl -y
Install Java 25:
sudo apt install openjdk-25-jre-headless -y
Verify Java Installation (Ensure it reports OpenJDK 25)
java -version
Now we install the Minecraft server

Create the Server Directory:
mkdir ~/minecraft_server && cd ~/minecraft_server
Download the Server Software:
wget -O server.jar [https://piston-data.mojang.com/v1/objects/97ccd4c0ed3f81bbb7bfacddd1090b0c56f9bc51/server.jar](https://piston-data.mojang.com/v1/objects/97ccd4c0ed3f81bbb7bfacddd1090b0c56f9bc51/server.jar)
Assuming the file downloaded we need an initial run to generate the file:
java -Xms1G -Xmx1G -jar server.jar nogui
When the file is first created it will not run until we Accept the EULA with the command:
sed -i 's/eula=false/eula=true/' eula.txt
We can create the Start Script:
nano start.sh
Paste in the following
<nowiki> #!/bin/bash
while true
do
echo "--- Starting Minecraft Server ---"
java -Xms3G -Xmx3G \
--enable-native-access=ALL-UNNAMED \
-XX:+UseG1GC \
-XX:MaxGCPauseMillis=200 \
-XX:+UnlockExperimentalVMOptions \
-XX:+DisableExplicitGC \
-XX:+AlwaysPreTouch \
-jar server.jar nogui
echo "--- Server stopped. Restarting in 5 seconds (Ctrl+C to cancel) ---"
sleep 5
done</nowiki>
Set the script to execute with
chmod +x start.sh
We can start the server with
./start.sh
'''Note''' we can type the command stop in the terminal and the server will save the world and stop it for 5 seconds during the 5 seconds, if we type ctrl+c it will end the script or if we just leave it the server will restart.

====Enable External Access====

We will need to access the server from outside world so we should forward the Minecraft port 25565 to the IP address of cherry. To make the port forward rules in Pfsense easier to understand we add an alias for cherry's IP address and a port alias for 25565. We add a port forward rule to Pfsense that says source IP 192.168.0.0/16 and any port, destination this firewall (self) Destination port Minecraft_standard, redirect IP_cherry port Minecraft_standard.

====Testing====

With this configuration loading a Minecraft client and setting the destination server to the WAN port IP address it will connect to the cherry host.

As part of the wider LAN setup we added a Adguard LXC to manage DNS. Part of the Adguard configuration was made to avoid the hairpin network access so a DNS redirect was made to forward *.seaoffate.net to Pfsense WAN and as the default domain name was set to seaoffate.net. So now when we have a destination of cherry Adguard will translate the hostname to cherry.seaoffate.net and redirect it to Pfsense, Pfsense will then forward to the relevant server. If that does not work as expected the next test would be to set the destination to cherry.seaoffate.net which should be redirected by Adguard.

===Velocity Installation===

The Velocity server VM does not need to be especially high because all it needs to do is accept connections and forward them on to the relevant host and any associated functions like handle logon, bans and etc. Unlike the cherry host that we just setup the base specification from the Debian template needs to be cut down a bit and does not need a extra swap file or anything special.

{| class="wikitable"
|+
|-
! Item !! Value !! Notes
|-
|CPU || 1 ||
|-
|RAM || 1GB ||
|-
|Storage || 32GB ||
|-
|Base OS || Debian 13.3 || Server version
|-
|Hostname || Vangueria ||
|-
|IP Address || 192.168.100.29 ||
|}
====Software Installation====

As there is no additions to the VM's specification there is no hardware to configure so we can get straight to the software installation. So the well known update/upgrade and the packages can be installed with
sudo apt update && sudo apt upgrade -y
sudo apt install -y openjdk-25-jre-headless htop screen wget jq curl
Once the dependencies are installed, we create a dedicated application directory and use an automated script to identify the most recent build of Velocity 3.4.0. This ensures we are not relying on hardcoded links that may expire.
mkdir ~/velocity && cd ~/velocity
export PROJECT="velocity"
export VERSION="3.4.0-SNAPSHOT"
export LATEST_BUILD=$(curl -s https://api.papermc.io/v2/projects/${PROJECT}/versions/${VERSION} | jq '.builds[-1]')
wget -O ~/velocity/velocity.jar "https://api.papermc.io/v2/projects/${PROJECT}/versions/${VERSION}/builds/${LATEST_BUILD}/downloads/${PROJECT}-${VERSION}-${LATEST_BUILD}.jar"
The initial boot of Velocity is performed to generate the necessary configuration files. We launch it with a 512MB heap size and then shut it down gracefully using the end command once the prompt appears.
java -Xms512M -Xmx512M -jar velocity.jar

====Proxy Configuration and Routing====

The primary configuration for the proxy is handled within the velocity.toml file. This file dictates how the proxy listens for incoming traffic and how it maps domain names to internal IP addresses. We edit this file to ensure the proxy is listening on all interfaces and that it is using the modern forwarding protocol.
nano ~/velocity/velocity.toml
Modify these specific lines:
* Bind Address: bind = "0.0.0.0:25565" (Allows it to hear traffic from pfSense).
* Forwarding Mode: player-info-forwarding-mode = "modern" (This is the most secure protocol for 2026).
* ping-passthrough should be set to ALL. This is to ensure the server list on the Minecraft client correctly displays the status and version of the backend servers
* Server List: Scroll down to the [servers] section:
<nowiki>[servers]
cherry = "192.168.100.30:25565"
apple = "192.168.100.35:25565"

[servers]
try = [
"cherry"
]</nowiki>
* Forced Hosts: This tells the proxy which server to pick based on the URL the player typed:
<nowiki>[forced-hosts]
"cherry.seaoffate.net" = ["cherry"]
"apple.seaoffate.net" = ["apple"]</nowiki>
Save and close the file. next we need a start.sh file for Velocity
nano ~/velocity/start.sh
copy the following into the file
<nowiki> #!/bin/bash
while true
do
echo "--- Starting Vangueria Proxy ---"
java -Xms512M -Xmx512M \
-XX:+UseG1GC \
-XX:MaxGCPauseMillis=200 \
-XX:+UnlockExperimentalVMOptions \
-XX:+DisableExplicitGC \
-XX:+AlwaysPreTouch \
-jar velocity.jar
echo "--- Proxy stopped. Restarting in 5s ---"
sleep 5
done</nowiki>
To make the script executable
chmod +x ~/velocity/start.sh
At this point the since Vangueria is now set to Modern Forwarding, Cherry will reject all connections until it has the forwarding.secret. the secret can be obtained with the command
cat ~/velocity/forwarding.secret
Copy the code to a safe location because we will need it to setup cherry (and apple). then we should be able to finally start the proxy with the start.sh
./start.sh
Now we move to cherry to setup it's ability to receive connections from Vangueria.

====Configuring Cherry To Accept Proxied Connections====

To complete the integration between the proxy and the backend, Cherry must be transitioned from a standalone Vanilla server to a "Proxy-Aware" host. Because Vanilla Minecraft does not natively support Velocity’s Modern Forwarding (the security handshake), we use the Fabric Loader as a lightweight wrapper. This allows us to install a bridge mod that validates the secret key without changing the gameplay experience.The transition of Cherry involves three main phases: installing the Fabric environment, adding the bridge mods, and configuring the security handshake to match Vangueria.

First, we must stop the existing server and install the Fabric transition layer. This replaces the standard Mojang launcher with a version capable of loading the security bridge. We need to download the Fabric Installer and then Install Fabric for the 1.21.1 environment.
cd ~/minecraft_server
wget https://maven.fabricmc.net/net/fabricmc/fabric-installer/1.0.1/fabric-installer-1.0.1.jar
java -jar fabric-installer-1.0.1.jar server -mcversion 1.21.1 -downloadMinecraft
Once complete, the installer will have created a new file named fabric-server-launch.jar. This is now the primary entry point for the server.

To install the Security Bridge we require two specific components in the mods folder: the Fabric API (the library that allows mods to interact with the game engine) and FabricProxy-Lite (the specific mod that handles the Velocity secret key). It is vital to use version-matched JARs for 1.21.1 to ensure stability.
mkdir -p ~/minecraft_server/mods
wget -O ~/minecraft_server/mods/FabricProxy-Lite.jar https://github.com/OKTW-Network/FabricProxy-Lite/releases/download/v2.10.1/FabricProxy-Lite-2.10.1.jar
wget -O ~/minecraft_server/mods/fabric-api.jar https://github.com/FabricMC/fabric-api/releases/download/0.116.11%2B1.21.1/fabric-api-0.116.11+1.21.1.jar

To configure the handshake after placing the mods, we must run the server once to generate the configuration structure, then shut it down to inject the secret.
Update start.sh to point to fabric-server-launch.jar instead of server.jar
sed -i 's/server.jar/fabric-server-launch.jar/' start.sh
Initial run to generate config (Type 'stop' once the 'Done' message appears)
./start.sh
Now, we create the configuration file and link it to Vangueria. This is where we ensure the backend only trusts traffic coming from our proxy.
mkdir -p ~/minecraft_server/config
nano ~/minecraft_server/config/FabricProxy-Lite.toml
Paste the following configuration into the file, ensuring the secret matches the one obtained from Vangueria:
enabled = true
hackOnlineMode = true
secret = "PASTE_YOUR_VANGUERIA_SECRET_HERE"
The final step is to adjust the server.properties file. Because Vangueria handles the official Mojang authentication at the "front door," the backend server must be set to offline mode to allow the proxy to pass the authenticated user data through.
sed -i 's/online-mode=true/online-mode=false/' server.properties
With the configuration complete, the server should be launched inside a named screen session to ensure it remains active.
screen -S minecraft ./start.sh
We should now change the Pfsense port forward rule to forward traffic to the 192.168.100.29 (IP address of Vangueria) and then connecting a client from a laptop outside of Pfsense and using the address cherry.seaoffate.net, we can try using the IP address of the Pfsense WAN port but it may not work (if the default server is set to cherry it may connect)

===Additional Options===

There are a few additional considerations that will make the servers run more reliably. The first is thing that needs to be done is to run the server in a screen so that there does not need to be a SSH session to be running. The following will start a screen called minecraft and will execute the start.sh command.
screen -S minecraft ./start
To exit the minecraft screen and return to the main SSH type ctrl + a and then d, the minecraft screen can be reloaded with the command
screen -r minecraft
The next thing that we will need to do is to have the minecraft server start whenever the host reboots. So we need to add a cron tab to the start.sh
crontab -e
Select nano if asked then add the line
@reboot screen -dmS minecraft /home/nigel/minecraft_server/start.sh

The next thing is not a minecraft helper exactly but it will be useful as a reminder in the future. When a user logs on to the host the message of the day will be displayed to add simple notes to the message we can simply edit the motd with the command
sudo nano /etc/motd

===Adding a second Minecraft server Apple===

Now that we have the basic setup with potential for multiple hosts we will need to create at least one more so that we can prove the proxy works as intended. The next server will be a different version with some mods. As soon as we start adding mods to a Minecraft world they will use more resources so we will need the next host to be a bit better specified.

{| class="wikitable"
|+
|-
! Item !! Value !! Notes
|-
|CPU || 6 ||
|-
|RAM || 14GB ||
|-
|Swap || 16gb || Additional disk allocated from Lexar SSD
|-
|Storage || 150GB || Initially set at 32gb
|-
|Base OS || Debian 13.3 || Server version
|-
|Hostname || Apple||
|-
|IP Address || 192.168.100.35 ||
|}

Minecraft

2026-05-12T18:00:52Z

Wikisailor: /* Adding a second Minecraft server Apple */

==Introduction==

We are to have some Minecraft servers on the '''[[Home Lab]]''''. The general setup will be to have a Velocity server in front several Minecraft host '''[[Virtual Machines]]'''. Velocity works in a similar way to a Nginx reverse proxy whereby Pfsense forwards all Minecraft traffic to the Velocity server including the SNI and Velocity redirects traffic to the required hostname based on the DNS name. Cloudflare does not reverse proxy Minecraft traffic on the free tier and as we do not want to have to deal with random bots from the east so we will not leave the port open on the edge or Pfsense to random bots with port scanners. So we will use grey cloud at Cloudflare but DNS will point to a service like TCPShield and our firewalls only accept Minecraft traffic from their IP addresses and Velocity will only accept named servers and drop any unknown DNS names.

==Installation==

The installation will be in some distinct stages to enable each step to be proved to be working before proceeding to the next stage. First we setup a simple vanilla Minecraft server and set the firewall to port forward to it directly. Once that is proven to be working we will setup a Velocity server that will receive all 25565 traffic and forward it to the working Minecraft host. The next phase after the first host is getting traffic forwarded is to setup a second host and make sure velocity can forward to each, included in this step will be hardening the Velocity server with whatever security measures that it has available. When we are sure that Velocity is working properly we can work on the remote access stage, where we use TCPShield to proxy the service and have Cloudflare DNS only names setup with cherry.seaoffate.net and apple.seaoffate.net etc. From this point forward any new Minecraft servers will simply follow the same setup procedure.

===The First Minecraft Host Configuration===

The first Minecraft host needs to have enough resources to run the JVM and the server but as it just a vanilla server the specification does not need to be excessive. The table shows the highlights.

{| class="wikitable"
|+
|-
! Item !! Value !! Notes
|-
|CPU || 2 ||
|-
|RAM || 4GB ||
|-
|Swap || 16gb || Additional disk allocated from Lexar SSD
|-
|Storage || 96GB || Initially set at 32gb
|-
|Base OS || Debian 13.3 || Server version
|-
|Hostname || Cherry ||
|-
|IP Address || 192.168.100.30 ||
|}

====Hardware Configuration====
The Cherry host was created as a clone of the Debian template and then the basic specifications were improved so we will need to configure these extra items in the OS. First we need to identify the harddrive to use as the swap file
lsblk
The result is likely to show that the disk is likely to be /dev/sdb so we can set the swap space and enable it with
sudo mkswap /dev/sdb
sudo swapon /dev/sdb
To make the swap file persistent we edit the fstab
sudo nano /etc/fstab
Add the line:
/dev/sdb none swap sw 0 0
and remove or comment out the line that refers to
/dev/sda3
Before the storage sda main partition can be expanded to the full 96GB we have to remove the swap that is in the way so disable the existing swap with
sudo swapoff /dev/sda3
Open the disk utility to modify sda
sudo fdisk /dev/sda
Delete the swap partition with the option d, then type 3 to delete partition 3, then w to save and exit. The next thing to do is expand the Primary Root Partition so open fdisk again:
sudo fdisk /dev/sda
Delete the root partition:
* Type d (Delete)
* Type 2 (this only deletes the table entry, not the data).
* Type n (Create a new partition)
* Type p (Primary Partition)
* Type 2 (For Partition number 2)
* Type enter (Use default values for start sector)
* Type enter (Use default values for end sectors to fill the 96GB)
* CRITICAL: When asked if you want to remove the signature, type N.
* Type w (Save and exit)
To finalize Storage reboot to refresh the kernel partition table:
sudo systemctl reboot
When the VM reboots expand the filesystem into the new space:
sudo resize2fs /dev/sda2
We can verify the new swap and new sda size with
df -h
Now that the hardware is setup and configured we can proceed to the software installation

====Software Installation====

The software installation consists of updates, install the JVM and then install the Minecraft server. So to start as we do on most hosts with updates
sudo apt update
sudo apt upgrade
Install Necessary Utilities:
sudo apt install htop screen wget curl -y
Install Java 25:
sudo apt install openjdk-25-jre-headless -y
Verify Java Installation (Ensure it reports OpenJDK 25)
java -version
Now we install the Minecraft server

Create the Server Directory:
mkdir ~/minecraft_server && cd ~/minecraft_server
Download the Server Software:
wget -O server.jar [https://piston-data.mojang.com/v1/objects/97ccd4c0ed3f81bbb7bfacddd1090b0c56f9bc51/server.jar](https://piston-data.mojang.com/v1/objects/97ccd4c0ed3f81bbb7bfacddd1090b0c56f9bc51/server.jar)
Assuming the file downloaded we need an initial run to generate the file:
java -Xms1G -Xmx1G -jar server.jar nogui
When the file is first created it will not run until we Accept the EULA with the command:
sed -i 's/eula=false/eula=true/' eula.txt
We can create the Start Script:
nano start.sh
Paste in the following
<nowiki> #!/bin/bash
while true
do
echo "--- Starting Minecraft Server ---"
java -Xms3G -Xmx3G \
--enable-native-access=ALL-UNNAMED \
-XX:+UseG1GC \
-XX:MaxGCPauseMillis=200 \
-XX:+UnlockExperimentalVMOptions \
-XX:+DisableExplicitGC \
-XX:+AlwaysPreTouch \
-jar server.jar nogui
echo "--- Server stopped. Restarting in 5 seconds (Ctrl+C to cancel) ---"
sleep 5
done</nowiki>
Set the script to execute with
chmod +x start.sh
We can start the server with
./start.sh
'''Note''' we can type the command stop in the terminal and the server will save the world and stop it for 5 seconds during the 5 seconds, if we type ctrl+c it will end the script or if we just leave it the server will restart.

====Enable External Access====

We will need to access the server from outside world so we should forward the Minecraft port 25565 to the IP address of cherry. To make the port forward rules in Pfsense easier to understand we add an alias for cherry's IP address and a port alias for 25565. We add a port forward rule to Pfsense that says source IP 192.168.0.0/16 and any port, destination this firewall (self) Destination port Minecraft_standard, redirect IP_cherry port Minecraft_standard.

====Testing====

With this configuration loading a Minecraft client and setting the destination server to the WAN port IP address it will connect to the cherry host.

As part of the wider LAN setup we added a Adguard LXC to manage DNS. Part of the Adguard configuration was made to avoid the hairpin network access so a DNS redirect was made to forward *.seaoffate.net to Pfsense WAN and as the default domain name was set to seaoffate.net. So now when we have a destination of cherry Adguard will translate the hostname to cherry.seaoffate.net and redirect it to Pfsense, Pfsense will then forward to the relevant server. If that does not work as expected the next test would be to set the destination to cherry.seaoffate.net which should be redirected by Adguard.

===Velocity Installation===

The Velocity server VM does not need to be especially high because all it needs to do is accept connections and forward them on to the relevant host and any associated functions like handle logon, bans and etc. Unlike the cherry host that we just setup the base specification from the Debian template needs to be cut down a bit and does not need a extra swap file or anything special.

{| class="wikitable"
|+
|-
! Item !! Value !! Notes
|-
|CPU || 1 ||
|-
|RAM || 1GB ||
|-
|Storage || 32GB ||
|-
|Base OS || Debian 13.3 || Server version
|-
|Hostname || Vangueria ||
|-
|IP Address || 192.168.100.29 ||
|}
====Software Installation====

As there is no additions to the VM's specification there is no hardware to configure so we can get straight to the software installation. So the well known update/upgrade and the packages can be installed with
sudo apt update && sudo apt upgrade -y
sudo apt install -y openjdk-25-jre-headless htop screen wget jq curl
Once the dependencies are installed, we create a dedicated application directory and use an automated script to identify the most recent build of Velocity 3.4.0. This ensures we are not relying on hardcoded links that may expire.
mkdir ~/velocity && cd ~/velocity
export PROJECT="velocity"
export VERSION="3.4.0-SNAPSHOT"
export LATEST_BUILD=$(curl -s https://api.papermc.io/v2/projects/${PROJECT}/versions/${VERSION} | jq '.builds[-1]')
wget -O ~/velocity/velocity.jar "https://api.papermc.io/v2/projects/${PROJECT}/versions/${VERSION}/builds/${LATEST_BUILD}/downloads/${PROJECT}-${VERSION}-${LATEST_BUILD}.jar"
The initial boot of Velocity is performed to generate the necessary configuration files. We launch it with a 512MB heap size and then shut it down gracefully using the end command once the prompt appears.
java -Xms512M -Xmx512M -jar velocity.jar

====Proxy Configuration and Routing====

The primary configuration for the proxy is handled within the velocity.toml file. This file dictates how the proxy listens for incoming traffic and how it maps domain names to internal IP addresses. We edit this file to ensure the proxy is listening on all interfaces and that it is using the modern forwarding protocol.
nano ~/velocity/velocity.toml
Modify these specific lines:
* Bind Address: bind = "0.0.0.0:25565" (Allows it to hear traffic from pfSense).
* Forwarding Mode: player-info-forwarding-mode = "modern" (This is the most secure protocol for 2026).
* ping-passthrough should be set to ALL. This is to ensure the server list on the Minecraft client correctly displays the status and version of the backend servers
* Server List: Scroll down to the [servers] section:
<nowiki>[servers]
cherry = "192.168.100.30:25565"
apple = "192.168.100.35:25565"

[servers]
try = [
"cherry"
]</nowiki>
* Forced Hosts: This tells the proxy which server to pick based on the URL the player typed:
<nowiki>[forced-hosts]
"cherry.seaoffate.net" = ["cherry"]
"apple.seaoffate.net" = ["apple"]</nowiki>
Save and close the file. next we need a start.sh file for Velocity
nano ~/velocity/start.sh
copy the following into the file
<nowiki> #!/bin/bash
while true
do
echo "--- Starting Vangueria Proxy ---"
java -Xms512M -Xmx512M \
-XX:+UseG1GC \
-XX:MaxGCPauseMillis=200 \
-XX:+UnlockExperimentalVMOptions \
-XX:+DisableExplicitGC \
-XX:+AlwaysPreTouch \
-jar velocity.jar
echo "--- Proxy stopped. Restarting in 5s ---"
sleep 5
done</nowiki>
To make the script executable
chmod +x ~/velocity/start.sh
At this point the since Vangueria is now set to Modern Forwarding, Cherry will reject all connections until it has the forwarding.secret. the secret can be obtained with the command
cat ~/velocity/forwarding.secret
Copy the code to a safe location because we will need it to setup cherry (and apple). then we should be able to finally start the proxy with the start.sh
./start.sh
Now we move to cherry to setup it's ability to receive connections from Vangueria.

====Configuring Cherry To Accept Proxied Connections====

To complete the integration between the proxy and the backend, Cherry must be transitioned from a standalone Vanilla server to a "Proxy-Aware" host. Because Vanilla Minecraft does not natively support Velocity’s Modern Forwarding (the security handshake), we use the Fabric Loader as a lightweight wrapper. This allows us to install a bridge mod that validates the secret key without changing the gameplay experience.The transition of Cherry involves three main phases: installing the Fabric environment, adding the bridge mods, and configuring the security handshake to match Vangueria.

First, we must stop the existing server and install the Fabric transition layer. This replaces the standard Mojang launcher with a version capable of loading the security bridge. We need to download the Fabric Installer and then Install Fabric for the 1.21.1 environment.
cd ~/minecraft_server
wget https://maven.fabricmc.net/net/fabricmc/fabric-installer/1.0.1/fabric-installer-1.0.1.jar
java -jar fabric-installer-1.0.1.jar server -mcversion 1.21.1 -downloadMinecraft
Once complete, the installer will have created a new file named fabric-server-launch.jar. This is now the primary entry point for the server.

To install the Security Bridge we require two specific components in the mods folder: the Fabric API (the library that allows mods to interact with the game engine) and FabricProxy-Lite (the specific mod that handles the Velocity secret key). It is vital to use version-matched JARs for 1.21.1 to ensure stability.
mkdir -p ~/minecraft_server/mods
wget -O ~/minecraft_server/mods/FabricProxy-Lite.jar https://github.com/OKTW-Network/FabricProxy-Lite/releases/download/v2.10.1/FabricProxy-Lite-2.10.1.jar
wget -O ~/minecraft_server/mods/fabric-api.jar https://github.com/FabricMC/fabric-api/releases/download/0.116.11%2B1.21.1/fabric-api-0.116.11+1.21.1.jar

To configure the handshake after placing the mods, we must run the server once to generate the configuration structure, then shut it down to inject the secret.
Update start.sh to point to fabric-server-launch.jar instead of server.jar
sed -i 's/server.jar/fabric-server-launch.jar/' start.sh
Initial run to generate config (Type 'stop' once the 'Done' message appears)
./start.sh
Now, we create the configuration file and link it to Vangueria. This is where we ensure the backend only trusts traffic coming from our proxy.
mkdir -p ~/minecraft_server/config
nano ~/minecraft_server/config/FabricProxy-Lite.toml
Paste the following configuration into the file, ensuring the secret matches the one obtained from Vangueria:
enabled = true
hackOnlineMode = true
secret = "PASTE_YOUR_VANGUERIA_SECRET_HERE"
The final step is to adjust the server.properties file. Because Vangueria handles the official Mojang authentication at the "front door," the backend server must be set to offline mode to allow the proxy to pass the authenticated user data through.
sed -i 's/online-mode=true/online-mode=false/' server.properties
With the configuration complete, the server should be launched inside a named screen session to ensure it remains active.
screen -S minecraft ./start.sh
We should now change the Pfsense port forward rule to forward traffic to the 192.168.100.29 (IP address of Vangueria) and then connecting a client from a laptop outside of Pfsense and using the address cherry.seaoffate.net, we can try using the IP address of the Pfsense WAN port but it may not work (if the default server is set to cherry it may connect)

===Additional Options===

There are a few additional considerations that will make the servers run more reliably. The first is thing that needs to be done is to run the server in a screen so that there does not need to be a SSH session to be running. The following will start a screen called minecraft and will execute the start.sh command.
screen -S minecraft ./start
To exit the minecraft screen and return to the main SSH type ctrl + a and then d, the minecraft screen can be reloaded with the command
screen -r minecraft
The next thing that we will need to do is to have the minecraft server start whenever the host reboots. So we need to add a cron tab to the start.sh
crontab -e
Select nano if asked then add the line
@reboot screen -dmS minecraft /home/nigel/minecraft_server/start.sh

The next thing is not a minecraft helper exactly but it will be useful as a reminder in the future. When a user logs on to the host the message of the day will be displayed to add simple notes to the message we can simply edit the motd with the command
sudo nano /etc/motd

===Adding a second Minecraft server Apple===

Now that we have the basic setup with potential for multiple hosts we will need to create at least one more so that we can prove the proxy works as intended. The next server will be a different version with some mods. As soon as we start adding mods to a Minecraft world they will use more resources so we will need the next host to be a bit better specified.

{| class="wikitable"
|+
|-
! Item !! Value !! Notes
|-
|CPU || 2 ||
|-
|RAM || 4GB ||
|-
|Swap || 16gb || Additional disk allocated from Lexar SSD
|-
|Storage || 150GB || Initially set at 32gb
|-
|Base OS || Debian 13.3 || Server version
|-
|Hostname || Apple||
|-
|IP Address || 192.168.100.30 ||
|}

Minecraft

2026-05-12T17:59:36Z

Wikisailor: /* Adding a second Minecraft server */

Minecraft

2026-05-12T17:52:41Z

Wikisailor: /* Configuring Cherry To Accept Proxied Connections */

Minecraft

2026-05-12T16:18:59Z

Wikisailor: /* Proxy Configuration and Routing */

Minecraft

2026-05-12T05:52:24Z

Wikisailor: /* Proxy Configuration and Routing */

Minecraft

2026-05-12T05:28:33Z

Wikisailor: /* Velocity Installation */

Minecraft

2026-05-12T04:52:49Z

Wikisailor: /* Velocity Installation */

Minecraft

2026-05-12T01:23:27Z

Wikisailor: /* Velocity Installation */

Minecraft

2026-05-12T01:07:11Z

Wikisailor: /* Velocity Installation */

Minecraft

2026-05-12T01:03:05Z

Wikisailor: /* The First Minecraft Host Configuration */

Minecraft

2026-05-12T00:58:55Z

Wikisailor: /* Testing */

Minecraft

2026-05-12T00:57:17Z

Wikisailor: /* The First Minecraft Host Configuration */

Minecraft

2026-05-12T00:56:03Z

Wikisailor: /* Testing */

Minecraft

2026-05-12T00:55:42Z

Wikisailor: /* Enable External Access */

Minecraft

2026-05-12T00:55:19Z

Wikisailor: /* Software Installation */

Minecraft

2026-05-12T00:52:11Z

Wikisailor: /* The First Minecraft Host */

Minecraft

2026-05-11T23:02:42Z

Wikisailor: /* The First Minecraft Host */

Minecraft

2026-05-11T22:21:44Z

Wikisailor: /* The First Minecraft Host */

Minecraft

2026-05-11T22:11:54Z

Wikisailor: /* The First Minecraft Host */

Minecraft

2026-05-11T22:10:48Z

Wikisailor: /* The First Minecraft Host */

Minecraft

2026-05-11T21:59:11Z

Wikisailor: /* Introduction */

Minecraft

2026-05-11T21:19:58Z

Wikisailor: /* Introduction */

Minecraft

2026-05-11T21:19:15Z

Wikisailor: /* Introduction */

==Introduction==

We are to have some Minecraft servers on the [[Home Lab]]. The general setup will be to have a Velocity server in front several Minecraft host [[Virtual Machines]]. Velocity works in a similar way to a Nginx reverse proxy whereby Pfsense forwards all Minecraft traffic to the Velocity server including the SNI and Velocity redirects traffic to the required hostname based on the DNS name. Cloudflare does not reverse proxy Minecraft traffic on the free tier and as we do not want to have to deal with random bots from the east so we will not leave the port open on the edge or Pfsense to random bots with port scanners. So we will use grey cloud at Cloudflare but DNS will point to a service like TCPShield and our firewalls only accept Minecraft traffic from their IP addresses and Velocity will only accept named servers and drop any unknown DNS names.

Minecraft

2026-05-11T21:17:45Z

Wikisailor: /* Introduction */

==Introduction==

We are to have some Minecraft servers on the [[Home lab]]. The general setup will be to have a Velocity server in front several Minecraft host [[Virtual Machines]]. Velocity works in a similar way to a Nginx reverse proxy whereby Pfsense forwards all Minecraft traffic to the Velocity server including the SNI and Velocity redirects traffic to the required hostname based on the DNS name. Cloudflare does not reverse proxy Minecraft traffic on the free tier and as we do not want to have to deal with random bots from the east so we will not leave the port open on the edge or Pfsense to random bots with port scanners. So we will use grey cloud at Cloudflare but DNS will point to a service like TCPShield and our firewalls only accept Minecraft traffic from their IP addresses and Velocity will only accept named servers and drop any unknown DNS names.

Minecraft

2026-05-11T21:15:12Z

Wikisailor: Created page with "==Introduction== We are to have some Minecraft servers on the Homelab. The general setup will be to have a Velocity server in front several Minecraft host VMs. Velocity works in a similar way to a Nginx reverse proxy whereby Pfsense forwards all Minecraft traffic to the Velocity server including the SNI and Velocity redirects traffic to the required hostname based on the DNS name. Cloudflare does not reverse proxy Minecraft traffic on the free tier and as we do not..."

==Introduction==

We are to have some Minecraft servers on the [[Homelab]]. The general setup will be to have a Velocity server in front several Minecraft host VMs. Velocity works in a similar way to a Nginx reverse proxy whereby Pfsense forwards all Minecraft traffic to the Velocity server including the SNI and Velocity redirects traffic to the required hostname based on the DNS name. Cloudflare does not reverse proxy Minecraft traffic on the free tier and as we do not want to have to deal with random bots from the east so we will not leave the port open on the edge or Pfsense to random bots with port scanners. So we will use grey cloud at Cloudflare but DNS will point to a service like TCPShield and our firewalls only accept Minecraft traffic from their IP addresses and Velocity will only accept named servers and drop any unknown DNS names.

Proxmox Server

2026-05-01T07:33:52Z

Wikisailor: /* 🥝 Kiwi Host: Technical Manual & Build Log */

==📋Introduction==

This is the server that will sit under my desk until I move house. It has the hostname Pear and will be the beginning of the '''[[Home Lab]]'''. There is also now a new smaller and less powerful server with the hostname Kiwi.

==🥝[[Create Virtual Machine from a template]]==

it is possible to create a new VM based on a fixed template. The two possibilities are a full clone or a linked clone. the linked clone is the preferred as it should need less storage but the full clone would be completely independent of the template so it will use more storage and take longer to create.We can go down that rabbit hole when we look ant Ansible in a big way. For now just understand that we can call a new vm using the qm clone command. the will be more details to follow.

==Orchard (Pear)==
The first host has Proxmox installed with the following specification

===🛠️Hardware Specification===

The Main components were purchased in 2024 as follows

* The Cpu is AMD Ryzen 9 5950X Processor (16Cores/32Threads, 105W TDP, Socket AM4, 72MB Cache, Up to 4.9 GHz Max Boost, no cooler) £369.98
* The cooler is Noctua NH-D15, Premium CPU Cooler with 2x NF-A15 PWM 140mm Fans (Brown) £99.95
* Mainboard is Gigabyte B550M AORUS ELITE Motherboard - Supports AMD Ryzen 5000 Series AM4 CPUs, 5+3 Phases Pure Digital VRM, up to 4733MHz DDR4 (OC), 2xPCIe 3.0 M.2, GbE LAN, USB 3.2 Gen1 £103.48
* 128gb Ram is configured as two sets of CORSAIR VENGEANCE LPX DDR4 RAM 64GB (2x32GB) 3200MHz CL16-20-20-38 1.35V (CMK64GX4M2E3200C16) £112.20 for one set
* GPU is a Gigabyte Geforce RTX 5060 TI with 16 GB Ram
* Power supply is Corsair RM750x 80 Plus Gold Fully Modular ATX 750 Watt Power Supply £109.00
* The case is Fractal Design Node 804 - Black - Compact Computer Case - mATX - High Airflow - Modular interior - 3x Fractal Design Silent R2 120mm Fans Included - Water-cooling ready - USB 3.0 -Window Side Panel £99.95
* SSD is Crucial P3 Plus SSD 4TB M.2 NVMe PCIe Gen4 Internal SSD, Up to 4800MB/s, Laptop & Desktop (PC) Compatible, Solid State Drive - CT4000P3PSSD801 £189.99 and £159.99
* Three 16 TB Seagate Ironwolf NAS drives make up the hard disk storage at a cost of £179.94 each total £ 539.82.
* One cheap 1 TB SATA SSD currently set as a L2ARC but may reconfigure as a sacrificial drive for the high wear VMs if it looks like it is not getting many hits as L2ARC '''Update ''' no longer used as L2ARC and formmated to a zpool fastpool.

===Configuration===

====🌐Network Access====

The IP Address and port of the host is 192.168.0.110:8006. I have my virgin media router forwarding all incoming traffic to 192.168.0.125 so it will go directly to the Pfsense firewall. All of the terminals can also send traffic to the WAN port of Pfsense. '''Edit''' with the change to Vodaphone the network address changed to 192.168.1.0/24 so Proxmox console is now 192.168.1.111:8006 and the WAN port of Pfsense is 192.168.1.125. a further change was to only forward those ports that are actually needed to Pfsense because the new ISP router has better options than the really old Virgin media one ( to be fair if i had stayed with Virgin i would have got a newer router). More '''[[Network Configuration]]''' details.

====💾Storage====

The main storage is the three 16TB hard drives configure into ZFS z1 so that they have one redundant disk. As one disk is redundant, obviously, it has 32TB of storage available.

I couldn't get PCI passthrough to work reliably without significant effort and some expense so I set up ZFS on Proxmox itself or more precisely on the Debian Linux that Proxmox resides on. Unfortunately, that means that I have to do any config on the CLI. I may write some scripts to perform some of the admin tasks or more likely setup a Nginx container to automate as much of it as possible. For the time being some useful ZFS commands can be found '''[[ZFS Commands |here]]'''

==🥝 Grove (Kiwi) : Technical Manual & Build Log==

Kiwi is the secondary Proxmox host in the Home Lab, housed in a Fractal Design ITX chassis. While less powerful than the primary host (Pear), it serves as a high-capacity storage node and 2.5G data target.

=== Hardware Specification ===

* CPU: AMD Ryzen 5 with Stock Wraith Cooler.
* RAM: 64GB (2x32GB Crucial DDR4), maxing out the two available slots.
* System Drive: 2TB Samsung 990 Pro NVMe (Firmware verified: 5B2QJXD7).
* Storage Pool: 3x 14TB Seagate IronWolf Pro HDDs (ZFS RAIDZ1, 28TB usable).
* Network: Onboard 2.5 Gbps Wired NIC (nic0) + Built-in Wi-Fi (wlp5s0).
* GPU: Legacy Nvidia GPU (Required for POST and initial installation). The Mainboard has 4 SATA ports on board. Three of them have 14 TB Ironwolf pro drives to be formatted as a ZFS array with Z! so will give 28TB of usable storage with one disk of redundancy

===Proxmox Installation===

It is assumed that the Proxmox installer has been downloaded from their website and the iso has been copied on to a USB stick and made bootable with Rufus or some other similar. If the reader doesn't know how to make a USB installer from an ISO try typing "How do I make a USB stick into a proxmox installer" in to a browser. there will be loads of guides on how to use Rufus. When a bootable USB stick with Proxmox installer on it has been created insert in to one of the USB slots along with a keyboard, mouse and screen. Please note the keyboard mouse and screen will only be needed for the installation, once Proxmox is installed it is unlikely that these will ever be used again because virtually all administration is performed on a web GUI.

====BIOS settings for Hypervisors (including Proxmox)====

Generally most BIOS can be left at defaults and a PC as a PC will work well enough, maybe the boot priority may need to be changed from a HDD to a SSD but even that is unlikely. It is possible to optimise lots of things in BIOS and for some people that is an option but it is also easy to make mistakes that either stop the machine from working or making the machine unstable so for most people, most of the time, it is better to leave BIOS alone. A big exception is when a hypervisor is to be install because a few options that are off by default need to be set for Virtualisation to work properly. The main things to set are:-
* SVM Mode (AMD-V): '''Must be Enabled.''' This is what allows Proxmox to run VMs. Without it virtualisation will fail with most or possibly all hypervisors
* IOMMU: Set to Enabled. This is vital if you ever want to "pass through" a SATA controller or GPU directly to a VM. while not vital for the virtualisation itself most hypervisors have this enabled.
* Power Supply Idle Control: If you find the server randomly freezes when idle, set this to "Typical Current Idle". Ryzen chips sometimes drop voltage too low for some power supplies when idling, causing a crash. Again not vital but a "nice to have" if possible in the BIOS.
* Boot options: The SSD should be at the top. It is better to set the USB at the bottom so that if a USB is left in the machine and it is rebooted it doesn't try to boot from the USB.
Once the BIOS option are set save the settings and quit. The computer will shutdown and restart, while it is restarting keep pressing the delete key or the F12 key to bring up the boot options (it is usually delete key but it should also display the options briefly on the screen as it starts).

====GPU Considerations====

The Proxmox installation is a little bit more tricky than is standard for the majority of computers in that this has an old GPU that the installer does not recognise. A GPU is required so that the machine will pass POST but is not really need or used by the Proxmox guests so is generally of little benefit for the overall Proxmox day to day running. A lot of Hypervisor hosts have the cheapest and lowest power GPUs installed just enough to POST but no more than that. The reason that GPU is of low priorty for most hypervisors hosts is that they are generally run headless, that is without a monitor attached, all interations with the host is through a dedicated application like Citrix XEN, or more likely through a web browser like Proxmox. Web based GUIs are popular because it is a lot easier and lighter processor load to have a webserver attached than it is to design a whole application. Kiwi has an old Nvidia GPU that works in that it provides a display but that is about it. Unfortunately, it does give some problems for the installer as it is so old but therea re steps to overcome that as will be detailed below. We may add a bigger and better GPU at a later date but for the foreseeable future that is in the realms of an upgrade for later and dependant on inheriting a GPU from another box.

====Proxmox Installer problems (The Kiwi exceptions)====

As stated earlier the Proxmox installer does not work with the GPU. This is shown in that the machine boots and loads the first screen of the installer with welcome to.. but when the first option is tried it starts to load then freezes at the loading Nvidia drivers or some such thing(cant remember exactly what it says). so to fix that issue we need to restart the host and when we get to the welcome screen again we highlight "Install Proxmox VE (Graphical)" but '''do not press Enter''' instead we press "e" so a black screen with GNU GRUB appears. Edit the line
linux /boot/linux26 ro ramdisk_size=16777216 rw quiet splash=silent
so it reads
linux /boot/linux26 ro ramdisk_size=16777216 rw nomodeset
* By removing the quiet splash=silent we force the installer to show every single line of code as it loads. If it freezes again, we see the exact driver name where it stopped (e.g., sata_nv or i915).
* Adding nomodeset: This is the "magic bullet" for the nvidiafb hang. It tells the kernel not to touch the video drivers until the system is fully loaded. It is most likely where the installer hangs. As we should see every line of the execution of the installer if we have a different driver issue we should still see it.
To save the changes press ctrl+x or maybe F10. The GNU Grub screen will close and the graphical installer will continue until it gets to the "end user license agreement (EULA) screen. For anyone else reading this, If the installer freezes again before it gets to the EULA screen the error will most likely be in the last laine of text displayed. The most likely error will be a conflict between Debian kernel and Advanced Configuration and Power Interface (ACPI) in which case restart and press the "e" to get to the Grub config and edit the same line
linux /boot/linux26 ro ramdisk_size=16777216 rw nomodeset
so that it now has noapic added. note that this is just for the installer not the Proxmox application.
linux /boot/linux26 ro ramdisk_size=16777216 rw nomodeset noapic
After modifying that line press ctrl+x or F10 to save and proceed. if it stalls again you will need to look for the exact error in the last line or last few lines that the installer performed or any line that starts or ends with failed.

====Proxmox installer continued====

After the earlier problems we should have got to the ELUA screen so press "I agree" button to continue. The next screen will be about choosing hard drives. Kiwi has a single SSD and three Ironwolf Pro 14 TB HDDs. Obviously, we will not install the OS onto a HDD or even all three HDDs as it would be too slow and as the SSD is fast we will choose that as the Target Harddisk. with the SSD selected click on options button.
* select zfs (RAID0)
* select samsung SSD as hardisk 0
* select Do not use for harddisk 1
* select Do not use for harddisk 2
* select Do not use for harddisk 3
ZFS is the best choice as it has native compression, Bitrot detection but not really protection because there is only one drive so nowhere to restore any corrupt data from. ZFS also has good snapshot capability. Ext4 / XFS are "set it and forget it" options. They use almost zero RAM, but they offer no protection against data corruption and have very basic snapshotting capabilities (via LVM). Btrfs is similar to ZFS but generally considered less stable and has a lower feature set. The HDDs will not be used during the installation of Proxmox because it is easier to set them up from within the Proxmox web GUI or CLI.so the do not use is the best option for now '''note''' before we exit the Harddisk Options we need to check that the '''ashift''' is set to 12 so that the data blocks align with the physical page size of the Samsung 990 Pro's NAND, ensuring maximum speed, so select Advanced Options button next to Disk setup. Choose
* ashift is 12
* compress is on
* checksum is on
* copies is 1. Since this is a single-disk ZFS RAID0, copies=1 is the standard. If it is set it to 2, it would store every block twice on the same physical SSD. While that would allow ZFS to repair bitrot, it would effectively cut the 2TB SSD down to 1TB and halve the write speeds. With a 990 Pro, standard checksums and a good backup strategy are much more efficient.
* ARC max size 6422 Since there are only have two RAM slots and we are capped at 64GB, we need to be very intentional about how we carve up Kiwi RAM. having said that it is only a Maximum not a set size and zfs does not have to use all of it's maximum
* hdsize is set to maximum ( the + button will only allow it to be the size of the harddisk so click it until it stops going up)
Check the settings and when all looks correct click next for the regional settings
* Country United Kingdom
* Timezone Europe/London (or UTC if preferred)
* Keyboard Layout United Kingdom
Then next to set password and email address screen. Set a strong password that you can remember for the administration of the host. If the password is lost it will be almost impossible to recover it so do not forget it. Also it will be the hackers dream to get hold of the Proxmox host's password in that all of the rest of the security is mainly built on top of the administration of the host. If a host in a cluster is compromised it is quite likely that the whole cluster is compromised. The email address is so Proxmox can send promotional or updates but in general they don't flood their users with spam so it is no problem adding in a real email address. When done Click next to se the Management Network configuration screen.

The Management Network Configuration will determine where the WebGUI will be presented from. Kiwi has two NICs, one is the 2.5 GB p/s wired NIC and the other is the wireless NIC. by default it is likely to be the wired NIC that is going to be the one used for the management interface, mainly because at this stage WiFi has not been set up yet. Set up the options as follows
* Management Interface nic0 (the r8169 is the driver that Debian uses for wired nics) It is the one that is up and the Wifi nic is down so it is straight forward to establish which is which.
* hostname will be kiwi.seaoffate.net it is safe for us to use this domain name because we have registered it. If the reader has no domain name it could be kiwi.local but it would be unwise to use something that is already register on the public Internet, it may appear to work but there will be odd unforeseen problems like getting updates or push notifications or some other odd thing that don't work because the reply is being sent to a different IP address.
* IP address will be 192.168.1.112/24
* Gateway will be 192.168.1.1
* DNS will be 192.168.1.1
When this is done click next for the Summary. Make sure it is all correct and the auto reboot after successful installation then click install.

====Post Installation ====

When the host finishes the install it will restart. It may show the Proxmox Intallation again if the USB is still plugged in depending on the boot options, if so remove the USB and restart the computer. once the computer has finished starting it should show a simple login screen with the web address that is the main administration panel. from this point on the screen, mouse and keyboard can and should be removed as they will probably be never be used again. Now Kiwi will be managed from a web browser. The address will be whatever was set in the Management Network Configuration section with the port number 8006. in the case of Kiwi it is http://192.168.1.112:8006 the browser will give a security warning as no SSL cert has been setup for it yet so click advanced or ignore or whatever the browser needs to get to the web address. Then there will be a bank Proxmox screen with a popup in the middle with the title Proxmox VE Login the login details are
* Username root
* Password your_password ( whatever was set in the password and email section of the instalation)
* Realm is Linux PAM standard authentication
* Language English - English
'''note''' username and password are case sensitive

=====Samsung 990 Pro series SSDs Firmware=====
Now we have logged in we need to check that the Samsung SSD has got up to date firmware, '''Note This is for Samsung 990 Pro SSDs''' and not all SSDs it is not even all Samsung SSDs just this particular model in the early versions. Select Kiwi from the left pane then towards the top right of the main pane there is a row of buttons reboot, shutdown, shell, bulk actions, and help click on shell. A new window will appear with root@kiwi already logged in. Type the following into the window
smartctl -a /dev/nvme0n1
look through the information for the SSD, under === START OF INFORMATION SECTION === it should have a firmware Version line. Make sure the version is not "1B2QJXD7" it should be safe if it starts with 3 or more. If the Samsung 990 Pro SSD does have the unsafe version stop now and update the firmware immediately or it is likely that it will stop working after a short time. The version on this host is Firmware Version: 5B2QJXD7

=====Fix the No Subscription nag and do system update=====
By default, Proxmox tries to use a paid repository that you can't access. We need to disable that and add the free community one. This assumes that it is Proxmox version 9.x. Proxmox 9 uses .sources files. We must disable the default enterprise links and add the community repository. Run these commands in the Kiwi shell
# 1. Disable Enterprise PVE Repo
mv /etc/apt/sources.list.d/pve-enterprise.sources /etc/apt/sources.list.d/pve-enterprise.sources.bak
# 2. Disable Enterprise Ceph Repo
mv /etc/apt/sources.list.d/ceph.sources /etc/apt/sources.list.d/ceph.sources.bak
# 3. Create the No-Subscription Source
cat <<EOF > /etc/apt/sources.list.d/pve-no-subscription.sources
Types: deb
URIs: http://download.proxmox.com/debian/pve
Suites: trixie
Components: pve-no-subscription
Architectures: amd64
Signed-By: /usr/share/keyrings/proxmox-archive-keyring.gpg
EOF
The "No-Nag" UI Patch: This command neutralizes the subscription check in the web interface and restarts the proxy service to apply it
# 4. Remove 'No Valid Subscription' Login Popup
sed -Ezi.bak "s/(Ext.Msg.show\(\{\s+title: gettext\(\'No valid sub)/void\(\{ \/\/\1/g" /usr/share/javascript/proxmox-widget-toolkit/proxmoxlib.js && systemctl restart pveproxy.service
When the system reboots open a new console window for the host. So we can do an update. Always use dist-upgrade for Proxmox to ensure kernel and dependency changes are handled correctly.
# 5. Refresh and Upgrade
apt update && apt dist-upgrade -y
Summary of why we did this
* The .bak method: Instead of fighting sed patterns that might change, moving the files to .bak is a "bulletproof" way to ensure apt ignores them.
* Trixie Suites: Using Suites: trixie ensures you aren't pulling in old bookworm (Proxmox 8) packages that could destabilize your new Ryzen 5 build.
* The 63 Packages: Now that you've run the update, those 63 packages are waiting. Running the dist-upgrade command above will install the latest 2026 security patches and hardware drivers.

=====Ironwolf Pro Harddrive Setup=====

Since we have already performed the dist-upgrade, the kernel is fresh and ready to handle the heavy I/O of those 14TB drives. We will set this up via the CLI to ensure we get the exact optimizations needed for a high-density vault. First, we must be 100% certain which device names (/dev/sdX) belong to the IronWolfs.
lsblk -o NAME,SIZE,MODEL,SERIAL
Look for the three drives that show approximately 12.7T (the TiB equivalent of 14TB). Verify the Model says ST14000.... In this case they are
* sda 12.7T ST14000NE0008-2JK101 ZTM0D5FK
* sdb 12.7T ST14000NE0008-2H4101 ZL2EJCXX (this one has a partition sdb1 but we ignore it)
* sdc 12.7T ST14000NE0008-2JK101 ZTM0D5A0
The Clean Slate (Wipe the Labels) Run these commands to clear the old ZFS and EFI labels. This doesn't delete all of the old data (which takes hours), it just "un-formats" the start and end of the disks so ZFS sees them as new. It may not be necessary for all of the drives but certainly is for sdb as that has a partition on it
# Wipe the ZFS labels specifically
zpool labelclear -f /dev/sda
zpool labelclear -f /dev/sdb
zpool labelclear -f /dev/sdc
# Wipe the partition tables entirely (the "Nuclear" option)
wipefs -a /dev/sda
wipefs -a /dev/sdb
wipefs -a /dev/sdc

The other drive is the 990 Pro SSD. Now we can create the ZFS Z1 Pool We will name the pool kiwipool. We are using ashift=12 for 4K sector alignment and atime=off to save the mechanical heads from unnecessary movement.
zpool create -o ashift=12 kiwipool raidz1 /dev/sda /dev/sdb /dev/sdc
# Apply optimizations
zfs set compression=lz4 kiwipool
zfs set atime=off kiwipool
zfs set xattr=sa kiwipool
zfs set recordsize=1M kiwipool
once that is done we can verify the pool is built with
zpool status kiwipool
Next we need to make some datasets to keep the pool organised and not write anything to the root of kiwipool. Run thes commands
zfs create kiwipool/PFK
zfs create kiwipool/PFK/pdata
zfs create kiwipool/PFK/pdata/KiwiHDs
zfs create kiwipool/ISO
zfs create kiwipool/PFK/backups
zfs list
The zpool will show up in the webgui in Kiwi->storage and kiwi->zfs but not in the VM list on the left hand pane so they cannot be added to VMs yet. To make them available we run the command
pvesm add zfspool KiwiHDs --pool kiwipool/PFK/pdata/KiwiHDs --content rootdir,images
pvesm add dir KiwiISOs --path /kiwipool/ISO --content iso,vztmpl
pvesm add dir KiwiBackups --path /kiwipool/PFK/backups --content backup
Now in the webgui there should be the drives for VM HDs, ISOs and backups

=====Check and configure the WiFi=====

Testing Wi-Fi on a Proxmox (Debian) host is a bit different than on a laptop because there is no "taskbar" to click. We have to do this through the CLI. First, let's see if Debian even sees the Wi-Fi card and has the drivers loaded.
ip link
Look for: An interface starting with w (e.g., wlp2s0 or wlan0). If you don't see one the drivers might be missing or it's "Hard Blocked" in the BIOS. In this case The hardware check is a success. Your Wi-Fi card is identified as wlp5s0 (it did show up in the installer but it was ignored then ). The state is currently DOWN, which is expected since it hasn't been configured with your SSID or credentials yet. Because Proxmox is built for servers, it lacks a graphical Wi-Fi picker. We have to manually tell the background service (wpa_supplicant) how to talk to your router. at the same time install the wireless tools package.
apt update && apt install wpasupplicant wireless-tools -y
Instead of typing the Wi-Fi password in plain text, we’ll use a tool to generate a secure configuration block. Replace Your_SSID and Your_Password with your actual wireless AP details:
wpa_passphrase "Your_SSID" "Your_Password" > /etc/wpa_supplicant/wpa_supplicant.conf
Now we can test the connection let's see if Kiwi can actually authenticate.
wpa_supplicant -B -i wlp5s0 -c /etc/wpa_supplicant/wpa_supplicant.conf
Then wait a few seconds before checking the status with
iw wlp5s0 link
Assuming it shows a connection we can make it permanent. To ensure the Wi-Fi comes up automatically on boot and acts as a secondary management port, we need to add it to the network interfaces file. Warning: Be very careful with the syntax here. Use this command to append the configuration to /etc/network/interfaces. cat <<EOF >> /etc/network/interfaces
auto wlp5s0
iface wlp5s0 inet static
address 192.168.1.113/24
wpa-conf /etc/wpa_supplicant/wpa_supplicant.conf
EOF

=====🌐 Networking & The "Wi-Fi Failover" Battle=====

This section documents the attempt to create a reliable wireless "emergency backdoor." The objective was to have the Wi-Fi (192.168.1.113) act as a secondary management port that remains accessible even if the 2.5G cable is pulled. The Problem was cuased by (Asymmetric Routing). Linux prefers the route with the lowest metric. Since the 2.5G wire has a metric of 10 and Wi-Fi has 100, pulling the cable caused a "Routing Black Hole"—Kiwi would receive requests via Wi-Fi but try to reply via the dead Ethernet cable.

Several fixes were applied including
* Kernel Routing Tweaks: Added to /etc/sysctl.conf to force the OS to ignore dead routes immediately
nano /etc/sysctl.conf

net.ipv4.conf.all.ignore_routes_with_linkdown=1
net.ipv4.conf.default.ignore_routes_with_linkdown=1
net.ipv4.conf.all.arp_ignore=1
net.ipv4.conf.all.arp_announce=2
* We tried to create service persistence. We created a systemd override for wpa_supplicant@wlp5s0 to handle driver timing issues
[Service]
Restart=on-failure
RestartSec=5s
ExecStartPost=/usr/sbin/ifup wlp5s0 --force

Proxmox Server

2026-05-01T07:33:04Z

Wikisailor: /* Pear */

==📋Introduction==

This is the server that will sit under my desk until I move house. It has the hostname Pear and will be the beginning of the '''[[Home Lab]]'''. There is also now a new smaller and less powerful server with the hostname Kiwi.

==🥝[[Create Virtual Machine from a template]]==

it is possible to create a new VM based on a fixed template. The two possibilities are a full clone or a linked clone. the linked clone is the preferred as it should need less storage but the full clone would be completely independent of the template so it will use more storage and take longer to create.We can go down that rabbit hole when we look ant Ansible in a big way. For now just understand that we can call a new vm using the qm clone command. the will be more details to follow.

==Orchard (Pear)==
The first host has Proxmox installed with the following specification

===🛠️Hardware Specification===

The Main components were purchased in 2024 as follows

* The Cpu is AMD Ryzen 9 5950X Processor (16Cores/32Threads, 105W TDP, Socket AM4, 72MB Cache, Up to 4.9 GHz Max Boost, no cooler) £369.98
* The cooler is Noctua NH-D15, Premium CPU Cooler with 2x NF-A15 PWM 140mm Fans (Brown) £99.95
* Mainboard is Gigabyte B550M AORUS ELITE Motherboard - Supports AMD Ryzen 5000 Series AM4 CPUs, 5+3 Phases Pure Digital VRM, up to 4733MHz DDR4 (OC), 2xPCIe 3.0 M.2, GbE LAN, USB 3.2 Gen1 £103.48
* 128gb Ram is configured as two sets of CORSAIR VENGEANCE LPX DDR4 RAM 64GB (2x32GB) 3200MHz CL16-20-20-38 1.35V (CMK64GX4M2E3200C16) £112.20 for one set
* GPU is a Gigabyte Geforce RTX 5060 TI with 16 GB Ram
* Power supply is Corsair RM750x 80 Plus Gold Fully Modular ATX 750 Watt Power Supply £109.00
* The case is Fractal Design Node 804 - Black - Compact Computer Case - mATX - High Airflow - Modular interior - 3x Fractal Design Silent R2 120mm Fans Included - Water-cooling ready - USB 3.0 -Window Side Panel £99.95
* SSD is Crucial P3 Plus SSD 4TB M.2 NVMe PCIe Gen4 Internal SSD, Up to 4800MB/s, Laptop & Desktop (PC) Compatible, Solid State Drive - CT4000P3PSSD801 £189.99 and £159.99
* Three 16 TB Seagate Ironwolf NAS drives make up the hard disk storage at a cost of £179.94 each total £ 539.82.
* One cheap 1 TB SATA SSD currently set as a L2ARC but may reconfigure as a sacrificial drive for the high wear VMs if it looks like it is not getting many hits as L2ARC '''Update ''' no longer used as L2ARC and formmated to a zpool fastpool.

===Configuration===

====🌐Network Access====

The IP Address and port of the host is 192.168.0.110:8006. I have my virgin media router forwarding all incoming traffic to 192.168.0.125 so it will go directly to the Pfsense firewall. All of the terminals can also send traffic to the WAN port of Pfsense. '''Edit''' with the change to Vodaphone the network address changed to 192.168.1.0/24 so Proxmox console is now 192.168.1.111:8006 and the WAN port of Pfsense is 192.168.1.125. a further change was to only forward those ports that are actually needed to Pfsense because the new ISP router has better options than the really old Virgin media one ( to be fair if i had stayed with Virgin i would have got a newer router). More '''[[Network Configuration]]''' details.

====💾Storage====

The main storage is the three 16TB hard drives configure into ZFS z1 so that they have one redundant disk. As one disk is redundant, obviously, it has 32TB of storage available.

I couldn't get PCI passthrough to work reliably without significant effort and some expense so I set up ZFS on Proxmox itself or more precisely on the Debian Linux that Proxmox resides on. Unfortunately, that means that I have to do any config on the CLI. I may write some scripts to perform some of the admin tasks or more likely setup a Nginx container to automate as much of it as possible. For the time being some useful ZFS commands can be found '''[[ZFS Commands |here]]'''

==🥝 Kiwi Host: Technical Manual & Build Log==

Kiwi is the secondary Proxmox host in the Home Lab, housed in a Fractal Design ITX chassis. While less powerful than the primary host (Pear), it serves as a high-capacity storage node and 2.5G data target.

=== Hardware Specification ===

* CPU: AMD Ryzen 5 with Stock Wraith Cooler.
* RAM: 64GB (2x32GB Crucial DDR4), maxing out the two available slots.
* System Drive: 2TB Samsung 990 Pro NVMe (Firmware verified: 5B2QJXD7).
* Storage Pool: 3x 14TB Seagate IronWolf Pro HDDs (ZFS RAIDZ1, 28TB usable).
* Network: Onboard 2.5 Gbps Wired NIC (nic0) + Built-in Wi-Fi (wlp5s0).
* GPU: Legacy Nvidia GPU (Required for POST and initial installation). The Mainboard has 4 SATA ports on board. Three of them have 14 TB Ironwolf pro drives to be formatted as a ZFS array with Z! so will give 28TB of usable storage with one disk of redundancy

===Proxmox Installation===

It is assumed that the Proxmox installer has been downloaded from their website and the iso has been copied on to a USB stick and made bootable with Rufus or some other similar. If the reader doesn't know how to make a USB installer from an ISO try typing "How do I make a USB stick into a proxmox installer" in to a browser. there will be loads of guides on how to use Rufus. When a bootable USB stick with Proxmox installer on it has been created insert in to one of the USB slots along with a keyboard, mouse and screen. Please note the keyboard mouse and screen will only be needed for the installation, once Proxmox is installed it is unlikely that these will ever be used again because virtually all administration is performed on a web GUI.

====BIOS settings for Hypervisors (including Proxmox)====

Generally most BIOS can be left at defaults and a PC as a PC will work well enough, maybe the boot priority may need to be changed from a HDD to a SSD but even that is unlikely. It is possible to optimise lots of things in BIOS and for some people that is an option but it is also easy to make mistakes that either stop the machine from working or making the machine unstable so for most people, most of the time, it is better to leave BIOS alone. A big exception is when a hypervisor is to be install because a few options that are off by default need to be set for Virtualisation to work properly. The main things to set are:-
* SVM Mode (AMD-V): '''Must be Enabled.''' This is what allows Proxmox to run VMs. Without it virtualisation will fail with most or possibly all hypervisors
* IOMMU: Set to Enabled. This is vital if you ever want to "pass through" a SATA controller or GPU directly to a VM. while not vital for the virtualisation itself most hypervisors have this enabled.
* Power Supply Idle Control: If you find the server randomly freezes when idle, set this to "Typical Current Idle". Ryzen chips sometimes drop voltage too low for some power supplies when idling, causing a crash. Again not vital but a "nice to have" if possible in the BIOS.
* Boot options: The SSD should be at the top. It is better to set the USB at the bottom so that if a USB is left in the machine and it is rebooted it doesn't try to boot from the USB.
Once the BIOS option are set save the settings and quit. The computer will shutdown and restart, while it is restarting keep pressing the delete key or the F12 key to bring up the boot options (it is usually delete key but it should also display the options briefly on the screen as it starts).

====GPU Considerations====

The Proxmox installation is a little bit more tricky than is standard for the majority of computers in that this has an old GPU that the installer does not recognise. A GPU is required so that the machine will pass POST but is not really need or used by the Proxmox guests so is generally of little benefit for the overall Proxmox day to day running. A lot of Hypervisor hosts have the cheapest and lowest power GPUs installed just enough to POST but no more than that. The reason that GPU is of low priorty for most hypervisors hosts is that they are generally run headless, that is without a monitor attached, all interations with the host is through a dedicated application like Citrix XEN, or more likely through a web browser like Proxmox. Web based GUIs are popular because it is a lot easier and lighter processor load to have a webserver attached than it is to design a whole application. Kiwi has an old Nvidia GPU that works in that it provides a display but that is about it. Unfortunately, it does give some problems for the installer as it is so old but therea re steps to overcome that as will be detailed below. We may add a bigger and better GPU at a later date but for the foreseeable future that is in the realms of an upgrade for later and dependant on inheriting a GPU from another box.

====Proxmox Installer problems (The Kiwi exceptions)====

As stated earlier the Proxmox installer does not work with the GPU. This is shown in that the machine boots and loads the first screen of the installer with welcome to.. but when the first option is tried it starts to load then freezes at the loading Nvidia drivers or some such thing(cant remember exactly what it says). so to fix that issue we need to restart the host and when we get to the welcome screen again we highlight "Install Proxmox VE (Graphical)" but '''do not press Enter''' instead we press "e" so a black screen with GNU GRUB appears. Edit the line
linux /boot/linux26 ro ramdisk_size=16777216 rw quiet splash=silent
so it reads
linux /boot/linux26 ro ramdisk_size=16777216 rw nomodeset
* By removing the quiet splash=silent we force the installer to show every single line of code as it loads. If it freezes again, we see the exact driver name where it stopped (e.g., sata_nv or i915).
* Adding nomodeset: This is the "magic bullet" for the nvidiafb hang. It tells the kernel not to touch the video drivers until the system is fully loaded. It is most likely where the installer hangs. As we should see every line of the execution of the installer if we have a different driver issue we should still see it.
To save the changes press ctrl+x or maybe F10. The GNU Grub screen will close and the graphical installer will continue until it gets to the "end user license agreement (EULA) screen. For anyone else reading this, If the installer freezes again before it gets to the EULA screen the error will most likely be in the last laine of text displayed. The most likely error will be a conflict between Debian kernel and Advanced Configuration and Power Interface (ACPI) in which case restart and press the "e" to get to the Grub config and edit the same line
linux /boot/linux26 ro ramdisk_size=16777216 rw nomodeset
so that it now has noapic added. note that this is just for the installer not the Proxmox application.
linux /boot/linux26 ro ramdisk_size=16777216 rw nomodeset noapic
After modifying that line press ctrl+x or F10 to save and proceed. if it stalls again you will need to look for the exact error in the last line or last few lines that the installer performed or any line that starts or ends with failed.

====Proxmox installer continued====

After the earlier problems we should have got to the ELUA screen so press "I agree" button to continue. The next screen will be about choosing hard drives. Kiwi has a single SSD and three Ironwolf Pro 14 TB HDDs. Obviously, we will not install the OS onto a HDD or even all three HDDs as it would be too slow and as the SSD is fast we will choose that as the Target Harddisk. with the SSD selected click on options button.
* select zfs (RAID0)
* select samsung SSD as hardisk 0
* select Do not use for harddisk 1
* select Do not use for harddisk 2
* select Do not use for harddisk 3
ZFS is the best choice as it has native compression, Bitrot detection but not really protection because there is only one drive so nowhere to restore any corrupt data from. ZFS also has good snapshot capability. Ext4 / XFS are "set it and forget it" options. They use almost zero RAM, but they offer no protection against data corruption and have very basic snapshotting capabilities (via LVM). Btrfs is similar to ZFS but generally considered less stable and has a lower feature set. The HDDs will not be used during the installation of Proxmox because it is easier to set them up from within the Proxmox web GUI or CLI.so the do not use is the best option for now '''note''' before we exit the Harddisk Options we need to check that the '''ashift''' is set to 12 so that the data blocks align with the physical page size of the Samsung 990 Pro's NAND, ensuring maximum speed, so select Advanced Options button next to Disk setup. Choose
* ashift is 12
* compress is on
* checksum is on
* copies is 1. Since this is a single-disk ZFS RAID0, copies=1 is the standard. If it is set it to 2, it would store every block twice on the same physical SSD. While that would allow ZFS to repair bitrot, it would effectively cut the 2TB SSD down to 1TB and halve the write speeds. With a 990 Pro, standard checksums and a good backup strategy are much more efficient.
* ARC max size 6422 Since there are only have two RAM slots and we are capped at 64GB, we need to be very intentional about how we carve up Kiwi RAM. having said that it is only a Maximum not a set size and zfs does not have to use all of it's maximum
* hdsize is set to maximum ( the + button will only allow it to be the size of the harddisk so click it until it stops going up)
Check the settings and when all looks correct click next for the regional settings
* Country United Kingdom
* Timezone Europe/London (or UTC if preferred)
* Keyboard Layout United Kingdom
Then next to set password and email address screen. Set a strong password that you can remember for the administration of the host. If the password is lost it will be almost impossible to recover it so do not forget it. Also it will be the hackers dream to get hold of the Proxmox host's password in that all of the rest of the security is mainly built on top of the administration of the host. If a host in a cluster is compromised it is quite likely that the whole cluster is compromised. The email address is so Proxmox can send promotional or updates but in general they don't flood their users with spam so it is no problem adding in a real email address. When done Click next to se the Management Network configuration screen.

The Management Network Configuration will determine where the WebGUI will be presented from. Kiwi has two NICs, one is the 2.5 GB p/s wired NIC and the other is the wireless NIC. by default it is likely to be the wired NIC that is going to be the one used for the management interface, mainly because at this stage WiFi has not been set up yet. Set up the options as follows
* Management Interface nic0 (the r8169 is the driver that Debian uses for wired nics) It is the one that is up and the Wifi nic is down so it is straight forward to establish which is which.
* hostname will be kiwi.seaoffate.net it is safe for us to use this domain name because we have registered it. If the reader has no domain name it could be kiwi.local but it would be unwise to use something that is already register on the public Internet, it may appear to work but there will be odd unforeseen problems like getting updates or push notifications or some other odd thing that don't work because the reply is being sent to a different IP address.
* IP address will be 192.168.1.112/24
* Gateway will be 192.168.1.1
* DNS will be 192.168.1.1
When this is done click next for the Summary. Make sure it is all correct and the auto reboot after successful installation then click install.

====Post Installation ====

When the host finishes the install it will restart. It may show the Proxmox Intallation again if the USB is still plugged in depending on the boot options, if so remove the USB and restart the computer. once the computer has finished starting it should show a simple login screen with the web address that is the main administration panel. from this point on the screen, mouse and keyboard can and should be removed as they will probably be never be used again. Now Kiwi will be managed from a web browser. The address will be whatever was set in the Management Network Configuration section with the port number 8006. in the case of Kiwi it is http://192.168.1.112:8006 the browser will give a security warning as no SSL cert has been setup for it yet so click advanced or ignore or whatever the browser needs to get to the web address. Then there will be a bank Proxmox screen with a popup in the middle with the title Proxmox VE Login the login details are
* Username root
* Password your_password ( whatever was set in the password and email section of the instalation)
* Realm is Linux PAM standard authentication
* Language English - English
'''note''' username and password are case sensitive

=====Samsung 990 Pro series SSDs Firmware=====
Now we have logged in we need to check that the Samsung SSD has got up to date firmware, '''Note This is for Samsung 990 Pro SSDs''' and not all SSDs it is not even all Samsung SSDs just this particular model in the early versions. Select Kiwi from the left pane then towards the top right of the main pane there is a row of buttons reboot, shutdown, shell, bulk actions, and help click on shell. A new window will appear with root@kiwi already logged in. Type the following into the window
smartctl -a /dev/nvme0n1
look through the information for the SSD, under === START OF INFORMATION SECTION === it should have a firmware Version line. Make sure the version is not "1B2QJXD7" it should be safe if it starts with 3 or more. If the Samsung 990 Pro SSD does have the unsafe version stop now and update the firmware immediately or it is likely that it will stop working after a short time. The version on this host is Firmware Version: 5B2QJXD7

=====Fix the No Subscription nag and do system update=====
By default, Proxmox tries to use a paid repository that you can't access. We need to disable that and add the free community one. This assumes that it is Proxmox version 9.x. Proxmox 9 uses .sources files. We must disable the default enterprise links and add the community repository. Run these commands in the Kiwi shell
# 1. Disable Enterprise PVE Repo
mv /etc/apt/sources.list.d/pve-enterprise.sources /etc/apt/sources.list.d/pve-enterprise.sources.bak
# 2. Disable Enterprise Ceph Repo
mv /etc/apt/sources.list.d/ceph.sources /etc/apt/sources.list.d/ceph.sources.bak
# 3. Create the No-Subscription Source
cat <<EOF > /etc/apt/sources.list.d/pve-no-subscription.sources
Types: deb
URIs: http://download.proxmox.com/debian/pve
Suites: trixie
Components: pve-no-subscription
Architectures: amd64
Signed-By: /usr/share/keyrings/proxmox-archive-keyring.gpg
EOF
The "No-Nag" UI Patch: This command neutralizes the subscription check in the web interface and restarts the proxy service to apply it
# 4. Remove 'No Valid Subscription' Login Popup
sed -Ezi.bak "s/(Ext.Msg.show\(\{\s+title: gettext\(\'No valid sub)/void\(\{ \/\/\1/g" /usr/share/javascript/proxmox-widget-toolkit/proxmoxlib.js && systemctl restart pveproxy.service
When the system reboots open a new console window for the host. So we can do an update. Always use dist-upgrade for Proxmox to ensure kernel and dependency changes are handled correctly.
# 5. Refresh and Upgrade
apt update && apt dist-upgrade -y
Summary of why we did this
* The .bak method: Instead of fighting sed patterns that might change, moving the files to .bak is a "bulletproof" way to ensure apt ignores them.
* Trixie Suites: Using Suites: trixie ensures you aren't pulling in old bookworm (Proxmox 8) packages that could destabilize your new Ryzen 5 build.
* The 63 Packages: Now that you've run the update, those 63 packages are waiting. Running the dist-upgrade command above will install the latest 2026 security patches and hardware drivers.

=====Ironwolf Pro Harddrive Setup=====

Since we have already performed the dist-upgrade, the kernel is fresh and ready to handle the heavy I/O of those 14TB drives. We will set this up via the CLI to ensure we get the exact optimizations needed for a high-density vault. First, we must be 100% certain which device names (/dev/sdX) belong to the IronWolfs.
lsblk -o NAME,SIZE,MODEL,SERIAL
Look for the three drives that show approximately 12.7T (the TiB equivalent of 14TB). Verify the Model says ST14000.... In this case they are
* sda 12.7T ST14000NE0008-2JK101 ZTM0D5FK
* sdb 12.7T ST14000NE0008-2H4101 ZL2EJCXX (this one has a partition sdb1 but we ignore it)
* sdc 12.7T ST14000NE0008-2JK101 ZTM0D5A0
The Clean Slate (Wipe the Labels) Run these commands to clear the old ZFS and EFI labels. This doesn't delete all of the old data (which takes hours), it just "un-formats" the start and end of the disks so ZFS sees them as new. It may not be necessary for all of the drives but certainly is for sdb as that has a partition on it
# Wipe the ZFS labels specifically
zpool labelclear -f /dev/sda
zpool labelclear -f /dev/sdb
zpool labelclear -f /dev/sdc
# Wipe the partition tables entirely (the "Nuclear" option)
wipefs -a /dev/sda
wipefs -a /dev/sdb
wipefs -a /dev/sdc

The other drive is the 990 Pro SSD. Now we can create the ZFS Z1 Pool We will name the pool kiwipool. We are using ashift=12 for 4K sector alignment and atime=off to save the mechanical heads from unnecessary movement.
zpool create -o ashift=12 kiwipool raidz1 /dev/sda /dev/sdb /dev/sdc
# Apply optimizations
zfs set compression=lz4 kiwipool
zfs set atime=off kiwipool
zfs set xattr=sa kiwipool
zfs set recordsize=1M kiwipool
once that is done we can verify the pool is built with
zpool status kiwipool
Next we need to make some datasets to keep the pool organised and not write anything to the root of kiwipool. Run thes commands
zfs create kiwipool/PFK
zfs create kiwipool/PFK/pdata
zfs create kiwipool/PFK/pdata/KiwiHDs
zfs create kiwipool/ISO
zfs create kiwipool/PFK/backups
zfs list
The zpool will show up in the webgui in Kiwi->storage and kiwi->zfs but not in the VM list on the left hand pane so they cannot be added to VMs yet. To make them available we run the command
pvesm add zfspool KiwiHDs --pool kiwipool/PFK/pdata/KiwiHDs --content rootdir,images
pvesm add dir KiwiISOs --path /kiwipool/ISO --content iso,vztmpl
pvesm add dir KiwiBackups --path /kiwipool/PFK/backups --content backup
Now in the webgui there should be the drives for VM HDs, ISOs and backups

=====Check and configure the WiFi=====

Testing Wi-Fi on a Proxmox (Debian) host is a bit different than on a laptop because there is no "taskbar" to click. We have to do this through the CLI. First, let's see if Debian even sees the Wi-Fi card and has the drivers loaded.
ip link
Look for: An interface starting with w (e.g., wlp2s0 or wlan0). If you don't see one the drivers might be missing or it's "Hard Blocked" in the BIOS. In this case The hardware check is a success. Your Wi-Fi card is identified as wlp5s0 (it did show up in the installer but it was ignored then ). The state is currently DOWN, which is expected since it hasn't been configured with your SSID or credentials yet. Because Proxmox is built for servers, it lacks a graphical Wi-Fi picker. We have to manually tell the background service (wpa_supplicant) how to talk to your router. at the same time install the wireless tools package.
apt update && apt install wpasupplicant wireless-tools -y
Instead of typing the Wi-Fi password in plain text, we’ll use a tool to generate a secure configuration block. Replace Your_SSID and Your_Password with your actual wireless AP details:
wpa_passphrase "Your_SSID" "Your_Password" > /etc/wpa_supplicant/wpa_supplicant.conf
Now we can test the connection let's see if Kiwi can actually authenticate.
wpa_supplicant -B -i wlp5s0 -c /etc/wpa_supplicant/wpa_supplicant.conf
Then wait a few seconds before checking the status with
iw wlp5s0 link
Assuming it shows a connection we can make it permanent. To ensure the Wi-Fi comes up automatically on boot and acts as a secondary management port, we need to add it to the network interfaces file. Warning: Be very careful with the syntax here. Use this command to append the configuration to /etc/network/interfaces. cat <<EOF >> /etc/network/interfaces
auto wlp5s0
iface wlp5s0 inet static
address 192.168.1.113/24
wpa-conf /etc/wpa_supplicant/wpa_supplicant.conf
EOF

=====🌐 Networking & The "Wi-Fi Failover" Battle=====

This section documents the attempt to create a reliable wireless "emergency backdoor." The objective was to have the Wi-Fi (192.168.1.113) act as a secondary management port that remains accessible even if the 2.5G cable is pulled. The Problem was cuased by (Asymmetric Routing). Linux prefers the route with the lowest metric. Since the 2.5G wire has a metric of 10 and Wi-Fi has 100, pulling the cable caused a "Routing Black Hole"—Kiwi would receive requests via Wi-Fi but try to reply via the dead Ethernet cable.

Several fixes were applied including
* Kernel Routing Tweaks: Added to /etc/sysctl.conf to force the OS to ignore dead routes immediately
nano /etc/sysctl.conf

net.ipv4.conf.all.ignore_routes_with_linkdown=1
net.ipv4.conf.default.ignore_routes_with_linkdown=1
net.ipv4.conf.all.arp_ignore=1
net.ipv4.conf.all.arp_announce=2
* We tried to create service persistence. We created a systemd override for wpa_supplicant@wlp5s0 to handle driver timing issues
[Service]
Restart=on-failure
RestartSec=5s
ExecStartPost=/usr/sbin/ifup wlp5s0 --force

Proxmox Server

2026-05-01T04:35:52Z

Wikisailor: /* 🌐Network Access */

==📋Introduction==

This is the server that will sit under my desk until I move house. It has the hostname Pear and will be the beginning of the '''[[Home Lab]]'''. There is also now a new smaller and less powerful server with the hostname Kiwi.

==🥝[[Create Virtual Machine from a template]]==

it is possible to create a new VM based on a fixed template. The two possibilities are a full clone or a linked clone. the linked clone is the preferred as it should need less storage but the full clone would be completely independent of the template so it will use more storage and take longer to create.We can go down that rabbit hole when we look ant Ansible in a big way. For now just understand that we can call a new vm using the qm clone command. the will be more details to follow.

==Pear==
The first host has Proxmox installed with the following specificatio

===🛠️Hardware Specification===

The Main components were purchased in 2024 as follows

* The Cpu is AMD Ryzen 9 5950X Processor (16Cores/32Threads, 105W TDP, Socket AM4, 72MB Cache, Up to 4.9 GHz Max Boost, no cooler) £369.98
* The cooler is Noctua NH-D15, Premium CPU Cooler with 2x NF-A15 PWM 140mm Fans (Brown) £99.95
* Mainboard is Gigabyte B550M AORUS ELITE Motherboard - Supports AMD Ryzen 5000 Series AM4 CPUs, 5+3 Phases Pure Digital VRM, up to 4733MHz DDR4 (OC), 2xPCIe 3.0 M.2, GbE LAN, USB 3.2 Gen1 £103.48
* 128gb Ram is configured as two sets of CORSAIR VENGEANCE LPX DDR4 RAM 64GB (2x32GB) 3200MHz CL16-20-20-38 1.35V (CMK64GX4M2E3200C16) £112.20 for one set
* GPU is a Gigabyte Geforce RTX 5060 TI with 16 GB Ram
* Power supply is Corsair RM750x 80 Plus Gold Fully Modular ATX 750 Watt Power Supply £109.00
* The case is Fractal Design Node 804 - Black - Compact Computer Case - mATX - High Airflow - Modular interior - 3x Fractal Design Silent R2 120mm Fans Included - Water-cooling ready - USB 3.0 -Window Side Panel £99.95
* SSD is Crucial P3 Plus SSD 4TB M.2 NVMe PCIe Gen4 Internal SSD, Up to 4800MB/s, Laptop & Desktop (PC) Compatible, Solid State Drive - CT4000P3PSSD801 £189.99 and £159.99
* Three 16 TB Seagate Ironwolf NAS drives make up the hard disk storage at a cost of £179.94 each total £ 539.82.
* One cheap 1 TB SATA SSD currently set as a L2ARC but may reconfigure as a sacrificial drive for the high wear VMs if it looks like it is not getting many hits as L2ARC '''Update ''' no longer used as L2ARC and formmated to a zpool fastpool.

===Configuration===

====🌐Network Access====

The IP Address and port of the host is 192.168.0.110:8006. I have my virgin media router forwarding all incoming traffic to 192.168.0.125 so it will go directly to the Pfsense firewall. All of the terminals can also send traffic to the WAN port of Pfsense. '''Edit''' with the change to Vodaphone the network address changed to 192.168.1.0/24 so Proxmox console is now 192.168.1.111:8006 and the WAN port of Pfsense is 192.168.1.125. a further change was to only forward those ports that are actually needed to Pfsense because the new ISP router has better options than the really old Virgin media one ( to be fair if i had stayed with Virgin i would have got a newer router). More '''[[Network Configuration]]''' details.

====💾Storage====

The main storage is the three 16TB hard drives configure into ZFS z1 so that they have one redundant disk. As one disk is redundant, obviously, it has 32TB of storage available.

I couldn't get PCI passthrough to work reliably without significant effort and some expense so I set up ZFS on Proxmox itself or more precisely on the Debian Linux that Proxmox resides on. Unfortunately, that means that I have to do any config on the CLI. I may write some scripts to perform some of the admin tasks or more likely setup a Nginx container to automate as much of it as possible. For the time being some useful ZFS commands can be found '''[[ZFS Commands |here]]'''

==🥝 Kiwi Host: Technical Manual & Build Log==

Kiwi is the secondary Proxmox host in the Home Lab, housed in a Fractal Design ITX chassis. While less powerful than the primary host (Pear), it serves as a high-capacity storage node and 2.5G data target.

=== Hardware Specification ===

* CPU: AMD Ryzen 5 with Stock Wraith Cooler.
* RAM: 64GB (2x32GB Crucial DDR4), maxing out the two available slots.
* System Drive: 2TB Samsung 990 Pro NVMe (Firmware verified: 5B2QJXD7).
* Storage Pool: 3x 14TB Seagate IronWolf Pro HDDs (ZFS RAIDZ1, 28TB usable).
* Network: Onboard 2.5 Gbps Wired NIC (nic0) + Built-in Wi-Fi (wlp5s0).
* GPU: Legacy Nvidia GPU (Required for POST and initial installation). The Mainboard has 4 SATA ports on board. Three of them have 14 TB Ironwolf pro drives to be formatted as a ZFS array with Z! so will give 28TB of usable storage with one disk of redundancy

===Proxmox Installation===

It is assumed that the Proxmox installer has been downloaded from their website and the iso has been copied on to a USB stick and made bootable with Rufus or some other similar. If the reader doesn't know how to make a USB installer from an ISO try typing "How do I make a USB stick into a proxmox installer" in to a browser. there will be loads of guides on how to use Rufus. When a bootable USB stick with Proxmox installer on it has been created insert in to one of the USB slots along with a keyboard, mouse and screen. Please note the keyboard mouse and screen will only be needed for the installation, once Proxmox is installed it is unlikely that these will ever be used again because virtually all administration is performed on a web GUI.

====BIOS settings for Hypervisors (including Proxmox)====

Generally most BIOS can be left at defaults and a PC as a PC will work well enough, maybe the boot priority may need to be changed from a HDD to a SSD but even that is unlikely. It is possible to optimise lots of things in BIOS and for some people that is an option but it is also easy to make mistakes that either stop the machine from working or making the machine unstable so for most people, most of the time, it is better to leave BIOS alone. A big exception is when a hypervisor is to be install because a few options that are off by default need to be set for Virtualisation to work properly. The main things to set are:-
* SVM Mode (AMD-V): '''Must be Enabled.''' This is what allows Proxmox to run VMs. Without it virtualisation will fail with most or possibly all hypervisors
* IOMMU: Set to Enabled. This is vital if you ever want to "pass through" a SATA controller or GPU directly to a VM. while not vital for the virtualisation itself most hypervisors have this enabled.
* Power Supply Idle Control: If you find the server randomly freezes when idle, set this to "Typical Current Idle". Ryzen chips sometimes drop voltage too low for some power supplies when idling, causing a crash. Again not vital but a "nice to have" if possible in the BIOS.
* Boot options: The SSD should be at the top. It is better to set the USB at the bottom so that if a USB is left in the machine and it is rebooted it doesn't try to boot from the USB.
Once the BIOS option are set save the settings and quit. The computer will shutdown and restart, while it is restarting keep pressing the delete key or the F12 key to bring up the boot options (it is usually delete key but it should also display the options briefly on the screen as it starts).

====GPU Considerations====

The Proxmox installation is a little bit more tricky than is standard for the majority of computers in that this has an old GPU that the installer does not recognise. A GPU is required so that the machine will pass POST but is not really need or used by the Proxmox guests so is generally of little benefit for the overall Proxmox day to day running. A lot of Hypervisor hosts have the cheapest and lowest power GPUs installed just enough to POST but no more than that. The reason that GPU is of low priorty for most hypervisors hosts is that they are generally run headless, that is without a monitor attached, all interations with the host is through a dedicated application like Citrix XEN, or more likely through a web browser like Proxmox. Web based GUIs are popular because it is a lot easier and lighter processor load to have a webserver attached than it is to design a whole application. Kiwi has an old Nvidia GPU that works in that it provides a display but that is about it. Unfortunately, it does give some problems for the installer as it is so old but therea re steps to overcome that as will be detailed below. We may add a bigger and better GPU at a later date but for the foreseeable future that is in the realms of an upgrade for later and dependant on inheriting a GPU from another box.

====Proxmox Installer problems (The Kiwi exceptions)====

As stated earlier the Proxmox installer does not work with the GPU. This is shown in that the machine boots and loads the first screen of the installer with welcome to.. but when the first option is tried it starts to load then freezes at the loading Nvidia drivers or some such thing(cant remember exactly what it says). so to fix that issue we need to restart the host and when we get to the welcome screen again we highlight "Install Proxmox VE (Graphical)" but '''do not press Enter''' instead we press "e" so a black screen with GNU GRUB appears. Edit the line
linux /boot/linux26 ro ramdisk_size=16777216 rw quiet splash=silent
so it reads
linux /boot/linux26 ro ramdisk_size=16777216 rw nomodeset
* By removing the quiet splash=silent we force the installer to show every single line of code as it loads. If it freezes again, we see the exact driver name where it stopped (e.g., sata_nv or i915).
* Adding nomodeset: This is the "magic bullet" for the nvidiafb hang. It tells the kernel not to touch the video drivers until the system is fully loaded. It is most likely where the installer hangs. As we should see every line of the execution of the installer if we have a different driver issue we should still see it.
To save the changes press ctrl+x or maybe F10. The GNU Grub screen will close and the graphical installer will continue until it gets to the "end user license agreement (EULA) screen. For anyone else reading this, If the installer freezes again before it gets to the EULA screen the error will most likely be in the last laine of text displayed. The most likely error will be a conflict between Debian kernel and Advanced Configuration and Power Interface (ACPI) in which case restart and press the "e" to get to the Grub config and edit the same line
linux /boot/linux26 ro ramdisk_size=16777216 rw nomodeset
so that it now has noapic added. note that this is just for the installer not the Proxmox application.
linux /boot/linux26 ro ramdisk_size=16777216 rw nomodeset noapic
After modifying that line press ctrl+x or F10 to save and proceed. if it stalls again you will need to look for the exact error in the last line or last few lines that the installer performed or any line that starts or ends with failed.

====Proxmox installer continued====

After the earlier problems we should have got to the ELUA screen so press "I agree" button to continue. The next screen will be about choosing hard drives. Kiwi has a single SSD and three Ironwolf Pro 14 TB HDDs. Obviously, we will not install the OS onto a HDD or even all three HDDs as it would be too slow and as the SSD is fast we will choose that as the Target Harddisk. with the SSD selected click on options button.
* select zfs (RAID0)
* select samsung SSD as hardisk 0
* select Do not use for harddisk 1
* select Do not use for harddisk 2
* select Do not use for harddisk 3
ZFS is the best choice as it has native compression, Bitrot detection but not really protection because there is only one drive so nowhere to restore any corrupt data from. ZFS also has good snapshot capability. Ext4 / XFS are "set it and forget it" options. They use almost zero RAM, but they offer no protection against data corruption and have very basic snapshotting capabilities (via LVM). Btrfs is similar to ZFS but generally considered less stable and has a lower feature set. The HDDs will not be used during the installation of Proxmox because it is easier to set them up from within the Proxmox web GUI or CLI.so the do not use is the best option for now '''note''' before we exit the Harddisk Options we need to check that the '''ashift''' is set to 12 so that the data blocks align with the physical page size of the Samsung 990 Pro's NAND, ensuring maximum speed, so select Advanced Options button next to Disk setup. Choose
* ashift is 12
* compress is on
* checksum is on
* copies is 1. Since this is a single-disk ZFS RAID0, copies=1 is the standard. If it is set it to 2, it would store every block twice on the same physical SSD. While that would allow ZFS to repair bitrot, it would effectively cut the 2TB SSD down to 1TB and halve the write speeds. With a 990 Pro, standard checksums and a good backup strategy are much more efficient.
* ARC max size 6422 Since there are only have two RAM slots and we are capped at 64GB, we need to be very intentional about how we carve up Kiwi RAM. having said that it is only a Maximum not a set size and zfs does not have to use all of it's maximum
* hdsize is set to maximum ( the + button will only allow it to be the size of the harddisk so click it until it stops going up)
Check the settings and when all looks correct click next for the regional settings
* Country United Kingdom
* Timezone Europe/London (or UTC if preferred)
* Keyboard Layout United Kingdom
Then next to set password and email address screen. Set a strong password that you can remember for the administration of the host. If the password is lost it will be almost impossible to recover it so do not forget it. Also it will be the hackers dream to get hold of the Proxmox host's password in that all of the rest of the security is mainly built on top of the administration of the host. If a host in a cluster is compromised it is quite likely that the whole cluster is compromised. The email address is so Proxmox can send promotional or updates but in general they don't flood their users with spam so it is no problem adding in a real email address. When done Click next to se the Management Network configuration screen.

The Management Network Configuration will determine where the WebGUI will be presented from. Kiwi has two NICs, one is the 2.5 GB p/s wired NIC and the other is the wireless NIC. by default it is likely to be the wired NIC that is going to be the one used for the management interface, mainly because at this stage WiFi has not been set up yet. Set up the options as follows
* Management Interface nic0 (the r8169 is the driver that Debian uses for wired nics) It is the one that is up and the Wifi nic is down so it is straight forward to establish which is which.
* hostname will be kiwi.seaoffate.net it is safe for us to use this domain name because we have registered it. If the reader has no domain name it could be kiwi.local but it would be unwise to use something that is already register on the public Internet, it may appear to work but there will be odd unforeseen problems like getting updates or push notifications or some other odd thing that don't work because the reply is being sent to a different IP address.
* IP address will be 192.168.1.112/24
* Gateway will be 192.168.1.1
* DNS will be 192.168.1.1
When this is done click next for the Summary. Make sure it is all correct and the auto reboot after successful installation then click install.

====Post Installation ====

When the host finishes the install it will restart. It may show the Proxmox Intallation again if the USB is still plugged in depending on the boot options, if so remove the USB and restart the computer. once the computer has finished starting it should show a simple login screen with the web address that is the main administration panel. from this point on the screen, mouse and keyboard can and should be removed as they will probably be never be used again. Now Kiwi will be managed from a web browser. The address will be whatever was set in the Management Network Configuration section with the port number 8006. in the case of Kiwi it is http://192.168.1.112:8006 the browser will give a security warning as no SSL cert has been setup for it yet so click advanced or ignore or whatever the browser needs to get to the web address. Then there will be a bank Proxmox screen with a popup in the middle with the title Proxmox VE Login the login details are
* Username root
* Password your_password ( whatever was set in the password and email section of the instalation)
* Realm is Linux PAM standard authentication
* Language English - English
'''note''' username and password are case sensitive

=====Samsung 990 Pro series SSDs Firmware=====
Now we have logged in we need to check that the Samsung SSD has got up to date firmware, '''Note This is for Samsung 990 Pro SSDs''' and not all SSDs it is not even all Samsung SSDs just this particular model in the early versions. Select Kiwi from the left pane then towards the top right of the main pane there is a row of buttons reboot, shutdown, shell, bulk actions, and help click on shell. A new window will appear with root@kiwi already logged in. Type the following into the window
smartctl -a /dev/nvme0n1
look through the information for the SSD, under === START OF INFORMATION SECTION === it should have a firmware Version line. Make sure the version is not "1B2QJXD7" it should be safe if it starts with 3 or more. If the Samsung 990 Pro SSD does have the unsafe version stop now and update the firmware immediately or it is likely that it will stop working after a short time. The version on this host is Firmware Version: 5B2QJXD7

=====Fix the No Subscription nag and do system update=====
By default, Proxmox tries to use a paid repository that you can't access. We need to disable that and add the free community one. This assumes that it is Proxmox version 9.x. Proxmox 9 uses .sources files. We must disable the default enterprise links and add the community repository. Run these commands in the Kiwi shell
# 1. Disable Enterprise PVE Repo
mv /etc/apt/sources.list.d/pve-enterprise.sources /etc/apt/sources.list.d/pve-enterprise.sources.bak
# 2. Disable Enterprise Ceph Repo
mv /etc/apt/sources.list.d/ceph.sources /etc/apt/sources.list.d/ceph.sources.bak
# 3. Create the No-Subscription Source
cat <<EOF > /etc/apt/sources.list.d/pve-no-subscription.sources
Types: deb
URIs: http://download.proxmox.com/debian/pve
Suites: trixie
Components: pve-no-subscription
Architectures: amd64
Signed-By: /usr/share/keyrings/proxmox-archive-keyring.gpg
EOF
The "No-Nag" UI Patch: This command neutralizes the subscription check in the web interface and restarts the proxy service to apply it
# 4. Remove 'No Valid Subscription' Login Popup
sed -Ezi.bak "s/(Ext.Msg.show\(\{\s+title: gettext\(\'No valid sub)/void\(\{ \/\/\1/g" /usr/share/javascript/proxmox-widget-toolkit/proxmoxlib.js && systemctl restart pveproxy.service
When the system reboots open a new console window for the host. So we can do an update. Always use dist-upgrade for Proxmox to ensure kernel and dependency changes are handled correctly.
# 5. Refresh and Upgrade
apt update && apt dist-upgrade -y
Summary of why we did this
* The .bak method: Instead of fighting sed patterns that might change, moving the files to .bak is a "bulletproof" way to ensure apt ignores them.
* Trixie Suites: Using Suites: trixie ensures you aren't pulling in old bookworm (Proxmox 8) packages that could destabilize your new Ryzen 5 build.
* The 63 Packages: Now that you've run the update, those 63 packages are waiting. Running the dist-upgrade command above will install the latest 2026 security patches and hardware drivers.

=====Ironwolf Pro Harddrive Setup=====

Since we have already performed the dist-upgrade, the kernel is fresh and ready to handle the heavy I/O of those 14TB drives. We will set this up via the CLI to ensure we get the exact optimizations needed for a high-density vault. First, we must be 100% certain which device names (/dev/sdX) belong to the IronWolfs.
lsblk -o NAME,SIZE,MODEL,SERIAL
Look for the three drives that show approximately 12.7T (the TiB equivalent of 14TB). Verify the Model says ST14000.... In this case they are
* sda 12.7T ST14000NE0008-2JK101 ZTM0D5FK
* sdb 12.7T ST14000NE0008-2H4101 ZL2EJCXX (this one has a partition sdb1 but we ignore it)
* sdc 12.7T ST14000NE0008-2JK101 ZTM0D5A0
The Clean Slate (Wipe the Labels) Run these commands to clear the old ZFS and EFI labels. This doesn't delete all of the old data (which takes hours), it just "un-formats" the start and end of the disks so ZFS sees them as new. It may not be necessary for all of the drives but certainly is for sdb as that has a partition on it
# Wipe the ZFS labels specifically
zpool labelclear -f /dev/sda
zpool labelclear -f /dev/sdb
zpool labelclear -f /dev/sdc
# Wipe the partition tables entirely (the "Nuclear" option)
wipefs -a /dev/sda
wipefs -a /dev/sdb
wipefs -a /dev/sdc

The other drive is the 990 Pro SSD. Now we can create the ZFS Z1 Pool We will name the pool kiwipool. We are using ashift=12 for 4K sector alignment and atime=off to save the mechanical heads from unnecessary movement.
zpool create -o ashift=12 kiwipool raidz1 /dev/sda /dev/sdb /dev/sdc
# Apply optimizations
zfs set compression=lz4 kiwipool
zfs set atime=off kiwipool
zfs set xattr=sa kiwipool
zfs set recordsize=1M kiwipool
once that is done we can verify the pool is built with
zpool status kiwipool
Next we need to make some datasets to keep the pool organised and not write anything to the root of kiwipool. Run thes commands
zfs create kiwipool/PFK
zfs create kiwipool/PFK/pdata
zfs create kiwipool/PFK/pdata/KiwiHDs
zfs create kiwipool/ISO
zfs create kiwipool/PFK/backups
zfs list
The zpool will show up in the webgui in Kiwi->storage and kiwi->zfs but not in the VM list on the left hand pane so they cannot be added to VMs yet. To make them available we run the command
pvesm add zfspool KiwiHDs --pool kiwipool/PFK/pdata/KiwiHDs --content rootdir,images
pvesm add dir KiwiISOs --path /kiwipool/ISO --content iso,vztmpl
pvesm add dir KiwiBackups --path /kiwipool/PFK/backups --content backup
Now in the webgui there should be the drives for VM HDs, ISOs and backups

=====Check and configure the WiFi=====

Testing Wi-Fi on a Proxmox (Debian) host is a bit different than on a laptop because there is no "taskbar" to click. We have to do this through the CLI. First, let's see if Debian even sees the Wi-Fi card and has the drivers loaded.
ip link
Look for: An interface starting with w (e.g., wlp2s0 or wlan0). If you don't see one the drivers might be missing or it's "Hard Blocked" in the BIOS. In this case The hardware check is a success. Your Wi-Fi card is identified as wlp5s0 (it did show up in the installer but it was ignored then ). The state is currently DOWN, which is expected since it hasn't been configured with your SSID or credentials yet. Because Proxmox is built for servers, it lacks a graphical Wi-Fi picker. We have to manually tell the background service (wpa_supplicant) how to talk to your router. at the same time install the wireless tools package.
apt update && apt install wpasupplicant wireless-tools -y
Instead of typing the Wi-Fi password in plain text, we’ll use a tool to generate a secure configuration block. Replace Your_SSID and Your_Password with your actual wireless AP details:
wpa_passphrase "Your_SSID" "Your_Password" > /etc/wpa_supplicant/wpa_supplicant.conf
Now we can test the connection let's see if Kiwi can actually authenticate.
wpa_supplicant -B -i wlp5s0 -c /etc/wpa_supplicant/wpa_supplicant.conf
Then wait a few seconds before checking the status with
iw wlp5s0 link
Assuming it shows a connection we can make it permanent. To ensure the Wi-Fi comes up automatically on boot and acts as a secondary management port, we need to add it to the network interfaces file. Warning: Be very careful with the syntax here. Use this command to append the configuration to /etc/network/interfaces. cat <<EOF >> /etc/network/interfaces
auto wlp5s0
iface wlp5s0 inet static
address 192.168.1.113/24
wpa-conf /etc/wpa_supplicant/wpa_supplicant.conf
EOF

=====🌐 Networking & The "Wi-Fi Failover" Battle=====

This section documents the attempt to create a reliable wireless "emergency backdoor." The objective was to have the Wi-Fi (192.168.1.113) act as a secondary management port that remains accessible even if the 2.5G cable is pulled. The Problem was cuased by (Asymmetric Routing). Linux prefers the route with the lowest metric. Since the 2.5G wire has a metric of 10 and Wi-Fi has 100, pulling the cable caused a "Routing Black Hole"—Kiwi would receive requests via Wi-Fi but try to reply via the dead Ethernet cable.

Several fixes were applied including
* Kernel Routing Tweaks: Added to /etc/sysctl.conf to force the OS to ignore dead routes immediately
nano /etc/sysctl.conf

net.ipv4.conf.all.ignore_routes_with_linkdown=1
net.ipv4.conf.default.ignore_routes_with_linkdown=1
net.ipv4.conf.all.arp_ignore=1
net.ipv4.conf.all.arp_announce=2
* We tried to create service persistence. We created a systemd override for wpa_supplicant@wlp5s0 to handle driver timing issues
[Service]
Restart=on-failure
RestartSec=5s
ExecStartPost=/usr/sbin/ifup wlp5s0 --force

Proxmox Server

2026-05-01T04:35:25Z

Wikisailor: /* 🌐Network Access */

==📋Introduction==

This is the server that will sit under my desk until I move house. It has the hostname Pear and will be the beginning of the '''[[Home Lab]]'''. There is also now a new smaller and less powerful server with the hostname Kiwi.

==🥝[[Create Virtual Machine from a template]]==

it is possible to create a new VM based on a fixed template. The two possibilities are a full clone or a linked clone. the linked clone is the preferred as it should need less storage but the full clone would be completely independent of the template so it will use more storage and take longer to create.We can go down that rabbit hole when we look ant Ansible in a big way. For now just understand that we can call a new vm using the qm clone command. the will be more details to follow.

==Pear==
The first host has Proxmox installed with the following specificatio

===🛠️Hardware Specification===

The Main components were purchased in 2024 as follows

* The Cpu is AMD Ryzen 9 5950X Processor (16Cores/32Threads, 105W TDP, Socket AM4, 72MB Cache, Up to 4.9 GHz Max Boost, no cooler) £369.98
* The cooler is Noctua NH-D15, Premium CPU Cooler with 2x NF-A15 PWM 140mm Fans (Brown) £99.95
* Mainboard is Gigabyte B550M AORUS ELITE Motherboard - Supports AMD Ryzen 5000 Series AM4 CPUs, 5+3 Phases Pure Digital VRM, up to 4733MHz DDR4 (OC), 2xPCIe 3.0 M.2, GbE LAN, USB 3.2 Gen1 £103.48
* 128gb Ram is configured as two sets of CORSAIR VENGEANCE LPX DDR4 RAM 64GB (2x32GB) 3200MHz CL16-20-20-38 1.35V (CMK64GX4M2E3200C16) £112.20 for one set
* GPU is a Gigabyte Geforce RTX 5060 TI with 16 GB Ram
* Power supply is Corsair RM750x 80 Plus Gold Fully Modular ATX 750 Watt Power Supply £109.00
* The case is Fractal Design Node 804 - Black - Compact Computer Case - mATX - High Airflow - Modular interior - 3x Fractal Design Silent R2 120mm Fans Included - Water-cooling ready - USB 3.0 -Window Side Panel £99.95
* SSD is Crucial P3 Plus SSD 4TB M.2 NVMe PCIe Gen4 Internal SSD, Up to 4800MB/s, Laptop & Desktop (PC) Compatible, Solid State Drive - CT4000P3PSSD801 £189.99 and £159.99
* Three 16 TB Seagate Ironwolf NAS drives make up the hard disk storage at a cost of £179.94 each total £ 539.82.
* One cheap 1 TB SATA SSD currently set as a L2ARC but may reconfigure as a sacrificial drive for the high wear VMs if it looks like it is not getting many hits as L2ARC '''Update ''' no longer used as L2ARC and formmated to a zpool fastpool.

===Configuration===

====🌐Network Access====

The IP Address and port of the host is 192.168.0.110:8006. I have my virgin media router forwarding all incoming traffic to 192.168.0.125 so it will go directly to the Pfsense firewall. All of the terminals can also send traffic to the WAN port of Pfsense. '''Edit''' with the change to Vodaphone the network address changed to 192.168.1.0/24 so Proxmox console is now 192.168.1.111:8006 and the WAN port of Pfsense is 192.168.1.125. a further change was to only forward those ports that are actually needed to Pfsense because the new ISP router has better options than the really old Virgin media one ( to be fair if i had stayed with Virgin i would have got a newer router). More [[Network Configuration]] details.

====💾Storage====

The main storage is the three 16TB hard drives configure into ZFS z1 so that they have one redundant disk. As one disk is redundant, obviously, it has 32TB of storage available.

I couldn't get PCI passthrough to work reliably without significant effort and some expense so I set up ZFS on Proxmox itself or more precisely on the Debian Linux that Proxmox resides on. Unfortunately, that means that I have to do any config on the CLI. I may write some scripts to perform some of the admin tasks or more likely setup a Nginx container to automate as much of it as possible. For the time being some useful ZFS commands can be found '''[[ZFS Commands |here]]'''

==🥝 Kiwi Host: Technical Manual & Build Log==

Kiwi is the secondary Proxmox host in the Home Lab, housed in a Fractal Design ITX chassis. While less powerful than the primary host (Pear), it serves as a high-capacity storage node and 2.5G data target.

=== Hardware Specification ===

* CPU: AMD Ryzen 5 with Stock Wraith Cooler.
* RAM: 64GB (2x32GB Crucial DDR4), maxing out the two available slots.
* System Drive: 2TB Samsung 990 Pro NVMe (Firmware verified: 5B2QJXD7).
* Storage Pool: 3x 14TB Seagate IronWolf Pro HDDs (ZFS RAIDZ1, 28TB usable).
* Network: Onboard 2.5 Gbps Wired NIC (nic0) + Built-in Wi-Fi (wlp5s0).
* GPU: Legacy Nvidia GPU (Required for POST and initial installation). The Mainboard has 4 SATA ports on board. Three of them have 14 TB Ironwolf pro drives to be formatted as a ZFS array with Z! so will give 28TB of usable storage with one disk of redundancy

===Proxmox Installation===

It is assumed that the Proxmox installer has been downloaded from their website and the iso has been copied on to a USB stick and made bootable with Rufus or some other similar. If the reader doesn't know how to make a USB installer from an ISO try typing "How do I make a USB stick into a proxmox installer" in to a browser. there will be loads of guides on how to use Rufus. When a bootable USB stick with Proxmox installer on it has been created insert in to one of the USB slots along with a keyboard, mouse and screen. Please note the keyboard mouse and screen will only be needed for the installation, once Proxmox is installed it is unlikely that these will ever be used again because virtually all administration is performed on a web GUI.

====BIOS settings for Hypervisors (including Proxmox)====

Generally most BIOS can be left at defaults and a PC as a PC will work well enough, maybe the boot priority may need to be changed from a HDD to a SSD but even that is unlikely. It is possible to optimise lots of things in BIOS and for some people that is an option but it is also easy to make mistakes that either stop the machine from working or making the machine unstable so for most people, most of the time, it is better to leave BIOS alone. A big exception is when a hypervisor is to be install because a few options that are off by default need to be set for Virtualisation to work properly. The main things to set are:-
* SVM Mode (AMD-V): '''Must be Enabled.''' This is what allows Proxmox to run VMs. Without it virtualisation will fail with most or possibly all hypervisors
* IOMMU: Set to Enabled. This is vital if you ever want to "pass through" a SATA controller or GPU directly to a VM. while not vital for the virtualisation itself most hypervisors have this enabled.
* Power Supply Idle Control: If you find the server randomly freezes when idle, set this to "Typical Current Idle". Ryzen chips sometimes drop voltage too low for some power supplies when idling, causing a crash. Again not vital but a "nice to have" if possible in the BIOS.
* Boot options: The SSD should be at the top. It is better to set the USB at the bottom so that if a USB is left in the machine and it is rebooted it doesn't try to boot from the USB.
Once the BIOS option are set save the settings and quit. The computer will shutdown and restart, while it is restarting keep pressing the delete key or the F12 key to bring up the boot options (it is usually delete key but it should also display the options briefly on the screen as it starts).

====GPU Considerations====

The Proxmox installation is a little bit more tricky than is standard for the majority of computers in that this has an old GPU that the installer does not recognise. A GPU is required so that the machine will pass POST but is not really need or used by the Proxmox guests so is generally of little benefit for the overall Proxmox day to day running. A lot of Hypervisor hosts have the cheapest and lowest power GPUs installed just enough to POST but no more than that. The reason that GPU is of low priorty for most hypervisors hosts is that they are generally run headless, that is without a monitor attached, all interations with the host is through a dedicated application like Citrix XEN, or more likely through a web browser like Proxmox. Web based GUIs are popular because it is a lot easier and lighter processor load to have a webserver attached than it is to design a whole application. Kiwi has an old Nvidia GPU that works in that it provides a display but that is about it. Unfortunately, it does give some problems for the installer as it is so old but therea re steps to overcome that as will be detailed below. We may add a bigger and better GPU at a later date but for the foreseeable future that is in the realms of an upgrade for later and dependant on inheriting a GPU from another box.

====Proxmox Installer problems (The Kiwi exceptions)====

As stated earlier the Proxmox installer does not work with the GPU. This is shown in that the machine boots and loads the first screen of the installer with welcome to.. but when the first option is tried it starts to load then freezes at the loading Nvidia drivers or some such thing(cant remember exactly what it says). so to fix that issue we need to restart the host and when we get to the welcome screen again we highlight "Install Proxmox VE (Graphical)" but '''do not press Enter''' instead we press "e" so a black screen with GNU GRUB appears. Edit the line
linux /boot/linux26 ro ramdisk_size=16777216 rw quiet splash=silent
so it reads
linux /boot/linux26 ro ramdisk_size=16777216 rw nomodeset
* By removing the quiet splash=silent we force the installer to show every single line of code as it loads. If it freezes again, we see the exact driver name where it stopped (e.g., sata_nv or i915).
* Adding nomodeset: This is the "magic bullet" for the nvidiafb hang. It tells the kernel not to touch the video drivers until the system is fully loaded. It is most likely where the installer hangs. As we should see every line of the execution of the installer if we have a different driver issue we should still see it.
To save the changes press ctrl+x or maybe F10. The GNU Grub screen will close and the graphical installer will continue until it gets to the "end user license agreement (EULA) screen. For anyone else reading this, If the installer freezes again before it gets to the EULA screen the error will most likely be in the last laine of text displayed. The most likely error will be a conflict between Debian kernel and Advanced Configuration and Power Interface (ACPI) in which case restart and press the "e" to get to the Grub config and edit the same line
linux /boot/linux26 ro ramdisk_size=16777216 rw nomodeset
so that it now has noapic added. note that this is just for the installer not the Proxmox application.
linux /boot/linux26 ro ramdisk_size=16777216 rw nomodeset noapic
After modifying that line press ctrl+x or F10 to save and proceed. if it stalls again you will need to look for the exact error in the last line or last few lines that the installer performed or any line that starts or ends with failed.

====Proxmox installer continued====

After the earlier problems we should have got to the ELUA screen so press "I agree" button to continue. The next screen will be about choosing hard drives. Kiwi has a single SSD and three Ironwolf Pro 14 TB HDDs. Obviously, we will not install the OS onto a HDD or even all three HDDs as it would be too slow and as the SSD is fast we will choose that as the Target Harddisk. with the SSD selected click on options button.
* select zfs (RAID0)
* select samsung SSD as hardisk 0
* select Do not use for harddisk 1
* select Do not use for harddisk 2
* select Do not use for harddisk 3
ZFS is the best choice as it has native compression, Bitrot detection but not really protection because there is only one drive so nowhere to restore any corrupt data from. ZFS also has good snapshot capability. Ext4 / XFS are "set it and forget it" options. They use almost zero RAM, but they offer no protection against data corruption and have very basic snapshotting capabilities (via LVM). Btrfs is similar to ZFS but generally considered less stable and has a lower feature set. The HDDs will not be used during the installation of Proxmox because it is easier to set them up from within the Proxmox web GUI or CLI.so the do not use is the best option for now '''note''' before we exit the Harddisk Options we need to check that the '''ashift''' is set to 12 so that the data blocks align with the physical page size of the Samsung 990 Pro's NAND, ensuring maximum speed, so select Advanced Options button next to Disk setup. Choose
* ashift is 12
* compress is on
* checksum is on
* copies is 1. Since this is a single-disk ZFS RAID0, copies=1 is the standard. If it is set it to 2, it would store every block twice on the same physical SSD. While that would allow ZFS to repair bitrot, it would effectively cut the 2TB SSD down to 1TB and halve the write speeds. With a 990 Pro, standard checksums and a good backup strategy are much more efficient.
* ARC max size 6422 Since there are only have two RAM slots and we are capped at 64GB, we need to be very intentional about how we carve up Kiwi RAM. having said that it is only a Maximum not a set size and zfs does not have to use all of it's maximum
* hdsize is set to maximum ( the + button will only allow it to be the size of the harddisk so click it until it stops going up)
Check the settings and when all looks correct click next for the regional settings
* Country United Kingdom
* Timezone Europe/London (or UTC if preferred)
* Keyboard Layout United Kingdom
Then next to set password and email address screen. Set a strong password that you can remember for the administration of the host. If the password is lost it will be almost impossible to recover it so do not forget it. Also it will be the hackers dream to get hold of the Proxmox host's password in that all of the rest of the security is mainly built on top of the administration of the host. If a host in a cluster is compromised it is quite likely that the whole cluster is compromised. The email address is so Proxmox can send promotional or updates but in general they don't flood their users with spam so it is no problem adding in a real email address. When done Click next to se the Management Network configuration screen.

The Management Network Configuration will determine where the WebGUI will be presented from. Kiwi has two NICs, one is the 2.5 GB p/s wired NIC and the other is the wireless NIC. by default it is likely to be the wired NIC that is going to be the one used for the management interface, mainly because at this stage WiFi has not been set up yet. Set up the options as follows
* Management Interface nic0 (the r8169 is the driver that Debian uses for wired nics) It is the one that is up and the Wifi nic is down so it is straight forward to establish which is which.
* hostname will be kiwi.seaoffate.net it is safe for us to use this domain name because we have registered it. If the reader has no domain name it could be kiwi.local but it would be unwise to use something that is already register on the public Internet, it may appear to work but there will be odd unforeseen problems like getting updates or push notifications or some other odd thing that don't work because the reply is being sent to a different IP address.
* IP address will be 192.168.1.112/24
* Gateway will be 192.168.1.1
* DNS will be 192.168.1.1
When this is done click next for the Summary. Make sure it is all correct and the auto reboot after successful installation then click install.

====Post Installation ====

When the host finishes the install it will restart. It may show the Proxmox Intallation again if the USB is still plugged in depending on the boot options, if so remove the USB and restart the computer. once the computer has finished starting it should show a simple login screen with the web address that is the main administration panel. from this point on the screen, mouse and keyboard can and should be removed as they will probably be never be used again. Now Kiwi will be managed from a web browser. The address will be whatever was set in the Management Network Configuration section with the port number 8006. in the case of Kiwi it is http://192.168.1.112:8006 the browser will give a security warning as no SSL cert has been setup for it yet so click advanced or ignore or whatever the browser needs to get to the web address. Then there will be a bank Proxmox screen with a popup in the middle with the title Proxmox VE Login the login details are
* Username root
* Password your_password ( whatever was set in the password and email section of the instalation)
* Realm is Linux PAM standard authentication
* Language English - English
'''note''' username and password are case sensitive

=====Samsung 990 Pro series SSDs Firmware=====
Now we have logged in we need to check that the Samsung SSD has got up to date firmware, '''Note This is for Samsung 990 Pro SSDs''' and not all SSDs it is not even all Samsung SSDs just this particular model in the early versions. Select Kiwi from the left pane then towards the top right of the main pane there is a row of buttons reboot, shutdown, shell, bulk actions, and help click on shell. A new window will appear with root@kiwi already logged in. Type the following into the window
smartctl -a /dev/nvme0n1
look through the information for the SSD, under === START OF INFORMATION SECTION === it should have a firmware Version line. Make sure the version is not "1B2QJXD7" it should be safe if it starts with 3 or more. If the Samsung 990 Pro SSD does have the unsafe version stop now and update the firmware immediately or it is likely that it will stop working after a short time. The version on this host is Firmware Version: 5B2QJXD7

=====Fix the No Subscription nag and do system update=====
By default, Proxmox tries to use a paid repository that you can't access. We need to disable that and add the free community one. This assumes that it is Proxmox version 9.x. Proxmox 9 uses .sources files. We must disable the default enterprise links and add the community repository. Run these commands in the Kiwi shell
# 1. Disable Enterprise PVE Repo
mv /etc/apt/sources.list.d/pve-enterprise.sources /etc/apt/sources.list.d/pve-enterprise.sources.bak
# 2. Disable Enterprise Ceph Repo
mv /etc/apt/sources.list.d/ceph.sources /etc/apt/sources.list.d/ceph.sources.bak
# 3. Create the No-Subscription Source
cat <<EOF > /etc/apt/sources.list.d/pve-no-subscription.sources
Types: deb
URIs: http://download.proxmox.com/debian/pve
Suites: trixie
Components: pve-no-subscription
Architectures: amd64
Signed-By: /usr/share/keyrings/proxmox-archive-keyring.gpg
EOF
The "No-Nag" UI Patch: This command neutralizes the subscription check in the web interface and restarts the proxy service to apply it
# 4. Remove 'No Valid Subscription' Login Popup
sed -Ezi.bak "s/(Ext.Msg.show\(\{\s+title: gettext\(\'No valid sub)/void\(\{ \/\/\1/g" /usr/share/javascript/proxmox-widget-toolkit/proxmoxlib.js && systemctl restart pveproxy.service
When the system reboots open a new console window for the host. So we can do an update. Always use dist-upgrade for Proxmox to ensure kernel and dependency changes are handled correctly.
# 5. Refresh and Upgrade
apt update && apt dist-upgrade -y
Summary of why we did this
* The .bak method: Instead of fighting sed patterns that might change, moving the files to .bak is a "bulletproof" way to ensure apt ignores them.
* Trixie Suites: Using Suites: trixie ensures you aren't pulling in old bookworm (Proxmox 8) packages that could destabilize your new Ryzen 5 build.
* The 63 Packages: Now that you've run the update, those 63 packages are waiting. Running the dist-upgrade command above will install the latest 2026 security patches and hardware drivers.

=====Ironwolf Pro Harddrive Setup=====

Since we have already performed the dist-upgrade, the kernel is fresh and ready to handle the heavy I/O of those 14TB drives. We will set this up via the CLI to ensure we get the exact optimizations needed for a high-density vault. First, we must be 100% certain which device names (/dev/sdX) belong to the IronWolfs.
lsblk -o NAME,SIZE,MODEL,SERIAL
Look for the three drives that show approximately 12.7T (the TiB equivalent of 14TB). Verify the Model says ST14000.... In this case they are
* sda 12.7T ST14000NE0008-2JK101 ZTM0D5FK
* sdb 12.7T ST14000NE0008-2H4101 ZL2EJCXX (this one has a partition sdb1 but we ignore it)
* sdc 12.7T ST14000NE0008-2JK101 ZTM0D5A0
The Clean Slate (Wipe the Labels) Run these commands to clear the old ZFS and EFI labels. This doesn't delete all of the old data (which takes hours), it just "un-formats" the start and end of the disks so ZFS sees them as new. It may not be necessary for all of the drives but certainly is for sdb as that has a partition on it
# Wipe the ZFS labels specifically
zpool labelclear -f /dev/sda
zpool labelclear -f /dev/sdb
zpool labelclear -f /dev/sdc
# Wipe the partition tables entirely (the "Nuclear" option)
wipefs -a /dev/sda
wipefs -a /dev/sdb
wipefs -a /dev/sdc

The other drive is the 990 Pro SSD. Now we can create the ZFS Z1 Pool We will name the pool kiwipool. We are using ashift=12 for 4K sector alignment and atime=off to save the mechanical heads from unnecessary movement.
zpool create -o ashift=12 kiwipool raidz1 /dev/sda /dev/sdb /dev/sdc
# Apply optimizations
zfs set compression=lz4 kiwipool
zfs set atime=off kiwipool
zfs set xattr=sa kiwipool
zfs set recordsize=1M kiwipool
once that is done we can verify the pool is built with
zpool status kiwipool
Next we need to make some datasets to keep the pool organised and not write anything to the root of kiwipool. Run thes commands
zfs create kiwipool/PFK
zfs create kiwipool/PFK/pdata
zfs create kiwipool/PFK/pdata/KiwiHDs
zfs create kiwipool/ISO
zfs create kiwipool/PFK/backups
zfs list
The zpool will show up in the webgui in Kiwi->storage and kiwi->zfs but not in the VM list on the left hand pane so they cannot be added to VMs yet. To make them available we run the command
pvesm add zfspool KiwiHDs --pool kiwipool/PFK/pdata/KiwiHDs --content rootdir,images
pvesm add dir KiwiISOs --path /kiwipool/ISO --content iso,vztmpl
pvesm add dir KiwiBackups --path /kiwipool/PFK/backups --content backup
Now in the webgui there should be the drives for VM HDs, ISOs and backups

=====Check and configure the WiFi=====

Testing Wi-Fi on a Proxmox (Debian) host is a bit different than on a laptop because there is no "taskbar" to click. We have to do this through the CLI. First, let's see if Debian even sees the Wi-Fi card and has the drivers loaded.
ip link
Look for: An interface starting with w (e.g., wlp2s0 or wlan0). If you don't see one the drivers might be missing or it's "Hard Blocked" in the BIOS. In this case The hardware check is a success. Your Wi-Fi card is identified as wlp5s0 (it did show up in the installer but it was ignored then ). The state is currently DOWN, which is expected since it hasn't been configured with your SSID or credentials yet. Because Proxmox is built for servers, it lacks a graphical Wi-Fi picker. We have to manually tell the background service (wpa_supplicant) how to talk to your router. at the same time install the wireless tools package.
apt update && apt install wpasupplicant wireless-tools -y
Instead of typing the Wi-Fi password in plain text, we’ll use a tool to generate a secure configuration block. Replace Your_SSID and Your_Password with your actual wireless AP details:
wpa_passphrase "Your_SSID" "Your_Password" > /etc/wpa_supplicant/wpa_supplicant.conf
Now we can test the connection let's see if Kiwi can actually authenticate.
wpa_supplicant -B -i wlp5s0 -c /etc/wpa_supplicant/wpa_supplicant.conf
Then wait a few seconds before checking the status with
iw wlp5s0 link
Assuming it shows a connection we can make it permanent. To ensure the Wi-Fi comes up automatically on boot and acts as a secondary management port, we need to add it to the network interfaces file. Warning: Be very careful with the syntax here. Use this command to append the configuration to /etc/network/interfaces. cat <<EOF >> /etc/network/interfaces
auto wlp5s0
iface wlp5s0 inet static
address 192.168.1.113/24
wpa-conf /etc/wpa_supplicant/wpa_supplicant.conf
EOF

=====🌐 Networking & The "Wi-Fi Failover" Battle=====

This section documents the attempt to create a reliable wireless "emergency backdoor." The objective was to have the Wi-Fi (192.168.1.113) act as a secondary management port that remains accessible even if the 2.5G cable is pulled. The Problem was cuased by (Asymmetric Routing). Linux prefers the route with the lowest metric. Since the 2.5G wire has a metric of 10 and Wi-Fi has 100, pulling the cable caused a "Routing Black Hole"—Kiwi would receive requests via Wi-Fi but try to reply via the dead Ethernet cable.

Several fixes were applied including
* Kernel Routing Tweaks: Added to /etc/sysctl.conf to force the OS to ignore dead routes immediately
nano /etc/sysctl.conf

net.ipv4.conf.all.ignore_routes_with_linkdown=1
net.ipv4.conf.default.ignore_routes_with_linkdown=1
net.ipv4.conf.all.arp_ignore=1
net.ipv4.conf.all.arp_announce=2
* We tried to create service persistence. We created a systemd override for wpa_supplicant@wlp5s0 to handle driver timing issues
[Service]
Restart=on-failure
RestartSec=5s
ExecStartPost=/usr/sbin/ifup wlp5s0 --force

The Kiwix Archive

2026-04-20T20:29:48Z

Wikisailor: /* 📖 Introduction */

==📖 Introduction==
Kiwix is an offline content reader that allows you to browse massive websites—like Wikipedia, StackExchange, or Project Gutenberg—without an internet connection.
* The Format: It uses highly compressed .ZIM files. A single file can contain the entirety of Wikipedia (with images) or the complete medical encyclopedia.
* The Goal: To provide a permanent, offline knowledge base that remains accessible even if the internet is down, serving everyone on your local network.
* Synergy: Works alongside '''[[OpenAlex]]''' (scholarly search) and '''[[The Web Archive (ArchiveBox) | ArchiveBox]]''' (personal web snapshots) to create a three-tier local research library.

Once this collection of Zims are downloaded we can also extract the text from the files to create a collection of .MD files which can then be used as a Retrieval-Augmented Generation database or RAG database for offline LLMs or the same data could be used as fine tuning data for o0ne or more LLMs. Although some of the .MDs will be general knowledge and only really useful for the RAG DB some will detailed question and answer tables of condensed information for example the Slack Overflow will be high density data sets

==💾 The Infrastructure ==
Blackberry has been slimmed down to be more efficient now that indexing is handled elsewhere.
* Host: Blackberry
* VM Config: Debian | 4 Cores | 6GB RAM.
* Storage: 4TB XFS disk mounted at /mnt/docker_data and an additional 5TB XFS disk for ArchiveBox /mnt/archive_data

==[[Linux Commands]]==

A set of Linux commands to help show the progress of indexing and file copying

==🐋 The Software Stack (Docker)==

=== Installing Docker & Compose===

Before installing Dockge, we must install the Docker engine and the Compose plugin officially on Debian.
# Update and install dependencies
sudo apt update && sudo apt install -y ca-certificates curl gnupg
# Add Docker’s official GPG key
sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/debian/gpg -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc
# Add the repository to Apt sources
echo \
"deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/debian \
$(. /etc/os-release && echo "$VERSION_CODENAME") stable" | \
sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
# Install Docker Engine and Compose Plugin
sudo apt update
sudo apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
# Optional: Allow your user to run docker without sudo
sudo usermod -aG docker $USER

===🛠️ Installing Dockge===
Dockge allows us to manage our "Stacks" (Docker Compose files) through a clean web interface.
# Preparation: Create directories
mkdir -p /opt/stacks /opt/dockge
cd /opt/dockge
# Download and Start Dockge
curl https://raw.githubusercontent.com/louislam/dockge/master/compose.yaml --output compose.yaml
docker compose up -d

===🛠️ Preparation: Storage Folders===
Organize The ZIM files on the 5TB disk so the container can find them easily.
mkdir -p /mnt/docker_data/stacks/kiwix-archive/zim/

===📄 Kiwix YAML (The Stack) ===
Deploy this in your Dockge instance on Blackberry (Port 5001) and name it kiwix

services:
kiwix:
image: ghcr.io/kiwix/kiwix-serve:latest
container_name: kiwix_wikipedia
volumes:
- /mnt/docker_data/stacks/kiwix-archive/zim:/data
ports:
- 8081:8080
command:
- --library
- library.xml
restart: unless-stopped
networks: {}

===🌐 Accessing and Using the Library===

{| class="wikitable"

|-
! Tool !! URL !! Purpose
|-
|Kiwix Web UI || http://blackberry:8080 || Browsing your downloaded offline libraries.
|-
|ZIM Library || https://kiwix.org/en/download || Where to download new content (Wikipedia, StackOverflow, etc.).
|-
| German Zim Library || https://ftp.fau.de/kiwix/zim/ || lists of zim files.
|-
| Kewix org || https://download.kiwix.org/zim/ || More Lists of Zim files
|}

===Indexing Files after download===

There are three helper scripts in the /mnt/docker_data/stacks/kiwix-archive/zim/ directory that will help add new zim files to the xml index
{| class="wikitable"

|-
! Filename !! Purpose
|-
|./audit_incomplete.sh || scans zim dir for incomplete files and move them to incomplete directory
|-
|./sweep_parts.sh || Checks any files in the incomplete directory for files that have corresponding completed downloaded Zim
|-
|./index_vault.sh || Adds new Zim to XML index file
|}

AI & Jellyfin

2026-04-20T18:53:06Z

Wikisailor: /* Jellyfin Installation */

==Introduction==

The objective for Quince is to make it the power house Virtual Machine for the AI so it needs to have the [[Linux Docker And GPU Passthrough | Nvidia 5060TI GPU passthrough ]] completed . At the same time it will also run a media server in the form of Jellyfin so that the GPU can do the transcoding. With the AI being serviced by this host we can use '''[[Data Archive | Blackberry]]''' for the Data Harvesting.

== Docker Applications installed on Quince ==

We are going to need to install several applications that will share the GPU. The first will be Dockge so that any new containers can be managed easily. We will also need to install Ollama so that we can run LLMs easily. Then to make use of the data archive we can use AnythingLLM.

==Installation Strategy==

Once the Blackwell GPU passthrough was verified on the Pear host, we transitioned to the Quince VM to set up the containerized environment. This allows us to run high-performance AI (Ollama) and media (Jellyfin) apps while keeping the base OS clean.

===Docker Engine Installation===

We use the official Docker repository to ensure access to v29+, which includes critical patches for Gen 5 PCIe and Blackwell architecture support.
sudo apt update
sudo apt install ca-certificates curl gnupg
Then setup the repository
sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
sudo chmod a+r /etc/apt/keyrings/docker.gpg
echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
Next Install Engine & Compose
sudo apt update
sudo apt install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
===NVIDIA Container Toolkit (The "Magic Bridge")===
This toolkit enables the libnvidia-container library, which maps the physical GPU device files (/dev/nvidia0, etc.) into the virtualized Docker namespace.
curl -fsSL https://nvidia.github.io/libnvidia-container/gpgkey | sudo gpg --dearmor -o /usr/share/keyrings/nvidia-container-toolkit-keyring.gpg
curl -s -L https://nvidia.github.io/libnvidia-container/stable/deb/nvidia-container-toolkit.list | sed 's#deb https://#deb [signed-by=/usr/share/keyrings/nvidia-container-toolkit-keyring.gpg] https://#g' | sudo tee /etc/apt/sources.list.d/nvidia-container-toolkit.list
sudo apt update
sudo apt install -y nvidia-container-toolkit
and last we configure the Nvidia Container tool Kit and restart Docker
sudo nvidia-ctk runtime configure --runtime=docker
sudo systemctl restart docker

==Docker Applications==

===Dockge Setup===
Now that docker is installed we can install Dockge. To get Dockge running on Quince, we followed a specific path that keeps it isolated but powerful enough to manage your other stacks (Jellyfin, AnythingLLM, etc.).
Since Dockge is a "Docker manager that runs inside Docker," the installation is a bit like a "Inception" move, we create a directory for it, and then use a simple script or a compose.yaml to launch it.
* Create the Directory Structure On Quince, we created a dedicated space for Dockge and all the future stacks you'll build. open a terminal and run the following
mkdir -p /mnt/docker_data/dockge /mnt/docker_data/stacks
cd /mnt/docker_data/dockge
* Download the Compose File We pulled the official configuration. Dockge needs access to the Docker Socket (/var/run/docker.sock) so it can "reach out" and control the other containers on Quince.
curl https://raw.githubusercontent.com/louislam/dockge/master/compose.yaml --output compose.yaml
* Launch Dockge We started it up in "detached" mode.
docker compose up -d
Now that Dockge is running we have a web interface on Quince:5001 and we can use it to add new services.

===Jellyfin Installation===

To give the media server plenty of storage we have mounted a 3TB data drive at /mnt/jellyfin/ to store all of the media files, we have another drive at /mnt/docker_data to hold all of the configuration data for the containers. We had some difficulty with a left over jellyfin container instalation so we called this container jellyfin-new to start with. The yaml file for "jellyfin-new" is as follows.

services:
jellyfin:
image: jellyfin/jellyfin
container_name: jellyfin
user: 1000:1000
# ADD THIS SECTION:
runtime: nvidia # Tells Docker to use the NVIDIA Container Toolkit
deploy:
resources:
reservations:
devices:
- driver: nvidia
count: 1
capabilities: [gpu, video] # Grants access to NVENC/NVDEC
ports:
- 8096:8096
volumes:
- /mnt/docker_data/jellyfin/config:/config
- /mnt/docker_data/jellyfin/cache:/cache
- /mnt/jellyfin/audiobooks:/data/audiobooks
- /mnt/jellyfin/oldfilms:/data/movies
- /mnt/jellyfin/oldseries:/data/tvshows
- /mnt/jellyfin/dji:/data/dji
restart: unless-stopped
networks: {}

The web interface for Jellyfin is on port 8096 so http://quince:8096 will bring it up. To setup the local devices either with a webrowser or the Jellyfin Media player the firewall will forward 8096 to the media server.
* To use the Nvidia Toolkit with jellyfin we set the device driver to nvidia in the yaml file.
* After clicking "Deploy" in Dockge, we can verified the container could "talk" to the 5060 Ti with the command
docker exec -it jellyfin nvidia-smi
We should have an output with the line something like
NVIDIA-SMI 580.126.09 Driver Version: 580.126.09 CUDA Version: 13.0
====Post-Install Playback Optimization====
Inside the Jellyfin Web UI (Dashboard > Playback), we have enabled Nvidia NVENC and checked the following critical Blackwell features:
* Hardware Decoding: H264, HEVC, AV1, VP9.
* AV1 Encoding: Allowed (The 5060 Ti is one of the few cards that can do this, significantly saving bandwidth).
* Tone Mapping: Enabled (Necessary for playing 4K HDR DJI drone footage on SDR screens).

===AI applications ===

We will need several inter-connected AI applications.

====Ollama installation====

We want to be able to run a variety of LLMs so will setup Ollama with a
* Container name ollama and a yaml file as follows
services:
ollama:
image: ollama/ollama:latest
container_name: ollama
volumes:
- /mnt/docker_data/ollama:/root/.ollama
networks:
- ai-network
deploy:
resources:
reservations:
devices:
- driver: nvidia
count: 1
capabilities:
- gpu
restart: unless-stopped
networks:
ai-network:
external: true

* Note that the device driver is set to nvidia
* To verify it's in the GPU
docker exec -it ollama nvidia-smi

====Loading a model via SSH ====
Since Ollama is running as a container, we don't run ollama run directly on the Quince host. We run it through Docker
* To download and start chatting with a model immediately:
docker exec -it ollama ollama run llama3.1:8b
* To just download (pull) a model to the disk without starting a chat:
docker exec -it ollama ollama pull mistral:7b
*What happens next
** Ollama will download the model manifest and layers.
** Because you mapped /mnt/docker_data/ollama, these models are saved to the SSD-backed 100GB config drive, ensuring they load into the 5060 Ti's VRAM almost instantly.
* To check what is currently on your disk, complete with the version and size run:
docker exec -it ollama ollama list

{| class="wikitable"
|+ Expected Models
|-
! Model !! Size !! Why run it?
|-
| Llama 3.2 (3B) || ~2.0 GB || Lightning fast. Great for simple summaries and quick tasks.
|-
| Mistral (7B) || ~4.1 GB || The "Gold Standard" for general purpose local AI. Very reliable.
|-
| Llama 3.1 (8B) || ~4.7 GB || Excellent reasoning; very "human" in its responses.
|-
|DeepSeek-Coder (6.7B) || ~4.0 GB || If you want help writing scripts or fixing Nginx configs.
|-
|Command R (35B) || ~20 GB || The Stretch Goal. At 4-bit quantization, this might fit or spill slightly into system RAM. It’s incredibly smart for document analysis.
|-
|Qwen2.5-Coder || ~4.7 GB || Good for coding in Go
|-
|GPT-OSS:20B || ~13 GB ||
|-
|gemma3:12b || ~8.1 GB ||
|}

When you run the command, Ollama tells you exactly what it's doing in the terminal.
* For Mistral: It pulls the 7B version by default so no need to be specific.
docker exec -it ollama ollama run mistral
* For Llama: it pulls the 8B version by default.
docker exec -it ollama ollama run llama3.1
To be 100% specific, you can use "tags" like this:
docker exec -it ollama ollama run mistral:7b
docker exec -it ollama ollama run llama3.1:8b

* How to verify it's in the GPU (The "Acid Test"). This is the most important part for the 5060 Ti. While chatting with a model in one SSH window, open a second SSH window and run:
docker exec -it ollama nvidia-smi
Look at the Memory-Usage and the Processes list at the bottom. It should show ollama using ~4.5 GB or ~5.2 GB of VRAM, it is successfully running on the GPU. If it stays at 4MiB / 16311MiB, it’s "hallucinating" on your CPU instead, and we’d need to check the drivers.

===AnythingLLM ===

The objective of AnythingLLM is to take data from personal data stores like a collection of books or other data store and use a LLM from Ollama to extract information as required, for example if the data source is a concerned with Go programming language, the user could have the LLM write a Go application while being safe in the knowledge that no outside influence will have tainted the code. So the main uses can be summed up as:
* '''Retrieval-Augmented Generation (RAG):''' This is the "killer feature." It allows the user to ask a model (like Mistral) questions about their own files. Instead of the AI guessing, it "reads" the ArchiveBox documents first and provides answers based only on their data.
* '''Workspace Isolation:''' It can use different "Workspaces" (e.g., one for Research, one for Home Server Logs, one for Family History). Each workspace has its own specific set of documents and its own "personality," so the AI doesn't get confused between work and hobbies.
* '''Multi-User "ChatGPT" Experience:''' It provides a polished, web-based interface that feels like ChatGPT but is hosted at http://quince.seaoffate.net(only from within the local network). This allows the use of the AI from any device on the local network (or via Raisin) without needing to use the SSH terminal.
* '''AI Agent Hub:''' Beyond just chatting, AnythingLLM can act as an Agent. It can browse the web, scrape new URLs given to it, even summarize entire folders of transcripts from the new Whisper-WebUI setup.

Why? Docker’s internal DNS resolves the name ollama to the correct internal IP automatically because they are on the same network.
* It should be mentioned that the network isolation provided by both Ollama and Anythingllm residing on the ai-network means AnythingLLM can reach the LLM at http://ollama:11434. This internal traffic never touches the main LAN, keeping the AI conversations extremely fast and private from other devices on the local network.

The AnythingLLM can be installed with the name "anythingllm" and the yaml file below
services:
anythingllm:
image: mintplexlabs/anythingllm:latest
container_name: anythingllm
ports:
- 3001:3001
cap_add:
- SYS_ADMIN
environment:
- STORAGE_DIR=/app/server/storage
volumes:
- /mnt/docker_data/anythingllm:/app/server/storage
- /mnt/docker_data/anythingllm/.env:/app/server/.env
# This links the Blackberry NFS mount into AnythingLLM
- /mnt/archive_data/archivebox:/app/server/storage/documents/archivebox:ro
networks:
- ai-network
restart: unless-stopped
networks:
ai-network:
external: true

====🌐The "ai-network" Handshake====
Since we defined ai-network as an external network that both Ollama and AnythingLLM share, they can talk to each other using their Container Names instead of IP addresses. Inside the AnythingLLM Settings UI:
* '''LLM Provider:''' Select Ollama.
* '''Ollama URL:''' Use http://ollama:11434 (Not localhost and not the IP).
* Why? Docker’s internal DNS resolves the name ollama to the correct internal IP automatically because they are on the same network.

====📂The ArchiveBox "Read-Only" Link====
The volume mapping for ArchiveBox is very clever
/mnt/archive_data/archivebox:/app/server/storage/documents/archivebox:ro
'''We should note:'''
* The :ro flag: This is critical. It ensures AnythingLLM can read the archives to "learn" from them, but it can never accidentally delete or modify the ArchiveBox data.
* Visibility: In the AnythingLLM UI, when we go to "Upload Documents," we will see a folder named archivebox. We can then move those files into your Workspace to start chatting with our archived websites.

====🛠️Environment & Permissions====
* '''The .env file:''' We are mounting /mnt/docker_data/anythingllm/.env. Before we run docker compose up, we make sure that file actually exists (even if it's empty) or Docker might create it as a folder by mistake.
** Quick fix: touch /mnt/docker_data/anythingllm/.env
* SYS_ADMIN Capability: This is required by AnythingLLM because it uses a technology called Puppeteer to scrape websites. Without this "cap_add," the document scraper will likely fail.

====📊 Quince GPU Status (Ollama + AnythingLLM)====
Ollama Memory: 4900MiB / 16311MiB
The "Quiet" Documentation: Now that AnythingLLM is joining the party on Quince:
* VRAM: AnythingLLM itself uses almost zero VRAM. It just sends instructions to Ollama.
* Concurrency: You can have Jellyfin transcoding a movie, Ollama running Mistral, and AnythingLLM scraping a document all at once on that 5060 Ti.

AI & Jellyfin

2026-04-20T18:51:19Z

Wikisailor: /* Docker Applications installed on Quince */

==Introduction==

The objective for Quince is to make it the power house Virtual Machine for the AI so it needs to have the [[Linux Docker And GPU Passthrough | Nvidia 5060TI GPU passthrough ]] completed . At the same time it will also run a media server in the form of Jellyfin so that the GPU can do the transcoding. With the AI being serviced by this host we can use '''[[Data Archive | Blackberry]]''' for the Data Harvesting.

== Docker Applications installed on Quince ==

We are going to need to install several applications that will share the GPU. The first will be Dockge so that any new containers can be managed easily. We will also need to install Ollama so that we can run LLMs easily. Then to make use of the data archive we can use AnythingLLM.

==Installation Strategy==

Once the Blackwell GPU passthrough was verified on the Pear host, we transitioned to the Quince VM to set up the containerized environment. This allows us to run high-performance AI (Ollama) and media (Jellyfin) apps while keeping the base OS clean.

===Docker Engine Installation===

We use the official Docker repository to ensure access to v29+, which includes critical patches for Gen 5 PCIe and Blackwell architecture support.
sudo apt update
sudo apt install ca-certificates curl gnupg
Then setup the repository
sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
sudo chmod a+r /etc/apt/keyrings/docker.gpg
echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
Next Install Engine & Compose
sudo apt update
sudo apt install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
===NVIDIA Container Toolkit (The "Magic Bridge")===
This toolkit enables the libnvidia-container library, which maps the physical GPU device files (/dev/nvidia0, etc.) into the virtualized Docker namespace.
curl -fsSL https://nvidia.github.io/libnvidia-container/gpgkey | sudo gpg --dearmor -o /usr/share/keyrings/nvidia-container-toolkit-keyring.gpg
curl -s -L https://nvidia.github.io/libnvidia-container/stable/deb/nvidia-container-toolkit.list | sed 's#deb https://#deb [signed-by=/usr/share/keyrings/nvidia-container-toolkit-keyring.gpg] https://#g' | sudo tee /etc/apt/sources.list.d/nvidia-container-toolkit.list
sudo apt update
sudo apt install -y nvidia-container-toolkit
and last we configure the Nvidia Container tool Kit and restart Docker
sudo nvidia-ctk runtime configure --runtime=docker
sudo systemctl restart docker

==Docker Applications==

===Dockge Setup===
Now that docker is installed we can install Dockge. To get Dockge running on Quince, we followed a specific path that keeps it isolated but powerful enough to manage your other stacks (Jellyfin, AnythingLLM, etc.).
Since Dockge is a "Docker manager that runs inside Docker," the installation is a bit like a "Inception" move, we create a directory for it, and then use a simple script or a compose.yaml to launch it.
* Create the Directory Structure On Quince, we created a dedicated space for Dockge and all the future stacks you'll build. open a terminal and run the following
mkdir -p /mnt/docker_data/dockge /mnt/docker_data/stacks
cd /mnt/docker_data/dockge
* Download the Compose File We pulled the official configuration. Dockge needs access to the Docker Socket (/var/run/docker.sock) so it can "reach out" and control the other containers on Quince.
curl https://raw.githubusercontent.com/louislam/dockge/master/compose.yaml --output compose.yaml
* Launch Dockge We started it up in "detached" mode.
docker compose up -d
Now that Dockge is running we have a web interface on Quince:5001 and we can use it to add new services.

===Jellyfin Installation===

To give the media server plenty of storage we have mounted a 3TB data drive at /mnt/jellyfin/ to store all of the media files, we have another drive at /mnt/docker_data to hold all of the configuration data for the containers. We had some difficulty with a left over jellyfin container instalation so we called this container jellyfin-new. The yaml file for "jellyfin-new" is as follows.

services:
jellyfin:
image: jellyfin/jellyfin
container_name: jellyfin
user: 1000:1000
# ADD THIS SECTION:
runtime: nvidia # Tells Docker to use the NVIDIA Container Toolkit
deploy:
resources:
reservations:
devices:
- driver: nvidia
count: 1
capabilities: [gpu, video] # Grants access to NVENC/NVDEC
ports:
- 8096:8096
volumes:
- /mnt/docker_data/jellyfin/config:/config
- /mnt/docker_data/jellyfin/cache:/cache
- /mnt/jellyfin/audiobooks:/data/audiobooks
- /mnt/jellyfin/oldfilms:/data/movies
- /mnt/jellyfin/oldseries:/data/tvshows
- /mnt/jellyfin/dji:/data/dji
restart: unless-stopped
networks: {}

The web interface for Jellyfin is on port 8096 so http://quince:8096 will bring it up. To setup the local devices either with a webrowser or the Jellyfin Media player the firewall will forward 8096 to the media server.
* To use the Nvidia Toolkit with jellyfin we set the device driver to nvidia in the yaml file.
* After clicking "Deploy" in Dockge, we can verified the container could "talk" to the 5060 Ti with the command
docker exec -it jellyfin nvidia-smi
We should have an output with the line something like
NVIDIA-SMI 580.126.09 Driver Version: 580.126.09 CUDA Version: 13.0
====Post-Install Playback Optimization====
Inside the Jellyfin Web UI (Dashboard > Playback), we have enabled Nvidia NVENC and checked the following critical Blackwell features:
* Hardware Decoding: H264, HEVC, AV1, VP9.
* AV1 Encoding: Allowed (The 5060 Ti is one of the few cards that can do this, significantly saving bandwidth).
* Tone Mapping: Enabled (Necessary for playing 4K HDR DJI drone footage on SDR screens).

===AI applications ===

We will need several inter-connected AI applications.

====Ollama installation====

We want to be able to run a variety of LLMs so will setup Ollama with a
* Container name ollama and a yaml file as follows
services:
ollama:
image: ollama/ollama:latest
container_name: ollama
volumes:
- /mnt/docker_data/ollama:/root/.ollama
networks:
- ai-network
deploy:
resources:
reservations:
devices:
- driver: nvidia
count: 1
capabilities:
- gpu
restart: unless-stopped
networks:
ai-network:
external: true

* Note that the device driver is set to nvidia
* To verify it's in the GPU
docker exec -it ollama nvidia-smi

====Loading a model via SSH ====
Since Ollama is running as a container, we don't run ollama run directly on the Quince host. We run it through Docker
* To download and start chatting with a model immediately:
docker exec -it ollama ollama run llama3.1:8b
* To just download (pull) a model to the disk without starting a chat:
docker exec -it ollama ollama pull mistral:7b
*What happens next
** Ollama will download the model manifest and layers.
** Because you mapped /mnt/docker_data/ollama, these models are saved to the SSD-backed 100GB config drive, ensuring they load into the 5060 Ti's VRAM almost instantly.
* To check what is currently on your disk, complete with the version and size run:
docker exec -it ollama ollama list

{| class="wikitable"
|+ Expected Models
|-
! Model !! Size !! Why run it?
|-
| Llama 3.2 (3B) || ~2.0 GB || Lightning fast. Great for simple summaries and quick tasks.
|-
| Mistral (7B) || ~4.1 GB || The "Gold Standard" for general purpose local AI. Very reliable.
|-
| Llama 3.1 (8B) || ~4.7 GB || Excellent reasoning; very "human" in its responses.
|-
|DeepSeek-Coder (6.7B) || ~4.0 GB || If you want help writing scripts or fixing Nginx configs.
|-
|Command R (35B) || ~20 GB || The Stretch Goal. At 4-bit quantization, this might fit or spill slightly into system RAM. It’s incredibly smart for document analysis.
|-
|Qwen2.5-Coder || ~4.7 GB || Good for coding in Go
|-
|GPT-OSS:20B || ~13 GB ||
|-
|gemma3:12b || ~8.1 GB ||
|}

When you run the command, Ollama tells you exactly what it's doing in the terminal.
* For Mistral: It pulls the 7B version by default so no need to be specific.
docker exec -it ollama ollama run mistral
* For Llama: it pulls the 8B version by default.
docker exec -it ollama ollama run llama3.1
To be 100% specific, you can use "tags" like this:
docker exec -it ollama ollama run mistral:7b
docker exec -it ollama ollama run llama3.1:8b

* How to verify it's in the GPU (The "Acid Test"). This is the most important part for the 5060 Ti. While chatting with a model in one SSH window, open a second SSH window and run:
docker exec -it ollama nvidia-smi
Look at the Memory-Usage and the Processes list at the bottom. It should show ollama using ~4.5 GB or ~5.2 GB of VRAM, it is successfully running on the GPU. If it stays at 4MiB / 16311MiB, it’s "hallucinating" on your CPU instead, and we’d need to check the drivers.

===AnythingLLM ===

The objective of AnythingLLM is to take data from personal data stores like a collection of books or other data store and use a LLM from Ollama to extract information as required, for example if the data source is a concerned with Go programming language, the user could have the LLM write a Go application while being safe in the knowledge that no outside influence will have tainted the code. So the main uses can be summed up as:
* '''Retrieval-Augmented Generation (RAG):''' This is the "killer feature." It allows the user to ask a model (like Mistral) questions about their own files. Instead of the AI guessing, it "reads" the ArchiveBox documents first and provides answers based only on their data.
* '''Workspace Isolation:''' It can use different "Workspaces" (e.g., one for Research, one for Home Server Logs, one for Family History). Each workspace has its own specific set of documents and its own "personality," so the AI doesn't get confused between work and hobbies.
* '''Multi-User "ChatGPT" Experience:''' It provides a polished, web-based interface that feels like ChatGPT but is hosted at http://quince.seaoffate.net(only from within the local network). This allows the use of the AI from any device on the local network (or via Raisin) without needing to use the SSH terminal.
* '''AI Agent Hub:''' Beyond just chatting, AnythingLLM can act as an Agent. It can browse the web, scrape new URLs given to it, even summarize entire folders of transcripts from the new Whisper-WebUI setup.

Why? Docker’s internal DNS resolves the name ollama to the correct internal IP automatically because they are on the same network.
* It should be mentioned that the network isolation provided by both Ollama and Anythingllm residing on the ai-network means AnythingLLM can reach the LLM at http://ollama:11434. This internal traffic never touches the main LAN, keeping the AI conversations extremely fast and private from other devices on the local network.

The AnythingLLM can be installed with the name "anythingllm" and the yaml file below
services:
anythingllm:
image: mintplexlabs/anythingllm:latest
container_name: anythingllm
ports:
- 3001:3001
cap_add:
- SYS_ADMIN
environment:
- STORAGE_DIR=/app/server/storage
volumes:
- /mnt/docker_data/anythingllm:/app/server/storage
- /mnt/docker_data/anythingllm/.env:/app/server/.env
# This links the Blackberry NFS mount into AnythingLLM
- /mnt/archive_data/archivebox:/app/server/storage/documents/archivebox:ro
networks:
- ai-network
restart: unless-stopped
networks:
ai-network:
external: true

====🌐The "ai-network" Handshake====
Since we defined ai-network as an external network that both Ollama and AnythingLLM share, they can talk to each other using their Container Names instead of IP addresses. Inside the AnythingLLM Settings UI:
* '''LLM Provider:''' Select Ollama.
* '''Ollama URL:''' Use http://ollama:11434 (Not localhost and not the IP).
* Why? Docker’s internal DNS resolves the name ollama to the correct internal IP automatically because they are on the same network.

====📂The ArchiveBox "Read-Only" Link====
The volume mapping for ArchiveBox is very clever
/mnt/archive_data/archivebox:/app/server/storage/documents/archivebox:ro
'''We should note:'''
* The :ro flag: This is critical. It ensures AnythingLLM can read the archives to "learn" from them, but it can never accidentally delete or modify the ArchiveBox data.
* Visibility: In the AnythingLLM UI, when we go to "Upload Documents," we will see a folder named archivebox. We can then move those files into your Workspace to start chatting with our archived websites.

====🛠️Environment & Permissions====
* '''The .env file:''' We are mounting /mnt/docker_data/anythingllm/.env. Before we run docker compose up, we make sure that file actually exists (even if it's empty) or Docker might create it as a folder by mistake.
** Quick fix: touch /mnt/docker_data/anythingllm/.env
* SYS_ADMIN Capability: This is required by AnythingLLM because it uses a technology called Puppeteer to scrape websites. Without this "cap_add," the document scraper will likely fail.

====📊 Quince GPU Status (Ollama + AnythingLLM)====
Ollama Memory: 4900MiB / 16311MiB
The "Quiet" Documentation: Now that AnythingLLM is joining the party on Quince:
* VRAM: AnythingLLM itself uses almost zero VRAM. It just sends instructions to Ollama.
* Concurrency: You can have Jellyfin transcoding a movie, Ollama running Mistral, and AnythingLLM scraping a document all at once on that 5060 Ti.

Homelab Dashboard

2026-04-20T18:50:03Z

Wikisailor: /* Introduction */

==Introduction==

We have decided to setup a '''[[Home Lab]]''' dashboard to monitor and administer the entire estate of '''[[Virtual Machines]]''', '''[[Proxmox Server | Proxmox]]''' hosts and all of the services that we have created. initially we will use the dashy dashboard but may well change for something else if dashy proves to be to difficult or in some way unsuitable.

==Dashy Setup==

in the interests of security for this sensitive project we are extending your "Full-Chain TLS" SME standard to Blackberry. This ensures that even if a client bypasses the proxy (Raisin) and hits Blackberry directly on the network, the traffic is still encrypted and presents the valid *.seaoffate.net certificate. It will also mean that within the Pfsense side of the LAN any client will still meet the same secure SSL certificate system provided by Letsencrypt. 🛡️We will mount our existing SSL certificates (synced from Raisin) directly into the Dashy container and configure Dashy to serve HTTPS natively. Details of how the Certs are downloaded and installed can be found '''[[Letsencrypt SSL Certs |here]]'''.

===Installation on Blackberry===

🛠️ The "Dockge-Way" Setup, on our Dockge UI on Blackberry, create a new stack called dashy, and use this single, hardened configuration
services:
dashy:
image: lissy93/dashy:latest
container_name: dashy
restart: unless-stopped
ports:
- 443:443
volumes:
# Use the path that we proved works:
- /mnt/archive_data/docker_data/stacks/dashy/conf.yml:/app/public/conf.yml
# SSL Certificates (Synced from Raisin)
- /etc/nginx/ssl/seaoffate.net/fullchain.pem:/etc/ssl/certs/fullchain.pem:ro
- /etc/nginx/ssl/seaoffate.net/privkey.pem:/etc/ssl/private/privkey.pem:ro
environment:
- NODE_ENV=production
- DOCKGE_ENABLE_CONSOLE=true
- SSL_PUB_KEY_PATH=/etc/ssl/certs/fullchain.pem
- SSL_PRIV_KEY_PATH=/etc/ssl/private/privkey.pem
- NODE_OPTIONS=--max-old-space-size=2048
networks: {}

===Post-Installation Steps ===

====Certificate Synchronization Hook====

Before the container will start correctly in SSL mode, we must have a basic conf.yml in the same directory as our compose.yaml. This file defines our users and our "Fruit Cluster" links. It is better to be sure that the docker app has the correct permissions for the yml, especially if it is in a non standard location.
touch sudo nano /mnt/archive_data/docker_data/stacks/dashy/conf.yml
sudo chown 1000:1000 /mnt/archive_data/docker_data/stacks/dashy/conf.yml
sudo chmod 644 /mnt/archive_data/docker_data/stacks/dashy/conf.yml
'''''Note''' we are using a non standard directory for our stacks, the more common location for the conf.yml is /opt/dockge/stacks/dashy/conf.yml''

To ensure Dashy stays updated when Raisin renews the Wildcard certs, make sure the deploy-wildcard.sh script on Raisin includes the Blackberry sync. It should have the Blackberry host in the servers list and the dashy restart in the if statements something like
# Restart Dashy (Blackberry)
if [ \$(docker ps -q -f name=dashy) ]; then
echo ' Restarting Dashy...'
docker restart dashy
fi

====Authentication Hardening====

To fulfill the "Secure Application" requirement, we enable Dashy’s internal authentication. Even with a valid SSL cert, no data is visible without a login. Dashy requires a SHA-256 hash for the admin password. Run this on any terminal:
echo -n "YourSecretPassword" | sha256sum
'''''Note''' the quotes are only needed if there is spaces or similar in the password and the quotation marks are not part of the password''
Take the resulting string and place it in the auth section of your conf.yml on Blackberry
nano /mnt/archive_data/docker_data/stacks/dashy/conf.yml
A sample conf is as follows ( including the password YourSecretPassword it is assumed that the user will change the hash to some other password):
<nowiki>appConfig:
title: SeaOfFate Command
statusCheck: true
auth:
enable: true
enableGuestAccess: false
users:
- user: nigel
hash: '790e294c25e704e042c899bb4dbb696b9daa2ed330d270082599f8591dc62b96'
type: admin
sections:
- name: Infrastructure
items:
- title: Vaultwarden
url: https://vault.seaoffate.net/alive
icon: hl-bitwarden</nowiki>

'''💡 Why /alive'''

if you just ping the main URL, Dashy might get a 401 Unauthorized or a redirect, which can sometimes show up as a "Yellow" or "Red" dot even if the service is fine. The /alive path is specifically designed for health checks like this and always returns a simple 200 OK

====Verification====

Once started, you can verify the "Full-Chain TLS" by visiting:
* Internal(inside Pfsence): https://192.168.100.85 (Should show the valid seaoffate.net certificate from letsencrypt ).
* Internal(inside Pfsence): https://blackberry (Assuming the internal nameserver ctns1 has the DNS entry for blackberry set should show the valid seaoffate.net certificate from letsencrypt).
* Internal(inside Pfsence): https://dashy.seaoffate.net (Assuming the internal nameserver ctns1 has the DNS entry for dashy set should show the valid seaoffate.net certificate from letsencrypt).
* Internal:(outside Pfsence) https://dashy.seaoffate.net (Assuming the DNS rewrite foe seaoffate.net on adguard set and Raisin reverse proxy rule is set, should show the valid seaoffate.net certificate from letsencrypt).
* External(though mobile phone Internet): https://dashy.seaoffate.net (Assuming the DNS for dashy is set on Cloudflare's control panel and dashy is proxied through Raisin it should show the Cloudflare SSL certificate).
When we have proved that the the dashboard works and that the login screen is displayed first we can move on to adding items to the dashboard.

==Configuring the Dashboard==

Homelab Dashboard

2026-04-20T18:48:49Z

Wikisailor: /* Introduction */

==Introduction==

We have decided to setup a '''[[Home Lab]]''' dashboard to monitor and administer the entire estate of '''[[Virtual Machines]]''', '''[[Proxmox Server| Proxmox]]''' hosts and all of the services that we have created. initially we will use the dashy dashboard but may well change for something else if dashy proves to be to difficult or in some way unsuitable.

==Dashy Setup==

in the interests of security for this sensitive project we are extending your "Full-Chain TLS" SME standard to Blackberry. This ensures that even if a client bypasses the proxy (Raisin) and hits Blackberry directly on the network, the traffic is still encrypted and presents the valid *.seaoffate.net certificate. It will also mean that within the Pfsense side of the LAN any client will still meet the same secure SSL certificate system provided by Letsencrypt. 🛡️We will mount our existing SSL certificates (synced from Raisin) directly into the Dashy container and configure Dashy to serve HTTPS natively. Details of how the Certs are downloaded and installed can be found '''[[Letsencrypt SSL Certs |here]]'''.

===Installation on Blackberry===

🛠️ The "Dockge-Way" Setup, on our Dockge UI on Blackberry, create a new stack called dashy, and use this single, hardened configuration
services:
dashy:
image: lissy93/dashy:latest
container_name: dashy
restart: unless-stopped
ports:
- 443:443
volumes:
# Use the path that we proved works:
- /mnt/archive_data/docker_data/stacks/dashy/conf.yml:/app/public/conf.yml
# SSL Certificates (Synced from Raisin)
- /etc/nginx/ssl/seaoffate.net/fullchain.pem:/etc/ssl/certs/fullchain.pem:ro
- /etc/nginx/ssl/seaoffate.net/privkey.pem:/etc/ssl/private/privkey.pem:ro
environment:
- NODE_ENV=production
- DOCKGE_ENABLE_CONSOLE=true
- SSL_PUB_KEY_PATH=/etc/ssl/certs/fullchain.pem
- SSL_PRIV_KEY_PATH=/etc/ssl/private/privkey.pem
- NODE_OPTIONS=--max-old-space-size=2048
networks: {}

===Post-Installation Steps ===

====Certificate Synchronization Hook====

Before the container will start correctly in SSL mode, we must have a basic conf.yml in the same directory as our compose.yaml. This file defines our users and our "Fruit Cluster" links. It is better to be sure that the docker app has the correct permissions for the yml, especially if it is in a non standard location.
touch sudo nano /mnt/archive_data/docker_data/stacks/dashy/conf.yml
sudo chown 1000:1000 /mnt/archive_data/docker_data/stacks/dashy/conf.yml
sudo chmod 644 /mnt/archive_data/docker_data/stacks/dashy/conf.yml
'''''Note''' we are using a non standard directory for our stacks, the more common location for the conf.yml is /opt/dockge/stacks/dashy/conf.yml''

To ensure Dashy stays updated when Raisin renews the Wildcard certs, make sure the deploy-wildcard.sh script on Raisin includes the Blackberry sync. It should have the Blackberry host in the servers list and the dashy restart in the if statements something like
# Restart Dashy (Blackberry)
if [ \$(docker ps -q -f name=dashy) ]; then
echo ' Restarting Dashy...'
docker restart dashy
fi

====Authentication Hardening====

To fulfill the "Secure Application" requirement, we enable Dashy’s internal authentication. Even with a valid SSL cert, no data is visible without a login. Dashy requires a SHA-256 hash for the admin password. Run this on any terminal:
echo -n "YourSecretPassword" | sha256sum
'''''Note''' the quotes are only needed if there is spaces or similar in the password and the quotation marks are not part of the password''
Take the resulting string and place it in the auth section of your conf.yml on Blackberry
nano /mnt/archive_data/docker_data/stacks/dashy/conf.yml
A sample conf is as follows ( including the password YourSecretPassword it is assumed that the user will change the hash to some other password):
<nowiki>appConfig:
title: SeaOfFate Command
statusCheck: true
auth:
enable: true
enableGuestAccess: false
users:
- user: nigel
hash: '790e294c25e704e042c899bb4dbb696b9daa2ed330d270082599f8591dc62b96'
type: admin
sections:
- name: Infrastructure
items:
- title: Vaultwarden
url: https://vault.seaoffate.net/alive
icon: hl-bitwarden</nowiki>

'''💡 Why /alive'''

if you just ping the main URL, Dashy might get a 401 Unauthorized or a redirect, which can sometimes show up as a "Yellow" or "Red" dot even if the service is fine. The /alive path is specifically designed for health checks like this and always returns a simple 200 OK

====Verification====

Once started, you can verify the "Full-Chain TLS" by visiting:
* Internal(inside Pfsence): https://192.168.100.85 (Should show the valid seaoffate.net certificate from letsencrypt ).
* Internal(inside Pfsence): https://blackberry (Assuming the internal nameserver ctns1 has the DNS entry for blackberry set should show the valid seaoffate.net certificate from letsencrypt).
* Internal(inside Pfsence): https://dashy.seaoffate.net (Assuming the internal nameserver ctns1 has the DNS entry for dashy set should show the valid seaoffate.net certificate from letsencrypt).
* Internal:(outside Pfsence) https://dashy.seaoffate.net (Assuming the DNS rewrite foe seaoffate.net on adguard set and Raisin reverse proxy rule is set, should show the valid seaoffate.net certificate from letsencrypt).
* External(though mobile phone Internet): https://dashy.seaoffate.net (Assuming the DNS for dashy is set on Cloudflare's control panel and dashy is proxied through Raisin it should show the Cloudflare SSL certificate).
When we have proved that the the dashboard works and that the login screen is displayed first we can move on to adding items to the dashboard.

==Configuring the Dashboard==

Homelab Dashboard

2026-04-20T18:47:32Z

Wikisailor: /* Introduction */

Homelab Dashboard

2026-04-20T18:47:22Z

Wikisailor: /* Introduction */

==Introduction==

We have decided to setup a '''[[Home Lab]]''' dashboard to monitor and administer the entire estate of '''[[Virtual machines]]''', '''[[Proxmox Server | Proxmox]]''' hosts and all of the services that we have created. initially we will use the dashy dashboard but may well change for something else if dashy proves to be to difficult or in some way unsuitable.

==Dashy Setup==

in the interests of security for this sensitive project we are extending your "Full-Chain TLS" SME standard to Blackberry. This ensures that even if a client bypasses the proxy (Raisin) and hits Blackberry directly on the network, the traffic is still encrypted and presents the valid *.seaoffate.net certificate. It will also mean that within the Pfsense side of the LAN any client will still meet the same secure SSL certificate system provided by Letsencrypt. 🛡️We will mount our existing SSL certificates (synced from Raisin) directly into the Dashy container and configure Dashy to serve HTTPS natively. Details of how the Certs are downloaded and installed can be found '''[[Letsencrypt SSL Certs |here]]'''.

===Installation on Blackberry===

🛠️ The "Dockge-Way" Setup, on our Dockge UI on Blackberry, create a new stack called dashy, and use this single, hardened configuration
services:
dashy:
image: lissy93/dashy:latest
container_name: dashy
restart: unless-stopped
ports:
- 443:443
volumes:
# Use the path that we proved works:
- /mnt/archive_data/docker_data/stacks/dashy/conf.yml:/app/public/conf.yml
# SSL Certificates (Synced from Raisin)
- /etc/nginx/ssl/seaoffate.net/fullchain.pem:/etc/ssl/certs/fullchain.pem:ro
- /etc/nginx/ssl/seaoffate.net/privkey.pem:/etc/ssl/private/privkey.pem:ro
environment:
- NODE_ENV=production
- DOCKGE_ENABLE_CONSOLE=true
- SSL_PUB_KEY_PATH=/etc/ssl/certs/fullchain.pem
- SSL_PRIV_KEY_PATH=/etc/ssl/private/privkey.pem
- NODE_OPTIONS=--max-old-space-size=2048
networks: {}

===Post-Installation Steps ===

====Certificate Synchronization Hook====

Before the container will start correctly in SSL mode, we must have a basic conf.yml in the same directory as our compose.yaml. This file defines our users and our "Fruit Cluster" links. It is better to be sure that the docker app has the correct permissions for the yml, especially if it is in a non standard location.
touch sudo nano /mnt/archive_data/docker_data/stacks/dashy/conf.yml
sudo chown 1000:1000 /mnt/archive_data/docker_data/stacks/dashy/conf.yml
sudo chmod 644 /mnt/archive_data/docker_data/stacks/dashy/conf.yml
'''''Note''' we are using a non standard directory for our stacks, the more common location for the conf.yml is /opt/dockge/stacks/dashy/conf.yml''

To ensure Dashy stays updated when Raisin renews the Wildcard certs, make sure the deploy-wildcard.sh script on Raisin includes the Blackberry sync. It should have the Blackberry host in the servers list and the dashy restart in the if statements something like
# Restart Dashy (Blackberry)
if [ \$(docker ps -q -f name=dashy) ]; then
echo ' Restarting Dashy...'
docker restart dashy
fi

====Authentication Hardening====

To fulfill the "Secure Application" requirement, we enable Dashy’s internal authentication. Even with a valid SSL cert, no data is visible without a login. Dashy requires a SHA-256 hash for the admin password. Run this on any terminal:
echo -n "YourSecretPassword" | sha256sum
'''''Note''' the quotes are only needed if there is spaces or similar in the password and the quotation marks are not part of the password''
Take the resulting string and place it in the auth section of your conf.yml on Blackberry
nano /mnt/archive_data/docker_data/stacks/dashy/conf.yml
A sample conf is as follows ( including the password YourSecretPassword it is assumed that the user will change the hash to some other password):
<nowiki>appConfig:
title: SeaOfFate Command
statusCheck: true
auth:
enable: true
enableGuestAccess: false
users:
- user: nigel
hash: '790e294c25e704e042c899bb4dbb696b9daa2ed330d270082599f8591dc62b96'
type: admin
sections:
- name: Infrastructure
items:
- title: Vaultwarden
url: https://vault.seaoffate.net/alive
icon: hl-bitwarden</nowiki>

'''💡 Why /alive'''

if you just ping the main URL, Dashy might get a 401 Unauthorized or a redirect, which can sometimes show up as a "Yellow" or "Red" dot even if the service is fine. The /alive path is specifically designed for health checks like this and always returns a simple 200 OK

====Verification====

Once started, you can verify the "Full-Chain TLS" by visiting:
* Internal(inside Pfsence): https://192.168.100.85 (Should show the valid seaoffate.net certificate from letsencrypt ).
* Internal(inside Pfsence): https://blackberry (Assuming the internal nameserver ctns1 has the DNS entry for blackberry set should show the valid seaoffate.net certificate from letsencrypt).
* Internal(inside Pfsence): https://dashy.seaoffate.net (Assuming the internal nameserver ctns1 has the DNS entry for dashy set should show the valid seaoffate.net certificate from letsencrypt).
* Internal:(outside Pfsence) https://dashy.seaoffate.net (Assuming the DNS rewrite foe seaoffate.net on adguard set and Raisin reverse proxy rule is set, should show the valid seaoffate.net certificate from letsencrypt).
* External(though mobile phone Internet): https://dashy.seaoffate.net (Assuming the DNS for dashy is set on Cloudflare's control panel and dashy is proxied through Raisin it should show the Cloudflare SSL certificate).
When we have proved that the the dashboard works and that the login screen is displayed first we can move on to adding items to the dashboard.

==Configuring the Dashboard==

Homelab Dashboard

2026-04-20T18:46:55Z

Wikisailor: /* Introduction */

==Introduction==

We have decided to setup a '''[[Home Lab]]''' dashboard to monitor and administer the entire estate of Virtual machines, '''[[Proxmox Server | Proxmox]]''' hosts and all of the services that we have created. initially we will use the dashy dashboard but may well change for something else if dashy proves to be to difficult or in some way unsuitable.

==Dashy Setup==

in the interests of security for this sensitive project we are extending your "Full-Chain TLS" SME standard to Blackberry. This ensures that even if a client bypasses the proxy (Raisin) and hits Blackberry directly on the network, the traffic is still encrypted and presents the valid *.seaoffate.net certificate. It will also mean that within the Pfsense side of the LAN any client will still meet the same secure SSL certificate system provided by Letsencrypt. 🛡️We will mount our existing SSL certificates (synced from Raisin) directly into the Dashy container and configure Dashy to serve HTTPS natively. Details of how the Certs are downloaded and installed can be found '''[[Letsencrypt SSL Certs |here]]'''.

===Installation on Blackberry===

🛠️ The "Dockge-Way" Setup, on our Dockge UI on Blackberry, create a new stack called dashy, and use this single, hardened configuration
services:
dashy:
image: lissy93/dashy:latest
container_name: dashy
restart: unless-stopped
ports:
- 443:443
volumes:
# Use the path that we proved works:
- /mnt/archive_data/docker_data/stacks/dashy/conf.yml:/app/public/conf.yml
# SSL Certificates (Synced from Raisin)
- /etc/nginx/ssl/seaoffate.net/fullchain.pem:/etc/ssl/certs/fullchain.pem:ro
- /etc/nginx/ssl/seaoffate.net/privkey.pem:/etc/ssl/private/privkey.pem:ro
environment:
- NODE_ENV=production
- DOCKGE_ENABLE_CONSOLE=true
- SSL_PUB_KEY_PATH=/etc/ssl/certs/fullchain.pem
- SSL_PRIV_KEY_PATH=/etc/ssl/private/privkey.pem
- NODE_OPTIONS=--max-old-space-size=2048
networks: {}

===Post-Installation Steps ===

====Certificate Synchronization Hook====

Before the container will start correctly in SSL mode, we must have a basic conf.yml in the same directory as our compose.yaml. This file defines our users and our "Fruit Cluster" links. It is better to be sure that the docker app has the correct permissions for the yml, especially if it is in a non standard location.
touch sudo nano /mnt/archive_data/docker_data/stacks/dashy/conf.yml
sudo chown 1000:1000 /mnt/archive_data/docker_data/stacks/dashy/conf.yml
sudo chmod 644 /mnt/archive_data/docker_data/stacks/dashy/conf.yml
'''''Note''' we are using a non standard directory for our stacks, the more common location for the conf.yml is /opt/dockge/stacks/dashy/conf.yml''

To ensure Dashy stays updated when Raisin renews the Wildcard certs, make sure the deploy-wildcard.sh script on Raisin includes the Blackberry sync. It should have the Blackberry host in the servers list and the dashy restart in the if statements something like
# Restart Dashy (Blackberry)
if [ \$(docker ps -q -f name=dashy) ]; then
echo ' Restarting Dashy...'
docker restart dashy
fi

====Authentication Hardening====

To fulfill the "Secure Application" requirement, we enable Dashy’s internal authentication. Even with a valid SSL cert, no data is visible without a login. Dashy requires a SHA-256 hash for the admin password. Run this on any terminal:
echo -n "YourSecretPassword" | sha256sum
'''''Note''' the quotes are only needed if there is spaces or similar in the password and the quotation marks are not part of the password''
Take the resulting string and place it in the auth section of your conf.yml on Blackberry
nano /mnt/archive_data/docker_data/stacks/dashy/conf.yml
A sample conf is as follows ( including the password YourSecretPassword it is assumed that the user will change the hash to some other password):
<nowiki>appConfig:
title: SeaOfFate Command
statusCheck: true
auth:
enable: true
enableGuestAccess: false
users:
- user: nigel
hash: '790e294c25e704e042c899bb4dbb696b9daa2ed330d270082599f8591dc62b96'
type: admin
sections:
- name: Infrastructure
items:
- title: Vaultwarden
url: https://vault.seaoffate.net/alive
icon: hl-bitwarden</nowiki>

'''💡 Why /alive'''

if you just ping the main URL, Dashy might get a 401 Unauthorized or a redirect, which can sometimes show up as a "Yellow" or "Red" dot even if the service is fine. The /alive path is specifically designed for health checks like this and always returns a simple 200 OK

====Verification====

Once started, you can verify the "Full-Chain TLS" by visiting:
* Internal(inside Pfsence): https://192.168.100.85 (Should show the valid seaoffate.net certificate from letsencrypt ).
* Internal(inside Pfsence): https://blackberry (Assuming the internal nameserver ctns1 has the DNS entry for blackberry set should show the valid seaoffate.net certificate from letsencrypt).
* Internal(inside Pfsence): https://dashy.seaoffate.net (Assuming the internal nameserver ctns1 has the DNS entry for dashy set should show the valid seaoffate.net certificate from letsencrypt).
* Internal:(outside Pfsence) https://dashy.seaoffate.net (Assuming the DNS rewrite foe seaoffate.net on adguard set and Raisin reverse proxy rule is set, should show the valid seaoffate.net certificate from letsencrypt).
* External(though mobile phone Internet): https://dashy.seaoffate.net (Assuming the DNS for dashy is set on Cloudflare's control panel and dashy is proxied through Raisin it should show the Cloudflare SSL certificate).
When we have proved that the the dashboard works and that the login screen is displayed first we can move on to adding items to the dashboard.

==Configuring the Dashboard==

Homelab Dashboard

2026-04-20T18:46:44Z

Wikisailor: /* Introduction */

==Introduction==

We have decided to setup a '''[[Home Lab]]'' dashboard to monitor and administer the entire estate of Virtual machines, '''[[Proxmox Server | Proxmox]]''' hosts and all of the services that we have created. initially we will use the dashy dashboard but may well change for something else if dashy proves to be to difficult or in some way unsuitable.

==Dashy Setup==

in the interests of security for this sensitive project we are extending your "Full-Chain TLS" SME standard to Blackberry. This ensures that even if a client bypasses the proxy (Raisin) and hits Blackberry directly on the network, the traffic is still encrypted and presents the valid *.seaoffate.net certificate. It will also mean that within the Pfsense side of the LAN any client will still meet the same secure SSL certificate system provided by Letsencrypt. 🛡️We will mount our existing SSL certificates (synced from Raisin) directly into the Dashy container and configure Dashy to serve HTTPS natively. Details of how the Certs are downloaded and installed can be found '''[[Letsencrypt SSL Certs |here]]'''.

===Installation on Blackberry===

🛠️ The "Dockge-Way" Setup, on our Dockge UI on Blackberry, create a new stack called dashy, and use this single, hardened configuration
services:
dashy:
image: lissy93/dashy:latest
container_name: dashy
restart: unless-stopped
ports:
- 443:443
volumes:
# Use the path that we proved works:
- /mnt/archive_data/docker_data/stacks/dashy/conf.yml:/app/public/conf.yml
# SSL Certificates (Synced from Raisin)
- /etc/nginx/ssl/seaoffate.net/fullchain.pem:/etc/ssl/certs/fullchain.pem:ro
- /etc/nginx/ssl/seaoffate.net/privkey.pem:/etc/ssl/private/privkey.pem:ro
environment:
- NODE_ENV=production
- DOCKGE_ENABLE_CONSOLE=true
- SSL_PUB_KEY_PATH=/etc/ssl/certs/fullchain.pem
- SSL_PRIV_KEY_PATH=/etc/ssl/private/privkey.pem
- NODE_OPTIONS=--max-old-space-size=2048
networks: {}

===Post-Installation Steps ===

====Certificate Synchronization Hook====

Before the container will start correctly in SSL mode, we must have a basic conf.yml in the same directory as our compose.yaml. This file defines our users and our "Fruit Cluster" links. It is better to be sure that the docker app has the correct permissions for the yml, especially if it is in a non standard location.
touch sudo nano /mnt/archive_data/docker_data/stacks/dashy/conf.yml
sudo chown 1000:1000 /mnt/archive_data/docker_data/stacks/dashy/conf.yml
sudo chmod 644 /mnt/archive_data/docker_data/stacks/dashy/conf.yml
'''''Note''' we are using a non standard directory for our stacks, the more common location for the conf.yml is /opt/dockge/stacks/dashy/conf.yml''

To ensure Dashy stays updated when Raisin renews the Wildcard certs, make sure the deploy-wildcard.sh script on Raisin includes the Blackberry sync. It should have the Blackberry host in the servers list and the dashy restart in the if statements something like
# Restart Dashy (Blackberry)
if [ \$(docker ps -q -f name=dashy) ]; then
echo ' Restarting Dashy...'
docker restart dashy
fi

====Authentication Hardening====

To fulfill the "Secure Application" requirement, we enable Dashy’s internal authentication. Even with a valid SSL cert, no data is visible without a login. Dashy requires a SHA-256 hash for the admin password. Run this on any terminal:
echo -n "YourSecretPassword" | sha256sum
'''''Note''' the quotes are only needed if there is spaces or similar in the password and the quotation marks are not part of the password''
Take the resulting string and place it in the auth section of your conf.yml on Blackberry
nano /mnt/archive_data/docker_data/stacks/dashy/conf.yml
A sample conf is as follows ( including the password YourSecretPassword it is assumed that the user will change the hash to some other password):
<nowiki>appConfig:
title: SeaOfFate Command
statusCheck: true
auth:
enable: true
enableGuestAccess: false
users:
- user: nigel
hash: '790e294c25e704e042c899bb4dbb696b9daa2ed330d270082599f8591dc62b96'
type: admin
sections:
- name: Infrastructure
items:
- title: Vaultwarden
url: https://vault.seaoffate.net/alive
icon: hl-bitwarden</nowiki>

'''💡 Why /alive'''

if you just ping the main URL, Dashy might get a 401 Unauthorized or a redirect, which can sometimes show up as a "Yellow" or "Red" dot even if the service is fine. The /alive path is specifically designed for health checks like this and always returns a simple 200 OK

====Verification====

Once started, you can verify the "Full-Chain TLS" by visiting:
* Internal(inside Pfsence): https://192.168.100.85 (Should show the valid seaoffate.net certificate from letsencrypt ).
* Internal(inside Pfsence): https://blackberry (Assuming the internal nameserver ctns1 has the DNS entry for blackberry set should show the valid seaoffate.net certificate from letsencrypt).
* Internal(inside Pfsence): https://dashy.seaoffate.net (Assuming the internal nameserver ctns1 has the DNS entry for dashy set should show the valid seaoffate.net certificate from letsencrypt).
* Internal:(outside Pfsence) https://dashy.seaoffate.net (Assuming the DNS rewrite foe seaoffate.net on adguard set and Raisin reverse proxy rule is set, should show the valid seaoffate.net certificate from letsencrypt).
* External(though mobile phone Internet): https://dashy.seaoffate.net (Assuming the DNS for dashy is set on Cloudflare's control panel and dashy is proxied through Raisin it should show the Cloudflare SSL certificate).
When we have proved that the the dashboard works and that the login screen is displayed first we can move on to adding items to the dashboard.

==Configuring the Dashboard==

Homelab Dashboard

2026-04-20T18:46:12Z

Wikisailor: /* Introduction */

==Introduction==

We have decided to setup a [[Home Lab]] dashboard to monitor and administer the entire estate of Virtual machines, [[Proxmox Server | Proxmox]]hosts and all of the services that we have created. initially we will use the dashy dashboard but may well change for something else if dashy proves to be to difficult or in some way unsuitable.

==Dashy Setup==

in the interests of security for this sensitive project we are extending your "Full-Chain TLS" SME standard to Blackberry. This ensures that even if a client bypasses the proxy (Raisin) and hits Blackberry directly on the network, the traffic is still encrypted and presents the valid *.seaoffate.net certificate. It will also mean that within the Pfsense side of the LAN any client will still meet the same secure SSL certificate system provided by Letsencrypt. 🛡️We will mount our existing SSL certificates (synced from Raisin) directly into the Dashy container and configure Dashy to serve HTTPS natively. Details of how the Certs are downloaded and installed can be found '''[[Letsencrypt SSL Certs |here]]'''.

===Installation on Blackberry===

🛠️ The "Dockge-Way" Setup, on our Dockge UI on Blackberry, create a new stack called dashy, and use this single, hardened configuration
services:
dashy:
image: lissy93/dashy:latest
container_name: dashy
restart: unless-stopped
ports:
- 443:443
volumes:
# Use the path that we proved works:
- /mnt/archive_data/docker_data/stacks/dashy/conf.yml:/app/public/conf.yml
# SSL Certificates (Synced from Raisin)
- /etc/nginx/ssl/seaoffate.net/fullchain.pem:/etc/ssl/certs/fullchain.pem:ro
- /etc/nginx/ssl/seaoffate.net/privkey.pem:/etc/ssl/private/privkey.pem:ro
environment:
- NODE_ENV=production
- DOCKGE_ENABLE_CONSOLE=true
- SSL_PUB_KEY_PATH=/etc/ssl/certs/fullchain.pem
- SSL_PRIV_KEY_PATH=/etc/ssl/private/privkey.pem
- NODE_OPTIONS=--max-old-space-size=2048
networks: {}

===Post-Installation Steps ===

====Certificate Synchronization Hook====

Before the container will start correctly in SSL mode, we must have a basic conf.yml in the same directory as our compose.yaml. This file defines our users and our "Fruit Cluster" links. It is better to be sure that the docker app has the correct permissions for the yml, especially if it is in a non standard location.
touch sudo nano /mnt/archive_data/docker_data/stacks/dashy/conf.yml
sudo chown 1000:1000 /mnt/archive_data/docker_data/stacks/dashy/conf.yml
sudo chmod 644 /mnt/archive_data/docker_data/stacks/dashy/conf.yml
'''''Note''' we are using a non standard directory for our stacks, the more common location for the conf.yml is /opt/dockge/stacks/dashy/conf.yml''

To ensure Dashy stays updated when Raisin renews the Wildcard certs, make sure the deploy-wildcard.sh script on Raisin includes the Blackberry sync. It should have the Blackberry host in the servers list and the dashy restart in the if statements something like
# Restart Dashy (Blackberry)
if [ \$(docker ps -q -f name=dashy) ]; then
echo ' Restarting Dashy...'
docker restart dashy
fi

====Authentication Hardening====

To fulfill the "Secure Application" requirement, we enable Dashy’s internal authentication. Even with a valid SSL cert, no data is visible without a login. Dashy requires a SHA-256 hash for the admin password. Run this on any terminal:
echo -n "YourSecretPassword" | sha256sum
'''''Note''' the quotes are only needed if there is spaces or similar in the password and the quotation marks are not part of the password''
Take the resulting string and place it in the auth section of your conf.yml on Blackberry
nano /mnt/archive_data/docker_data/stacks/dashy/conf.yml
A sample conf is as follows ( including the password YourSecretPassword it is assumed that the user will change the hash to some other password):
<nowiki>appConfig:
title: SeaOfFate Command
statusCheck: true
auth:
enable: true
enableGuestAccess: false
users:
- user: nigel
hash: '790e294c25e704e042c899bb4dbb696b9daa2ed330d270082599f8591dc62b96'
type: admin
sections:
- name: Infrastructure
items:
- title: Vaultwarden
url: https://vault.seaoffate.net/alive
icon: hl-bitwarden</nowiki>

'''💡 Why /alive'''

if you just ping the main URL, Dashy might get a 401 Unauthorized or a redirect, which can sometimes show up as a "Yellow" or "Red" dot even if the service is fine. The /alive path is specifically designed for health checks like this and always returns a simple 200 OK

====Verification====

Once started, you can verify the "Full-Chain TLS" by visiting:
* Internal(inside Pfsence): https://192.168.100.85 (Should show the valid seaoffate.net certificate from letsencrypt ).
* Internal(inside Pfsence): https://blackberry (Assuming the internal nameserver ctns1 has the DNS entry for blackberry set should show the valid seaoffate.net certificate from letsencrypt).
* Internal(inside Pfsence): https://dashy.seaoffate.net (Assuming the internal nameserver ctns1 has the DNS entry for dashy set should show the valid seaoffate.net certificate from letsencrypt).
* Internal:(outside Pfsence) https://dashy.seaoffate.net (Assuming the DNS rewrite foe seaoffate.net on adguard set and Raisin reverse proxy rule is set, should show the valid seaoffate.net certificate from letsencrypt).
* External(though mobile phone Internet): https://dashy.seaoffate.net (Assuming the DNS for dashy is set on Cloudflare's control panel and dashy is proxied through Raisin it should show the Cloudflare SSL certificate).
When we have proved that the the dashboard works and that the login screen is displayed first we can move on to adding items to the dashboard.

==Configuring the Dashboard==

Homelab Dashboard

2026-04-20T18:45:03Z

Wikisailor: /* Introduction */

==Introduction==

We have decided to setup a [[Home Lab]] dashboard to monitor and administer the entire estate of Virtual machines, Proxmox hosts and all of the services that we have created. initially we will use the dashy dashboard but may well change for something else if dashy proves to be to difficult or in some way unsuitable.

==Dashy Setup==

in the interests of security for this sensitive project we are extending your "Full-Chain TLS" SME standard to Blackberry. This ensures that even if a client bypasses the proxy (Raisin) and hits Blackberry directly on the network, the traffic is still encrypted and presents the valid *.seaoffate.net certificate. It will also mean that within the Pfsense side of the LAN any client will still meet the same secure SSL certificate system provided by Letsencrypt. 🛡️We will mount our existing SSL certificates (synced from Raisin) directly into the Dashy container and configure Dashy to serve HTTPS natively. Details of how the Certs are downloaded and installed can be found '''[[Letsencrypt SSL Certs |here]]'''.

===Installation on Blackberry===

🛠️ The "Dockge-Way" Setup, on our Dockge UI on Blackberry, create a new stack called dashy, and use this single, hardened configuration
services:
dashy:
image: lissy93/dashy:latest
container_name: dashy
restart: unless-stopped
ports:
- 443:443
volumes:
# Use the path that we proved works:
- /mnt/archive_data/docker_data/stacks/dashy/conf.yml:/app/public/conf.yml
# SSL Certificates (Synced from Raisin)
- /etc/nginx/ssl/seaoffate.net/fullchain.pem:/etc/ssl/certs/fullchain.pem:ro
- /etc/nginx/ssl/seaoffate.net/privkey.pem:/etc/ssl/private/privkey.pem:ro
environment:
- NODE_ENV=production
- DOCKGE_ENABLE_CONSOLE=true
- SSL_PUB_KEY_PATH=/etc/ssl/certs/fullchain.pem
- SSL_PRIV_KEY_PATH=/etc/ssl/private/privkey.pem
- NODE_OPTIONS=--max-old-space-size=2048
networks: {}

===Post-Installation Steps ===

====Certificate Synchronization Hook====

Before the container will start correctly in SSL mode, we must have a basic conf.yml in the same directory as our compose.yaml. This file defines our users and our "Fruit Cluster" links. It is better to be sure that the docker app has the correct permissions for the yml, especially if it is in a non standard location.
touch sudo nano /mnt/archive_data/docker_data/stacks/dashy/conf.yml
sudo chown 1000:1000 /mnt/archive_data/docker_data/stacks/dashy/conf.yml
sudo chmod 644 /mnt/archive_data/docker_data/stacks/dashy/conf.yml
'''''Note''' we are using a non standard directory for our stacks, the more common location for the conf.yml is /opt/dockge/stacks/dashy/conf.yml''

To ensure Dashy stays updated when Raisin renews the Wildcard certs, make sure the deploy-wildcard.sh script on Raisin includes the Blackberry sync. It should have the Blackberry host in the servers list and the dashy restart in the if statements something like
# Restart Dashy (Blackberry)
if [ \$(docker ps -q -f name=dashy) ]; then
echo ' Restarting Dashy...'
docker restart dashy
fi

====Authentication Hardening====

To fulfill the "Secure Application" requirement, we enable Dashy’s internal authentication. Even with a valid SSL cert, no data is visible without a login. Dashy requires a SHA-256 hash for the admin password. Run this on any terminal:
echo -n "YourSecretPassword" | sha256sum
'''''Note''' the quotes are only needed if there is spaces or similar in the password and the quotation marks are not part of the password''
Take the resulting string and place it in the auth section of your conf.yml on Blackberry
nano /mnt/archive_data/docker_data/stacks/dashy/conf.yml
A sample conf is as follows ( including the password YourSecretPassword it is assumed that the user will change the hash to some other password):
<nowiki>appConfig:
title: SeaOfFate Command
statusCheck: true
auth:
enable: true
enableGuestAccess: false
users:
- user: nigel
hash: '790e294c25e704e042c899bb4dbb696b9daa2ed330d270082599f8591dc62b96'
type: admin
sections:
- name: Infrastructure
items:
- title: Vaultwarden
url: https://vault.seaoffate.net/alive
icon: hl-bitwarden</nowiki>

'''💡 Why /alive'''

if you just ping the main URL, Dashy might get a 401 Unauthorized or a redirect, which can sometimes show up as a "Yellow" or "Red" dot even if the service is fine. The /alive path is specifically designed for health checks like this and always returns a simple 200 OK

====Verification====

Once started, you can verify the "Full-Chain TLS" by visiting:
* Internal(inside Pfsence): https://192.168.100.85 (Should show the valid seaoffate.net certificate from letsencrypt ).
* Internal(inside Pfsence): https://blackberry (Assuming the internal nameserver ctns1 has the DNS entry for blackberry set should show the valid seaoffate.net certificate from letsencrypt).
* Internal(inside Pfsence): https://dashy.seaoffate.net (Assuming the internal nameserver ctns1 has the DNS entry for dashy set should show the valid seaoffate.net certificate from letsencrypt).
* Internal:(outside Pfsence) https://dashy.seaoffate.net (Assuming the DNS rewrite foe seaoffate.net on adguard set and Raisin reverse proxy rule is set, should show the valid seaoffate.net certificate from letsencrypt).
* External(though mobile phone Internet): https://dashy.seaoffate.net (Assuming the DNS for dashy is set on Cloudflare's control panel and dashy is proxied through Raisin it should show the Cloudflare SSL certificate).
When we have proved that the the dashboard works and that the login screen is displayed first we can move on to adding items to the dashboard.

==Configuring the Dashboard==