Store backups in Dropbox

This is how you set up your Dropbox as a target for your backups. You do not enter a password: you sign in at Dropbox, give your consent there and come back to the “Targets” page.

What you need

• a Dropbox account with enough free space for your backups,
• a website whose admin area can be reached via https://,
• the PHP extension cURL with https on the web server.

If the web server lacks cURL, Dropbox is greyed out in the selection of the target types and carries the label Not available on this server.

Step 1: Choose the target type

Open the Targets page and click Add target. Choose Dropbox.

1. Name is up to you. The plugin suggests “Dropbox 1”; any name that is not in use yet works.
2. The note on the sign-in says that you will be redirected to Dropbox and come back to this page afterwards, and that the service auth.cloneworx.de brokers the sign-in.
3. The note of the target type says that the plugin gets its own folder under “Apps” in your Dropbox and sees nothing else, and that deleted backups can still be restored in Dropbox for a while.
4. The button Connect with Dropbox starts the sign-in.

The form has no field for a password, no field for a folder and no button Test connection: a target of the type Dropbox only comes into being with the sign-in, and its location is the folder that Dropbox keeps for the app.

Step 2: Connect with Dropbox

Click Connect with Dropbox. Your browser leaves the Targets page:

1. Sign in at Dropbox and give your consent.
2. After that, the service auth.cloneworx.de shows a page that names the website to which the access is handed over. Only continue if that is your website.
3. Your browser comes back to the Targets page. There it briefly says Finishing the sign-in …

The plugin saves the target, tests the connection at once and reports the result: “…” saved and connected. You do not have to save any more.

1. All targets are connected.
2. The message names the target: saved and connected.
3. The new target is in the list. The green dot means: connected.
4. The location of the target is the address of the connected Dropbox account.

A sign-in that has been started is valid for 15 minutes. Plans and backups use a target only after a successful connection test.

If the plugin finds backups in your Dropbox that are not in your list, the tile Backups found at “…” appears. More about this: Find backups again after a total loss.

Step 3: Choose the target in the backup plan

• Your first target: The plugin creates the plan “Daily backup”: daily at a random time, everything, this target, Max. backups 7. The plan is paused until you switch it on.
• Another target: Choose it on the Backup page in the tile Backup plans in a plan. The free version allows two plans and one target per plan.

More about this: Schedule backups automatically.

When the sign-in does not work

If you come back from Dropbox without access, no target is created. The Targets page reports the reason, and the form opens again with your entries.

1. The message says: Dropbox reports that access was not granted. Nothing was connected.
2. The form is open again, with your entries.
3. The button Connect with Dropbox starts the sign-in again.

Message	What to do
Connecting needs https: the address of the admin area of this website does not begin with https.	The message is shown in the form before the browser leaves the page. The sign-in service hands over an access only to a website whose admin area can be reached via https://. Switch the website to https.
The sign-in was cancelled. Nothing was connected.	This is information, not an error. Click Connect with Dropbox once more if you want to set up the target.
… reports that access was not granted. Nothing was connected.	Start the sign-in again and give your consent at Dropbox.
… did not grant all the permissions that the backup needs. Nothing was connected.	The plugin needs all four permissions, see the section “What the plugin may see in Dropbox”. Start the sign-in again.
This sign-in is unknown or has expired. Please connect again.	Here the form does not open again. Click Add target and start again.
The sign-in took too long or was already used. Please connect again.	Start the sign-in again.
The sign-in service cannot be reached at the moment. Please try again later.	Try again later. Below the message, Show log leads to the general log.
… cannot be reached at the moment or reports an error. Please try again later.	The message names Dropbox. Try again later. Here too, Show log leads to the general log.
The sign-in worked, but the first access to the account failed: …	The reason follows the colon. Start the sign-in again once it is resolved.

What the plugin may see in Dropbox

At Dropbox the app has the access type “App folder”: the plugin sees its own folder under “Apps” in your Dropbox and nothing else. Dropbox sets the name of this folder. The plugin does not see any other file in your Dropbox.

The plugin asks Dropbox for four permissions:

Permission	What for
account_info.read	read the address and the space of the account
files.metadata.read	list the files in its folder
files.content.read	read the files in its folder
files.content.write	write files into its folder

The backups are stored in your Dropbox under Apps/<app name>/cloneworx-backup-<code>/<backup>/. Structure and files of a backup are the same as at any other target.

