Skip to content

Useful console command examples

Jump to bottom Edit New page
Peter Gervai edited this page Jan 12, 2021 · 31 revisions

Administrative Console

There are several ways to interact with 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 (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 console and is the best choice.

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

  4. 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.

❗ THE CONSOLE HAS COMPLETE CONTROL OF THE SERVER. CHANGES TO SERVER STATE AND CONFIGURATION THROUGH THE CONSOLE ARE EFFECTIVE IMMEDIATELY. ERRONEOUS VALUES MAY CAUSE UNEXPECTED BEHAVIOR RESULTING IN 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 Matrix protocol.
  2. ! room - Collection of events in a timeline.
  3. @ user - Party to the Matrix Protocol.
  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 (!kjkjkjljlkjkljlk:example.com)
  • alias (#alias:example.com)

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 ?.

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 set ircd.log.info.file.enable true

Enable logging to file(s).

conf diff

Show all differences between your current configuration and 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). Therefor log level CRITICAL only displays CRITICAL messages.

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).

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.

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.
Add a custom footer

Clone this wiki locally