commit 4cb8a33f529d8037edc990dc9bf4052c684de160
parent 59fe3fe5fc47c5932b261afd787cb2735f6c47c2
Author: Nick Econopouly <wry@mm.st>
Date: Fri, 19 Feb 2021 15:56:43 -0500
Add changelog and .gitignore
Diffstat:
8 files changed, 666 insertions(+), 813 deletions(-)
diff --git a/.gitignore b/.gitignore
@@ -0,0 +1 @@
+_build/*+
\ No newline at end of file
diff --git a/changelog.md b/changelog.md
@@ -0,0 +1,38 @@
+# Changelog
+
+I'm documenting what I've done with the docs here for SFL. We will
+delete this page once the new docs get accepted for docs.jami.net
+
+
+- added "How to contribute to this documentation"
+- refactored build guide (old build page should still be checked to make sure I didn't remove anything important)
+- rewrote introduction
+- organized everything into a series of chapters like "General", "Technical Reference", etc (every page can be accessed at any time through the sidebar)
+- removed handwritten tables of contents in pages and replaced them with autogenerated TOCs
+- fixed grammer and spelling in FAQ; added all questions from the old Ring FAQ that hadn't been added yet; added everything from the website FAQ; combined some similar questions
+- Old links were out of date and not very useful, but just in case, here they are:
+ - <https://web.archive.org/web/20181226012503/https://ring.cx/en/documentation/faq>
+ - <https://web.archive.org/web/20181226012541/https://ring.cx/en/about/privacy-and-anonymity>
+ - <https://web.archive.org/web/20180224163130/https://ring.cx/en/about/practical>
+ - old wiki link no longer works: <https://tuleap.ring.cx/plugins/mediawiki/wiki/ring/index.php?title=Special:AllPages>
+- added some new questions to the FAQ
+- added all relevant questions from the jami.net FAQ to this FAQ (we should just have one document)
+- made all headlines in the FAQ questions
+- uploads/media are now located in the same directory as the document that refers to them
+ - if documents from multiple chapters refer to a file, the file can go in the media/ directory
+- renamed guides to "How to..." based on this advice: <https://documentation.divio.com/how-to-guides/>
+- Changed filenames to lowercase-with-hyphens, and use .md for markdown and .txt for reStructuredText following this: <https://documentation-style-guide-sphinx.readthedocs.io/en/latest/style-guide.html>
+ - all documents should only have one h1, which becomes the title of the document
+- Moved most of the audio/video stuff into a separate "troubleshooting" page; IMO these types of troubleshooting questions aren't meant for the FAQ and they make it look bad. Some of them should be deleted alltogether, for instance questions asking the location of a setting which is just sitting there in the "general settings" page.
+
+
+
+
+
+Notes:
+
+- FAQ is pretty large. I don't know if parts of it should be moved to other pages
+
+- the "General" chapter should remain the top priority; we should be open to debate about which things to include or exclude, and we should strive to keep the chapter complete and correct. 99% of users won't read the other chapters. The first chapter is still an entry point, so it counts as marketing as well as documentation.
+
+- Linking guide: from the "General" chapter, only link to other documents in the same chapter, except for the technical overview, which can link to the technical reference. For instance, in the FAQ, link to the name server heading of the Technical Overview, but in the Technical Overview, you can link to the name server page of the technical reference (there are a few exceptions, like linking to "How to contribute")
diff --git a/general/all-features-by-client.rst b/general/all-features-by-client.txt
diff --git a/general/faq.rst b/general/faq.rst
@@ -1,617 +0,0 @@
-FAQ
-===
-
-This is an exhaustive list of frequently asked questions, including
-some technical questions.
-
-.. contents::
- :local:
- :depth: 3
-
-Basics
-------
-
-What is Jami?
-~~~~~~~~~~~~~
-
-Read the :doc:`Introduction <introduction>`.
-
-What makes Jami different from other communication platforms?
-~~~~~~~~~~~~~~~~~~~~~
-
-Jami doesn't work like most communication platforms because it is
-*distributed*:
-
-.. image:: distributed-network-topo.png
-
-Some of the consequences may seem surprising. For instance, since
-accounts are stored on your device, passwords are optional. However,
-the most significant practical differences are that you have more
-*freedom* and *privacy*.
-
-TODO: expand on this
-
-What do the red/green status circles next to avatars mean?
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-On your own account, a red circle means that you aren't connected to
-the DHT. You may need to check your connection or restart the app.
-
-On other contacts, a red circle means that they are not online, and a
-green circle means they are online and you should be able to message
-them.
-
-Note that a green circle only means that the contact has announced
-their presence on the DHT. It does not indicate a direct connection to
-their device. In some cases, a contact may be able to send and receive
-DHT messages but cannot make calls or file transfers because of their
-firewall.
-
-
-Why is a feature missing on my client?
-~~~~~~~~~~~~~~~~~~~~
-
-Not every client implements all features; check the list :doc:`here
-<all-features-by-client>` to see if your client is missing the
-feature.
-
-You can make feature requests at
-https://git.jami.net/.
-
-Does Jami support read reciepts? Can I turn them on or off?
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-You can enable or disable read receipts on Android. Other platforms
-only have partial or no support. Please see :doc:`All Features by
-Client <all-features-by-client>` for the current status.
-
-Does Jami support typing notifications? Can I turn them on or off?
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Most of the client support sending and receiving typing
-notifications. You can enable/disable them in the general settings.
-
-Can I share my screen?
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Yes, on all platforms except for iOS. Search for a dedicated "Share
-screen" button while you are in a video call.
-
-
-Can I make group conference calls?
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-Yes. You can add Jami contacts to existing calls (audio or video) by
-clicking the "Add participant" button.
-
-Does Jami have group chats?
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Not yet. Group chats are `coming soon
-<technical-overview.html#swarms>`_.
-
-
-Why is my contact not seeing my avatar?
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Due to technical limitation, avatars are only transfered to your
-contacts during a video or audio call. This limitation will disappear
-when `group chats <technical-overview.html#swarms>`_ are released.
-
-Why aren't my sent messages showing up on all linked devices?
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-All of your devices receive the same messages from your contacts, but
-*sent* messages will not show up on all of your devices.
-
-The `swarm <technical-overview.html#swarms>`_ update will introduce
-full conversation sync between linked devices for all conversations
-(including one-on-one conversations).
-
-
-
-How can I make a bug report?
-~~~~~~~~~~~~~~
-
-Please see :doc:`How to Make a Bug Report <../guides/how-to-make-a-bug-report>`.
-
-Where are the configuration files located?
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Jami saves its configuration (account, certificates, history) at
-different locations depending the platform.
-
-- **GNU/Linux**: global configuration is under
- **~/.config/jami/dring.yml** and account files are under
- **~/.local/share/jami/**. Finally, a cache can be stored in
- **~/.cache/jami**
-
-
-- **OSX**: The full configuration is under **~/Library/Application Support/Jami** if installed via https://jami.net.
- The app store version uses
- **~/Library/Containers/com.savoirfairelinux.ring.macos/Data/Library/Application Support/jami**
-
-- **Android**: The full configuration is under **/data/data/cx.ring**
- (may require root privileges)
-
-- **Windows**: global configuration is under
- **%AppData%/Local/jami/dring.yml** and Account files are under
- **%AppData%/Local/jami/**. Finally, a cache is stored in
- **%USERPROFILE%/.cache/jami**
-
-Note: audio and video messages are recorded in the local-data in the
-folder: ``sent_data``
-
-TODO: check this ^^^ and add note about file downloads (like images)
-
-How much bandwidth do I need for calls?
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-For audio calls, Jami uses about 100 Kbps. For a video call, you need
-about 2 Mbit/s for medium quality. If your connection is slower, the
-bitrate will be automatically reduced.
-
-If you are hosting a video conference, you will need approximately 2
-Mbps more per participant. For a conference with 10 participants, each
-participants will need 2Mbps up & down and the host will need 20Mbps
-up and down.
-
-Auto-adaptation is done between 200Kbit/s / max:6Mbit/s
-
-TODO: ^^^^^^^^^^^^^ What does this last line mean?
-
-Account management
-------------------
-
-What is a Jami account?
-~~~~~~~~~~~~~~~~~~~~~~~
-
-A Jami account is an `asymmetric encryption key
-<https://en.wikipedia.org/wiki/Public-key_cryptography>`_. Your
-account is identified by a Jami ID, which is a `fingerprint
-<https://en.wikipedia.org/wiki/Public_key_fingerprint>`_ of your
-public key.
-
-What information do I need to provide to create a Jami account?
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-When you create a new Jami account, you don’t have to provide private
-information like an email, address, or phone number.
-
-This is the information you can provide if you choose (it's all
-optional):
-
-1. An avatar
-2. A display name, which is the name that clients will display for
- your contact. It can contain special characters.
-3. An optional username, which is a unique identifier that is directly
- associated with your JamiID. This username->Jami ID mapping is
- stored on a server (ns.jami.net by default, but you can host your
- own)
-4. A password. This password is used to protect the account archive in
- your device.
-
-For more information about Jami accounts, see `the Technical Overview
-<technical-overview.html#what-is-a-jami-account>`_.
-
-Where is my Jami ID?
-~~~~~~~~~~~~~~~~
-
-Your Jami ID should be displayed prominently in whichever app you're
-using. It looks like a long string of numbers and letters:
-``f2c815f5554bcc22689ce84d45aefdda1bce9146``
-
-Why don't I have to use a password?
-~~~~~~~~~~~~
-
-You are not forced to have a password on your account. On a
-centralized system you would use your password to authenticate with a
-public server where your account is stored. Someone who knows your
-password could steal your identity.
-
-With Jami, your account is stored in a `folder
-<#where-are-the-configuration-files-located>`_ on your device. **The
-password is only used to encrypt your account to protect you from
-someone who has physical access to your device.**
-
-If your device is encrypted, you may not want or need to use a
-password.
-
-Why don't I have to register a username?
-~~~~~~~~~~~~
-
-The most permanent, secure identifier is your `Jami Id
-<#where-is-my-jami-id>`_, but since these are difficult to use for
-some people, you also have the option of registering a
-username. Username registration requires a name server, such as Jami's
-default one at ns.jami.net.
-
-If you don't register a username, you can still choose to register one
-later at any time.
-
-Can I change my username?
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-With the default nameserver you cannot change your username.
-
-What is the difference between a username and a display name?
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-You can use your username as an identifier. The username points to
-your `Jami Id <#where-is-my-jami-id>`_, which is your permanent,
-secure identifier. Two people cannot have the same username.
-
-A display name allows you to choose another name that identifies you
-to your contacts. Display names can be edited or changed at any time
-and only your contacts can see them.
-
-
-How can I back up my account?
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-There are two ways to back-up your account:
-
-1. Link another device to your account so your account will be on two
- devices. You can find this option in the account settings page.
-2. Back up the `account archive
- <technical-overview.html#account-storage-and-backup>`_ . This file
- can be found in the account files `folder
- <#where-are-the-configuration-files-located>`_. In some clients,
- you can export this archive from the account settings.
-
-Can I retrieve my username without my keys?
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-If you used the default name server at ``ns.jami.net``, **you
-can’t**. There is no way to prove it’s your username without your key.
-
-If you use a different name server, there may be a way to move a
-username to a new Jami Id at the discretion of the administrator of
-that name server.
-
-For more information about name servers, see `the Technical Overview
-<technical-overview.html#name-servers>`_.
-
-Can I recover my account if I forget my password?
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-No. There can't be a traditional account recovery process; you are the
-only person with access to your data. If you are worried about
-forgetting your password, please use a password manager.
-
-What happens when I delete my account?
-~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Your account is only stored on your own devices. If you delete your
-account from each device, the account is gone and you cannot get it
-back. Nobody else can use your account after that.
-
-Your contacts will still have the messages you sent them, but all
-public record of your account on the DHT will disappear.
-
-**Note for accounts with a username:**
-
-The default nameserver at ``ns.jami.net`` will not delete your
-username, but nobody will be able to message you at that username or
-register a new account with that username.
-
-Other name servers may allow username deletion (not recommended) at
-the administrator's discretion.
-
-If you do not want to lose your account, please `back it up
-<#how-can-i-back-up-my-account>`_!
-
-What happens when I link a new device?
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-When you link a device to your account, your `account archive
-<technical-overview.html#account-storage-and-backup>`_ is put on the
-Jami network for a few minutes. It is protected by a password Jami
-gives you.
-
-The new device receives your full account certificate with the master
-RSA keys, but it generates a new device key for signing/encrypting
-messages.
-
-Advanced
---------
-
-What protocol does Jami use for the end-to-end encryption?
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-We use TLS 1.3 with a perfect forward secrecy requirement for the
-negotiated ciphers for calls and file transfers. Messages are
-encrypted with an RSA key.
-
-
-What data passes through my machine when I participate in the Jami network?
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-**All these data are encrypted**. There is:
-
-- ICE descriptors of other Jami users. ICE is a protocol that help
- establishing communication between two computers
-- certain text messages
-- as indicated above, accounts currently being linked to a new device
-
-Audio/video streams and some text messages pass through the VOIP
-protocol. Text messages can be sent either via VOIP or DHT (the
-distributed network) depending on whether a VOIP communication channel
-is already open or not.
-
-Why am I able to communicate with myself?
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Many users use Jami to transfer data from one machine to another.
-
-Should I enable push notifications?
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Push notifications allow Jami to operate in a way more adapted to the
-context of mobility (energy consumption, data…). However, for the
-moment, notifications go through Google’s servers, via the Firebase
-service. Only one identifier is transferred and it is unusable for
-anyone who does not have access to your account.
-
-What is a bootstrap server?
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-TODO
-
-What is a TURN server? What is STUN?
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-TODO
-
-What is DHT proxy?
-~~~~~~~~~~~~~~~~~~
-
-The DHT proxy is a server that registers on the DHT for you and relays
-your information to you. Thus, it is the server that will be active on
-the DHT and will participate in the network, and no longer the target
-device. Multiple devices can register on the same DHT proxy.
-
-How the username registration service work?
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-For default parameters the usernames are registered on an Ethereum
-blockchain. By default, it’s ns.jami.net that is used, but if you are a
-developper, you can create your own system. Hence, nothing forces you to
-implement it with a blockchain. You can check results at
-http://ns.jami.net/name/test, where “test” is a username for which we
-are looking for a matching `Infohashs <guidelines/Identifiers>`__. Once
-registered, this server doesn’t provide a way to remove the mapping.
-More informations there:
-https://git.jami.net/savoirfairelinux/ring-project/wikis/technical/Name-Server-Protocol
-
-How can I change the timeout for a call?
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-In the ``dring.yml`` file, you can change your ringingTimeout (in
-seconds)
-
-How to back up and reimport conversations and accounts
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Note: This is only for client based on LRC (desktop ones)
-
-First you will need to export all your accounts (For GNU/Linux: Settings
-=> Account => Export account). Then you will need to copy the database
-(in ``~/.local/share/jami`` for example).
-
-Then on the new device, when you will open Jami for the first time, you
-have to re-import your accounts via the archive previously saved. This
-will re-import your settings and contacts (with empty conversations).
-Then close the client and replace the database with the one previously
-saved. That’s all!
-
-How secure are you?
-~~~~~~~~~~~~~~~~~~~
-
-\*\* We use TLS/SRTP to secure connection and communications over the
-network.*\*
-
-We implement SRTP over SIP using recommendations written in following
-RFCs:
-
-- ```http://tools.ietf.org/html/rfc3711`` <http://tools.ietf.org/html/rfc3711>`__
-- ```http://tools.ietf.org/html/rfc4568`` <http://tools.ietf.org/html/rfc4568>`__
-
-Typically 2 kind of sockets are negotiated. One for the control socket,
-the other for the media sockets
-
-Typical control session will use the following cipher suite:
-(TLS1.3)-(ECDHE-SECP384R1)-(RSA-PSS-RSAE-SHA384)-(AES-256-GCM)
-(TLS_ECDHE_RSA_AES_256_GCM_SHA384)
-
-DTLS (fallback) supported:
-“SECURE192:-KX-ALL:+ANON-ECDH:+ANON-DH:+SECURE192:-VERS-TLS-ALL:+VERS-DTLS-ALL:-RSA:%SERVER_PRECEDENCE:%SAFE_RENEGOTIATION”
-TLS:
-“SECURE192:-KX-ALL:+ANON-ECDH:+ANON-DH:+SECURE192:-RSA:-GROUP-FFDHE4096:-GROUP-FFDHE6144:-GROUP-FFDHE8192:+GROUP-X25519:%SERVER_PRECEDENCE:%SAFE_RENEGOTIATION”
-
-Supported crypto suite for the media session are:
-
-- AES_CM_128_HMAC_SHA1_80 / SRTP_AES128_CM_HMAC_SHA1_80
-- AES_CM_128_HMAC_SHA1_32 / SRTP_AES128_CM_HMAC_SHA1_32
-
-When do public IPs get exposed?
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-We can describe 3 main connectivity scenarios. A classic configuration
-(1.), behind a VPN (2.), via Tor (3.). As Jami is a p2p app, I think you
-understand that (2.) or (3.) is a bit mandatory to avoid IP leaking.
-
-Moreover, even if it’s my answer, you can choose to not trust my answer
-and check the code, or use wireshark or other tools. Generally, I (and
-the other devs I think) are using the first scenario (sometimes the
-second one), and we surely can’t test all the network we want, so if you
-discover a bug, please open a issue.
-
-Anyway, in these 3 scenarios, there is 3 main actions:
-
-- Send a message (this will use the DHT)
-- Send a file (TCP ICE connection as described here:
- https://git.jami.net/savoirfairelinux/ring-project/wikis/technical/2.5.%20File%20transfer)
-- Do a call (TCP + UDP ICE connection as described here:
- https://git.jami.net/savoirfairelinux/ring-project/wikis/technical/2.4.%20Let’s%20do%20a%20call)
-
-Classic config
-^^^^^^^^^^^^^^
-
-- Send a message
-
-The Jami application is running a DHT (https://opendht.net) node on your
-device. So every operations on the DHT will use your ips. This is why
-Jami has the option to use a dhtproxy (eg dhtproxy.jami.net), this will
-avoid to use your node, but will use another node on the network (which
-will see your ip). Note that your message is not sent directly to the
-other device. In fact your message is sent on some nodes of the DHT and
-your contact will retrieve the message on this node. So, your contact
-don’t see your IP at this step, but the node who get the message will
-(or they will see the IP of the proxy).
-
-- Send a file
-
-As described in the docs, you will send a message with all the IP you
-know that your peer can contact in an encrypted packet. So, if your peer
-send you a file or you send a file, your addresses will appear in the
-ICE message.
-
-- Calls
-
-Same as above, the IP is present in the ICE.
-
-Behind a VPN
-^^^^^^^^^^^^
-
-- Send a message
-
-The IP of your VPN will be used by the DHT node. If you want a proof,
-you can compile dhtnode and run the ‘la’ command to get your public
-detected address. This is what I got:
-
-::
-
- ./tools/dhtnode -b bootstrap.jami.net
- Bootstrap: bootstrap.jami.net:4222
- OpenDHT node be58fdc9f782269bfc0bbfc21a60bca5f02cb881 running on port 54299
- (type 'h' or 'help' for a list of possible commands)
-
- >> la
- Reported public addresses:
- IPs OF MY VPN
-
-So, if you don’t use a proxy, your VPN addresses will be used for using
-the DHT. If you use a dhtproxy, the dhtproxy will see your VPN addresses
-
-- Send a file
-
-Same as above, the ICE will contains: + addresses from your LAN + public
-address of your VPN + TURN address if TURN is enabled
-
-- Do a call
-
-Same as above, your public address is replaced by your VPN address. You
-can see it in the logs from daemon. See
-https://git.jami.net/savoirfairelinux/ring-project/wikis/tutorials/Bug-report-guide#logs
-
-Tor
-^^^
-
-- Send a message
-
-Tor basically doesn’t supports UDP. This means that you can’t use your
-DHT node locally, you MUST use a DHTProxy. That proxy will see the Exit
-node.
-
-- Send a file
-
-I prefer a proof that any description. So, I did a file transfer with
-Jami + TOR. This is what I see in the logs for the remote:
-
-::
-
- [1574218330.556|10688|p2p.cpp :241 ] [Account:93a03f519f394143] add remote ICE candidate: Hc0a8c801 1 TCP 2130706431 192.168.200.1 33293 typ host tcptype passive
- [1574218330.556|10688|p2p.cpp :241 ] [Account:93a03f519f394143] add remote ICE candidate: Hc0a8c801 1 TCP 2130706431 192.168.200.1 9 typ host tcptype active
- [1574218330.556|10688|p2p.cpp :241 ] [Account:93a03f519f394143] add remote ICE candidate: Hc0a80103 1 TCP 2130706431 192.168.1.3 33293 typ host tcptype passive
- [1574218330.556|10688|p2p.cpp :241 ] [Account:93a03f519f394143] add remote ICE candidate: Hc0a80103 1 TCP 2130706431 192.168.1.3 9 typ host tcptype active
- [1574218330.556|10688|p2p.cpp :241 ] [Account:93a03f519f394143] add remote ICE candidate: R33fe279d 1 TCP 16777215 51.254.39.157 27427 typ relay tcptype passive
- [1574218330.556|10688|p2p.cpp :241 ] [Account:93a03f519f394143] add remote ICE candidate: Sc0a8c801 1 TCP 1694498815 185.220.101.24 33293 typ srflx tcptype passive
-
-The first ones are some 192.168.x.x so we don’t care. 51.254.39.157 is
-the TURN address in France (my device is in the Canada). 185.220.101.24
-is the Tor exit node:
-
-::
-
- inetnum: 185.220.101.0 - 185.220.101.127
- netname: MK-TOR-EXIT
-
-- Do a call
-
-This will not work (actually, you can create the SIP control connection
-because it’s a TCP connection), but medias are negotiated in UDP, so
-this will fail.
-
-What ports does Jami use?
-~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Jami works as a server and gets new ports for each connections (randomly
-binded). These are the ranges that can be used for each component:
-
-- dht: UDP [4000, 8888]
-- audio: UDP [16384-32766]
-- video: UDP [49152-65534]
-- SIP Control: UDP/TCP randomly binded
-
-So for ufw, we recommend to run: ``sudo ufw default allow outgoing``
-
-For now, you can’t specify a specific range to configure ports used by
-Jami. The inbound traffic can be controlled without issue, Jami should
-work and can use a TURN server if needed.
-
-If you run your own proxy or nameserver:
-
-- dhtproxy, nameserver: TCP [80-100], 443
-
-If you run your own TURN server:
-
-- TURN/STUN: TCP+UDP 3478, 5349
-
-How can I configure the codecs even more?
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Codecs can be configured via a file. In the configurations files, you
-can create a file called ``encoder.json`` like this:
-
-::
-
- {
- "libx264": {
- "profile": 100,
- "level": 42,
- "crf": 20,
- "preset": "ultrafast"
- },
- "h264_vaapi": {
- "low_power": 1
- },
- "libopus": {
- "application": "voip"
- }
- }
-
-or:
-
-::
-
- {
- "libopus": {
- "bit_rate": 128000
- }
- }
-
-This file is located in the same directory of
-```dring.yml`` <#basics-5>`__
-
-The best way to check which options are supported is through the command
-“ffmpeg -h encoder=[encoder_name]” where encoder_name can be whichever
-of libx264, libvpx, mpeg4, h263, libopus, libspeex, g722, pcm_alaw,
-pcm_mulaw (FFmpeg names for all of Jami’s supported encoders).
diff --git a/general/faq.txt b/general/faq.txt
@@ -0,0 +1,625 @@
+FAQ
+===
+
+This is an exhaustive list of frequently asked questions, including
+some technical questions.
+
+.. contents::
+ :local:
+ :depth: 3
+
+Basics
+------
+
+What is Jami?
+~~~~~~~~~~~~~
+
+Read the :doc:`Introduction <introduction>`.
+
+What makes Jami different from other communication platforms?
+~~~~~~~~~~~~~~~~~~~~~
+
+Jami doesn't work like most communication platforms because it is
+*distributed*:
+
+.. image:: distributed-network-topo.png
+
+Some of the consequences may seem surprising. For instance, since
+accounts are stored on your device, passwords are optional. However,
+the most significant practical differences are that you have more
+*freedom* and *privacy*.
+
+TODO: expand on this
+
+What do the red/green status circles next to avatars mean?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+On your own account, a red circle means that you aren't connected to
+the DHT. You may need to check your connection or restart the app.
+
+On other contacts, a red circle means that they are not online, and a
+green circle means they are online and you should be able to message
+them.
+
+Note that a green circle only means that the contact has announced
+their presence on the DHT. It does not indicate a direct connection to
+their device. In some cases, a contact may be able to send and receive
+DHT messages but cannot make calls or file transfers because of their
+firewall.
+
+
+Why is a feature missing on my client?
+~~~~~~~~~~~~~~~~~~~~
+
+Not every client implements all features; check the list :doc:`here
+<all-features-by-client>` to see if your client is missing the
+feature.
+
+You can make feature requests at
+https://git.jami.net/.
+
+Does Jami support read reciepts? Can I turn them on or off?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+You can enable or disable read receipts on Android. Other platforms
+only have partial or no support. Please see :doc:`All Features by
+Client <all-features-by-client>` for the current status.
+
+Does Jami support typing notifications? Can I turn them on or off?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Most of the client support sending and receiving typing
+notifications. You can enable/disable them in the general settings.
+
+Can I share my screen?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Yes, on all platforms except for iOS. Search for a dedicated "Share
+screen" button while you are in a video call.
+
+
+Can I make group conference calls?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Yes. You can add Jami contacts to existing calls (audio or video) by
+clicking the "Add participant" button.
+
+Does Jami have group chats?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Not yet. Group chats are `coming soon
+<technical-overview.html#swarms>`_.
+
+
+Why is my contact not seeing my avatar?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Due to technical limitation, avatars are only transfered to your
+contacts during a video or audio call. This limitation will disappear
+when `group chats <technical-overview.html#swarms>`_ are released.
+
+Why aren't my sent messages showing up on all linked devices?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+All of your devices receive the same messages from your contacts, but
+*sent* messages will not show up on all of your devices.
+
+The `swarm <technical-overview.html#swarms>`_ update will introduce
+full conversation sync between linked devices for all conversations
+(including one-on-one conversations).
+
+
+
+How can I make a bug report?
+~~~~~~~~~~~~~~
+
+Please see :doc:`How to Make a Bug Report <../guides/how-to-make-a-bug-report>`.
+
+Where are the configuration files located?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Jami saves its configuration (account, certificates, history) at
+different locations depending the platform.
+
+- **GNU/Linux**: global configuration is under
+ **~/.config/jami/dring.yml** and account files are under
+ **~/.local/share/jami/**. Finally, a cache can be stored in
+ **~/.cache/jami**
+
+
+- **OSX**: The full configuration is under **~/Library/Application Support/Jami** if installed via https://jami.net.
+ The app store version uses
+ **~/Library/Containers/com.savoirfairelinux.ring.macos/Data/Library/Application Support/jami**
+
+- **Android**: The full configuration is under **/data/data/cx.ring**
+ (may require root privileges)
+
+- **Windows**: global configuration is under
+ **%AppData%/Local/jami/dring.yml** and Account files are under
+ **%AppData%/Local/jami/**. Finally, a cache is stored in
+ **%USERPROFILE%/.cache/jami**
+
+Note: audio and video messages are recorded in the local-data in the
+folder: ``sent_data``
+
+TODO: check this ^^^ and add note about file downloads (like images)
+
+How much bandwidth do I need for calls?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+For audio calls, Jami uses about 100 Kbps. For a video call, you need
+about 2 Mbit/s for medium quality. If your connection is slower, the
+bitrate will be automatically reduced.
+
+If you are hosting a video conference, you will need approximately 2
+Mbps more per participant. For a conference with 10 participants, each
+participants will need 2Mbps up & down and the host will need 20Mbps
+up and down.
+
+Auto-adaptation is done between 200Kbit/s / max:6Mbit/s
+
+TODO: ^^^^^^^^^^^^^ What does this last line mean?
+
+TODO: How can SFL afford to give Jami away for free? How does/will SFL make money off Jami?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Summary: ethical company, they will make money supporting managed Jami
+solutions for organizations; their main source of income is elsewhere;
+all Jami code is GPL3 etc. etc.
+
+
+Account management
+------------------
+
+What is a Jami account?
+~~~~~~~~~~~~~~~~~~~~~~~
+
+A Jami account is an `asymmetric encryption key
+<https://en.wikipedia.org/wiki/Public-key_cryptography>`_. Your
+account is identified by a Jami ID, which is a `fingerprint
+<https://en.wikipedia.org/wiki/Public_key_fingerprint>`_ of your
+public key.
+
+What information do I need to provide to create a Jami account?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+When you create a new Jami account, you don’t have to provide private
+information like an email, address, or phone number.
+
+This is the information you can provide if you choose (it's all
+optional):
+
+1. An avatar
+2. A display name, which is the name that clients will display for
+ your contact. It can contain special characters.
+3. An optional username, which is a unique identifier that is directly
+ associated with your JamiID. This username->Jami ID mapping is
+ stored on a server (ns.jami.net by default, but you can host your
+ own)
+4. A password. This password is used to protect the account archive in
+ your device.
+
+For more information about Jami accounts, see `the Technical Overview
+<technical-overview.html#what-is-a-jami-account>`_.
+
+Where is my Jami ID?
+~~~~~~~~~~~~~~~~
+
+Your Jami ID should be displayed prominently in whichever app you're
+using. It looks like a long string of numbers and letters:
+``f2c815f5554bcc22689ce84d45aefdda1bce9146``
+
+Why don't I have to use a password?
+~~~~~~~~~~~~
+
+You are not forced to have a password on your account. On a
+centralized system you would use your password to authenticate with a
+public server where your account is stored. Someone who knows your
+password could steal your identity.
+
+With Jami, your account is stored in a `folder
+<#where-are-the-configuration-files-located>`_ on your device. **The
+password is only used to encrypt your account to protect you from
+someone who has physical access to your device.**
+
+If your device is encrypted, you may not want or need to use a
+password.
+
+Why don't I have to register a username?
+~~~~~~~~~~~~
+
+The most permanent, secure identifier is your `Jami Id
+<#where-is-my-jami-id>`_, but since these are difficult to use for
+some people, you also have the option of registering a
+username. Username registration requires a name server, such as Jami's
+default one at ns.jami.net.
+
+If you don't register a username, you can still choose to register one
+later at any time.
+
+Can I change my username?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+With the default nameserver you cannot change your username.
+
+What is the difference between a username and a display name?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+You can use your username as an identifier. The username points to
+your `Jami Id <#where-is-my-jami-id>`_, which is your permanent,
+secure identifier. Two people cannot have the same username.
+
+A display name allows you to choose another name that identifies you
+to your contacts. Display names can be edited or changed at any time
+and only your contacts can see them.
+
+
+How can I back up my account?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+There are two ways to back-up your account:
+
+1. Link another device to your account so your account will be on two
+ devices. You can find this option in the account settings page.
+2. Back up the `account archive
+ <technical-overview.html#account-storage-and-backup>`_ . This file
+ can be found in the account files `folder
+ <#where-are-the-configuration-files-located>`_. In some clients,
+ you can export this archive from the account settings.
+
+Can I retrieve my username without my keys?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If you used the default name server at ``ns.jami.net``, **you
+can’t**. There is no way to prove it’s your username without your key.
+
+If you use a different name server, there may be a way to move a
+username to a new Jami Id at the discretion of the administrator of
+that name server.
+
+For more information about name servers, see `the Technical Overview
+<technical-overview.html#name-servers>`_.
+
+Can I recover my account if I forget my password?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+No. There can't be a traditional account recovery process; you are the
+only person with access to your data. If you are worried about
+forgetting your password, please use a password manager.
+
+What happens when I delete my account?
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Your account is only stored on your own devices. If you delete your
+account from each device, the account is gone and you cannot get it
+back. Nobody else can use your account after that.
+
+Your contacts will still have the messages you sent them, but all
+public record of your account on the DHT will disappear.
+
+**Note for accounts with a username:**
+
+The default nameserver at ``ns.jami.net`` will not delete your
+username, but nobody will be able to message you at that username or
+register a new account with that username.
+
+Other name servers may allow username deletion (not recommended) at
+the administrator's discretion.
+
+If you do not want to lose your account, please `back it up
+<#how-can-i-back-up-my-account>`_!
+
+What happens when I link a new device?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+When you link a device to your account, your `account archive
+<technical-overview.html#account-storage-and-backup>`_ is put on the
+Jami network for a few minutes. It is protected by a password Jami
+gives you.
+
+The new device receives your full account certificate with the master
+RSA keys, but it generates a new device key for signing/encrypting
+messages.
+
+Advanced
+--------
+
+What protocol does Jami use for the end-to-end encryption?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+We use TLS 1.3 with a perfect forward secrecy requirement for the
+negotiated ciphers for calls and file transfers. Messages are
+encrypted with an RSA key.
+
+
+What data passes through my machine when I participate in the Jami network?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+**All these data are encrypted**. There is:
+
+- ICE descriptors of other Jami users. ICE is a protocol that help
+ establishing communication between two computers
+- certain text messages
+- as indicated above, accounts currently being linked to a new device
+
+Audio/video streams and some text messages pass through the VOIP
+protocol. Text messages can be sent either via VOIP or DHT (the
+distributed network) depending on whether a VOIP communication channel
+is already open or not.
+
+Why am I able to communicate with myself?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Many users use Jami to transfer data from one machine to another.
+
+Should I enable push notifications?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Push notifications allow Jami to operate in a way more adapted to the
+context of mobility (energy consumption, data…). However, for the
+moment, notifications go through Google’s servers, via the Firebase
+service. Only one identifier is transferred and it is unusable for
+anyone who does not have access to your account.
+
+What is a bootstrap server?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+TODO
+
+What is a TURN server? What is STUN?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+TODO
+
+What is DHT proxy?
+~~~~~~~~~~~~~~~~~~
+
+The DHT proxy is a server that registers on the DHT for you and relays
+your information to you. Thus, it is the server that will be active on
+the DHT and will participate in the network, and no longer the target
+device. Multiple devices can register on the same DHT proxy.
+
+How the username registration service work?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+For default parameters the usernames are registered on an Ethereum
+blockchain. By default, it’s ns.jami.net that is used, but if you are a
+developper, you can create your own system. Hence, nothing forces you to
+implement it with a blockchain. You can check results at
+http://ns.jami.net/name/test, where “test” is a username for which we
+are looking for a matching `Infohashs <guidelines/Identifiers>`__. Once
+registered, this server doesn’t provide a way to remove the mapping.
+More informations there:
+https://git.jami.net/savoirfairelinux/ring-project/wikis/technical/Name-Server-Protocol
+
+How can I change the timeout for a call?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+In the ``dring.yml`` file, you can change your ringingTimeout (in
+seconds)
+
+How to back up and reimport conversations and accounts
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Note: This is only for client based on LRC (desktop ones)
+
+First you will need to export all your accounts (For GNU/Linux: Settings
+=> Account => Export account). Then you will need to copy the database
+(in ``~/.local/share/jami`` for example).
+
+Then on the new device, when you will open Jami for the first time, you
+have to re-import your accounts via the archive previously saved. This
+will re-import your settings and contacts (with empty conversations).
+Then close the client and replace the database with the one previously
+saved. That’s all!
+
+How secure are you?
+~~~~~~~~~~~~~~~~~~~
+
+\*\* We use TLS/SRTP to secure connection and communications over the
+network.*\*
+
+We implement SRTP over SIP using recommendations written in following
+RFCs:
+
+- ```http://tools.ietf.org/html/rfc3711`` <http://tools.ietf.org/html/rfc3711>`__
+- ```http://tools.ietf.org/html/rfc4568`` <http://tools.ietf.org/html/rfc4568>`__
+
+Typically 2 kind of sockets are negotiated. One for the control socket,
+the other for the media sockets
+
+Typical control session will use the following cipher suite:
+(TLS1.3)-(ECDHE-SECP384R1)-(RSA-PSS-RSAE-SHA384)-(AES-256-GCM)
+(TLS_ECDHE_RSA_AES_256_GCM_SHA384)
+
+DTLS (fallback) supported:
+“SECURE192:-KX-ALL:+ANON-ECDH:+ANON-DH:+SECURE192:-VERS-TLS-ALL:+VERS-DTLS-ALL:-RSA:%SERVER_PRECEDENCE:%SAFE_RENEGOTIATION”
+TLS:
+“SECURE192:-KX-ALL:+ANON-ECDH:+ANON-DH:+SECURE192:-RSA:-GROUP-FFDHE4096:-GROUP-FFDHE6144:-GROUP-FFDHE8192:+GROUP-X25519:%SERVER_PRECEDENCE:%SAFE_RENEGOTIATION”
+
+Supported crypto suite for the media session are:
+
+- AES_CM_128_HMAC_SHA1_80 / SRTP_AES128_CM_HMAC_SHA1_80
+- AES_CM_128_HMAC_SHA1_32 / SRTP_AES128_CM_HMAC_SHA1_32
+
+When do public IPs get exposed?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+We can describe 3 main connectivity scenarios. A classic configuration
+(1.), behind a VPN (2.), via Tor (3.). As Jami is a p2p app, I think you
+understand that (2.) or (3.) is a bit mandatory to avoid IP leaking.
+
+Moreover, even if it’s my answer, you can choose to not trust my answer
+and check the code, or use wireshark or other tools. Generally, I (and
+the other devs I think) are using the first scenario (sometimes the
+second one), and we surely can’t test all the network we want, so if you
+discover a bug, please open a issue.
+
+Anyway, in these 3 scenarios, there is 3 main actions:
+
+- Send a message (this will use the DHT)
+- Send a file (TCP ICE connection as described here:
+ https://git.jami.net/savoirfairelinux/ring-project/wikis/technical/2.5.%20File%20transfer)
+- Do a call (TCP + UDP ICE connection as described here:
+ https://git.jami.net/savoirfairelinux/ring-project/wikis/technical/2.4.%20Let’s%20do%20a%20call)
+
+Classic config
+^^^^^^^^^^^^^^
+
+- Send a message
+
+The Jami application is running a DHT (https://opendht.net) node on your
+device. So every operations on the DHT will use your ips. This is why
+Jami has the option to use a dhtproxy (eg dhtproxy.jami.net), this will
+avoid to use your node, but will use another node on the network (which
+will see your ip). Note that your message is not sent directly to the
+other device. In fact your message is sent on some nodes of the DHT and
+your contact will retrieve the message on this node. So, your contact
+don’t see your IP at this step, but the node who get the message will
+(or they will see the IP of the proxy).
+
+- Send a file
+
+As described in the docs, you will send a message with all the IP you
+know that your peer can contact in an encrypted packet. So, if your peer
+send you a file or you send a file, your addresses will appear in the
+ICE message.
+
+- Calls
+
+Same as above, the IP is present in the ICE.
+
+Behind a VPN
+^^^^^^^^^^^^
+
+- Send a message
+
+The IP of your VPN will be used by the DHT node. If you want a proof,
+you can compile dhtnode and run the ‘la’ command to get your public
+detected address. This is what I got:
+
+::
+
+ ./tools/dhtnode -b bootstrap.jami.net
+ Bootstrap: bootstrap.jami.net:4222
+ OpenDHT node be58fdc9f782269bfc0bbfc21a60bca5f02cb881 running on port 54299
+ (type 'h' or 'help' for a list of possible commands)
+
+ >> la
+ Reported public addresses:
+ IPs OF MY VPN
+
+So, if you don’t use a proxy, your VPN addresses will be used for using
+the DHT. If you use a dhtproxy, the dhtproxy will see your VPN addresses
+
+- Send a file
+
+Same as above, the ICE will contains: + addresses from your LAN + public
+address of your VPN + TURN address if TURN is enabled
+
+- Do a call
+
+Same as above, your public address is replaced by your VPN address. You
+can see it in the logs from daemon. See
+https://git.jami.net/savoirfairelinux/ring-project/wikis/tutorials/Bug-report-guide#logs
+
+Tor
+^^^
+
+- Send a message
+
+Tor basically doesn’t supports UDP. This means that you can’t use your
+DHT node locally, you MUST use a DHTProxy. That proxy will see the Exit
+node.
+
+- Send a file
+
+I prefer a proof that any description. So, I did a file transfer with
+Jami + TOR. This is what I see in the logs for the remote:
+
+::
+
+ [1574218330.556|10688|p2p.cpp :241 ] [Account:93a03f519f394143] add remote ICE candidate: Hc0a8c801 1 TCP 2130706431 192.168.200.1 33293 typ host tcptype passive
+ [1574218330.556|10688|p2p.cpp :241 ] [Account:93a03f519f394143] add remote ICE candidate: Hc0a8c801 1 TCP 2130706431 192.168.200.1 9 typ host tcptype active
+ [1574218330.556|10688|p2p.cpp :241 ] [Account:93a03f519f394143] add remote ICE candidate: Hc0a80103 1 TCP 2130706431 192.168.1.3 33293 typ host tcptype passive
+ [1574218330.556|10688|p2p.cpp :241 ] [Account:93a03f519f394143] add remote ICE candidate: Hc0a80103 1 TCP 2130706431 192.168.1.3 9 typ host tcptype active
+ [1574218330.556|10688|p2p.cpp :241 ] [Account:93a03f519f394143] add remote ICE candidate: R33fe279d 1 TCP 16777215 51.254.39.157 27427 typ relay tcptype passive
+ [1574218330.556|10688|p2p.cpp :241 ] [Account:93a03f519f394143] add remote ICE candidate: Sc0a8c801 1 TCP 1694498815 185.220.101.24 33293 typ srflx tcptype passive
+
+The first ones are some 192.168.x.x so we don’t care. 51.254.39.157 is
+the TURN address in France (my device is in the Canada). 185.220.101.24
+is the Tor exit node:
+
+::
+
+ inetnum: 185.220.101.0 - 185.220.101.127
+ netname: MK-TOR-EXIT
+
+- Do a call
+
+This will not work (actually, you can create the SIP control connection
+because it’s a TCP connection), but medias are negotiated in UDP, so
+this will fail.
+
+What ports does Jami use?
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Jami works as a server and gets new ports for each connections (randomly
+binded). These are the ranges that can be used for each component:
+
+- dht: UDP [4000, 8888]
+- audio: UDP [16384-32766]
+- video: UDP [49152-65534]
+- SIP Control: UDP/TCP randomly binded
+
+So for ufw, we recommend to run: ``sudo ufw default allow outgoing``
+
+For now, you can’t specify a specific range to configure ports used by
+Jami. The inbound traffic can be controlled without issue, Jami should
+work and can use a TURN server if needed.
+
+If you run your own proxy or nameserver:
+
+- dhtproxy, nameserver: TCP [80-100], 443
+
+If you run your own TURN server:
+
+- TURN/STUN: TCP+UDP 3478, 5349
+
+How can I configure the codecs even more?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Codecs can be configured via a file. In the configurations files, you
+can create a file called ``encoder.json`` like this:
+
+::
+
+ {
+ "libx264": {
+ "profile": 100,
+ "level": 42,
+ "crf": 20,
+ "preset": "ultrafast"
+ },
+ "h264_vaapi": {
+ "low_power": 1
+ },
+ "libopus": {
+ "application": "voip"
+ }
+ }
+
+or:
+
+::
+
+ {
+ "libopus": {
+ "bit_rate": 128000
+ }
+ }
+
+This file is located in the same directory of
+```dring.yml`` <#basics-5>`__
+
+The best way to check which options are supported is through the command
+“ffmpeg -h encoder=[encoder_name]” where encoder_name can be whichever
+of libx264, libvpx, mpeg4, h263, libopus, libspeex, g722, pcm_alaw,
+pcm_mulaw (FFmpeg names for all of Jami’s supported encoders).
diff --git a/general/old-understanding.md b/general/old-understanding.md
@@ -1,196 +0,0 @@
-# Understanding Jami
-
-The goal of this page is to explain the Jami network clearly and
-concisely.
-
-## Prerequisites
-
-The page does not go into the details. (For more in-depth information
-about implementation, libraries, and APIs see the [Technical
-Reference](../technical/index.html).)
-
-Nevertheless, distributed systems are complex. You may have to
-research some of these terms and draw your own diagrams. At the
-least, you should have a basic understanding of [public-key
-cryptography](https://en.wikipedia.org/wiki/Public-key_cryptography)
-and computing concepts like [software
-libraries](https://en.wikipedia.org/wiki/Library_(computing)).
-
-If you are still struggling to understand part of this document,
-please reach out to us and we can try to help you understand it or
-make improvements, if needed.
-
-## What is a Jami account?
-
-A Jami account is an x.509 certificate as defined by [RFC
-5280](https://tools.ietf.org/html/rfc5280) with a 4096-bit RSA key
-pair.
-
-Jami uses the [gnutls](https://www.gnutls.org/) library to generate
-and manage RSA keys and certificates.
-
-### Account certificate
-
-An account certificate is generated at account creation and represents
-the identity of a Jami user. The certificate contains:
-
-- the public key
-- its 160 bit fingerprint (the Jami Id)
-- the fingerprint of the certificate issuer, which can be a
- certificate authority, but most likely is just same as the Jami ID,
- indicating a self-signature
-- the signature: a signed hash of the certificate
-
-
-### Device certificate
-
-Each device has its own certificate. Device certificates look like
-account certificates except that instead of being self-signed they are
-signed by the RSA key associated with the account certificate.
-
-For more information about Jami certificates, see
-[Certificates](certificates.html).
-
-The fingerprint of the device's public key is called the Device
-Id.
-
-### Account storage and backup
-
-Jami serializes account data using JSON, including contacts, daemon
-settings, certificates, revoked devices, display name, and almost
-anything else besides message history. The file is compressed using
-Gzip and stored in the [account files
-folder](faq.html#where-are-the-configuration-files-located) as
-`archive.gz`. If you use an account password, this file will also be
-encrypted.
-
-Linking a device entails simply copying this file to another device
-over the DHT.
-
-## The DHT
-
-Jami uses a [distributed hash
-table](https://en.wikipedia.org/wiki/Distributed_hash_table) library,
-[OpenDHT](https://github.com/savoirfairelinux/opendht) (also led by
-Savoir-faire Linux), to find peers, connect new devices, and even
-temporarily store messages. Understanding how a DHT works is out of
-the scope of this overview, but if you want to learn more, [this blog
-post](https://enconn.fr/blog/p2p-internals-dht/) is a good
-introduction.
-
-For now, think of it as a *distributed* way to store key-value pairs
-on the Jami network.
-
-You can think of the key `k` as a "location" on the DHT. `put(k, v)`
-stores the value `v` on the DHT at location `k`, while `get(k)` gets
-the value(s) stored at `k`.
-
-The key, in this case, is always a Jami Id or Device Id. Jami checks
-that values are signed by a device key belonging to the correct Jami
-ID.
-
-### DHT example: announcing and checking presence
-
-To announce your presence to the Jami network, simply `put(<Jami ID>,
-<Device ID>)` on the DHT. To check for the presence of your contacts,
-check the DHT for devices announced at the contact's Jami ID:
-`get(<Jami ID>)`.
-
-### Doing more with the DHT
-
-It should be clear by now that the DHT is a useful data store that
-serves as an intermediary for peers. Clients exchange IP addresses,
-device and account certificates, text messages, device revocations,
-and more over the DHT.
-
-Once accounts have exchanged their certificates, they can encrypt and
-sign messages before storing them on the DHT. So your IP address and
-message content is always encrypted to a 4096-bit RSA key while on the
-public DHT.
-
-The OpenDHT library takes care of encrypting and signing values with
-your certificate.
-
-OpenDHT has other useful features, like the ability to "listen" on a
-DHT location (rather than polling every X seconds), but we will not
-cover all of them.
-
-## Significance of the Jami Id
-
-Jami Ids are a fundamental way to "bootstrap" secure communication
-between two peers. As long as you have the correct Jami Id for your
-friend, nobody can impersonate them or read messages you've sent
-them. The Jami Id is used to verify certificates during the initial
-certificate exchange. OpenDHT handles certificate exchange with an
-"identity layer" for publishing certificates. See [OpenDHT's
-documentation](https://github.com/savoirfairelinux/opendht/wiki) for
-more information.
-
-
-
-
-## Calls and file transfers
-The DHT's bandwidth and latency are not good enough for real-time
-communications (RTC) and file tranfers. For calls and file transfers,
-we must make direct (peer-to-peer) connections between devices.
-
-Once our devices are connected, Jami uses the IETF [SIP
-standard](https://tools.ietf.org/html/rfc3261) to share files and
-stream audio and video with the [PJSIP](https://www.pjsip.org/)
-library. The hard part is first establishing a secure connection. Jami
-does this with ICE.
-
-### Connecting devices with ICE
-
-We've seen that securely exchanging IP addresses over the DHT is easy,
-but how do we actually connect two devices? We need to navigate
-firewalls and other network conditions.
-
-[RFC 5245](https://tools.ietf.org/html/rfc5245) defines ICE
-(Interactive Connectivity Establishment), a protocol for NAT
-traversal. Jami uses ICE to establish a peer-to-peer communication
-between two devices.
-
-As a quick summary, each client gathers a list of potential IP:port
-addresses called **ICE candidates**. The peer initiating the call or
-tranfer stores these candidates on the DHT (encrypted to the
-recipient, of course). Once the recipient accepts the connection by
-storing their candidate list, the devices each build a list of
-**candidate pairs** and the devices negotiate a connection using rules
-specified by ICE.
-
-
-### Encrypting the connection with GnuTLS
-
-Once a peer-to-peer communication channel has been established, the
-recipient device listens on it for incoming DTLS connections (acting
-as a DTLS server) while the caller initiates an outgoing DTLS
-connection (acting as a DTLS client).
-
-The DTLS communication must be
-[RFC6347](https://tools.ietf.org/html/rfc6347) compliant.
-
-
-Peers must only support PFS (perfect forward secrecy) cypher
-suites. The set of supported cypher suites is implementation defined
-but should include at least ECDHE-AES-GCM (TODO: specify the exact
-suites recommended to support).
-
-During the DTLS handshake, both peers must provide their respective
-device certificate chain and must authenticate the other peer. Jami
-checks that its public key is the same key used during the DHT ICE
-exchange.
-
-This connection is similar to the connection your browser makes with a
-web server (web browsers actually use DTLS for WebRTC). Jami uses
-GnuTLS instead of implementing its own crypto. This keeps connections
-up-to-date with the latest algorithms and security fixes, and helps us
-avoid the pitfalls of DIY crypto.
-
-TODO: Someone please review the wording and correctness of this section^^^^
-
-##
-
-
-
-## Swarm: a new generation of group conversations
diff --git a/general/troubleshooting.rst b/general/troubleshooting.txt
diff --git a/index.rst b/index.rst
@@ -23,6 +23,7 @@ contribute<guides/how-to-contribute-to-this-documentation>`!
building-jami/index
technical/index
extra/index
+ changelog
..
Indices and tables
