DOCSEARCHbyAlgolia
Submit Docs

Ketesa Documentation

repository·main·Indexed 19 days ago

https://github.com/etkecc/ketesa

A comprehensive web-based administration interface for Matrix homeservers, specifically Synapse (v1.150.0+) and Matrix Authentication Service (MAS). Ketesa provides tools for user management, room and media control, federation monitoring, and server statistics. It supports multiple deployment methods including Docker, static files, and hosted CDN, and can be configured via config.json or .well-known/matrix/client.

Tokens
41.3K
Snippets
97
Records
199
Agent score
65%

What's inside Ketesa

  1. Overview of Ketesa documentation and guides

    main

    Ketesa is a management interface that interacts with Synapse and MAS APIs. The documentation is organized into several key areas to help you manage your Matrix server:

    • Configuration: Guides for tuning CORS, restricting homeservers, managing system/appservice users, customizing menus, and configuring external auth providers.
    • APIs: A complete list of supported Synapse and MAS endpoints.
    • User Management: Tools for user search, bulk CSV imports, registration tokens, and managing account data/policies.
    • Room Management: Controls for blocking, purging history, deleting rooms, managing members/state, and media management.
    • Moderation & Federation: Tools for reviewing event reports and monitoring federation connections.
    • Statistics & Tasks: Monitoring database sizes, media usage, and background tasks.
    • etke.cc-exclusive features: Specialized components for users on etke.cc-hosted deployments, including server status, notifications, actions, billing, and support.

  2. Overview of Ketesa features

    main

    Ketesa is a web interface for managing Synapse and Matrix Authentication Service (MAS) homeservers. Key management capabilities include:

    • User Management: Suspend, shadow-ban, deactivate, or erase accounts. Manage rate limits, experimental features, account data, devices, room memberships, and cross-signing keys. Supports CSV import for bulk onboarding and native MAS user management (session revocation, linked emails, OAuth2).
    • Room Management: Block/unblock rooms, purge history, delete rooms, manage room hierarchy (spaces), and view messages with filters.
    • Media Management: Quarantine, protect, or delete media by file, user, or room.
    • Authentication: Supports username/password, raw access tokens, OIDC/SSO, and native Matrix Authentication Service (MAS) integration.
    • Server Statistics: Monitor per-user media usage, database room size, federation health, and review reported events.
    • Customization: Users can reorder/hide columns in data tables via react-admin components. Admins can use a config.json file to restrict homeservers, add custom navigation, pre-fill login forms, tune CORS, and shield appservice-managed users.

  3. Supported APIs in Ketesa

    main

    Ketesa integrates with various Matrix-related APIs to manage homeservers and services. The current implementation is compiled against Synapse v1.151.0 and MAS (Matrix Authentication Service) v1.15.0.

    When using Ketesa, be aware that API support status is tracked using the following legend:

    • ✅ fully implemented
    • 🟡 in progress
    • ❌ not implemented
    • ⏭️ superseded (newer version available)

  4. Understand the structure of ketesa components

    main

    The components/ directory contains shared UI components organized by feature domain. This organization helps developers locate components based on the functional area they serve.

    Key domains include:

    • layout/: App-level structural components like AdminLayout, LoginFormBox, EmptyState, and Footer.
    • users/: Components for user management, further subdivided into buttons/ (e.g., DeactivateButton, ResetPasswordButton) and fields/ (e.g., AvatarField).
    • rooms/: Components related to room management.
    • media/: Components for media quarantine and deletion.
    • user-import/: Self-contained components for bulk CSV user imports.
    • etke.cc/: Components implementing ETKE.CC-exclusive features.
    • hooks/: Shared React hooks used across the project.

  5. Understand Well-known discovery in Ketesa

    main

    By default, Ketesa uses the Matrix specification for well-known discovery. When a user enters a domain (e.g., https://example.com) or a full Matrix ID (e.g., @user:example.com) on the login page, Ketesa fetches the /.well-known/matrix/client file from that domain. It then reads the m.homeserver.base_url to determine the actual homeserver address (e.g., https://matrix.example.com) to connect to.

    This behavior is enabled by default and is intended for most standard deployments.

  6. Understand the severity score in reports

    main

    Reports include a numeric severity score (where Synapse's admin API treats -100 as most offensive and 0 as inoffensive).

    Warning: Do not use this score for triage. Because client applications often send the default value on every report, the score is effectively noise and does not provide a reliable signal of how offensive an event actually is. Always judge content based on the raw data in the Details tab.

  7. Protect appservice-managed users with asManagedUsers

    main

    Matrix bridges create 'puppet' accounts for bridged users. Modifying these accounts (e.g., deactivating, locking, or resetting passwords) can silently break the bridge for that user.

    To prevent this, you can use the asManagedUsers configuration to mark specific MXID patterns as appservice-managed. Once marked, Ketesa protects these accounts from destructive changes while still allowing harmless cosmetic updates like changing a display name or avatar.

    Protected actions (Blocked on managed accounts):

    • Deactivating or erasing the account
    • Locking, suspending, or shadow-banning
    • Resetting the password
    • Changing admin status
    • Removing devices and sessions

    Allowed actions:

    • Editing display names
    • Changing avatars
    • Re-activating an account that was already locked, deactivated, or erased (for repair purposes)

  8. Deactivate, erase, or delete user accounts

    main

    User account management involves three distinct levels of removal. Be aware that the "Delete" button's behavior changes based on your authentication mode.

    1. Deactivation (Reversible)

    Check the Deactivated checkbox on the edit form.

    • Effect: Disables login, invalidates access tokens, and removes the user from rooms.
    • Data: The account record and message history remain intact.
    • Reversal: Uncheck Deactivated and set a new password to restore the account.

    2. Erasing (Permanent)

    Check the Erased checkbox on the edit form (this requires Deactivated to be checked first).

    • Effect: Performs deactivation and instructs Synapse to purge the user's messages and media.
    • Data: The purge is permanent and cannot be undone. If you uncheck Erased later, you get an empty account record back.

    3. The "Delete" Button (Mode-Dependent)

    This button appears in the edit-page toolbar and the list's bulk-action toolbar. Its behavior depends on your auth mode:

    ModeActionDetails
    Native SynapseErasesDeactivates the account and purges content. Offers options to: 1. Delete user media, 2. Redact user events first.
    MAS ModeDeactivatesOnly deactivates the account; media and redaction options are hidden.

    Restriction: You cannot deactivate, erase, or delete your own admin account.

  9. Configure conflict behavior during import

    main

    A conflict occurs when a row's ID already belongs to an existing account. Because the importer only creates accounts and never updates them, you must choose how to handle these clashes using the Conflict Mode dropdown:

    • Stop (default): The import halts at the first clash. The offending ID is named in an error card. Use this if your CSV is intended to contain only entirely new users.
    • Skip: The importer sets clashing rows aside and continues processing the rest of the file. Use this to re-run a partially finished import or when mixing new and existing users.

    Note: There is no update mode for existing accounts. To modify existing users, use the user edit form or bulk actions in the user list.

  10. Block or Unblock a room

    main

    Blocking a room prevents new members from joining. Existing members remain in the room and can continue communicating.

    • Single room: Use the Block or Unblock button in the room's detail view toolbar.
    • Bulk action: Select multiple rooms in the Room List and use the bulk bar.
    • By ID: Use the Block room by ID button in the Room List toolbar to block a room directly using its full Matrix ID.

  11. Understand how table column settings are stored

    main

    Table column configurations (visibility and order) are stored in the browser's local storage rather than on the Ketesa server.

    Because settings are client-side:

    • Device Specific: Layout changes made on a desktop will not appear on a mobile device or a different browser.
    • Persistence: Settings persist across sessions unless the browser's site data/browsing data is cleared. Clearing site data will reset all tables to their default column configurations.

  12. Read and inspect a report

    main

    Clicking a row in the Reported events list opens a report view with two tabs:

    • Basic: Contains metadata including the report ID, timestamp, and the reporter's free-text reason. It provides direct links to the Reporter, the Sender, and the Room via their avatar entries to facilitate quick moderation.
    • Details: Displays the raw JSON of the flagged event as stored by the homeserver (type, content, sender, timestamps, and signatures). If the event has been redacted or deleted, this tab will be empty.