You cannot select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

32 KiB

Raw Blame History Unescape Escape

layout	title	date	categories
post	FAQ	2015-08-19 16:58:07	guides

FAQ

{:.no_toc}

FAQ Content

{:.no_toc}

TOC {:toc .toc}

General

What is Matrix?

Matrix is an open standard for interoperable, decentralised, real-time communication over IP. It can be used to power Instant Messaging, VoIP/WebRTC signalling, Internet of Things communication - or anywhere you need a standard HTTP API for publishing and subscribing to data whilst tracking the conversation history.

Matrix defines the standard, and provides open source reference implementations of Matrix-compatible Servers, Clients, Client SDKs and Application Services to help you create new communication solutions or extend the capabilities and reach of existing ones.

What is Matrix's Mission?

Matrix's initial goal is to fix the problem of fragmented IP communications: letting users message and call each other without having to care what app the other user is on - making it as easy as sending an email.

The longer term goal is for Matrix to act as a generic HTTP messaging and data synchronisation system for the whole web - allowing people, services and devices to easily communicate with each other, empowering users to own and control their data and select the services and vendors they want to use.

What does Matrix provide?

Matrix provides:

Open Standard HTTP APIs for transferring JSON messages (e.g. instant messages, WebRTC signalling), including:
Client<->Server API - defines how Matrix compatible clients communicate with Matrix homeservers.
Server<->Server API - defines how Matrix homeservers exchange messages and synchronise history with each other.
Application Service API - defines how to extend the functionality of Matrix with 'integrations' and bridge to other networks.
Modules - specifies features that must be implemented by particular classes of clients.
Open source reference implementations of:
Clients (Web (React), iOS, Android)
Client SDKs (Javascript, Web (React), iOS, Android)
Homeservers (Synapse)
Application Services (bridges to IRC, Slack, Skype, Lync and more...)
The actual ecosystem and community of everyone running Matrix servers and services
Loads of 3rd party contributions of clients, SDKs, servers and services.

You can find the full list of Matrix enabled projects at https://matrix.org/blog/try-matrix-now.

What does this mean for users?

The aim is to provide an analogous ecosystem to email - one where you can communicate with pretty much anyone, without caring what app or server they are using, using whichever app & server you chose to use, and use a neutral identity system like an e-mail address or phone number to discover people to talk to.

What kind of company is Matrix.org?

Matrix is an open initiative which acts as a neutral custodian of the Matrix standard. It's not actually incorporated anywhere at the moment but we are looking at the best legal structure for the future (and as of October 2015 we have hopefully found one). Whatever the legal structure, we are committed to keeping the Matrix project open.

Who is funding Matrix.org?

Most of the current core contributors to Matrix work at Amdocs, who have kindly given us permission to work on Matrix as an independent non-profit initiative. Other contributors are funded by their own employers or donate their own time to the project.

Who is building Matrix?

The core team is ~10 people with extensive experience in building custom VoIP and Messaging apps for mobile network operators. Most of us have day jobs at Amdocs or OpenMarket, but there are an increasing number of contributors from other companies and folks all over the internet.

Why are you called Matrix?

We are called Matrix because we provide a structure in which all communication can be matrixed together.

No, it's nothing to do with the film (although you could go and build virtual worlds on top of Matrix if you wanted :)

Why have you released this as open source?

We believe that any open standard defining interoperable communication needs to be justified, demonstrated and validated with transparent open source implementations. For Matrix to achieve its mission of making all communications services interoperable we believe it needs to be truly open, giving people access to take all the code we produce and to use and build on top of it.

What do you mean by open?

Matrix is an open standard, meaning that we have freely published the details for how to communicate interoperably using the Matrix set of HTTP APIs. We encourage anyone and everyone to use the APIs and build their own projects which implement them and so benefit from interoperability with the rest of the Matrix ecosystem. We also ensure the standard is not encumbered by any known patent licensing requirements.

Matrix is also open source, meaning that we have released the source code of the reference servers, clients and services to the public domain under the Apache Licence v2, to encourage anyone and everyone to run their own servers and clients, and enhance them and contribute their enhancements as they see fit.