The sign-in service auth.cloneworx.de

Dropbox requires a secret for the sign-in. A secret cannot be in a plugin whose code anyone can read. That is why it lives with a small service by cloneworx, auth.cloneworx.de, which brokers the sign-in.

Who sends	What the service learns
Your browser, when you click Connect with Dropbox	the address of the admin page of your website, a random value and the language
Your web server, after the return	the code of the sign-in. The service passes the sign-in on to Dropbox.
Your web server, as long as the target is in use	the stored permanent access, whenever a new access is needed: every few hours

In addition, as with every request, the IP addresses of browser and web server. The service stores nothing. It never receives a backup, never a file and never the address of your Dropbox account.

At the target two values are stored, encrypted like every password of a target: the permanent access and the access that is valid for a few hours. The address of the connected Dropbox account is shown visibly at the target. It never appears in the log or in the support report.

The fields of the Extended view

1. Connection timeout (seconds) takes 3 to 60, the default is 10.
2. Upload rate (bytes per second) may stay empty: then what the connection test measured applies. Based on it the plugin chooses the size of the sections of an upload.

There is no field for a folder in the Extended view either.

Editing and testing the target

In the row of the target, click More …, then Edit.

1. Name is the name of the target in lists and messages.
2. The connected account is the address of the Dropbox account in which the backups are stored.
3. Save saves your changes.
4. The button Connect again with Dropbox starts the sign-in for this target again.
5. Test connection tests the connection.

Click Test connection. The connection test writes a small file into the Dropbox, reads it back and deletes it again. In addition it uploads a test file in three sections, measures the upload rate while doing so and checks whether Dropbox names the right position to continue from after a lost response. Finally it compares size and checksum. It deletes this file again as well.

1. The result of the test: the connection works, a test file was written, read back and deleted.
2. The upload method and the measured upload rate.

Line in the result	Meaning
Connection works: a test file was written, read back and deleted.	Writing, reading back and deleting work.
Upload method: in sections (upload session); an upload continues where it stopped.	The plugin uploads every file in sections. If the response to a section is lost, that costs only this one section.
Measured upload rate: … per second.	Based on the rate the plugin chooses the size of the sections: so that a section and the response from Dropbox fit into the rest of a step.

Warning after a successful test

A warning is shown in yellow below the result. The target is usable nevertheless.

Warning	Meaning
The service names no checksum for the file; after an upload only the size is checked.	After an upload the plugin compares the size, not the checksum.

When the test fails

A failed test names the cause, for some causes the reason in more detail below it, and then the error message from Dropbox in the line Message from the target: … The error message is not translated. The address of the Dropbox account is replaced by <user> in it.

1. The cause in plain language, here: the target reports that there is no space left.
2. The error message from Dropbox, not translated.

Message	What to do
The target reports that there is no space left.	Free up space in your Dropbox account and test again.
The account refused the access. The provider no longer accepts the stored consent. Connect the target again.	See the section “Disconnected and connecting again”.
The account refused the access. The provider did not accept the access. If this persists, connect the target again.	Dropbox refused the access, for example because it has expired. Test once more. If the message stays, connect the target again.
The account does not allow this request. The stored consent does not cover this request. Connect the target again.	The consent lacks a permission. Open the target for editing and click Connect again with Dropbox.
The account does not allow this request.	If no reason is shown below it, Dropbox does not allow the request, for example because Dropbox has suspended the account or a rule of the account forbids it. The target does not count as disconnected in this case, and connecting again does not help. Clarify the cause in your Dropbox account or with Dropbox. What Dropbox says about it is named in the line Message from the target: …
The sign-in service did not return a new access. The sign-in service cannot be reached.	The plugin could not fetch a new access. Test again later.
The target asked for a pause: it is busy, or it received too many requests.	Test again later. In a backup the plugin itself waits as long as Dropbox names, and then tries again.
An upload did not arrive before the time of a step ran out: the connection to the target is too slow for it. The plugin sends an upload to this service in sections of at least 256 KiB, and such a section has to arrive within one step.	The connection between your web server and Dropbox is too slow for the smallest section.

Disconnected and connecting again

Dropbox no longer accepts a consent if you have disconnected the app in the settings of your Dropbox account. The plugin then marks the target as disconnected at once. Backups skip it until you connect it again.

