GitHubじゃ!Pythonじゃ!

GitHubからPython関係の優良リポジトリを探したかったのじゃー、でも英語は出来ないから日本語で読むのじゃー、英語社会世知辛いのじゃー

matrix-org

synapse – シナプス:マトリックスリファレンスホームサーバー

投稿日:

シナプス:マトリックスリファレンスホームサーバー http://matrix.org

内容

前書き

MatrixはオープンなフェデレーションインスタントメッセージングとVoIPの野心的な新しいエコシステムです。 起動して実行するために知る必要がある基本事項は次のとおりです。

  • 行列のすべてが部​​屋で起こります。 部屋は分散されており、単一のサーバーには存在しません。 部屋は#matrix:matrix.org#test:localhost:8448ような便利なエイリアスを使って#matrix:matrix.orgことができます。
  • MatrixユーザーIDは@matthew:matrix.orgように見えます(ただし、将来的にはMatrixユーザーIDを操作するのではなく、電子メールアドレス、電話番号などの第三者識別子(3PID)を使用して自分自身や他者を参照します)

全体的なアーキテクチャは次のとおりです。

client <----> homeserver <=====================> homeserver <----> client
       https://somewhere.org/_matrix      https://elsewhere.net/_matrix

#matrix:matrix.orgはMatrixの正式なサポート室であり、 #matrix:matrix.org任意のクライアントやirc://でIRCブリッジを介してアクセスできますirc.freenode.net/matrix。

Synapseは現在急速に開発されていますが、バージョン0.5以降では、実際の使用に向けたインターネット接続サービスとして十分に安定していると考えています。

マトリックスについて

Matrixでは、実用的なRESTful HTTP JSON APIのセットをオープンスタンダードとして指定しています。

  • 単一のコントロールポイントまたは障害のない完全に分散したチャットルームの作成と管理
  • 最終的には、連合されたサーバーとサービスのグローバルなオープンネットワーク全体で、部屋の状態を暗号的に安全に同期させる
  • (オプションの)エンドツーエンド暗号化を使用して部屋に拡張メッセージを送受信する[1]
  • 招待、参加、退室、蹴り、部屋のメンバーの禁止
  • ユーザーアカウントの管理(登録、ログイン、ログアウト)
  • メールアドレス、電話番号、Facebookアカウントなどの第三者ID(3PID)を使用して、Matrix上のユーザーを認証し、識別し、発見します。
  • VoIPとビデオの1:1呼び出し

これらのAPIは、幅広いサーバー、サービス、およびクライアントに実装することを目的としており、クローズドまたは独自のソリューションを使用するのではなく、完全にオープンなMatrixエコシステムの上にメッセージングおよびVoIP機能を構築できます。 マトリクスは、完全にオープンで相互運用可能なメッセージングとインターネット用のVoIPアプリケーションの新世代の構築ブロックとして機能することが期待されています。

Synapseは、Python / Twistedで書かれたmatrix.orgのコア開発チームからのMatrixのリファレンス “ホームサーバー”実装です。 これは、Matrixの概念を紹介し、コードベースのコンテキストで仕様を見て、自分のホームサーバーを実行させ、一般的にエコシステムのブートストラップを助けることを目的としています。

Matrixでは、すべてのユーザーが1つまたは複数のMatrixクライアントを実行し、MatrixクライアントはMatrixホームサーバーに接続します。 ホームサーバーは、個人のチャット履歴とユーザーアカウント情報をすべて保存します。メールクライアントがIMAP / SMTPサーバーに接続するのと同じくらいです。 電子メールと同じように、独自のMatrixホームサーバーを実行し、独自のコミュニケーションと履歴を管理したり、他の人がホストしているものを使用することもできます(matrix.orgなど)。Matrixには単一のコントロールポイントまたは必須サービスプロバイダはありません。 WhatsApp、Facebook、ハングアウトなど

#matrix:matrix.org( https://matrix.org/docs/projects/try-matrix-now.html経由)に参加し、ホームサーバーを実行し、 Matrix仕様を見て、 APIクライアントSDKを試してみてください。

Matrixをご利用いただきありがとうございます!

[1]エンドツーエンドの暗号化は現在ベータ版です: ブログ記事

Synapseのインストール

SynapseはPython / Twisted Matrixホームサーバーの実装を参照しています。

システム要求:

  • POSIX準拠のシステム(LinuxおよびOS Xでテスト済み)
  • Python 2.7
  • #matrix:matrix.orgのような大規模なパブリックルームに参加するには、少なくとも1GBの空きRAMが必要です

