tomas.kracmar/ma1sd
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Rename config file, parameters, application name, package.

Browse Source
This commit is contained in:
Anatoly Sablin
2019-07-11 22:26:20 +03:00
parent c3262a9f25
commit e6fec9199d
41 changed files with 263 additions and 263 deletions
Download Patch File Download Diff File Expand all files Collapse all files

4
.gitignore vendored
View File

@@ -7,8 +7,8 @@ out/
.idea/
# Local dev config
/mxisd.yaml
/ma1sd.yaml
/application.yaml
# Local dev storage
/mxisd.db
/ma1sd.db

14
Dockerfile
View File

@@ -2,17 +2,17 @@ FROM openjdk:8-jre-alpine
RUN apk update && apk add bash && rm -rf /var/lib/apk/* /var/cache/apk/*
VOLUME /etc/mxisd
VOLUME /var/mxisd
VOLUME /etc/ma1sd
VOLUME /var/ma1sd
EXPOSE 8090
ENV JAVA_OPTS=""
ENV CONF_FILE_PATH="/etc/mxisd/mxisd.yaml"
ENV SIGN_KEY_PATH="/var/mxisd/sign.key"
ENV SQLITE_DATABASE_PATH="/var/mxisd/mxisd.db"
ENV CONF_FILE_PATH="/etc/ma1sd/ma1sd.yaml"
ENV SIGN_KEY_PATH="/var/ma1sd/sign.key"
ENV SQLITE_DATABASE_PATH="/var/ma1sd/ma1sd.db"
CMD [ "/start.sh" ]
ADD src/docker/start.sh /start.sh
ADD src/script/mxisd /app/mxisd
ADD build/libs/mxisd.jar /app/mxisd.jar
ADD src/script/ma1sd /app/ma1sd
ADD build/libs/ma1sd.jar /app/ma1sd.jar

14
README.md
View File

@@ -1,6 +1,6 @@
ma1sd - Federated Matrix Identity Server
----------------------------------------
![Travis-CI build status](https://travis-ci.org/ma1uta/mxisd.svg?branch=master)
![Travis-CI build status](https://travis-ci.org/ma1uta/ma1sd.svg?branch=master)
- [Overview](#overview)
- [Features](#features)
@@ -25,11 +25,11 @@ and several [extra features](#features) that greatly enhance user experience wit
It is the one stop shop for anything regarding Authentication, Directory and Identity management in Matrix built in a
single coherent product.
mxisd is specifically designed to connect to an existing on-premise Identity store (AD/Samba/LDAP, SQL Database,
ma1sd is specifically designed to connect to an existing on-premise Identity store (AD/Samba/LDAP, SQL Database,
Web services/app, etc.) and ease the integration of a Matrix infrastructure within an existing one.
Check [our FAQ entry](docs/faq.md#what-kind-of-setup-is-mxisd-really-designed-for) to know if mxisd is a good fit for you.
Check [our FAQ entry](docs/faq.md#what-kind-of-setup-is-ma1sd-really-designed-for) to know if ma1sd is a good fit for you.
The core principle of mxisd is to map between Matrix IDs and 3PIDs (Third-Party IDentifiers) for the Homeserver and its
The core principle of ma1sd is to map between Matrix IDs and 3PIDs (Third-Party IDentifiers) for the Homeserver and its
users. 3PIDs can be anything that uniquely and globally identify a user, like:
- Email address
- Phone number
@@ -75,7 +75,7 @@ As an enhanced Identity service:
- Users can directly find each other using whatever attribute is relevant within your Identity store
- Federate your Identity server so you can discover others and/or others can discover you
Also, check [our FAQ entry](docs/faq.md#what-kind-of-setup-is-mxisd-really-designed-for) to know if mxisd is a good fit for you.
Also, check [our FAQ entry](docs/faq.md#what-kind-of-setup-is-ma1sd-really-designed-for) to know if ma1sd is a good fit for you.
# Getting started
See the [dedicated document](docs/getting-started.md)
@@ -94,8 +94,8 @@ Don't hesitate to ask about project and feel free to create issues at https://gi
# Contribute
You can contribute as a community member by:
- Giving us feedback about your usage of ma1sd/mxisd, even if it seems unimportant or if all is working well!
- Opening issues for any weird behaviour or bug. ma1sd/mxisd should feel natural, let us know if it does not!
- Giving us feedback about your usage of ma1sd, even if it seems unimportant or if all is working well!
- Opening issues for any weird behaviour or bug. ma1sd should feel natural, let us know if it does not!
- Helping us improve the documentation: tell us what is good or not good (in an issue or in Matrix), or make a PR with
changes you feel improve the doc.
- Contribute code directly: we love contributors! All your contributions will be licensed under AGPLv3.

30
build.gradle
View File

@@ -1,5 +1,5 @@
/*
* mxisd - Matrix Identity Server Daemon
* ma1sd - Matrix Identity Server Daemon
* Copyright (C) 2017 Kamax Sarl
*
* https://www.kamax.io/
@@ -25,16 +25,16 @@ apply plugin: 'application'
apply plugin: 'com.github.johnrengelman.shadow'
apply plugin: 'idea'
def confFileName = "mxisd.example.yaml"
def confFileName = "ma1sd.example.yaml"
def distDir = "${project.buildDir}/dist"
def debBinPath = "/usr/lib/mxisd"
def debConfPath = "/etc/mxisd"
def debDataPath = "/var/lib/mxisd"
def debBinPath = "/usr/lib/ma1sd"
def debConfPath = "/etc/ma1sd"
def debDataPath = "/var/lib/ma1sd"
def debSystemdPath = "/etc/systemd/system"
def debConfFileName = confFileName
def debStartScriptFilename = "mxisd"
def debStartScriptFilename = "ma1sd"
def debBuildBasePath = "${project.buildDir}/tmp/debian"
def debBuildDebianPath = "${debBuildBasePath}/DEBIAN"
@@ -43,18 +43,18 @@ def debBuildConfPath = "${debBuildBasePath}${debConfPath}"
def debBuildDataPath = "${debBuildBasePath}${debDataPath}"
def debBuildSystemdPath = "${debBuildBasePath}${debSystemdPath}"
def dockerImageName = "kamax/mxisd"
def dockerImageTag = "${dockerImageName}:${mxisdVersion()}"
def dockerImageName = "ma1uta/ma1sd"
def dockerImageTag = "${dockerImageName}:${ma1sdVersion()}"
group = 'io.kamax'
mainClassName = 'io.kamax.mxisd.MxisdStandaloneExec'
sourceCompatibility = '1.8'
targetCompatibility = '1.8'
String mxisdVersion() {
String ma1sdVersion() {
def versionPattern = Pattern.compile("v(\\d+\\.)?(\\d+\\.)?(\\d+)(-.*)?")
String version = System.getenv('MXISD_BUILD_VERSION')
String version = System.getenv('MA1SD_BUILD_VERSION')
if (version == null || version.size() == 0) {
version = gitVersion()
}
@@ -160,7 +160,7 @@ dependencies {
jar {
manifest {
attributes(
'Implementation-Version': mxisdVersion()
'Implementation-Version': ma1sdVersion()
)
}
}
@@ -173,7 +173,7 @@ shadowJar {
task debBuild(dependsOn: shadowJar) {
doLast {
String debVersion = mxisdVersion()
String debVersion = ma1sdVersion()
println "Version for package: ${debVersion}"
mkdir distDir
mkdir debBuildBasePath
@@ -184,7 +184,7 @@ task debBuild(dependsOn: shadowJar) {
mkdir debBuildSystemdPath
copy {
from "${project.buildDir}/libs/mxisd.jar"
from "${project.buildDir}/libs/ma1sd.jar"
into debBuildBinPath
}
@@ -232,7 +232,7 @@ task debBuild(dependsOn: shadowJar) {
ant.replace(
file: "${debBuildDebianPath}/postinst",
token: '%DEB_CONF_FILE%',
value: "${debConfPath}/mxisd.yaml"
value: "${debConfPath}/ma1sd.yaml"
)
ant.chmod(
@@ -246,7 +246,7 @@ task debBuild(dependsOn: shadowJar) {
)
copy {
from "${project.file('src/systemd/mxisd.service')}"
from "${project.file('src/systemd/ma1sd.service')}"
into debBuildSystemdPath
}

4
docs/architecture.md
View File

@@ -16,7 +16,7 @@ TCP 443
+<---------------------------------<+
|
| +-------------------+
TCP 8090 +-> | mxisd |
TCP 8090 +-> | ma1sd |
| |
| - Profile's 3PIDs |
| - 3PID Invites |
@@ -25,7 +25,7 @@ TCP 443
TCP 443
| +------------------------+
| | Remote Federated |
| | mxisd servers |
| | ma1sd servers |
| | |
+--> - 3PID Invites |
+------------------------+

12
docs/build.md
View File

@@ -17,12 +17,12 @@ cd ma1sd
./gradlew build
```
Create a new configuration file by coping `mxisd.example.yaml` to `mxisd.yaml` and edit to your needs.
Create a new configuration file by coping `ma1sd.example.yaml` to `ma1sd.yaml` and edit to your needs.
For advanced configuration, see the [Configure section](configure.md).
Start the server in foreground to validate the build and configuration:
```bash
java -jar build/libs/mxisd.jar
java -jar build/libs/ma1sd.jar
```
Ensure the signing key is available:
@@ -34,9 +34,9 @@ $ curl 'http://localhost:8090/_matrix/identity/api/v1/pubkey/ed25519:0'
Test basic recursive lookup (requires Internet connection with access to TCP 443):
```bash
$ curl 'http://localhost:8090/_matrix/identity/api/v1/lookup?medium=email&address=mxisd-federation-test@kamax.io'
$ curl 'http://localhost:8090/_matrix/identity/api/v1/lookup?medium=email&address=ma1sd-federation-test@kamax.io'
{"address":"mxisd-federation-test@kamax.io","medium":"email","mxid":"@mxisd-lookup-test:kamax.io",...}
{"address":"ma1sd-federation-test@kamax.io","medium":"email","mxid":"@ma1sd-lookup-test:kamax.io",...}
```
If you enabled LDAP, you can also validate your config with a similar request after replacing the `address` value with
@@ -56,7 +56,7 @@ Requirements:
- fakeroot
- dpkg-deb
[Build mxisd](#build) then:
[Build ma1sd](#build) then:
```bash
./gradlew debBuild
```
@@ -64,7 +64,7 @@ You will find the debian package in `build/dist`.
Then follow the instruction in the [Debian package](install/debian.md) document.
## Docker image
[Build mxisd](#build) then:
[Build ma1sd](#build) then:
```bash
./gradlew dockerBuild
```

10
docs/concepts.md
View File

@@ -1,6 +1,6 @@
# Concepts
- [Matrix](#matrix)
- [mxisd](#mxisd)
- [ma1sd](#ma1sd)
## Matrix
The following concepts are part of the Matrix ecosystem and specification.
@@ -15,7 +15,7 @@ A 3PID is a globally unique canonical identifier which is made of:
- Medium, which describes what network it belongs to (Email, Phone, Twitter, Discord, etc.)
- Address, the actual value people typically use on a daily basis.
mxisd core mission is to map those identifiers to Matrix User IDs.
ma1sd core mission is to map those identifiers to Matrix User IDs.
### Homeserver
Where a user **account and data** are stored.
@@ -34,10 +34,10 @@ An Identity server:
### 3PID session
The fact to validate a 3PID (email, phone number, etc.) via the introduction of a token which was sent to the 3PID address.
## mxisd
The following concepts are specific to mxisd.
## ma1sd
The following concepts are specific to ma1sd.
### Identity store
Where your user accounts and 3PID mappings are stored.
mxisd itself **DOES NOT STORE** user accounts or 3PID mappings.
ma1sd itself **DOES NOT STORE** user accounts or 3PID mappings.

4
docs/configure.md
View File

@@ -41,7 +41,7 @@ matrix:
Create a list under the label `myOtherServers` containing two Identity servers: `https://other1.example.org` and `https://other2.example.org`.
## Server
- `server.name`: Public hostname of mxisd, if different from the Matrix domain.
- `server.name`: Public hostname of ma1sd, if different from the Matrix domain.
- `server.port`: HTTP port to listen on (unencrypted)
- `server.publicUrl`: Defaults to `https://{server.name}`
@@ -68,7 +68,7 @@ notification:
msisdn: 'raw'
```
- Emails notifications would use the `sendgrid` handler, which define its own configuration under `notification.handlers.sendgrid`
- Phone notification would use the `raw` handler, basic default built-in handler in mxisd
- Phone notification would use the `raw` handler, basic default built-in handler in ma1sd
### Handlers
- `notification.handers.<handler ID>`: Handler-specific configuration for the given handler ID. Repeatable.

46
docs/faq.md
View File

@@ -10,32 +10,32 @@ first basic setup running which relies on you reading the documentation in the r
- [Identity stores](stores/README.md) you wish to fetch data from.
- [Features](features) you are interested in that will use your Identity store(s) data.
**IMPORTANT**: Be aware that mxisd tries to fit within the current protocol and existing products and basic understanding
**IMPORTANT**: Be aware that ma1sd tries to fit within the current protocol and existing products and basic understanding
of the Matrix protocol is required for some advanced features.
If all fails, come over to [the project room](https://matrix.to/#/#ma1sd:ru-matrix.org) and we'll do our best to get you
started and answer questions you might have.
### What kind of setup is mxisd really designed for?
mxisd is primarily designed for setups that:
- [Care for their privacy](https://github.com/kamax-matrix/mxisd/wiki/mxisd-and-your-privacy)
### What kind of setup is ma1sd really designed for?
ma1sd is primarily designed for setups that:
- [Care for their privacy](https://github.com/kamax-matrix/ma1sd/wiki/ma1sd-and-your-privacy)
- Have their own [domains](https://en.wikipedia.org/wiki/Domain_name)
- Use those domains for their email addresses and all other services
- Already have an [Identity store](stores/README.md), typically [LDAP-based](stores/ldap.md).
If you meet all the conditions, then you are the prime use case we designed mxisd for.
If you meet all the conditions, then you are the prime use case we designed ma1sd for.
If you meet some of the conditions, but not all, mxisd will still be a good fit for you but you won't fully enjoy all its
If you meet some of the conditions, but not all, ma1sd will still be a good fit for you but you won't fully enjoy all its
features.
### Do I need to use mxisd if I run a Homeserver?
### Do I need to use ma1sd if I run a Homeserver?
No, but it is strongly recommended, even if you don't use any Identity store or integration.
In its default configuration, mxisd uses other federated public servers when performing queries.
In its default configuration, ma1sd uses other federated public servers when performing queries.
It can also [be configured](features/identity.md#lookups) to use the central matrix.org servers, giving you access to at
least the same information as if you were not running it.
So mxisd is like your gatekeeper and guardian angel. It does not change what you already know, just adds some nice
So ma1sd is like your gatekeeper and guardian angel. It does not change what you already know, just adds some nice
simple features on top of it.
### I'm not sure I understand what an "Identity server" is supposed to be or do...
@@ -44,18 +44,18 @@ what they want to do with that part of the ecosystem. Therefore, "Identity" is c
Given the scope of the current Identity Service API, it would be best called "Invitation service".
Because the current scope is so limited and no integration is done with the Homeserver, there was a big lack of features
for groups/corporations/organisation. This is where mxisd comes in.
for groups/corporations/organisation. This is where ma1sd comes in.
mxisd implements the Identity Service API and also a set of features which are expected by regular users, truly living
ma1sd implements the Identity Service API and also a set of features which are expected by regular users, truly living
up to its "Identity server" name.
### Can I migrate my existing account on another Matrix server with mxisd?
### Can I migrate my existing account on another Matrix server with ma1sd?
No.
Accounts cannot currently migrate/move from one server to another.
See a [brief explanation document](concepts.md) about Matrix and mxisd concepts and vocabulary.
See a [brief explanation document](concepts.md) about Matrix and ma1sd concepts and vocabulary.
### I already use the synapse LDAP3 auth provider. Why should I care about mxisd?
### I already use the synapse LDAP3 auth provider. Why should I care about ma1sd?
The [synapse LDAP3 auth provider](https://github.com/matrix-org/matrix-synapse-ldap3) is not longer maintained despite
saying so and only handles on specific flow: validate credentials at login.
@@ -65,7 +65,7 @@ It does not:
- Integrate with Directory searches
- Integrate with Profile data
mxisd is a replacement and enhancement of it, offering coherent results in all areas, which the LDAP3 auth provider
ma1sd is a replacement and enhancement of it, offering coherent results in all areas, which the LDAP3 auth provider
does not.
### Sydent is the official Identity server implementation of the Matrix team. Why not use that?
@@ -76,22 +76,22 @@ You can, but [sydent](https://github.com/matrix-org/sydent):
- forces you to duplicate all your identity data, so people can be found by 3PIDs
- forces users to enter all their emails and phone numbers manually in their profile
So really, you should go with mxisd.
So really, you should go with ma1sd.
### Will I loose access to the central Matrix.org/Vector.im Identity data if I use mxisd?
### Will I loose access to the central Matrix.org/Vector.im Identity data if I use ma1sd?
No.
In its default configuration, mxisd does not talk to the central Identity server matrix.org to avoid leaking your private
In its default configuration, ma1sd does not talk to the central Identity server matrix.org to avoid leaking your private
data and those of people you might know.
[You can configure it](features/identity.md#lookups) to talk to the central Identity servers if you wish.
### So mxisd is just a big hack! I don't want to use non-official features!
mxisd primary concerns are your privacy and to always be compatible with the Matrix ecosystem and the Identity service API.
Whenever the API will be updated and/or enhanced, mxisd will follow, remaining 100% compatible with the ecosystem.
### So ma1sd is just a big hack! I don't want to use non-official features!
ma1sd primary concerns are your privacy and to always be compatible with the Matrix ecosystem and the Identity service API.
Whenever the API will be updated and/or enhanced, ma1sd will follow, remaining 100% compatible with the ecosystem.
### Should I use mxisd if I don't host my own Homeserver?
### Should I use ma1sd if I don't host my own Homeserver?
No.
It is possible, but it is not supported and the scope of features will be extremely limited.
Please consider hosting your own Homeserver and using mxisd alongside it.
Please consider hosting your own Homeserver and using ma1sd alongside it.

30
docs/features/authentication.md
View File

@@ -3,7 +3,7 @@
- [Basic](#basic)
- [Overview](#overview)
- [synapse](#synapse)
- [mxisd](#mxisd)
- [ma1sd](#ma1sd)
- [Validate](#validate)
- [Next steps](#next-steps)
- [Profile auto-fil](#profile-auto-fill)
@@ -16,15 +16,15 @@
- [DNS Overwrite](#dns-overwrite)
## Description
Authentication is an enhanced feature of mxisd to ensure coherent and centralized identity management.
It allows to use Identity stores configured in mxisd to authenticate users on your Homeserver.
Authentication is an enhanced feature of ma1sd to ensure coherent and centralized identity management.
It allows to use Identity stores configured in ma1sd to authenticate users on your Homeserver.
Authentication is divided into two parts:
- [Basic](#basic): authenticate with a regular username.
- [Advanced](#advanced): same as basic with extra abilities like authenticate using a 3PID or do username rewrite.
## Basic
Authentication by username is possible by linking synapse and mxisd together using a specific module for synapse, also
Authentication by username is possible by linking synapse and ma1sd together using a specific module for synapse, also
known as password provider.
### Overview
@@ -33,7 +33,7 @@ An overview of the Basic Authentication process:
Identity stores
Client +------+
| +-------------------------+ +--> | LDAP |
| +---------------+ /_matrix/identity | mxisd | | +------+
| +---------------+ /_matrix/identity | ma1sd | | +------+
+-> | Reverse proxy | >------------------+ | | |
+--|------------+ | | | | +--------+
| +-----> Check ID stores >------+--> | SQL DB |
@@ -55,14 +55,14 @@ Performed on [synapse with REST auth module](https://github.com/kamax-io/matrix-
- Install the [password provider](https://github.com/kamax-io/matrix-synapse-rest-auth)
- Edit your **synapse** configuration:
- As described by the auth module documentation
- Set `endpoint` to `http://mxisdAddress:8090` - Replace `mxisdAddress` by an IP/host name that provides a direct
connection to mxisd.
- Set `endpoint` to `http://ma1sdAddress:8090` - Replace `ma1sdAddress` by an IP/host name that provides a direct
connection to ma1sd.
This **MUST NOT** be a public address, and SHOULD NOT go through a reverse proxy.
- Restart synapse
### mxisd
### ma1sd
- Configure and enable at least one [Identity store](../stores/README.md)
- Restart mxisd
- Restart ma1sd
### Validate
Login on the Homeserver using credentials present in one of your Identity stores.
@@ -93,7 +93,7 @@ This is performed by intercepting the Homeserver endpoint `/_matrix/client/r0/lo
| | Step 1 +---------------------------+ Step 2
| | | |
Client+---->| /_matrix/client/r0/login +---------------->| | Look up address +---------+
| ^ | | mxisd - Identity server +----------------->| Backend |
| ^ | | ma1sd - Identity server +----------------->| Backend |
| | | | | +---------+
| /_matrix/* +--+ +---------------------+ |
| | | +---------------+-----------+
@@ -110,7 +110,7 @@ Client+---->| /_matrix/client/r0/login +---------------->|
```
Steps of user authentication using a 3PID:
1. The intercepted login request is directly sent to mxisd instead of the Homeserver.
1. The intercepted login request is directly sent to ma1sd instead of the Homeserver.
2. Identity stores are queried for a matching user identity in order to modify the request to use the user name.
3. The Homeserver, from which the request was intercepted, is queried using the request at previous step.
Its address is resolved using the DNS Overwrite feature to reach its internal address on a non-encrypted port.
@@ -129,7 +129,7 @@ The specific configuration to put under the relevant `VirtualHost`:
```apache
ProxyPass /_matrix/client/r0/login http://localhost:8090/_matrix/client/r0/login
```
`ProxyPreserveHost` or equivalent **must** be enabled to detect to which Homeserver mxisd should talk to when building results.
`ProxyPreserveHost` or equivalent **must** be enabled to detect to which Homeserver ma1sd should talk to when building results.
Your VirtualHost should now look similar to:
```apache
@@ -188,10 +188,10 @@ server {
#### DNS Overwrite
Just like you need to configure a reverse proxy to send client requests to mxisd, you also need to configure mxisd with
Just like you need to configure a reverse proxy to send client requests to ma1sd, you also need to configure ma1sd with
the internal IP of the Homeserver so it can talk to it directly to integrate its directory search.
To do so, put the following configuration in your mxisd configuration:
To do so, put the following configuration in your ma1sd configuration:
```yaml
dns:
overwrite:
@@ -214,7 +214,7 @@ The following features are available after you have a working Advanced setup:
- Username rewrite: Allows you to rewrite the username of a regular login/pass authentication to a 3PID, that then gets resolved using the regular lookup process. Most common use case is to allow login with numerical usernames on synapse, which is not possible out of the box.
#### Username rewrite
In mxisd config:
In ma1sd config:
```yaml
auth:
rewrite:

4
docs/features/bridge-integration.md
View File

@@ -1,11 +1,11 @@
# Bridge Integration
To help natural bridge integration into the regular usage of a Matrix client, mxisd provides a way for bridge to reply
To help natural bridge integration into the regular usage of a Matrix client, ma1sd provides a way for bridge to reply
to 3PID queries if no mapping was found, allowing seamless bridging to a network.
This is performed by implementing a specific endpoint on the bridge to map a 3PID lookup to a virtual user.
**NOTE**: This document is incomplete and might be misleading. In doubt, come in our Matrix room.
You can also look at our [Email Bridge README](https://github.com/kamax-matrix/matrix-appservice-email#mxisd) for an example
You can also look at our [Email Bridge README](https://github.com/kamax-matrix/matrix-appservice-email#ma1sd) for an example
of working configuration.
## Configuration

16
docs/features/directory.md
View File

@@ -22,9 +22,9 @@ By enabling this feature, you can by default:
- Search for users which you are not in contact with yet. Super useful for corporations who want to give Matrix access
internally, so users can just find themselves **prior** to having any common room(s)
- Add extra attributes of your backend to extend the search
- Include your homeserver search results to those found by mxisd
- Include your homeserver search results to those found by ma1sd
By integrating mxisd, you get the default behaviour and a bunch of extras, ensuring your users will always find each other.
By integrating ma1sd, you get the default behaviour and a bunch of extras, ensuring your users will always find each other.
## Overview
This is performed by intercepting the Homeserver endpoint `/_matrix/client/r0/user_directory/search` like so:
@@ -33,7 +33,7 @@ This is performed by intercepting the Homeserver endpoint `/_matrix/client/r0/us
Client --> | Reverse proxy Step 2
| Step 1 +-------------------------+
| /_matrix/client/r0/user_directory/search ----------> | | Search in +---------+
| /\ | mxisd - Identity server | -----------> | Backend |
| /\ | ma1sd - Identity server | -----------> | Backend |
| /_matrix/* \----------------------------- | | all users +---------+
| | Step 4: Send back merged results +-------------------------+
+ | |
@@ -44,7 +44,7 @@ Client --> | Reverse proxy
+------------+ /_matrix/client/r0/user_directory/search
```
Steps:
1. The intercepted request is directly sent to mxisd instead of the Homeserver.
1. The intercepted request is directly sent to ma1sd instead of the Homeserver.
2. Identity stores are queried for any match on the search value sent by the client.
3. The Homeserver, from which the request was intercepted, is queried using the same request as the client.
Its address is resolved using the DNS Overwrite feature to reach its internal address on a non-encrypted port.
@@ -52,7 +52,7 @@ Steps:
which directly answered the request.
## Requirements
- Reverse proxy setup, which you should already have in place if you use mxisd
- Reverse proxy setup, which you should already have in place if you use ma1sd
- At least one compatible [Identity store](../stores/README.md) enabled
## Configuration
@@ -62,7 +62,7 @@ The specific configuration to put under the relevant `VirtualHost`:
```apache
ProxyPass /_matrix/client/r0/user_directory/ http://0.0.0.0:8090/_matrix/client/r0/user_directory/
```
`ProxyPreserveHost` or equivalent must be enabled to detect to which Homeserver mxisd should talk to when building
`ProxyPreserveHost` or equivalent must be enabled to detect to which Homeserver ma1sd should talk to when building
results.
Your `VirtualHost` should now look like this:
@@ -118,7 +118,7 @@ server {
```
### DNS Overwrite
Just like you need to configure a reverse proxy to send client requests to mxisd, you also need to configure mxisd with
Just like you need to configure a reverse proxy to send client requests to ma1sd, you also need to configure ma1sd with
the internal IP of the Homeserver so it can talk to it directly to integrate its directory search.
To do so, use the following configuration:
@@ -136,7 +136,7 @@ dns:
## Next steps
### Homeserver results
You can configure if the Homeserver should be queried at all when doing a directory search.
To disable Homeserver results, set the following in mxisd configuration file:
To disable Homeserver results, set the following in ma1sd configuration file:
```yaml
directory:
exclude:

22
docs/features/experimental/application-service.md
View File

@@ -11,7 +11,7 @@ The following capabilities are provided in this feature:
> **NOTE:** Make sure you are familiar with [configuration format and rules](../../configure.md).
Integration as an Application service is a three steps process:
1. Create the baseline mxisd configuration to allow integration.
1. Create the baseline ma1sd configuration to allow integration.
2. Integrate with the homeserver.
3. Configure the specific capabilities, if applicable.
@@ -22,11 +22,11 @@ Under the `appsvc` namespace:
| Key | Type | Required | Default | Purpose |
|-----------------------|---------|----------|---------|----------------------------------------------------------------|
| `enabled` | boolean | No | `false` | Globally enable/disable the feature |
| `user.main` | string | No | `mxisd` | Localpart for the main appservice user |
| `user.main` | string | No | `ma1sd` | Localpart for the main appservice user |
| `endpoint.toHS.url` | string | Yes | *None* | Base URL to the Homeserver |
| `endpoint.toHS.token` | string | Yes | *None* | Token to use when sending requests to the Homeserver |
| `endpoint.toAS.url` | string | Yes | *None* | Base URL to mxisd from the Homeserver |
| `endpoint.toAS.token` | string | Yes | *None* | Token for the Homeserver to use when sending requests to mxisd |
| `endpoint.toAS.url` | string | Yes | *None* | Base URL to ma1sd from the Homeserver |
| `endpoint.toAS.token` | string | Yes | *None* | Token for the Homeserver to use when sending requests to ma1sd |
#### Example
```yaml
@@ -46,7 +46,7 @@ Under the `appsvc.registration.synapse` namespace:
| Key | Type | Required | Default | Purpose |
|--------|--------|----------|--------------------|--------------------------------------------------------------------------|
| `id` | string | No | `appservice-mxisd` | The unique, user-defined ID of this application service. See spec. |
| `id` | string | No | `appservice-ma1sd` | The unique, user-defined ID of this application service. See spec. |
| `file` | string | Yes | *None* | If defined, the synapse registration file that should be created/updated |
##### Example
@@ -54,17 +54,17 @@ Under the `appsvc.registration.synapse` namespace:
appsvc:
registration:
synapse:
file: '/etc/matrix-synapse/mxisd-appservice-registration.yaml'
file: '/etc/matrix-synapse/ma1sd-appservice-registration.yaml'
```
Edit your `homeserver.yaml` and add a new entry to the appservice config file, which should look something like this:
```yaml
app_service_config_files:
- '/etc/matrix-synapse/mxisd-appservice-registration.yaml'
- '/etc/matrix-synapse/ma1sd-appservice-registration.yaml'
- ...
```
Restart synapse when done to register mxisd.
Restart synapse when done to register ma1sd.
#### Others
See your Homeserver documentation on how to integrate.
@@ -86,9 +86,9 @@ appsvc:
#### Use
The following steps assume:
- `matrix.domain` set to `example.org`
- `appsvc.user.main` set to `mxisd` or not set
- `appsvc.user.main` set to `ma1sd` or not set
1. Invite `@mxisd:example.org` to a new direct chat
1. Invite `@ma1sd:example.org` to a new direct chat
2. Type `!help` to get all available commands
### Email Notification about room invites by Matrix IDs
@@ -100,7 +100,7 @@ account was already provisioned on the Homeserver.
- At least one email entry in the identity store for each user that could be invited.
#### Configuration
In your mxisd config file:
In your ma1sd config file:
```yaml
synapseSql:
enabled: false ## Do not use this line if Synapse is used as an Identity Store

10
docs/features/federation.md
View File

@@ -5,7 +5,7 @@ Federated Identity server using the DNS domain part of the 3PID.
Emails are the best candidate for this kind of resolution which are DNS domain based already.
On the other hand, Phone numbers cannot be resolved this way.
For 3PIDs which are not compatible with the DNS system, mxisd can be configured to talk to fallback Identity servers like
For 3PIDs which are not compatible with the DNS system, ma1sd can be configured to talk to fallback Identity servers like
the central matrix.org one. See the [Identity feature](identity.md#lookups) for instructions on how to enable it.
Outbound federation is enabled by default while inbound federation is opt-in and require a specific DNS record.
@@ -13,7 +13,7 @@ Outbound federation is enabled by default while inbound federation is opt-in and
## Overview
```
+-------------------+ +-------------> +----------+
| mxisd | | | Backends |
| ma1sd | | | Backends |
| | | +------> +----------+
| | | |
| Invites / Lookups | | |
@@ -23,7 +23,7 @@ Outbound federation is enabled by default while inbound federation is opt-in and
| | |
| +--------+ | | +-------------------+
Homeserver --->| Local |>------------------+------> | Remote Federated |
and clients | +--------+ | | mxisd servers |
and clients | +--------+ | | ma1sd servers |
+-------------------+ +-------------------+
```
@@ -34,11 +34,11 @@ If you would like to be reachable for lookups over federation, create the follow
_matrix-identity._tcp.example.com. 3600 IN SRV 10 0 443 matrix.example.com.
```
The port must be HTTPS capable which is what you get in a regular setup with a reverse proxy from 443 to TCP 8090 of mxisd.
The port must be HTTPS capable which is what you get in a regular setup with a reverse proxy from 443 to TCP 8090 of ma1sd.
## Outbound
If you would like to disable outbound federation and isolate your identity server from the rest of the Matrix network,
use the following mxisd configuration options:
use the following ma1sd configuration options:
```yaml
lookup:
recursive:

12
docs/features/identity.md
View File

@@ -17,7 +17,7 @@ forward:
- 'matrix-org'
```
**NOTE:** You should carefully consider enabling this option, which is discouraged.
For more info, see the [relevant issue](https://github.com/kamax-matrix/mxisd/issues/76).
For more info, see the [relevant issue](https://github.com/kamax-matrix/ma1sd/issues/76).
## Invitations
### Expiration
@@ -25,10 +25,10 @@ For more info, see the [relevant issue](https://github.com/kamax-matrix/mxisd/is
Matrix does not provide a mean to remove/cancel pending 3PID invitations with the APIs. The current reference
implementations also do not provide any mean to do so. This leads to 3PID invites forever stuck in rooms.
To provide this functionality, mxisd uses a workaround: resolve the invite to a dedicated User ID, which can be
controlled by mxisd or a bot/service that will then reject the invite.
To provide this functionality, ma1sd uses a workaround: resolve the invite to a dedicated User ID, which can be
controlled by ma1sd or a bot/service that will then reject the invite.
If this dedicated User ID is to be controlled by mxisd, the [Application Service](experimental/application-service.md)
If this dedicated User ID is to be controlled by ma1sd, the [Application Service](experimental/application-service.md)
feature must be configured and integrated with your Homeserver, as well as the *Auto-reject 3PID invite capability*.
#### Configuration
@@ -63,7 +63,7 @@ It's a middle ground between a closed server, where every user must be created o
and an open server, where anyone can register.
#### Integration
Because Identity Servers do not control 3PID invites as per Matrix spec, mxisd needs to intercept a set of Homeserver
Because Identity Servers do not control 3PID invites as per Matrix spec, ma1sd needs to intercept a set of Homeserver
endpoints to apply the policies.
##### Reverse Proxy
@@ -101,7 +101,7 @@ Resolution of 3PID invitations can be customized using the following configurati
`invite.resolution.timer`
- Default value: `1`
- Description: How often, in minutes, mxisd should try to resolve pending invites.
- Description: How often, in minutes, ma1sd should try to resolve pending invites.
## 3PIDs Management
See the [3PID session documents](../threepids/session)

4
docs/features/registration.md
View File

@@ -13,7 +13,7 @@
## Overview
**NOTE**: This feature is beta: it is considered stable enough for production but is incomplete and may contain bugs.
Registration is an enhanced feature of mxisd to control registrations involving 3PIDs on a Homeserver based on policies:
Registration is an enhanced feature of ma1sd to control registrations involving 3PIDs on a Homeserver based on policies:
- Match pending 3PID invites on the server
- Match 3PID pattern, like a specific set of domains for emails
- In further releases, use 3PIDs found in Identity stores
@@ -28,7 +28,7 @@ As such, it relies on the homeserver to require 3PIDs with the registration flow
This feature is not part of the Matrix Identity Server spec.
## Integration
mxisd needs to be integrated at several levels for this feature to work:
ma1sd needs to be integrated at several levels for this feature to work:
- Reverse proxy: intercept the 3PID register endpoints and act on them
- Homeserver: require 3PID to be part of the registration data

38
docs/getting-started.md
View File

@@ -12,8 +12,8 @@ This will be a good ground work for further integration with features and your e
---
If you would like a more fully integrated setup out of the box, the [matrix-docker-ansible-deploy](https://github.com/spantaleev/matrix-docker-ansible-deploy)
project provides a turn-key full-stack solution, including LDAP and the various mxisd features enabled and ready.
We work closely with the project owner so the latest mxisd version is always supported.
project provides a turn-key full-stack solution, including LDAP and the various ma1sd features enabled and ready.
We work closely with the project owner so the latest ma1sd version is always supported.
If you choose to use it, this Getting Started guide is not applicable - See the project documentation. You may then
directly go to the [Next steps](#next-steps).
@@ -21,21 +21,21 @@ directly go to the [Next steps](#next-steps).
## Preparation
You will need:
- Working Homeserver, ideally with working federation
- Reverse proxy with regular TLS/SSL certificate (Let's encrypt) for your mxisd domain
- Reverse proxy with regular TLS/SSL certificate (Let's encrypt) for your ma1sd domain
If you use synapse:
- It requires an HTTPS connection when talking to an Identity service, **a reverse proxy is required** as mxisd does
- It requires an HTTPS connection when talking to an Identity service, **a reverse proxy is required** as ma1sd does
not support HTTPS listener at this time.
- HTTPS is hardcoded when talking to the Identity server. If your Identity server URL in your client is `https://matrix.example.org/`,
then you need to ensure `https://matrix.example.org/_matrix/identity/api/v1/...` will reach mxisd if called from the synapse host.
then you need to ensure `https://matrix.example.org/_matrix/identity/api/v1/...` will reach ma1sd if called from the synapse host.
In doubt, test with `curl` or similar.
For maximum integration, it is best to have your Homeserver and mxisd reachable via the same public hostname.
For maximum integration, it is best to have your Homeserver and ma1sd reachable via the same public hostname.
Be aware of a [NAT/Reverse proxy gotcha](https://github.com/kamax-matrix/mxisd/wiki/Gotchas#nating) if you use the same
Be aware of a [NAT/Reverse proxy gotcha](https://github.com/kamax-matrix/ma1sd/wiki/Gotchas#nating) if you use the same
host.
The following Quick Start guide assumes you will host the Homeserver and mxisd under the same hostname.
The following Quick Start guide assumes you will host the Homeserver and ma1sd under the same hostname.
If you would like a high-level view of the infrastructure and how each feature is integrated, see the
[dedicated document](architecture.md)
@@ -54,7 +54,7 @@ See the [Latest release](https://github.com/ma1uta/ma1sd/releases/latest) for li
> **NOTE**: Details about configuration syntax and format are described [here](configure.md)
If you haven't created a configuration file yet, copy `mxisd.example.yaml` to where the configuration file is stored given
If you haven't created a configuration file yet, copy `ma1sd.example.yaml` to where the configuration file is stored given
your installation method and edit to your needs.
The following items must be at least configured:
@@ -62,15 +62,15 @@ The following items must be at least configured:
- `key.path` will store the signing keys, which must be kept safe! If the file does not exist, keys will be generated for you.
- `storage.provider.sqlite.database` is the location of the SQLite Database file which will hold state (invites, etc.)
If your HS/mxisd hostname is not the same as your Matrix domain, configure `server.name`.
If your HS/ma1sd hostname is not the same as your Matrix domain, configure `server.name`.
Complete configuration guide is available [here](configure.md).
## Integrate
For an overview of a typical mxisd infrastructure, see the [dedicated document](architecture.md)
For an overview of a typical ma1sd infrastructure, see the [dedicated document](architecture.md)
### Reverse proxy
#### Apache2
In the `VirtualHost` section handling the domain with SSL, add the following and replace `0.0.0.0` by the internal
hostname/IP pointing to mxisd.
hostname/IP pointing to ma1sd.
**This line MUST be present before the one for the homeserver!**
```apache
ProxyPass /_matrix/identity http://0.0.0.0:8090/_matrix/identity
@@ -91,7 +91,7 @@ Typical configuration would look like:
#### nginx
In the `server` section handling the domain with SSL, add the following and replace `0.0.0.0` with the internal
hostname/IP pointing to mxisd.
hostname/IP pointing to ma1sd.
**This line MUST be present before the one for the homeserver!**
```nginx
location /_matrix/identity {
@@ -122,7 +122,7 @@ server {
```
### Synapse
Add your mxisd domain into the `homeserver.yaml` at `trusted_third_party_id_servers` and restart synapse.
Add your ma1sd domain into the `homeserver.yaml` at `trusted_third_party_id_servers` and restart synapse.
In a typical configuration, you would end up with something similar to:
```yaml
trusted_third_party_id_servers:
@@ -138,20 +138,20 @@ your installation validated.
1. Log in using your Matrix client and set `https://matrix.example.org` as your Identity server URL, replacing `matrix.example.org`
by the relevant hostname which you configured in your reverse proxy.
2. Create a new empty room. All further actions will take place in this room.
3. Invite `mxisd-federation-test@kamax.io`
4. The 3PID invite should be turned into a Matrix invite to `@mxisd-lookup-test:kamax.io`.
3. Invite `ma1sd-federation-test@kamax.io`
4. The 3PID invite should be turned into a Matrix invite to `@ma1sd-lookup-test:kamax.io`.
5. The invited test user will join the room, send a congratulation message and leave.
**NOTE:** You might not see a suggestion for the e-mail address, which is normal. Still proceed with the invite.
If it worked, it means you are up and running and can enjoy mxisd in its basic mode! Congratulations!
If it worked, it means you are up and running and can enjoy ma1sd in its basic mode! Congratulations!
If it did not work, read the basic [troubleshooting guide](troubleshooting.md), [get in touch](../README.md#support) and
we'll do our best to get you started.
## Next steps
Once your mxisd server is up and running, there are several ways you can enhance and integrate further with your
Once your ma1sd server is up and running, there are several ways you can enhance and integrate further with your
infrastructure:
- [Enable extra features](features/)
- [Use your own Identity stores](stores/README.md)
- [Hardening your mxisd installation](install/security.md)
- [Hardening your ma1sd installation](install/security.md)
- [Learn about day-to-day operations](operations.md)

28
docs/install/debian.md
View File

@@ -6,37 +6,37 @@
1. Download the [latest release](https://github.com/ma1uta/ma1sd/releases/latest)
2. Run:
```bash
dpkg -i /path/to/downloaded/mxisd.deb
dpkg -i /path/to/downloaded/ma1sd.deb
```
## Files
| Location | Purpose |
|-------------------------------------|----------------------------------------------|
| `/etc/mxisd` | Configuration directory |
| `/etc/mxisd/mxisd.yaml` | Main configuration file |
| `/etc/systemd/system/mxisd.service` | Systemd configuration file for mxisd service |
| `/usr/lib/mxisd` | Binaries |
| `/var/lib/mxisd` | Data |
| `/var/lib/mxisd/signing.key` | Default location for mxisd signing keys |
| `/etc/ma1sd` | Configuration directory |
| `/etc/ma1sd/ma1sd.yaml` | Main configuration file |
| `/etc/systemd/system/ma1sd.service` | Systemd configuration file for ma1sd service |
| `/usr/lib/ma1sd` | Binaries |
| `/var/lib/ma1sd` | Data |
| `/var/lib/ma1sd/signing.key` | Default location for ma1sd signing keys |
## Control
Start mxisd using:
Start ma1sd using:
```bash
sudo systemctl start mxisd
sudo systemctl start ma1sd
```
Stop mxisd using:
Stop ma1sd using:
```bash
sudo systemctl stop mxisd
sudo systemctl stop ma1sd
```
## Troubleshoot
All logs are sent to `STDOUT` which are saved in `/var/log/syslog` by default.
You can:
- grep & tail using `mxisd`:
- grep & tail using `ma1sd`:
```
tail -n 99 -f /var/log/syslog | grep mxisd
tail -n 99 -f /var/log/syslog | grep ma1sd
```
- use Systemd's journal:
```
journalctl -f -n 99 -u mxisd
journalctl -f -n 99 -u ma1sd
```

6
docs/install/docker.md
View File

@@ -8,12 +8,12 @@
## Fetch
Pull the latest stable image:
```bash
docker pull kamax/mxisd
docker pull kamax/ma1sd
```
## Configure
On first run, simply using `MATRIX_DOMAIN` as an environment variable will create a default config for you.
You can also provide a configuration file named `mxisd.yaml` in the volume mapped to `/etc/mxisd` before starting your
You can also provide a configuration file named `ma1sd.yaml` in the volume mapped to `/etc/ma1sd` before starting your
container.
## Run
@@ -22,7 +22,7 @@ Use the following command after adapting to your needs:
- The volumes host paths
```bash
docker run --rm -e MATRIX_DOMAIN=example.org -v /data/mxisd/etc:/etc/mxisd -v /data/mxisd/var:/var/mxisd -p 8090:8090 -t kamax/mxisd
docker run --rm -e MATRIX_DOMAIN=example.org -v /data/ma1sd/etc:/etc/ma1sd -v /data/ma1sd/var:/var/ma1sd -p 8090:8090 -t kamax/ma1sd
```
For more info, including the list of possible tags, see [the public repository](https://hub.docker.com/r/kamax/mxisd/)

16
docs/install/security.md
View File

@@ -5,23 +5,23 @@ avoid leak of credentials/key pairs
## Configuration
Your config file should have the following ownership:
- Dedicated user for mxisd, used to run the software
- Dedicated group for mxisd, used by other applications to access and read configuration files
- Dedicated user for ma1sd, used to run the software
- Dedicated group for ma1sd, used by other applications to access and read configuration files
Your config file should have the following access:
- Read and write for the mxisd user
- Read for the mxisd group
- Read and write for the ma1sd user
- Read for the ma1sd group
- Nothing for others
This translates into `640` and be applied with `chmod 640 /path/to/config/file.yaml`.
## Data
The only sensible place is the key store where mxisd's signing keys are stored. You should therefore limit access to only
the mxisd user, and deny access to anything else.
The only sensible place is the key store where ma1sd's signing keys are stored. You should therefore limit access to only
the ma1sd user, and deny access to anything else.
Your key store should have the following access:
- Read and write for the mxisd user
- Nothing for the mxisd group
- Read and write for the ma1sd user
- Nothing for the ma1sd group
- Nothing for others
The identity store can either be a file or a directory, depending on your version. v1.4 and higher are using a directory,

30
docs/install/source.md
View File

@@ -5,40 +5,40 @@ Follow the [build instructions](../build.md) then:
### Prepare files and directories:
```bash
# Create a dedicated user
useradd -r mxisd
useradd -r ma1sd
# Create config directory
mkdir -p /etc/mxisd
mkdir -p /etc/ma1sd
# Create data directory and set ownership
mkdir -p /var/lib/mxisd
chown -R mxisd /var/lib/mxisd
mkdir -p /var/lib/ma1sd
chown -R ma1sd /var/lib/ma1sd
# Create bin directory, copy the jar and launch scriot to bin directory
mkdir /usr/lib/mxisd
cp ./build/libs/mxisd.jar /usr/lib/mxisd/
cp ./src/script/mxisd /usr/lib/mxisd
chown -R mxisd /usr/lib/mxisd
chmod a+x /usr/lib/mxisd/mxisd
mkdir /usr/lib/ma1sd
cp ./build/libs/ma1sd.jar /usr/lib/ma1sd/
cp ./src/script/ma1sd /usr/lib/ma1sd
chown -R ma1sd /usr/lib/ma1sd
chmod a+x /usr/lib/ma1sd/ma1sd
# Create symlink for easy exec
ln -s /usr/lib/mxisd/mxisd /usr/bin/mxisd
ln -s /usr/lib/ma1sd/ma1sd /usr/bin/ma1sd
```
### Prepare config file
Copy the configuration file you've created following the build instructions to `/etc/mxisd/mxisd.yaml`
Copy the configuration file you've created following the build instructions to `/etc/ma1sd/ma1sd.yaml`
### Prepare Systemd
1. Copy `src/systemd/mxisd.service` to `/etc/systemd/system/` and edit if needed
1. Copy `src/systemd/ma1sd.service` to `/etc/systemd/system/` and edit if needed
2. Enable service for auto-startup
```bash
systemctl enable mxisd
systemctl enable ma1sd
```
### Run
```bash
systemctl start mxisd
systemctl start ma1sd
```
## Debug
mxisd logs to stdout, which is normally sent to `/var/log/syslog` or `/var/log/messages`.
ma1sd logs to stdout, which is normally sent to `/var/log/syslog` or `/var/log/messages`.

14
docs/operations.md
View File

@@ -4,18 +4,18 @@
- [Backuo](#backup)
## Overview
This document gives various information for the day-to-day management and operations of mxisd.
This document gives various information for the day-to-day management and operations of ma1sd.
## Maintenance
mxisd does not require any maintenance task to run at optimal performance.
ma1sd does not require any maintenance task to run at optimal performance.
## Backup
### Run
mxisd requires all file in its configuration and data directory to be backed up.
ma1sd requires all file in its configuration and data directory to be backed up.
They are usually located at:
- `/etc/mxisd`
- `/var/lib/mxisd`
- `/etc/ma1sd`
- `/var/lib/ma1sd`
### Restore
Reinstall mxisd, restore the two folders above in the appropriate location (depending on your install method) and you
will be good to go. Simply start mxisd to restore functionality.
Reinstall ma1sd, restore the two folders above in the appropriate location (depending on your install method) and you
will be good to go. Simply start ma1sd to restore functionality.

6
docs/stores/exec.md
View File

@@ -42,7 +42,7 @@
| [Profile](../features/profile.md) | Yes |
This Identity Store lets you run arbitrary commands to handle the various requests in each support feature.
It is the most versatile Identity store of mxisd, allowing you to connect any kind of logic with any executable/script.
It is the most versatile Identity store of ma1sd, allowing you to connect any kind of logic with any executable/script.
## Overview
Each request can be mapping to a fully customizable command configuration.
@@ -190,7 +190,7 @@ The following types are available:
exec:
auth:
enabled: true
command: '/opt/mxisd-exec/auth.sh'
command: '/opt/ma1sd-exec/auth.sh'
args: ['{localpart}']
input:
type: 'plain'
@@ -198,7 +198,7 @@ exec:
env:
DOMAIN: '{domain}'
```
With Authentication enabled, run `/opt/mxisd-exec/auth.sh` when validating credentials, providing:
With Authentication enabled, run `/opt/ma1sd-exec/auth.sh` when validating credentials, providing:
- A single command-line argument to provide the `localpart` as username
- A plain text string with the password token for standard input, which will be replaced by the password to check
- A single environment variable `DOMAIN` containing Matrix ID domain, if given

8
docs/stores/ldap.md
View File

@@ -17,19 +17,19 @@ For NetIQ, replace all the `ldap` prefix in the configuration by `netiq`.
## Getting started
### Base
To use your LDAP backend, add the bare minimum configuration in mxisd config file:
To use your LDAP backend, add the bare minimum configuration in ma1sd config file:
```yaml
ldap:
enabled: true
connection:
host: 'ldapHostnameOrIp'
port: 389
bindDn: 'CN=My Mxisd User,OU=Users,DC=example,DC=org'
bindDn: 'CN=My User,OU=Users,DC=example,DC=org'
bindPassword: 'TheUserPassword'
baseDNs:
- 'OU=Users,DC=example,DC=org'
```
These are standard LDAP connection configuration. mxisd will try to connect on port default port 389 without encryption.
These are standard LDAP connection configuration. ma1sd will try to connect on port default port 389 without encryption.
If you would like to use several Base DNs, simply add more entries under `baseDNs`.
@@ -89,7 +89,7 @@ ldap:
#### 3PIDs
You can also change the attribute lists for 3PID, like email or phone numbers.
The following example would overwrite the [default list of attributes](../../src/main/java/io/kamax/mxisd/config/ldap/LdapConfig.java#L64)
The following example would overwrite the [default list of attributes](../../src/main/java/io/kamax/ma1sd/config/ldap/LdapConfig.java#L64)
for emails and phone number:
```yaml
ldap:

14
docs/stores/rest.md
View File

@@ -20,13 +20,13 @@ To integrate this backend with your webapp, you will need to implement the REST
|--------------------------------------|------------------------------------------------|------------------------------------------------------|
| `rest.enabled` | `false` | Globally enable/disable the REST backend |
| `rest.host` | *None* | Default base URL to use for the different endpoints. |
| `rest.endpoints.auth` | `/_mxisd/backend/api/v1/auth/login` | Validate credentials and get user profile |
| `rest.endpoints.directory` | `/_mxisd/backend/api/v1/directory/user/search` | Search for users by arbitrary input |
| `rest.endpoints.identity.single` | `/_mxisd/backend/api/v1/identity/single` | Endpoint to query a single 3PID |
| `rest.endpoints.identity.bulk` | `/_mxisd/backend/api/v1/identity/bulk` | Endpoint to query a list of 3PID |
| `rest.endpoints.profile.displayName` | `/_mxisd/backend/api/v1/profile/displayName` | Query the display name for a Matrix ID
| `rest.endpoints.profile.threepids` | `/_mxisd/backend/api/v1/profile/threepids` | Query the 3PIDs for a Matrix ID
| `rest.endpoints.profile.roles` | `/_mxisd/backend/api/v1/profile/roles` | Query the Roles for a Matrix ID
| `rest.endpoints.auth` | `/_ma1sd/backend/api/v1/auth/login` | Validate credentials and get user profile |
| `rest.endpoints.directory` | `/_ma1sd/backend/api/v1/directory/user/search` | Search for users by arbitrary input |
| `rest.endpoints.identity.single` | `/_ma1sd/backend/api/v1/identity/single` | Endpoint to query a single 3PID |
| `rest.endpoints.identity.bulk` | `/_ma1sd/backend/api/v1/identity/bulk` | Endpoint to query a list of 3PID |
| `rest.endpoints.profile.displayName` | `/_ma1sd/backend/api/v1/profile/displayName` | Query the display name for a Matrix ID
| `rest.endpoints.profile.threepids` | `/_ma1sd/backend/api/v1/profile/threepids` | Query the 3PIDs for a Matrix ID
| `rest.endpoints.profile.roles` | `/_ma1sd/backend/api/v1/profile/roles` | Query the Roles for a Matrix ID
Endpoint values can handle two formats:
- URL Path starting with `/` that gets happened to the `rest.host`

6
docs/stores/sql.md
View File

@@ -80,7 +80,7 @@ sql:
type: <string>
value: <string>
```
For each query, `type` can be used to tell mxisd how to process the ID column:
For each query, `type` can be used to tell ma1sd how to process the ID column:
- `localpart` will append the `matrix.domain` to it
- `mxid` will use the ID as-is. If it is not a valid Matrix ID, the search will fail.
@@ -114,7 +114,7 @@ sql:
medium:
mediumTypeExample: <dedicated query>
```
`type` is used to tell mxisd how to process the returned `uid` column containing the User ID:
`type` is used to tell ma1sd how to process the returned `uid` column containing the User ID:
- `localpart` will build a full Matrix ID using the `matrix.domain` value.
- `mxid` will use the ID as-is. If it is not a valid Matrix ID, lookup(s) will fail.
@@ -135,7 +135,7 @@ sql:
```
For the `role` query, `type` can be used to tell mxisd how to inject the User ID in the query:
For the `role` query, `type` can be used to tell ma1sd how to inject the User ID in the query:
- `localpart` will extract and set only the localpart.
- `mxid` will use the ID as-is.

4
docs/stores/wordpress.md
View File

@@ -29,9 +29,9 @@ define('JWT_AUTH_SECRET_KEY', 'your-top-secret-key');
#### Rewrite of `index.php`
Wordpress is normally configured with rewrite of `index.php` so it does not appear in URLs.
If this is not the case for your installation, the mxisd URL will need to be appended with `/index.php`
If this is not the case for your installation, the ma1sd URL will need to be appended with `/index.php`
### mxisd
### ma1sd
Enable in the configuration:
```yaml
wordpress:

4
docs/threepids/notification/template-generator.md
View File

@@ -9,7 +9,7 @@ provide your own custom templates.
Templates for the following events/actions are available:
- [3PID invite](../../features/identity.md)
- [3PID session: validation](../session/session.md)
- [3PID session: fraudulent unbind](https://github.com/kamax-matrix/mxisd/wiki/mxisd-and-your-privacy#improving-your-privacy-one-commit-at-the-time)
- [3PID session: fraudulent unbind](https://github.com/kamax-matrix/ma1sd/wiki/ma1sd-and-your-privacy#improving-your-privacy-one-commit-at-the-time)
- [Matrix ID invite](../../features/experimental/application-service.md#email-notification-about-room-invites-by-matrix-ids)
## Placeholders
@@ -57,7 +57,7 @@ Specific placeholders:
| `NEXT_URL` | URL to redirect to after the sessions has been validated. |
## Templates
mxisd comes with a set of builtin templates to easily get started. Those templates can be found
ma1sd comes with a set of builtin templates to easily get started. Those templates can be found
[in the repository](https://github.com/ma1uta/ma1sd/tree/master/src/main/resources/threepids). If you want to use
customized templates, we recommend using the builtin templates as a starting point.

6
docs/threepids/session/session-views.md
View File

@@ -27,12 +27,12 @@ Two configuration keys are available that accept paths to HTML templates:
- `failure`
### Serving static assets
mxisd will not serve any static asset (images, JS, CSS, etc.). If such are needed, you will need to serve them using the
reverse proxy sitting in front of mxisd using a path outside of the `/_matrix/identity/` namespace. We advise using
ma1sd will not serve any static asset (images, JS, CSS, etc.). If such are needed, you will need to serve them using the
reverse proxy sitting in front of ma1sd using a path outside of the `/_matrix/identity/` namespace. We advise using
the base path `/static/` for such use cases, allowing to remain under the same hostname/origin.
You can also serve such assets using absolute URL, possibly under other domains, but be aware of Cross-Origin restrictions
in browsers which are out of scope of mxisd.
in browsers which are out of scope of ma1sd.
## Placeholders
### Success

10
docs/threepids/session/session.md
View File

@@ -30,11 +30,11 @@ by a 3PID, allowing it to be resolved to a Matrix ID.
## Restrictions
### Bindings
mxisd does not store bindings directly. While a user can see its email, phone number or any other 3PID in its
ma1sd does not store bindings directly. While a user can see its email, phone number or any other 3PID in its
settings/profile, it does **NOT** mean it is published/saved anywhere or can be used to invite/search the user.
Identity stores are the ones holding such data, irrelevant if a user added a 3PID to their profile. When queried for
bindings, mxisd will query Identity stores which are responsible to store this kind of information.
bindings, ma1sd will query Identity stores which are responsible to store this kind of information.
Therefore, by default, any 3PID added to a user profile which is NOT within a configured and enabled Identity backend
will simply not be usable for search or invites, **even on the same Homeserver!**
@@ -60,7 +60,7 @@ Example: a user from Homeserver `example.org` adds an email `john@gmail.com`.
If a federated lookup was performed, Identity servers would try to find the 3PID bind at the `gmail.com` server, and
not `example.org`.
As mxisd is built for self-hosted use cases, mainly for orgs/corps, this is usually not a problem for emails.
As ma1sd is built for self-hosted use cases, mainly for orgs/corps, this is usually not a problem for emails.
Sadly, there is currently no mechanism to make this work for phone numbers.
## Notifications
@@ -68,7 +68,7 @@ Sadly, there is currently no mechanism to make this work for phone numbers.
Identity server that received the request. This is usually done by means of a URL to visit for email or a short number
received by SMS for phone numbers.
mxisd use two components for this:
ma1sd use two components for this:
- Generator which produces the message to be sent with the necessary information the user needs to validate their session.
- Connector which actually send the notification (e.g. SMTP for email).
@@ -134,7 +134,7 @@ on how to configure/customize/brand those pages to your liking.
This configuration would disable 3PID sessions altogether, preventing users from validating emails and/or phone numbers
and any subsequent actions that requires them, like adding them to their profiles.
This would be used if mxisd is also performing authentication for the Homeserver, typically with synapse and the
This would be used if ma1sd is also performing authentication for the Homeserver, typically with synapse and the
[REST password provider](https://github.com/ma1uta/matrix-synapse-rest-password-provider), where 3PID mappings would be
auto-populated.

8
docs/troubleshooting.md
View File

@@ -7,11 +7,11 @@
- [Submit an issue](#submit-an-issue)
## Purpose
This document describes basic troubleshooting steps for mxisd.
This document describes basic troubleshooting steps for ma1sd.
## Logs
### Locations
mxisd logs to `STDOUT` (Standard Output) and `STDERR` (Standard Error) only, which gets redirected
ma1sd logs to `STDOUT` (Standard Output) and `STDERR` (Standard Error) only, which gets redirected
to log file(s) depending on your system.
If you use the [Debian package](install/debian.md), this goes to `syslog`.
@@ -22,13 +22,13 @@ For any other platform, please refer to your package maintainer.
### Increase verbosity
To increase log verbosity and better track issues, the following means are available:
- Add the `-v` command line parameter
- Use the environment variable and value `MXISD_LOG_LEVEL=debug`
- Use the environment variable and value `MA1SD_LOG_LEVEL=debug`
### Reading them
Before reporting an issue, it is important to produce clean and complete logs so they can be understood.
It is usually useless to try to troubleshoot an issue based on a single log line. Any action or API request
in mxisd would trigger more than one log lines, and those would be considered necessary context to
in ma1sd would trigger more than one log lines, and those would be considered necessary context to
understand what happened.
You may also find things called *stacktraces*. Those are important to pin-point bugs and the likes and should

20
mxisd.example.yaml → ma1sd.example.yaml
View File

@@ -2,7 +2,7 @@
#
# For a complete list of options, see https://github.com/ma1uta/ma1sd/docs/README.md
#
# Please follow the Getting Started guide if this is your first time using/configuring mxisd
# Please follow the Getting Started guide if this is your first time using/configuring ma1sd
#
# -- https://github.com/ma1uta/ma1sd/blob/master/docs/getting-started.md#getting-started
#
@@ -30,28 +30,28 @@ matrix:
# /!\ THIS MUST **NOT** BE YOUR HOMESERVER KEYS FILE /!\
# If this path does not exist, it will be auto-generated.
#
# During testing, /var/tmp/mxisd/keys is a possible value
# During testing, /var/tmp/ma1sd/keys is a possible value
# For production, recommended location shall be one of the following:
# - /var/lib/mxisd/keys
# - /var/opt/mxisd/keys
# - /var/local/mxisd/keys
# - /var/lib/ma1sd/keys
# - /var/opt/ma1sd/keys
# - /var/local/ma1sd/keys
#
key:
path: ''
# Path to the SQLite DB file for mxisd internal storage
# Path to the SQLite DB file for ma1sd internal storage
# /!\ THIS MUST **NOT** BE YOUR HOMESERVER DATABASE /!\
#
# Examples:
# - /var/opt/mxisd/store.db
# - /var/local/mxisd/store.db
# - /var/lib/mxisd/store.db
# - /var/opt/ma1sd/store.db
# - /var/local/ma1sd/store.db
# - /var/lib/ma1sd/store.db
#
storage:
provider:
sqlite:
database: '/path/to/mxisd.db'
database: '/path/to/ma1sd.db'
###################

2
src/debian/control
View File

@@ -1,4 +1,4 @@
Package: mxisd
Package: ma1sd
Maintainer: ma1uta <sablintolya@gmail.com>
Homepage: https://github.com/ma1uta/ma1sd
Description: Federated Matrix Identity Server

14
src/debian/postinst
View File

@@ -1,19 +1,19 @@
#!/bin/bash -e
# Add service account
useradd -r mxisd || true
useradd -r ma1sd || true
# Set permissions for data directory
chown -R mxisd:mxisd %DEB_DATA_DIR%
chown -R ma1sd:ma1sd %DEB_DATA_DIR%
# Create symlink to mxisd run script
ln -sfT /usr/lib/mxisd/mxisd /usr/bin/mxisd
# Create symlink to ma1sd run script
ln -sfT /usr/lib/ma1sd/ma1sd /usr/bin/ma1sd
# Enable systemd service
systemctl enable mxisd.service
systemctl enable ma1sd.service
# If we already have a config file setup, we attempt to run mxisd automatically
# If we already have a config file setup, we attempt to run ma1sd automatically
# Specifically targeted at upgrades where the service needs to be restarted
if [ -f "%DEB_CONF_FILE%" ]; then
systemctl restart mxisd.service
systemctl restart ma1sd.service
fi

6
src/debian/prerm
View File

@@ -1,10 +1,10 @@
#!/bin/bash
# Stop running instance if needed
systemctl stop mxisd.service
systemctl stop ma1sd.service
# Disable service if exists
systemctl disable mxisd.service
systemctl disable ma1sd.service
# remove symlink
rm /usr/bin/mxisd
rm /usr/bin/ma1sd

4
src/docker/start.sh
View File

@@ -27,8 +27,8 @@ if [[ -n "$CONF_FILE_PATH" ]] && [ ! -f "$CONF_FILE_PATH" ]; then
echo >> "$CONF_FILE_PATH"
fi
echo "Starting mxisd..."
echo "Starting ma1sd..."
echo
fi
exec java -jar /app/mxisd.jar -c /etc/mxisd/mxisd.yaml
exec java -jar /app/ma1sd.jar -c /etc/ma1sd/ma1sd.yaml

2
src/main/java/io/kamax/mxisd/MxisdStandaloneExec.java
View File

@@ -36,7 +36,7 @@ public class MxisdStandaloneExec {
private static final Logger log = LoggerFactory.getLogger("App");
public static void main(String[] args) {
String logLevel = System.getenv("MXISD_LOG_LEVEL");
String logLevel = System.getenv("MA1SD_LOG_LEVEL");
if (StringUtils.isNotBlank(logLevel)) {
System.setProperty("org.slf4j.simpleLogger.log.io.kamax.mxisd", logLevel);
}

14
src/main/java/io/kamax/mxisd/config/rest/RestBackendConfig.java
View File

@@ -33,8 +33,8 @@ public class RestBackendConfig {
public static class IdentityEndpoints {
private String single = "/_mxisd/backend/api/v1/identity/single";
private String bulk = "/_mxisd/backend/api/v1/identity/bulk";
private String single = "/_ma1sd/backend/api/v1/identity/single";
private String bulk = "/_ma1sd/backend/api/v1/identity/bulk";
public String getSingle() {
return single;
@@ -56,9 +56,9 @@ public class RestBackendConfig {
public static class ProfileEndpoints {
private String displayName = "/_mxisd/backend/api/v1/profile/displayName";
private String threepids = "/_mxisd/backend/api/v1/profile/threepids";
private String roles = "/_mxisd/backend/api/v1/profile/roles";
private String displayName = "/_ma1sd/backend/api/v1/profile/displayName";
private String threepids = "/_ma1sd/backend/api/v1/profile/threepids";
private String roles = "/_ma1sd/backend/api/v1/profile/roles";
public String getDisplayName() {
return displayName;
@@ -88,8 +88,8 @@ public class RestBackendConfig {
public static class Endpoints {
private String auth = "/_mxisd/backend/api/v1/auth/login";
private String directory = "/_mxisd/backend/api/v1/directory/user/search";
private String auth = "/_ma1sd/backend/api/v1/auth/login";
private String directory = "/_ma1sd/backend/api/v1/directory/user/search";
private IdentityEndpoints identity = new IdentityEndpoints();
private ProfileEndpoints profile = new ProfileEndpoints();

10
src/script/mxisd → src/script/ma1sd
View File

@@ -2,7 +2,7 @@
##############################################################################
##
## mxisd start up script for UN*X
## ma1sd start up script for UN*X
##
##############################################################################
@@ -21,10 +21,10 @@ while [ -h "$PRG" ] ; do
done
APP_HOME=`dirname "$PRG"`
APP_NAME="mxisd"
APP_NAME="ma1sd"
APP_BASE_NAME=`basename "$0"`
# Add default JVM options here. You can also use JAVA_OPTS and MXISD_OPTS to pass JVM options to this script.
# Add default JVM options here. You can also use JAVA_OPTS and MA1SD_OPTS to pass JVM options to this script.
DEFAULT_JVM_OPTS=""
# Use the maximum available, or set MAX_FD != -1 to use that value.
@@ -61,7 +61,7 @@ case "`uname`" in
;;
esac
CLASSPATH=$APP_HOME/mxisd.jar
CLASSPATH=$APP_HOME/ma1sd.jar
# Determine the Java command to use to start the JVM.
if [ -n "$JAVA_HOME" ] ; then
@@ -158,7 +158,7 @@ for s in "${@}" ; do
done
# Collect JVM options
JVM_OPTS=$DEFAULT_JVM_OPTS" "$JAVA_OPTS" "$MXISD_OPTS
JVM_OPTS=$DEFAULT_JVM_OPTS" "$JAVA_OPTS" "$MA1SD_OPTS
# by default we should be in the correct project dir, but when run from Finder on Mac, the cwd is wrong
if [ "$(uname)" = "Darwin" ] && [ "$HOME" = "$PWD" ]; then

10
src/systemd/ma1sd.service Normal file
View File

@@ -0,0 +1,10 @@
[Unit]
Description=ma1sd
After=syslog.target
[Service]
User=ma1sd
ExecStart=/usr/bin/ma1sd -c /etc/ma1sd/ma1sd.yaml
[Install]
WantedBy=multi-user.target

10
src/systemd/mxisd.service
View File

@@ -1,10 +0,0 @@
[Unit]
Description=mxisd
After=syslog.target
[Service]
User=mxisd
ExecStart=/usr/bin/mxisd -c /etc/mxisd/mxisd.yaml
[Install]
WantedBy=multi-user.target