Skip to content

Home

Jump to bottom
Christopher Schinnerl edited this page Apr 18, 2023 · 12 revisions

Welcome to the renterd wiki, a collection of information about renterd and how to use it to rent storage on the Sia network.

This wiki is a WIP and will be extended over time as renterd evolves.

About renterd

The Sia network is a distributed marketplace of cloud storage where hosts sell their disk space and renters can rent it using a token called Siacoin. The software renters use to get access to that marketplace is called renterd. The d stands for daemon, a term used for software running as a background process on a server. While running, renterd serves an http API that can be used to upload files to the Sia network and download them. Software that wants to use Sia as a backend consumes this API similar to how it would use the API of other storage providers. The actual upload/download of files to/from the network is then handled by renterd.

We recommend that you first check out the learning material on our website to get a high level overview of how Sia works before diving into renterd. If you know how to run renterd already and want to get started building right away take a look at the API docs.

Table of Contents

Getting started with renterd

In this section we walk you through setting up and running an instance of renterd.

Setup

First we need to install renterd. Right now this can be done using any of the following ways:

Downloading the Binary

At this time renterd binaries are not yet available on the website. But you can download recent binaries from the build artifacts on GitHub.

You can find all build artifacts here. The "Publish" tab contains mainnet binaries and the "Zen Testnet" tab contains testnet binaries. We generally recommend using recent artifacts from runs marked stable.

Building from Source

# Clone the repository
git clone https://github.com/SiaFoundation/renterd.git
cd renterd

# (Optional) Check out the stable branch
git checkout stable

# Build the binary. If you want to use the production network drop the '-tags="testnet"'
go build -tags="testnet" -o ./ ./...

Using Docker

We also host official docker images. At this time we automatically build master, stable, master-testnet and stable-testnet images.

e.g. you can run renterd with the following command assuming you already have a seed. Continue reading to find out how to obtain a seed.

docker run -d --name renterd -e RENTERD_API_PASSWORD="<PASSWORD>" -e RENTERD_SEED="<SEED>" -p 127.0.0.1:9880:9880/tcp -p :9881:9981/tcp ghcr.io/siafoundation/renterd:stable-testnet

Starting the Renter

The next step is creating a seed. The seed needs to be kept secret at all times. This should return something like the following output. (NOTE: The seed is only an example and is not meant to be used. Use the one from your own output)

./renterd seed

Output:

renterd v0.1.0
Network Testnet-Zen
Seed phrase: impulse paper myself burden elegant adapt lyrics cruel cargo warrior body claim

Finally we are ready to launch renterd with the following command. You can choose any API password you'd like. For the seed, provide the one that you received from the previous command.

./renterd

Output:

renterd v0.1.0
Network Testnet-Zen
Enter API password: 
Enter wallet seed: 
api: Listening on 127.0.0.1:9880
bus: Listening on localhost:9881

Congrats! You now have a running instance of renterd that is connected to the Zen Testnet. If you go to http://localhost:9880 in your browser and enter your API password you should see the renterd UI. For the sake of completeness we are going to explain the remaining steps both the CLI as well as the UI way.

After starting renterd, you can follow its initial blockchain syncing progress through the Blockchain node tab in the UI or using the /consensus/state endpoint like this:

curl -u ":yourapipassword" --location 'localhost:9880/api/bus/consensus/state'

Response:

{
	"BlockHeight": 13109,
	"Synced": true
}

Incoming transactions won't be reflected in the wallet's balance before the consensus state is considered "synced".

Next, we need to get some Zen-Siacoins to fund renterd's wallet. Otherwise it won't be able to form file contracts to upload data to. To do so we need to get an address first which we can do using the right endpoint.

curl -u ":yourapipassword" --location 'localhost:9880/api/bus/wallet/address'

Response.

"addr:c0d6af1cfc0bc5fb9d53ee58781a9677f572202e3bfa2a53df2ae545115fea843ea9745bd5ea"

Alternatively go to the wallet tab in the UI and click the "receive" button on the top right to get your address.

