/monero-bash

a wrapper for Monero written in Bash

Primary LanguageShellMIT LicenseMIT

Archived on 2023-04-25

Update functionality is broken.

v2.0.0 will fix this (which will come... eventually...)

Until then, this project is no longer actively maintained.

For a GUI alternative to running P2Pool/XMRig, see Gupax.


README

monero-bash

monero-bash

Contents

About

monero-bash is a Linux CLI wrapper for: Monero | P2Pool | XMRig

A few video demos:

  • Wallet menu
    wallet.mp4
  • Package manager
    package.mp4
  • Mining & watching live stats
    watch.mp4

This project was funded by the Monero Community via the CCS, thanks to all who donated!

Features

  • 📦 PKG MANAGER Automatic download/verification/upgrading of packages
  • 💵 WALLET MENU Interactive menu for selecting/creating wallets
  • 👺 SYSTEMD Control monerod/p2pool/xmrig as background processes
  • ⛏️ MINING Interactive mining configuration, built for P2Pool
  • 📈 STATUS Display stats (CPU usage, P2Pool shares, Hashrate, etc)
  • 👁️ WATCH Watch live output of processes or general status
  • 🧅 TOR Route connections through Tor
  • 📄 RPC monerod JSON-RPC interface
  • 🔒 GPG Encrypt and backup your wallets

Distro Coverage

Linux Distribution Version Status Info
Debian 11, 10 🟢
Ubuntu LTS 22.04, 20.05 🟢
Pop!_OS LTS 22.04, 20.04 🟢
Linux Mint 21, 20.03 🟢
Fedora Workstation 36, 35 🔴 SELinux disables systemd functionality
Arch Linux 🟡 wget must be installed
Manjaro 21.3.7 🟢
Gentoo 🔴 wget & systemd must be installed

Install

To install: download the latest release here, extract and run monero-bash

tar -xf monero-bash-v1.9.8.tar
cd monero-bash
./monero-bash

This will start the interactive install process into /usr/local/share/monero-bash

It is recommended to verify the hash and PGP signature before installation.
Download the SHA256SUM file, download and import my PGP key, and verify:

sha256sum -c SHA256SUM
gpg --import hinto-janai.asc
gpg --verify SHA256SUM

To install with git:

git clone https://github.com/hinto-janai/monero-bash
cd monero-bash
./monero-bash

ALWAYS clone the main branch, the other branches are not tested


To uninstall:

monero-bash uninstall

Or manually remove everything:

rm -r ~/.monero-bash
sudo rm /usr/local/bin/monero-bash
sudo rm -r /usr/local/share/monero-bash
sudo rm /etc/systemd/system/monero-bash*
sudo rm /etc/systemd/system/multi-user.target.wants/monero-bash*

THIS WILL DELETE YOUR WALLETS - remember to move them before uninstalling!

Commands

USAGE: monero-bash command <argument> [optional]

monero-bash                                           Open wallet menu
uninstall                                             Uninstall ALL OF monero-bash

update                                                Check for package updates
upgrade [force|verbose]                               Upgrade all out-of-date packages
upgrade <package> [force|verbose]                     Upgrade a specific package
install <all/package> [verbose]                       Install <all> or a specific package
remove  <all/package>                                 Remove <all> or a specific package

config                                                Configure P2Pool+XMRig mining settings
full    <monero/p2pool/xmrig>                         Start the process directly attached (foreground)
start   <all/monero/p2pool/xmrig>                     Start process with systemd (background)
stop    <all/monero/p2pool/xmrig>                     Gracefully stop the systemd process
restart <all/monero/p2pool/xmrig>                     Restart the systemd process
enable  <all/monero/p2pool/xmrig>                     Enable the process to auto-start on boot
disable <all/monero/p2pool/xmrig>                     Disable the process from auto-starting on boot
reset   <bash/monero/p2pool/xmrig> [config|systemd]   Reset your configs/systemd to default
edit    <bash/monero/p2pool/xmrig> [config|systemd]   Edit config/systemd service file
watch   [monero|p2pool|xmrig]                         Watch live status or a specific process

