sia: finish documentation #4514

Also rename stuttering `--sia-sia-user-agent` to `--sia-user-agent`

backend/sia/sia.go

@@ -41,17 +41,19 @@ func init() {
 		NewFs:       NewFs,
 		Options: []fs.Option{{
 			Name: "api_url",
-			Help:     "Sia HTTP API URL\nLike http://127.0.0.1:9980",
+			Help: `Sia daemon API URL, like http://sia.daemon.host:9980.
-			Required: true,
+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",
+			Help: `Sia Daemon API Password.
-			Required:   false,
+Can be found in the apipassword file located in HOME/.sia/ or in the daemon directory.`,
 			IsPassword: true,
 		}, {
-			Name:     "sia_user_agent",
+			Name: "user_agent",
-			Help:     "Siad User Agent\nSia requires a 'Sia-Agent' user agent by default for security",
+			Help: `Siad User Agent
-			Required: false,
+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"`
 }
 

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/" >}}

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/)

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             | -         |

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"
 ---
 
-<i class="fa fa-globe"></i> 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
+Storage> sia
-** See help for sia backend at: https://rclone.org/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).
-Sia HTTP API URL
+Keep default if Sia daemon runs on localhost.
-Like http://127.0.0.1:9980
+Enter a string value. Press Enter for the default ("http://127.0.0.1:9980").
-Enter a string value. Press Enter for the default ("").
 api_url> http://127.0.0.1:9980
-Sia API Password
+Sia Daemon API Password.
-siad 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
+```
 
-
+{{< rem autogenerated options start" - DO NOT EDIT - instead edit fs.RegInfo in backend/sia/sia.go then run make backenddocs" >}}
-<!--- autogenerated options start - DO NOT EDIT, instead edit fs.RegInfo in backend/sia/sia.go then run make backenddocs -->
+### Standard options
-### Standard Options
 
 Here are the standard options specific to sia (Sia Decentralized Cloud).
 
 #### --sia-api-url
 
-Sia HTTP API URL
+Sia daemon API URL, like http://sia.daemon.host:9980.
-Like http://127.0.0.1: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
+Sia Daemon API Password.
-siad 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
+- Config:      user_agent
-- Env Var:     RCLONE_SIA_SIA_USER_AGENT
+- Env Var:     RCLONE_SIA_USER_AGENT
 - Type:        string
 - Default:     "Sia-Agent"
 
-<!--- autogenerated options stop -->
+#### --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

docs/layouts/chrome/navbar.html

@@ -95,6 +95,7 @@
           <a class="dropdown-item" href="/putio/"><i class="fas fa-parking"></i> put.io</a>
           <a class="dropdown-item" href="/seafile/"><i class="fa fa-server"></i> Seafile</a>
           <a class="dropdown-item" href="/sftp/"><i class="fa fa-server"></i> SFTP</a>
+          <a class="dropdown-item" href="/sia/"><i class="fa fa-globe"></i> Sia</a>
           <a class="dropdown-item" href="/sugarsync/"><i class="fas fa-dove"></i> SugarSync</a>
           <a class="dropdown-item" href="/tardigrade/"><i class="fas fa-dove"></i> Tardigrade</a>
           <a class="dropdown-item" href="/uptobox/"><i class="fa fa-archive"></i> Uptobox</a>