Useful console command examples

Some random useful commands

The console right now lacks comprehensive help; here are some useful commands seen in the wild. You can use the console (CTRL-C) or the !control:SERVERNAME room. Riot is super inconvenient for the latter, but nheko (for example) makes it convenient to edit the previous line.

Most of these commands are only interesting throughout the betatesting, like unscrewing room or server states, or examining what's going on.

$ event - Atomic unit of Matrix protocol.
! room - Collection of events in a timeline.
@ user - Party to the Matrix Protocol.
+ group - Collection of rooms and users.
: node - Collection of users (a.k.a. origin, server).
bridge - Management of an application-service.
fed - Diagnostic for a remote server interaction (federation API).
mc - Diagnostic for remote server interaction (client API).
file - Diagnostic for media.

Commands for multiple elements of a specific category:

events - Diagnostic over multiple/all events known to server.
rooms - Diagnostic over multiple/all rooms known to server.
users - Diagnostic over multiple/all users known to server.
groups - Diagnostic over multiple/all groups known to server.
bridges - Diagnostic over multiple/all registered application-services.
feds - Performs equivalent diagnostic to fed over multiple/all servers in a room.

Other Matrix application suites:

vm - Information about event dispatch; core processing.
hook - Information about event listeners.
synchron - Information about synchronizing clients.
redact - Quick shortcut to redact an event.
fetch - Diagnostic to fetch an event from any server in a room.
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).
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).
conf - List and control server configuration.
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 connected clients.
host - Domain Name System diagnostic suite.
peer - Information and controls for connections to other servers.
resource - Information about the registered HTTP handler hierarchy.
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).

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

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.

user

`user room_tags <mxid>`

Show room tags of an user. (Supposedly.)

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.

Useful console command examples

Some random useful commands

Table of Contents

Commands for a specific element of Matrix:

Commands for multiple elements of a specific category:

Other Matrix application suites:

General Server Operation

Primary Information

Primary Administration

Subsystem Administration

Top-level Networking Related:

Miscellaneous Diagnostics & Tools:

Developer Diagnostics & Tools:

MXID-as-command

<room_id>

<room_id> <type> <state_key>

<event_id>

<event_id> content

<event_id> raw

<room_alias>

room

room events <room>

room head reset <room>

room restrap <join-event_id> <member_server>

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

room state <room>

room state rebuild <room>

room state space rebuild <room>

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

room members <room>

room events <room>

room events <room> <int> <int>

room purge <room>

room join <room> <user>

rooms

rooms head reset remote_joined_only

conf

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

conf diff

log

log

log level [level-name]

log mask [facility] [...]

log unmask [facility] [...]

fed

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

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

db

db

db info <db>

db columns <db>

db compact <db> <table>

db cache events *

user

user room_tags <mxid>

redact

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

mod

mod reload <module>

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Clone this wiki locally

`<room_id>`

`<room_id> <type> <state_key>`

`<event_id>`

`<event_id> content`

`<event_id> raw`

`<room_alias>`

`room events <room>`

`room head reset <room>`

`room restrap <join-event_id> <member_server>`

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

`room state <room>`

`room state rebuild <room>`

`room state space rebuild <room>`

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

`room members <room>`

`room events <room>`

`room events <room> <int> <int>`

`room purge <room>`

`room join <room> <user>`

`rooms head reset remote_joined_only`

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

`conf diff`

`log`

`log level [level-name]`

`log mask [facility] [...]`

`log unmask [facility] [...]`

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

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

`db`

`db info <db>`

`db columns <db>`

`db compact <db> <table>`

`db cache events *`

`user room_tags <mxid>`

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

`mod reload <module>`