[[TOC]]

Tor Project is using Nextcloud as a tool for managing and sharing resources and for collaborative editing.

Questions and bug reports are handled by Tor's Nextcloud service admin team. For bug reports, please create a ticket in the Service - Nextcloud component in Trac. For questions, find us on IRC (GeKo, ln5, pospeselr, anarcat, gaba) or send email to nextcloud-admin@torproject.org.

Tutorial

Signing in and setting up two-factor authentication

  1. Find an email sent to your personal Tor Project email address from nc@riseup.net with a link to https://nc.torproject.net/
  2. Do not click on the link in the email, clicking on links in emails is dangerous! Instead, use the safe way: copy and paste the link in the email into your web browser.
  3. Follow the instructions for changing your passphrase.

  4. Enable two-factor authentication (2FA):

    1. Pick either a TOTP or U2F device as an "second factor". TOTP is often done with an app like Google Authenticator or a free alternative (for example free OTP plus, see also this list from the Nextcloud project). U2F is usually supported by security tokens like the YubiKey, Nitrokey, or similar.
    2. If you have a TOTP setup, locate it and then:
    3. Click "Enable TOTP" on the web page.
    4. Insert your token or start the TOTP application on your handheld device and scan the QR code displayed on the web page.
    5. Enter the numbers from the token/application into the text field on the web page.
    6. Log out and log in again, to verify that you got two factor authentication working.
    7. If you have a U2F setup, locate it and then:
    8. Click the "Add U2F device" button under the "U2F device" section
    9. Insert the token and press the button when prompted by your web browser
    10. Enter a name for the device and click "Add"
    11. Log out and log in again, to verify that you got two factor authentication working.
    12. In Nextcloud, select Settings -> Security. The link to your settings can be found by clicking on your "user icon" in the top right corner. Direct link: Settings -> Security.
    13. Click "Generate Backup codes" in the Two-Factor Authentication section of that page.
    14. Save your backup codes to a password manager of your choice. These will be needed to regain access to your Nextcloud account if you ever lose your 2FA token/application.

A note on credentials

Don't let other people use your credentials. Not even people you know and like. If you know someone who should have a Nextcloud account, let the service admins know in a ticket.

Don't let other people use your credentials. Never enter your passphrase or two-factor code on any other site than Tor Project's Nextcloud site. Lower the risk of entering your credentials to the wrong site by verifying that there's a green padlock next to the URL and that the URL is indeed correct.

Don't lose your credentials. This is especially important since files are encrypted in a key derived from your passphrase. To help deal with when a phone or hardware token is lost, you should really (really!) generate Backup codes and store those in a safe place, together with your passphrase. Backup codes can be used to restore access to your Nextcloud and encrypted files. There is no other way of accessing encrypted files! Backup codes can be generated from the Settings -> Security page.

Files

In the top left of the header-bar, you should see a "Folder" icon; when moused over a text label should appear beneath it that says Files. When clicked, you will be taken to the Files app and placed in the root of your Nextcloud file directory. Here, you can upload local files to Nextcloud, download remote files to your local storage, and share remote files across the internet. You can also perform the various file management operations (move, rename, copy, etc) you are familiar with in Explorer on Windows or Finder on macOS.

On the left side of the Files app there is a side-bar with a few helpful views of your files.

  • All files : takes you to your root folder
  • Recent : recently accessed files and folders
  • Favorites : bookmarked files and folders
  • Shares : files and folders that have been shared with you or you are sharing with others
  • Tags : search for files and folders by tag

Upload a file

Local files saved on your computer can be uploaded to Nextcloud. To upload a file:

  1. In the Nextcloud Files app, navigate to the folder where you want to store the file
  2. Click on the circular button with a + inside it (to the right of the little house icon)
  3. Click Upload file entry in the context menu
  4. Select a file to upload using your system's file browser window

Share a file or directory with another Nextcloud user or a group of users

Files stored in your Nextcloud file directory can be selectively shared with other Nextcloud users.

They can also be shared with a group of users to grant the same permission to more than one user at once. When sharing to a group, it becomes possible to manage who has access to the file or directory by managing members of the group.

