MirrorHub
/
construct
mirror of https://github.com/matrix-construct/construct
0
0
Fork 0
Code Issues Releases Wiki Activity
Page: Useful console command examples
Pages
ARCHITECTURE AUQ About the server BUILD Bridges DOCKER Events dump and rebuild FAQ Home Other known problems SETUP STYLE TUNING Troubleshooting problems Useful console command examples
31 Useful console command examples
Jason Volk edited this page 2023-01-11 10:15:05 -08:00
Table of Contents

Administrative Console

Accessing the Console

  1. Administrators with local access can strike CTRL-C and interact with the command prompt. This is the same as otherwise raising SIGINT and interacting with the server using standard input and output, which is available to parent processes.

  2. Administrators may join themselves to !control:SERVERNAME room to execute commands through their client (using terminal: room join !control:servername @user:servername).

    👉 Note responses to commands are truncated to the 64 KiB Matrix event limit in this mode (but rarely an issue).

    • Riot is inconvenient for this use case; suggest compact timeline layout mode.
    • nheko makes it convenient to edit the previous line.
    • The !control room in gomuks looks and feels identical to the terminal console and is the best choice.

  3. The control server-side command (\\control <command>) is available for users joined to !control as prescribed above. Commands can be input in any client when viewing any room: they will not be echoed and their response will be displayed privately.

    👉 Server-side commands and their responses can be publicly echoed by using the \\! prefix (\\!control <command>) such that the interaction will be broadcast to the room from the administrator's user.

    👉 Outputs from server-side commands will remain in the room's timeline like any other message. Private outputs do not survive a client clear-cache & reload and should not be visible in the timeline afterward.

  4. Executing the server with the -console parameter will spawn the console immediately after startup. The server will still be running normally in the background.

  5. Executing the server with the -execute <command> parameter will spawn the console immediately after startup and execute the command. Upon completion the console will exit; the server will still be running normally in the background.

    👉 Only the next argument after -execute is the command. Refer to your shell's documentation for how to pass complex program options (hint: use quotes around commands with spaces).

    👉 Use multiple -execute parameters for multiple commands.

🛑 DANGER

THE CONSOLE HAS COMPLETE CONTROL OF THE SERVER. CHANGES THROUGH THE CONSOLE ARE EFFECTIVE IMMEDIATELY. ERRONEOUS VALUES MAY CAUSE UNEXPECTED BEHAVIOR RESULTING IN ABNORMAL PROGRAM TERMINATION AND/OR LOSS OF DATA. ACCESS TO THE !CONTROL ROOM AND SERVER TERMINAL MUST REMAIN RESTRICTED AT ALL TIMES TO AUTHORIZED USERS ONLY.

👉 To learn more about a command, including the list of all sub-commands, use help <command>. We kindly request your contribution for missing help text.

Table of Contents

Commands for a specific element of Matrix:
  1. $ event - Atomic unit of the Matrix protocol.
  2. @ user - Party to the Matrix protocol.
  3. ! room - Collection of events in a timeline.
  4. + group - Collection of rooms and users.
  5. : node - Collection of users (a.k.a. origin, server).
  6. bridge - Management of an application-service.
  7. fed - Diagnostic for a remote server interaction (federation API).
  8. mc - Diagnostic for remote server interaction (client API).
  9. file - Diagnostic for media.
Commands for multiple elements of a specific category:
  1. events - Diagnostic over multiple/all events known to server.
  2. rooms - Diagnostic over multiple/all rooms known to server.
  3. users - Diagnostic over multiple/all users known to server.
  4. groups - Diagnostic over multiple/all groups known to server.
  5. bridges - Diagnostic over multiple/all registered application-services.
  6. feds - Performs equivalent diagnostic to fed over multiple/all servers in a room.
Other Matrix application suites:
  1. vm - Information about event dispatch; core processing.
  2. hook - Information about event listeners.
  3. synchron - Information about synchronizing clients.
  4. redact - Quick shortcut to redact an event.
  5. fetch - Diagnostic to fetch an event from any server in a room.
  6. stage - Create and manipulate events from scratch in console memory (difficult interface).

