Setup Guide for Xandeum pNodes

this document provides step by step instructions for setting up and managing a pnode for the xandeum network each section covers a specific part of the process, from prerequisites to troubleshooting if you have already run through the prerequisites and security concerns, you can skip to the installation https //app archbee com/docs/jjnl3gd8vnrbik0kh13ok/dxthfwswjqtbz2gyn2gpv#ibw0o prerequisites for setting up a pnode for xandeum before you begin setting up your pnode for the xandeum network, ensure you meet the following requirements these steps will prepare your hardware, software, and environment to run xandminer and xandminerd effectively hardware requirements recommended vps we recommend using a virtual private server (vps) from contabo for $5 50/month however, contabo’s default 20 gb ssd storage is insufficient for xandeum’s needs ensure your vps or server has at least 4 cpu core 4 gb ram 80 gb ssd storage (20 gb for system operations + an additional at least 60gib free space to dedicate to the xandeum network) 1 gbps network alternative options you can use any ubuntu based machine, including home servers or other vps providers, as long as they meet the minimum specs above and have a stable internet connection storage for blockchain grade data ensure your pnode has sufficient storage (e g , additional drives or partitions) to handle xandeum’s blockchain grade storage needs xandminerd will interface with your hardware to query drives and partitions software requirements operating system on pnode ubuntu 24 04 lts or later (recommended for stability and compatibility with xandeum software) ensure the pnode has a clean, updated ubuntu installation local machine os (for managing pnode) windows 10 or later, macos, or any linux distribution (e g , ubuntu, fedora) windows users must have powershell or command prompt available (built into windows 10/11) ssh client windows built in openssh client (available since windows 10) macos/linux built in ssh command (via openssh) web browser any modern browser (e g , chrome, firefox, edge) to access the xandminer gui at http //localhost 3000 network requirements stable internet connection your pnode and local machine need a reliable internet connection for ssh access and software updates port availability ensure ports 3000 and 4000 are not blocked by firewalls or your isp on your pnode, as it will be used for the xandminer gui and xandminerd background service via an ssh tunnel static ip (recommended) a static ip address for your pnode is recommended for consistent access, though dynamic ips can work with proper dns configuration tools and access git installed on your pnode to clone repositories from github ssh keys you’ll need to generate an ssh key pair (ed25519 recommended) on your local machine and add it to your pnode for secure access instructions for this are in the next section basic command line knowledge familiarity with terminal commands (e g , ssh , curl , git ) on your local machine and pnode notes important these prerequisites ensure your pnode can run xandminer https //github com/xandeum/xandminer https //github com/xandeum/xandminer and xandminerd https //github com/xandeum/xandminerd https //github com/xandeum/xandminerd effectively if you have questions or encounter issues, consult our troubleshooting section or join our community on x/discord for support future bft consensus as xandeum evolves to include byzantine fault tolerance (bft) consensus, your pnode will need additional resources we’ll provide updates in future sections xandeum network branding note that “xandeum network” is our official branding, with both words capitalized visit our main website at xandeum network https //xandeum network for more information ssh key setup for pnode access to securely access and manage your pnode, you'll need to generate an ssh key pair on your local machine and configure it on your pnode we recommend using ed25519 keys for their security and performance, but rsa 4096 is also supported as a fallback generating an ssh key pair follow these steps based on your local machine's operating system on windows (using openssh) requirements ensure you're running windows 10 or later with powershell or command prompt available generate an ed25519 key open powershell or command prompt run the following command to generate an ed25519 key pair ssh keygen t ed25519 press enter to accept the default file location ( c \users\\\<username>\\ ssh\id ed25519 ) or specify a custom path optionally, enter a passphrase for added security (recommended, but optional) this will create two files id ed25519 (private key) and id ed25519 pub (public key) in your ssh directory fallback to rsa 4096 (if needed) if ed25519 isn't compatible with your pnode, generate an rsa 4096 key with ssh keygen t rsa b 4096 verify the key check that the keys were generated by listing the ssh directory dir c \users\\\<username>\\ ssh on linux or macos generate an ed25519 key open a terminal run the following command to generate an ed25519 key pair ssh keygen t ed25519 press enter to accept the default file location ( /home/\<username>/ ssh/id ed25519 ) or specify a custom path optionally, enter a passphrase for added security (recommended, but optional) this will create id ed25519 (private key) and id ed25519 pub (public key) in your ssh directory fallback to rsa 4096 (if needed) if ed25519 isn't compatible, generate an rsa 4096 key with ssh keygen t rsa b 4096 verify the key check the keys by listing the ssh directory ls l / ssh adding the public key to your pnode copy the public key ( id ed25519 pub or id rsa pub , depending on the key type you generated) to your clipboard on windows (powershell) type c \users\\\<username>\\ ssh\id ed25519 pub | clip on linux/macos cat / ssh/id ed25519 pub | pbcopy # macos cat / ssh/id ed25519 pub | xclip # linux (if xclip is installed) ssh into your pnode using password authentication (you'll disable this later) ssh root@\<my p node ip> replace \<my p node ip> with your pnode's ip address create or edit the / ssh/authorized keys file on your pnode mkdir p / ssh nano / ssh/authorized keys paste your public key into the file, save, and exit (ctrl+o, enter, ctrl+x in nano ) ensure the permissions are correct chmod 700 / ssh chmod 600 / ssh/authorized keys testing ssh access exit the pnode ( exit ) and test ssh access using your private key on windows (powershell) ssh i c \users\\\<username>\\ ssh\id ed25519 root@\<my p node ip> on linux/macos ssh i / ssh/id ed25519 root@\<my p node ip> if prompted, enter your ssh key passphrase (if you set one) you should now access your pnode without a password if you are still prompted for a password, go back through the above steps or ask for assistance from the community disabling password login for enhanced security to maximize the security of your pnode, you should disable password based ssh login and rely solely on ssh keys this prevents brute force attacks and ensures only authorized users with ssh keys can access your pnode however, this step is irreversible without access to your ssh private key, so proceed carefully important precautions ensure you've successfully tested ssh key based access (as described earlier in this guide) before proceeding keep your ssh private key safe and backed up if you lose it, you won't be able to access your pnode without assistance from your hosting provider run this step from a secure connection, and keep your current ssh session open in case you need to revert changes using our script to disable password login we've created a simple script to safely disable password login on your pnode, handling common configuration file variations (e g , /etc/ssh/sshd d ) follow these steps note will only work if you are using file naming from above (ie / ssh/id ed25519 ) note option 4 in the xandeum pnode software installer will handle ssh hardening also you may use either method download our ssh hardening script by running the following command in your terminal wget https //gist github com/bernieblume/7c49b49e718f9e41d4802e94e7a9e103/raw/nopwlogin sh make the script executable chmod +x nopwlogin sh run the script with sudo sudo /nopwlogin sh follow the on screen instructions and verify that you can still access your pnode using your ssh key manual instructions (advanced users) if you prefer to disable password login manually or the script doesn't work for your setup, follow these steps ssh from your local machine into your pnode using your ssh key ssh i / ssh/id ed25519 root@\<my p node ip> open the ssh configuration file in a text editor (e g , nano or vim ) nano /etc/ssh/sshd config look for the following lines and set them to no if the lines are commented (start with # ), uncomment them by removing the # passwordauthentication no challengeresponseauthentication no check if /etc/ssh/sshd config d/ exists if it does, create or edit a file (e g , 10 disable password auth conf ) in that directory and add passwordauthentication no challengeresponseauthentication no save the file and exit the editor (in nano , press ctrl+o, enter, then ctrl+x) restart the ssh service systemctl restart ssh or, if that doesn't work service ssh restart test ssh access with your key to ensure you're not locked out ssh i / ssh/id ed25519 root@\<my p node ip> troubleshooting if you're locked out, restore from the backups created by the script (located at /etc/ssh/sshd config bak and /etc/ssh/sshd config d bak ) or contact your hosting provider for console access if password login is still enabled, check for conflicting settings in /etc/ssh/sshd config d/ files and ensure the ssh service restarted correctly note disabling password login is permanent unless you re enable it manually or via console access always test key based access before proceeding installing and configuring xandminer on your pnode now that you've secured your pnode with ssh key based authentication and disabled password login, it's time to install and configure the xandminer software to set up your pnode as a mining node this chapter guides you through downloading and running the pnode installer script, which automates the setup of xandminer and xandminerd, including repository management, systemd service configuration, and verification steps prerequisites before proceeding, ensure the following you have ssh access to your pnode using your ssh key (as configured in the previous chapter) optionally, open an ssh session tunnel that forwards the ports that will be needed later as well ssh i / ssh/id ed25519 root@\<my p node ip> l 4000\ localhost 4000 l 3000\ localhost 3000 this will allow port http //localhost 3000 in your web browser to connect through the ssh tunnel to your xandminer port 4000 is used to connect the gui to the xandminerd service your pnode is running a compatible linux distribution (e g , ubuntu 20 04 or later, debian 11 or later) you have root privileges on your pnode git, curl, and systemd are installed on your pnode you can install them with apt update && apt install y git curl systemd restart if prompted to load newer kernel downloading and running the pnode installer we've created a simple installer script to automate the setup of xandminer and xandminerd on your pnode this script checks for critical security settings, clones or updates the repositories, configures systemd services, and provides instructions for the next steps steps to run the installer ssh from your local machine into your pnode using your ssh key ssh i / ssh/id ed25519 root@\<my p node ip> l 4000\ localhost 4000 l 3000\ localhost 3000 replace \<my p node ip> with your pnode's ip address download the installer script by running the following command in your terminal wget o install sh "https //raw\ githubusercontent com/xandeum/xandminer installer/refs/heads/master/install sh" make install sh executable chmod a+x install sh run the script with sudo /install sh follow the on screen instructions and verify the output to ensure the installation completed successfully choose option 1 install xandeum pnode software what the installer script does the installer script performs the following actions repository management checks if the xandminer and xandminerd directories exist in /root if the directories don't exist, the script clones the respective git repositories into /root/xandminer and /root/xandminerd if the directories exist, the script changes into each directory and runs git pull to update the repositories to the latest version systemd service configuration copies the xandminer service and xandminerd service files (located in the root directory of their respective repositories) to /etc/systemd/system enablesand starts the services using systemctl enable xandminer service now and systemctl enable xandminerd service now success message outputs a success message indicating that the services are enabled and running, along with a link to the documentation for further instructions (using a placeholder for now, e g , \<docs link> ) troubleshooting if git cloning or pulling fails, ensure you have an active internet connection and the necessary permissions on your pnode if systemd service configuration fails, check the permissions of /etc/systemd/system and ensure systemd is properly installed and running next steps once the installer script has completed successfully, it is reccomeended to restart your pnode to load any new kernel drivers xandminer and xandminerd services will be running upon reboot refer to the documentation at \<docs link> for detailed instructions on starting, monitoring, and troubleshooting the services, as well as configuring xandminer for optimal mining performance starting and monitoring xandminer services now that you’ve installed and enabled the xandminer and xandminerd services on your pnode using the installer script, it’s time to start them and monitor their operation this chapter walks you through manually starting the services, checking their status, reviewing logs, and troubleshooting common issues to ensure your pnode is mining effectively prerequisites before proceeding, ensure the following you have ssh access to your pnode using your ssh key (as configured in the “ssh key setup” chapter) the xandminer and xandminerd services are installed and enabled on your pnode (as described in the “installing and configuring xandminer on your pnode” chapter) you have root privileges on your pnode starting the xandminer and xandminerd services the installer script enabled the services but did not start them follow these steps to manually start the services ssh into your pnode using your ssh key ssh i / ssh/id ed25519 root@\<my p node ip> l 4000\ localhost 4000 l 3000\ localhost 3000 replace \<my p node ip> with your pnode’s ip address start the xandminer service systemctl start xandminer start the xandminerd service systemctl start xandminerd checking service status after starting the services, verify they are running correctly check the status of the xandminer service systemctl status xandminer look for output indicating “active (running)” and no errors if the service isn’t running, you’ll see “inactive” or “failed ” check the status of the xandminerd service systemctl status xandminerd sample output for a running service here’s an example of what a running service status might look like xandminer service xandminer mining service loaded loaded (/etc/systemd/system/xandminer service; enabled; vendor preset enabled) active active (running) since fri 2025 02 21 10 00 00 utc; 5min ago main pid 12345 (xandminer) tasks 10 (limit 4915) memory 50 0m cgroup /system slice/xandminer service └─12345 /usr/bin/xandminer config /root/xandminer/config json or, if there’s an issue xandminer service xandminer mining service loaded loaded (/etc/systemd/system/xandminer service; enabled; vendor preset enabled) active failed (result exit code) since fri 2025 02 21 10 05 00 utc; 1min ago docs \<docs link> process 12346 execstart=/usr/bin/xandminer config /root/xandminer/config json (code=exited, status=1/failure) \### monitoring logs to troubleshoot or monitor the services, check their logs using `journalctl` 1\ view logs for xandminer `journalctl u xandminer` 2\ view logs for xandminerd `journalctl u xandminerd` you can also tail the logs in real time `journalctl u xandminer f` `journalctl u xandminerd f` look for any error messages, warnings, or indications of successful mining activity (e g , connection to the mining pool, hash rates, etc ) troubleshooting common issues if the services fail to start or aren’t running as expected, try the following check permissions ensure the service files in /etc/systemd/system and the repository directories ( /root/xandminer , /root/xandminerd ) have the correct permissions chmod 644 /etc/systemd/system/xandminer service chmod 644 /etc/systemd/system/xandminerd service chmod r 755 /root/xandminer chmod r 755 /root/xandminerd restart services if you make changes, restart the services systemctl restart xandminer systemctl restart xandminerd review logs use journalctl to identify specific errors (e g , missing dependencies, configuration issues, or network problems) verify dependencies ensure all required dependencies for xandminer and xandminerd are installed check network ensure your pnode has internet access and can connect to the mining pool (if applicable) enabling automatic startup (optional) if you want the services to start automatically on boot (in addition to manual starting), you can enable them (though this was already done by the installer) systemctl enable xandminer systemctl enable xandminerd next steps once the services are running and monitored, you can configure xandminer for optimal mining performance setting up an ssh tunnel and accessing the xandminer web gui to manage your pnode remotely and access the xandminer web based graphical user interface (gui) securely, you can set up an ssh tunnel using openssh on windows this chapter guides you through creating an ssh tunnel to forward traffic from your local machine to the xandminer web gui running on your pnode, ensuring secure and encrypted access prerequisites before proceeding, ensure the following you have ssh access to your pnode using your ssh key (as configured in the “ssh key setup” chapter) the xandminer and xandminerd services are installed, enabled, and running (as described in the “starting and monitoring xandminer services” chapter) the xandminer web gui is enabled and configured on your pnode you have root privileges on your pnode you have openssh installed on your windows machine you can install it via windows 10/11 settings under “optional features” or through windows subsystem for linux (wsl) enabling the xandminer web gui open an ssh tunnel that forwards the proper ports through the tunnel, ensure the xandminer service is enabled and running on your pnode ssh into your pnode using openssh on windows ssh i %userprofile%\\ ssh\id ed25519 root@\<my p node ip> l 4000\ localhost 4000 l 3000\ localhost 3000 replace \<my p node ip> with your pnode’s ip address check if the xandminer web gui service is installed and enabled systemctl status xandminer if the service isn’t running or installed, refer to the xandminer installation instructions start and enable the xandminer web gui service systemctl enable now xandminer verify the gui is accessible locally on the pnode (if on the same network) by opening a web browser on the pnode and navigating to http //localhost 3000 (or the port specified in the documentation) setting up an ssh tunnel with openssh on windows the xandminer web gui typically runs on a local port (e g , 3000) on your pnode, but it may not be exposed publicly for security reasons you can use an ssh tunnel with openssh on windows to forward traffic from your local machine to the pnode’s gui port securely open a windows command prompt, powershell, or wsl terminal on your local machine and create an ssh tunnel to forward local ports 3000 and 4000 to the pnode’s ports 3000 and 4000 ssh i %userprofile%\\ ssh\id ed25519 l 4000\ localhost 4000 l 3000\ localhost 3000 root@\<my p node ip> l 3000\ localhost 3000 forwards local port 3000 to port 3000 on the pnode l 4000\ localhost 4000 forwards local port 4000 to port 4000 on the pnode replace \<my p node ip> with your pnode’s ip address keep the terminal window open to maintain the tunnel the ssh connection will stay active until you close the terminal, the session times out, or the connection is interrupted open a web browser on your local machine and navigate to http //localhost 3000 to access the xandminer web gui managing the ssh tunnel when using an ssh tunnel, consider the following guidance to manage it effectively and securely leaving the tunnel open you can leave the ssh tunnel open while actively managing your pnode via the xandminer web gui this allows continuous access to the gui without needing to recreate the tunnel frequently however, be aware that the tunnel might close over time due to network interruptions, idle timeouts, or system sleep/hibernate modes on your local machine or pnode reopening the tunnel if the tunnel closes (e g , due to a network disconnection or timeout), you’ll need to reopen it by rerunning the ssh command ssh i %userprofile%\\ ssh\id ed25519 l 4000\ localhost 4000 l 3000\ localhost 3000 root@\<my p node ip> check the terminal for error messages (e g , “connection closed” or “connection timed out”) to diagnose why the tunnel closed avoid leaving unattended for too long do not leave the ssh tunnel open for extended periods when you’re not actively using it, such as when you leave your pc unattended for hours or overnight leaving the tunnel open unnecessarily can expose your pnode to potential security risks if the connection is compromised or if your local machine is left unsecured close the terminal or disconnect the ssh session ( exit or ctrl+c) when you’re done using the gui to minimize risks checking the pnode ports use this one line command to check if the correct ports are accessible from the public interent it tests public udp 5000 and localhost tcp 3000 and tcp 4000 the tool uses nc (netcat) and ss (socket statistics) to test the pnode ports cli my ip=$(curl s https //ipinfo io/ip) && echo " udp 5000 on $my ip" && if command v nc >/dev/null 2>&1; then timeout 10 nc zu $my ip 5000 && echo "✅ udp 5000 public" || echo "❌ udp 5000 not public"; else echo "⚠️ netcat (nc) not installed cannot test udp 5000"; fi && echo " localhost tcp " && for port in 3000 4000; do ss tlnp 2>/dev/null | grep q "127 0 0 1 $port " && echo "✅ $port" || echo "❌ $port"; done the output should look like this if you have any red x marks next to a port you need to investigate the connection issues this section is now complete see below for advanced and future features otherwise, continue on to register your pnode docid\ pl5ymcm3wuiz5pbdbcqoe on the xandeum devnet troubleshooting ssh tunnels and web gui access if you encounter issues, try the following connection refused ensure the xandminer web gui service is running on the pnode sudo systemctl status xandminer start it if necessary sudo systemctl enable now xandminer port conflict verify port 3000 (or the configured gui port) isn’t in use by another service on your local machine or pnode sudo netstat tuln | grep 3000 ssh key issues confirm your ssh key is correctly configured and permissions are set (e g , chmod 600 %userprofile%\\ ssh\id ed25519 on wsl or via a linux like file manager on windows) firewall rules ensure port 3000 is open on the pnode for local access (if not using a tunnel, though tunnels bypass external firewalls) ufw allow 3000/tcp browser issues clear your browser cache or try a different browser if the gui doesn’t load automating ssh tunnels (optional) for frequent access, automate the ssh tunnel using a batch script or ssh configuration create a batch script (e g , start ssh tunnel bat ) @echo off start cmd /k "ssh i %userprofile% ssh\id ed25519 l 3000\ localhost 3000 l 4000\ localhost 4000 root@\<my p node ip>" save it, double click to run, and it will open a new command prompt window with the tunnel close the window to terminate the tunnel or, edit your ssh config ( %userprofile%\\ ssh\config ) to include a tunnel host \<pnode hostname> hostname \<my p node ip> user root identityfile %userprofile% ssh\id ed25519 localforward 3000 localhost 3000 localforward 4000 localhost 4000 then connect with ssh pnode next steps with the ssh tunnel and xandminer web gui set up, you can remotely manage your pnode’s mining operations securely use the gui to complement the command line tools and monitoring scripts from previous chapters