From 6d02530f9dcc7e29a935251880fee47a8e9c83b1 Mon Sep 17 00:00:00 2001 From: Ivan Andreev Date: Sun, 10 Oct 2021 15:24:23 +0300 Subject: [PATCH] sia: finish documentation #4514 Also rename stuttering `--sia-sia-user-agent` to `--sia-user-agent` --- backend/sia/sia.go | 22 ++-- docs/content/_index.md | 1 + docs/content/docs.md | 1 + docs/content/overview.md | 1 + docs/content/sia.md | 176 +++++++++++++++++++++----------- docs/layouts/chrome/navbar.html | 1 + 6 files changed, 132 insertions(+), 70 deletions(-) diff --git a/backend/sia/sia.go b/backend/sia/sia.go index 2d114ce82..10a14c1b9 100644 --- a/backend/sia/sia.go +++ b/backend/sia/sia.go @@ -40,18 +40,20 @@ func init() { Description: "Sia Decentralized Cloud", NewFs: NewFs, Options: []fs.Option{{ - Name: "api_url", - Help: "Sia HTTP API URL\nLike http://127.0.0.1:9980", - Required: true, + Name: "api_url", + Help: `Sia daemon API URL, like http://sia.daemon.host:9980. +Note that siad must run with --disable-api-security to open API port for other hosts (not recommended). +Keep default if Sia daemon runs on localhost.`, + Default: "http://127.0.0.1:9980", }, { - Name: "api_password", - Help: "Sia API Password\nsiad API Password", - Required: false, + Name: "api_password", + Help: `Sia Daemon API Password. +Can be found in the apipassword file located in HOME/.sia/ or in the daemon directory.`, IsPassword: true, }, { - Name: "sia_user_agent", - Help: "Siad User Agent\nSia requires a 'Sia-Agent' user agent by default for security", - Required: false, + Name: "user_agent", + Help: `Siad User Agent +Sia daemon requires the 'Sia-Agent' user agent by default for security`, Default: "Sia-Agent", Advanced: true, }, { @@ -73,7 +75,7 @@ func init() { type Options struct { APIURL string `config:"api_url"` APIPassword string `config:"api_password"` - UserAgent string `config:"sia_user_agent"` + UserAgent string `config:"user_agent"` Enc encoder.MultiEncoder `config:"encoding"` } diff --git a/docs/content/_index.md b/docs/content/_index.md index 7024ee440..8ea1dbdb3 100644 --- a/docs/content/_index.md +++ b/docs/content/_index.md @@ -149,6 +149,7 @@ WebDAV or S3, that work out of the box.) {{< provider name="Seafile" home="https://www.seafile.com/" config="/seafile/" >}} {{< provider name="SeaweedFS" home="https://github.com/chrislusf/seaweedfs/" config="/s3/#seaweedfs" >}} {{< provider name="SFTP" home="https://en.wikipedia.org/wiki/SSH_File_Transfer_Protocol" config="/sftp/" >}} +{{< provider name="Sia" home="https://sia.tech/" config="/sia/" >}} {{< provider name="StackPath" home="https://www.stackpath.com/products/object-storage/" config="/s3/#stackpath" >}} {{< provider name="SugarSync" home="https://sugarsync.com/" config="/sugarsync/" >}} {{< provider name="Tardigrade" home="https://tardigrade.io/" config="/tardigrade/" >}} diff --git a/docs/content/docs.md b/docs/content/docs.md index a1ee45970..f60b79a73 100644 --- a/docs/content/docs.md +++ b/docs/content/docs.md @@ -62,6 +62,7 @@ See the following for detailed instructions for * [QingStor](/qingstor/) * [Seafile](/seafile/) * [SFTP](/sftp/) + * [Sia](/sia/) * [SugarSync](/sugarsync/) * [Tardigrade](/tardigrade/) * [Union](/union/) diff --git a/docs/content/overview.md b/docs/content/overview.md index b9e758852..ca2daf23a 100644 --- a/docs/content/overview.md +++ b/docs/content/overview.md @@ -46,6 +46,7 @@ Here is an overview of the major features of each cloud storage system. | QingStor | MD5 | No | No | No | R/W | | Seafile | - | No | No | No | - | | SFTP | MD5, SHA1 ² | Yes | Depends | No | - | +| Sia | - | No | No | No | - | | SugarSync | - | No | No | No | - | | Tardigrade | - | Yes | No | No | - | | Uptobox | - | No | No | Yes | - | diff --git a/docs/content/sia.md b/docs/content/sia.md index a09780a54..edc76d410 100644 --- a/docs/content/sia.md +++ b/docs/content/sia.md @@ -1,17 +1,63 @@ --- title: "Sia" -description: "Rclone docs for Sia" +description: "Remote for Sia Decentralized Cloud" date: "2019-10-02" --- - Sia ------------------------------------------ +# {{< icon "fa fa-globe" >}} Sia -Sia is the [Sia Decentralized Cloud](https://sia.tech/). +Sia ([sia.tech](https://sia.tech/)) is a decentralized cloud storage platform +based on the [blockchain](https://wikipedia.org/wiki/Blockchain) technology. +With rclone you can use it like any other remote filesystem or mount Sia folders +locally. The technology behind it involves a number of new concepts such as +Siacoins and Wallet, Blockchain and Consensus, Renting and Hosting, and so on. +If you are new to it, you'd better first familiarize yourself using their +excellent [support documentation](https://support.sia.tech/). -You will need to be running a copy of Sia-UI or siad, locally or on your LAN (e.g. a NAS). Sia's HTTP API is required and typically listens on port 9980. +## Introduction -Here is an example of how to make a remote called `remote`. First run: +Before you can use rclone with Sia, you will need to have a running copy of +`Sia-UI` or `siad` (the Sia daemon) locally on your computer or on local +network (e.g. a NAS). Please follow the [Get started](https://sia.tech/get-started) +guide and install one. + +rclone interacts with Sia network by talking to the Sia daemon via [HTTP API](https://sia.tech/docs/) +which is usually available on port _9980_. By default you will run the daemon +locally on the same computer so it's safe to leave the API password blank +(the API URL will be `http://127.0.0.1:9980` making external access impossible). + +However, if you want to access Sia daemon running on another node, for example +due to memory constraints or because you want to share single daemon between +several rclone and Sia-UI instances, you'll need to make a few more provisions: +- Ensure you have _Sia daemon_ installed directly or in + a [docker container](https://github.com/SiaFoundation/siad/pkgs/container/siad) + because Sia-UI does not support this mode natively. +- Run it on externally accessible port, for example provide `--api-addr :9980` + and `--disable-api-security` arguments on the daemon command line. +- Enforce API password for the `siad` daemon via environment variable + `SIA_API_PASSWORD` or text file named `apipassword` in the daemon directory. +- Set rclone backend option `api_password` taking it from above locations. + + +Notes: +1. If your wallet is locked, rclone cannot unlock it automatically. + You should either unlock it in advance by using Sia-UI or via command line + `siac wallet unlock`. + Alternatively you can make `siad` unlock your wallet automatically upon + startup by running it with environment variable `SIA_WALLET_PASSWORD`. +2. If `siad` cannot find the `SIA_API_PASSWORD` variable or the `apipassword` file + in the `SIA_DIR` directory, it will generate a random password and store in the + text file named `apipassword` under `YOUR_HOME/.sia/` directory on Unix + or `C:\Users\YOUR_HOME\AppData\Local\Sia\apipassword` on Windows. + Remember this when you configure password in rclone. +3. The only way to use `siad` without API password is to run it **on localhost** + with command line argument `--authorize-api=false`, but this is insecure and + **strongly discouraged**. + +## Configuration + +Here is an example of how to make a `sia` remote called `mySia`. +First, run: rclone config @@ -23,118 +69,128 @@ n) New remote s) Set configuration password q) Quit config n/s/q> n -name> remote +name> mySia Type of storage to configure. Enter a string value. Press Enter for the default (""). Choose a number from below, or type in your own value ... 29 / Sia Decentralized Cloud \ "sia" -30 / Transparently chunk/split large files - \ "chunker" -31 / Union merges the contents of several remotes - \ "union" ... -Storage> 29 -** See help for sia backend at: https://rclone.org/sia/ ** - -Sia HTTP API URL -Like http://127.0.0.1:9980 -Enter a string value. Press Enter for the default (""). +Storage> sia +Sia daemon API URL, like http://sia.daemon.host:9980. +Note that siad must run with --disable-api-security to open API port for other hosts (not recommended). +Keep default if Sia daemon runs on localhost. +Enter a string value. Press Enter for the default ("http://127.0.0.1:9980"). api_url> http://127.0.0.1:9980 -Sia API Password -siad API Password +Sia Daemon API Password. +Can be found in the apipassword file located in HOME/.sia/ or in the daemon directory. y) Yes type in my own password g) Generate random password -n) No leave this optional password blank +n) No leave this optional password blank (default) y/g/n> y Enter the password: password: Confirm the password: password: -Edit advanced config? (y/n) +Edit advanced config? y) Yes -n) No +n) No (default) y/n> n -Remote config -------------------- -[remote] +[mySia] type = sia api_url = http://127.0.0.1:9980 api_password = *** ENCRYPTED *** -------------------- -y) Yes this is OK +y) Yes this is OK (default) e) Edit this remote d) Delete this remote y/e/d> y -Current remotes: - -Name Type -==== ==== -remote sia - -e) Edit existing remote -n) New remote -d) Delete remote -r) Rename remote -c) Copy remote -s) Set configuration password -q) Quit config -e/n/d/r/c/s/q> q ``` -Once configured you can then use `rclone` like this, +Once configured, you can then use `rclone` like this: -List directories in top level of your Sia storage +- List directories in top level of your Sia storage - rclone lsd remote: +``` +rclone lsd mySia: +``` -List all the files in your Sia storage +- List all the files in your Sia storage - rclone ls remote: +``` +rclone ls mySia: +``` -To copy a local directory to an Sia directory called backup +- Upload a local directory to the Sia directory called _backup_ - rclone copy /home/source remote:backup +``` +rclone copy /home/source mySia:backup +``` - - -### Standard Options +{{< rem autogenerated options start" - DO NOT EDIT - instead edit fs.RegInfo in backend/sia/sia.go then run make backenddocs" >}} +### Standard options Here are the standard options specific to sia (Sia Decentralized Cloud). #### --sia-api-url -Sia HTTP API URL -Like http://127.0.0.1:9980 +Sia daemon API URL, like http://sia.daemon.host:9980. +Note that siad must run with --disable-api-security to open API port for other hosts (not recommended). +Keep default if Sia daemon runs on localhost. - Config: api_url - Env Var: RCLONE_SIA_API_URL - Type: string -- Default: "" +- Default: "http://127.0.0.1:9980" #### --sia-api-password -Sia API Password -siad API Password +Sia Daemon API Password. +Can be found in the apipassword file located in HOME/.sia/ or in the daemon directory. + +**NB** Input to this must be obscured - see [rclone obscure](/commands/rclone_obscure/). - Config: api_password - Env Var: RCLONE_SIA_API_PASSWORD - Type: string - Default: "" -### Advanced Options +### Advanced options Here are the advanced options specific to sia (Sia Decentralized Cloud). -#### --sia-sia-user-agent +#### --sia-user-agent Siad User Agent -Sia requires a 'Sia-Agent' user agent by default for security +Sia daemon requires the 'Sia-Agent' user agent by default for security -- Config: sia_user_agent -- Env Var: RCLONE_SIA_SIA_USER_AGENT +- Config: user_agent +- Env Var: RCLONE_SIA_USER_AGENT - Type: string - Default: "Sia-Agent" - +#### --sia-encoding + +This sets the encoding for the backend. + +See: the [encoding section in the overview](/overview/#encoding) for more info. + +- Config: encoding +- Env Var: RCLONE_SIA_ENCODING +- Type: MultiEncoder +- Default: Slash,Question,Hash,Percent,Del,Ctl,InvalidUtf8,Dot + +{{< rem autogenerated options stop >}} + +## Limitations + +- Modification times not supported +- Checksums not supported +- `rclone about` not supported +- rclone can work only with _Siad_ or _Sia-UI_ at the moment, + the **SkyNet daemon is not supported yet.** +- Sia does not allow control characters or symbols like question and pound + signs in file names. rclone will transparently [encode](/overview/#encoding) + them for you, but you'd better be aware diff --git a/docs/layouts/chrome/navbar.html b/docs/layouts/chrome/navbar.html index 2c4533cd1..aeeef6e07 100644 --- a/docs/layouts/chrome/navbar.html +++ b/docs/layouts/chrome/navbar.html @@ -95,6 +95,7 @@ put.io Seafile SFTP + Sia SugarSync Tardigrade Uptobox