1. The status tile names the disconnected target, the cause and the next step.
2. Connect again opens the form of the disconnected target.
3. Disconnected is shown in the list at the target. The dot in front of it is yellow.

As the cause the status tile names: The provider no longer accepts the stored consent: it was withdrawn or has expired. Below it the next step is shown: Next step: connect “…” again. Until then, backups skip this target. Click Connect again.

1. The connected account is the address of the Dropbox account in which the backups are stored.
2. The cause is shown in yellow: Dropbox no longer accepts the stored consent.
3. The button Connect again with Dropbox starts the sign-in.

Click Connect again with Dropbox and give your consent at Dropbox as when setting up. The target, its name and its backups are kept.

With the new connection the plugin revokes at Dropbox the access the target had until then. That also applies if you connect again a target that is not disconnected. More about this in the next section.

When the plugin revokes the access at Dropbox

The plugin asks Dropbox to revoke the access that a target holds:

• when you remove the target, on the Targets page or with WP-CLI,
• when you connect the target again: then the access the target had until then, never the new one,
• when you delete the plugin in WordPress and the switch in the tile Uninstall on the Settings page is on. Then the plugin first revokes the access of every target of the type Dropbox and afterwards removes settings, targets and logs. If the switch is off, the plugin revokes nothing: the targets stay in the database for a new installation.

The backups stay in your Dropbox in any case. Other websites that you have connected with the same Dropbox account have their own access and stay connected.

The revocation does not always succeed:

• The plugin cannot send it if it can no longer read the stored credentials, for example after a changed database password, if the target was already removed or if cURL is missing.
• It can fail, for example if Dropbox or the sign-in service cannot be reached at that moment. The plugin needs the sign-in service when the access has expired: then it fetches a new one first.
• When deleting the plugin, a revocation only starts as long as no ten seconds have passed since the first one. A target whose turn would come after that keeps its access.

The target is removed or connected again nevertheless, and deleting the plugin continues. The access then stays valid at Dropbox until you disconnect the app in your Dropbox account.

Good to know

• Removing the target revokes at Dropbox the access the target had. The backups stay in your Dropbox. When the revocation is not sent or fails is described in the section “When the plugin revokes the access at Dropbox”.
• Free space. Dropbox names the space of the account and how much of it is used. If a backup does not fit in there, it skips this target and goes to the other targets of the plan. It ends “with warnings” and names the target, the space needed and the free space. If the backup is left with no target, the job ends before it writes anything. Dropbox counts an upload only once it is complete: if the account fills up in the meantime, the upload fails at its end.
• Uploads. The plugin chooses the size of a section based on the measured upload rate, at least 256 KiB. A file appears in Dropbox only with the completion of the upload, in one go. If a file with this name already exists there, the completion replaces it; nothing is deleted beforehand. Every section carries a checksum, and Dropbox rejects a section that arrives altered. After the upload the plugin compares size and checksum at Dropbox with the local file.
• Short steps. If less than 6 seconds are left in a step that has already done work, it does not start another request to Dropbox. The next step continues with its full time.
• Limits of Dropbox. A request carries at most 150 MiB; the plugin stays far below that. An upload that is never completed expires at Dropbox after seven days.
• A folder is removed by the plugin only if Dropbox lists it as empty. Otherwise it deletes only files.
• No download through the plugin. Backups that are stored only in Dropbox you fetch in Dropbox. Restore, check and finding backups read directly from Dropbox.
• The plugin also uses a proxy from the wp-config.php for this target type. It never follows a redirect.
• Below the selection of the target types the note reads: Names and logos of third parties are the property of their respective owners. This does not imply any affiliation or partnership.

See also

• Which target suits you?
• The “Targets” page
• Renew the credentials of a target
• Store backups in Google Drive
• Remove a target
• Check backups at a target and clean up leftovers
• Uninstall the plugin

On the command line

WP-CLI not set up yet? How to install WP-CLI.

You create a target of the type Dropbox in the browser, on the Targets page: that is where you give your consent at Dropbox. Connecting again also only works in the browser. Testing, checking and removing also work with WP-CLI:

# Show targets with ID and state
wp cloneworx-backup target list

# Test the connection
wp cloneworx-backup target test dropbox-1

# Check the backups at this target
wp cloneworx-backup target check dropbox-1

# Remove the target; the backups in Dropbox are kept
wp cloneworx-backup target remove dropbox-1