What does federated mean?

Federation allows separate deployments of a communication service to communicate with each other - for instance a mail server run by Google federates with a mail server run by Microsoft when you send email from @gmail.com to @hotmail.com.

Federation is different to interoperability, as interoperable clients may simply be running on the same deployment - whereas in federation the deployments themselves are exchanging data in a compatible manner.

Matrix provides open federation - meaning that anyone on the internet can join into the Matrix ecosystem by deploying their own server.

How is this like e-mail?

When email was first set up in the early ‘80s, companies like Compuserve and AT&T and Sprint set up isolated email communities which only allowed you to exchange mail with users on the same system. If you got your email from one service and your friend from another, then you couldn't message each other. This is basically the situation we're in today with VoIP and IM.

Why has no-one done this before?

There have been several attempts before including SIP, XMPP and RCS. All of these have had some level of success, but many different technological/usability/economic factors have ended up limiting their success. Unfortunately, we've not ended up in a world where everyone has a SIP URI or Jabber ID on their business card, or a phone that actually uses RCS.

What is the difference between Matrix and IRC?

We love IRC. In fact, as of today the core Matrix team still uses it as our primary communication tool. Between us we've written IRCds, IRC bots and admined dreamforge, UnrealIRCd, epona, ircservices and several others. That said, it has some limitations that Matrix seeks to improve on:

Text only
No history
No multiple-device support
No presence support
Fragmented identity model
No open federation
No standard APIs, just a rather limited TCP line protocol
Non-standardised federation protocol
No built-in end-to-end encryption
Disruptive net-splits
Non-extensible

IRCv3 exists and is addressing some of these issues; this is great news and we wish them well. It's almost a contradiction in terms to get competitive between openly interoperable communication projects - we look forward to increasing the richness of Matrix<->IRC bridges as the project progresses.

What is the difference between Matrix and XMPP?

The Matrix team used XMPP (Openfire, ejabberd, spectrum, asmack, XMPPFramework) for IM before starting to experiment with open HTTP APIs as an alternative in around 2012. The main issues with XMPP that drove us in this direction were:

Not particularly web-friendly - you can't easily speak XMPP from a web browser. (N.B. Nowadays you have options like XMPP-FTW and Stanza.io that help loads with letting browsers talk XMPP).
Single logical server per MUC is a single point of control and availability. (MUCs can be distributed over multiple physical servers, but they still sit behind a single logical JID and domain. FMUC improves this with a similar approach to Matrix, but as of Oct 2015 there are no open source implementations.)
History synchronisation is very much a second class citizen feature
Bridging to other protocols and defragmenting existing communication apps and networks is very much a second class citizen feature
Stanzas aren't framed or reliably delivered without extensions. (See wiki.xmpp.org for an XMPP take on this)
Multiple device support is limited. (Apparently Carbons and MAM help with this)
Baseline feature set is so minimal that fragmentation of features between clients and servers is common, especially as interoperability profiles for features have fallen behind (as of July 2015)
No strong identity system (i.e. no standard E2E PKI, unless you count X.509 certs, which are questionable)
Not particularly well designed for mobile use cases: push; bandwidth-efficient transports. (Since the time of writing a Push XEP has appeared, and wiki.xmpp.org claims that XMPP runs "fine" over a 9600bps + 30s latency link.)

The whole subject of XMPP vs Matrix seems to bring out the worst in people. Rather than fighting over which open interoperable communication standard works the best, we should just collaborate and bridge everything together. The more federation and interoperability the better.

We think of Matrix and XMPP as being quite different; at its core Matrix can be thought of as an eventually consistent global JSON db with an HTTP API and pubsub semantics - whilst XMPP can be thought of as a message passing protocol. You can use them both to build chat systems; you can use them both to build pubsub systems; each comes with different tradeoffs. Matrix has a deliberately extensive 'kitchen sink' baseline of functionality; XMPP has a deliberately minimal baseline set of functionality. If XMPP does what you need it to do, then we're genuinely happy for you :) Meanwhile, rather than competing, an XMPP Bridge like Skaverat's xmpptrix beta or jfred's matrix-xmpp-bridge or Matrix.org's own purple-matrix has potential to let both environments coexist and make the most of each other's benefits.