To share a file:

  1. Locate the file you wish to share (either by navigating to the folder it is in, by searching, or by using one of the views in the sidebar).
  2. Click the file's Share icon (to the right of the file name)
  3. In the pane that pops out from the right, click on the search box labeled Name, federated cloud ID or email address…
  4. Search for the user or group you wish to share with by Nextcloud user id (pospeselr), email address (richard@torproject.org), or name (Richard Pospesel) and select them from the dropdown.
  5. Optional: click on the meatball menu to the right of the shared user and edit the sharing options associated with the file or directory.
    • For instance, you may wish to automatically un-share the file at some point in the future
    • refer to notes on share options for some further considerations about permissions

Share a file with the internet

Files can also be shared with the internet via a URL. Files shared in this fashion are read-only by default, but be mindful of what you share: by default, anyone who knows the link URL can download the file. To share a file:

  1. Locate the file you wish to share
  2. Click the file's Share icon (to the right of the file name)
  3. In the pane that pops out from the right, click the + icon beside the Share link entry
  4. Select appropriate sharing options in the context menu (these can be changed later without invalidating the link)
  5. Optional: A few measures to limit access to a shared file:
  6. Prevent general access by selecting the Password protect option
  7. Automatically deactivate the share link at a certain time by selecting the Set expiration date option
  8. Finally, copy the shared link to your clipboard by clicking on the Clipboard icon

Un-share files or edit their permissions

If you have shared files or folders with either the internet or another Nextcloud user, you can un-share them. To un-share a file:

  1. Locate the file you wish to un-share in the Files app
  2. All of your currently shared files and folders can be found from the Shares view
  3. Click the file's Shared icon (to the right of the file name)
  4. In the pane that pops out from the right, you get a listing of all of the users and share links associated with this file
  5. Click the meatball menu to the right of one of these listings to edit share permissions, or to delete the share entirely

Some notes on share options

Here are some gotchas to be aware of when sharing files or folders:

  • When sharing PDF files (or folders containing PDF files), if you choose "Custom permissions", make sure to enable "Allow download and sync". If you don't, the people with whom you shared the PDF files will not be able to see them in the Web Browser nor download them.
  • Avoid creating different shares for folders and for files within them targeting the same people or groups. Doing so can end up in weird behavior and create problems like the one described above for PDF files.

File management

Search for a file

In the Files application press Ctrl+F, or click the magnifying glass at the upper right of the screen, and type any part of a file name.

Desktop support

Files can be addressed transparently through WebDAV. Most file explorer support the protocol which should enable you to browse the files natively on your desktop computer. Detailed instructions on how to setup various platforms are available in the main Nextcloud documentation site about WebDAV.

But the short version is you can find the URL in the "Settings wheel" at the bottom right of the files tab, which should look something like https://nc.torproject.net/remote.php/webdav/. You might have to change the https:// part to davs:// or webdavs:// depending on the desktop environment you are running.

If you have setup 2FA (two-factor authentication), you will also need to setup an "app password". To set that up:

  1. head to your personal settings by clicking on your icon on the top right and then Settings
  2. click the Security tab on the right
  3. in the Devices & sessions section, fill in an "app name" (for example, "Nautilus file manager on my desktop") and click Create new app password
  4. copy-paste the password and store it in your password manager
  5. click done

The password can now be used in your WebDAV configuration. If you fail to perform the above configuration, WebDAV connections will fail with an Unauthorized error message as long as 2FA is configured.

Collaborative editing of a document

Press the plus button at the top of the file browser, it brings you a pull-down menu where you can pick "Document", "Spreadsheet", "Presentation". When you click one of those, it will become an editable field where you should put the name of the file you wish to create and hit enter, or the arrow.

A few gotchas with collaborative editing

