SYNCTL(1)

📦
version 1.132.0 · 2 versions
, in opensuse-leap 16.0

💅 SYNCTL(1) — like, the synctl manual page, bestie 🎀

okay so this is SYNCTL(1), the manual page for synctl — the Synapse server control interface. yes, that Synapse. the Matrix homeserver one. we're doing sysadmin today and honestly? iconic of us. ✨

🌸 NAME 🌸

synctl — the Synapse server control interface. that's it, that's the vibe. she controls the server. main character energy fr fr. 👑

🦋 SYNOPSIS 🦋

Start, stop or restart synapse server. that's the whole job description, no notes.

synctl {start|stop|restart} [configfile] [-w|--worker=WORKERCONFIG]
[-a|--all-processes=WORKERCONFIGDIR]

look at her. three actions, one optional config file, and two flags that let you get all up in the worker situation. we love a compact queen. 💜

✨ DESCRIPTION ✨

so like, synctl can be used to start, stop or restart the Synapse server. that's the tea. ☕

and here's the cute part: the control operation can be done on all processes or on a single worker process. so you can do the group-chat thing where everyone gets the message, or you can slide into one worker's DMs specifically. both valid. both slay. 🫶

💖 OPTIONS 💖

  • action — the value of action should be one of start, stop or restart. pick one bestie, it's not a multiple choice where you get to circle all three. 🙈
  • configfile — optional path of the configuration file to use. the default value is homeserver.yaml. and listen — the configuration file must exist for the operation to succeed. like, no config file, no operation. she's not doing charity work. 😭
  • -w, --worker: — this exists. the original page gives us the flag and then… nothing. no description, no explanation, just -w, --worker: sitting there like a mystery. 🕵️‍♀️ i'm not gonna make stuff up about her — that's not the vibe — so: here's the flag, character for character, exactly as the page gives it.
  • -a, --all-processes: — same situation, bestie. flag present, description absent. -a, --all-processes: and that's genuinely all we got. respect the mystery. 💀
ngl it's giving "the docs ran out of steam at the options section" but we don't judge. we just transcribe. 💅

🧚 CONFIGURATION FILE 🧚

okay so you need a configuration file and you don't have one? the configuration file may be generated as follows:

$ python -m synapse.app.homeserver -c config.yaml --generate-config --server-name=<server name>

copy it, paste it, swap in your <server name>, and boom — config file, generated, gorgeous, done. ⭐

🌈 ENVIRONMENT 🌈

🍓 SYNAPSE_CACHE_FACTOR

okay this one's a whole essay so buckle up bestie. 💀

Synapse's architecture is quite RAM hungry currently — and when the manpage says "quite RAM hungry" it means she eats. we deliberately cache a lot of recent room data and metadata in RAM in order to speed up common requests. that's the trade: RAM now, fast later.

we'll improve this in the future, but for now the easiest way to either reduce the RAM usage (at the risk of slowing things down) is to set the almost-undocumented SYNAPSE_CACHE_FACTOR environment variable.

the default is 0.5. you can decrease it to reduce RAM usage in memory constrained enviroments, or increase it if performance starts to degrade. so like, small number = less RAM, big number = more speed. simple. except it's not. 😭

plot twist warning 🚨 — degraded performance due to a low cache factor, common on machines with slow disks, often leads to explosions in memory use due backlogged requests. and in this case, reducing the cache factor will make things worse. worse!! so do not do the intuitive thing. the intuitive thing is a trap.

instead, try increasing it drastically. 2.0 is a good starting value. yes you read that right, the fix for "slow and struggling" is more cache. she's complicated like that. 🔥

this man page was written by Sunil Mohan Adapa <mailto:sunil@medhas.org> for the Debian GNU/Linux distribution. credit where credit is due, we love a documented author. 🫶

🔥 SEE ALSO 🔥

go read these too, they're the friend group:

and that's the whole page, bestie. no notes. go forth and control your Synapse server responsibly. 💜

🌸 this has been SYNCTL(1), from July 2021 — mwah, talk later, xoxo 🎀

📦 where this page comes from