tor                                                   Test Tor connection
rpc     [help]                                        Send a RPC call to monerod
seed    [language]                                    Generate random 25-word Monero seed
list                                                  List wallets
size                                                  Show size of monero-bash folders
price                                                 Fetch price data from cryptocompare.com API
status                                                Print status of all installed packages
version                                               Print versions of installed packages

backup                                                Encrypt & backup [wallets] -> [backup.tar.gpg]
decrypt                                               Decrypt [backup.tar.gpg] -> [backup]

help                                                  Show this help message

Usage

Wallet

Wallet files are found in: ~/.monero-bash/wallets

To open the wallet menu, type: monero-bash. You will have 3 options:

  • Select Type a wallets name to open it
  • New Create a new wallet
  • Exit Exit the wallet menu

There is no built-in way to delete a wallet.
You'll have to manually remove the files inside the wallet folder:

rm ~/.monero-bash/wallets/MY_WALLET
rm ~/.monero-bash/wallets/MY_WALLET.keys

Config

Config files for all packages are in: ~/.monero-bash/config

monero-bash comes with pre-configured configuration files:

P2Pool does not have native support for a config file, so monero-bash uses its self-created p2pool.conf.

Processes that are started in the background (monero-bash start <process>) will also respect their config files.
For example: If you set MINI=true in p2pool.conf, monero-bash start p2pool will start P2Pool on the mini sidechain.


Mining

These instructions (and monero-bash itself) is built around running your own P2Pool, with XMRig pointed at it, click here for more info. However you can use any combination you'd like: only Monero, only P2Pool, etc.

Warning:

  • Wallet addresses are public on P2Pool! It is recommended to create a seperate mining wallet.
  • You are using your own nodes to mine. Both the Monero & P2Pool nodes have to be fully synced!

To start mining on P2Pool with XMRig:

  1. Install all the packages: monero-bash install all
  2. Configure basic mining settings: monero-bash config
  3. Start all processes in the background: monero-bash start all
  4. And watch them live with: monero-bash watch

Unfortunately, you cannot interact directly with a systemd background process so it may be useful to download screen or tmux so you can open multiple terminals and use:

monero-bash full <monero/p2pool/xmrig>

This allows you to interact with the processes directly AND have them in a background terminal.


Watch

To watch live status output:

monero-bash watch

Or a specific (background) process:

monero-bash watch <process>

Press the LEFT/RIGHT arrow keys to switch processes. To just print a static status page, you can:

monero-bash status

Security

Fun fact: Docker uses the exact same Linux namespace primitives as systemd, both are not VMs, both directly use the host kernel for "sandboxing".

Processes started with systemd aka monero-bash start will utilize systemd's security features. These are completely bypassed if you start processes directly with monero-bash full, you are relying on your own security measures in that instance.

Here are the options set in the service files:

PrivateTmp=yes               Mounts a private /tmp/ folder for the process
NoNewPrivileges=yes          The process (and its children) cannot escalate privileges
ProcSubset=pid               The process can only see its own /proc/ directory
RestrictRealtime=yes         Disallows realtime scheduling
RestrictNamespaces=true      Restricts access to Linux namespace functionality for the process
CapabilityBoundingSet=...    Controls certain system capabilities the process has
PrivateUsers=true            Creates a new user namespace for the executed processes
ProtectHostname=true         Creates a new UTS namespace for the executed process + disallows hostname changes
ProtectClock=...             Disallows changing the systems clock
ProtectKernelModules=...     Disallows loading kernel modules
ProtectKernelLogs=yes        Disallows accessing the kernel log ring buffer
ProtectProc=invisible        Processes owned by other users in /proc/ are hidden from the process
ProtectControlGroups=yes     /sys/fs/cgroup/ will be made read-only
ProtectKernelTunables=yes    Disallows changing kernel variables
ProtectSystem=strict         Mounts /usr/, /etc/, and /boot/ as read-only for the process
ProtectHome=read-only        Mounts /home/ as read-only for the process
BindPaths=...                Allows CERTAIN directories to be read from/written to

