Matrix

Matrix is a messaging system you can on your server. It allows your to send messages to a phone/watch from command line on the server. It is useful with HomeAssistant for monitoring the house.

Here is an example of a Matrix Client, called Element[1], available on iOS, Android and Desktops.

IMG_2070A268049A-1.jpeg

  1. https://element.io/

Install

Matrix.org provides Debian/Ubuntu packages of Synapse via https://packages.matrix.org/debian/. To install the latest release:

Prerequsites:

sudo apt install -y lsb-release wget apt-transport-https

Matrix.org packages

sudo wget -O /usr/share/keyrings/matrix-org-archive-keyring.gpg https://packages.matrix.org/debian/matrix-org-archive-keyring.gpg
echo "deb [signed-by=/usr/share/keyrings/matrix-org-archive-keyring.gpg] https://packages.matrix.org/debian/ $(lsb_release -cs) main" |
    sudo tee /etc/apt/sources.list.d/matrix-org.list

sudo apt update
sudo apt install matrix-synapse-py3

Reference: https://github.com/matrix-org/synapse/blob/master/INSTALL.md

Configure

  • Set the public_baseurl to your server's local IP address.
  • Set the listeners to your server's local IP address too.

File: /etc/matrix-synapse/homeserver.yaml

#public_baseurl: https://example.com/
public_baseurl: http://192.168.1.3/
~
listeners:
  - port: 8008
    tls: false
    type: http
    x_forwarded: true
    bind_addresses: ['::1', '127.0.0.1', '192.168.1.3']

    resources:
      - names: [client, federation]
        compress: false
~
:wq

Set the shared secret and enable registration so we can create users for ourselves. We can disable it later because anyone with the shared secret can register, whether enabled or not.

Create the shared secret like this:

cat /dev/urandom | tr -dc 'a-zA-Z0-9' | fold -w 32 | head -n 1

File: /etc/matrix-synapse/homeserver.yaml

#enable_registration: false
enable_registration: true
~
# If set, allows registration of standard or admin accounts by anyone who
# has the shared secret, even if registration is otherwise disabled.
#
# Change the 'registration_shared_secret' with the random passphrase generated on below
#
registration_shared_secret: "S9gYeYowVX49U6OG25EEROKU4b2gEU3S"
#
server_name: localhost
#
:wq

Create User(s)

Using enable_registration=true, we can create users via register_new_matrix_user client.

$ register_new_matrix_user -c /etc/matrix-synapse/homeserver.yaml http://localhost:8008
New user localpart [bob]: alice
Password: 
Confirm password: 
Make admin [no]: n
Sending registration request...
Success!

Must have python > 2.7.9

Reference: https://matrix-org.github.io/synapse/latest/usage/administration/admin_api/

Database

Database is sqlite3, here:

$ ls /var/lib/matrix-synapse
homeserver.db  media

Check your database settings in the configuration file, connect to the correct database using either psql [database name] (if using PostgreSQL) or sqlite3 path/to/your/database.db (if using SQLite) and elevate the user @foo:bar.com to server administrator.

UPDATE users SET admin = 1 WHERE name = '@foo:bar.com';

You can also revoke server admin by setting admin = 0 above.

Room administrators and server administrators are different. Server admins don't have any power over rooms. When you use the "Start chat" button in Riot, it'll set everyone as room admin.

You can convert the database to PostgreSQL

https://github.com/matrix-org/synapse/blob/master/docs/postgres.md

Secure Configuration

Once you have tested Matrix, created users and have a SSL/TLS certificate, you can enable external communication.

Turn off registrations and comment out the registration_key.

File: /etc/matrix-synapse/homeserver.yaml

~
  46 # This is set in /etc/matrix-synapse/conf.d/server_name.yaml for Debian installations.
  47 # server_name: "SERVERNAME"
  48 server_name: matrix.example.com
~
  64 # The public-facing base URL that clients use to access this Homeserver (not
  65 # including _matrix/...). This is the same URL a user might enter into the
  66 # 'Custom Homeserver URL' field on their client. If you use Synapse with a
  67 # reverse proxy, this should be the URL to reach Synapse via the proxy.
  68 # Otherwise, it should be the URL to reach Synapse's client HTTP listener (see
  69 # 'listeners' below).
  70 #
  71 #public_baseurl: https://example.com/
  72 public_baseurl: https://matrix.example.com:8448