Behind the scenes, when a user opens a document for editing, the document is being copied from the Nextcloud server to the document editing server. Once all editing sessions are closed, the document is being copied back to Nextcloud. This behavior makes the following information important.

  • The document editing server copies documents from Nextcloud, so while a document is open for editing it will differ from the version stored in Nextcloud. The effect of this is that downloads from Nextcloud will show a different version than the one currently being edited.

  • A document is stored back to Nextcloud 10 seconds after all editing sessions for that document have finished. This means that as long as there's a session open, active or idle, the versions will differ. If either the document server breaks or the connection between Nextcloud and the document server breaks it is possible that there will be data loss.

  • An idle editing session expires after 1 hour (even though this should be shorter). This helps making sure the document will not hang indefinitely in the document editing server even if a user leaves a browser tab open.

  • Clicking the Save icon (đź’ľ) saves the document back to Nextcloud. This helps preventing data loss as it forces writing the contents from the document editing server back to the persistent storage in Nextcloud.

  • If a document is edited locally (i.e. it's synchronized and edited using LibreOffice or MS Office, for example) and collaboratively at the same time, data loss can occur. Using the ONLYOFFICE Desktop Editor is a better alternative, as it avoids parallel edits of the same file. If you really need to edit files locally with something other than the ONLYOFFICE Desktop Editor, then it's better to make a copy of the file or stop/quit the Nextcloud Sync app to force a conflict in case the file is changed in the server at the same time.

Client software for both desktop (Window, macOS,Linux) and handheld (Android and iPhone)

https://nextcloud.com/clients/

Using calendars for appointments and tasks

TODO

Importing a calendar feed from Google

  1. In your Google calendar go to the "Settings and Sharing" menu (menu appears by hovering over the right hand side of your calendar's name - "Options for " and the calendar name) for the calendar feed you want to import.
  2. Scroll down to the "Integrate Calendar" section and copy the "Secret address in iCal format" value.
  3. In Nextcloud, click on "New Subscription" and paste in the calendar link you copied above.

Calendar clients

Nextcloud has extensive support for events and appointments in its Calendar app. It can be used through the web interface, but since it supports the CalDAV standard, it can also be used with other clients. This section tries to guide our users towards some solutions which could be of interest.

Android

First create a Nextcloud "App" password by logging into the Nextcloud web interface, and then go to your profile->Settings->Security->Create a new App Password. Give it a name and then copy the randomly generated password (you cannot see the password again after you are finished!), then click Done.

Install DAVx^5 from F-Droid or the Play store This program will synchronize with Nextcloud your calendars and contacts and is Free. Launch it and press the "+" to add a new account. Pick "Login with URL and username". Set Base URL: "nc.torproject.org", put your Nextcloud username into "Username" and then the App password that you generated previously into the "Password" field, click Login. Under Create Account, make your Account name your email address, then click Create Account. Then click the CalDAV tab and select the calendars you wish to sync and then press the round orange button with the two arrows in the bottom right to begin the synchronization. You can also sync your contacts, if you store them in Nextcloud, by clicking the CardDav tab and selecting things there.

For more information, check the Nextcloud documentation

iOS

This is a specific configuration for those that have two-factor-authentication enabled on their account.

  1. Go to your Nextcloud account
  2. Select Settings
  3. On the left bar, select Security
  4. A list of topics will appear: “Password, Two-factor Authentication, Password-less Authentication, Devices & Session”
  5. Go to Devices & Session, on the field “App name” create a name for your phone, like “iPhone Calendar” and click on “Create new app password”
  6. A specific password will be created to sync your Calendar on your phone, note that this password will only be shown this one time.

Then, you can follow the Nextcloud settings, take your phone:

  1. Go to your phone Settings
  2. Select Calendar
  3. Select Accounts
  4. Select Add Account
  5. Select Other as account type
  6. Select Add CalDAV account
  7. For server, type the domain name of your server i.e. example.com.
  8. Enter your user name and the password that was just created to sync your account.
  9. Select Next.

Done!

Note: the above instructions come from this tutorial.

Mac, Windows, Linux: Thunderbird

Thunderbird, made by the Mozilla foundation, has a built-in calendar. This used to be a separate extension called Lightning, but it is now integrated into Thunderbird itself. Thunderbird also integrated builtin support for CalDAV/CardDAV from version 120 onwards.

It's a good choice if you already use Thunderbird, but you can also use it as a calendar if you do not use Thunderbird.

In order to use the calendar, you need to first generate an App password. Then you'll ask Thunderbird to find your calendars.

Nextcloud "App" password

Log into the Nextcloud web interface, and then go to your profile->Settings->Security->Create a new App Password (at the very bottom of the page). Give it a name and then copy the randomly generated password (you cannot see the password again after you are finished!), then click Done.

Note: if you did this previously for Android, it's not a bad idea to have a separate App Password for Thunderbird. That way you can revoke the Android password if you lose your device and still have access to your Thunderbird calendar.

Calendars

Open up the calendar view in Thunderbird (in versions 120+ it's the calendar icon on the left vertical bar). Click on "New Calendar" and select "On the Network". Then enter the user name associated to your app password and for the URL use the following: https://nc.torproject.net/remote.php/dav

After hitting the "Next" button, you'll be prompted for your app password. Normally after a little while you should be able to subscribe to your calendars (including the ones shared with you by other users).

The above procedure also works well for adding missing calendars (e.g. ones that were created in nextcloud after you subscribed to the calendars).

Note: Nextcloud used to recommend using the Tbsync plugin with its associated CalDAV/CardDAV backend plugin, but this does not work anymore for Thunderbird 120+. If you're still using an older version, refer to Nextcloud's documentation to setup Tbsync.

Contacts

To automatically get all of your contacts from nextcloud, open the Address Book view (in the left vertical bar in versions 120+). Click on the arrow beside "New Address Book" and choose "Add CardDav Address Book". Then enter the username associated to your app password and for the URL, use the same URL as for the calendars: https://nc.torproject.net/remote.php/dav

After hitting "Next" you'll be prompted for your app password and after a while you should be able to choose from the sources of contacts to synchronize from.

Linux: GNOME Calendar, KDE Korganizer

GNOME has a Calendar and KDE has Korganizer, which may be good choices depending on your favorite Linux desktop.

Untested. GNOME Calendar doesn't display time zones which is probably a deal breaker.

Command line tools: vdirsyncer, ikhal, calcurses

vdirsyncer is the hardcore, command line tool to synchronize calendars from a remote CalDAV server to a local directory, and back. It does nothing else. vdirsyncer is somewhat tricky to configure and to use, and doesn't deal well with calendars that disappear.

To read calendars, you would typically use something like khal, which works well. Anarcat sometimes uses ikhal and vdirsyncer to read his calendars.

Another option is calcurses which is similar to ikhal but has "experimental CalDAV support". Untested.

Managing contacts

TODO

How-to

Showing UTC times in weekly calendar view

This TimeZoneChallenged.user.js Greasemonkey script allows you to see the UTC time next to your local time in the left column of the Nextcloud Calendar's "weekly" view.

To install it:

  1. install the Greasemonkey add-on if not already done
  2. in the extension, select "new user script"
  3. copy paste the above script and save
  4. in the extension, select the script, then "user script options"
  5. in "user includes", add https://nc.torproject.net/*

Ideally, this would be builtin to Nextcloud, see this discussion and this issue for followup.

Resetting 2FA for another user

If someone manages to lock themselves out of their two-factor authentication, they might ask you for help.

First, you need to make absolutely sure they are who they say they are. Typically, this happens with an OpenPGP signature of a message that states the current date and the actual desire to reset the 2FA mechanisms. For example, a message like this:

-----BEGIN PGP SIGNED MESSAGE-----

i authorize a Nextcloud admin to reset or disable my 2FA credentials on
nc.torproject.net for at most one week. now is 2022-01-31 9:33UTC

-----BEGIN PGP SIGNATURE-----
[...]
-----END PGP SIGNATURE-----

This is to ensure that such a message cannot be "replayed" by an hostile party to reset 2FA for another user.

Once you have verified the person's identity correctly, you need to "impersonate" the user and reset their 2FA, with the following path:

  1. log into Nextcloud
  2. hit your avatar on the top-right
  3. hit "Users"
  4. find the user in the list (hint: you can enter the username or email on the first row)
  5. hit the little "three dots" (...) button on the right
  6. pick "impersonate", you are now logged in as that person (be careful!)
  7. hit the avatar on the top-right again
  8. select "Settings"
  9. on the left menu, select "Security"
  10. click the "regenerate backup codes" button and send them one of the codes, encrypted

When you send the recovery code, make sure to advise the user to regenerate the recovery codes and keep a copy somewhere. This is a good template to use:

Hi!

Please use this 2fa recovery code to login to your nextcloud account:

[INSERT CODE HERE]

Once you are done, regenerate the recovery codes (Avatar -> Settings ->
Security) and save a copy somewhere safe so this doesn't happen again!

FAQ

Why do we not use server-side encryption?

Example question:

I saw that we have server-side encryption disabled in our configuration. That seems bad. Isn't encryption good? Don't we want to be good?

Answer:

Server-side encryption doesn't help us with our current setup. We're hosting the Nextcloud server and its files at the same provider.

If we would be (say) hosting the server at provider A and the files at (say) provider B, that would give us some protection because an provider B compromise wouldn't compromise the files. But that's not our configuration, so server-side encryption doesn't give us additional security benefits.

Reference

Authentication

See TPA-RFC-39 for who gets Nextcloud accounts.

Issues

Known issues