Then head over to the official Testnet Faucet and request 10,000 or so Siacoins for your address. NOTE: Remove the addr: prefix and surrounding quotes if you used the CLI to get your address. Otherwise you'll receive an error.

It will take some time for that transaction to be mined but once it is, we can ask the wallet for its balance. The number returned by the endpoint represents Hastings, the smallest unit of value in the Sia ecosystem. 1 Siacoin equals 10^24 Hastings.

curl -u ":yourapipassword" --location 'localhost:9880/api/bus/wallet/balance'

Response:

"10000000000000000000000000000"

In the UI the balance should update in the wallet tab.

Forming contracts

For renterd to actually start forming contracts automatically, we need to configure the autopilot. The autopilot is responsible for keeping renterd operational given its configuration. In the UI, the settings can be found in the autopilot tab. If you are using the CLI, you can view the current configuration using the corresponding endpoint:

curl -u ":asdf" --location 'localhost:9880/api/autopilot/config'

Response:

{
	"wallet": {
		"defragThreshold": 0
	},
	"hosts": {
		"ignoreRedundantIPs": false,
		"maxDowntimeHours": 0,
		"scoreOverrides": null
	},
	"contracts": {
		"set": "",
		"amount": 0,
		"allowance": "0",
		"period": 0,
		"renewWindow": 0,
		"download": 0,
		"upload": 0,
		"storage": 0
	}
}

The following are some sane settings you can use on the Zen testnet.

  • "defragThreshold": 1000 Siacoin outputs before the wallet is defragmented
  • "ignoreRedundantIPs": true on testnet, otherwise false
  • "maxDownTimeHours": 1 week of downtime before hosts get ignored
  • "scoreOverrides": {} -> no manual overrides
  • "set": "autopilot" -> name of the contract set used by the autopilot
  • "amount": 30 -> keep a set of 30 contracts
  • "allowance": 1000 Siacoins
  • "period": 6 week contract periods before they expire
  • "renewWindow": 2 weeks before the end of a contract period we start renewing them
  • "download": 10 GB of expected downloads per period
  • "upload": 10 GB of expected uploads per period
  • "storage": 10 GB of expected stored data per period

You can either use the UI to set these or run the following command from your CLI.

curl -u ":yourpassword" --location --request PUT 'localhost:9880/api/autopilot/config' \
--data '{
    "wallet": {
        "defragThreshold": 1000
    },
    "hosts": {
        "ignoreRedundantIPs": false,
        "maxDowntimeHours": 168,
        "scoreOverrides": {}
    },
    "contracts": {
        "set": "autopilot",
        "amount": 30,
        "allowance": "1000000000000000000000000000", 
        "period": 6048,                              
        "renewWindow": 2016,
        "download": 10000000000,
        "upload": 10000000000,
        "storage": 10000000000 
    }
}'

After updating the autopilot settings, the autopilot will start forming contracts. Eventually it will have formed 30 contracts. You can check the progress in either the UI's contracts tab or via the following command:

curl -u ":asdf" --location 'localhost:9880/api/bus/contracts/active'

Uploading and Downloading

Before starting to upload data to the testnet, we recommend changing the redundancy settings used for uploads. You can either do that in the configuration tab of the UI or via the following command. It sets the total hosts used for an upload to 3 since the testnet has fewer hosts than the mainnet.

curl -u ":yourpassword" --location --request PUT 'localhost:9880/api/bus/setting/redundancy' \
--data '{
    "minShards": 1,            
    "totalShards": 3                            
}'

Afterwards we are ready to upload our first file. The easiest way to upload and download is via the UI's files tab. Alternatively you can use the following commands to upload a file to the path /foo.txt which contains the string Hello World!.

curl -u ":yourpassword" --location --request PUT 'localhost:9880/api/worker/objects/foo.txt' --header "Content-Type: application/octet-stream" --data-binary 'Hello World!'

Upon success, you can download the file again:

curl -u ":asdf" localhost:9880/api/worker/objects/foo.txt

Response

Hello World!%
Clone this wiki locally