In the event of fatal process bugs like remote code execution, these settings will prevent or at the very least lessen the damage done.

Note: XMRig is ran as root for the MSR hashrate boost. Although it is still heavily restricted with these settings, they are not perfect. Unless you consider XMRig malware, you should be more concerned with programs that have much more realistic attack surfaces: constant internet-facing applications like Monero/P2Pool nodes, or any other software on your computer in the same vein.

Privacy

Tor

monero-bash supports routing all of its traffic through the Tor network. Options in monero-bash.conf:

USE_TOR                Enable connections via Tor
TEST_TOR               Run tests to make sure Tor works before making any connections
TOR_PROXY              Tor SOCKS proxy IP/port to use (default: 127.0.0.1:9050)
TOR_QUIET              Silence Tor set-up messages

torsocks is the backend library used to route the traffic through Tor, although it is not necessary to download, only access to a regular Tor SOCKS proxy is needed.

Quick setup guide for Tor (only for proxy purposes):

  • Debian/Ubuntu/Pop!_OS/Linux Mint
    sudo apt install tor
    sudo systemctl start tor.service
    
  • Arch Linux/Manjaro
    sudo pacman -S tor
    sudo systemctl start tor.service
    
  • Fedora
    sudo dnf install tor
    sudo systemctl start tor.service
    
  • Gentoo
    sudo emerge --ask net-vpn/tor
    sudo systemctl start tor.service
    

Things to note:

  • This ONLY affects monero-bash. This will not make your Monero node run through Tor, see monerod.conf & monero-wallet-cli.conf if you'd like to run Monero through Tor

  • If the torsocks shared object file is already detected on your computer: /usr/lib/x86_64-linux-gnu/torsocks/libtorsocks.so or /usr/lib/torsocks/libtorsocks.so, it will be used. If it isn't found (or even installed), monero-bash will use the one it comes with

  • The built-in shared object file is from torsocks v2.3.0 with a SHA256 hash of 91464358f1358e3dfbf3968fad81a4fff95d6f3ce0961a1ba1ae7054b6998159, this should match against Debian's APT version. You are free to replace it with your own (or just install torsocks), just make sure it is placed in the correct path: /usr/local/share/monero-bash/src/libtorsocks.so

  • The actual wrapper script /usr/bin/torsocks has been rewritten and modified to reflect monero-bash's use-case (remove macOS code, Tor shell, etc) and it will always be used over any system versions found

  • Tor will not be used for RPC calls to localhost/127.0.0.1/192.168.x.x


HTTP Spoofing

monero-bash has options to spoof the HTTP headers sent during connections such that you blend in with web-browsers. Options in monero-bash.conf:

FAKE_HTTP_HEADERS      Send random (weighted) browser-like HTTP headers instead of [Wget/VERSION]
TOR_BROWSER_MIMIC      Mimic the HTTP headers that [Tor browser] uses
ONLY_USER_AGENT        Only send a random [User-Agent] instead of all the normal HTTP headers
ONLY_WGET_CURL         Only use random [2016-2022] versions of Wget/Curl as the User-Agent
HTTP_HEADERS_VERBOSE   Print the HTTP headers selected before making a connection

Things to note:

  • Some HTTP header values are favored more instead of being purely randomly selected, e.g. English is weighted more than other languages

  • The list of fake HTTP headers can be found in plain-text at docs/fake_http_headers and the selection process in the source code at src/func/header.sh

  • Tor proxying must be enabled for TOR_BROWSER_MIMIC to work

  • ONLY_USER_AGENT & ONLY_WGET_CURL will always be enabled when sending a non-local RPC call

  • Fake HTTP headers will not used for RPC calls to localhost/127.0.0.1/192.168.x.x


Connections

For transparency, here's all the connections monero-bash makes:

