Skip to content

Latest commit

 

History

History
247 lines (236 loc) · 13.8 KB

instructions.md

File metadata and controls

247 lines (236 loc) · 13.8 KB

Welcome To Synapse!

Synapse is your personal gateway to the Matrix federation. With it, you can communicate with anyone, anywhere, without restriction, without permission, independently, and in total, trustless privacy.

Warning! Synapse is an incredibly powerful and complex piece of software. Please read these instructions carefully. If you find yourself in trouble, the best thing to do is stop clicking and contact support.


Instructions

Step 1: Initial Config

  1. Federation: Enabling Federation allows you to discover and join rooms on other Tor-enabled servers and vice versa. If you want a totally private chat server, you should disable Federation. Either way, you will not be able to interact with rooms and people on clearnet servers, such as matrix.org.
  2. Email Notifications: If you wish to receive email notification from your Synapse server, you must provide your own SMTP credentials.
  3. Advanced - Enable Registration: If you enable registration, anyone will be able to create an account on your Synapse server. It is highly recommended that you disable registrations whenever possible. The only time we recommend turning it on is if you quickly want multiple people to create accounts on your server, then you should turn it back off.


Step 2: Creating Your First Account

With registrations disabled, the only way to create an account on your Server is through the Admin Portal.

  1. In your Synapse dashboard, click "Launch UI"
  2. Log in with your Admin Username and Password (located in Properties). For "Homeserver URL", do not enter your Homeserver address. Instead, enter your Admin Portal URL. Hint: this is the URL currently showing in your browser URL bar, minus the path. e.g. https://exampleaddress.local or http://exampleaddress.onion.
  3. In the "Users" tab, you will notice the admin user already created.
  4. In the "Users" tab, click "+ Create"
  5. Choose a User-ID, Displayname, and Password for your account. Optionally enter an email address under the 3PIDs section. It is not recommended to make this user a Server Administrator, as it is best to limit admin access.


Step 3: Using Your Server

In order to use your new Synapse server, you will need to select a client app. We recommend:

These instructions are written for Element, but they are identical for SchildiChat.

  • Web

      Note: Element Web is not mobile responsive, meaning it does not adapt well to smaller screen sizes. You should only use it from desktop/laptop browsers, not from your mobile device

    1. Visit https://app.element.io from a Tor-enabled browser (Tor Browser or Firefox, but not Brave)
    2. Click Sign In or Create Account, depending on whether or not you have already created your account
    3. Beneath "Host Account On" (following Create Account), or "Homeserver" (following Sign In), click Edit and change "matrix.org" to http://your_synapse_address_from_interfaces.onion
    4. Complete sign in or account creation

  • macOS

    1. Configure your macOS device to run Tor following these instructions
    2. Download Element for macOS
    3. Click Sign In or Create Account, depending on whether or not you have already created your account
    4. Beneath "Host Account On" (following Create Account), or "Homeserver" (following Sign In), click Edit and change "matrix.org" to http://your_synapse_address_from_interfaces.onion
    5. Complete sign in or account creation

  • Linux

    1. Configure your Linux device to run Tor following these instructions
    2. Download Element for Linux
    3. Because Element app is not Tor-enabled by default, you must launch it from the command line using the following command: element-desktop --proxy-server=socks5://127.0.0.1:9050
    4. Click Sign In or Create Account, depending on whether or not you have already created your account
    5. Beneath "Host Account On" (following Create Account), or "Homeserver" (following Sign In), click Edit and change "matrix.org" to http://your_synapse_address_from_interfaces.onion
    6. Complete sign in or account creation

  • Windows

    1. Configure your Windows device to run Tor following these instructions
    2. Download Element for Windows
    3. Right click on Element app icon
    4. Click "Properties"
    5. On the "Shortcut" tab, add --proxy-server=socks5://127.0.0.1:9050 to the end of the "Target" field. Please note, there must be a space between ...Element.exe and --proxy...
    6. Click Sign In or Create Account, depending on whether or not you have already created your account
    7. Beneath "Host Account On" (following Create Account), or "Homeserver" (following Sign In), click Edit and change "matrix.org" to http://your_synapse_address_from_interfaces.onion
    8. Complete sign in or account creation

  • Android

    1. Configure your Android device to run Tor following these instructions
    2. Download Element for Android
    3. Add Element to the list of VPN apps inside Orbot
    4. In the Element app, you will be asked to "Select a Server." Choose "Other," and enter http://your_synapse_address_from_interfaces.onion
    5. Complete sign in or account creation. If you are asked to 'Trust' a certificate, go ahead and do so. This is safe to do as you are the server operator and traffic is already over Tor

  • iOS

    1. Configure your iOS device to run Tor following these instructions
    2. Download Element app for iOS
    3. In the Element app, you will be asked to "Select a Server." Choose "Other," and enter http://your_synapse_address_from_interfaces.onion
    4. Complete sign in or account creation. If you are asked to 'Trust' a certificate, go ahead and do so. This is safe to do as you are the server operator and traffic is already over Tor