ソースからインストールする

(ビルド済みのパッケージは一部のプラットフォームで使用できます – 「 プラットフォーム固有の注意事項」を参照してください)。

SynapseはPythonで書かれていますが、使用するライブラリの一部はCで書かれています。そこで、シナプス自体をインストールする前に、動作するCコンパイラと、Python C拡張のヘッダファイルが必要です。

UbuntuまたはDebianでの前提条件のインストール:

sudo apt-get install build-essential python2.7-dev libffi-dev \
                     python-pip python-setuptools sqlite3 \
                     libssl-dev python-virtualenv libjpeg-dev libxslt1-dev

ArchLinuxの前提条件のインストール:

sudo pacman -S base-devel python2 python-pip \
               python-setuptools python-virtualenv sqlite3

CentOS 7またはFedora 25の前提条件のインストール:

sudo yum install libtiff-devel libjpeg-devel libzip-devel freetype-devel \
                 lcms2-devel libwebp-devel tcl-devel tk-devel redhat-rpm-config \
                 python-virtualenv libffi-devel openssl-devel
sudo yum groupinstall "Development Tools"

Mac OS Xでの前提条件のインストール:

xcode-select --install
sudo easy_install pip
sudo pip install virtualenv
brew install pkg-config libffi

Raspbianの前提条件のインストール:

sudo apt-get install build-essential python2.7-dev libffi-dev \
                     python-pip python-setuptools sqlite3 \
                     libssl-dev python-virtualenv libjpeg-dev
sudo pip install --upgrade pip
sudo pip install --upgrade ndg-httpsclient
sudo pip install --upgrade virtualenv

openSUSEの前提条件のインストール:

sudo zypper in -t pattern devel_basis
sudo zypper in python-pip python-setuptools sqlite3 python-virtualenv \
               python-devel libffi-devel libopenssl-devel libjpeg62-devel

OpenBSDでの前提条件のインストール:

doas pkg_add python libffi py-pip py-setuptools sqlite3 py-virtualenv \
             libxslt

シナプスホームサーバーをインストールするには:

virtualenv -p python2.7 ~/.synapse
source ~/.synapse/bin/activate
pip install --upgrade pip
pip install --upgrade setuptools
pip install https://github.com/matrix-org/synapse/tarball/master

これにより、使用しているライブラリとともに、シナプスが~/.synapse下の仮想環境に~/.synapseます。 必要に応じて、別のディレクトリを自由に選んでください。

問題が発生した場合は、下記の「トラブルシューティング」を参照してください。

あるいは、Andreas Peters(以前はSilvio Fricke)がDockerファイルを寄稿してDockerの上記を自動化しました( https://hub.docker.com/r/avhost/docker-matrix/tags/)。

また、Martin Giess氏は、VirtualBox / AWS / DigitalOceanでテストされている迷惑行為/不可抗力の自動展開プロセスを作成しました。詳細はhttps://github.com/EMnify/matrix-synapse-auto-deployを参照してください。

シナプスの設定

Synapseを開始する前に、構成ファイルを生成する必要があります。 これを行うには、前と同じようにvirtualenvで実行します:

cd ~/.synapse
python -m synapse.app.homeserver \
    --server-name my.domain.name \
    --config-path homeserver.yaml \
    --generate-config \
    --report-stats=[yes|no]

--server-name適切な値を代入します。 サーバー名は、サーバー上のユーザーのuser-idsの「ドメイン」部分を決定します。これらはすべて、 @user:my.domain.nameという形式です。 また、他のマトリックスサーバーがどのようにあなたのものに到達するかを決定します。 テスト構成の場合は、これをサーバーのホスト名に設定します。 プロダクション対応の設定をするには、マトリックス固有のホスト名ではなく、ドメイン( example.com )を指定することをお勧めします( user@email.example.comではなくuser@example.comと同じ方法が考えられuser@email.example.com ) – そうすることでより高度な設定が必要になることがあります – フェデレーションの設定を参照してください。 後でサーバー名を変更することはできないことに注意してください。

このコマンドを実行すると、カスタマイズすることができる設定ファイルが生成されますが、一連のキーも生成されます。 これらのキーは、ホームサーバーが他のホームサーバーに自身を識別させるようにします。 それらを安全な場所にバックアップすることが賢明でしょう。 (何らかの理由でホームサーバーのキーを変更する必要がある場合は、他のホームサーバーに古いキーがキャッシュされていることがあります)。署名キーを更新する場合は、 <server name>.signing.keyファイル(2番目の単語)を別のものに変更します。キー管理の詳細については、仕様を参照してください。

デフォルト設定では、2つのHTTPポート8008と8448が公開されています。ポート8008はTLSなしで設定されています。 ポート443上のTLS / SSL終端用のリバースプロキシの背後にある必要があります。これは、クライアント用に使用する必要があります。 ポート8448は、自己署名証明書でTLSを使用するように構成されています。 リバースプロキシを設定することなくクライアントで初期テストを行いたい場合は、別の証明書を一時的に使用することができます。 フェデレーションの場合 、自己署名証明書は問題ありません )。 これを行うには、 tls_private_key_path tls_certificate_pathtls_private_key_pathおよびtls_dh_params_pathhomeserver.yamlます。 代わりに、リバースプロキシを使用することもできますが、その際に必ずSynapseでリバースプロキシを使用するをお読みください。