General Server Operation

Primary Information
  • help - List commands or information about a command.
  • credits - Information about the project, license and contributors.
  • version - The server's current version (N.B. version -a).
  • versions - Versions from library and system dependencies.
Primary Administration
  • exit - Close the console (ctrl-d/EOF).
  • conf - List and control server configuration.
  • sync - Force flush and synchronize to local storage.
  • restart - Restart the server.
  • die - Shutdown the server.
Subsystem Administration
  • aio - Information about Linux AIO (on available systems).
  • ctx - Userspace threading lists and controls.
  • db - Database system interface.
  • fs - Miscellaneous filesystem related commands.
  • ios - Core event loop diagnostics.
  • log - Logging system interface.
  • mem - Dynamic memory interface.
  • mod - Dynamic module system.
  • net - Miscellaneous network related commands.
  • prof - Profiling and performance related.
  • stats - Server statistics and tickers.
Top-level Networking Related:
  • client - Information and control over incoming connections.
  • host - Domain Name System diagnostic suite.
  • peer - Information and control over outgoing connections.
  • resource - Information and control over incoming request handlers.
  • well_known - well-known diagnostic (i.e. well_known matrix server <host>)
Miscellaneous Diagnostics & Tools:
  • date - Diagnostic for the current date and time.
  • env - Posix environment variables for server (N.B. env *).
  • icu - Diagnostic explaining all characters (including hidden) given as argument.
  • ls - Convenience browser of the server's $PWD
  • mark - Immediately mark the logfiles with a message which can be searched for later.
  • proc - Convenience browser of /proc/self/ (i.e. proc sched proc net proc net/tcp)
  • stringify - Diagnostic outputting canonical JSON from argument.
  • uptime - Duration the server has been running.
Developer Diagnostics & Tools:
  • bt - Print a backtrace.
  • debug - Toggle debug logging.
  • demangle - Diagnostic for symbol name mangling.
  • test - dlsym(3) the function bool ircd::ircd_test(const string_view &) and pass argument.
  • vg - Valgrind hypercall interface (when running in valgrind).

Auxilary commands:

  1. watch <second_float> <command with args> - repeatedly run any command (example: watch 0.25 vm)

MXID-as-command

A Matrix-ID itself is recognized as a command for convenience.

<room_id>

Shows the known data of the specific room_id.

<room_id> <type> <state_key>

Shows the known data of an event in the room's state.

<event_id>

Shows the known data of the specific event_id.

<event_id> content

Shows the content field of the specific event_id.

<event_id> raw

Shows the raw JSON of the specific event_id.

<room_alias>

Room aliases are resolved to a room_id throughout all console commands. In this case it behaves as <room_id> was described earlier.

room

