diff --git a/.gitignore b/.gitignore index 616aad7..9c12686 100644 --- a/.gitignore +++ b/.gitignore @@ -7,8 +7,8 @@ out/ .idea/ # Local dev config -/mxisd.yaml +/ma1sd.yaml /application.yaml # Local dev storage -/mxisd.db +/ma1sd.db diff --git a/Dockerfile b/Dockerfile index ebdab25..8a38986 100644 --- a/Dockerfile +++ b/Dockerfile @@ -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 diff --git a/README.md b/README.md index c5d1cac..f20caad 100644 --- a/README.md +++ b/README.md @@ -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. diff --git a/build.gradle b/build.gradle index d6c241c..0d12997 100644 --- a/build.gradle +++ b/build.gradle @@ -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 } diff --git a/docs/architecture.md b/docs/architecture.md index c15f567..212d6bb 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -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 | +------------------------+ diff --git a/docs/build.md b/docs/build.md index 522e600..8a78284 100644 --- a/docs/build.md +++ b/docs/build.md @@ -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 ``` diff --git a/docs/concepts.md b/docs/concepts.md index 863c82b..148467c 100644 --- a/docs/concepts.md +++ b/docs/concepts.md @@ -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. diff --git a/docs/configure.md b/docs/configure.md index 7061af4..a3ce347 100644 --- a/docs/configure.md +++ b/docs/configure.md @@ -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-specific configuration for the given handler ID. Repeatable. diff --git a/docs/faq.md b/docs/faq.md index 9bf40fc..6b44db4 100644 --- a/docs/faq.md +++ b/docs/faq.md @@ -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. diff --git a/docs/features/authentication.md b/docs/features/authentication.md index f3d7998..9336a66 100644 --- a/docs/features/authentication.md +++ b/docs/features/authentication.md @@ -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: diff --git a/docs/features/bridge-integration.md b/docs/features/bridge-integration.md index 63174a8..0b81154 100644 --- a/docs/features/bridge-integration.md +++ b/docs/features/bridge-integration.md @@ -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 diff --git a/docs/features/directory.md b/docs/features/directory.md index fde3689..942592e 100644 --- a/docs/features/directory.md +++ b/docs/features/directory.md @@ -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: diff --git a/docs/features/experimental/application-service.md b/docs/features/experimental/application-service.md index 98af586..8eb4cd8 100644 --- a/docs/features/experimental/application-service.md +++ b/docs/features/experimental/application-service.md @@ -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 diff --git a/docs/features/federation.md b/docs/features/federation.md index fb44da1..a42a64d 100644 --- a/docs/features/federation.md +++ b/docs/features/federation.md @@ -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: diff --git a/docs/features/identity.md b/docs/features/identity.md index 8e281fc..ebde3cf 100644 --- a/docs/features/identity.md +++ b/docs/features/identity.md @@ -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) diff --git a/docs/features/registration.md b/docs/features/registration.md index cb90234..87db5ed 100644 --- a/docs/features/registration.md +++ b/docs/features/registration.md @@ -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 diff --git a/docs/getting-started.md b/docs/getting-started.md index 9b5414b..ae32361 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -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) diff --git a/docs/install/debian.md b/docs/install/debian.md index 84a51be..c9ed2b9 100644 --- a/docs/install/debian.md +++ b/docs/install/debian.md @@ -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 ``` diff --git a/docs/install/docker.md b/docs/install/docker.md index c713785..2e5067d 100644 --- a/docs/install/docker.md +++ b/docs/install/docker.md @@ -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/) diff --git a/docs/install/security.md b/docs/install/security.md index 61691bc..de4d46a 100644 --- a/docs/install/security.md +++ b/docs/install/security.md @@ -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, diff --git a/docs/install/source.md b/docs/install/source.md index 5a318cf..139b6c7 100644 --- a/docs/install/source.md +++ b/docs/install/source.md @@ -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`. diff --git a/docs/operations.md b/docs/operations.md index e236704..cf2aa8a 100644 --- a/docs/operations.md +++ b/docs/operations.md @@ -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. diff --git a/docs/stores/exec.md b/docs/stores/exec.md index e5d040d..8da4321 100644 --- a/docs/stores/exec.md +++ b/docs/stores/exec.md @@ -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 diff --git a/docs/stores/ldap.md b/docs/stores/ldap.md index 1280f43..535f2fc 100644 --- a/docs/stores/ldap.md +++ b/docs/stores/ldap.md @@ -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: diff --git a/docs/stores/rest.md b/docs/stores/rest.md index 09fa18b..8b39a54 100644 --- a/docs/stores/rest.md +++ b/docs/stores/rest.md @@ -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` diff --git a/docs/stores/sql.md b/docs/stores/sql.md index 72534a0..95074ea 100644 --- a/docs/stores/sql.md +++ b/docs/stores/sql.md @@ -80,7 +80,7 @@ sql: type: value: ``` -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: ``` -`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. diff --git a/docs/stores/wordpress.md b/docs/stores/wordpress.md index 33efd35..2692194 100644 --- a/docs/stores/wordpress.md +++ b/docs/stores/wordpress.md @@ -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: diff --git a/docs/threepids/notification/template-generator.md b/docs/threepids/notification/template-generator.md index 517dd57..fffb040 100644 --- a/docs/threepids/notification/template-generator.md +++ b/docs/threepids/notification/template-generator.md @@ -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. diff --git a/docs/threepids/session/session-views.md b/docs/threepids/session/session-views.md index f8cd503..9d06e2a 100644 --- a/docs/threepids/session/session-views.md +++ b/docs/threepids/session/session-views.md @@ -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 diff --git a/docs/threepids/session/session.md b/docs/threepids/session/session.md index 22d414c..c8696c9 100644 --- a/docs/threepids/session/session.md +++ b/docs/threepids/session/session.md @@ -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. diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index b96972d..e7611fa 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.md @@ -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 diff --git a/mxisd.example.yaml b/ma1sd.example.yaml similarity index 90% rename from mxisd.example.yaml rename to ma1sd.example.yaml index 1f5b819..0f3be3a 100644 --- a/mxisd.example.yaml +++ b/ma1sd.example.yaml @@ -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' ################### diff --git a/src/debian/control b/src/debian/control index d9ccbd0..bef1a5e 100644 --- a/src/debian/control +++ b/src/debian/control @@ -1,4 +1,4 @@ -Package: mxisd +Package: ma1sd Maintainer: ma1uta Homepage: https://github.com/ma1uta/ma1sd Description: Federated Matrix Identity Server diff --git a/src/debian/postinst b/src/debian/postinst index b8d9b2b..3a06ed4 100755 --- a/src/debian/postinst +++ b/src/debian/postinst @@ -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 diff --git a/src/debian/prerm b/src/debian/prerm index 05a65f4..bee08db 100644 --- a/src/debian/prerm +++ b/src/debian/prerm @@ -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 diff --git a/src/docker/start.sh b/src/docker/start.sh index 37daba6..1edaecf 100755 --- a/src/docker/start.sh +++ b/src/docker/start.sh @@ -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 diff --git a/src/main/java/io/kamax/mxisd/MxisdStandaloneExec.java b/src/main/java/io/kamax/mxisd/MxisdStandaloneExec.java index 73d3292..fd84e39 100644 --- a/src/main/java/io/kamax/mxisd/MxisdStandaloneExec.java +++ b/src/main/java/io/kamax/mxisd/MxisdStandaloneExec.java @@ -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); } diff --git a/src/main/java/io/kamax/mxisd/config/rest/RestBackendConfig.java b/src/main/java/io/kamax/mxisd/config/rest/RestBackendConfig.java index 1f1a7b8..1291531 100644 --- a/src/main/java/io/kamax/mxisd/config/rest/RestBackendConfig.java +++ b/src/main/java/io/kamax/mxisd/config/rest/RestBackendConfig.java @@ -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(); diff --git a/src/script/mxisd b/src/script/ma1sd similarity index 96% rename from src/script/mxisd rename to src/script/ma1sd index 331afe1..ec550c8 100755 --- a/src/script/mxisd +++ b/src/script/ma1sd @@ -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 diff --git a/src/systemd/ma1sd.service b/src/systemd/ma1sd.service new file mode 100644 index 0000000..253138f --- /dev/null +++ b/src/systemd/ma1sd.service @@ -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 diff --git a/src/systemd/mxisd.service b/src/systemd/mxisd.service deleted file mode 100644 index e60803f..0000000 --- a/src/systemd/mxisd.service +++ /dev/null @@ -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