What is the difference between Matrix and PSYC?

PSYC is a open federated messaging protocol loosely inspired by IRC. In version 1 it was a standalone protocol, and in version 2 it is being reutilised as a messaging layer on top of GNUnet. We honestly don't know that much about it, beyond trying to use psycd as an XMPP<->IRC bridge in 2010. Matrix differentiates primarily by providing simple HTTP APIs rather than the more exotic compact line protocol in PSYC v1 or the comprehensive GNUnet stack in v2, and Matrix focuses more on decentralised conversation history rather than just decentralised chat servers. On the other hand, Matrix doesn't provide the metadata protection guarantees that GNUnet/PSYC aims for.

See http://about.psyc.eu/Matrix for PSYC's views on Matrix.

What is the difference between Matrix and Tox?

Tox.im looks to be a very cool clone of Skype - a fully decentralised peer-to-peer network. Matrix is deliberately not a 'pure' peer-to-peer system; instead each user has a well-defined homeserver which stores his data and that he can depend upon. Matrix provides HTTP APIs; Tox.im provides C APIs. As of October 2015 Tox doesn't seem to have an answer yet for decentralised conversation history storage.

How does Matrix compare with something like Trillian or Pidgin?

Trillian and Pidgin and similar aggregating IM clients merge all your IM activity into a single app. However, your history and identity is still fragmented across the networks. People can't find you easily, and your history is fragmented (other than on the device where the client runs). And rather than being able to chose the right app for the job when communicating with people, you are pushed towards relying on a specific aggregation app.

Matrix lets you get the best of both worlds by linking to all the different networks (XMPP, AIM, ICQ, Lync, Skype etc) on the serverside, using bridges which can be run by anyone. Matrix then provides a simple standard HTTP API to access any of these networks, and lets you choose whichever client you prefer (either as a 'native' Matrix client or using a non-Matrix client from one of the networks which has been bridged in).

What Matrix compliant apps are there?

Quite a few, ranging from the glossy mass-market to the geeky command-line. There's even an emacs macro. Check out [https://matrix.org/blog/try-matrix-now] for the current list of Matrix enabled projects.

What bridges to other networks are available?

The number of 'bridges' which integrate existing communication networks into Matrix are growing on a daily basis - both written by the Matrix core team and contributed by the wider community. The full list can be seen at https://matrix.org/blog/try-matrix-now, but the core ones as of Oct 2015 include:

matrix-appservice-irc - an increasingly comprehensive Matrix<->IRC bridge
matrix-appservice-verto - links from Matrix to FreeSWITCH via the Verto protocol
matrix-appservice-slack - a basic bridge to Slack
matrix-appservice-purple - lets you access any of the 20+ protocols supported by libpurple, including Skype, Lync, XMPP, etc)
matrix-appservice-bridge - a general NodeJS framework for writing bridges

Writing new bridges is incredibly fun and easy - see the matrix-appservice-bridge HOWTO for an example of how to write a fully functional Slack bridge in less than 100 lines of code!

Why do you think existing apps will ever join this officially?

We firmly believe it is what is right for the consumer. As people begin to use interoperable communications tools, service providers will see the benefit and compete on quality of service, security and features rather than relying on locking people into their walled garden. We believe as soon as users see the availability and benefits of interoperable services they will demand it.

Why aren't you doing this through the IETF? or W3C? or 3GPP?

We do recognise the advantages of working with existing standards bodies. We have been focused on writing code and getting it out, and the standard has been evolving rapidly since initial release in September 2014. Once the standard has matured sufficiently it may well be appropriate to work with an official standard body to maintain it going forwards.

Quick Start

How do I get an account and get started?

The quickest way is to pick a client from https://matrix.org/blog/try-matrix-now and sign up. Please note that you can point clients to access any homeserver - you don't have to use matrix.org, although as of day 1, matrix.org is the only communal homeserver available.

