mirror of
https://github.com/rclone/rclone.git
synced 2024-11-27 02:34:21 +08:00
358 lines
11 KiB
Markdown
358 lines
11 KiB
Markdown
---
|
||
title: "Proton Drive"
|
||
description: "Rclone docs for Proton Drive"
|
||
versionIntroduced: "v1.64.0"
|
||
status: Beta
|
||
---
|
||
|
||
# {{< icon "fa fa-folder" >}} Proton Drive
|
||
|
||
[Proton Drive](https://proton.me/drive) is an end-to-end encrypted Swiss vault
|
||
for your files that protects your data.
|
||
|
||
This is an rclone backend for Proton Drive which supports the file transfer
|
||
features of Proton Drive using the same client-side encryption.
|
||
|
||
Due to the fact that Proton Drive doesn't publish its API documentation, this
|
||
backend is implemented with best efforts by reading the open-sourced client
|
||
source code and observing the Proton Drive traffic in the browser.
|
||
|
||
**NB** This backend is currently in Beta. It is believed to be correct
|
||
and all the integration tests pass. However the Proton Drive protocol
|
||
has evolved over time there may be accounts it is not compatible
|
||
with. Please [post on the rclone forum](https://forum.rclone.org/) if
|
||
you find an incompatibility.
|
||
|
||
Paths are specified as `remote:path`
|
||
|
||
Paths may be as deep as required, e.g. `remote:directory/subdirectory`.
|
||
|
||
## Configurations
|
||
|
||
Here is an example of how to make a remote called `remote`. First run:
|
||
|
||
rclone config
|
||
|
||
This will guide you through an interactive setup process:
|
||
|
||
```
|
||
No remotes found, make a new one?
|
||
n) New remote
|
||
s) Set configuration password
|
||
q) Quit config
|
||
n/s/q> n
|
||
name> remote
|
||
Type of storage to configure.
|
||
Choose a number from below, or type in your own value
|
||
[snip]
|
||
XX / Proton Drive
|
||
\ "Proton Drive"
|
||
[snip]
|
||
Storage> protondrive
|
||
User name
|
||
user> you@protonmail.com
|
||
Password.
|
||
y) Yes type in my own password
|
||
g) Generate random password
|
||
n) No leave this optional password blank
|
||
y/g/n> y
|
||
Enter the password:
|
||
password:
|
||
Confirm the password:
|
||
password:
|
||
Option 2fa.
|
||
2FA code (if the account requires one)
|
||
Enter a value. Press Enter to leave empty.
|
||
2fa> 123456
|
||
Remote config
|
||
--------------------
|
||
[remote]
|
||
type = protondrive
|
||
user = you@protonmail.com
|
||
pass = *** ENCRYPTED ***
|
||
--------------------
|
||
y) Yes this is OK
|
||
e) Edit this remote
|
||
d) Delete this remote
|
||
y/e/d> y
|
||
```
|
||
|
||
**NOTE:** The Proton Drive encryption keys need to have been already generated
|
||
after a regular login via the browser, otherwise attempting to use the
|
||
credentials in `rclone` will fail.
|
||
|
||
Once configured you can then use `rclone` like this,
|
||
|
||
List directories in top level of your Proton Drive
|
||
|
||
rclone lsd remote:
|
||
|
||
List all the files in your Proton Drive
|
||
|
||
rclone ls remote:
|
||
|
||
To copy a local directory to an Proton Drive directory called backup
|
||
|
||
rclone copy /home/source remote:backup
|
||
|
||
### Modified time
|
||
|
||
Proton Drive Bridge does not support updating modification times yet.
|
||
|
||
### Restricted filename characters
|
||
|
||
Invalid UTF-8 bytes will be [replaced](/overview/#invalid-utf8), also left and
|
||
right spaces will be removed ([code reference](https://github.com/ProtonMail/WebClients/blob/b4eba99d241af4fdae06ff7138bd651a40ef5d3c/applications/drive/src/app/store/_links/validation.ts#L51))
|
||
|
||
### Duplicated files
|
||
|
||
Proton Drive can not have two files with exactly the same name and path. If the
|
||
conflict occurs, depending on the advanced config, the file might or might not
|
||
be overwritten.
|
||
|
||
### [Mailbox password](https://proton.me/support/the-difference-between-the-mailbox-password-and-login-password)
|
||
|
||
Please set your mailbox password in the advanced config section.
|
||
|
||
### Caching
|
||
|
||
The cache is currently built for the case when the rclone is the only instance
|
||
performing operations to the mount point. The event system, which is the proton
|
||
API system that provides visibility of what has changed on the drive, is yet
|
||
to be implemented, so updates from other clients won’t be reflected in the
|
||
cache. Thus, if there are concurrent clients accessing the same mount point,
|
||
then we might have a problem with caching the stale data.
|
||
|
||
{{< rem autogenerated options start" - DO NOT EDIT - instead edit fs.RegInfo in backend/protondrive/protondrive.go then run make backenddocs" >}}
|
||
### Standard options
|
||
|
||
Here are the Standard options specific to protondrive (Proton Drive).
|
||
|
||
#### --protondrive-username
|
||
|
||
The username of your proton account
|
||
|
||
Properties:
|
||
|
||
- Config: username
|
||
- Env Var: RCLONE_PROTONDRIVE_USERNAME
|
||
- Type: string
|
||
- Required: true
|
||
|
||
#### --protondrive-password
|
||
|
||
The password of your proton account.
|
||
|
||
**NB** Input to this must be obscured - see [rclone obscure](/commands/rclone_obscure/).
|
||
|
||
Properties:
|
||
|
||
- Config: password
|
||
- Env Var: RCLONE_PROTONDRIVE_PASSWORD
|
||
- Type: string
|
||
- Required: true
|
||
|
||
#### --protondrive-2fa
|
||
|
||
The 2FA code
|
||
|
||
The value can also be provided with --protondrive-2fa=000000
|
||
|
||
The 2FA code of your proton drive account if the account is set up with
|
||
two-factor authentication
|
||
|
||
Properties:
|
||
|
||
- Config: 2fa
|
||
- Env Var: RCLONE_PROTONDRIVE_2FA
|
||
- Type: string
|
||
- Required: false
|
||
|
||
### Advanced options
|
||
|
||
Here are the Advanced options specific to protondrive (Proton Drive).
|
||
|
||
#### --protondrive-mailbox-password
|
||
|
||
The mailbox password of your two-password proton account.
|
||
|
||
For more information regarding the mailbox password, please check the
|
||
following official knowledge base article:
|
||
https://proton.me/support/the-difference-between-the-mailbox-password-and-login-password
|
||
|
||
|
||
**NB** Input to this must be obscured - see [rclone obscure](/commands/rclone_obscure/).
|
||
|
||
Properties:
|
||
|
||
- Config: mailbox_password
|
||
- Env Var: RCLONE_PROTONDRIVE_MAILBOX_PASSWORD
|
||
- Type: string
|
||
- Required: false
|
||
|
||
#### --protondrive-client-uid
|
||
|
||
Client uid key (internal use only)
|
||
|
||
Properties:
|
||
|
||
- Config: client_uid
|
||
- Env Var: RCLONE_PROTONDRIVE_CLIENT_UID
|
||
- Type: string
|
||
- Required: false
|
||
|
||
#### --protondrive-client-access-token
|
||
|
||
Client access token key (internal use only)
|
||
|
||
Properties:
|
||
|
||
- Config: client_access_token
|
||
- Env Var: RCLONE_PROTONDRIVE_CLIENT_ACCESS_TOKEN
|
||
- Type: string
|
||
- Required: false
|
||
|
||
#### --protondrive-client-refresh-token
|
||
|
||
Client refresh token key (internal use only)
|
||
|
||
Properties:
|
||
|
||
- Config: client_refresh_token
|
||
- Env Var: RCLONE_PROTONDRIVE_CLIENT_REFRESH_TOKEN
|
||
- Type: string
|
||
- Required: false
|
||
|
||
#### --protondrive-client-salted-key-pass
|
||
|
||
Client salted key pass key (internal use only)
|
||
|
||
Properties:
|
||
|
||
- Config: client_salted_key_pass
|
||
- Env Var: RCLONE_PROTONDRIVE_CLIENT_SALTED_KEY_PASS
|
||
- Type: string
|
||
- Required: false
|
||
|
||
#### --protondrive-encoding
|
||
|
||
The encoding for the backend.
|
||
|
||
See the [encoding section in the overview](/overview/#encoding) for more info.
|
||
|
||
Properties:
|
||
|
||
- Config: encoding
|
||
- Env Var: RCLONE_PROTONDRIVE_ENCODING
|
||
- Type: MultiEncoder
|
||
- Default: Slash,LeftSpace,RightSpace,InvalidUtf8,Dot
|
||
|
||
#### --protondrive-original-file-size
|
||
|
||
Return the file size before encryption
|
||
|
||
The size of the encrypted file will be different from (bigger than) the
|
||
original file size. Unless there is a reason to return the file size
|
||
after encryption is performed, otherwise, set this option to true, as
|
||
features like Open() which will need to be supplied with original content
|
||
size, will fail to operate properly
|
||
|
||
Properties:
|
||
|
||
- Config: original_file_size
|
||
- Env Var: RCLONE_PROTONDRIVE_ORIGINAL_FILE_SIZE
|
||
- Type: bool
|
||
- Default: true
|
||
|
||
#### --protondrive-app-version
|
||
|
||
The app version string
|
||
|
||
The app version string indicates the client that is currently performing
|
||
the API request. This information is required and will be sent with every
|
||
API request.
|
||
|
||
Properties:
|
||
|
||
- Config: app_version
|
||
- Env Var: RCLONE_PROTONDRIVE_APP_VERSION
|
||
- Type: string
|
||
- Default: "macos-drive@1.0.0-alpha.1+rclone"
|
||
|
||
#### --protondrive-replace-existing-draft
|
||
|
||
Create a new revision when filename conflict is detected
|
||
|
||
When a file upload is cancelled or failed before completion, a draft will be
|
||
created and the subsequent upload of the same file to the same location will be
|
||
reported as a conflict.
|
||
|
||
The value can also be set by --protondrive-replace-existing-draft=true
|
||
|
||
If the option is set to true, the draft will be replaced and then the upload
|
||
operation will restart. If there are other clients also uploading at the same
|
||
file location at the same time, the behavior is currently unknown. Need to set
|
||
to true for integration tests.
|
||
If the option is set to false, an error "a draft exist - usually this means a
|
||
file is being uploaded at another client, or, there was a failed upload attempt"
|
||
will be returned, and no upload will happen.
|
||
|
||
Properties:
|
||
|
||
- Config: replace_existing_draft
|
||
- Env Var: RCLONE_PROTONDRIVE_REPLACE_EXISTING_DRAFT
|
||
- Type: bool
|
||
- Default: false
|
||
|
||
#### --protondrive-enable-caching
|
||
|
||
Caches the files and folders metadata to reduce API calls
|
||
|
||
Notice: If you are mounting ProtonDrive as a VFS, please disable this feature,
|
||
as the current implementation doesn't update or clear the cache when there are
|
||
external changes.
|
||
|
||
The files and folders on ProtonDrive are represented as links with keyrings,
|
||
which can be cached to improve performance and be friendly to the API server.
|
||
|
||
The cache is currently built for the case when the rclone is the only instance
|
||
performing operations to the mount point. The event system, which is the proton
|
||
API system that provides visibility of what has changed on the drive, is yet
|
||
to be implemented, so updates from other clients won’t be reflected in the
|
||
cache. Thus, if there are concurrent clients accessing the same mount point,
|
||
then we might have a problem with caching the stale data.
|
||
|
||
Properties:
|
||
|
||
- Config: enable_caching
|
||
- Env Var: RCLONE_PROTONDRIVE_ENABLE_CACHING
|
||
- Type: bool
|
||
- Default: true
|
||
|
||
{{< rem autogenerated options stop >}}
|
||
|
||
## Limitations
|
||
|
||
This backend uses the
|
||
[Proton-API-Bridge](https://github.com/henrybear327/Proton-API-Bridge), which
|
||
is based on [go-proton-api](https://github.com/henrybear327/go-proton-api), a
|
||
fork of the [official repo](https://github.com/ProtonMail/go-proton-api).
|
||
|
||
There is no official API documentation available from Proton Drive. But, thanks
|
||
to Proton open sourcing [proton-go-api](https://github.com/ProtonMail/go-proton-api)
|
||
and the web, iOS, and Android client codebases, we don't need to completely
|
||
reverse engineer the APIs by observing the web client traffic!
|
||
|
||
[proton-go-api](https://github.com/ProtonMail/go-proton-api) provides the basic
|
||
building blocks of API calls and error handling, such as 429 exponential
|
||
back-off, but it is pretty much just a barebone interface to the Proton API.
|
||
For example, the encryption and decryption of the Proton Drive file are not
|
||
provided in this library.
|
||
|
||
The Proton-API-Bridge, attempts to bridge the gap, so rclone can be built on
|
||
top of this quickly. This codebase handles the intricate tasks before and after
|
||
calling Proton APIs, particularly the complex encryption scheme, allowing
|
||
developers to implement features for other software on top of this codebase.
|
||
There are likely quite a few errors in this library, as there isn't official
|
||
documentation available.
|