|
|
|
|
---
|
|
|
|
|
layout: post
|
|
|
|
|
title: FAQ
|
|
|
|
|
date: 2015-08-19 16:58:07
|
|
|
|
|
categories: guides
|
|
|
|
|
---
|
|
|
|
|
<link href="/docs/guides/css/faq.css" type="text/css" rel="stylesheet" />
|
|
|
|
|
|
|
|
|
|
# FAQ
|
|
|
|
|
{:.no_toc}
|
|
|
|
|
|
|
|
|
|
Categories
|
|
|
|
|
----------
|
|
|
|
|
{:.no_toc}
|
|
|
|
|
|
|
|
|
|
[General](#general)
|
|
|
|
|
|
|
|
|
|
[Quick Start](#quick-start)
|
|
|
|
|
|
|
|
|
|
[Standard](#standard)
|
|
|
|
|
|
|
|
|
|
[APIs](#apis)
|
|
|
|
|
|
|
|
|
|
[Reference Implementations](#reference-implementations)
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
FAQ Content
|
|
|
|
|
-----------
|
|
|
|
|
{:.no_toc}
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
* TOC
|
|
|
|
|
{:toc}
|
|
|
|
|
|
|
|
|
|
### General
|
|
|
|
|
|
|
|
|
|
##### What is Matrix?
|
|
|
|
|
|
|
|
|
|
Matrix is an ambitious new open standard for open, distributed,
|
|
|
|
|
real-time communication over IP. It defines interoperable Instant
|
|
|
|
|
Messaging and VoIP, providing pragmatic HTTP APIs and open source
|
|
|
|
|
reference implementations for creating and running your own real-time
|
|
|
|
|
communication infrastructure.
|
|
|
|
|
|
|
|
|
|
##### What is Matrix's Mission?
|
|
|
|
|
|
|
|
|
|
Matrix.org's initial inspiration and goal has been to fix the problem of
|
|
|
|
|
fragmented IP communications. But Matrix's real potential and ultimate
|
|
|
|
|
mission is to be a generic messaging and data synchronisation system for
|
|
|
|
|
the web - allowing people, services and devices to easily communicate
|
|
|
|
|
with each other with full history.
|
|
|
|
|
|
|
|
|
|
##### What does Matrix provide?
|
|
|
|
|
|
|
|
|
|
Today Matrix provides a new [open standard](/docs/spec),
|
|
|
|
|
[APIs](/docs/api) to integrate a service to the Matrix ecosystem and
|
|
|
|
|
reference [open source
|
|
|
|
|
implementations](http://github.com/matrix-org/synapse) of the standard.
|
|
|
|
|
|
|
|
|
|
##### 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 a nice 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. We are
|
|
|
|
|
committed to keeping the Matrix project open.
|
|
|
|
|
|
|
|
|
|
##### Who is funding Matrix.org?
|
|
|
|
|
|
|
|
|
|
We have been given permission by our employers, Amdocs, to work on
|
|
|
|
|
Matrix as an independent non-profit initiative.
|
|
|
|
|
|
|
|
|
|
##### Who is building Matrix?
|
|
|
|
|
|
|
|
|
|
We're a team of ~10 people with decades of experience building custom
|
|
|
|
|
VoIP and Messaging apps for mobile network operators. Most of us have
|
|
|
|
|
day jobs at Amdocs or OpenMarket, but we are supported by a mix of
|
|
|
|
|
freelancers and volunteers.
|
|
|
|
|
|
|
|
|
|
##### Why are you called Matrix?
|
|
|
|
|
|
|
|
|
|
We are called Matrix because we provide a structure in which all
|
|
|
|
|
communication can be matrixed together.
|
|
|
|
|
|
|
|
|
|
##### 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 interface with Matrix compliant servers and clients,
|
|
|
|
|
and encourage anyone and everyone to interface with them. 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 and clients to the public domain under the
|
|
|
|
|
[Apache Licence v2](http://www.apache.org/licenses/LICENSE-2.0.html), 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 @outlook.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
|
|
|
|
|
technological/usability/economic factors have ended up limiting their
|
|
|
|
|
success in providing true open federation.
|
|
|
|
|
|
|
|
|
|
##### 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 an archaic TCP line protocol
|
|
|
|
|
- Non-standardised federation protocol
|
|
|
|
|
- No built-in end-to-end encryption
|
|
|
|
|
- Disruptive net-splits
|
|
|
|
|
- Non-extensible
|
|
|
|
|
|
|
|
|
|
##### 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. 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 at time of
|
|
|
|
|
writing there are no open implementations.)
|
|
|
|
|
- History synchronisation is very much a second class citizen feature
|
|
|
|
|
- Stanzas aren't framed or reliably delivered without extensions. (See
|
|
|
|
|
[wiki.xmpp.org](http://wiki.xmpp.org/web/Myths#Myth_Four:_XMPP_is_unreliable_without_a_bunch_of_extensions.)
|
|
|
|
|
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
|
|
|
|
|
- No strong identity system (i.e. no standard E2E PKI, unless you
|
|
|
|
|
count X.509 certs, which [are
|
|
|
|
|
questionable](http://www.thoughtcrime.org/blog/ssl-and-the-future-of-authenticity/))
|
|
|
|
|
- Not particularly well designed for mobile use cases: push;
|
|
|
|
|
bandwidth-efficient transports. (Since the time of writing a [Push
|
|
|
|
|
XEP has appeared](http://xmpp.org/extensions/xep-0357.html), and
|
|
|
|
|
[wiki.xmpp.org](http://wiki.xmpp.org/web/Myths#Myth_Three:_It.27s_too_bandwidth-inefficient_for_mobile.)
|
|
|
|
|
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. We think of the standards 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 '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](https://github.com/SkaveRat/xmpptrix) 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 the 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
|
|
|
|
|
complicated GNUnet stack in v2. Meanwhile, Matrix doesn't provide of
|
|
|
|
|
the metadata protection guarantees that GNUnet/PSYC aims for.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
See [http://about.psyc.eu/Matrix](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 peer-to-peer; 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.
|
|
|
|
|
We haven't actually played with Tox at all yet.
|
|
|
|
|
|
|
|
|
|
##### 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 user experience. 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.
|
|
|
|
|
|
|
|
|
|
##### What Matrix compliant apps are there?
|
|
|
|
|
|
|
|
|
|
None yet, other than our examples. It's early days :)
|
|
|
|
|
|
|
|
|
|
##### Why do you think existing apps will ever join this?
|
|
|
|
|
|
|
|
|
|
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. As
|
|
|
|
|
Matrix matures it may well be appropriate to work with an official
|
|
|
|
|
standard body.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
### Quick Start
|
|
|
|
|
|
|
|
|
|
##### How do I get an account and get started?
|
|
|
|
|
|
|
|
|
|
The quickest way is to just jump to the demo webclient at
|
|
|
|
|
[http://matrix.org/beta](http://matrix.org/beta) and sign up. Please note that you can point the
|
|
|
|
|
webclient 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?
|
|
|
|
|
|
|
|
|
|
The demo webclient 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.
|
|
|
|
|
|
|
|
|
|
##### How do I connect my homeserver to the public Matrix network?
|
|
|
|
|
|
|
|
|
|
See
|
|
|
|
|
[http://github.com/matrix-org/synapse](http://github.com/matrix-org/synapse)
|
|
|
|
|
for details
|
|
|
|
|
|
|
|
|
|
##### How do I Matrix-enable my existing app?
|
|
|
|
|
|
|
|
|
|
See the [Client-Server API
|
|
|
|
|
HOWTO](http://matrix.org/docs/howtos/client-server.html) for an example
|
|
|
|
|
of how to use Matrix's client-server API to let your app communicate
|
|
|
|
|
with users via Matrix. We're currently working out the best way to
|
|
|
|
|
integrate your application's existing identity system with Matrix.
|
|
|
|
|
|
|
|
|
|
##### How can I write a client on Matrix?
|
|
|
|
|
|
|
|
|
|
See the [Client-Server API
|
|
|
|
|
HOWTO](http://matrix.org/docs/howtos/client-server.html) and the [API
|
|
|
|
|
docs](/docs/api) and [the Spec](/docs/spec) for all the details you need
|
|
|
|
|
to write a client.
|
|
|
|
|
|
|
|
|
|
##### *How can I help out with this?*
|
|
|
|
|
|
|
|
|
|
Install synapse and tell us how you get on. Critique the spec. Write
|
|
|
|
|
clients. Just come say hi on [\#matrix:matrix.org](/alpha) or the
|
|
|
|
|
[mailing lists](/mailman/listinfo/matrix-users)!
|
|
|
|
|
|
|
|
|
|
##### Where can I get support?
|
|
|
|
|
|
|
|
|
|
[\#matrix:matrix.org](/alpha), \#matrix on irc.freenode.net or
|
|
|
|
|
the [mailing lists](/mailman/listinfo/matrix-users) are your best bets.
|
|
|
|
|
|
|
|
|
|
##### 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
|
|
|
|
|
use the [mailing list](/mailman/listinfo/matrix-users) for now.
|
|
|
|
|
|
|
|
|
|
##### How mature is this?
|
|
|
|
|
|
|
|
|
|
We started working on Matrix in July 2014, and have opened it to the
|
|
|
|
|
public in September 2014. It's early days, and under no circumstances
|
|
|
|
|
should you use Matrix or Synapse for anything other than experimentation
|
|
|
|
|
and learning at this point. Obviously the spec and apps are maturing
|
|
|
|
|
rapidly, but as of the time of writing APIs are not frozen and the apps
|
|
|
|
|
are very much a work in progress.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
*Sorry, the FAQ is still work in progress, the rest of it will up
|
|
|
|
|
soon!* *In the mean time, don't hesitate to get in touch on
|
|
|
|
|
[\#matrix:matrix.org](/alpha) or the [mailing
|
|
|
|
|
lists](/mailman/listinfo/matrix-users)!*
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
### Standard
|
|
|
|
|
|
|
|
|
|
##### What is a home server?
|
|
|
|
|
|
|
|
|
|
##### What is an identity sever?
|
|
|
|
|
|
|
|
|
|
##### Where do my conversations get stored?
|
|
|
|
|
|
|
|
|
|
##### What is a 3PID?
|
|
|
|
|
|
|
|
|
|
##### How do you do VoIP calls on Matrix?
|
|
|
|
|
|
|
|
|
|
##### Can I log into other homeservers with my username and password?
|
|
|
|
|
|
|
|
|
|
##### Why Apache Licence?
|
|
|
|
|
|
|
|
|
|
##### Can I write a Matrix homeserver?
|
|
|
|
|
|
|
|
|
|
##### How secure is this?
|
|
|
|
|
|
|
|
|
|
##### Why aren't you using an ORM layer like SqlAlchemy?
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
### APIs
|
|
|
|
|
|
|
|
|
|
##### How do I join the global Matrix federation?
|
|
|
|
|
|
|
|
|
|
##### What ports do I have to open up to join the global Matrix federation?
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
### Reference Implementations
|
|
|
|
|
|
|
|
|
|
##### What is Matrix built on - and why?
|
|
|
|
|
|
|
|
|
|
##### How do I run my own home server?
|
|
|
|
|
|
|
|
|
|
##### Can I run my own identity server?
|
|
|
|
|
|
|
|
|
|
Yes - the reference implementation is
|
|
|
|
|
[sydent](https://github.com/matrix-org/sydent) and you can run your own
|
|
|
|
|
ID server cluster that tracks 3rd party to Matrix ID mappings. 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 is Synapse?
|
|
|
|
|
|
|
|
|
|
##### Why is Synapse in Python/Twisted?
|
|
|
|
|
|
|
|
|
|
##### What are Synapse's platform requirements?
|
|
|
|
|
|
|
|
|
|
##### What are the Synapse webclient's requirements?
|
|
|
|
|
|
|
|
|
|
##### Where is the mobile app?
|
|
|
|
|
|
|
|
|
|
##### What decides the room member order on the webclient?
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Any other question? Please contact us on
|
|
|
|
|
[\#matrix:matrix.org](/alpha) or the [mailing
|
|
|
|
|
lists](/mailman/listinfo/matrix-users)!
|