Domain Why When Where
https://github.com Fetching metadata information on packages + Tar/hash/signature/key download monero-bash update, monero-bash upgrade download.sh eol.sh gpg.sh verify.sh version.sh
https://getmonero.org Tar/hash/signature/key download specifically for Monero (not hosted on GitHub) When upgrading Monero Same as above
https://cryptocompare.com XMR price data monero-bash price price.sh
https://torproject.com Test Tor connection + Get exit IP monero-bash tor or when using any internet-related command with TEST_TOR enabled torsocks.sh
RPC Monero RPC calls, the IP given in DAEMON_RPC_IP will be contacted monero-bash rpc rpc.sh
DNS DNS connections will usually be handled by your OS (or whatever custom DNS setup you have). If using Tor, the torsocks wrapper will route all DNS requests through the Tor network automatically Any internet-related command when DNS isn't already cached All of the above

FAQ

Where are packages downloaded from?

The latest versions are downloaded using the GitHub API.

VPN/Tor connections are often rate-limited by the API, if so, monero-bash will find the download link by filtering the HTML of the package's /releases/latest/ GitHub page.

Hashes for Monero are found here: https://www.getmonero.org/downloads/hashes.txt

Every other package hash is found on its GitHub page.


Where are PGP keys downloaded from?

Keys are pre-downloaded in: gpg/ HOWEVER, they are checked against the online versions before getting imported. If a difference is found, you'll be dropped into a selection menu to pick which key to trust. If this happens, please search around to see what caused the difference.

  • monero-bash 21958EE945980282FCB849C8D7483F6CA27D1B1D -> hinto-janai
  • Monero 81AC591FE9C4B65C5806AFC3F0AF4D462A0BDF92 -> binaryFate
  • P2Pool 1FCAAB4D3DC3310D16CBD508C47F82B54DA87ADF -> SChernykh
  • XMRig 9AC4CEA8E66E35A5C7CDDC1B446A53638BE94409 -> XMRig

Does monero-bash have dependencies?

No

If you have a mainstream Linux distro you already have everything needed:

  • bash v5+
  • wget
  • systemd
  • GNU core utilities
  • Linux core utilities (util-linux)

See Distro Coverage for more info.

Optional:

  • tor is obviously required if using monero-bash's Tor options
  • screen or tmux is nice to have for monero-bash full <process>

Can I cancel mid-upgrade?

Yes

monero-bash uses temporary folders until it's ready to swap binaries:

/tmp/monero-bash.XXXXXXXXX

If you cancel right as the software is being upgraded, monero-bash will swap back your old binaries, and clean up temporary files.

If you cancel after software is installed, but before the local state is updated, monero-bash will force update it and clean up.


How are packages upgraded?

Click here for an explanation on how monero-bash upgrades packages

To see detailed output when installing/upgrading, type:

monero-bash install/upgrade <package> verbose

Where is monero-bash installed?

Installation path:

/usr/local/share/monero-bash

Packages:

/usr/local/share/monero-bash/bin

PATH symlink:

/usr/local/bin/monero-bash

User folder:

~/.monero-bash

Config files:

~/.monero-bash/config

Wallets:

~/.monero-bash/wallets

systemd files:

/etc/systemd/systemd/monero-bash-$PACKAGE_NAME.service
/etc/systemd/system/multi-user.target.wants/monero-bash-$PACKAGE_NAME.service

Where are the fake HTTP headers sourced from?

A combination of this recent list on Github and the free listings on whatismybrowser.com. Their full list is behind a 50$ paywall...! Their free lists have 1000s of common User-Agents, but they do not provide an API or an easy way to scrape it cleanly, probably on purpose. If you know how to use grep/sed (or Python) though, then it's easy :)

The full list monero-bash uses (including more than just User-Agents) can be found in plain-text and Bash array form at docs/fake_http_headers and the selection process can be found in the source code at src/func/header.sh


Where are the [monero-bash seed] mnemonics sourced from?

The Monero GitHub repo.

Plain-text and Bash array versions of the seed mnemonics for all languages can be found in this repo at docs/seed or directly in the code at src/func/seed.sh