gupaxx/src

Gupax source files. Development documentation is here.

• Structure
• Thread Model
• Bootstrap
• Disk
• Scale
• Naming Scheme
• Why does Gupax need to be Admin? (on Windows)
  • The issue
  • The requirements
  • CMD's RunAs
  • PowerShell's Start-Process
  • Win32's ShellExecuteW
  • Registry Edit
  • Windows vs Unix

Structure

File/Folder	Purpose
constants.rs	General constants needed in Gupax
disk.rs	Code for writing to disk: state.toml/node.toml/pool.toml; This holds the structs for the [State] struct
ferris.rs	Cute crab bytes
gupax.rs	Gupax tab
helper.rs	The "helper" thread that runs for the entire duration Gupax is alive. All the processing that needs to be done without blocking the main GUI thread runs here, including everything related to handling P2Pool/XMRig
main.rs	The main App struct that holds all data + misc data/functions
node.rs	Community node ping code for the P2Pool simple tab
p2pool.rs	P2Pool tab
status.rs	Status tab
sudo.rs	Code for handling sudo escalation for XMRig on Unix
update.rs	Update code for the Gupax tab
xmrig.rs	XMRig tab

Thread Model

Process's (both Simple/Advanced) have:

• 1 OS thread for the watchdog (API fetching, watching signals, etc)
• 1 OS thread for a PTY-Child combo (combines STDOUT/STDERR for me, nice!)
• A PTY (pseudo terminal) whose underlying type is abstracted with the portable_pty library

The reason why STDOUT/STDERR is non-async is because P2Pool requires a TTY to take STDIN. The PTY library used, portable_pty, doesn't implement async traits. There seem to be tokio PTY libraries, but they are Unix-specific. Having separate PTY code for Windows/Unix is also a big pain. Since the threads will be sleeping most of the time (the pipes are lazily read and buffered), it's fine. Ideally, any I/O should be a tokio task, though.

Bootstrap

This is how Gupax works internally when starting up:

1. INIT

   • Initialize custom console logging with log, env_logger
   • Initialize misc data (structs, text styles, thread count, images, etc)
   • Start initializing main App struct
   • Parse command arguments
   • Attempt to read disk files
   • If errors were found, set the panic error screen

2. AUTO

   • If auto_update == true, spawn auto-updating thread
   • If auto_ping == true, spawn community node ping thread
   • If auto_p2pool == true, spawn P2Pool
   • If auto_xmrig == true, spawn XMRig

3. MAIN

   • All data should be initialized at this point, either via state.toml or default options
   • Start App frame
   • Do App stuff
   • If ask_before_quit == true, ask before quitting
   • Kill processes, kill connections, exit

Disk

Long-term state is saved onto the disk in the "OS data folder", using the TOML format. If not found, default files will be created. Given a slightly corrupted state file, Gupax will attempt to merge it with a new default one. This will most likely happen if the internal data structure of state.toml is changed in the future (e.g removing an outdated setting). Merging silently in the background is a good non-interactive way to handle this. The node/pool database cannot be merged, and if given a corrupted file, Gupax will show an un-recoverable error screen. If Gupax can't read/write to disk at all, or if there are any other big issues, it will show an un-recoverable error screen.

OS	Data Folder	Example
Windows	{FOLDERID_LocalAppData}	C:\Users\Alice\AppData\Roaming\Gupax
macOS	$HOME/Library/Application Support	/Users/Alice/Library/Application Support/Gupax
Linux	$XDG_DATA_HOME or $HOME/.local/share	/home/alice/.local/share/gupax

The current files saved to disk:

• state.toml Gupax state/settings
• node.toml The manual node database used for P2Pool advanced
• pool.toml The manual pool database used for XMRig advanced

Arti (Tor) also needs to save cache and state. It uses the same file/folder conventions.

Scale