TLSを使用するポート8448とは別に、両方のポートはデフォルト設定で同じです。

ユーザーの登録

Matrixクライアントを使用するには、サーバーに少なくとも1人のユーザーが必要です。 ユーザーは、Matrixクライアントを介して、またはコマンドラインスクリプトを介して登録することができます。

まず、コマンドラインを使用して新規ユーザーを登録するのが最も簡単です。

$ source ~/.synapse/bin/activate
$ synctl start # if not already running
$ register_new_matrix_user -c homeserver.yaml https://localhost:8448
New user localpart: erikj
Password:
Confirm password:
Make admin [no]:
Success!

このプロセスでは、 homeserver.yaml設定が使用register_new_matrix_userます。これは、Synapse自体とregister_new_matrix_userスクリプトで共有register_new_matrix_userます。 それは何であろうと(無作為な値は--generate-configによって生成されます)、それを知っている人ならenable_registrationfalseあってもあなたのサーバ上のユーザを登録できるので、秘密にしておく必要がありfalse

TURNサーバーの設定

このホームサーバ経由で信頼できるVoIPコールをルーティングするには、TURNサーバを設定する必要があります。 詳細については、 docs / turn-howto.rstを参照してください。

IPv6

Synapse 0.19では、私は最終的にIPv6をサポートしました。PR#1696を提供するために@kyriasと@glyphに感謝しています。

ただし、フェデレーションがIPv6 DNSサーバーを使用するホストで動作するに 、Twisted 17.1.0以降が必要です。詳しくは、 https://github.com/matrix-org/synapse/issues/1002を参照してください。 SynapseをデフォルトでTwisted 17.1に依存させることはできません。これは、古いバージョンのディストリビューション( https://github.com/matrix-org/synapse/pull/1909を参照)を破るためです。オペレーティングシステムの依存関係を使用している場合、ピストやバックポートなどで自分のTwisted 17.1パッケージをインストールする必要があります。

あなたがvirtualenvで走っているならば、pipは自動的に最新のTwistedをインストールしていなければなりませんが、あなたのvirtualenvが古い場合、手動で新しいTwisted依存性にアップグレードする必要があります:

pipインストールTwisted> = 17.1.0

シナプスの実行

新しいホームサーバーを実際に実行するには、Synapseが動作するための作業ディレクトリ(例えば、 ~/.synapse )を選択し、

cd ~/.synapse
source ./bin/activate
synctl start

クライアントからのシナプスへの接続

新しいSynapseインストールを試す最も簡単な方法は、Webクライアントから接続することです。 最も簡単なオプションは、おそらくhttp://riot.im/appのものです。 ログオン時または登録時に「カスタムサーバー」を指定する必要がありhttps://domain.tld推奨セットアップまたはhttps://localhost:8448 https://domain.tldリバースプロキシを設定する場合は、これをhttps://domain.tld設定します。ポート( :8448 )(そうでない場合は:443 )。 (アイデンティティサーバーをデフォルトのままにします 。「 アイデンティティサーバー 」を参照してください)。

ポート8448を使用している場合は、自己署名証明書を受け入れるまでエラーになります。 ブラウザでhttps://localhost:8448直接アクセスし、提示された証明書を受け入れることで、簡単にこれを行うことができます。 その後、Webクライアントに戻ってさらに進めていくことができます。

すべてがうまくいけば、少なくともログインして部屋を作り、メッセージを送ることができるはずです。

