mirror of
https://git.anonymousland.org/anonymousland/synapse.git
synced 2024-09-09 15:22:11 +00:00
Merge branch 'master' into develop
This commit is contained in:
commit
2d55d43d40
166
README.rst
166
README.rst
@ -4,13 +4,13 @@ Introduction
|
|||||||
Matrix is an ambitious new ecosystem for open federated Instant Messaging and
|
Matrix is an ambitious new ecosystem for open federated Instant Messaging and
|
||||||
VoIP. The basics you need to know to get up and running are:
|
VoIP. The basics you need to know to get up and running are:
|
||||||
|
|
||||||
- Chatrooms are distributed and do not exist on any single server. Rooms
|
- Chatrooms are distributed and do not exist on any single server. Rooms
|
||||||
can be found using aliases like ``#matrix:matrix.org`` or
|
can be found using aliases like ``#matrix:matrix.org`` or
|
||||||
``#test:localhost:8008`` or they can be ephemeral.
|
``#test:localhost:8008`` or they can be ephemeral.
|
||||||
|
|
||||||
- Matrix user IDs look like ``@matthew:matrix.org`` (although in the future
|
- Matrix user IDs look like ``@matthew:matrix.org`` (although in the future
|
||||||
you will normally refer to yourself and others using a 3PID: email
|
you will normally refer to yourself and others using a 3PID: email
|
||||||
address, phone number, etc rather than manipulating Matrix user IDs)
|
address, phone number, etc rather than manipulating Matrix user IDs)
|
||||||
|
|
||||||
The overall architecture is::
|
The overall architecture is::
|
||||||
|
|
||||||
@ -20,70 +20,74 @@ The overall architecture is::
|
|||||||
WARNING
|
WARNING
|
||||||
=======
|
=======
|
||||||
|
|
||||||
**Synapse is currently in a state of rapid development, and not all features are yet functional.
|
**Synapse is currently in a state of rapid development, and not all features
|
||||||
Critically, some security features are still in development, which means Synapse can *not*
|
are yet functional. Critically, some security features are still in
|
||||||
be considered secure or reliable at this point.** For instance:
|
development, which means Synapse can *not* be considered secure or reliable at
|
||||||
|
this point.** For instance:
|
||||||
|
|
||||||
- **SSL Certificates used by server-server federation are not yet validated.**
|
- **SSL Certificates used by server-server federation are not yet validated.**
|
||||||
- **Room permissions are not yet enforced on traffic received via federation.**
|
- **Room permissions are not yet enforced on traffic received via federation.**
|
||||||
- **Homeservers do not yet cryptographically sign their events to avoid tampering**
|
- **Homeservers do not yet cryptographically sign their events to avoid
|
||||||
|
tampering**
|
||||||
- Default configuration provides open signup to the service from the internet
|
- Default configuration provides open signup to the service from the internet
|
||||||
|
|
||||||
Despite this, we believe Synapse is more than useful as a way for experimenting and
|
Despite this, we believe Synapse is more than useful as a way for experimenting
|
||||||
exploring Synapse, and the missing features will land shortly. **Until then, please do *NOT*
|
and exploring Synapse, and the missing features will land shortly. **Until
|
||||||
use Synapse for any remotely important or secure communication.**
|
then, please do *NOT* use Synapse for any remotely important or secure
|
||||||
|
communication.**
|
||||||
|
|
||||||
|
|
||||||
Quick Start
|
Quick Start
|
||||||
===========
|
===========
|
||||||
|
|
||||||
System requirements:
|
System requirements:
|
||||||
- POSIX-compliant system (tested on Linux & OSX)
|
- POSIX-compliant system (tested on Linux & OSX)
|
||||||
- Python 2.7
|
- Python 2.7
|
||||||
|
|
||||||
To get up and running:
|
To get up and running:
|
||||||
|
|
||||||
- To simply play with an **existing** homeserver you can
|
|
||||||
just go straight to http://matrix.org/alpha.
|
|
||||||
|
|
||||||
- To run your own **private** homeserver on localhost:8008, generate a basic
|
|
||||||
config file: ``./synctl start`` will give you instructions on how to do this.
|
|
||||||
Once you've done so, running ``./synctl start`` again will start your private
|
|
||||||
home sserver. You will find a webclient running at http://localhost:8008.
|
|
||||||
Please use a recent Chrome or Firefox for now (or Safari if you don't need
|
|
||||||
VoIP support).
|
|
||||||
|
|
||||||
- To run a **public** homeserver and let it exchange messages with other homeservers
|
- To simply play with an **existing** homeserver you can
|
||||||
and participate in the global Matrix federation, you must expose port 8448 to the
|
just go straight to http://matrix.org/alpha.
|
||||||
internet and edit homeserver.yaml to specify server_name (the public DNS entry for
|
|
||||||
this server) and then run ``synctl start``. If you changed the server_name, you may
|
- To run your own **private** homeserver on localhost:8008, generate a basic
|
||||||
need to move the old database (homeserver.db) out of the way first. Then come join
|
config file: ``./synctl start`` will give you instructions on how to do this.
|
||||||
``#matrix:matrix.org`` and say hi! :)
|
Once you've done so, running ``./synctl start`` again will start your private
|
||||||
|
home sserver. You will find a webclient running at http://localhost:8008.
|
||||||
|
Please use a recent Chrome or Firefox for now (or Safari if you don't need
|
||||||
|
VoIP support).
|
||||||
|
|
||||||
|
- To run a **public** homeserver and let it exchange messages with other
|
||||||
|
homeservers and participate in the global Matrix federation, you must expose
|
||||||
|
port 8448 to the internet and edit homeserver.yaml to specify server_name
|
||||||
|
(the public DNS entry for this server) and then run ``synctl start``. If you
|
||||||
|
changed the server_name, you may need to move the old database
|
||||||
|
(homeserver.db) out of the way first. Then come join ``#matrix:matrix.org``
|
||||||
|
and say hi! :)
|
||||||
|
|
||||||
For more detailed setup instructions, please see further down this document.
|
For more detailed setup instructions, please see further down this document.
|
||||||
|
|
||||||
|
|
||||||
About Matrix
|
About Matrix
|
||||||
============
|
============
|
||||||
|
|
||||||
Matrix specifies a set of pragmatic RESTful HTTP JSON APIs as an open standard,
|
Matrix specifies a set of pragmatic RESTful HTTP JSON APIs as an open standard,
|
||||||
which handle:
|
which handle:
|
||||||
|
|
||||||
- Creating and managing fully distributed chat rooms with no
|
- Creating and managing fully distributed chat rooms with no
|
||||||
single points of control or failure
|
single points of control or failure
|
||||||
- Eventually-consistent cryptographically secure[1] synchronisation of room
|
- Eventually-consistent cryptographically secure[1] synchronisation of room
|
||||||
state across a global open network of federated servers and services
|
state across a global open network of federated servers and services
|
||||||
- Sending and receiving extensible messages in a room with (optional)
|
- Sending and receiving extensible messages in a room with (optional)
|
||||||
end-to-end encryption[2]
|
end-to-end encryption[2]
|
||||||
- Inviting, joining, leaving, kicking, banning room members
|
- Inviting, joining, leaving, kicking, banning room members
|
||||||
- Managing user accounts (registration, login, logout)
|
- Managing user accounts (registration, login, logout)
|
||||||
- Using 3rd Party IDs (3PIDs) such as email addresses, phone numbers,
|
- Using 3rd Party IDs (3PIDs) such as email addresses, phone numbers,
|
||||||
Facebook accounts to authenticate, identify and discover users on Matrix.
|
Facebook accounts to authenticate, identify and discover users on Matrix.
|
||||||
- Placing 1:1 VoIP and Video calls
|
- Placing 1:1 VoIP and Video calls
|
||||||
|
|
||||||
These APIs are intended to be implemented on a wide range of servers, services
|
These APIs are intended to be implemented on a wide range of servers, services
|
||||||
and clients, letting developers build messaging and VoIP functionality on top of
|
and clients, letting developers build messaging and VoIP functionality on top
|
||||||
the entirely open Matrix ecosystem rather than using closed or proprietary
|
of the entirely open Matrix ecosystem rather than using closed or proprietary
|
||||||
solutions. The hope is for Matrix to act as the building blocks for a new
|
solutions. The hope is for Matrix to act as the building blocks for a new
|
||||||
generation of fully open and interoperable messaging and VoIP apps for the
|
generation of fully open and interoperable messaging and VoIP apps for the
|
||||||
internet.
|
internet.
|
||||||
@ -98,17 +102,17 @@ In Matrix, every user runs one or more Matrix clients, which connect through to
|
|||||||
a Matrix homeserver which stores all their personal chat history and user
|
a Matrix homeserver which stores all their personal chat history and user
|
||||||
account information - much as a mail client connects through to an IMAP/SMTP
|
account information - much as a mail client connects through to an IMAP/SMTP
|
||||||
server. Just like email, you can either run your own Matrix homeserver and
|
server. Just like email, you can either run your own Matrix homeserver and
|
||||||
control and own your own communications and history or use one hosted by someone
|
control and own your own communications and history or use one hosted by
|
||||||
else (e.g. matrix.org) - there is no single point of control or mandatory
|
someone else (e.g. matrix.org) - there is no single point of control or
|
||||||
service provider in Matrix, unlike WhatsApp, Facebook, Hangouts, etc.
|
mandatory service provider in Matrix, unlike WhatsApp, Facebook, Hangouts, etc.
|
||||||
|
|
||||||
Synapse ships with two basic demo Matrix clients: webclient (a basic group chat
|
Synapse ships with two basic demo Matrix clients: webclient (a basic group chat
|
||||||
web client demo implemented in AngularJS) and cmdclient (a basic Python
|
web client demo implemented in AngularJS) and cmdclient (a basic Python
|
||||||
command line utility which lets you easily see what the JSON APIs are up to).
|
command line utility which lets you easily see what the JSON APIs are up to).
|
||||||
|
|
||||||
We'd like to invite you to take a look at the Matrix spec, try to run a
|
We'd like to invite you to take a look at the Matrix spec, try to run a
|
||||||
homeserver, and join the existing Matrix chatrooms already out there, experiment
|
homeserver, and join the existing Matrix chatrooms already out there,
|
||||||
with the APIs and the demo clients, and let us know your thoughts at
|
experiment with the APIs and the demo clients, and let us know your thoughts at
|
||||||
https://github.com/matrix-org/synapse/issues or at matrix@matrix.org.
|
https://github.com/matrix-org/synapse/issues or at matrix@matrix.org.
|
||||||
|
|
||||||
Thanks for trying Matrix!
|
Thanks for trying Matrix!
|
||||||
@ -121,14 +125,14 @@ Thanks for trying Matrix!
|
|||||||
Homeserver Installation
|
Homeserver Installation
|
||||||
=======================
|
=======================
|
||||||
|
|
||||||
First, the dependencies need to be installed. Start by installing
|
First, the dependencies need to be installed. Start by installing
|
||||||
'python2.7-dev' and the various tools of the compiler toolchain.
|
'python2.7-dev' and the various tools of the compiler toolchain.
|
||||||
|
|
||||||
Installing prerequisites on Ubuntu::
|
Installing prerequisites on Ubuntu::
|
||||||
|
|
||||||
$ sudo apt-get install build-essential python2.7-dev libffi-dev
|
$ sudo apt-get install build-essential python2.7-dev libffi-dev
|
||||||
|
|
||||||
Installing prerequisites on Mac OS X::
|
Installing prerequisites on Mac OS X::
|
||||||
|
|
||||||
$ xcode-select --install
|
$ xcode-select --install
|
||||||
|
|
||||||
@ -136,24 +140,24 @@ The homeserver has a number of external dependencies, that are easiest
|
|||||||
to install by making setup.py do so, in --user mode::
|
to install by making setup.py do so, in --user mode::
|
||||||
|
|
||||||
$ python setup.py develop --user
|
$ python setup.py develop --user
|
||||||
|
|
||||||
You'll need a version of setuptools new enough to know about git, so you
|
You'll need a version of setuptools new enough to know about git, so you
|
||||||
may need to also run:
|
may need to also run::
|
||||||
|
|
||||||
$ sudo apt-get install python-pip
|
$ sudo apt-get install python-pip
|
||||||
$ sudo pip install --upgrade setuptools
|
$ sudo pip install --upgrade setuptools
|
||||||
|
|
||||||
If you don't have access to github, then you may need to install ``syutil``
|
If you don't have access to github, then you may need to install ``syutil``
|
||||||
manually by checking it out and running ``python setup.py develop --user`` on it
|
manually by checking it out and running ``python setup.py develop --user`` on
|
||||||
too.
|
it too.
|
||||||
|
|
||||||
If you get errors about ``sodium.h`` being missing, you may also need to
|
If you get errors about ``sodium.h`` being missing, you may also need to
|
||||||
manually install a newer PyNaCl via pip as setuptools installs an old one. Or
|
manually install a newer PyNaCl via pip as setuptools installs an old one. Or
|
||||||
you can check PyNaCl out of git directly (https://github.com/pyca/pynacl) and
|
you can check PyNaCl out of git directly (https://github.com/pyca/pynacl) and
|
||||||
installing it. Installing PyNaCl using pip may also work (remember to remove any
|
installing it. Installing PyNaCl using pip may also work (remember to remove
|
||||||
other versions installed by setuputils in, for example, ~/.local/lib).
|
any other versions installed by setuputils in, for example, ~/.local/lib).
|
||||||
|
|
||||||
On OSX, if you encounter ``clang: error: unknown argument: '-mno-fused-madd'``
|
On OSX, if you encounter ``clang: error: unknown argument: '-mno-fused-madd'``
|
||||||
you will need to ``export CFLAGS=-Qunused-arguments``.
|
you will need to ``export CFLAGS=-Qunused-arguments``.
|
||||||
|
|
||||||
This will run a process of downloading and installing into your
|
This will run a process of downloading and installing into your
|
||||||
@ -177,7 +181,7 @@ Upgrading an existing homeserver
|
|||||||
|
|
||||||
Before upgrading an existing homeserver to a new version, please refer to
|
Before upgrading an existing homeserver to a new version, please refer to
|
||||||
UPGRADE.rst for any additional instructions.
|
UPGRADE.rst for any additional instructions.
|
||||||
|
|
||||||
|
|
||||||
Setting up Federation
|
Setting up Federation
|
||||||
=====================
|
=====================
|
||||||
@ -187,14 +191,14 @@ be publicly visible on the internet, and they will need to know its host name.
|
|||||||
You have two choices here, which will influence the form of your Matrix user
|
You have two choices here, which will influence the form of your Matrix user
|
||||||
IDs:
|
IDs:
|
||||||
|
|
||||||
1) Use the machine's own hostname as available on public DNS in the form of its
|
1) Use the machine's own hostname as available on public DNS in the form of
|
||||||
A or AAAA records. This is easier to set up initially, perhaps for testing,
|
its A or AAAA records. This is easier to set up initially, perhaps for
|
||||||
but lacks the flexibility of SRV.
|
testing, but lacks the flexibility of SRV.
|
||||||
|
|
||||||
2) Set up a SRV record for your domain name. This requires you create a SRV
|
2) Set up a SRV record for your domain name. This requires you create a SRV
|
||||||
record in DNS, but gives the flexibility to run the server on your own
|
record in DNS, but gives the flexibility to run the server on your own
|
||||||
choice of TCP port, on a machine that might not be the same name as the
|
choice of TCP port, on a machine that might not be the same name as the
|
||||||
domain name.
|
domain name.
|
||||||
|
|
||||||
For the first form, simply pass the required hostname (of the machine) as the
|
For the first form, simply pass the required hostname (of the machine) as the
|
||||||
--host parameter::
|
--host parameter::
|
||||||
@ -204,10 +208,10 @@ For the first form, simply pass the required hostname (of the machine) as the
|
|||||||
--config-path homeserver.config \
|
--config-path homeserver.config \
|
||||||
--generate-config
|
--generate-config
|
||||||
$ python synapse/app/homeserver.py --config-path homeserver.config
|
$ python synapse/app/homeserver.py --config-path homeserver.config
|
||||||
|
|
||||||
Alternatively, you can run synapse via synctl - running ``synctl start`` to
|
Alternatively, you can run synapse via synctl - running ``synctl start`` to
|
||||||
generate a homeserver.yaml config file, where you can then edit server-name to
|
generate a homeserver.yaml config file, where you can then edit server-name to
|
||||||
specify machine.my.domain.name, and then set the actual server running again
|
specify machine.my.domain.name, and then set the actual server running again
|
||||||
with synctl start.
|
with synctl start.
|
||||||
|
|
||||||
For the second form, first create your SRV record and publish it in DNS. This
|
For the second form, first create your SRV record and publish it in DNS. This
|
||||||
@ -269,8 +273,8 @@ account. Your name will take the form of::
|
|||||||
|
|
||||||
Specify your desired localpart in the topmost box of the "Register for an
|
Specify your desired localpart in the topmost box of the "Register for an
|
||||||
account" form, and click the "Register" button. Hostnames can contain ports if
|
account" form, and click the "Register" button. Hostnames can contain ports if
|
||||||
required due to lack of SRV records (e.g. @matthew:localhost:8080 on an internal
|
required due to lack of SRV records (e.g. @matthew:localhost:8080 on an
|
||||||
synapse sandbox running on localhost)
|
internal synapse sandbox running on localhost)
|
||||||
|
|
||||||
|
|
||||||
Logging In To An Existing Account
|
Logging In To An Existing Account
|
||||||
@ -285,9 +289,9 @@ Identity Servers
|
|||||||
|
|
||||||
The job of authenticating 3PIDs and tracking which 3PIDs are associated with a
|
The job of authenticating 3PIDs and tracking which 3PIDs are associated with a
|
||||||
given Matrix user is very security-sensitive, as there is obvious risk of spam
|
given Matrix user is very security-sensitive, as there is obvious risk of spam
|
||||||
if it is too easy to sign up for Matrix accounts or harvest 3PID data. Meanwhile
|
if it is too easy to sign up for Matrix accounts or harvest 3PID data.
|
||||||
the job of publishing the end-to-end encryption public keys for Matrix users is
|
Meanwhile the job of publishing the end-to-end encryption public keys for
|
||||||
also very security-sensitive for similar reasons.
|
Matrix users is also very security-sensitive for similar reasons.
|
||||||
|
|
||||||
Therefore the role of managing trusted identity in the Matrix ecosystem is
|
Therefore the role of managing trusted identity in the Matrix ecosystem is
|
||||||
farmed out to a cluster of known trusted ecosystem partners, who run 'Matrix
|
farmed out to a cluster of known trusted ecosystem partners, who run 'Matrix
|
||||||
@ -296,7 +300,7 @@ track 3PID logins and publish end-user public keys.
|
|||||||
|
|
||||||
It's currently early days for identity servers as Matrix is not yet using 3PIDs
|
It's currently early days for identity servers as Matrix is not yet using 3PIDs
|
||||||
as the primary means of identity and E2E encryption is not complete. As such,
|
as the primary means of identity and E2E encryption is not complete. As such,
|
||||||
we are running a single identity server (http://matrix.org:8090) at the current
|
we are running a single identity server (http://matrix.org:8090) at the current
|
||||||
time.
|
time.
|
||||||
|
|
||||||
|
|
||||||
|
Loading…
Reference in New Issue
Block a user