Every frame, the max available [width, height] are calculated, and those are used as a baseline for the Top/Bottom bars, containing the tabs and status bar. After that, all available space is given to the middle ui elements. The scale is calculated every frame so that all elements can scale immediately as the user adjusts it; this doesn't take as much CPU as you might think since frames are only rendered on user interaction. Some elements are subtracted a fixed number because the ui.seperator()'s add some fixed space which needs to be accounted for.

Main [App] outer frame (default: [1280.0, 800.0], 16:10 aspect ratio)
   ├─ TopPanel     = height: 1/12th
   ├─ BottomPanel  = height: 1/20th
   ├─ CentralPanel = height: the rest

Naming Scheme

This is the internal naming scheme used by Gupax when updating/creating default folders/etc:

Windows:

• Gupax: Gupax.exe
• P2Pool: P2Pool\p2pool.exe
• XMRig: XMRig\xmrig.exe

macOS:

• Gupax: Gupax.app/.../Gupax (Gupax is packaged as an .app on macOS)
• P2Pool: p2pool/p2pool
• XMRig: xmrig/xmrig

Linux:

• Gupax: gupax
• P2Pool: p2pool/p2pool
• XMRig: xmrig/xmrig

These have to be packaged exactly with these names because the update code is case-sensitive. If an exact match is not found, it will error.

Package naming schemes:

• gupax - gupax-vX.X.X-(windows|macos|linux)-x64(standalone|bundle).(zip|tar.gz)
• p2pool - p2pool-vX.X.X-(windows|macos|linux)-x64.(zip|tar.gz)
• xmrig - xmrig-X.X.X-(msvc-win64|macos-x64|linux-static-x64).(zip|tar.gz)

Exceptions (there are always exceptions...):

• XMRig doesn't have a [v], so it is [xmrig-6.18.0-...]
• XMRig separates the hash and signature
• P2Pool hashes are in UPPERCASE

Why does Gupax need to be Admin? (on Windows)

TL;DR: Because Windows.

Slightly more detailed TL;DR: Rust does not have mature Win32 API wrapper libraries. Although Microsoft has an official "Rust" library, it is quite low-level and using it within Gupax would mean re-implementing a lot of Rust's STDLIB process module code.

If you are confused because you use Gupax on macOS/Linux, this is a Windows-only issue.

The following sections will go more into the technical issues I've encountered in trying to implement something that sounds pretty trivial: Starting a child process with elevated privilege, and getting a handle to it and its output. (it's a rant about windows).

---

The issue

XMRig needs to be run with administrative privileges to enable MSR mods and hugepages. There are other ways of achieving this through pretty manual and technical efforts (which also gets more complicated due to OS differences) but in the best interest of Gupax's users, I always want to implement things so that it's easy for the user.

Users should not need to be familiar with MSRs to get max hashrate, this is something the program (me, Gupax!) should do for them.

---

The requirements

Process's in Gupax need the following criteria met:

• I (as the parent process, Gupax) must have a direct handle to the process so that I can send SIGNALs
• I must have a handle to the process's STDOUT+STDERR so that I can actually relay output to the user
• I really should but don't absolutely need a handle to STDIN so that I can send input from the user

In the case of XMRig, I absolutely must enable MSR's automatically for the user, that's the whole point of XMRig, that's the point of an easy-to-use GUI. Although I want XMRig with elevated rights, I don't want these side-effects:

• All of Gupax running as Admin
• P2Pool running as Admin

Here are the "solutions" I've attempted:

---

CMD's RunAs

Window has a runas command, which allows for privilege escalation. Perfect! Spawn a shell and it's easy as running this:

runas /user:Administrator xmrig.exe [...]

...right?

The Administrator in this context is a legacy account, not meant to be touched, not really the Admin we are looking for, but more importantly: the password is not set, and the entire account is disabled by default. This means you cannot actually runas as that Administrator. Technically, all it would take is for the user to enabled the account and set a password. But that is already asking for too much, remember: that's my job, to make this easy and automatic. So this is a no-go, next.

---

PowerShell's Start-Process