What can I actually do with this?

A typical client provides a simple chatroom interface to Matrix - letting the user interact with users and rooms anywhere within the Matrix federation. Text and image messages are supported, and basic voice-only VoIP calling via WebRTC is supported in one-to-one rooms. (As of October 2015, experimental multi-way calling is also available on Vector.im).

How do I connect my homeserver to the public Matrix network?

See http://github.com/matrix-org/synapse for details

How do I Matrix-enable my existing app?

If your app doesn't have any communication capability already, you'll want to use one of the Matrix client SDKs to add it in. These come in different levels of sophistication - ranging from a simple HTTP API wrapper (like matrix-js-sdk, matrix-ios-sdk or matrix-android-sdk) through to reusable UI components (like matrix-react-sdk and matrix-ios-kit). Pick the one for your platform, or a 3rd party one if none of the above work for you, and get plugging it in. You'll probably also want to read the Client-Server API HOWTO too.

If you already have communication infrastructure set up (XMPP, custom HTTP, or whatever), then you'll want to run a bridge to expose it to the wider Matrix ecosystem. See matrix-appservice-bridge HOWTO for a guide of how to write bridges using the matrix-appservice-bridge framework, or co-opt one from the list at https://matrix.org/blog/try-matrix-now. Application Service API gives the details of the API that bridges have to implement.

How can I write a client on Matrix?

See the Client-Server API HOWTO and the API docs and the Spec for all the details you need to write a client.

How can I help out with this?

Come say hi on #matrix:matrix.org! Install synapse and tell us how you get on. Critique the spec. Write clients. Write bridges! Run bridges! Nose around in Jira and send us some pull requests on github to fix some bugs or add some features! You could even try to write a homeserver (but be warned, Matrix's architecture makes homeservers orders of magnitude harder than clients or bridges.)

See CONTRIBUTING.rst for full details on how to contribute to the project. All are welcome!

Where can I get support?

#matrix:matrix.org aka #matrix on irc.freenode.is your best bet.

How do I register custom matrix event types?

We're not yet managing a registry of custom matrix event types. If you have any particularly good ones you want to tell the world about, please let us know on #matrix-dev:matrix.org.

How mature is this?

We started working on Matrix in July 2014, and opened it to the public in September 2014. We got all the core features in place in December 2014 and entered beta, and since then have been iterating away on the beta refining the architecture and APIs, fixing bugs and scalability, and adding new features, clients, bridges etc.

As of October 2015 (synapse 0.10) it's good for serious experimentation and non-production services and can absolutely be used in the real world. However, we're still in beta and we'll want to freeze the spec and implement clustering and other nice features before we really declare it ready for production.

Standard

What is a client?

Users in Matrix use one or more clients to communicate. This could be any combination of a web client, a command line client, a mobile client - or embedded clients built into existing apps. It could even be a piece of hardware (e.g. a drone) that is Matrix enabled.

Can I use Matrix without installing a Matrix client?

Sure. An ever increasing number of protocols are being bridged into Matrix, so if you use something like IRC on Freenode you may well be indirectly benefiting from Matrix, as others may be connected into the IRC channel via Matrix.

What is a home server?

A user's clients connect to a single homeserver, which stores the communication history and account information for that user, and shares data with the wider Matrix ecosystem by synchronising communication history with other homeservers.

What is an identity server?

Users in Matrix are identified internally via their matrix user ID (MXID). However, existing 3rd party ID (3PID) namespaces such as email addresses or phone numbers should be used publically to identify Matrix users, at least for invitation purposes. A Matrix "Identity" describes both the user ID and any other existing IDs from third party namespaces linked to their account.

Matrix users can link third-party IDs (3PIDs) to their user ID. Linking 3PIDs creates a mapping from a 3PID to a user ID. This mapping can then be used by Matrix users in order to discover the MXIDs of their contacts.

In order to ensure that the mapping from 3PID to user ID is genuine, a globally federated cluster of trusted "Identity Servers" (IS) are used to verify the 3PID and persist and replicate the mappings. Usage of an IS is not required in order for a client application to be part of the Matrix ecosystem. However, without one clients will not be able to look up user IDs using 3PIDs.