Step 4: Enable Cross Signing

  1. Go to Settings --> Security & Privacy --> Cross-signing
  2. If you see a green checkmark with Cross-signing is ready for use, then you are good to go
  3. If you see Cross-signing has not been set up, then click Set Up, then follow the instructions to complete setup
  4. Alternatively, if you see Cross-signing is ready but keys are not backed up, follow the backup instructions in Step 4

Explanation: The Matrix protocol uses advanced cryptography to ensure that you are, in fact, communicating with the people you think you are, and not impostors. To make this as simple as possible, Matrix offers something called Cross Signing, which allows users to verify each other, and then for each user to verify their own various devices. The alternative is that every user would need to verify every device of everyone they interact with, which is simply annoying. You can read more about Cross Signing here.



Step 5: Joining a Remote Room

  1. On the main dashboard, select Explore Public Rooms.
  2. In the search field, paste in the alias of the room you want to join. Room aliases start with #. For example, if you want to join a room on a friend's server, you would need their .onion address and the room name. It would look something like this: #room-name:yxtgpdjhafirrf3jskstue3bcs5wrrj47u4ljbmcgrubq46uxwpz7fad.onion. Then click ↲ Join.
  3. Joining a room can take a while, depending on how many users are currently in the room. If it fails, simply try again.
  4. Please note that to join a room on a remote server over federation, you need to know the .onion address of that server. This is like sharing secrets between each other, but the secret is one party's V3 .onion homeserver address with the room name.


Step 6: Creating Backups - Important, Read Carefully!

Encryption Keys: Matrix uses end-to-end (E2E) encryption, meaning all encryption/decryption is performed locally on your phone/computer using keys stored on the device. To further complicate things, these keys are frequently changed to ensure maximum security. And to even further complicate things, when you log out of Element, these keys are purged from memory. Meaning, if you log out of all your Element client apps, you will lose your keys and be unable to decrypt your own message history!

Message History: Additionally, your entire (encrypted) message history is stored on your personal Synapse server, which is running on your physical Start9 server. So there are two, separate types of backups that are needed: (1) the encryption keys on your device and (2) the message history on your Start9 server.

  • Backing up encryption keys

    There are two methods of backing up encryption keys: Manual and Automatic

    • Manual

      Because your encryption keys are rotated frequently, it is almost impossible to perform manual backups and guarantee that all messages can be recovered. However, performing periodic backups can at least ensure the recovery of messages up until that point in time.

      1. In your Element app, go to Settings --> Security & Privacy --> Cryptography --> "Export E2E room keys"
      2. Optionally enter a passphrase to protect the backup and save the file somewhere safe
      3. Remember, the keys involved in this backup will only be capable of decrypting messages up until the time of backup. New messages will likely be unrecoverable
    • Automatic

      This option will automatically store encrypted backups of your keys on your Start9 server whenever they are rotated and is the recommended way of doing key backup

      1. In your Element app, go to Settings --> Security & Privacy --> Secure Backup --> "Set up".
      2. You will be prompted to select either Generate a Security Key or Enter a Security Phrase. This is a misleading choice. Either way, Element will generate a security key. If you select Generate a Security Key (recommended), Element will display the Security Key for you to store on your own. If you select Enter a Security Phrase, Element will encrypt the Security Key with your Security Phrase, then store it on your Start9 server. In the former case, you will need to keep and protect a private key. In the latter case, you will need to keep and protect a chosen passphrase. Either way, you will need to store something. The reason it is recommended to select Generate a Security Key is because, if someone gets access to your Synapse server, it is far more likely they will guess your chosen passphrase than be able to brute force a private key.
      3. Regardless of which option you choose, you must store the value somewhere safe. Do not lose it!. It is recommended to store it in your self-hosted Bitwarden.

  • Backing up message history

    All of your (encrypted) messages are securely stored on your dedicated Start9 server. Given the importance of preserving your data, it is crucial to regularly create backups of Synapse on StartOS to ensure its protection and availability.