Window's PowerShell has a nice built-in called Start-Process. This allows PowerShell to start... processes. In particular, I was intrigued by the all-in-one flag: -Verb RunAs, which runs the provided process with elevated permissions after a UAC prompt. That sounds perfect... except if you click that link you'll see 2 sets of syntax. IF you are escalating privilege, Microsoft puts a lot more retrictions on what you can do with this built-in, in particular:

• You CANNOT redirect STDOUT/STDERR/STDIN
• You CANNOT run the process in the current shell (a new PowerShell window will always open!)

I attempted some hacks like chaining non-admin PowerShell + admin PowerShell together, which made things overly complicated and meant I would be handling logic within these child PowerShell's which would be controlled via STDIN from Gupax code... Not very robust. I also tried just starting an admin PowerShell directly from Gupax, but that meant the user, upon clicking [Start] for XMRig, would see a UAC prompt to open PowerShell, which wasn't a good look. Eventually I gave up on PowerShell, next.

---

Win32's ShellExecuteW

This was the first option I came across, but I intentionally ignored it due to many reasons. Microsoft has official Windows API bindings in Rust. That library has a couple problems:

1. All (the entire library) code requires unsafe
2. It's extremely low-level

The first one isn't actually as bad as it seems, this is Win32 so it's battle-tested. It's also extern C, so it makes sense it has to wrapped in unsafe.

The second one is the real issue. ShellExecuteW is a Win32 function that allows exactly what I need, starting a process with elevated privilege with the runas flag. It even shows the UAC to the user. But... that's it! No other functionality. The highly abstracted Command type in Rust's STDLIB actually uses CreateProcessW, and due to type imcompatabilities, using ShellExecuteW on my own would mean re-implementing ALL the functionality Rust STDLIB gives, aka: handling STDOUT, STDERR, STDIN, sending SIGNALS, waiting on process, etc etc. I would be programming for "Windows", not "Rust". Okay... next.

---

Registry Edit

To start a process in Windows with elevated escalation you can right-click -> Run as Administrator, but you can also set a permanent flag deeper in the file's options. In reality this sets a Registry Key with the absolute path to that executable and a RUNASADMIN flag. This allows Windows to know which programs to run as an admin. There is a Rust library called WinReg that provides functionality to read/write to the Registry. Editing the Registry is akin to editing someone's .bashrc, it's a sin! But... if it means automatically applying the MSR mod and better UX, then yes I will. The flow would have been:

• User starts XMRig
• Gupax notices XMRig is not admin
• Gupax tells user
• Gupax gives option to AUTOMATICALLY edit registry
• Gupax also gives the option to show how to do it manually

This was the solution I would have gone with, but alas, the abstracted Command types I am using to start processes completely ignore this metadata. When Gupax starts XMRig, that Run as Administrator flag is completely ignored. Grrr... what options are left?

---

Windows vs Unix

Unix (macOS/Linux) has have a super nice, easy, friendly, not-completely-garbage userland program called: sudo. It is so extremely simple to use sudo as a sort of wrapper around XMRig since sudo isn't completely backwards and actually has valuable flags! No legacy Administrator, no UAC prompt, no shells within shells, no low-level system APIs, no messing with the user Registry.

You get the user's password, you input it to sudo with --stdin and you execute XMRig with it. Simple, easy, nice. (Don't forget to zero the password memory, though).

With no other option left on Windows, I unfortunately have to fallback to the worst solution: shipping Gupax's binary to have Administrator metadata, so that it will automatically prompt users for UAC. This means all child process spawned by Gupax will ALSO have admin rights. Windows having one of the most complicated spaghetti privilege systems is ironically what led me to use the most unsecure option.

Depending on the privilege used, Gupax will error/panic:

• Windows: If not admin, warn the user about potential lower XMRig hashrate
• Unix: IF admin, panic! Don't allow anything. As it should be.

If you're reading this and have a solution (that isn't using Win32), please... please teach me.