The precise architecture of identity servers is currently in flux and subject to change as we work to fully decentralise them.

Where do my conversations get stored?

Each homeserver stores the communication history and account information for all of its clients, and shares data with the wider Matrix ecosystem by synchronising communication history with other homeservers and their clients. Clients typically communicate with each other by emitting events in the context of a virtual room. Room data is replicated across all of the homeservers whose users are participating in a given room.

What is a 3PID?

Third-party IDs (3PIDs) are IDs from other systems or contexts, such as email addresses, social network accounts and phone numbers.

How do you do VoIP calls on Matrix?

Voice (and video) over Matrix uses the WebRTC 1.0 standard to transfer call media (i.e. the actual voice and video traffic). Matrix is used to signal the establishment and termination of the call by sending call events, like any other event. Currently calls are only supported in rooms with exactly two participants - however, one of those participants may be a conferencing bridge. We're looking at better ways to do group calling.

Can I log into other homeservers with my username and password?

Currently, no. We are looking at options for decentralising or migrating user accounts between multiple servers, and might add this feature at a later stage.

Why Apache Licence?

The Apache Licence is a permissive licence. We want the Matrix protocol itself to be free and open, but people are free to create both free and commercial apps and services that uses the protocol. In our opinion, any Matrix-service only enhances the Matrix ecosystem.

Can I write a Matrix homeserver?

Yes. Matrix is just a spec, so implementations of the spec are very welcome! It should be noted that as of October 2015, changes are still being made to the spec, so if you want to write a Matrix homeserver, it is strongly recommended that you chat to the Matrix.org devs in #matrix:matrix.org first! You can also read about the Federation API here.

How secure is this?

Server-server traffic is mandatorily TLS from the outset. Server-client traffic mandates transport layer encryption other than for tinkering. Servers maintain a public/private key pair, and sign the integrity of all messages in the context of the historical conversation, preventing tampering. Server keys are distributed using a PERSPECTIVES-style system.

End-to-end encryption is coming shortly to clients for both 1:1 and group chats to protect user data stored on servers, using the Olm cryptographic ratchet implementation. As of October 2015 this is blocked on implementing the necessary key distribution and fingerprint management.

Privacy of metadata is not currently protected from server administrators - a malicious homeserver administrator can see who is talking to who and when, but not what is being said (once E2E encryption is enabled). See this presentation from Jardin Entropique for a more comprehensive discussion of privacy in Matrix.

Why HTTP? Doesn't HTTP suck?

HTTP is indeed not the most efficient transport, but it is ubiquitous, very well understood and has numerous implementations on almost every platform and language. It also has a simple upgrade path to HTTP/2, which is relatively bandwidth and round-trip efficient.

It has thus been chosen as the mandatory baseline of the exchange, but it is still entirely possible to use more fancy protocols for communication between clients and server (see for example this websocket transport draft), and it's also possible in the future that negotiation of more efficient protocols will be added for the federation between servers, with HTTP+JSON remaining as the compability baseline.

Implementations

What is Synapse?

Synapse is a reference "homeserver" implementation of Matrix from the core development team at matrix.org, written in Python 2/Twisted. It is intended to showcase the concept of Matrix and let folks see the spec in the context of a codebase and let you run your own homeserver and generally help bootstrap the ecosystem.

How do I join the global Matrix federation?

You can download and run one of the available Matrix servers - please see this guide for details!

What ports do I have to open up to join the global Matrix federation?

We recommend servers use port 8448 for server<->server HTTPS traffic. Look at "Setting up Federation" in the Synapse readme file for details.

Client<->Server traffic can talk directly to Synapse via port 8448, but as by default Synapse creates a self-signed TLS certificate this can cause problems for clients which can't easily trust self-signed certificates (e.g. most web browsers). Instead, you can proxy access to Synapse's HTTP listener on port 8008 via an existing HTTPS proxy with a valid certificate (e.g. an nginx listening on port 443), or you can point Synapse at a valid X.509 signed TLS certificate. In future, Synapse will probably use letsencrypt to autogenerate valid certificates rather than self-signed ones during installation, simplifying this process enormously.

