*cloud - FileLink for Nextcloud and ownCloud

Deutsche Dokumentation

A MailExtension for Thunderbird (68+) that uploads large attachments to your Cloud and generates a link you can send by mail instead of the file.

[[TOC]]

Requirements

• Nextcloud: 18 or newer (older versions might work, but are not supported by Nextcloud)
• ownCloud: 10.0.10+ (10.0.9 and older versions contain bugs that prevent *cloud from working).
• Thunderbird: 68.2.1 or newer

User guide

Installation

1. Go to Settings -> Compose -> Attachments (in Thunderbird 68 Attachments -> Outgoing)
2. Click the link "Find more providers..." at the bottom of the page.
3. Find *cloud in the list and click the "Add to Thunderbird" button.
4. On the "Options" tab click the button "Add *cloud".
5. Configure. Only three settings are strictly necessary:
   • Server URL
   • Username
   • App token or password

*cloud is also available via Thunderbird's Add-on repository:

.

Known issues

You don't like the text/HTML/links inserted into the message

Many users would like to change the text that is inserted into the message along with the download url, eg add the expiration date, change the cloud service link, remove some of the text or style the HTML less prominently. Addons like *cloud have no chance to do that, because the template text surrounding the url is part of Thunderbird. The Addon only supplies the url, Thunderbird wraps its template around it and inserts the whole thing into your message (technical details here and here).

There is a feature suggestion for Thunderbird, to make this template editable. You might consider backing this suggestion with your vote or a helpful comment.

Files from network shares uploaded to cloud and attached

There was a bug in Thunderbird: If you attached a file from a network share, it was uploaded to the cloud and the share link was inserted into your mail, but the file was also attached to the message. This was fixed in Thunderbird 68.11.0 and 78.0.1. If you're still experiencing this issue, update Thunderbird.

URL works in browser but not in *cloud

In some situations the url you use to access your Nextcloud/ownCloud account in the browser doesn't work in *cloud.

Reason 1: Redirect

If your access url is redirected to the actual cloud location (plus some technicality), *cloud can't find the actual url.

If this happens to you, point *cloud to the actual cloud location:

1. Open your cloud in your browser.
2. Log in.
3. Depending on your cloud version you now have different views:
   • In Nextcloud 20 you see the "Dashboard", just continue to the next step.
   • In older versions of Nextcloud and in ownCloud your see the "Files" app. Continue to the next step.
   • If you are neither in the "Dashboard" nor the "Files" app, click on the folder icon in the cloud's top menu to go to the "Files" app.
4. Copy the complete url from the url bar of your browser
5. Paste it into the server url field in *cloud's configuration (in Thunderbird).

When you save the settings, *cloud will remove unnecessary parts.

Reason 2: https certificate

If the admin of your cloud used something called a "self signed certificate", Thunderbird (not *cloud) refuses to connect to the server. There are two solutions:

1. (preferred) Tell your admin about the problem. She might install another type of certificate, which Thunderbird accepts.
2. (if 1. is not possible) Force Thunderbird to accept the certificate:
   1. Open Thunderbird's preferences
   2. Go to "Privacy & Security"
   3. Scroll down to "Certificates"
   4. Click on "Manage Certificates"
   5. Choose "Servers"
   6. Click on "Add Exception"
   7. Enter your cloud's address in the "Location" field
   8. Click "Ger Certificate"
   9. Click "Confirm Security Exception"

Still not working?

If things still don't work, I'd appreciate a problem report by email containing the url you pasted. Don't be afraid, the url does not contain any secret data. Thanks.

Upload problems

• The download password has to comply with all the rules for passwords on your cloud, otherwise the upload will fail. There are default rules of Nextcloud and ownCloud, and your admin might have configured some different rules.
• If the Add-On still fails, please check if it's a known bug. Feel free to open a new issue otherwise.

Good to know

Download passwords

If you use download passwords, never put them into an email, but give them to the recipient via a separate, secure channel eg a messenger or a telefone call.