can be

  • room_id (!AAAANTUiY1fBZ230:zemos.net)
  • alias (#construct-server:grin.hu)

room events <room>

lookup room events

room head reset <room>

Rebootstrap room: try to clear and re-retrieve all data from the start.

room restrap <join-event_id> <member_server>

Re-bootstrap a room from a known join event, using any server which has the said event. Can be usd to rebuild the room graph in case of… need.

room get <room> [<event_type> [<mxid>]]

List room events, optionally restricting to the given type or the given mxid. Maybe any of them.

room state <room>

Get complete room state according to the server.

room state rebuild <room>

Manually rebuild the present room state from the room state space. Required if the present state resolves incorrectly or falls out of sync due to bugs or missing functionality in the server.

room state space rebuild <room>

Manually rebuild the higher dimension room state space table from the room events table. Required if any state event is missing from this table, but is in the room events (rare).

room state space <room> [event_type] [state_key]

Show all possible states for a given (type,state_key) "cell"

  • The state which is selected for the present-state is marked with an * asterisk.
  • A state which fails one of the three authentication phases is marked with an X and a reason string may be present on the right.
  • A state which has been redacted is marked with an R

room members <room>

Show members of a room according to the server.

room events <room>

Show room events (or at least the first few ones).

room events <room> <int> <int>

Show events only ? to ?. The first number is ? and the second is ?. FIXME

room purge <room>

Remove room data from server [will be backfilled if needed]. May be needed to remove histerical historical rooms causing trouble.

room join <room> <user>

Grabs the user and throws it into the room.

  • room join #construct:zemos.net @joe:construct.example.com

room alias cache

Lists the entries in the alias cache.

room alias cache del <room_alias>

Delete an entry in the cache; forces a fetch next time alias is used.

room acquire <room_id> [low depth] [high depth]

Fetch & evaluate all missing events in the room, filling in at least from low depth to high depth. If high depth is zero or not given, the room's head is fetched from remote servers and filled in from the low depth. If neither are given an attempt is made to acquire all missing events. This operation may take several minutes. For some rooms it may take several hours.

rooms

rooms head reset remote_joined_only

Mass reset room heads of remote rooms.

conf

Configuration and settings.

conf [config_string_start]

Show all config variables. If you give it a string (like conf ircd.m.media) it will list all the config variables starting with that string.

conf get <variable> and conf set <variable> <value>

Get/Set a config variable. The value part is not type checked so try not to put numbers into booleans, etc.

conf set ircd.log.info.file.enable true

Enable logging to file(s).

conf diff

Show all differences between your current configuration and the defaults. Very useful to see all your config changes from the defaults.

log

Log level and facility control.

log

List all logging facilities. CONSOLE and FILE are displayed if active.

log level [level-name]

Enable log levels equal and less than provided level (affects console only). Most severe log level is CRITICAL (0) and least severe level is DEBUG (7). Therefore log level CRITICAL only displays CRITICAL messages.

Most of the DEBUG level messages require you to compile the server with --enable-debug, see [[BUILD]].

log mask [facility] [...]

Only enables facilities listed (affects console only). All other facilities are muted. Note: log mask with no arguments mutes all facilities.

log unmask [facility] [...]

Mutes all facilities listed (affects console only). All other facilities will be enabled.

Example: log unmask m.presence m.typing m.receipt

Note: log unmask with no arguments unmutes all facilities.

fed

Federation related.

fed event <event_id> <host> [eval|raw]

Federation query to host for event with result pretty-printed in console. Use "raw" argument to display actual string received from host; or use "eval" argument to process the event.

fed state <room> <host> [event_id] [eval]

Federation query to host for the state of room at event_id. Optionally the "eval" argument will process the state as well (note this is for diagnostic purposes and may evaluate the state slower than normal methods).

db

db

List active databases

db info <db>

Information on a database (events, media).

db columns <db>

Show database columns (and their size).

db compact <db> [<table>]

Call a RocksDB compaction on db (events or media) table (like _room_head). The purpose of the compaction is…

db sort <db>

…(I guess it does sort/index the table for faster access?)… FIXME

db cache events *

Majority of the memory usage is db cache. This command shows the memory usage of the db cache. If you use two stars (**) you get the details. You can tailor the "Capacity" by configuring like conf ircd.m.dbs.content.cache.size.

db files <db>

  • db files events

List database statistics for all the tables.

db files <db> <table>

  • db files events _event_json

List table statistics for one table, listing the specific database files the table uses.

db files <db> <tablefile>

  • db files events /019496.sst

List file table statistics for the specifc file of a table. Details internal data, including compression.

db check <db>

Check database for basic consistency.

user

user room_tags <mxid>

Show room tags of an user. (Supposedly.)

user register <localname> <password>

Register a new user. Requires a name only:

  • user register test d34bd05ee2e403b1cd199d8068e590615390

redact

redact <event_id> [user_id] or redact <room> <type> <state_key> [user_id]

Quick redact command. The user_id defaults to @ircd:your.host which is only useful for internal rooms. For public rooms you must give the user with permission to redact.

Some examples:

  • redact !dns:your.host well-known.matrix.server some.host - drop record from the well-known cache.
  • redact !dns:your.host ircd.net.dns.rrs.AAAA some.host - drop ip6 record from the DNS cache.

mod

mod reload <module>

This is useful when you want to restart a module without dieing the whole server. Like, when you update webbapp you out to

  • mod reload web_root since The Construct have cached the webapp files.