You can also put Synapse entirely behind an existing TLS load balancer and not expose port 8448 at all. In this situation, Synapse will need to be configured to share the same public TLS certificate as the load balancer (as Synapse uses the public certificate for identity in other areas too, and it has to match the certificate that other servers see when they connect).

How do I run my own homeserver?

Follow the instructions for the homeserver you want to run. If you want to run Synapse, the reference homeserver from Matrix.org, follow these instructions.

Can I run my own identity server?

Yes - the reference implementation is sydent and you can run your own ID server cluster that tracks 3rd party to Matrix ID mappings. This won't be very useful right now, though, and we don't recommend it.

If you want your server to participate in the global replicated Matrix ID service then please get in touch with us. Meanwhile, we are looking at ways of decentralising the 'official' Matrix identity service so that identity servers are 100% decentralised and can openly federate with each other. N.B. that you can use Matrix without ever using the identity service - it exists only to map 3rd party IDs (e.g. email addresses) to matrix IDs to aid user discovery.

What are Synapse's platform requirements?

Synapse will use as much RAM as you give it in order to cache conversations in RAM to avoid hitting the database. For small deployments (<50 active users) around 512MB of RAM is probably okay. You can configure the amount of RAM used by synapse with the event_cache_size config parameter - the more events in the cache, the more RAM required. Synapse itself requires relatively little diskspace other than for logging (which as of October 2015 is quite verbose for debugging purposes), but as it caches the content of all the file attachments (images, videos etc) viewed by its users, you may need to size storage appropriately. Synapse is currently effectively single threaded, and will never use more than 1 core.

For better performance, one should back Synapse with a Postgres database rather than the default SQLite - see https://github.com/matrix-org/synapse/tree/master/README.rst#using-postgresql for details.

Why is Synapse in Python/Twisted?

This is because both provide a mature and well known event-driven async IO framework for writing serverside code. Whilst this has been okay for our initial experimentation and proof of concept, it's likely that future homeserver work will be written in a more strongly typed language (e.g. Go).

Why aren't you using an ORM layer like SqlAlchemy in Synapse?

Synapse is very database dependent (as of Oct 2015; this is improving in the near future however), and we like having the flexibility to sculpt our own queries.

Where can I find a mobile app?

The "Matrix Console" reference apps (ugly, geeky and powerful - intended for early adopter powerusers) can be downloaded from the Google Play store and Apple store.

For the Android app, you can also install the latest development version built by Jenkins.

Where can I find a web app?

As of Oct 2015, the best web app options are to use Vector.im - a glossy web client written on top of matrix-react-sdk, or the original AngularJS based client, which has serious performance problems and is not currently being maintained. In future a "Matrix Console" reference web app built on matrix-react-sdk will be released by matrix.org to complement the mobile apps above.

QUESTIONS TO BE ANSWERED!

This FAQ is a constant work in progress - patches and pull requests are very welcome to help us improve it. Some of the frequent questions where we need to write an answer include:

How do I rename servers?
How do I change the TLS key of my server?
How do I maintain my synapse's DB (e.g. prune old conversations)?
How do I maintain my synapse's content repository (e.g. prune old content)?
What are redactions?
Why is the spec so big, especially relative to the XMPP baseline spec?
How do I contribute to the spec?
What is the privacy policy on Matrix.org?
How precisely does E2E work?
How does Matrix actually work architecturally?
What IOT use cases are there for Matrix?
Why is are the Matrix reference implementations written in so many different languages?
How does push work?
What's on the roadmap?
How can I use Matrix to talk on Freenode or other IRC networks?
Where can I learn more about Matrix? (link to PDFs of other presentations etc)
Why don't you use websockets?
Why is synapse so resource intensive immediately after federating for the first time?
```
your question goes here...
```

Any other questions? Please contact us in #matrix:matrix.org.

32 KiB Raw Blame History Unescape Escape

FAQ

Categories