(ホームサーバーはデフォルトでhttps:// localhost:8448 /にWebクライアントを実行しますが 、執筆時点では古くて、実際には推奨されていません – https://github.com/matrix-org/synapse/issues / 1527 )。

クライアントから新しいユーザーを登録する

デフォルトでは、Matrixクライアントを介した新規ユーザーの登録は無効になっています。 有効にするには、 enable_registration: trueを指定します。 (CAPTCHAも設定することをお勧めします – docs / CAPTCHA_SETUP.rstを参照してください)。

enable_registrationtrueに設定されると、 riot.imまたは他のMatrixクライアント経由でユーザを登録することができます。

新しいユーザ名は、 server_nameシナプスの設定を参照)から部分的に形成され、一部はアカウント作成時に指定したlocalpartから形成されます。 あなたの名前は次の形式になります:

@localpart:my.domain.name

( “私のドットドメインドット名にlocalpartで発音”)。

ログイン時と同じように、「カスタムサーバー」を指定する必要があります。 [ユーザー名]ボックスに必要なlocalpartを指定します。

セキュリティ上の注意

Matrixは、一部のAPI、特にコンテンツリポジトリのエンドポイントで生のユーザー生成データを処理します

起こりうるXSS攻撃(例えばhttps://github.com/matrix-org/synapse/pull/1021 )を軽減しようとする一方で、専用のドメイン名でマトリックスホームサーバーを実行し、悪意のあるユーザー生成コンテンツをWebブラウザでは、同じドメイン上にホストされているWebアプリケーションを攻撃することができないように、マトリックスAPIがあります。 これは、同じドメイン上のマトリックスWebクライアントとサーバーを共有する場合に特に当てはまります。

詳細については、 https://github.com/vector-im/vector-web/issues/1977およびhttps://developer.github.com/changes/2014-04-25-user-content-securityを参照してください。

プラットフォーム固有の命令

Debian

Matrixは、 http: //matrix.org/packages/debian/から公式のDebianパッケージを提供しています。 これらのパッケージにはクライアントが含まれていないことに注意してください。https://matrix.org/docs/projects/try-matrix-now.htmlから1つを選択してください (または、私たちのSDKの1つで自分自身をビルドしてください:)

フェドラ

シナプスは、フェドラのリポジトリにmatrix-synapseとして存在します:

sudo dnf install matrix-synapse

Oleg GirkoはFedora RPMをhttps://obs.infoserver.lv/project/monitor/matrix-synapseで提供しています。

ArchLinux

ArchLinuxを立ち上げて実行する最も速い方法はおそらく、コミュニティパッケージhttps://www.archlinux.org/packages/community/any/matrix-synapse/です 。これは、必要な依存関係のほとんどを引き出すはずです。 デフォルトのWebクライアントを提供する場合(生成された設定ではデフォルトで有効)、 https://www.archlinux.org/packages/community/any/python2-matrix-angular-sdk/もインストールする必要があります。

あるいは、pipを使用してインストールするには、ArchLinuxがPython 3にデフォルト設定されているため、いくつかの変更が必要かもしれませんが、現在シナプスはデフォルトでPython 2.7を前提としています:

pipが古くなっている可能性があります(6.0.7-1、6.0.8-1にアップグレードする必要があります)。

sudo pip2.7 install --upgrade pip

また、インストール要求中にpython 2.7を明示的に指定する必要があるかもしれません:

pip2.7 install https://github.com/matrix-org/synapse/tarball/master

誤ったELFクラス:ELFCLASS32(x64システム)を引き起こすlib bcryptでエラーが発生した場合は、py-bcryptを再インストールして適切なアーキテクチャで正しくコンパイルする必要があります。 (これはvirtualenvの下にインストールする場合は必要ありません):

sudo pip2.7 uninstall py-bcrypt
sudo pip2.7 install py-bcrypt

Synapseのセットアップ中にpython2.7を直接呼び出す必要があります:

cd ~/.synapse
python2.7 -m synapse.app.homeserver \
  --server-name machine.my.domain.name \
  --config-path homeserver.yaml \
  --generate-config

…あなたのホストとドメイン名を適切に置き換えてください。

FreeBSD

Synapseは、Brendan Molloyが寄稿したFreeBSDのポートまたはパッケージを通じてインストールできます:

  • ポート: cd /usr/ports/net-im/py-matrix-synapse && make install clean
  • パッケージ: pkg install py27-matrix-synapse

OpenBSD

現在、OpenBSD用のポートはありません。 さらに、OpenBSDのセキュリティ設定には、やや難しいインストールプロセスが必要です。

  1. _synapseという新しいディレクトリを/usr/local作成します。 また、 _synapseという新しいユーザーを作成し、そのユーザーのホームとしてそのディレクトリを設定します。 これは、デフォルトでOpenBSDが/usr/localから同じメモリ空間上で書き込みと実行の許可を必要とするバイナリのみを許可するためです。
  2. suを新しい_synapseユーザーに_synapse 、ホームディレクトリに移動します。
  3. 新しいvirtualenvを作成します: virtualenv -p python2.7 ~/.synapse
  4. /usr/local/_synapse/.synapse/bin/activateあるvirtualenv設定を入手します。 これはkshを使って行われ. コマンドではなく、 bashsourceです。
  5. オプションで、 pipを使用してlxmlをインストールしlxml 。これは、Synapseがタイトル用のWebページを解析する必要があります。
  6. pipを使用してこのリポジトリをpip install https://github.com/matrix-org/synapse/tarball/masterpip install https://github.com/matrix-org/synapse/tarball/master
  7. オプションで、 _synapseのシェルを/bin/falseに変更して、侵害されたSynapseサーバーがボックスを引き継ぐ可能性を減らします。

その後、残りのインストール手順を進めることができます。

NixOS

Robin Lambertzは、Synapse for NixOSをhttps://github.com/NixOS/nixpkgs/blob/master/nixos/modules/services/misc/matrix-synapse.nixにパッケージングしました。

Windowsインストール

SynapseはCygwinにインストールできます。 以下のCygwinパッケージが必要です:

  • gcc
  • git
  • libffi-devel
  • openssl(そしてopenssl-devel、python-openssl)
  • パイソン
  • python-setuptools

コンテンツリポジトリには追加のパッケージが必要です。コンテンツリポジトリを使用せずにアップロードを処理することはできません。

  • libjpeg8
  • libjpeg8-devel
  • zlib

これらのパッケージを使用せずにSynapseをインストールする場合は、変更を適用するためにpillowを再インストールする必要があります。たとえば、 pip uninstall pillow pip install pillow --user

トラブルシューティング:

  • これを正しく動作させるには、 setuptoolsをアップグレードする必要があります: pip install setuptools --upgrade
  • libffi-develインストールされていてもffi.hが見つからないというエラーが発生することがあります。 その場合は、 .hファイルをコピーしcp /usr/lib/libffi-3.0.13/include/*.h /usr/include
  • PyNaclをインストールするには、ソースからlibsodiumをインストールする必要があります。 もしそうなら、 libsodium.aへのシンボリックリンクを作成する必要があるかもしれませんlibsodium.a ln -s /usr/local/lib/libsodium.a /usr/lib/libsodium.a

トラブルシューティング

インストールのトラブルシューティング

Synapseにはpip 1.7以降が必要です。したがって、OSのバージョンが古すぎる場合は、手動でアップグレードする必要があります。

sudo pip install --upgrade pip

インストールが失敗することCould not find any downloads that satisfy the requirement pymacaroons-pynacl (from matrix-synapse==0.12.0)ことがCould not find any downloads that satisfy the requirement pymacaroons-pynacl (from matrix-synapse==0.12.0) これを修正するには、pipとvirtualenvを手動でアップグレードします。

sudo pip install --upgrade virtualenv

次に、 virtualenv -p python2.7 synapseを再実行して、仮想virtualenv -p python2.7 synapseを更新することができます。

InsecurePlatformWarning: A true SSLContext object is not available. This prevents urllib3 from configuring SSL appropriately and may cause certain SSL connections to fail. For more information, see https://urllib3.readthedocs.org/en/latest/security.html#insecureplatformwarning. virtualenvをインストール中にインストールが失敗するInsecurePlatformWarning: A true SSLContext object is not available. This prevents urllib3 from configuring SSL appropriately and may cause certain SSL connections to fail. For more information, see https://urllib3.readthedocs.org/en/latest/security.html#insecureplatformwarning. InsecurePlatformWarning: A true SSLContext object is not available. This prevents urllib3 from configuring SSL appropriately and may cause certain SSL connections to fail. For more information, see https://urllib3.readthedocs.org/en/latest/security.html#insecureplatformwarning. ndg-httpsclientを手動でインストールすることでこれを修正できます:

pip install --upgrade ndg-httpsclient

mock requires setuptools>=17.1. Aborting installationインストールすると失敗するかもしれませんmock requires setuptools>=17.1. Aborting installation mock requires setuptools>=17.1. Aborting installation setuptoolsをアップグレードすることでこれを修正できます:

pip install --upgrade setuptools

pipがインストール中にクラッシュした場合(つまり、端末が失われた場合)、pipは作成した一時インストールディレクトリを削除するまで実行を拒否することがあります。 インストールをリセットするには:

rm -rf /tmp/pip_install_matrix

pipはインストール中にたくさんのメモリがリークするようです。 たとえば、512MBのRAMを搭載したLinuxホストでは、Twistedをインストールしている間にメモリが不足する可能性があります。 このような場合は、失敗した依存関係を個別にインストールする必要があります。

pip install twisted

OS Xでは、clang:error:unknown引数: ‘-mno-fused-madd’が発生した場合、CFLAGS = -Qunused-argumentsをエクスポートする必要があります。

実行中のトラブルシューティング

If synapse fails with missing "sodium.h" crypto errors, you may need to manually upgrade PyNaCL, as synapse uses NaCl ( http://nacl.cr.yp.to/ ) for encryption and digital signatures. Unfortunately PyNACL currently has a few issues ( https://github.com/pyca/pynacl/issues/53 ) and ( https://github.com/pyca/pynacl/issues/79 ) that mean it may not install correctly, causing all tests to fail with errors about missing “sodium.h”. To fix try re-installing from PyPI or directly from ( https://github.com/pyca/pynacl ):

# Install from PyPI
pip install --user --upgrade --force pynacl

# Install from github
pip install --user https://github.com/pyca/pynacl/tarball/master

Running out of File Handles

If synapse runs out of filehandles, it typically fails badly – live-locking at 100% CPU, and/or failing to accept new TCP connections (blocking the connecting client). Matrix currently can legitimately use a lot of file handles, thanks to busy rooms like #matrix:matrix.org containing hundreds of participating servers. The first time a server talks in a room it will try to connect simultaneously to all participating servers, which could exhaust the available file descriptors between DNS queries & HTTPS sockets, especially if DNS is slow to respond. (We need to improve the routing algorithm used to be better than full mesh, but as of June 2017 this hasn’t happened yet).

If you hit this failure mode, we recommend increasing the maximum number of open file handles to be at least 4096 (assuming a default of 1024 or 256). This is typically done by editing /etc/security/limits.conf

Separately, Synapse may leak file handles if inbound HTTP requests get stuck during processing – eg blocked behind a lock or talking to a remote server etc. This is best diagnosed by matching up the ‘Received request’ and ‘Processed request’ log lines and looking for any ‘Processed request’ lines which take more than a few seconds to execute. Please let us know at #matrix-dev:matrix.org if you see this failure mode so we can help debug it, however.

ArchLinux

If running $ synctl start fails with ‘returned non-zero exit status 1’, you will need to explicitly call Python2.7 – either running as:

python2.7 -m synapse.app.homeserver --daemonize -c homeserver.yaml

…or by editing synctl with the correct python executable.

Upgrading an existing Synapse

The instructions for upgrading synapse are in UPGRADE.rst . Please check these instructions as upgrading may require extra steps for some versions of synapse.

Setting up Federation

Federation is the process by which users on different servers can participate in the same room. For this to work, those other servers must be able to contact yours to send messages.

As explained in Configuring synapse , the server_name in your homeserver.yaml file determines the way that other servers will reach yours. By default, they will treat it as a hostname and try to connect to port 8448. This is easy to set up and will work with the default configuration, provided you set the server_name to match your machine’s public DNS hostname.

For a more flexible configuration, you can set up a DNS SRV record. This allows you to run your server on a machine that might not have the same name as your domain name. For example, you might want to run your server at synapse.example.com , but have your Matrix user-ids look like @user:example.com . (A SRV record also allows you to change the port from the default 8448. However, if you are thinking of using a reverse-proxy on the federation port, which is not recommended, be sure to read Reverse-proxying the federation port first.)

To use a SRV record, first create your SRV record and publish it in DNS. This should have the format _matrix._tcp.<yourdomain.com> <ttl> IN SRV 10 0 <port> <synapse.server.name> . The DNS record should then look something like:

$ dig -t srv _matrix._tcp.example.com
_matrix._tcp.example.com. 3600    IN      SRV     10 0 8448 synapse.example.com.

You can then configure your homeserver to use <yourdomain.com> as the domain in its user-ids, by setting server_name :

python -m synapse.app.homeserver \
    --server-name <yourdomain.com> \
    --config-path homeserver.yaml \
    --generate-config
python -m synapse.app.homeserver --config-path homeserver.yaml

If you’ve already generated the config file, you need to edit the server_name in your homeserver.yaml file. If you’ve already started Synapse and a database has been created, you will have to recreate the database.

If all goes well, you should be able to connect to your server with a client , and then join a room via federation. (Try #matrix-dev:matrix.org as a first step. “Matrix HQ”‘s sheer size and activity level tends to make even the largest boxes pause for thought.)

トラブルシューティング

You can use the federation tester to check if your homeserver is all set: https://matrix.org/federationtester/api/report?server_name=<your_server_name> If any of the attributes under “checks” is false, federation won’t work.

The typical failure mode with federation is that when you try to join a room, it is rejected with “401: Unauthorized”. Generally this means that other servers in the room couldn’t access yours. (Joining a room over federation is a complicated dance which requires connections in both directions).

So, things to check are:

  • If you are trying to use a reverse-proxy, read Reverse-proxying the federation port .
  • If you are not using a SRV record, check that your server_name (the part of your user-id after the : ) matches your hostname, and that port 8448 on that hostname is reachable from outside your network.
  • If you are using a SRV record, check that it matches your server_name (it should be _matrix._tcp.<server_name> ), and that the port and hostname it specifies are reachable from outside your network.

Running a Demo Federation of Synapses

If you want to get up and running quickly with a trio of homeservers in a private federation, there is a script in the demo directory. This is mainly useful just for development purposes. See demo/README .

Using PostgreSQL

As of Synapse 0.9, PostgreSQL is supported as an alternative to the SQLite database that Synapse has traditionally used for convenience and simplicity.

The advantages of Postgres include:

  • significant performance improvements due to the superior threading and caching model, smarter query optimiser
  • allowing the DB to be run on separate hardware
  • allowing basic active/backup high-availability with a “hot spare” synapse pointing at the same DB master, as well as enabling DB replication in synapse itself.

For information on how to install and use PostgreSQL, please see docs/postgres.rst .

Using a reverse proxy with Synapse

It is recommended to put a reverse proxy such as nginx , Apache or HAProxy in front of Synapse. One advantage of doing so is that it means that you can expose the default https port (443) to Matrix clients without needing to run Synapse with root privileges.

The most important thing to know here is that Matrix clients and other Matrix servers do not necessarily need to connect to your server via the same port. Indeed, clients will use port 443 by default, whereas servers default to port 8448. Where these are different, we refer to the ‘client port’ and the ‘federation port’.

The next most important thing to know is that using a reverse-proxy on the federation port has a number of pitfalls. It is possible, but be sure to read Reverse-proxying the federation port .

The recommended setup is therefore to configure your reverse-proxy on port 443 to port 8008 of synapse for client connections, but to also directly expose port 8448 for server-server connections. All the Matrix endpoints begin /_matrix , so an example nginx configuration might look like:

server {
    listen 443 ssl;
    listen [::]:443 ssl;
    server_name matrix.example.com;

    location /_matrix {
        proxy_pass http://localhost:8008;
        proxy_set_header X-Forwarded-For $remote_addr;
    }
}

You will also want to set bind_addresses: ['127.0.0.1'] and x_forwarded: true for port 8008 in homeserver.yaml to ensure that client IP addresses are recorded correctly.

Having done so, you can then use https://matrix.example.com (instead of https://matrix.example.com:8448 ) as the “Custom server” when Connecting to Synapse from a client .

Reverse-proxying the federation port

There are two issues to consider before using a reverse-proxy on the federation port:

  • Due to the way SSL certificates are managed in the Matrix federation protocol (see spec ), Synapse needs to be configured with the path to the SSL certificate, even if you do not terminate SSL at Synapse .
  • Synapse does not currently support SNI on the federation protocol ( bug #1491 ), which means that using name-based virtual hosting is unreliable.

Furthermore, a number of the normal reasons for using a reverse-proxy do not apply:

  • Other servers will connect on port 8448 by default, so there is no need to listen on port 443 (for federation, at least), which avoids the need for root privileges and virtual hosting.
  • A self-signed SSL certificate is fine for federation, so there is no need to automate renewals. (The certificate generated by --generate-config is valid for 10 years.)

If you want to set up a reverse-proxy on the federation port despite these caveats, you will need to do the following:

  • In homeserver.yaml , set tls_certificate_path to the path to the SSL certificate file used by your reverse-proxy, and set no_tls to True . ( tls_private_key_path will be ignored if no_tls is True .)
  • In your reverse-proxy configuration:
    • If there are other virtual hosts on the same port, make sure that the default one uses the certificate configured above.
    • Forward /_matrix to Synapse.
  • If your reverse-proxy is not listening on port 8448, publish a SRV record to tell other servers how to find you. See Setting up Federation .

When updating the SSL certificate, just update the file pointed to by tls_certificate_path : there is no need to restart synapse. (You may like to use a symbolic link to help make this process atomic.)

The most common mistake when setting up federation is not to tell Synapse about your SSL certificate. To check it, you can visit https://matrix.org/federationtester/api/report?server_name=<your_server_name> . Unfortunately, there is no UI for this yet, but, you should see "MatchingTLSFingerprint": true . If not, check that Certificates[0].SHA256Fingerprint (the fingerprint of the certificate presented by your reverse-proxy) matches Keys.tls_fingerprints[0].sha256 (the fingerprint of the certificate Synapse is using).

Identity Servers

Identity servers have the job of mapping email addresses and other 3rd Party IDs (3PIDs) to Matrix user IDs, as well as verifying the ownership of 3PIDs before creating that mapping.

They are not where accounts or credentials are stored – these live on home servers. Identity Servers are just for mapping 3rd party IDs to matrix IDs.

This process 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. In the longer term, we hope to create a decentralised system to manage it ( matrix-doc #712 ), but in the meantime, the role of managing trusted identity in the Matrix ecosystem is farmed out to a cluster of known trusted ecosystem partners, who run ‘Matrix Identity Servers’ such as Sydent , whose role is purely to authenticate and track 3PID logins and publish end-user public keys.

You can host your own copy of Sydent, but this will prevent you reaching other users in the Matrix ecosystem via their email address, and prevent them finding you. We therefore recommend that you use one of the centralised identity servers at https://matrix.org or https://vector.im for now.

To reiterate: the Identity server will only be used if you choose to associate an email address with your account, or send an invite to another user via their email address.

URL Previews

Synapse 0.15.0 introduces a new API for previewing URLs at /_matrix/media/r0/preview_url . This is disabled by default. To turn it on you must enable the url_preview_enabled: True config parameter and explicitly specify the IP ranges that Synapse is not allowed to spider for previewing in the url_preview_ip_range_blacklist configuration parameter. This is critical from a security perspective to stop arbitrary Matrix users spidering ‘internal’ URLs on your network. At the very least we recommend that your loopback and RFC1918 IP addresses are blacklisted.

This also requires the optional lxml and netaddr python dependencies to be installed. This in turn requires the libxml2 library to be available – on Debian/Ubuntu this means apt-get install libxml2-dev , or equivalent for your OS.

パスワードのリセット

If a user has registered an email address to their account using an identity server, they can request a password-reset token via clients such as Vector.

A manual password reset can be done via direct database access as follows.

First calculate the hash of the new password:

$ source ~/.synapse/bin/activate
$ ./scripts/hash_password
Password:
Confirm password:
$2a$12$xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Then update the users table in the database:

UPDATE users SET password_hash='$2a$12$xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'
    WHERE name='@test:test.com';

Synapse Development

Before setting up a development environment for synapse, make sure you have the system dependencies (such as the python header files) installed – see Installing from source .

To check out a synapse for development, clone the git repo into a working directory of your choice:

git clone https://github.com/matrix-org/synapse.git
cd synapse

Synapse has a number of external dependencies, that are easiest to install using pip and a virtualenv:

virtualenv -p python2.7 env
source env/bin/activate
python synapse/python_dependencies.py | xargs pip install
pip install lxml mock

This will run a process of downloading and installing all the needed dependencies into a virtual env.

Once this is done, you may wish to run Synapse’s unit tests, to check that everything is installed as it should be:

PYTHONPATH="." trial tests

This should end with a ‘PASSED’ result:

Ran 143 tests in 0.601s

PASSED (successes=143)

Running the Integration Tests

Synapse is accompanied by SyTest , a Matrix homeserver integration testing suite, which uses HTTP requests to access the API as a Matrix client would. It is able to run Synapse directly from the source tree, so installation of the server is not required.

Testing with SyTest is recommended for verifying that changes related to the Client-Server API are functioning correctly. See the installation instructions for details.

Building Internal API Documentation

Before building internal API documentation install sphinx and sphinxcontrib-napoleon:

pip install sphinx
pip install sphinxcontrib-napoleon

Building internal API documentation:

python setup.py build_sphinx

Help!! Synapse eats all my RAM!

Synapse’s architecture is quite RAM hungry currently – we deliberately cache a lot of recent room data and metadata in RAM in order to speed up common requests. We’ll improve this in future, but for now the easiest way to either reduce the RAM usage (at the risk of slowing things down) is to set the almost-undocumented SYNAPSE_CACHE_FACTOR environment variable. The default is 0.5, which can be decreased to reduce RAM usage in memory constrained enviroments, or increased if performance starts to degrade.







-matrix-org

執筆者: