Skip to main content
Version: Pre-Release

Advanced CLI

Advanced Usage

Pulsar (previously Simple CLI or Subspace CLI) is the recommended way to farm on the Subspace Network. Follow the guide below to get started or check out the project README on GitHub.

I. Pre-requisites​

A. System Requirements​

Farming can be Network Intensive.

Make sure you have a stable network connection. During the plotting phase of farming, it can be network intensive.

This may impact your network usage so please check your network connection if you have a hard data limit.

HardwareSpecs
CPU4 Core+
RAM8GB+
SWAP4GB
Storage100GB SSD
SWAP Warning

A swap is only necessary if you have a low amount of RAM.

CoW Filesystems Warning

It is advised not to use the Subspace farmer and node on CoW file systems for any OS (ReFS, BTRFS, ZFS, bcachefs, HAMMER and some more).

If BTRFS is used with Subspace, the directory/whole file system must be CoW disabled with the following command prior to starting Subspace, because it only applies to newly created files.

Command to Disable CoW on BTRFS

sudo chattr +C path/to/data/dir

Alternatively, non-CoW file systems like ext4 or XFS can be used instead.

Redundancy

Using redundancy (RAID1/5/6, RAIDZ and others) on a filesystem with plot makes no sense, as the farmer uses checksums to verify the integrity of the plot, and is able to recover corrupted blocks if necessary in most cases. See scrub command below.

Filesystem chunk size

Creating a filesystem with a chunk (sunit) size of 32KB can prevent data fragmentation and improve performance, since the farmer operates on ~32KB chunks.

XFS

sudo mkfs.xfs -d su=32k,sw=1 /path/to/dev

Then use largeio and swalloc mount options.

ext4

sudo mkfs.ext4 -E stride=8,stripe-width=8 /path/to/dev

You can change these settings for an existing file system:

sudo tune2fs -E stride=8,stripe-width=8 /path/to/dev

B. Crypto Wallet​

Before running anything you need to have a wallet where you'll receive testnet coins. There are currently two wallets we suggest using, SubWallet being the preferred route.

Install one of the two wallets above into your browser and create a new account there. The address of your account will be necessary at the last step.

For help refer to our forum post How to setup Subwallet & a Polkadot.js Wallet

  • make sure to follow the Bonus section of the bottom of the post above.

C. Required ports​

Currently, a few ports need to be exposed for node to work properly.

If you have a server with no firewall, there is nothing to be done, but otherwise make sure to open the following TCP ports for incoming connections.

  • 30333
  • 30433
  • 30533

On the desktop side if you have a router in front of your computer, you'll need to forward TCP ports to the machine on which your node is running (how this is done varies from router to router, but there is always a feature like this, refer to How to Forward Ports for a more in-depth tutorial). If you're connected directly without any router, then again nothing needs to be done in such case.

II. Installation​

Looking for all Releases?

You can always find these executables in the Releases section on our GitHub

We will be downloading two files for your respective operating system.

  1. Subspace-Node - This is the executable that actually makes the connection with the Subspace Network
  2. Subspace-Farmer - This is the executable that will actually farm for rewards on your allocated storage plot.
  • Those using Docker will not have to download anything, just configure the docker-compose.yaml

  1. Input your parameters in the provided form and click Generate. Don't forget to specify your reward address instead of a default one!

    Docker Compose File Generator

    docker-compose.yaml

  2. Copy the generated docker-compose.yaml file.

  3. Create the subspace directory and the docker-compose.yaml file in it. Paste the output from the generator into the file.

  4. Now go to directory with docker-compose.yaml and type docker compose up -d to start everything

    You can read logs with docker compose logs --tail=1000 -f, for the rest read Docker Compose CLI reference.

III. Post Node & Farmer Install Care​

Now that your Node & Farmer have been started you will wait for the node to sync and the farmer to complete the initial plotting. While this is occurring you can check out some of the helpful resources below.

- Telemetry Server

- Block Explorer

Using a Custom Path​

You can set a custom path for your node & farmer to use if you want to use an external hard drive, or set a custom path from the default. You can set the node and farmer to different directories if you would like.

Set Node Custom Path.​

To set your node to use a custom path all you will need to do is add the --base-path parameter.

# start node and store data in `NODE_DATA_PATH` instead of default location
./NODE_FILE_NAME --base-path NODE_DATA_PATH --chain gemini-3f ...`

Switching to a new snapshot from older/different versions of Subspace​

info

Unless specifically mentioned by the Development team you should NOT have to wipe & purge your configuration on new releases.

In general you should be able to download the latest release, and re-start the Node & Farmer with the same commands as you started to prior version with no errors.

There are some cases where version updates will cause issue with your Node & Farmer and you may have to wipe & purge your node, typically when errors occur. If you have any issues you can always check our Forums and hop in our Discord Server to ask for help.

Wipe & Purge​

If you were running a node previously, and want to switch to a new snapshot, please perform these steps and then follow the guideline again:

# Replace `FARMER_FILE_NAME` with the name of the node file you downloaded from releases
./FARMER_FILE_NAME wipe PATH_TO_FARM
# Replace `NODE_FILE_NAME` with the name of the node file you downloaded from releases
./NODE_FILE_NAME purge-chain --chain gemini-3f

Does not matter if the node/farmer executable is the previous one or from the new snapshot, both will work :) The reason we require this is, with every snapshot change, the network might get partitioned, and you may be on a different genesis than the current one. In plain English, these commands are like a reset button for snapshot changes.

Now follow installation guide.

Docker Wipe & Purge​

In case of Docker setup run docker compose down -v (and manually delete custom directories if you have specified them).

Now follow installation guide.

Help​

There are extra commands and parameters you can use on farmer or node, use the --help after any other command to display additional options.

# Replace `FARMER_FILE_NAME` with the name of the node file you downloaded from releases
./FARMER_FILE_NAME farm --help

IV. Advanced​

Helpful commands examples​

  • ./FARMER_FILE_NAME info PATH_TO_FARM : show information about the farm at PATH_TO_FARM
  • ./FARMER_FILE_NAME scrub PATH_TO_FARM : Scrub the farm to find and fix farm at PATH_TO_FARM corruption
  • ./FARMER_FILE_NAME wipe PATH_TO_FARM : erases everything related to farmer if data were stored in PATH_TO_FARM
  • ./NODE_FILE_NAME --base-path NODE_DATA_PATH --chain gemini-3f ... : start node and store data in NODE_DATA_PATH instead of default location
  • ./NODE_FILE_NAME purge-chain --base-path NODE_DATA_PATH --chain gemini-3f : erases data related to the node if data were stored in NODE_DATA_PATH

Support for multiple disks​

Farm path and size you have seen above can be specified more than once to engage multiple disks. It is recommended to specify multiple disks explicitly rather than using RAID for better hardware utilization and efficiency.

Example:

./FARMER_FILE_NAME farm --reward-address WALLET_ADDRESS \
    path=/media/ssd1,size=100GiB \
    path=/media/ssd2,size=10T \
    path=/media/ssd3,size=10T

Build from source (Linux)​

If you're running unsupported Linux distribution or CPU architecture, you may try to build binaries yourself from source.

NOTE: This is primarily targeted at tech-savvy users and not recommended unless you know what you're doing. Please try to find answer to your question online before reaching out to maintainers.

You'll have to have Rust toolchain installed as well as LLVM, Clang and CMake in addition to usual developer tooling (Ubuntu example):

sudo apt-get install llvm clang cmake
LLVM + Clang 16

The build with LLVM + Clang 16 ends with UnknownOpcode(192) error due to breaking changes concerning WASM in LLVM 16. You can read more about this issue here. At this point, the solution is to use LLVM + Clang 15 and add the -Z build-std flag to the cargo build command.

Now clone the source and build snapshot snapshot-2023-aug-18 (replace occurrences with the snapshot you want to build):

git clone https://github.com/subspace/subspace.git
cd subspace
git checkout snapshot-2023-aug-18
cargo build \
    --profile production \
    --bin subspace-node \
    --bin subspace-farmer

You'll find two binaries under target/production directory once it succeeds, after which refer to instructions above on how to use them.

V. Having Trouble?​

If you are having some issues with running the node or the farmer for the subspace network, feel free to join our Discord or even better you can take a look at our Forums and review and existing questions or post a new one if needed!

- Forums​

- Discord​

Enable Rust Backtrace​

When running the Subspace Network Farmer & Node, sometimes you may encounter an error message that includes a line similar to the following:

Backtrace omitted. Run with RUST_BACKTRACE=1 environment variable to display it.

This error message means that Rust (the programming language that Subspace Network Farmer & Node is written in) has encountered a problem and has provided a diagnostic backtrace that can help diagnose the issue. However, by default, the backtrace is not displayed. To see the backtrace, you need to enable the RUST_BACKTRACE environment variable.

In this section, we will show you how to enable the RUST_BACKTRACE environment variable on Linux, macOS, and Windows (PowerShell).

Enabling RUST_BACKTRACE on Windows (PowerShell)​

To enable the RUST_BACKTRACE environment variable on Windows using PowerShell, follow these steps:

  1. Open a PowerShell window.

  2. Type the following command:

    $Env:RUST_BACKTRACE=1

  3. Press Enter.

  4. After exporting the environment variable, run the Subspace Network Farmer & Node as usual, and any errors encountered will display the backtrace.