~
272 #
 273 listeners:
 274   # TLS-enabled listener: for when matrix traffic is sent directly to synapse.
 275   #
 276   # Disabled by default. To enable it, uncomment the following. (Note that you
 277   # will also need to give Synapse a TLS key and certificate: see the TLS section
 278   # below.)
 279   #
 280   - port: 8448
 281     type: http
 282     tls: true
 283     bind_addresses: ['::1', '0.0.0.0']
 284     resources:
 285       - names: [client, federation]
 286 
 287   # Unsecure HTTP listener: for when matrix traffic passes through a reverse proxy
 288   # that unwraps TLS.
 289   #
 290   # If you plan to use a reverse proxy, please see
 291   # https://matrix-org.github.io/synapse/latest/reverse_proxy.html.
 292   #
 293   - port: 8008
 294     tls: false
 295     type: http
 296     x_forwarded: true
 297     bind_addresses: ['::1', '127.0.0.1', '192.168.1.3']
 298 
 299     resources:
 300       - names: [client, federation]
 301         compress: false
 302 
~
 547 ## TLS ##
 548 
 549 # PEM-encoded X509 certificate for TLS.
 550 # This certificate, as of Synapse 1.0, will need to be a valid and verifiable
 551 # certificate, signed by a recognised Certificate Authority.
 552 #
 553 # Be sure to use a `.pem` file that includes the full certificate chain including
 554 # any intermediate certificates (for instance, if using certbot, use
 555 # `fullchain.pem` as your certificate, not `cert.pem`).
 556 #
 557 #tls_certificate_path: "/etc/matrix-synapse/SERVERNAME.tls.crt"
 558 tls_certificate_path: "/etc/letsencrypt/live/example.com/fullchain.pem"
 559 
 560 # PEM-encoded private key for TLS
 561 #
 562 #tls_private_key_path: "/etc/matrix-synapse/SERVERNAME.tls.key"
 563 tls_private_key_path: "/etc/letsencrypt/live/example.com/privkey.pem"
~
755 database:
 756   name: psycopg2
 757   args:
 758     user: matrix_user
 759     password: ************
 760     database: matrix
 761     host: 127.0.0.1
 762     cp_min: 5
 763     cp_max: 10
 764 
 765     # seconds of inactivity after which TCP should send a keepalive message to the server
 766     keepalives_idle: 10
 767 
 768     # the number of seconds after which a TCP keepalive message that is not
 769     # acknowledged by the server should be retransmitted
 770     keepalives_interval: 10
 771 
 772     # the number of TCP keepalives that can be lost before the client's connection
 773     # to the server is considered dead
 774     keepalives_count: 3
~
 777 ## Logging ##
 778 
 779 # A yaml python logging config file as described by
 780 # https://docs.python.org/3.7/library/logging.config.html#configuration-dictionary-schema
 781 #
 782 log_config: "/etc/matrix-synapse/log.yaml"
~
 906 # Directory where uploaded images and attachments are stored.
 907 #
 908 media_store_path: "/var/lib/matrix-synapse/media"
~
1139 # Enable registration for new users.
1140 #
1141 #enable_registration: false
1142 enable_registration: false
~
1190 # If set, allows registration of standard or admin accounts by anyone who
1191 # has the shared secret, even if registration is otherwise disabled.
1192 #
1193 #registration_shared_secret: <PRIVATE STRING>
1194 registration_shared_secret: "*****************************"
~
1438 ## Signing Keys ##
1439 
1440 # Path to the signing key to sign messages with
1441 #
1442 signing_key_path: "/etc/matrix-synapse/homeserver.signing.key"
~
#trusted_key_servers:
1500 #  - server_name: "my_trusted_server.example.com"
1501 #    verify_keys:
1502 #      "ed25519:auto": "abcdefghijklmnopqrstuvwxyzabcdefghijklmopqr"
1503 #  - server_name: "my_other_trusted_server.example.com"
1504 #
1505 trusted_key_servers:
1506   - server_name: "matrix.org"
~

File: /etc/matrix-synapse/conf.d/server_name.yaml

 # This file is autogenerated, and will be recreated on upgrade if it is deleted.
# Any changes you make will be preserved.

# The domain name of the server, with optional explicit port.
# This is used by remote servers to connect to this server,
# e.g. matrix.org, localhost:8080, etc.
# This is also the last part of your UserID.
#
server_name: matrix.example.com

Matrix Commander CLI

This will allow us to send text messages to our phone/watch from homeassistant.

Follow the instruction on the matrix-commander website. Specifically run with the --login parameter to create ~/.config/matrix-commander/credentials.json file.

Reference: https://github.com/8go/matrix-commander

Send Matrix

This script will assist in watching homeassistant for new messages, then sending them out.

File: ~/matrix/sendmatrix.sh 