Why? As a security measure the generated download links contain a long, almost random part. So an attacker (let's call her Eve) can't guess the link for a file or scan all possible links to find a file. The only reasonable way for Eve to gain access to your file is to intercept the mail. (If you are interested in technical details, read this posting).

So the links are fairly secure by themselves and quite comfortable for the recipient, because she only has to click the link.

If you use download passwords, never put them into the same email as the link. Because if Eve can read the link, she can also read the password. So a download password in the same email doesn't make the transfer more secure, but only more complicated for the recipient. The same goes for a separate email with the password: If Eve can intercept the first email with the link, she is very probably also able to intercept the second email.

Password vs. App Token

Instead of storing your password it's more secure to use an "App Token" with *cloud. There are two ways to get such a token:

• If you are using Nextcloud or ownCloud: Open your account in the browser and go to Settings -> Security -> App Token and at the bottom of the page generate a new token. Copy&paste it into the "App token" field of the Attachments preferences page in Thunderbird.

• Only if you are using Nextcloud: Type your user password into the Attachments/Outgoing preferences page in Thunderbird. Upon saving, the Add-On will try to get a token from your Nextcloud and use it instead of your password. You will notice the change, because afterwards the password field is filled with dots completely (app tokens are quite long).
  BUT! if getting the token fails for any reason (e.g. your Nextcloud is not reachable, timeout, wrong username, ...), the Add-On will store your password unencrypted.

Handling of existing files

• If you attach a file that's already in the attachments folder in your cloud with identical contents, that file is not uploaded again. Instead the existing file is shared.

• To make this possible, *cloud never deletes files in your cloud. Over time your attachments folder may grow to considerable size. It's safe to delete old attachments. Your admin may automate that; point her to the Admin Guide

• You can use this behavior if you want to share large (or many) files: Sync your attachments folder to a folder on your computer using the desktop client. If you then attach a synced file from your computer to a message, *cloud will notice that it's already uploaded.

• If you attach a file with the same name but different contents as a cloud file, the cloud file will not be overwritten. Instead *cloud moves the existing file to a subfolder of the attachments folder; the original share link will remain valid and point to the old content.
  Then the new file is uploaded and shared with a new share link.

*cloud uses the same method as the Nextcloud/ownCloud desktop clients to decide if the local and remote files are identical.

Information for cloud administrators

Server settings

Some settings in Nextcloud/ownCloud are relevant for this Add-On:

• Settings -> Sharing -> Allow apps to use the Share API has to be enabled
• Settings -> Sharing -> Allow users to share via link has to be enabled
• The app "Share Files" has to be active. In ownCloud the Apps management is part of the Administrator's settings, in Nextcloud it's accessible directly from the Admin's profile menu.

Old uploads

*cloud never deletes any file it uploads, because:

• It reuses previous uploads to save bandwidth,
• it can't decide if a file has been downloaded or is still necessary,
• an Addon in a client software is hardly the right place for server maintenance.

So users have to clean up their attachments folder themselves. You may help them by automatically removing files after some time. This works in Nextcloud and the Enterprise version of ownCloud:

1. Install and activate two server apps
   • Files automated tagging
   • Retention
2. In Settings -> Basic settings in section "Collaborative tags" create a new tag, eg "FilelinkUpload"
3. In Settings -> Flow click "Add new Flow"
   1. Choose "File is changed"
   2. Filter by "Request user agent"
   3. "matches"
   4. "Custom user agent"
   5. Enter /^Filelink for \*cloud/ as the Regular Expression
   6. As the action choose "Automated tagging"
   7. Select the previously created tag.
   8. Save
4. In the section "File retention"
   1. Select the tag
   2. Enter the number of days before the uploads will be deleted
   3. Create
5. (Optional) In Settings -> Sharing
   1. Choose "Set default expiration date for shares"
   2. Set a default expiry time that is shorter than the retention time you configured above. So users will be less confused if their files disappear.
   3. Choose "Enforce expiration date"

This might still delete shared files, because the Retention app deletes them n days after creation, ie upload. If the user shares it again before it is deleted, the file is not uploaded again and hence the retention timeout is not reset.

Redirects

In some configurations a start url like https://cloud.example.com is redirected to the actual url of the cloud eg https://example.com/cloud. *cloud has to access many different paths below this url, eg. status.php. If these are not also redirected (https://cloud.example.com/status.php -> https://example.com/cloud/status.php), *cloud can't access them and doesn't work. There is no way for the extension to find the actual base url with some certainty.

There is a workaround: Users can find out the actual url and configure it in *cloud. But it's easier for users if all urls are redirected. So it would be greatly appreciated if you would do that in your cloud instance (if you have to use redirects at all). Thanks.

Self-signed certificates

By default Thunderbird (not *cloud) refuses https connections using self-signed certificates. It's a lot easier for your users, if you install a Let's encrypt certificate. There are great How-tos on their site.

Information for Cloud Service Providers

If you run a service based on Nextcloud or ownCloud and would like to offer a branded/tailored version of *cloud for your service, please contact me by email.

Contributing

The project lives on GitLab: https://gitlab.com/joendres/filelink-nextcloud.

Reporting bugs and suggesting features

If you find a bug or have an idea for a feature:

1. Go to the issues board and check if there is an open issue already.
2. If there no issue describing your problem or your idea, there are two option to submit a new one:
   • Open a new issue on the issues board.
   • If you don't have a gitlab account, just send an e-mail to the Service Desk.

Pre-release versions

There usually are two development versions of *cloud:

• Release-x.y for the next release that has new features or visible changes for users
• Bugfix-x.y.z for the next release that only fixes bugs

These versions usually are more or less functional. They have corresponding branches in the repository.

All other branches are work in progress and guaranteed not to work 😉.

Testing

If you'd like to help with testing, first install one of the development versions:

1. Clone or download one the development branches
2. Pack the contents of the "src" subdirectory (not the subdir itself) into a zip file
3. In Thunderbird go to the Add-ons Manager and from the rotary menu select "Install Add-on from file"
4. Choose your zip file and install

If you find a bug please use one of the options above to report it.

Localizations

If you'd like to have *cloud in a language you are fluent in:

• If you're also fluent in git
  1. Clone the latest Release-x.y branch
  2. In src/_locales duplicate the directory en
  3. Rename the copy to the 2-letter code of your language
  4. Translate all the messages in messages.json in your new directory.
  5. Create a merge request into the Release-x.y branch you cloned.
• If you're not
  1. Just download the english strings file
  2. Translate alls the messages in that file
  3. Mail it to me stating the language

Important:

• Don't bother with the descriptions; they don't show up anywhere, they're just there for your reference.
• If you're not sure about a string's context, just put all your questions in an email or an issue. I'll be glad to clarify.

Code

If you'd like to fix a bug or implement a feature

• Just branch from the latest Release-x.y or Bugfix-x.y.z branch
• Use jshint to check your code.
• Optional: When your code is ready, git merge the original branch and resolve conflicts. I'll handle all conflicts that arise later.
• If you add strings, just add them to the english locales (and any other language you are fluent in), don't add english strings to other locales

Dev resources

• Nextcloud Client APIs
• ownCloud External API
• Thunderbird WebExtension APIs
• JavaScript APIs for WebExtensions), some of these are also available in Thunderbird
• Example extensions for Thunderbird WebExtensions APIs
• Getting started with web-ext If you are developing WebExtensions, you want to use this tool. For debugging just set the firefox config option to your thunderbird binary.
• Photon Components contain CSS styles and some additional resources to replicate the standard styles used in Thunderbird
• Firefox Brand + Design Assets are also useful for Thunderbird, especially the icon library.
• What you need to know about making add-ons for Thunderbird, not complete at all.
• @JasonBayton runs Nextcloud demo servers of many (old) versions, great for testing.

Contributions

• Johannes Endres, initial implementation, maintainer
• Josep Manel Mendoza, catalan and spanish localizations
• Gorom, french localization
• Jun Futagawa, implementation of generated random passwords
• Lionel Elie Mamane, solution of the LDAP/getapppassword problem
• Óvári, hungarian localization
• Based on FileLink Provider for Dropbox by Geoff Lankow
• Inspired by Nextcloud for Filelink by Olivier Paroz and Guillaume Viguier-Just.