Package: matrix-sydent
What is Sydent?Sydent is anidentity serverfor theMatrix communications protocol. It allows Matrix users to prove that they own an email address or phone number, and allows _other_ Matrix users to look them up using that email address or phone number.Do I need to run Sydent to run my own homeserver?Short answer:no.Medium answer:probably not. Most homeservers and clients use the Sydent
instance run bymatrix.org, or use no identity server whatsoever.Longer answer: if you want to allow user lookup via emails and phone numbers in
a private federation of multiple homeservers, Sydent _might_ be useful for you.
If you want your homeserver to be able to verify phone numbers via SMS and
you have an API token for theOpenMarket HTTP SMS API, then
Sydent might be useful for you.InstallationInstalling the system dependenciesTo install Sydent’s dependencies on a Debian-based system, run:sudo apt-get install build-essential python3-dev libffi-dev \
                     sqlite3 libssl-dev python3-virtualenv libxslt1-devFrom here, you can either install Sydent by using a PyPI release, or by recreating Sydent’s locked runtime environment.Installing the latest Sydent release from PyPITo create the virtual environment in which Sydent will run:virtualenv -p python3 ~/.sydent
source ~/.sydent/bin/activate
pip install --upgrade pip
pip install --upgrade setuptoolsSydent and its dependencies can be installed usingpipby running:pip install matrix-sydentWith the virtualenv activated, you can run Sydent using:python -m sydent.sydentInstalling from sourceAlternatively, Sydent can be installed usingpoetryfrom a local git checkout.
First installpoetry. Seepoetry’s documentationfor details; we recommend installing viapipx. Once that’s done:git clone https://github.com/matrix-org/sydent.git
cd sydent
poetry install --no-dev
# For development, pull in extra tools with
# poetry installTo start Sydent:poetry run sydentRunning SydentWhen Sydent is first run, it will create a configuration file insydent.confwith some defaults.
If a setting is defined in both the[DEFAULT]section and another section in the configuration file,
then the value in the other section is used.You’ll most likely want to change the server name (server.name) and specify an email server
(look for the settings starting withemail.).By default, Sydent will listen on0.0.0.0:8090. This can be changed by changing the values for
the configuration settingsclientapi.http.bind_addressandclientapi.http.port.Sydent uses SQLite as its database backend. By default, it will create the database assydent.dbin its working directory. The name can be overridden by modifying thedb.fileconfiguration option.
Sydent is known to be working with SQLite version 3.16.2 and later.Listening for HTTPS connectionsMost homeservers and clients will expect identity servers to be reachable using HTTPS.Sydent does not currently support listening for HTTPS connection by itself. Instead, it
is recommended to use a reverse proxy to proxy requests from homeservers and clients to
Sydent. It is then possible to have this reverse proxy serve Sydent’s API over HTTPS.When using a reverse proxy, it is recommended to limit the requests proxied to Sydent to
ones which paths start with/_matrix/identityfor security reasons.An exception to this is Sydent’s internal replication API, seedocs/replication.md.SMS originatorsDefaults for SMS originators will not be added to the generated config file, these should
be added to the[sms]section of that config file in the form:originators.<country code> = <long|short|alpha>:<originator>Where country code is the numeric country code, ordefaultto specify the originator
used for countries not listed. For example, to use a selection of long codes for the
US/Canada, a short code for the UK and an alphanumertic originator for everywhere else:originators.1 = long:12125552368,long:12125552369
originators.44 = short:12345
originators.default = alpha:MatrixDockerA Dockerfile is provided for sydent. To use it, rundocker build-tsydent .in a sydent checkout.
To run it, usedocker run--env=SYDENT_SERVER_NAME=my-sydent-server-p8090:8090 sydent.Persistent dataBy default, all data is stored in/data. To persist this to disk, bind/datato a
Docker volume.dockervolumecreatesydent-datadockerrun...--mounttype=volume,source=sydent-data,destination=/datasydentBut you can also bind a local directory to the container.
However, you then have to pay attention to the file permissions.mkdir/path/to/sydent-datachown993:993/path/to/sydent-datadockerrun...--mounttype=bind,source=/path/to/sydent-data,destination=/datasydentEnvironment variablesWarningThese variables are only taken into account at first start and are written to the configuration file.Variable NameSydent defaultDockerfile defaultSYDENT_SERVER_NAMEemptyemptySYDENT_CONFsydent.conf/data/sydent.confSYDENT_PID_FILEsydent.pid/data/sydent.pidSYDENT_DB_PATHsydent.db/data/sydent.dbInternal bind and unbind APIIt is possible to enable an internal API which allows for binding and unbinding
between identifiers and matrix IDs without any validation.
This is open to abuse, so is disabled by
default, and when it is enabled, is available only on a separate socket which
is bound tolocalhostby default.To enable it, configure the port in the config file. For example:[http]
internalapi.http.port = 8091To change the address to which that API is bound, set theinternalapi.http.bind_addressconfiguration
setting in the[http]section, for example:[http]
internalapi.http.port = 8091
internalapi.http.bind_address = 192.168.0.18As already mentioned above, this is open to abuse, so make sure this address is not publicly accessible.To use bind:curl -XPOST 'http://localhost:8091/_matrix/identity/internal/bind' -H "Content-Type: application/json" -d '{"address": "matthew@arasphere.net", "medium": "email", "mxid": "@matthew:matrix.org"}'The response has the same format as/_matrix/identity/api/v1/3pid/bind.To use unbind:curl -XPOST 'http://localhost:8091/_matrix/identity/internal/unbind' -H "Content-Type: application/json" -d '{"address": "matthew@arasphere.net", "medium": "email", "mxid": "@matthew:matrix.org"}'The response has the same format as/_matrix/identity/api/v1/3pid/unbind.ReplicationIt is possible to configure a mesh of Sydent instances which replicate identity bindings
between each other. Seedocs/replication.md.DiscussionMatrix room:#sydent:matrix.org.