#!/bin/bash
#----------------------------------------------------
# File: sendmatrix.sh
#
# Usage: sendmatrix.sh
#
# Purpose: Watch for new lines in a homeassistant (hass)
#  file (${HOME}/wave/hass/sendmatrix.log) and send an matrix 
#  message with those new line(s)
#
# Dependencies: 
#  - git clone https://github.com/8go/matrix-commander.git
#  - sudo apt-get install inotify-tools
#  - retail : git clone https://github.com/mbucc/retail.git
#  - NOTE: Docker configures / as /config for homeassistant
#          and ~/wave/hass is /
#  - ~/wave/hass/configuration.yaml
#       ~
#       shell_command:
#         xmpp_light_off: /config/script.sh Outside light off
#       ~
#  - ~/wave/hass/automations.yaml 
#       ~
#       - service: shell_command.xmpp_light_off
#       ~
#  - ~/wave/hass/script.sh
#       #!/bin/bash
#       echo "${@} - $(date)" >>  /config/sendxmpp.log
#
# Date     Author     Description
# ----     ------     -----------
# Sep-2021 Don Cohoon Created
# Sep-2022 Don Cohoon Updated matrix-commander version
# Oct-2022 Don Cohoon Fix matrix commander parameters
#----------------------------------------------------
HOME=${HOME}

# configure hass interface
DIR=${HOME}/wave
OFFSET=${DIR}/sendmatrix.cnt
RESULT=${DIR}/sendmatrix.txt
MSGS=${DIR}/hass/sendsms.log
LOG=${DIR}/sendmatrix.log
MATRIX_COMMANDER=$HOME/.local/lib/python3.10/site-packages/matrix_commander/matrix_commander.py
MATRIX_CONFIG=$HOME/.config/matrix-commander/credentials.json
MATRIX_STORE=$HOME/.config/matrix-commander/store
#MATRIX_DEBUG="-d"
MATRIX_DEBUG=""

#
date >> ${LOG}
# monitor mode, look for file ${MSGS} modification
/usr/bin/inotifywait -m -e modify ${MSGS} 2>&1 | while read line
do
  echo "$(date) - $line"  >> ${LOG}
  # grab any hass script.sh new lines since last time
  /usr/local/bin/retail -T ${OFFSET} ${MSGS} > ${RESULT}
  if [ ! -s "${RESULT}" ]; then
    rm ${RESULT}
  else
    # send text message to phone
    MSG=$(/bin/cat ${RESULT})
    /bin/cat ${RESULT} | /usr/bin/python3 ${MATRIX_COMMANDER} \
      -c ${MATRIX_CONFIG} -s ${MATRIX_STORE} --no-ssl ${MATRIX_DEBUG} -m - >>${LOG} 2>&1
    # nextcloud talk integration 
    ${HOME}/nextcloud/talk_mattermost.sh "${MSG}"
    #
    /bin/cat ${RESULT} >>${LOG} 2>&1
    date >> ${LOG}
  fi
done

Debug

matrix-commander credentials

This is the credentials.json file matrix-commander.py creates and uses.

$ cat  ~/.config/matrix-commander/credentials.json |jq .
{
  "homeserver": "http://127.0.0.1:8008",
  "device_id": "GTSIKDHJEG",
  "user_id": "@user:matrix.example.com",
  "room_id": "!JshkYudiHksdhKHSKk:matrix.example.com",
  "access_token": "syt_ZTSjdlksshoidywlSKkDHIASLJW_0D2t3m"
}

If you are interested in where the element values derive from, check these:

Change User Password

As an admin, you can reset another user's password.

Login as an admin and save an access token.

curl -XPOST -d '{"type":"m.login.password", "user":"<userId>", "password":"<pasword>"}' "https://localhost:8448/_matrix/client/r0/login"

Using that access token, reset any user's password.

curl -XPOST -H "Authorization: Bearer <access_token>" -H "Content-Type: application/json" -d '{"new_password":"<new_password>"}' "https://localhost:8448/_matrix/client/r0/admin/reset_password/<userId>"

<userId> is fully qualified. E.g. @user:server.com

Reference:

Matrix Client-Server API

The easiest way to administer a Matrix-Synapse server is through the Client-Server API [1].

Visit the API overview for many examples with code for:

  • Server Administration,
  • Account Management,
  • Spaces,
  • Event Relationships,
  • Threads,
  • Room Participation,
  • Session Management,
  • Capabilities,
  • Room Creation,
  • Device Management,
  • Room Discovery,
  • Room Directory,
  • Room Membership,
  • End-to-End Encryption,
  • Push Notifications,
  • Presence,
  • User Data,
  • and more.
  1. https://matrix.org/docs/api/#overview

Alternative: Nextcloud Talk

NextCloud Talk is part of NextCloud Services.

Continue

Now that you have set up Matrix Communication on your server, you can read some news to send to others. Read on to find out how to set up a local news/RSS reader.

Proceed in the order presented, some things are depending on prior setups.

Book Last Updated: 29-March-2024


Matrix Messaging - Linux in the House - https://linux-in-the-house.org Creative Commons License