| 123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780781782783784785786787788789790791792793794795796797798799800801802803804805806807808809810811812813814815816817818819820821822823824825826827828829830831832833834835836837838839840841842843844845846847848849850851852853854855856857858859860861862863864865866867868869870871872873874875876877878879880881882883884885886887888889890891892893894895896897898899900901902903904905906907908909910911912913914915916917918919920921922923924925926927928929930931932933934935936937938939940941942943944945946947948949950951952953954955956957958959960961962963964965966967968969970971972973974975976977978979980981982983984985986987988989990991992993994995996997998999100010011002100310041005100610071008100910101011101210131014101510161017101810191020102110221023102410251026102710281029103010311032103310341035103610371038103910401041104210431044104510461047104810491050105110521053105410551056105710581059106010611062106310641065106610671068106910701071107210731074107510761077107810791080108110821083108410851086108710881089109010911092109310941095109610971098109911001101110211031104110511061107110811091110111111121113111411151116111711181119112011211122112311241125112611271128112911301131113211331134113511361137113811391140114111421143114411451146114711481149115011511152115311541155115611571158115911601161116211631164116511661167116811691170117111721173117411751176117711781179118011811182118311841185118611871188118911901191119211931194119511961197119811991200120112021203120412051206120712081209121012111212121312141215121612171218121912201221122212231224122512261227122812291230123112321233123412351236123712381239124012411242124312441245124612471248124912501251125212531254125512561257125812591260126112621263126412651266126712681269127012711272127312741275127612771278127912801281128212831284128512861287128812891290129112921293129412951296129712981299130013011302130313041305130613071308130913101311131213131314131513161317131813191320132113221323132413251326132713281329133013311332133313341335133613371338133913401341134213431344134513461347134813491350135113521353135413551356135713581359136013611362136313641365136613671368136913701371137213731374137513761377137813791380138113821383138413851386138713881389139013911392139313941395139613971398139914001401140214031404140514061407140814091410141114121413141414151416141714181419142014211422142314241425142614271428142914301431143214331434143514361437143814391440144114421443144414451446144714481449145014511452145314541455145614571458145914601461146214631464146514661467146814691470147114721473147414751476147714781479148014811482148314841485148614871488148914901491149214931494149514961497149814991500150115021503150415051506150715081509151015111512151315141515151615171518151915201521152215231524152515261527152815291530153115321533153415351536153715381539154015411542154315441545154615471548154915501551155215531554155515561557155815591560156115621563156415651566156715681569157015711572157315741575157615771578157915801581158215831584158515861587158815891590159115921593159415951596159715981599160016011602160316041605160616071608160916101611161216131614161516161617161816191620162116221623162416251626162716281629163016311632163316341635163616371638163916401641164216431644164516461647164816491650165116521653165416551656165716581659166016611662166316641665166616671668166916701671167216731674167516761677167816791680168116821683168416851686168716881689169016911692169316941695169616971698169917001701170217031704170517061707170817091710171117121713171417151716171717181719172017211722172317241725172617271728172917301731173217331734173517361737173817391740174117421743174417451746174717481749175017511752175317541755175617571758175917601761176217631764176517661767176817691770177117721773177417751776177717781779178017811782178317841785178617871788178917901791179217931794179517961797179817991800180118021803180418051806180718081809181018111812181318141815181618171818181918201821182218231824182518261827182818291830183118321833183418351836183718381839184018411842184318441845184618471848184918501851185218531854185518561857185818591860186118621863186418651866186718681869187018711872187318741875187618771878187918801881188218831884188518861887188818891890189118921893189418951896189718981899190019011902190319041905190619071908190919101911191219131914191519161917191819191920192119221923192419251926192719281929193019311932193319341935193619371938193919401941194219431944194519461947194819491950195119521953195419551956195719581959196019611962196319641965196619671968196919701971197219731974197519761977197819791980198119821983198419851986198719881989199019911992199319941995199619971998199920002001200220032004200520062007200820092010201120122013201420152016201720182019202020212022202320242025202620272028202920302031203220332034203520362037203820392040204120422043204420452046204720482049205020512052205320542055205620572058205920602061206220632064206520662067206820692070207120722073207420752076207720782079208020812082208320842085208620872088208920902091209220932094209520962097209820992100210121022103210421052106210721082109211021112112211321142115211621172118211921202121212221232124212521262127212821292130213121322133213421352136213721382139214021412142214321442145214621472148214921502151215221532154215521562157215821592160216121622163216421652166216721682169217021712172217321742175217621772178217921802181218221832184218521862187218821892190219121922193219421952196219721982199220022012202220322042205220622072208220922102211221222132214221522162217221822192220222122222223222422252226222722282229223022312232223322342235223622372238223922402241224222432244224522462247224822492250225122522253225422552256225722582259226022612262226322642265226622672268226922702271227222732274227522762277227822792280228122822283228422852286228722882289229022912292229322942295229622972298229923002301230223032304230523062307230823092310231123122313231423152316231723182319232023212322232323242325232623272328232923302331233223332334233523362337233823392340234123422343234423452346234723482349235023512352235323542355235623572358235923602361236223632364236523662367236823692370237123722373237423752376237723782379238023812382238323842385238623872388238923902391239223932394239523962397239823992400240124022403240424052406240724082409241024112412241324142415241624172418241924202421242224232424242524262427242824292430243124322433243424352436243724382439244024412442244324442445244624472448244924502451245224532454245524562457245824592460246124622463246424652466246724682469247024712472247324742475247624772478247924802481248224832484248524862487248824892490249124922493249424952496249724982499250025012502250325042505250625072508250925102511251225132514251525162517251825192520252125222523252425252526252725282529253025312532253325342535253625372538253925402541254225432544254525462547254825492550255125522553255425552556255725582559256025612562256325642565256625672568256925702571257225732574257525762577257825792580258125822583258425852586258725882589259025912592259325942595259625972598259926002601260226032604260526062607260826092610261126122613261426152616261726182619262026212622262326242625262626272628262926302631263226332634263526362637263826392640264126422643264426452646264726482649265026512652265326542655265626572658265926602661266226632664266526662667266826692670267126722673267426752676267726782679268026812682268326842685268626872688268926902691269226932694269526962697269826992700270127022703270427052706270727082709271027112712271327142715271627172718271927202721272227232724272527262727272827292730273127322733273427352736273727382739274027412742274327442745274627472748274927502751275227532754275527562757275827592760276127622763276427652766276727682769277027712772277327742775277627772778277927802781278227832784278527862787278827892790279127922793279427952796279727982799280028012802280328042805280628072808280928102811281228132814281528162817281828192820282128222823282428252826282728282829283028312832283328342835283628372838283928402841284228432844284528462847284828492850285128522853285428552856285728582859286028612862286328642865286628672868286928702871287228732874287528762877287828792880288128822883288428852886288728882889289028912892289328942895289628972898289929002901290229032904290529062907290829092910291129122913291429152916291729182919292029212922292329242925292629272928292929302931293229332934293529362937293829392940294129422943294429452946294729482949295029512952295329542955295629572958295929602961296229632964296529662967296829692970297129722973297429752976297729782979298029812982298329842985298629872988298929902991299229932994299529962997299829993000300130023003300430053006300730083009301030113012301330143015301630173018301930203021302230233024302530263027302830293030303130323033303430353036303730383039304030413042304330443045304630473048304930503051305230533054305530563057305830593060306130623063306430653066306730683069307030713072307330743075307630773078307930803081308230833084308530863087308830893090309130923093309430953096309730983099310031013102310331043105310631073108310931103111311231133114311531163117311831193120312131223123312431253126312731283129313031313132313331343135313631373138313931403141314231433144314531463147314831493150315131523153315431553156315731583159316031613162316331643165316631673168316931703171317231733174317531763177317831793180318131823183318431853186318731883189319031913192319331943195319631973198319932003201320232033204320532063207320832093210321132123213321432153216321732183219322032213222322332243225322632273228322932303231323232333234323532363237323832393240324132423243324432453246324732483249325032513252325332543255325632573258325932603261326232633264326532663267326832693270327132723273327432753276327732783279328032813282328332843285328632873288328932903291329232933294329532963297329832993300330133023303330433053306330733083309331033113312331333143315331633173318331933203321332233233324332533263327332833293330333133323333333433353336333733383339334033413342334333443345334633473348334933503351335233533354335533563357335833593360336133623363336433653366336733683369337033713372337333743375337633773378337933803381338233833384338533863387338833893390339133923393339433953396339733983399340034013402340334043405340634073408340934103411341234133414341534163417341834193420342134223423342434253426342734283429343034313432343334343435343634373438343934403441344234433444344534463447344834493450345134523453345434553456345734583459346034613462346334643465346634673468346934703471347234733474347534763477347834793480348134823483348434853486348734883489349034913492349334943495349634973498349935003501350235033504350535063507350835093510351135123513351435153516351735183519352035213522352335243525352635273528352935303531353235333534353535363537353835393540354135423543354435453546354735483549355035513552355335543555355635573558355935603561356235633564356535663567356835693570357135723573357435753576357735783579358035813582358335843585358635873588358935903591359235933594359535963597359835993600360136023603360436053606360736083609361036113612361336143615361636173618361936203621362236233624362536263627362836293630363136323633363436353636363736383639364036413642364336443645364636473648364936503651365236533654365536563657365836593660366136623663366436653666366736683669367036713672367336743675367636773678367936803681368236833684368536863687368836893690369136923693369436953696369736983699370037013702370337043705370637073708370937103711371237133714371537163717371837193720372137223723372437253726372737283729373037313732373337343735373637373738373937403741374237433744374537463747374837493750375137523753375437553756375737583759376037613762376337643765376637673768376937703771377237733774377537763777377837793780378137823783378437853786378737883789379037913792379337943795379637973798379938003801380238033804380538063807380838093810381138123813381438153816381738183819382038213822382338243825382638273828382938303831383238333834383538363837383838393840384138423843384438453846384738483849385038513852385338543855385638573858385938603861386238633864386538663867386838693870387138723873387438753876387738783879388038813882388338843885388638873888388938903891389238933894389538963897389838993900390139023903390439053906390739083909391039113912391339143915391639173918391939203921392239233924392539263927392839293930393139323933393439353936393739383939394039413942394339443945394639473948394939503951395239533954395539563957395839593960396139623963396439653966396739683969397039713972397339743975397639773978397939803981398239833984398539863987398839893990399139923993399439953996399739983999400040014002400340044005400640074008400940104011401240134014401540164017401840194020402140224023402440254026402740284029403040314032403340344035403640374038403940404041404240434044404540464047404840494050405140524053405440554056405740584059406040614062406340644065406640674068406940704071407240734074407540764077407840794080408140824083408440854086408740884089409040914092409340944095409640974098409941004101410241034104410541064107410841094110411141124113411441154116411741184119412041214122412341244125412641274128412941304131413241334134413541364137413841394140414141424143414441454146414741484149415041514152415341544155415641574158415941604161416241634164416541664167416841694170417141724173417441754176417741784179418041814182418341844185418641874188418941904191419241934194419541964197419841994200420142024203420442054206420742084209421042114212421342144215421642174218421942204221422242234224422542264227422842294230423142324233423442354236423742384239424042414242424342444245424642474248424942504251425242534254425542564257425842594260426142624263426442654266426742684269427042714272427342744275427642774278427942804281428242834284428542864287428842894290429142924293429442954296429742984299430043014302430343044305430643074308430943104311431243134314431543164317431843194320432143224323432443254326432743284329433043314332433343344335433643374338433943404341434243434344434543464347434843494350435143524353435443554356435743584359436043614362436343644365436643674368436943704371437243734374437543764377437843794380438143824383438443854386438743884389439043914392439343944395439643974398439944004401440244034404440544064407440844094410441144124413441444154416441744184419442044214422442344244425442644274428442944304431443244334434443544364437443844394440444144424443444444454446444744484449445044514452445344544455445644574458445944604461446244634464446544664467446844694470447144724473447444754476447744784479448044814482448344844485448644874488448944904491449244934494449544964497449844994500450145024503450445054506450745084509451045114512451345144515451645174518451945204521452245234524452545264527452845294530453145324533453445354536453745384539454045414542454345444545454645474548454945504551455245534554455545564557455845594560456145624563456445654566456745684569457045714572457345744575457645774578457945804581458245834584458545864587458845894590459145924593459445954596459745984599460046014602460346044605460646074608460946104611461246134614461546164617461846194620462146224623462446254626462746284629463046314632463346344635463646374638463946404641464246434644464546464647464846494650465146524653465446554656465746584659466046614662466346644665466646674668466946704671467246734674467546764677467846794680468146824683468446854686468746884689469046914692469346944695469646974698469947004701470247034704470547064707470847094710471147124713471447154716471747184719472047214722472347244725472647274728472947304731473247334734473547364737473847394740474147424743474447454746474747484749475047514752475347544755475647574758475947604761476247634764476547664767476847694770477147724773477447754776477747784779478047814782478347844785478647874788478947904791479247934794479547964797479847994800480148024803480448054806480748084809481048114812481348144815481648174818481948204821482248234824482548264827482848294830483148324833483448354836483748384839484048414842484348444845484648474848484948504851485248534854485548564857485848594860486148624863486448654866486748684869487048714872487348744875487648774878487948804881488248834884488548864887488848894890489148924893489448954896489748984899490049014902490349044905490649074908490949104911491249134914491549164917491849194920492149224923492449254926492749284929493049314932493349344935493649374938493949404941494249434944494549464947494849494950495149524953495449554956495749584959496049614962496349644965496649674968496949704971497249734974497549764977497849794980498149824983498449854986498749884989499049914992499349944995499649974998499950005001500250035004500550065007500850095010501150125013501450155016501750185019502050215022502350245025502650275028502950305031503250335034503550365037503850395040504150425043504450455046504750485049505050515052505350545055505650575058505950605061506250635064506550665067506850695070507150725073507450755076507750785079508050815082508350845085508650875088508950905091509250935094509550965097509850995100510151025103510451055106510751085109511051115112511351145115511651175118511951205121512251235124512551265127512851295130513151325133513451355136513751385139514051415142514351445145514651475148514951505151515251535154515551565157515851595160516151625163516451655166516751685169517051715172517351745175517651775178517951805181518251835184518551865187518851895190519151925193519451955196519751985199520052015202520352045205520652075208520952105211521252135214521552165217521852195220522152225223522452255226522752285229523052315232523352345235523652375238523952405241524252435244524552465247524852495250525152525253525452555256525752585259526052615262526352645265526652675268526952705271527252735274527552765277527852795280528152825283528452855286528752885289529052915292529352945295529652975298529953005301530253035304530553065307530853095310531153125313531453155316531753185319532053215322532353245325532653275328532953305331533253335334533553365337533853395340534153425343534453455346534753485349535053515352535353545355535653575358535953605361536253635364536553665367536853695370537153725373537453755376537753785379538053815382538353845385538653875388538953905391539253935394539553965397539853995400540154025403540454055406540754085409541054115412541354145415541654175418541954205421542254235424542554265427542854295430543154325433543454355436543754385439544054415442544354445445544654475448544954505451545254535454545554565457545854595460546154625463546454655466546754685469547054715472547354745475547654775478547954805481548254835484548554865487548854895490549154925493549454955496549754985499550055015502550355045505550655075508550955105511551255135514551555165517551855195520552155225523552455255526552755285529553055315532553355345535553655375538553955405541554255435544554555465547554855495550555155525553555455555556555755585559556055615562556355645565556655675568556955705571557255735574557555765577557855795580558155825583558455855586558755885589559055915592559355945595559655975598559956005601560256035604560556065607560856095610561156125613561456155616561756185619562056215622562356245625562656275628562956305631563256335634563556365637563856395640564156425643564456455646564756485649565056515652565356545655565656575658565956605661566256635664566556665667566856695670567156725673567456755676567756785679568056815682568356845685568656875688568956905691569256935694569556965697569856995700570157025703570457055706570757085709571057115712571357145715571657175718571957205721572257235724572557265727572857295730573157325733573457355736573757385739574057415742574357445745574657475748574957505751575257535754575557565757575857595760576157625763576457655766576757685769577057715772577357745775577657775778577957805781578257835784578557865787578857895790579157925793579457955796579757985799580058015802580358045805580658075808580958105811581258135814581558165817581858195820582158225823582458255826582758285829583058315832583358345835583658375838583958405841584258435844584558465847584858495850585158525853585458555856585758585859586058615862586358645865586658675868586958705871587258735874587558765877587858795880588158825883588458855886588758885889589058915892589358945895589658975898589959005901590259035904590559065907590859095910591159125913591459155916591759185919592059215922592359245925592659275928592959305931593259335934593559365937593859395940594159425943594459455946594759485949595059515952595359545955595659575958595959605961596259635964596559665967596859695970597159725973597459755976597759785979598059815982598359845985598659875988598959905991599259935994599559965997599859996000600160026003600460056006600760086009601060116012601360146015601660176018601960206021602260236024602560266027602860296030603160326033603460356036603760386039604060416042604360446045604660476048604960506051605260536054605560566057605860596060606160626063606460656066606760686069607060716072607360746075607660776078607960806081608260836084608560866087608860896090609160926093609460956096609760986099610061016102610361046105610661076108610961106111611261136114611561166117611861196120612161226123612461256126612761286129613061316132613361346135613661376138613961406141614261436144614561466147614861496150615161526153615461556156615761586159616061616162616361646165616661676168616961706171617261736174617561766177617861796180618161826183618461856186618761886189619061916192619361946195619661976198619962006201620262036204620562066207620862096210621162126213621462156216621762186219622062216222622362246225622662276228622962306231623262336234623562366237623862396240624162426243624462456246624762486249625062516252625362546255625662576258625962606261626262636264626562666267626862696270627162726273627462756276627762786279628062816282628362846285628662876288628962906291629262936294629562966297629862996300630163026303630463056306630763086309631063116312631363146315631663176318631963206321632263236324632563266327632863296330633163326333633463356336633763386339634063416342634363446345634663476348634963506351635263536354635563566357635863596360636163626363636463656366636763686369637063716372637363746375637663776378637963806381638263836384638563866387638863896390639163926393639463956396639763986399640064016402640364046405640664076408640964106411641264136414641564166417641864196420642164226423642464256426642764286429643064316432643364346435643664376438643964406441644264436444644564466447644864496450645164526453645464556456645764586459646064616462646364646465646664676468646964706471647264736474647564766477647864796480648164826483648464856486648764886489649064916492649364946495649664976498649965006501650265036504650565066507650865096510651165126513651465156516651765186519652065216522652365246525652665276528652965306531653265336534653565366537653865396540654165426543654465456546654765486549655065516552655365546555655665576558655965606561656265636564656565666567656865696570657165726573657465756576657765786579658065816582658365846585658665876588658965906591659265936594659565966597659865996600660166026603660466056606660766086609661066116612661366146615661666176618661966206621662266236624662566266627662866296630663166326633663466356636663766386639664066416642664366446645664666476648664966506651665266536654665566566657665866596660666166626663666466656666666766686669667066716672667366746675667666776678667966806681668266836684668566866687668866896690669166926693669466956696669766986699670067016702670367046705670667076708670967106711671267136714671567166717671867196720672167226723672467256726672767286729673067316732673367346735673667376738673967406741674267436744674567466747674867496750675167526753675467556756675767586759676067616762676367646765676667676768676967706771677267736774677567766777677867796780678167826783678467856786678767886789679067916792679367946795679667976798679968006801680268036804680568066807680868096810681168126813681468156816681768186819682068216822682368246825682668276828682968306831683268336834683568366837683868396840684168426843684468456846684768486849685068516852685368546855685668576858685968606861686268636864686568666867686868696870687168726873687468756876687768786879688068816882688368846885688668876888688968906891689268936894689568966897689868996900690169026903690469056906690769086909691069116912691369146915691669176918691969206921692269236924692569266927692869296930693169326933693469356936693769386939694069416942694369446945694669476948694969506951695269536954695569566957695869596960696169626963696469656966696769686969697069716972697369746975697669776978697969806981698269836984698569866987698869896990699169926993699469956996699769986999700070017002700370047005700670077008700970107011701270137014701570167017701870197020702170227023702470257026702770287029703070317032703370347035703670377038703970407041704270437044704570467047704870497050705170527053705470557056705770587059706070617062706370647065706670677068706970707071707270737074707570767077707870797080708170827083708470857086708770887089709070917092709370947095709670977098709971007101710271037104710571067107710871097110711171127113711471157116711771187119712071217122712371247125712671277128712971307131713271337134713571367137713871397140714171427143714471457146714771487149715071517152715371547155715671577158715971607161716271637164716571667167716871697170717171727173717471757176717771787179718071817182718371847185718671877188718971907191719271937194719571967197719871997200720172027203720472057206720772087209721072117212721372147215721672177218721972207221722272237224722572267227722872297230723172327233723472357236723772387239724072417242724372447245724672477248724972507251725272537254725572567257725872597260726172627263726472657266726772687269727072717272727372747275727672777278727972807281728272837284728572867287728872897290729172927293729472957296729772987299730073017302730373047305730673077308730973107311731273137314731573167317731873197320732173227323732473257326732773287329733073317332733373347335733673377338733973407341734273437344734573467347734873497350735173527353735473557356735773587359736073617362736373647365736673677368736973707371737273737374737573767377737873797380738173827383738473857386738773887389739073917392739373947395739673977398739974007401740274037404740574067407740874097410741174127413741474157416741774187419742074217422742374247425742674277428742974307431743274337434743574367437743874397440744174427443744474457446744774487449745074517452745374547455745674577458745974607461746274637464746574667467746874697470747174727473747474757476747774787479748074817482748374847485748674877488748974907491749274937494749574967497749874997500750175027503750475057506750775087509751075117512751375147515751675177518751975207521752275237524752575267527752875297530753175327533753475357536753775387539754075417542754375447545754675477548754975507551755275537554755575567557755875597560756175627563756475657566756775687569757075717572757375747575757675777578757975807581758275837584758575867587758875897590759175927593759475957596759775987599760076017602760376047605760676077608760976107611761276137614761576167617761876197620762176227623762476257626762776287629763076317632763376347635763676377638763976407641764276437644764576467647764876497650765176527653765476557656765776587659766076617662766376647665766676677668766976707671767276737674767576767677767876797680768176827683768476857686768776887689769076917692769376947695769676977698769977007701770277037704770577067707770877097710771177127713771477157716771777187719772077217722772377247725772677277728772977307731773277337734773577367737773877397740774177427743774477457746774777487749775077517752775377547755775677577758775977607761776277637764776577667767776877697770777177727773777477757776777777787779778077817782778377847785778677877788778977907791779277937794779577967797779877997800780178027803780478057806780778087809781078117812781378147815781678177818781978207821782278237824782578267827782878297830783178327833783478357836783778387839784078417842784378447845784678477848784978507851785278537854785578567857785878597860786178627863786478657866786778687869787078717872787378747875787678777878787978807881788278837884788578867887788878897890789178927893789478957896789778987899790079017902790379047905790679077908790979107911791279137914791579167917791879197920792179227923792479257926792779287929793079317932793379347935793679377938793979407941794279437944794579467947794879497950795179527953795479557956795779587959796079617962796379647965796679677968796979707971797279737974797579767977797879797980798179827983798479857986798779887989799079917992799379947995799679977998799980008001800280038004800580068007800880098010801180128013801480158016801780188019802080218022802380248025802680278028802980308031803280338034803580368037803880398040804180428043804480458046804780488049805080518052805380548055805680578058805980608061806280638064806580668067806880698070807180728073807480758076807780788079808080818082808380848085808680878088808980908091809280938094809580968097809880998100810181028103810481058106810781088109811081118112811381148115811681178118811981208121812281238124812581268127812881298130813181328133813481358136813781388139814081418142814381448145814681478148814981508151815281538154815581568157815881598160816181628163816481658166816781688169817081718172817381748175817681778178817981808181818281838184818581868187818881898190819181928193819481958196819781988199820082018202820382048205820682078208820982108211821282138214821582168217821882198220822182228223822482258226822782288229823082318232823382348235823682378238823982408241824282438244824582468247824882498250825182528253825482558256825782588259826082618262826382648265826682678268826982708271827282738274827582768277827882798280828182828283828482858286828782888289829082918292829382948295829682978298829983008301830283038304830583068307830883098310831183128313831483158316831783188319832083218322832383248325832683278328832983308331833283338334833583368337833883398340834183428343834483458346834783488349835083518352835383548355835683578358835983608361836283638364836583668367836883698370837183728373837483758376837783788379838083818382838383848385838683878388838983908391839283938394839583968397839883998400840184028403840484058406840784088409841084118412841384148415841684178418841984208421842284238424842584268427842884298430843184328433843484358436843784388439844084418442844384448445844684478448844984508451845284538454845584568457845884598460846184628463846484658466846784688469847084718472847384748475847684778478847984808481848284838484848584868487848884898490849184928493849484958496849784988499850085018502850385048505850685078508850985108511851285138514851585168517851885198520852185228523852485258526852785288529853085318532853385348535853685378538853985408541854285438544854585468547854885498550855185528553855485558556855785588559856085618562856385648565856685678568856985708571857285738574857585768577857885798580858185828583858485858586858785888589859085918592859385948595859685978598859986008601860286038604860586068607860886098610861186128613861486158616861786188619862086218622862386248625862686278628862986308631863286338634863586368637863886398640864186428643864486458646864786488649865086518652865386548655865686578658865986608661866286638664866586668667866886698670867186728673867486758676867786788679868086818682868386848685868686878688868986908691869286938694869586968697869886998700870187028703870487058706870787088709871087118712871387148715871687178718871987208721872287238724872587268727872887298730873187328733873487358736873787388739874087418742874387448745874687478748874987508751875287538754875587568757875887598760876187628763876487658766876787688769877087718772877387748775877687778778877987808781878287838784878587868787878887898790879187928793879487958796879787988799880088018802880388048805880688078808880988108811881288138814881588168817881888198820882188228823882488258826882788288829883088318832883388348835883688378838883988408841884288438844884588468847884888498850885188528853885488558856885788588859886088618862886388648865886688678868886988708871887288738874887588768877887888798880888188828883888488858886888788888889889088918892889388948895889688978898889989008901890289038904890589068907890889098910891189128913891489158916891789188919892089218922892389248925892689278928892989308931893289338934893589368937893889398940894189428943894489458946894789488949895089518952895389548955895689578958895989608961896289638964896589668967896889698970897189728973897489758976897789788979898089818982898389848985898689878988898989908991899289938994899589968997899889999000900190029003900490059006900790089009901090119012901390149015901690179018901990209021902290239024902590269027902890299030903190329033903490359036903790389039904090419042904390449045904690479048904990509051905290539054905590569057905890599060906190629063906490659066906790689069907090719072907390749075907690779078907990809081908290839084908590869087908890899090909190929093909490959096909790989099910091019102910391049105910691079108910991109111911291139114911591169117911891199120912191229123912491259126912791289129913091319132913391349135913691379138913991409141914291439144914591469147914891499150915191529153915491559156915791589159916091619162916391649165916691679168916991709171917291739174917591769177917891799180918191829183918491859186918791889189919091919192919391949195919691979198919992009201920292039204920592069207920892099210921192129213921492159216921792189219922092219222922392249225922692279228922992309231923292339234923592369237923892399240924192429243924492459246924792489249925092519252925392549255925692579258925992609261926292639264926592669267926892699270927192729273927492759276927792789279928092819282928392849285928692879288928992909291929292939294929592969297929892999300930193029303930493059306930793089309931093119312931393149315931693179318931993209321932293239324932593269327932893299330933193329333933493359336933793389339934093419342934393449345934693479348934993509351935293539354935593569357935893599360936193629363936493659366936793689369937093719372937393749375937693779378937993809381938293839384938593869387938893899390939193929393939493959396939793989399940094019402940394049405940694079408940994109411941294139414941594169417941894199420942194229423942494259426942794289429943094319432943394349435943694379438943994409441944294439444944594469447944894499450945194529453945494559456945794589459946094619462946394649465946694679468946994709471947294739474947594769477947894799480948194829483948494859486948794889489949094919492949394949495949694979498949995009501950295039504950595069507950895099510951195129513951495159516951795189519952095219522952395249525952695279528952995309531953295339534953595369537953895399540954195429543954495459546954795489549955095519552955395549555955695579558955995609561956295639564956595669567956895699570957195729573957495759576957795789579958095819582958395849585958695879588958995909591959295939594959595969597959895999600960196029603960496059606960796089609961096119612961396149615961696179618961996209621962296239624962596269627962896299630963196329633963496359636963796389639964096419642964396449645964696479648964996509651965296539654965596569657965896599660966196629663966496659666966796689669967096719672967396749675967696779678967996809681968296839684968596869687968896899690969196929693969496959696969796989699970097019702970397049705970697079708970997109711971297139714971597169717971897199720972197229723972497259726972797289729973097319732973397349735973697379738973997409741974297439744974597469747974897499750975197529753975497559756975797589759976097619762976397649765976697679768976997709771977297739774977597769777977897799780978197829783978497859786978797889789979097919792979397949795979697979798979998009801980298039804980598069807980898099810981198129813981498159816981798189819982098219822982398249825982698279828982998309831983298339834983598369837983898399840984198429843984498459846984798489849985098519852985398549855985698579858985998609861986298639864986598669867986898699870987198729873987498759876987798789879988098819882988398849885988698879888988998909891989298939894989598969897989898999900990199029903990499059906990799089909991099119912991399149915991699179918991999209921992299239924992599269927992899299930993199329933993499359936993799389939994099419942994399449945994699479948994999509951995299539954995599569957995899599960996199629963996499659966996799689969997099719972997399749975997699779978997999809981998299839984998599869987998899899990999199929993999499959996999799989999100001000110002100031000410005100061000710008100091001010011100121001310014100151001610017100181001910020100211002210023100241002510026100271002810029100301003110032100331003410035100361003710038100391004010041100421004310044100451004610047100481004910050100511005210053100541005510056100571005810059100601006110062100631006410065100661006710068100691007010071100721007310074100751007610077100781007910080100811008210083100841008510086100871008810089100901009110092100931009410095100961009710098100991010010101101021010310104101051010610107101081010910110101111011210113101141011510116101171011810119101201012110122101231012410125101261012710128101291013010131101321013310134101351013610137101381013910140101411014210143101441014510146101471014810149101501015110152101531015410155101561015710158101591016010161101621016310164101651016610167101681016910170101711017210173101741017510176101771017810179101801018110182101831018410185101861018710188101891019010191101921019310194101951019610197101981019910200102011020210203102041020510206102071020810209102101021110212102131021410215102161021710218102191022010221102221022310224102251022610227102281022910230102311023210233102341023510236102371023810239102401024110242102431024410245102461024710248102491025010251102521025310254102551025610257102581025910260102611026210263102641026510266102671026810269102701027110272102731027410275102761027710278102791028010281102821028310284102851028610287102881028910290102911029210293102941029510296102971029810299103001030110302103031030410305103061030710308103091031010311103121031310314103151031610317103181031910320103211032210323103241032510326103271032810329103301033110332103331033410335103361033710338103391034010341103421034310344103451034610347103481034910350103511035210353103541035510356103571035810359103601036110362103631036410365103661036710368103691037010371103721037310374103751037610377103781037910380103811038210383103841038510386103871038810389103901039110392103931039410395103961039710398103991040010401104021040310404104051040610407104081040910410104111041210413104141041510416104171041810419104201042110422104231042410425104261042710428104291043010431104321043310434104351043610437104381043910440104411044210443104441044510446104471044810449104501045110452104531045410455104561045710458104591046010461104621046310464104651046610467104681046910470104711047210473104741047510476104771047810479104801048110482104831048410485104861048710488104891049010491104921049310494104951049610497104981049910500105011050210503105041050510506105071050810509105101051110512105131051410515105161051710518105191052010521105221052310524105251052610527105281052910530105311053210533105341053510536105371053810539105401054110542105431054410545105461054710548105491055010551105521055310554105551055610557105581055910560105611056210563105641056510566105671056810569105701057110572105731057410575105761057710578105791058010581105821058310584105851058610587105881058910590105911059210593105941059510596105971059810599106001060110602106031060410605106061060710608106091061010611106121061310614106151061610617106181061910620106211062210623106241062510626106271062810629106301063110632106331063410635106361063710638106391064010641106421064310644106451064610647106481064910650106511065210653106541065510656106571065810659106601066110662106631066410665106661066710668106691067010671106721067310674106751067610677106781067910680106811068210683106841068510686106871068810689106901069110692106931069410695106961069710698106991070010701107021070310704107051070610707107081070910710107111071210713107141071510716107171071810719107201072110722107231072410725107261072710728107291073010731107321073310734107351073610737107381073910740107411074210743107441074510746107471074810749107501075110752107531075410755107561075710758107591076010761107621076310764107651076610767107681076910770107711077210773107741077510776107771077810779107801078110782107831078410785107861078710788107891079010791107921079310794107951079610797107981079910800108011080210803108041080510806108071080810809108101081110812108131081410815108161081710818108191082010821108221082310824108251082610827108281082910830108311083210833108341083510836108371083810839108401084110842108431084410845108461084710848108491085010851108521085310854108551085610857108581085910860108611086210863108641086510866108671086810869108701087110872108731087410875108761087710878108791088010881108821088310884108851088610887108881088910890108911089210893108941089510896108971089810899109001090110902109031090410905109061090710908109091091010911109121091310914109151091610917109181091910920109211092210923109241092510926109271092810929109301093110932109331093410935109361093710938109391094010941109421094310944109451094610947109481094910950109511095210953109541095510956109571095810959109601096110962109631096410965109661096710968109691097010971109721097310974109751097610977109781097910980109811098210983109841098510986109871098810989109901099110992109931099410995109961099710998109991100011001110021100311004110051100611007110081100911010110111101211013110141101511016110171101811019110201102111022110231102411025110261102711028110291103011031110321103311034110351103611037110381103911040110411104211043110441104511046110471104811049110501105111052110531105411055110561105711058110591106011061110621106311064110651106611067110681106911070110711107211073110741107511076110771107811079110801108111082110831108411085110861108711088110891109011091110921109311094110951109611097110981109911100111011110211103111041110511106111071110811109111101111111112111131111411115111161111711118111191112011121111221112311124111251112611127111281112911130111311113211133111341113511136111371113811139111401114111142111431114411145111461114711148111491115011151111521115311154111551115611157111581115911160111611116211163111641116511166111671116811169111701117111172111731117411175111761117711178111791118011181111821118311184111851118611187111881118911190111911119211193111941119511196111971119811199112001120111202112031120411205112061120711208112091121011211112121121311214112151121611217112181121911220112211122211223112241122511226112271122811229112301123111232112331123411235112361123711238112391124011241112421124311244112451124611247112481124911250112511125211253112541125511256112571125811259112601126111262112631126411265112661126711268112691127011271112721127311274112751127611277112781127911280112811128211283112841128511286112871128811289112901129111292112931129411295112961129711298112991130011301113021130311304113051130611307113081130911310113111131211313113141131511316113171131811319113201132111322113231132411325113261132711328113291133011331113321133311334113351133611337113381133911340113411134211343113441134511346113471134811349113501135111352113531135411355113561135711358113591136011361113621136311364113651136611367113681136911370113711137211373113741137511376113771137811379113801138111382113831138411385113861138711388113891139011391113921139311394113951139611397113981139911400114011140211403114041140511406114071140811409114101141111412114131141411415114161141711418114191142011421114221142311424114251142611427114281142911430114311143211433114341143511436114371143811439114401144111442114431144411445114461144711448114491145011451114521145311454114551145611457114581145911460114611146211463114641146511466114671146811469114701147111472114731147411475114761147711478114791148011481114821148311484114851148611487114881148911490114911149211493114941149511496114971149811499115001150111502115031150411505115061150711508115091151011511115121151311514115151151611517115181151911520115211152211523115241152511526115271152811529115301153111532115331153411535115361153711538115391154011541115421154311544115451154611547115481154911550115511155211553115541155511556115571155811559115601156111562115631156411565115661156711568115691157011571115721157311574115751157611577115781157911580115811158211583115841158511586115871158811589115901159111592115931159411595115961159711598115991160011601116021160311604116051160611607116081160911610116111161211613116141161511616116171161811619116201162111622116231162411625116261162711628116291163011631116321163311634116351163611637116381163911640116411164211643116441164511646116471164811649116501165111652116531165411655116561165711658116591166011661116621166311664116651166611667116681166911670116711167211673116741167511676116771167811679116801168111682116831168411685116861168711688116891169011691116921169311694116951169611697116981169911700117011170211703117041170511706117071170811709117101171111712117131171411715117161171711718117191172011721117221172311724117251172611727117281172911730117311173211733117341173511736117371173811739117401174111742117431174411745117461174711748117491175011751117521175311754117551175611757117581175911760117611176211763117641176511766117671176811769117701177111772117731177411775117761177711778117791178011781117821178311784117851178611787117881178911790117911179211793117941179511796117971179811799118001180111802118031180411805118061180711808118091181011811118121181311814118151181611817118181181911820118211182211823118241182511826118271182811829118301183111832118331183411835118361183711838118391184011841118421184311844118451184611847118481184911850118511185211853118541185511856118571185811859118601186111862118631186411865118661186711868118691187011871118721187311874118751187611877118781187911880118811188211883118841188511886118871188811889118901189111892118931189411895118961189711898118991190011901119021190311904119051190611907119081190911910119111191211913119141191511916119171191811919119201192111922119231192411925119261192711928119291193011931119321193311934119351193611937119381193911940119411194211943119441194511946119471194811949119501195111952119531195411955119561195711958119591196011961119621196311964119651196611967119681196911970119711197211973119741197511976119771197811979119801198111982119831198411985119861198711988119891199011991119921199311994119951199611997119981199912000120011200212003120041200512006120071200812009120101201112012120131201412015120161201712018120191202012021120221202312024120251202612027120281202912030120311203212033120341203512036120371203812039120401204112042120431204412045120461204712048120491205012051120521205312054120551205612057120581205912060120611206212063120641206512066120671206812069120701207112072120731207412075120761207712078120791208012081120821208312084120851208612087120881208912090120911209212093120941209512096120971209812099121001210112102121031210412105121061210712108121091211012111121121211312114121151211612117121181211912120121211212212123121241212512126121271212812129121301213112132121331213412135121361213712138121391214012141121421214312144121451214612147121481214912150121511215212153121541215512156121571215812159121601216112162121631216412165121661216712168121691217012171121721217312174121751217612177121781217912180121811218212183121841218512186121871218812189121901219112192121931219412195121961219712198121991220012201122021220312204122051220612207122081220912210122111221212213122141221512216122171221812219122201222112222122231222412225122261222712228122291223012231122321223312234122351223612237122381223912240122411224212243122441224512246122471224812249122501225112252122531225412255122561225712258122591226012261122621226312264122651226612267122681226912270122711227212273122741227512276122771227812279122801228112282122831228412285122861228712288122891229012291122921229312294122951229612297122981229912300123011230212303123041230512306123071230812309123101231112312123131231412315123161231712318123191232012321123221232312324123251232612327123281232912330123311233212333123341233512336123371233812339123401234112342123431234412345123461234712348123491235012351123521235312354123551235612357123581235912360123611236212363123641236512366123671236812369123701237112372123731237412375123761237712378123791238012381123821238312384123851238612387123881238912390123911239212393123941239512396123971239812399124001240112402124031240412405124061240712408124091241012411124121241312414124151241612417124181241912420124211242212423124241242512426124271242812429124301243112432124331243412435124361243712438124391244012441124421244312444124451244612447124481244912450124511245212453124541245512456124571245812459124601246112462124631246412465124661246712468124691247012471124721247312474124751247612477124781247912480124811248212483124841248512486124871248812489124901249112492124931249412495124961249712498124991250012501125021250312504125051250612507125081250912510125111251212513125141251512516125171251812519125201252112522125231252412525125261252712528125291253012531125321253312534125351253612537125381253912540125411254212543125441254512546125471254812549125501255112552125531255412555125561255712558125591256012561125621256312564125651256612567125681256912570125711257212573125741257512576125771257812579125801258112582125831258412585125861258712588125891259012591 |
- <!DOCTYPE HTML>
- <html lang="en" class="sidebar-visible no-js light">
- <head>
- <!-- Book generated using mdBook -->
- <meta charset="UTF-8">
- <title>Synapse</title>
- <meta name="robots" content="noindex" />
- <!-- Custom HTML head -->
- <meta content="text/html; charset=utf-8" http-equiv="Content-Type">
- <meta name="description" content="">
- <meta name="viewport" content="width=device-width, initial-scale=1">
- <meta name="theme-color" content="#ffffff" />
- <link rel="icon" href="favicon.svg">
- <link rel="shortcut icon" href="favicon.png">
- <link rel="stylesheet" href="css/variables.css">
- <link rel="stylesheet" href="css/general.css">
- <link rel="stylesheet" href="css/chrome.css">
- <link rel="stylesheet" href="css/print.css" media="print">
- <!-- Fonts -->
- <link rel="stylesheet" href="FontAwesome/css/font-awesome.css">
- <link rel="stylesheet" href="fonts/fonts.css">
- <!-- Highlight.js Stylesheets -->
- <link rel="stylesheet" href="highlight.css">
- <link rel="stylesheet" href="tomorrow-night.css">
- <link rel="stylesheet" href="ayu-highlight.css">
- <!-- Custom theme stylesheets -->
- <link rel="stylesheet" href="docs/website_files/table-of-contents.css">
- <link rel="stylesheet" href="docs/website_files/remove-nav-buttons.css">
- <link rel="stylesheet" href="docs/website_files/indent-section-headers.css">
- <link rel="stylesheet" href="docs/website_files/version-picker.css">
- </head>
- <body>
- <!-- Provide site root to javascript -->
- <script type="text/javascript">
- var path_to_root = "";
- var default_theme = window.matchMedia("(prefers-color-scheme: dark)").matches ? "navy" : "light";
- </script>
- <!-- Work around some values being stored in localStorage wrapped in quotes -->
- <script type="text/javascript">
- try {
- var theme = localStorage.getItem('mdbook-theme');
- var sidebar = localStorage.getItem('mdbook-sidebar');
- if (theme.startsWith('"') && theme.endsWith('"')) {
- localStorage.setItem('mdbook-theme', theme.slice(1, theme.length - 1));
- }
- if (sidebar.startsWith('"') && sidebar.endsWith('"')) {
- localStorage.setItem('mdbook-sidebar', sidebar.slice(1, sidebar.length - 1));
- }
- } catch (e) { }
- </script>
- <!-- Set the theme before any content is loaded, prevents flash -->
- <script type="text/javascript">
- var theme;
- try { theme = localStorage.getItem('mdbook-theme'); } catch(e) { }
- if (theme === null || theme === undefined) { theme = default_theme; }
- var html = document.querySelector('html');
- html.classList.remove('no-js')
- html.classList.remove('light')
- html.classList.add(theme);
- html.classList.add('js');
- </script>
- <!-- Hide / unhide sidebar before it is displayed -->
- <script type="text/javascript">
- var html = document.querySelector('html');
- var sidebar = 'hidden';
- if (document.body.clientWidth >= 1080) {
- try { sidebar = localStorage.getItem('mdbook-sidebar'); } catch(e) { }
- sidebar = sidebar || 'visible';
- }
- html.classList.remove('sidebar-visible');
- html.classList.add("sidebar-" + sidebar);
- </script>
- <nav id="sidebar" class="sidebar" aria-label="Table of contents">
- <div class="sidebar-scrollbox">
- <ol class="chapter"><li class="chapter-item expanded affix "><li class="part-title">Introduction</li><li class="chapter-item expanded "><a href="welcome_and_overview.html">Welcome and Overview</a></li><li class="chapter-item expanded affix "><li class="part-title">Setup</li><li class="chapter-item expanded "><a href="setup/installation.html">Installation</a></li><li class="chapter-item expanded "><a href="postgres.html">Using Postgres</a></li><li class="chapter-item expanded "><a href="reverse_proxy.html">Configuring a Reverse Proxy</a></li><li class="chapter-item expanded "><a href="turn-howto.html">Configuring a Turn Server</a></li><li class="chapter-item expanded "><a href="delegate.html">Delegation</a></li><li class="chapter-item expanded affix "><li class="part-title">Upgrading</li><li class="chapter-item expanded "><a href="upgrade.html">Upgrading between Synapse Versions</a></li><li class="chapter-item expanded "><a href="MSC1711_certificates_FAQ.html">Upgrading from pre-Synapse 1.0</a></li><li class="chapter-item expanded affix "><li class="part-title">Usage</li><li class="chapter-item expanded "><a href="federate.html">Federation</a></li><li class="chapter-item expanded "><a href="usage/configuration/index.html">Configuration</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="usage/configuration/homeserver_sample_config.html">Homeserver Sample Config File</a></li><li class="chapter-item expanded "><a href="usage/configuration/logging_sample_config.html">Logging Sample Config File</a></li><li class="chapter-item expanded "><a href="structured_logging.html">Structured Logging</a></li><li class="chapter-item expanded "><a href="usage/configuration/user_authentication/index.html">User Authentication</a></li><li><ol class="section"><li class="chapter-item expanded "><div>Single-Sign On</div></li><li><ol class="section"><li class="chapter-item expanded "><a href="openid.html">OpenID Connect</a></li><li class="chapter-item expanded "><div>SAML</div></li><li class="chapter-item expanded "><div>CAS</div></li><li class="chapter-item expanded "><a href="sso_mapping_providers.html">SSO Mapping Providers</a></li></ol></li><li class="chapter-item expanded "><a href="password_auth_providers.html">Password Auth Providers</a></li><li class="chapter-item expanded "><a href="jwt.html">JSON Web Tokens</a></li></ol></li><li class="chapter-item expanded "><a href="CAPTCHA_SETUP.html">Registration Captcha</a></li><li class="chapter-item expanded "><a href="application_services.html">Application Services</a></li><li class="chapter-item expanded "><a href="server_notices.html">Server Notices</a></li><li class="chapter-item expanded "><a href="consent_tracking.html">Consent Tracking</a></li><li class="chapter-item expanded "><a href="url_previews.html">URL Previews</a></li><li class="chapter-item expanded "><a href="user_directory.html">User Directory</a></li><li class="chapter-item expanded "><a href="message_retention_policies.html">Message Retention Policies</a></li><li class="chapter-item expanded "><a href="modules.html">Pluggable Modules</a></li><li><ol class="section"><li class="chapter-item expanded "><div>Third Party Rules</div></li><li class="chapter-item expanded "><a href="spam_checker.html">Spam Checker</a></li><li class="chapter-item expanded "><a href="presence_router_module.html">Presence Router</a></li><li class="chapter-item expanded "><div>Media Storage Providers</div></li></ol></li><li class="chapter-item expanded "><a href="workers.html">Workers</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="synctl_workers.html">Using synctl with Workers</a></li><li class="chapter-item expanded "><a href="systemd-with-workers/index.html">Systemd</a></li></ol></li></ol></li><li class="chapter-item expanded "><a href="usage/administration/index.html">Administration</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="usage/administration/admin_api/index.html">Admin API</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="admin_api/account_validity.html">Account Validity</a></li><li class="chapter-item expanded "><a href="admin_api/delete_group.html">Delete Group</a></li><li class="chapter-item expanded "><a href="admin_api/event_reports.html">Event Reports</a></li><li class="chapter-item expanded "><a href="admin_api/media_admin_api.html">Media</a></li><li class="chapter-item expanded "><a href="admin_api/purge_history_api.html">Purge History</a></li><li class="chapter-item expanded "><a href="admin_api/purge_room.html">Purge Rooms</a></li><li class="chapter-item expanded "><a href="admin_api/register_api.html">Register Users</a></li><li class="chapter-item expanded "><a href="admin_api/room_membership.html">Manipulate Room Membership</a></li><li class="chapter-item expanded "><a href="admin_api/rooms.html">Rooms</a></li><li class="chapter-item expanded "><a href="admin_api/server_notices.html">Server Notices</a></li><li class="chapter-item expanded "><a href="admin_api/shutdown_room.html">Shutdown Room</a></li><li class="chapter-item expanded "><a href="admin_api/statistics.html">Statistics</a></li><li class="chapter-item expanded "><a href="admin_api/user_admin_api.html">Users</a></li><li class="chapter-item expanded "><a href="admin_api/version_api.html">Server Version</a></li></ol></li><li class="chapter-item expanded "><a href="manhole.html">Manhole</a></li><li class="chapter-item expanded "><a href="metrics-howto.html">Monitoring</a></li><li class="chapter-item expanded "><a href="usage/administration/request_log.html">Request log format</a></li><li class="chapter-item expanded "><div>Scripts</div></li></ol></li><li class="chapter-item expanded "><li class="part-title">Development</li><li class="chapter-item expanded "><a href="development/contributing_guide.html">Contributing Guide</a></li><li class="chapter-item expanded "><a href="code_style.html">Code Style</a></li><li class="chapter-item expanded "><a href="dev/git.html">Git Usage</a></li><li class="chapter-item expanded "><div>Testing</div></li><li class="chapter-item expanded "><a href="opentracing.html">OpenTracing</a></li><li class="chapter-item expanded "><a href="development/database_schema.html">Database Schemas</a></li><li class="chapter-item expanded "><div>Synapse Architecture</div></li><li><ol class="section"><li class="chapter-item expanded "><a href="log_contexts.html">Log Contexts</a></li><li class="chapter-item expanded "><a href="replication.html">Replication</a></li><li class="chapter-item expanded "><a href="tcp_replication.html">TCP Replication</a></li></ol></li><li class="chapter-item expanded "><a href="development/internal_documentation/index.html">Internal Documentation</a></li><li><ol class="section"><li class="chapter-item expanded "><div>Single Sign-On</div></li><li><ol class="section"><li class="chapter-item expanded "><a href="dev/saml.html">SAML</a></li><li class="chapter-item expanded "><a href="dev/cas.html">CAS</a></li></ol></li><li class="chapter-item expanded "><div>State Resolution</div></li><li><ol class="section"><li class="chapter-item expanded "><a href="auth_chain_difference_algorithm.html">The Auth Chain Difference Algorithm</a></li></ol></li><li class="chapter-item expanded "><a href="media_repository.html">Media Repository</a></li><li class="chapter-item expanded "><a href="room_and_user_statistics.html">Room and User Statistics</a></li></ol></li><li class="chapter-item expanded "><div>Scripts</div></li><li class="chapter-item expanded affix "><li class="part-title">Other</li><li class="chapter-item expanded "><a href="deprecation_policy.html">Dependency Deprecation Policy</a></li></ol>
- </div>
- <div id="sidebar-resize-handle" class="sidebar-resize-handle"></div>
- </nav>
- <div id="page-wrapper" class="page-wrapper">
- <div class="page">
- <div id="menu-bar-hover-placeholder"></div>
- <div id="menu-bar" class="menu-bar sticky bordered">
- <div class="left-buttons">
- <button id="sidebar-toggle" class="icon-button" type="button" title="Toggle Table of Contents" aria-label="Toggle Table of Contents" aria-controls="sidebar">
- <i class="fa fa-bars"></i>
- </button>
- <button id="theme-toggle" class="icon-button" type="button" title="Change theme" aria-label="Change theme" aria-haspopup="true" aria-expanded="false" aria-controls="theme-list">
- <i class="fa fa-paint-brush"></i>
- </button>
- <ul id="theme-list" class="theme-popup" aria-label="Themes" role="menu">
- <li role="none"><button role="menuitem" class="theme" id="light">Light (default)</button></li>
- <li role="none"><button role="menuitem" class="theme" id="rust">Rust</button></li>
- <li role="none"><button role="menuitem" class="theme" id="coal">Coal</button></li>
- <li role="none"><button role="menuitem" class="theme" id="navy">Navy</button></li>
- <li role="none"><button role="menuitem" class="theme" id="ayu">Ayu</button></li>
- </ul>
- <button id="search-toggle" class="icon-button" type="button" title="Search. (Shortkey: s)" aria-label="Toggle Searchbar" aria-expanded="false" aria-keyshortcuts="S" aria-controls="searchbar">
- <i class="fa fa-search"></i>
- </button>
- <div class="version-picker">
- <div class="dropdown">
- <div class="select">
- <span></span>
- <i class="fa fa-chevron-down"></i>
- </div>
- <input type="hidden" name="version">
- <ul class="dropdown-menu">
- <!-- Versions will be added dynamically in version-picker.js -->
- </ul>
- </div>
- </div>
- </div>
- <h1 class="menu-title">Synapse</h1>
- <div class="right-buttons">
- <a href="print.html" title="Print this book" aria-label="Print this book">
- <i id="print-button" class="fa fa-print"></i>
- </a>
- <a href="https://github.com/matrix-org/synapse" title="Git repository" aria-label="Git repository">
- <i id="git-repository-button" class="fa fa-github"></i>
- </a>
- </div>
- </div>
- <div id="search-wrapper" class="hidden">
- <form id="searchbar-outer" class="searchbar-outer">
- <input type="search" id="searchbar" name="searchbar" placeholder="Search this book ..." aria-controls="searchresults-outer" aria-describedby="searchresults-header">
- </form>
- <div id="searchresults-outer" class="searchresults-outer hidden">
- <div id="searchresults-header" class="searchresults-header"></div>
- <ul id="searchresults">
- </ul>
- </div>
- </div>
- <!-- Apply ARIA attributes after the sidebar and the sidebar toggle button are added to the DOM -->
- <script type="text/javascript">
- document.getElementById('sidebar-toggle').setAttribute('aria-expanded', sidebar === 'visible');
- document.getElementById('sidebar').setAttribute('aria-hidden', sidebar !== 'visible');
- Array.from(document.querySelectorAll('#sidebar a')).forEach(function(link) {
- link.setAttribute('tabIndex', sidebar === 'visible' ? 0 : -1);
- });
- </script>
- <div id="content" class="content">
- <main>
- <!-- Page table of contents -->
- <div class="sidetoc">
- <nav class="pagetoc"></nav>
- </div>
- <div style="break-before: page; page-break-before: always;"></div><h1 id="introduction"><a class="header" href="#introduction">Introduction</a></h1>
- <p>Welcome to the documentation repository for Synapse, the reference
- <a href="https://matrix.org">Matrix</a> homeserver implementation.</p>
- <div style="break-before: page; page-break-before: always;"></div><h1 id="installation-instructions"><a class="header" href="#installation-instructions">Installation Instructions</a></h1>
- <p>There are 3 steps to follow under <strong>Installation Instructions</strong>.</p>
- <ul>
- <li><a href="setup/installation.html#installation-instructions">Installation Instructions</a>
- <ul>
- <li><a href="setup/installation.html#choosing-your-server-name">Choosing your server name</a></li>
- <li><a href="setup/installation.html#installing-synapse">Installing Synapse</a>
- <ul>
- <li><a href="setup/installation.html#installing-from-source">Installing from source</a>
- <ul>
- <li><a href="setup/installation.html#platform-specific-prerequisites">Platform-specific prerequisites</a>
- <ul>
- <li><a href="setup/installation.html#debianubunturaspbian">Debian/Ubuntu/Raspbian</a></li>
- <li><a href="setup/installation.html#archlinux">ArchLinux</a></li>
- <li><a href="setup/installation.html#centosfedora">CentOS/Fedora</a></li>
- <li><a href="setup/installation.html#macos">macOS</a></li>
- <li><a href="setup/installation.html#opensuse">OpenSUSE</a></li>
- <li><a href="setup/installation.html#openbsd">OpenBSD</a></li>
- <li><a href="setup/installation.html#windows">Windows</a></li>
- </ul>
- </li>
- </ul>
- </li>
- <li><a href="setup/installation.html#prebuilt-packages">Prebuilt packages</a>
- <ul>
- <li><a href="setup/installation.html#docker-images-and-ansible-playbooks">Docker images and Ansible playbooks</a></li>
- <li><a href="setup/installation.html#debianubuntu">Debian/Ubuntu</a>
- <ul>
- <li><a href="setup/installation.html#matrixorg-packages">Matrix.org packages</a></li>
- <li><a href="setup/installation.html#downstream-debian-packages">Downstream Debian packages</a></li>
- <li><a href="setup/installation.html#downstream-ubuntu-packages">Downstream Ubuntu packages</a></li>
- </ul>
- </li>
- <li><a href="setup/installation.html#fedora">Fedora</a></li>
- <li><a href="setup/installation.html#opensuse-1">OpenSUSE</a></li>
- <li><a href="setup/installation.html#suse-linux-enterprise-server">SUSE Linux Enterprise Server</a></li>
- <li><a href="setup/installation.html#archlinux-1">ArchLinux</a></li>
- <li><a href="setup/installation.html#void-linux">Void Linux</a></li>
- <li><a href="setup/installation.html#freebsd">FreeBSD</a></li>
- <li><a href="setup/installation.html#openbsd-1">OpenBSD</a></li>
- <li><a href="setup/installation.html#nixos">NixOS</a></li>
- </ul>
- </li>
- </ul>
- </li>
- <li><a href="setup/installation.html#setting-up-synapse">Setting up Synapse</a>
- <ul>
- <li><a href="setup/installation.html#using-postgresql">Using PostgreSQL</a></li>
- <li><a href="setup/installation.html#tls-certificates">TLS certificates</a></li>
- <li><a href="setup/installation.html#client-well-known-uri">Client Well-Known URI</a></li>
- <li><a href="setup/installation.html#email">Email</a></li>
- <li><a href="setup/installation.html#registering-a-user">Registering a user</a></li>
- <li><a href="setup/installation.html#setting-up-a-turn-server">Setting up a TURN server</a></li>
- <li><a href="setup/installation.html#url-previews">URL previews</a></li>
- <li><a href="setup/installation.html#troubleshooting-installation">Troubleshooting Installation</a></li>
- </ul>
- </li>
- </ul>
- </li>
- </ul>
- <h2 id="choosing-your-server-name"><a class="header" href="#choosing-your-server-name">Choosing your server name</a></h2>
- <p>It is important to choose the name for your server before you install Synapse,
- because it cannot be changed later.</p>
- <p>The server name determines the "domain" part of user-ids for users on your
- server: these will all be of the format <code>@user:my.domain.name</code>. It also
- determines how other matrix servers will reach yours for federation.</p>
- <p>For a test configuration, set this to the hostname of your server. For a more
- production-ready setup, you will probably want to specify your domain
- (<code>example.com</code>) rather than a matrix-specific hostname here (in the same way
- that your email address is probably <code>user@example.com</code> rather than
- <code>user@email.example.com</code>) - but doing so may require more advanced setup: see
- <a href="setup/../federate.html">Setting up Federation</a>.</p>
- <h2 id="installing-synapse"><a class="header" href="#installing-synapse">Installing Synapse</a></h2>
- <h3 id="installing-from-source"><a class="header" href="#installing-from-source">Installing from source</a></h3>
- <p>(Prebuilt packages are available for some platforms - see <a href="setup/installation.html#prebuilt-packages">Prebuilt packages</a>.)</p>
- <p>When installing from source please make sure that the <a href="setup/installation.html#platform-specific-prerequisites">Platform-specific prerequisites</a> are already installed.</p>
- <p>System requirements:</p>
- <ul>
- <li>POSIX-compliant system (tested on Linux & OS X)</li>
- <li>Python 3.5.2 or later, up to Python 3.9.</li>
- <li>At least 1GB of free RAM if you want to join large public rooms like #matrix:matrix.org</li>
- </ul>
- <p>To install the Synapse homeserver run:</p>
- <pre><code class="language-sh">mkdir -p ~/synapse
- virtualenv -p python3 ~/synapse/env
- source ~/synapse/env/bin/activate
- pip install --upgrade pip
- pip install --upgrade setuptools
- pip install matrix-synapse
- </code></pre>
- <p>This will download Synapse from <a href="https://pypi.org/project/matrix-synapse">PyPI</a>
- and install it, along with the python libraries it uses, into a virtual environment
- under <code>~/synapse/env</code>. Feel free to pick a different directory if you
- prefer.</p>
- <p>This Synapse installation can then be later upgraded by using pip again with the
- update flag:</p>
- <pre><code class="language-sh">source ~/synapse/env/bin/activate
- pip install -U matrix-synapse
- </code></pre>
- <p>Before you can start Synapse, you will need to generate a configuration
- file. To do this, run (in your virtualenv, as before):</p>
- <pre><code class="language-sh">cd ~/synapse
- python -m synapse.app.homeserver \
- --server-name my.domain.name \
- --config-path homeserver.yaml \
- --generate-config \
- --report-stats=[yes|no]
- </code></pre>
- <p>... substituting an appropriate value for <code>--server-name</code>.</p>
- <p>This command will generate you a config file that you can then customise, but it will
- also generate a set of keys for you. These keys will allow your homeserver to
- identify itself to other homeserver, so don't lose or delete them. It would be
- wise to back them up somewhere safe. (If, for whatever reason, you do need to
- change your homeserver's keys, you may find that other homeserver have the
- old key cached. If you update the signing key, you should change the name of the
- key in the <code><server name>.signing.key</code> file (the second word) to something
- different. See the <a href="https://matrix.org/docs/spec/server_server/latest.html#retrieving-server-keys">spec</a> for more information on key management).</p>
- <p>To actually run your new homeserver, pick a working directory for Synapse to
- run (e.g. <code>~/synapse</code>), and:</p>
- <pre><code class="language-sh">cd ~/synapse
- source env/bin/activate
- synctl start
- </code></pre>
- <h4 id="platform-specific-prerequisites"><a class="header" href="#platform-specific-prerequisites">Platform-specific prerequisites</a></h4>
- <p>Synapse is written in Python but some of the libraries it uses are written in
- C. So before we can install Synapse itself we need a working C compiler and the
- header files for Python C extensions.</p>
- <h5 id="debianubunturaspbian"><a class="header" href="#debianubunturaspbian">Debian/Ubuntu/Raspbian</a></h5>
- <p>Installing prerequisites on Ubuntu or Debian:</p>
- <pre><code class="language-sh">sudo apt install build-essential python3-dev libffi-dev \
- python3-pip python3-setuptools sqlite3 \
- libssl-dev virtualenv libjpeg-dev libxslt1-dev
- </code></pre>
- <h5 id="archlinux"><a class="header" href="#archlinux">ArchLinux</a></h5>
- <p>Installing prerequisites on ArchLinux:</p>
- <pre><code class="language-sh">sudo pacman -S base-devel python python-pip \
- python-setuptools python-virtualenv sqlite3
- </code></pre>
- <h5 id="centosfedora"><a class="header" href="#centosfedora">CentOS/Fedora</a></h5>
- <p>Installing prerequisites on CentOS or Fedora Linux:</p>
- <pre><code class="language-sh">sudo dnf install libtiff-devel libjpeg-devel libzip-devel freetype-devel \
- libwebp-devel libxml2-devel libxslt-devel libpq-devel \
- python3-virtualenv libffi-devel openssl-devel python3-devel
- sudo dnf groupinstall "Development Tools"
- </code></pre>
- <h5 id="macos"><a class="header" href="#macos">macOS</a></h5>
- <p>Installing prerequisites on macOS:</p>
- <p>You may need to install the latest Xcode developer tools:</p>
- <pre><code class="language-sh">xcode-select --install
- </code></pre>
- <p>On ARM-based Macs you may need to explicitly install libjpeg which is a pillow dependency. You can use Homebrew (https://brew.sh):</p>
- <pre><code class="language-sh"> brew install jpeg
- </code></pre>
- <p>On macOS Catalina (10.15) you may need to explicitly install OpenSSL
- via brew and inform <code>pip</code> about it so that <code>psycopg2</code> builds:</p>
- <pre><code class="language-sh">brew install openssl@1.1
- export LDFLAGS="-L/usr/local/opt/openssl/lib"
- export CPPFLAGS="-I/usr/local/opt/openssl/include"
- </code></pre>
- <h5 id="opensuse"><a class="header" href="#opensuse">OpenSUSE</a></h5>
- <p>Installing prerequisites on openSUSE:</p>
- <pre><code class="language-sh">sudo zypper in -t pattern devel_basis
- sudo zypper in python-pip python-setuptools sqlite3 python-virtualenv \
- python-devel libffi-devel libopenssl-devel libjpeg62-devel
- </code></pre>
- <h5 id="openbsd"><a class="header" href="#openbsd">OpenBSD</a></h5>
- <p>A port of Synapse is available under <code>net/synapse</code>. The filesystem
- underlying the homeserver directory (defaults to <code>/var/synapse</code>) has to be
- mounted with <code>wxallowed</code> (cf. <code>mount(8)</code>), so creating a separate filesystem
- and mounting it to <code>/var/synapse</code> should be taken into consideration.</p>
- <p>To be able to build Synapse's dependency on python the <code>WRKOBJDIR</code>
- (cf. <code>bsd.port.mk(5)</code>) for building python, too, needs to be on a filesystem
- mounted with <code>wxallowed</code> (cf. <code>mount(8)</code>).</p>
- <p>Creating a <code>WRKOBJDIR</code> for building python under <code>/usr/local</code> (which on a
- default OpenBSD installation is mounted with <code>wxallowed</code>):</p>
- <pre><code class="language-sh">doas mkdir /usr/local/pobj_wxallowed
- </code></pre>
- <p>Assuming <code>PORTS_PRIVSEP=Yes</code> (cf. <code>bsd.port.mk(5)</code>) and <code>SUDO=doas</code> are
- configured in <code>/etc/mk.conf</code>:</p>
- <pre><code class="language-sh">doas chown _pbuild:_pbuild /usr/local/pobj_wxallowed
- </code></pre>
- <p>Setting the <code>WRKOBJDIR</code> for building python:</p>
- <pre><code class="language-sh">echo WRKOBJDIR_lang/python/3.7=/usr/local/pobj_wxallowed \\nWRKOBJDIR_lang/python/2.7=/usr/local/pobj_wxallowed >> /etc/mk.conf
- </code></pre>
- <p>Building Synapse:</p>
- <pre><code class="language-sh">cd /usr/ports/net/synapse
- make install
- </code></pre>
- <h5 id="windows"><a class="header" href="#windows">Windows</a></h5>
- <p>If you wish to run or develop Synapse on Windows, the Windows Subsystem For
- Linux provides a Linux environment on Windows 10 which is capable of using the
- Debian, Fedora, or source installation methods. More information about WSL can
- be found at <a href="https://docs.microsoft.com/en-us/windows/wsl/install-win10">https://docs.microsoft.com/en-us/windows/wsl/install-win10</a> for
- Windows 10 and <a href="https://docs.microsoft.com/en-us/windows/wsl/install-on-server">https://docs.microsoft.com/en-us/windows/wsl/install-on-server</a>
- for Windows Server.</p>
- <h3 id="prebuilt-packages"><a class="header" href="#prebuilt-packages">Prebuilt packages</a></h3>
- <p>As an alternative to installing from source, prebuilt packages are available
- for a number of platforms.</p>
- <h4 id="docker-images-and-ansible-playbooks"><a class="header" href="#docker-images-and-ansible-playbooks">Docker images and Ansible playbooks</a></h4>
- <p>There is an official synapse image available at
- <a href="https://hub.docker.com/r/matrixdotorg/synapse">https://hub.docker.com/r/matrixdotorg/synapse</a> which can be used with
- the docker-compose file available at
- <a href="https://github.com/matrix-org/synapse/tree/develop/contrib/docker">contrib/docker</a>.
- Further information on this including configuration options is available in the README
- on hub.docker.com.</p>
- <p>Alternatively, Andreas Peters (previously Silvio Fricke) has contributed a
- Dockerfile to automate a synapse server in a single Docker image, at
- <a href="https://hub.docker.com/r/avhost/docker-matrix/tags/">https://hub.docker.com/r/avhost/docker-matrix/tags/</a></p>
- <p>Slavi Pantaleev has created an Ansible playbook,
- which installs the offical Docker image of Matrix Synapse
- along with many other Matrix-related services (Postgres database, Element, coturn,
- ma1sd, SSL support, etc.).
- For more details, see
- <a href="https://github.com/spantaleev/matrix-docker-ansible-deploy">https://github.com/spantaleev/matrix-docker-ansible-deploy</a></p>
- <h4 id="debianubuntu"><a class="header" href="#debianubuntu">Debian/Ubuntu</a></h4>
- <h5 id="matrixorg-packages"><a class="header" href="#matrixorg-packages">Matrix.org packages</a></h5>
- <p>Matrix.org provides Debian/Ubuntu packages of Synapse via
- <a href="https://packages.matrix.org/debian/">https://packages.matrix.org/debian/</a>. To install the latest release:</p>
- <pre><code class="language-sh">sudo apt install -y lsb-release wget apt-transport-https
- sudo wget -O /usr/share/keyrings/matrix-org-archive-keyring.gpg https://packages.matrix.org/debian/matrix-org-archive-keyring.gpg
- echo "deb [signed-by=/usr/share/keyrings/matrix-org-archive-keyring.gpg] https://packages.matrix.org/debian/ $(lsb_release -cs) main" |
- sudo tee /etc/apt/sources.list.d/matrix-org.list
- sudo apt update
- sudo apt install matrix-synapse-py3
- </code></pre>
- <p>Packages are also published for release candidates. To enable the prerelease
- channel, add <code>prerelease</code> to the <code>sources.list</code> line. For example:</p>
- <pre><code class="language-sh">sudo wget -O /usr/share/keyrings/matrix-org-archive-keyring.gpg https://packages.matrix.org/debian/matrix-org-archive-keyring.gpg
- echo "deb [signed-by=/usr/share/keyrings/matrix-org-archive-keyring.gpg] https://packages.matrix.org/debian/ $(lsb_release -cs) main prerelease" |
- sudo tee /etc/apt/sources.list.d/matrix-org.list
- sudo apt update
- sudo apt install matrix-synapse-py3
- </code></pre>
- <p>The fingerprint of the repository signing key (as shown by <code>gpg /usr/share/keyrings/matrix-org-archive-keyring.gpg</code>) is
- <code>AAF9AE843A7584B5A3E4CD2BCF45A512DE2DA058</code>.</p>
- <h5 id="downstream-debian-packages"><a class="header" href="#downstream-debian-packages">Downstream Debian packages</a></h5>
- <p>We do not recommend using the packages from the default Debian <code>buster</code>
- repository at this time, as they are old and suffer from known security
- vulnerabilities. You can install the latest version of Synapse from
- <a href="setup/installation.html#matrixorg-packages">our repository</a> or from <code>buster-backports</code>. Please
- see the <a href="https://backports.debian.org/Instructions/">Debian documentation</a>
- for information on how to use backports.</p>
- <p>If you are using Debian <code>sid</code> or testing, Synapse is available in the default
- repositories and it should be possible to install it simply with:</p>
- <pre><code class="language-sh">sudo apt install matrix-synapse
- </code></pre>
- <h5 id="downstream-ubuntu-packages"><a class="header" href="#downstream-ubuntu-packages">Downstream Ubuntu packages</a></h5>
- <p>We do not recommend using the packages in the default Ubuntu repository
- at this time, as they are old and suffer from known security vulnerabilities.
- The latest version of Synapse can be installed from <a href="setup/installation.html#matrixorg-packages">our repository</a>.</p>
- <h4 id="fedora"><a class="header" href="#fedora">Fedora</a></h4>
- <p>Synapse is in the Fedora repositories as <code>matrix-synapse</code>:</p>
- <pre><code class="language-sh">sudo dnf install matrix-synapse
- </code></pre>
- <p>Oleg Girko provides Fedora RPMs at
- <a href="https://obs.infoserver.lv/project/monitor/matrix-synapse">https://obs.infoserver.lv/project/monitor/matrix-synapse</a></p>
- <h4 id="opensuse-1"><a class="header" href="#opensuse-1">OpenSUSE</a></h4>
- <p>Synapse is in the OpenSUSE repositories as <code>matrix-synapse</code>:</p>
- <pre><code class="language-sh">sudo zypper install matrix-synapse
- </code></pre>
- <h4 id="suse-linux-enterprise-server"><a class="header" href="#suse-linux-enterprise-server">SUSE Linux Enterprise Server</a></h4>
- <p>Unofficial package are built for SLES 15 in the openSUSE:Backports:SLE-15 repository at
- <a href="https://download.opensuse.org/repositories/openSUSE:/Backports:/SLE-15/standard/">https://download.opensuse.org/repositories/openSUSE:/Backports:/SLE-15/standard/</a></p>
- <h4 id="archlinux-1"><a class="header" href="#archlinux-1">ArchLinux</a></h4>
- <p>The quickest way to get up and running with ArchLinux is probably with the community package
- <a href="https://www.archlinux.org/packages/community/any/matrix-synapse/">https://www.archlinux.org/packages/community/any/matrix-synapse/</a>, which should pull in most of
- the necessary dependencies.</p>
- <p>pip may be outdated (6.0.7-1 and needs to be upgraded to 6.0.8-1 ):</p>
- <pre><code class="language-sh">sudo pip install --upgrade pip
- </code></pre>
- <p>If you encounter an error with lib bcrypt causing an Wrong ELF Class:
- ELFCLASS32 (x64 Systems), you may need to reinstall py-bcrypt to correctly
- compile it under the right architecture. (This should not be needed if
- installing under virtualenv):</p>
- <pre><code class="language-sh">sudo pip uninstall py-bcrypt
- sudo pip install py-bcrypt
- </code></pre>
- <h4 id="void-linux"><a class="header" href="#void-linux">Void Linux</a></h4>
- <p>Synapse can be found in the void repositories as 'synapse':</p>
- <pre><code class="language-sh">xbps-install -Su
- xbps-install -S synapse
- </code></pre>
- <h4 id="freebsd"><a class="header" href="#freebsd">FreeBSD</a></h4>
- <p>Synapse can be installed via FreeBSD Ports or Packages contributed by Brendan Molloy from:</p>
- <ul>
- <li>Ports: <code>cd /usr/ports/net-im/py-matrix-synapse && make install clean</code></li>
- <li>Packages: <code>pkg install py37-matrix-synapse</code></li>
- </ul>
- <h4 id="openbsd-1"><a class="header" href="#openbsd-1">OpenBSD</a></h4>
- <p>As of OpenBSD 6.7 Synapse is available as a pre-compiled binary. The filesystem
- underlying the homeserver directory (defaults to <code>/var/synapse</code>) has to be
- mounted with <code>wxallowed</code> (cf. <code>mount(8)</code>), so creating a separate filesystem
- and mounting it to <code>/var/synapse</code> should be taken into consideration.</p>
- <p>Installing Synapse:</p>
- <pre><code class="language-sh">doas pkg_add synapse
- </code></pre>
- <h4 id="nixos"><a class="header" href="#nixos">NixOS</a></h4>
- <p>Robin Lambertz has packaged Synapse for NixOS at:
- <a href="https://github.com/NixOS/nixpkgs/blob/master/nixos/modules/services/misc/matrix-synapse.nix">https://github.com/NixOS/nixpkgs/blob/master/nixos/modules/services/misc/matrix-synapse.nix</a></p>
- <h2 id="setting-up-synapse"><a class="header" href="#setting-up-synapse">Setting up Synapse</a></h2>
- <p>Once you have installed synapse as above, you will need to configure it.</p>
- <h3 id="using-postgresql"><a class="header" href="#using-postgresql">Using PostgreSQL</a></h3>
- <p>By default Synapse uses an <a href="https://sqlite.org/">SQLite</a> database and in doing so trades
- performance for convenience. Almost all installations should opt to use <a href="https://www.postgresql.org">PostgreSQL</a>
- instead. Advantages include:</p>
- <ul>
- <li>significant performance improvements due to the superior threading and
- caching model, smarter query optimiser</li>
- <li>allowing the DB to be run on separate hardware</li>
- </ul>
- <p>For information on how to install and use PostgreSQL in Synapse, please see
- <a href="setup/../postgres.html">Using Postgres</a></p>
- <p>SQLite is only acceptable for testing purposes. SQLite should not be used in
- a production server. Synapse will perform poorly when using
- SQLite, especially when participating in large rooms.</p>
- <h3 id="tls-certificates"><a class="header" href="#tls-certificates">TLS certificates</a></h3>
- <p>The default configuration exposes a single HTTP port on the local
- interface: <code>http://localhost:8008</code>. It is suitable for local testing,
- but for any practical use, you will need Synapse's APIs to be served
- over HTTPS.</p>
- <p>The recommended way to do so is to set up a reverse proxy on port
- <code>8448</code>. You can find documentation on doing so in
- <a href="setup/../reverse_proxy.html">the reverse proxy documentation</a>.</p>
- <p>Alternatively, you can configure Synapse to expose an HTTPS port. To do
- so, you will need to edit <code>homeserver.yaml</code>, as follows:</p>
- <ul>
- <li>First, under the <code>listeners</code> section, uncomment the configuration for the
- TLS-enabled listener. (Remove the hash sign (<code>#</code>) at the start of
- each line). The relevant lines are like this:</li>
- </ul>
- <pre><code class="language-yaml"> - port: 8448
- type: http
- tls: true
- resources:
- - names: [client, federation]
- </code></pre>
- <ul>
- <li>
- <p>You will also need to uncomment the <code>tls_certificate_path</code> and
- <code>tls_private_key_path</code> lines under the <code>TLS</code> section. You will need to manage
- provisioning of these certificates yourself.</p>
- <p>If you are using your own certificate, be sure to use a <code>.pem</code> file that
- includes the full certificate chain including any intermediate certificates
- (for instance, if using certbot, use <code>fullchain.pem</code> as your certificate, not
- <code>cert.pem</code>).</p>
- </li>
- </ul>
- <p>For a more detailed guide to configuring your server for federation, see
- <a href="setup/../federate.html">Federation</a>.</p>
- <h3 id="client-well-known-uri"><a class="header" href="#client-well-known-uri">Client Well-Known URI</a></h3>
- <p>Setting up the client Well-Known URI is optional but if you set it up, it will
- allow users to enter their full username (e.g. <code>@user:<server_name></code>) into clients
- which support well-known lookup to automatically configure the homeserver and
- identity server URLs. This is useful so that users don't have to memorize or think
- about the actual homeserver URL you are using.</p>
- <p>The URL <code>https://<server_name>/.well-known/matrix/client</code> should return JSON in
- the following format.</p>
- <pre><code class="language-json">{
- "m.homeserver": {
- "base_url": "https://<matrix.example.com>"
- }
- }
- </code></pre>
- <p>It can optionally contain identity server information as well.</p>
- <pre><code class="language-json">{
- "m.homeserver": {
- "base_url": "https://<matrix.example.com>"
- },
- "m.identity_server": {
- "base_url": "https://<identity.example.com>"
- }
- }
- </code></pre>
- <p>To work in browser based clients, the file must be served with the appropriate
- Cross-Origin Resource Sharing (CORS) headers. A recommended value would be
- <code>Access-Control-Allow-Origin: *</code> which would allow all browser based clients to
- view it.</p>
- <p>In nginx this would be something like:</p>
- <pre><code class="language-nginx">location /.well-known/matrix/client {
- return 200 '{"m.homeserver": {"base_url": "https://<matrix.example.com>"}}';
- default_type application/json;
- add_header Access-Control-Allow-Origin *;
- }
- </code></pre>
- <p>You should also ensure the <code>public_baseurl</code> option in <code>homeserver.yaml</code> is set
- correctly. <code>public_baseurl</code> should be set to the URL that clients will use to
- connect to your server. This is the same URL you put for the <code>m.homeserver</code>
- <code>base_url</code> above.</p>
- <pre><code class="language-yaml">public_baseurl: "https://<matrix.example.com>"
- </code></pre>
- <h3 id="email"><a class="header" href="#email">Email</a></h3>
- <p>It is desirable for Synapse to have the capability to send email. This allows
- Synapse to send password reset emails, send verifications when an email address
- is added to a user's account, and send email notifications to users when they
- receive new messages.</p>
- <p>To configure an SMTP server for Synapse, modify the configuration section
- headed <code>email</code>, and be sure to have at least the <code>smtp_host</code>, <code>smtp_port</code>
- and <code>notif_from</code> fields filled out. You may also need to set <code>smtp_user</code>,
- <code>smtp_pass</code>, and <code>require_transport_security</code>.</p>
- <p>If email is not configured, password reset, registration and notifications via
- email will be disabled.</p>
- <h3 id="registering-a-user"><a class="header" href="#registering-a-user">Registering a user</a></h3>
- <p>The easiest way to create a new user is to do so from a client like <a href="https://element.io/">Element</a>.</p>
- <p>Alternatively, you can do so from the command line. This can be done as follows:</p>
- <ol>
- <li>If synapse was installed via pip, activate the virtualenv as follows (if Synapse was
- installed via a prebuilt package, <code>register_new_matrix_user</code> should already be
- on the search path):
- <pre><code class="language-sh">cd ~/synapse
- source env/bin/activate
- synctl start # if not already running
- </code></pre>
- </li>
- <li>Run the following command:
- <pre><code class="language-sh">register_new_matrix_user -c homeserver.yaml http://localhost:8008
- </code></pre>
- </li>
- </ol>
- <p>This will prompt you to add details for the new user, and will then connect to
- the running Synapse to create the new user. For example:</p>
- <pre><code>New user localpart: erikj
- Password:
- Confirm password:
- Make admin [no]:
- Success!
- </code></pre>
- <p>This process uses a setting <code>registration_shared_secret</code> in
- <code>homeserver.yaml</code>, which is shared between Synapse itself and the
- <code>register_new_matrix_user</code> script. It doesn't matter what it is (a random
- value is generated by <code>--generate-config</code>), but it should be kept secret, as
- anyone with knowledge of it can register users, including admin accounts,
- on your server even if <code>enable_registration</code> is <code>false</code>.</p>
- <h3 id="setting-up-a-turn-server"><a class="header" href="#setting-up-a-turn-server">Setting up a TURN server</a></h3>
- <p>For reliable VoIP calls to be routed via this homeserver, you MUST configure
- a TURN server. See <a href="setup/../turn-howto.html">TURN setup</a> for details.</p>
- <h3 id="url-previews"><a class="header" href="#url-previews">URL previews</a></h3>
- <p>Synapse includes support for previewing URLs, which is disabled by default. To
- turn it on you must enable the <code>url_preview_enabled: True</code> config parameter
- and explicitly specify the IP ranges that Synapse is not allowed to spider for
- previewing in the <code>url_preview_ip_range_blacklist</code> configuration parameter.
- This is critical from a security perspective to stop arbitrary Matrix users
- spidering 'internal' URLs on your network. At the very least we recommend that
- your loopback and RFC1918 IP addresses are blacklisted.</p>
- <p>This also requires the optional <code>lxml</code> python dependency to be installed. This
- in turn requires the <code>libxml2</code> library to be available - on Debian/Ubuntu this
- means <code>apt-get install libxml2-dev</code>, or equivalent for your OS.</p>
- <h3 id="troubleshooting-installation"><a class="header" href="#troubleshooting-installation">Troubleshooting Installation</a></h3>
- <p><code>pip</code> seems to leak <em>lots</em> of memory during installation. For instance, a Linux
- host with 512MB of RAM may run out of memory whilst installing Twisted. If this
- happens, you will have to individually install the dependencies which are
- failing, e.g.:</p>
- <pre><code class="language-sh">pip install twisted
- </code></pre>
- <p>If you have any other problems, feel free to ask in
- <a href="https://matrix.to/#/#synapse:matrix.org">#synapse:matrix.org</a>.</p>
- <div style="break-before: page; page-break-before: always;"></div><h1 id="using-postgres"><a class="header" href="#using-postgres">Using Postgres</a></h1>
- <p>Synapse supports PostgreSQL versions 9.6 or later.</p>
- <h2 id="install-postgres-client-libraries"><a class="header" href="#install-postgres-client-libraries">Install postgres client libraries</a></h2>
- <p>Synapse will require the python postgres client library in order to
- connect to a postgres database.</p>
- <ul>
- <li>
- <p>If you are using the <a href="setup/installation.html#matrixorg-packages">matrix.org debian/ubuntu
- packages</a>, the necessary python
- library will already be installed, but you will need to ensure the
- low-level postgres library is installed, which you can do with
- <code>apt install libpq5</code>.</p>
- </li>
- <li>
- <p>For other pre-built packages, please consult the documentation from
- the relevant package.</p>
- </li>
- <li>
- <p>If you installed synapse <a href="setup/installation.html#installing-from-source">in a
- virtualenv</a>, you can install
- the library with:</p>
- <pre><code>~/synapse/env/bin/pip install "matrix-synapse[postgres]"
- </code></pre>
- <p>(substituting the path to your virtualenv for <code>~/synapse/env</code>, if
- you used a different path). You will require the postgres
- development files. These are in the <code>libpq-dev</code> package on
- Debian-derived distributions.</p>
- </li>
- </ul>
- <h2 id="set-up-database"><a class="header" href="#set-up-database">Set up database</a></h2>
- <p>Assuming your PostgreSQL database user is called <code>postgres</code>, first authenticate as the database user with:</p>
- <pre><code>su - postgres
- # Or, if your system uses sudo to get administrative rights
- sudo -u postgres bash
- </code></pre>
- <p>Then, create a postgres user and a database with:</p>
- <pre><code># this will prompt for a password for the new user
- createuser --pwprompt synapse_user
- createdb --encoding=UTF8 --locale=C --template=template0 --owner=synapse_user synapse
- </code></pre>
- <p>The above will create a user called <code>synapse_user</code>, and a database called
- <code>synapse</code>.</p>
- <p>Note that the PostgreSQL database <em>must</em> have the correct encoding set
- (as shown above), otherwise it will not be able to store UTF8 strings.</p>
- <p>You may need to enable password authentication so <code>synapse_user</code> can
- connect to the database. See
- <a href="https://www.postgresql.org/docs/current/auth-pg-hba-conf.html">https://www.postgresql.org/docs/current/auth-pg-hba-conf.html</a>.</p>
- <h2 id="synapse-config"><a class="header" href="#synapse-config">Synapse config</a></h2>
- <p>When you are ready to start using PostgreSQL, edit the <code>database</code>
- section in your config file to match the following lines:</p>
- <pre><code class="language-yaml">database:
- name: psycopg2
- args:
- user: <user>
- password: <pass>
- database: <db>
- host: <host>
- cp_min: 5
- cp_max: 10
- </code></pre>
- <p>All key, values in <code>args</code> are passed to the <code>psycopg2.connect(..)</code>
- function, except keys beginning with <code>cp_</code>, which are consumed by the
- twisted adbapi connection pool. See the <a href="https://www.postgresql.org/docs/current/libpq-connect.html#LIBPQ-PARAMKEYWORDS">libpq
- documentation</a>
- for a list of options which can be passed.</p>
- <p>You should consider tuning the <code>args.keepalives_*</code> options if there is any danger of
- the connection between your homeserver and database dropping, otherwise Synapse
- may block for an extended period while it waits for a response from the
- database server. Example values might be:</p>
- <pre><code class="language-yaml">database:
- args:
- # ... as above
- # seconds of inactivity after which TCP should send a keepalive message to the server
- keepalives_idle: 10
- # the number of seconds after which a TCP keepalive message that is not
- # acknowledged by the server should be retransmitted
- keepalives_interval: 10
- # the number of TCP keepalives that can be lost before the client's connection
- # to the server is considered dead
- keepalives_count: 3
- </code></pre>
- <h2 id="tuning-postgres"><a class="header" href="#tuning-postgres">Tuning Postgres</a></h2>
- <p>The default settings should be fine for most deployments. For larger
- scale deployments tuning some of the settings is recommended, details of
- which can be found at
- <a href="https://wiki.postgresql.org/wiki/Tuning_Your_PostgreSQL_Server">https://wiki.postgresql.org/wiki/Tuning_Your_PostgreSQL_Server</a>.</p>
- <p>In particular, we've found tuning the following values helpful for
- performance:</p>
- <ul>
- <li><code>shared_buffers</code></li>
- <li><code>effective_cache_size</code></li>
- <li><code>work_mem</code></li>
- <li><code>maintenance_work_mem</code></li>
- <li><code>autovacuum_work_mem</code></li>
- </ul>
- <p>Note that the appropriate values for those fields depend on the amount
- of free memory the database host has available.</p>
- <h2 id="porting-from-sqlite"><a class="header" href="#porting-from-sqlite">Porting from SQLite</a></h2>
- <h3 id="overview"><a class="header" href="#overview">Overview</a></h3>
- <p>The script <code>synapse_port_db</code> allows porting an existing synapse server
- backed by SQLite to using PostgreSQL. This is done in as a two phase
- process:</p>
- <ol>
- <li>Copy the existing SQLite database to a separate location and run
- the port script against that offline database.</li>
- <li>Shut down the server. Rerun the port script to port any data that
- has come in since taking the first snapshot. Restart server against
- the PostgreSQL database.</li>
- </ol>
- <p>The port script is designed to be run repeatedly against newer snapshots
- of the SQLite database file. This makes it safe to repeat step 1 if
- there was a delay between taking the previous snapshot and being ready
- to do step 2.</p>
- <p>It is safe to at any time kill the port script and restart it.</p>
- <p>Note that the database may take up significantly more (25% - 100% more)
- space on disk after porting to Postgres.</p>
- <h3 id="using-the-port-script"><a class="header" href="#using-the-port-script">Using the port script</a></h3>
- <p>Firstly, shut down the currently running synapse server and copy its
- database file (typically <code>homeserver.db</code>) to another location. Once the
- copy is complete, restart synapse. For instance:</p>
- <pre><code>./synctl stop
- cp homeserver.db homeserver.db.snapshot
- ./synctl start
- </code></pre>
- <p>Copy the old config file into a new config file:</p>
- <pre><code>cp homeserver.yaml homeserver-postgres.yaml
- </code></pre>
- <p>Edit the database section as described in the section <em>Synapse config</em>
- above and with the SQLite snapshot located at <code>homeserver.db.snapshot</code>
- simply run:</p>
- <pre><code>synapse_port_db --sqlite-database homeserver.db.snapshot \
- --postgres-config homeserver-postgres.yaml
- </code></pre>
- <p>The flag <code>--curses</code> displays a coloured curses progress UI.</p>
- <p>If the script took a long time to complete, or time has otherwise passed
- since the original snapshot was taken, repeat the previous steps with a
- newer snapshot.</p>
- <p>To complete the conversion shut down the synapse server and run the port
- script one last time, e.g. if the SQLite database is at <code>homeserver.db</code>
- run:</p>
- <pre><code>synapse_port_db --sqlite-database homeserver.db \
- --postgres-config homeserver-postgres.yaml
- </code></pre>
- <p>Once that has completed, change the synapse config to point at the
- PostgreSQL database configuration file <code>homeserver-postgres.yaml</code>:</p>
- <pre><code>./synctl stop
- mv homeserver.yaml homeserver-old-sqlite.yaml
- mv homeserver-postgres.yaml homeserver.yaml
- ./synctl start
- </code></pre>
- <p>Synapse should now be running against PostgreSQL.</p>
- <h2 id="troubleshooting"><a class="header" href="#troubleshooting">Troubleshooting</a></h2>
- <h3 id="alternative-auth-methods"><a class="header" href="#alternative-auth-methods">Alternative auth methods</a></h3>
- <p>If you get an error along the lines of <code>FATAL: Ident authentication failed for user "synapse_user"</code>, you may need to use an authentication method other than
- <code>ident</code>:</p>
- <ul>
- <li>
- <p>If the <code>synapse_user</code> user has a password, add the password to the <code>database:</code>
- section of <code>homeserver.yaml</code>. Then add the following to <code>pg_hba.conf</code>:</p>
- <pre><code>host synapse synapse_user ::1/128 md5 # or `scram-sha-256` instead of `md5` if you use that
- </code></pre>
- </li>
- <li>
- <p>If the <code>synapse_user</code> user does not have a password, then a password doesn't
- have to be added to <code>homeserver.yaml</code>. But the following does need to be added
- to <code>pg_hba.conf</code>:</p>
- <pre><code>host synapse synapse_user ::1/128 trust
- </code></pre>
- </li>
- </ul>
- <p>Note that line order matters in <code>pg_hba.conf</code>, so make sure that if you do add a
- new line, it is inserted before:</p>
- <pre><code>host all all ::1/128 ident
- </code></pre>
- <h3 id="fixing-incorrect-collate-or-ctype"><a class="header" href="#fixing-incorrect-collate-or-ctype">Fixing incorrect <code>COLLATE</code> or <code>CTYPE</code></a></h3>
- <p>Synapse will refuse to set up a new database if it has the wrong values of
- <code>COLLATE</code> and <code>CTYPE</code> set, and will log warnings on existing databases. Using
- different locales can cause issues if the locale library is updated from
- underneath the database, or if a different version of the locale is used on any
- replicas.</p>
- <p>The safest way to fix the issue is to dump the database and recreate it with
- the correct locale parameter (as shown above). It is also possible to change the
- parameters on a live database and run a <code>REINDEX</code> on the entire database,
- however extreme care must be taken to avoid database corruption.</p>
- <p>Note that the above may fail with an error about duplicate rows if corruption
- has already occurred, and such duplicate rows will need to be manually removed.</p>
- <h3 id="fixing-inconsistent-sequences-error"><a class="header" href="#fixing-inconsistent-sequences-error">Fixing inconsistent sequences error</a></h3>
- <p>Synapse uses Postgres sequences to generate IDs for various tables. A sequence
- and associated table can get out of sync if, for example, Synapse has been
- downgraded and then upgraded again.</p>
- <p>To fix the issue shut down Synapse (including any and all workers) and run the
- SQL command included in the error message. Once done Synapse should start
- successfully.</p>
- <div style="break-before: page; page-break-before: always;"></div><h1 id="using-a-reverse-proxy-with-synapse"><a class="header" href="#using-a-reverse-proxy-with-synapse">Using a reverse proxy with Synapse</a></h1>
- <p>It is recommended to put a reverse proxy such as
- <a href="https://nginx.org/en/docs/http/ngx_http_proxy_module.html">nginx</a>,
- <a href="https://httpd.apache.org/docs/current/mod/mod_proxy_http.html">Apache</a>,
- <a href="https://caddyserver.com/docs/quick-starts/reverse-proxy">Caddy</a>,
- <a href="https://www.haproxy.org/">HAProxy</a> or
- <a href="https://man.openbsd.org/relayd.8">relayd</a> in front of Synapse. One advantage
- of doing so is that it means that you can expose the default https port
- (443) to Matrix clients without needing to run Synapse with root
- privileges.</p>
- <p>You should configure your reverse proxy to forward requests to <code>/_matrix</code> or
- <code>/_synapse/client</code> to Synapse, and have it set the <code>X-Forwarded-For</code> and
- <code>X-Forwarded-Proto</code> request headers.</p>
- <p>You should remember that Matrix clients and other Matrix servers do not
- necessarily need to connect to your server via the same server name or
- port. Indeed, clients will use port 443 by default, whereas servers default to
- port 8448. Where these are different, we refer to the 'client port' and the
- 'federation port'. See <a href="https://matrix.org/docs/spec/server_server/latest#resolving-server-names">the Matrix
- specification</a>
- for more details of the algorithm used for federation connections, and
- <a href="delegate.html">Delegation</a> for instructions on setting up delegation.</p>
- <p><strong>NOTE</strong>: Your reverse proxy must not <code>canonicalise</code> or <code>normalise</code>
- the requested URI in any way (for example, by decoding <code>%xx</code> escapes).
- Beware that Apache <em>will</em> canonicalise URIs unless you specify
- <code>nocanon</code>.</p>
- <p>Let's assume that we expect clients to connect to our server at
- <code>https://matrix.example.com</code>, and other servers to connect at
- <code>https://example.com:8448</code>. The following sections detail the configuration of
- the reverse proxy and the homeserver.</p>
- <h2 id="reverse-proxy-configuration-examples"><a class="header" href="#reverse-proxy-configuration-examples">Reverse-proxy configuration examples</a></h2>
- <p><strong>NOTE</strong>: You only need one of these.</p>
- <h3 id="nginx"><a class="header" href="#nginx">nginx</a></h3>
- <pre><code>server {
- listen 443 ssl http2;
- listen [::]:443 ssl http2;
- # For the federation port
- listen 8448 ssl http2 default_server;
- listen [::]:8448 ssl http2 default_server;
- server_name matrix.example.com;
- location ~* ^(\/_matrix|\/_synapse\/client) {
- proxy_pass http://localhost:8008;
- proxy_set_header X-Forwarded-For $remote_addr;
- proxy_set_header X-Forwarded-Proto $scheme;
- proxy_set_header Host $host;
- # Nginx by default only allows file uploads up to 1M in size
- # Increase client_max_body_size to match max_upload_size defined in homeserver.yaml
- client_max_body_size 50M;
- }
- }
- </code></pre>
- <p><strong>NOTE</strong>: Do not add a path after the port in <code>proxy_pass</code>, otherwise nginx will
- canonicalise/normalise the URI.</p>
- <h3 id="caddy-1"><a class="header" href="#caddy-1">Caddy 1</a></h3>
- <pre><code>matrix.example.com {
- proxy /_matrix http://localhost:8008 {
- transparent
- }
- proxy /_synapse/client http://localhost:8008 {
- transparent
- }
- }
- example.com:8448 {
- proxy / http://localhost:8008 {
- transparent
- }
- }
- </code></pre>
- <h3 id="caddy-2"><a class="header" href="#caddy-2">Caddy 2</a></h3>
- <pre><code>matrix.example.com {
- reverse_proxy /_matrix/* http://localhost:8008
- reverse_proxy /_synapse/client/* http://localhost:8008
- }
- example.com:8448 {
- reverse_proxy http://localhost:8008
- }
- </code></pre>
- <p><a href="delegate.html">Delegation</a> example:</p>
- <pre><code>(matrix-well-known-header) {
- # Headers
- header Access-Control-Allow-Origin "*"
- header Access-Control-Allow-Methods "GET, POST, PUT, DELETE, OPTIONS"
- header Access-Control-Allow-Headers "Origin, X-Requested-With, Content-Type, Accept, Authorization"
- header Content-Type "application/json"
- }
- example.com {
- handle /.well-known/matrix/server {
- import matrix-well-known-header
- respond `{"m.server":"matrix.example.com:443"}`
- }
- handle /.well-known/matrix/client {
- import matrix-well-known-header
- respond `{"m.homeserver":{"base_url":"https://matrix.example.com"},"m.identity_server":{"base_url":"https://identity.example.com"}}`
- }
- }
- matrix.example.com {
- reverse_proxy /_matrix/* http://localhost:8008
- reverse_proxy /_synapse/client/* http://localhost:8008
- }
- </code></pre>
- <h3 id="apache"><a class="header" href="#apache">Apache</a></h3>
- <pre><code><VirtualHost *:443>
- SSLEngine on
- ServerName matrix.example.com
- RequestHeader set "X-Forwarded-Proto" expr=%{REQUEST_SCHEME}
- AllowEncodedSlashes NoDecode
- ProxyPreserveHost on
- ProxyPass /_matrix http://127.0.0.1:8008/_matrix nocanon
- ProxyPassReverse /_matrix http://127.0.0.1:8008/_matrix
- ProxyPass /_synapse/client http://127.0.0.1:8008/_synapse/client nocanon
- ProxyPassReverse /_synapse/client http://127.0.0.1:8008/_synapse/client
- </VirtualHost>
- <VirtualHost *:8448>
- SSLEngine on
- ServerName example.com
- RequestHeader set "X-Forwarded-Proto" expr=%{REQUEST_SCHEME}
- AllowEncodedSlashes NoDecode
- ProxyPass /_matrix http://127.0.0.1:8008/_matrix nocanon
- ProxyPassReverse /_matrix http://127.0.0.1:8008/_matrix
- </VirtualHost>
- </code></pre>
- <p><strong>NOTE</strong>: ensure the <code>nocanon</code> options are included.</p>
- <p><strong>NOTE 2</strong>: It appears that Synapse is currently incompatible with the ModSecurity module for Apache (<code>mod_security2</code>). If you need it enabled for other services on your web server, you can disable it for Synapse's two VirtualHosts by including the following lines before each of the two <code></VirtualHost></code> above:</p>
- <pre><code><IfModule security2_module>
- SecRuleEngine off
- </IfModule>
- </code></pre>
- <p><strong>NOTE 3</strong>: Missing <code>ProxyPreserveHost on</code> can lead to a redirect loop.</p>
- <h3 id="haproxy"><a class="header" href="#haproxy">HAProxy</a></h3>
- <pre><code>frontend https
- bind :::443 v4v6 ssl crt /etc/ssl/haproxy/ strict-sni alpn h2,http/1.1
- http-request set-header X-Forwarded-Proto https if { ssl_fc }
- http-request set-header X-Forwarded-Proto http if !{ ssl_fc }
- http-request set-header X-Forwarded-For %[src]
- # Matrix client traffic
- acl matrix-host hdr(host) -i matrix.example.com
- acl matrix-path path_beg /_matrix
- acl matrix-path path_beg /_synapse/client
- use_backend matrix if matrix-host matrix-path
- frontend matrix-federation
- bind :::8448 v4v6 ssl crt /etc/ssl/haproxy/synapse.pem alpn h2,http/1.1
- http-request set-header X-Forwarded-Proto https if { ssl_fc }
- http-request set-header X-Forwarded-Proto http if !{ ssl_fc }
- http-request set-header X-Forwarded-For %[src]
- default_backend matrix
- backend matrix
- server matrix 127.0.0.1:8008
- </code></pre>
- <h3 id="relayd"><a class="header" href="#relayd">Relayd</a></h3>
- <pre><code>table <webserver> { 127.0.0.1 }
- table <matrixserver> { 127.0.0.1 }
- http protocol "https" {
- tls { no tlsv1.0, ciphers "HIGH" }
- tls keypair "example.com"
- match header set "X-Forwarded-For" value "$REMOTE_ADDR"
- match header set "X-Forwarded-Proto" value "https"
- # set CORS header for .well-known/matrix/server, .well-known/matrix/client
- # httpd does not support setting headers, so do it here
- match request path "/.well-known/matrix/*" tag "matrix-cors"
- match response tagged "matrix-cors" header set "Access-Control-Allow-Origin" value "*"
- pass quick path "/_matrix/*" forward to <matrixserver>
- pass quick path "/_synapse/client/*" forward to <matrixserver>
- # pass on non-matrix traffic to webserver
- pass forward to <webserver>
- }
- relay "https_traffic" {
- listen on egress port 443 tls
- protocol "https"
- forward to <matrixserver> port 8008 check tcp
- forward to <webserver> port 8080 check tcp
- }
- http protocol "matrix" {
- tls { no tlsv1.0, ciphers "HIGH" }
- tls keypair "example.com"
- block
- pass quick path "/_matrix/*" forward to <matrixserver>
- pass quick path "/_synapse/client/*" forward to <matrixserver>
- }
- relay "matrix_federation" {
- listen on egress port 8448 tls
- protocol "matrix"
- forward to <matrixserver> port 8008 check tcp
- }
- </code></pre>
- <h2 id="homeserver-configuration"><a class="header" href="#homeserver-configuration">Homeserver Configuration</a></h2>
- <p>You will also want to set <code>bind_addresses: ['127.0.0.1']</code> and
- <code>x_forwarded: true</code> for port 8008 in <code>homeserver.yaml</code> to ensure that
- client IP addresses are recorded correctly.</p>
- <p>Having done so, you can then use <code>https://matrix.example.com</code> (instead
- of <code>https://matrix.example.com:8448</code>) as the "Custom server" when
- connecting to Synapse from a client.</p>
- <h2 id="health-check-endpoint"><a class="header" href="#health-check-endpoint">Health check endpoint</a></h2>
- <p>Synapse exposes a health check endpoint for use by reverse proxies.
- Each configured HTTP listener has a <code>/health</code> endpoint which always returns
- 200 OK (and doesn't get logged).</p>
- <h2 id="synapse-administration-endpoints"><a class="header" href="#synapse-administration-endpoints">Synapse administration endpoints</a></h2>
- <p>Endpoints for administering your Synapse instance are placed under
- <code>/_synapse/admin</code>. These require authentication through an access token of an
- admin user. However as access to these endpoints grants the caller a lot of power,
- we do not recommend exposing them to the public internet without good reason.</p>
- <div style="break-before: page; page-break-before: always;"></div><h1 id="overview-1"><a class="header" href="#overview-1">Overview</a></h1>
- <p>This document explains how to enable VoIP relaying on your Home Server with
- TURN.</p>
- <p>The synapse Matrix Home Server supports integration with TURN server via the
- <a href="https://tools.ietf.org/html/draft-uberti-behave-turn-rest-00">TURN server REST API</a>. This
- allows the Home Server to generate credentials that are valid for use on the
- TURN server through the use of a secret shared between the Home Server and the
- TURN server.</p>
- <p>The following sections describe how to install <a href="https://github.com/coturn/coturn">coturn</a> (which implements the TURN REST API) and integrate it with synapse.</p>
- <h2 id="requirements"><a class="header" href="#requirements">Requirements</a></h2>
- <p>For TURN relaying with <code>coturn</code> to work, it must be hosted on a server/endpoint with a public IP.</p>
- <p>Hosting TURN behind a NAT (even with appropriate port forwarding) is known to cause issues
- and to often not work.</p>
- <h2 id="coturn-setup"><a class="header" href="#coturn-setup"><code>coturn</code> setup</a></h2>
- <h3 id="initial-installation"><a class="header" href="#initial-installation">Initial installation</a></h3>
- <p>The TURN daemon <code>coturn</code> is available from a variety of sources such as native package managers, or installation from source.</p>
- <h4 id="debian-installation"><a class="header" href="#debian-installation">Debian installation</a></h4>
- <p>Just install the debian package:</p>
- <pre><code class="language-sh">apt install coturn
- </code></pre>
- <p>This will install and start a systemd service called <code>coturn</code>.</p>
- <h4 id="source-installation"><a class="header" href="#source-installation">Source installation</a></h4>
- <ol>
- <li>
- <p>Download the <a href="https://github.com/coturn/coturn/releases/latest">latest release</a> from github. Unpack it and <code>cd</code> into the directory.</p>
- </li>
- <li>
- <p>Configure it:</p>
- <pre><code>./configure
- </code></pre>
- <p>You may need to install <code>libevent2</code>: if so, you should do so in
- the way recommended by your operating system. You can ignore
- warnings about lack of database support: a database is unnecessary
- for this purpose.</p>
- </li>
- <li>
- <p>Build and install it:</p>
- <pre><code>make
- make install
- </code></pre>
- </li>
- </ol>
- <h3 id="configuration"><a class="header" href="#configuration">Configuration</a></h3>
- <ol>
- <li>
- <p>Create or edit the config file in <code>/etc/turnserver.conf</code>. The relevant
- lines, with example values, are:</p>
- <pre><code>use-auth-secret
- static-auth-secret=[your secret key here]
- realm=turn.myserver.org
- </code></pre>
- <p>See <code>turnserver.conf</code> for explanations of the options. One way to generate
- the <code>static-auth-secret</code> is with <code>pwgen</code>:</p>
- <pre><code>pwgen -s 64 1
- </code></pre>
- <p>A <code>realm</code> must be specified, but its value is somewhat arbitrary. (It is
- sent to clients as part of the authentication flow.) It is conventional to
- set it to be your server name.</p>
- </li>
- <li>
- <p>You will most likely want to configure coturn to write logs somewhere. The
- easiest way is normally to send them to the syslog:</p>
- <pre><code>syslog
- </code></pre>
- <p>(in which case, the logs will be available via <code>journalctl -u coturn</code> on a
- systemd system). Alternatively, coturn can be configured to write to a
- logfile - check the example config file supplied with coturn.</p>
- </li>
- <li>
- <p>Consider your security settings. TURN lets users request a relay which will
- connect to arbitrary IP addresses and ports. The following configuration is
- suggested as a minimum starting point:</p>
- <pre><code># VoIP traffic is all UDP. There is no reason to let users connect to arbitrary TCP endpoints via the relay.
- no-tcp-relay
- # don't let the relay ever try to connect to private IP address ranges within your network (if any)
- # given the turn server is likely behind your firewall, remember to include any privileged public IPs too.
- denied-peer-ip=10.0.0.0-10.255.255.255
- denied-peer-ip=192.168.0.0-192.168.255.255
- denied-peer-ip=172.16.0.0-172.31.255.255
- # special case the turn server itself so that client->TURN->TURN->client flows work
- allowed-peer-ip=10.0.0.1
- # consider whether you want to limit the quota of relayed streams per user (or total) to avoid risk of DoS.
- user-quota=12 # 4 streams per video call, so 12 streams = 3 simultaneous relayed calls per user.
- total-quota=1200
- </code></pre>
- </li>
- <li>
- <p>Also consider supporting TLS/DTLS. To do this, add the following settings
- to <code>turnserver.conf</code>:</p>
- <pre><code># TLS certificates, including intermediate certs.
- # For Let's Encrypt certificates, use `fullchain.pem` here.
- cert=/path/to/fullchain.pem
- # TLS private key file
- pkey=/path/to/privkey.pem
- </code></pre>
- <p>In this case, replace the <code>turn:</code> schemes in the <code>turn_uri</code> settings below
- with <code>turns:</code>.</p>
- <p>We recommend that you only try to set up TLS/DTLS once you have set up a
- basic installation and got it working.</p>
- </li>
- <li>
- <p>Ensure your firewall allows traffic into the TURN server on the ports
- you've configured it to listen on (By default: 3478 and 5349 for TURN
- traffic (remember to allow both TCP and UDP traffic), and ports 49152-65535
- for the UDP relay.)</p>
- </li>
- <li>
- <p>We do not recommend running a TURN server behind NAT, and are not aware of
- anyone doing so successfully.</p>
- <p>If you want to try it anyway, you will at least need to tell coturn its
- external IP address:</p>
- <pre><code>external-ip=192.88.99.1
- </code></pre>
- <p>... and your NAT gateway must forward all of the relayed ports directly
- (eg, port 56789 on the external IP must be always be forwarded to port
- 56789 on the internal IP).</p>
- <p>If you get this working, let us know!</p>
- </li>
- <li>
- <p>(Re)start the turn server:</p>
- <ul>
- <li>
- <p>If you used the Debian package (or have set up a systemd unit yourself):</p>
- <pre><code class="language-sh">systemctl restart coturn
- </code></pre>
- </li>
- <li>
- <p>If you installed from source:</p>
- <pre><code class="language-sh">bin/turnserver -o
- </code></pre>
- </li>
- </ul>
- </li>
- </ol>
- <h2 id="synapse-setup"><a class="header" href="#synapse-setup">Synapse setup</a></h2>
- <p>Your home server configuration file needs the following extra keys:</p>
- <ol>
- <li>"<code>turn_uris</code>": This needs to be a yaml list of public-facing URIs
- for your TURN server to be given out to your clients. Add separate
- entries for each transport your TURN server supports.</li>
- <li>"<code>turn_shared_secret</code>": This is the secret shared between your
- Home server and your TURN server, so you should set it to the same
- string you used in turnserver.conf.</li>
- <li>"<code>turn_user_lifetime</code>": This is the amount of time credentials
- generated by your Home Server are valid for (in milliseconds).
- Shorter times offer less potential for abuse at the expense of
- increased traffic between web clients and your home server to
- refresh credentials. The TURN REST API specification recommends
- one day (86400000).</li>
- <li>"<code>turn_allow_guests</code>": Whether to allow guest users to use the
- TURN server. This is enabled by default, as otherwise VoIP will
- not work reliably for guests. However, it does introduce a
- security risk as it lets guests connect to arbitrary endpoints
- without having gone through a CAPTCHA or similar to register a
- real account.</li>
- </ol>
- <p>As an example, here is the relevant section of the config file for <code>matrix.org</code>. The
- <code>turn_uris</code> are appropriate for TURN servers listening on the default ports, with no TLS.</p>
- <pre><code>turn_uris: [ "turn:turn.matrix.org?transport=udp", "turn:turn.matrix.org?transport=tcp" ]
- turn_shared_secret: "n0t4ctuAllymatr1Xd0TorgSshar3d5ecret4obvIousreAsons"
- turn_user_lifetime: 86400000
- turn_allow_guests: True
- </code></pre>
- <p>After updating the homeserver configuration, you must restart synapse:</p>
- <ul>
- <li>If you use synctl:
- <pre><code class="language-sh">cd /where/you/run/synapse
- ./synctl restart
- </code></pre>
- </li>
- <li>If you use systemd:
- <pre><code>systemctl restart matrix-synapse.service
- </code></pre>
- </li>
- </ul>
- <p>... and then reload any clients (or wait an hour for them to refresh their
- settings).</p>
- <h2 id="troubleshooting-1"><a class="header" href="#troubleshooting-1">Troubleshooting</a></h2>
- <p>The normal symptoms of a misconfigured TURN server are that calls between
- devices on different networks ring, but get stuck at "call
- connecting". Unfortunately, troubleshooting this can be tricky.</p>
- <p>Here are a few things to try:</p>
- <ul>
- <li>
- <p>Check that your TURN server is not behind NAT. As above, we're not aware of
- anyone who has successfully set this up.</p>
- </li>
- <li>
- <p>Check that you have opened your firewall to allow TCP and UDP traffic to the
- TURN ports (normally 3478 and 5479).</p>
- </li>
- <li>
- <p>Check that you have opened your firewall to allow UDP traffic to the UDP
- relay ports (49152-65535 by default).</p>
- </li>
- <li>
- <p>Some WebRTC implementations (notably, that of Google Chrome) appear to get
- confused by TURN servers which are reachable over IPv6 (this appears to be
- an unexpected side-effect of its handling of multiple IP addresses as
- defined by
- <a href="https://tools.ietf.org/html/draft-ietf-rtcweb-ip-handling-12"><code>draft-ietf-rtcweb-ip-handling</code></a>).</p>
- <p>Try removing any AAAA records for your TURN server, so that it is only
- reachable over IPv4.</p>
- </li>
- <li>
- <p>Enable more verbose logging in coturn via the <code>verbose</code> setting:</p>
- <pre><code>verbose
- </code></pre>
- <p>... and then see if there are any clues in its logs.</p>
- </li>
- <li>
- <p>If you are using a browser-based client under Chrome, check
- <code>chrome://webrtc-internals/</code> for insights into the internals of the
- negotiation. On Firefox, check the "Connection Log" on <code>about:webrtc</code>.</p>
- <p>(Understanding the output is beyond the scope of this document!)</p>
- </li>
- <li>
- <p>You can test your Matrix homeserver TURN setup with https://test.voip.librepush.net/.
- Note that this test is not fully reliable yet, so don't be discouraged if
- the test fails.
- <a href="https://github.com/matrix-org/voip-tester">Here</a> is the github repo of the
- source of the tester, where you can file bug reports.</p>
- </li>
- <li>
- <p>There is a WebRTC test tool at
- https://webrtc.github.io/samples/src/content/peerconnection/trickle-ice/. To
- use it, you will need a username/password for your TURN server. You can
- either:</p>
- <ul>
- <li>
- <p>look for the <code>GET /_matrix/client/r0/voip/turnServer</code> request made by a
- matrix client to your homeserver in your browser's network inspector. In
- the response you should see <code>username</code> and <code>password</code>. Or:</p>
- </li>
- <li>
- <p>Use the following shell commands:</p>
- <pre><code class="language-sh">secret=staticAuthSecretHere
- u=$((`date +%s` + 3600)):test
- p=$(echo -n $u | openssl dgst -hmac $secret -sha1 -binary | base64)
- echo -e "username: $u\npassword: $p"
- </code></pre>
- <p>Or:</p>
- </li>
- <li>
- <p>Temporarily configure coturn to accept a static username/password. To do
- this, comment out <code>use-auth-secret</code> and <code>static-auth-secret</code> and add the
- following:</p>
- <pre><code>lt-cred-mech
- user=username:password
- </code></pre>
- <p><strong>Note</strong>: these settings will not take effect unless <code>use-auth-secret</code>
- and <code>static-auth-secret</code> are disabled.</p>
- <p>Restart coturn after changing the configuration file.</p>
- <p>Remember to restore the original settings to go back to testing with
- Matrix clients!</p>
- </li>
- </ul>
- <p>If the TURN server is working correctly, you should see at least one <code>relay</code>
- entry in the results.</p>
- </li>
- </ul>
- <div style="break-before: page; page-break-before: always;"></div><h1 id="delegation"><a class="header" href="#delegation">Delegation</a></h1>
- <p>By default, other homeservers will expect to be able to reach yours via
- your <code>server_name</code>, on port 8448. For example, if you set your <code>server_name</code>
- to <code>example.com</code> (so that your user names look like <code>@user:example.com</code>),
- other servers will try to connect to yours at <code>https://example.com:8448/</code>.</p>
- <p>Delegation is a Matrix feature allowing a homeserver admin to retain a
- <code>server_name</code> of <code>example.com</code> so that user IDs, room aliases, etc continue
- to look like <code>*:example.com</code>, whilst having federation traffic routed
- to a different server and/or port (e.g. <code>synapse.example.com:443</code>).</p>
- <h2 id="well-known-delegation"><a class="header" href="#well-known-delegation">.well-known delegation</a></h2>
- <p>To use this method, you need to be able to alter the
- <code>server_name</code> 's https server to serve the <code>/.well-known/matrix/server</code>
- URL. Having an active server (with a valid TLS certificate) serving your
- <code>server_name</code> domain is out of the scope of this documentation.</p>
- <p>The URL <code>https://<server_name>/.well-known/matrix/server</code> should
- return a JSON structure containing the key <code>m.server</code> like so:</p>
- <pre><code class="language-json">{
- "m.server": "<synapse.server.name>[:<yourport>]"
- }
- </code></pre>
- <p>In our example, this would mean that URL <code>https://example.com/.well-known/matrix/server</code>
- should return:</p>
- <pre><code class="language-json">{
- "m.server": "synapse.example.com:443"
- }
- </code></pre>
- <p>Note, specifying a port is optional. If no port is specified, then it defaults
- to 8448.</p>
- <p>With .well-known delegation, federating servers will check for a valid TLS
- certificate for the delegated hostname (in our example: <code>synapse.example.com</code>).</p>
- <h2 id="srv-dns-record-delegation"><a class="header" href="#srv-dns-record-delegation">SRV DNS record delegation</a></h2>
- <p>It is also possible to do delegation using a SRV DNS record. However, that is
- considered an advanced topic since it's a bit complex to set up, and <code>.well-known</code>
- delegation is already enough in most cases.</p>
- <p>However, if you really need it, you can find some documentation on how such a
- record should look like and how Synapse will use it in <a href="https://matrix.org/docs/spec/server_server/latest#resolving-server-names">the Matrix
- specification</a>.</p>
- <h2 id="delegation-faq"><a class="header" href="#delegation-faq">Delegation FAQ</a></h2>
- <h3 id="when-do-i-need-delegation"><a class="header" href="#when-do-i-need-delegation">When do I need delegation?</a></h3>
- <p>If your homeserver's APIs are accessible on the default federation port (8448)
- and the domain your <code>server_name</code> points to, you do not need any delegation.</p>
- <p>For instance, if you registered <code>example.com</code> and pointed its DNS A record at a
- fresh server, you could install Synapse on that host, giving it a <code>server_name</code>
- of <code>example.com</code>, and once a reverse proxy has been set up to proxy all requests
- sent to the port <code>8448</code> and serve TLS certificates for <code>example.com</code>, you
- wouldn't need any delegation set up.</p>
- <p><strong>However</strong>, if your homeserver's APIs aren't accessible on port 8448 and on the
- domain <code>server_name</code> points to, you will need to let other servers know how to
- find it using delegation.</p>
- <h3 id="do-you-still-recommend-against-using-a-reverse-proxy-on-the-federation-port"><a class="header" href="#do-you-still-recommend-against-using-a-reverse-proxy-on-the-federation-port">Do you still recommend against using a reverse proxy on the federation port?</a></h3>
- <p>We no longer actively recommend against using a reverse proxy. Many admins will
- find it easier to direct federation traffic to a reverse proxy and manage their
- own TLS certificates, and this is a supported configuration.</p>
- <p>See <a href="reverse_proxy.html">the reverse proxy documentation</a> for information on setting up a
- reverse proxy.</p>
- <h3 id="do-i-still-need-to-give-my-tls-certificates-to-synapse-if-i-am-using-a-reverse-proxy"><a class="header" href="#do-i-still-need-to-give-my-tls-certificates-to-synapse-if-i-am-using-a-reverse-proxy">Do I still need to give my TLS certificates to Synapse if I am using a reverse proxy?</a></h3>
- <p>This is no longer necessary. If you are using a reverse proxy for all of your
- TLS traffic, then you can set <code>no_tls: True</code> in the Synapse config.</p>
- <p>In that case, the only reason Synapse needs the certificate is to populate a legacy
- <code>tls_fingerprints</code> field in the federation API. This is ignored by Synapse 0.99.0
- and later, and the only time pre-0.99 Synapses will check it is when attempting to
- fetch the server keys - and generally this is delegated via <code>matrix.org</code>, which
- is running a modern version of Synapse.</p>
- <h3 id="do-i-need-the-same-certificate-for-the-client-and-federation-port"><a class="header" href="#do-i-need-the-same-certificate-for-the-client-and-federation-port">Do I need the same certificate for the client and federation port?</a></h3>
- <p>No. There is nothing stopping you from using different certificates,
- particularly if you are using a reverse proxy.</p>
- <div style="break-before: page; page-break-before: always;"></div><h1 id="upgrading-synapse"><a class="header" href="#upgrading-synapse">Upgrading Synapse</a></h1>
- <p>Before upgrading check if any special steps are required to upgrade from
- the version you currently have installed to the current version of
- Synapse. The extra instructions that may be required are listed later in
- this document.</p>
- <ul>
- <li>
- <p>Check that your versions of Python and PostgreSQL are still
- supported.</p>
- <p>Synapse follows upstream lifecycles for <a href="https://endoflife.date/python">Python</a> and
- <a href="https://endoflife.date/postgresql">PostgreSQL</a>, and removes support for versions
- which are no longer maintained.</p>
- <p>The website <a href="https://endoflife.date">https://endoflife.date</a> also offers convenient
- summaries.</p>
- </li>
- <li>
- <p>If Synapse was installed using <a href="setup/installation.html#prebuilt-packages">prebuilt
- packages</a>, you will need to follow the
- normal process for upgrading those packages.</p>
- </li>
- <li>
- <p>If Synapse was installed from source, then:</p>
- <ol>
- <li>
- <p>Activate the virtualenv before upgrading. For example, if
- Synapse is installed in a virtualenv in <code>~/synapse/env</code> then
- run:</p>
- <pre><code class="language-bash">source ~/synapse/env/bin/activate
- </code></pre>
- </li>
- <li>
- <p>If Synapse was installed using pip then upgrade to the latest
- version by running:</p>
- <pre><code class="language-bash">pip install --upgrade matrix-synapse
- </code></pre>
- <p>If Synapse was installed using git then upgrade to the latest
- version by running:</p>
- <pre><code class="language-bash">git pull
- pip install --upgrade .
- </code></pre>
- </li>
- <li>
- <p>Restart Synapse:</p>
- <pre><code class="language-bash">./synctl restart
- </code></pre>
- </li>
- </ol>
- </li>
- </ul>
- <p>To check whether your update was successful, you can check the running
- server version with:</p>
- <pre><code class="language-bash"># you may need to replace 'localhost:8008' if synapse is not configured
- # to listen on port 8008.
- curl http://localhost:8008/_synapse/admin/v1/server_version
- </code></pre>
- <h2 id="rolling-back-to-older-versions"><a class="header" href="#rolling-back-to-older-versions">Rolling back to older versions</a></h2>
- <p>Rolling back to previous releases can be difficult, due to database
- schema changes between releases. Where we have been able to test the
- rollback process, this will be noted below.</p>
- <p>In general, you will need to undo any changes made during the upgrade
- process, for example:</p>
- <ul>
- <li>
- <p>pip:</p>
- <pre><code class="language-bash">source env/bin/activate
- # replace `1.3.0` accordingly:
- pip install matrix-synapse==1.3.0
- </code></pre>
- </li>
- <li>
- <p>Debian:</p>
- <pre><code class="language-bash"># replace `1.3.0` and `stretch` accordingly:
- wget https://packages.matrix.org/debian/pool/main/m/matrix-synapse-py3/matrix-synapse-py3_1.3.0+stretch1_amd64.deb
- dpkg -i matrix-synapse-py3_1.3.0+stretch1_amd64.deb
- </code></pre>
- </li>
- </ul>
- <h1 id="upgrading-to-v1390"><a class="header" href="#upgrading-to-v1390">Upgrading to v1.39.0</a></h1>
- <h2 id="deprecation-of-the-current-third-party-rules-module-interface"><a class="header" href="#deprecation-of-the-current-third-party-rules-module-interface">Deprecation of the current third-party rules module interface</a></h2>
- <p>The current third-party rules module interface is deprecated in favour of the new generic
- modules system introduced in Synapse v1.37.0. Authors of third-party rules modules can refer
- to <a href="modules.html#porting-an-existing-module-that-uses-the-old-interface">this documentation</a>
- to update their modules. Synapse administrators can refer to <a href="modules.html#using-modules">this documentation</a>
- to update their configuration once the modules they are using have been updated.</p>
- <p>We plan to remove support for the current third-party rules interface in September 2021.</p>
- <h1 id="upgrading-to-v1380"><a class="header" href="#upgrading-to-v1380">Upgrading to v1.38.0</a></h1>
- <h2 id="re-indexing-of-events-table-on-postgres-databases"><a class="header" href="#re-indexing-of-events-table-on-postgres-databases">Re-indexing of <code>events</code> table on Postgres databases</a></h2>
- <p>This release includes a database schema update which requires re-indexing one of
- the larger tables in the database, <code>events</code>. This could result in increased
- disk I/O for several hours or days after upgrading while the migration
- completes. Furthermore, because we have to keep the old indexes until the new
- indexes are ready, it could result in a significant, temporary, increase in
- disk space.</p>
- <p>To get a rough idea of the disk space required, check the current size of one
- of the indexes. For example, from a <code>psql</code> shell, run the following sql:</p>
- <pre><code class="language-sql">SELECT pg_size_pretty(pg_relation_size('events_order_room'));
- </code></pre>
- <p>We need to rebuild <strong>four</strong> indexes, so you will need to multiply this result
- by four to give an estimate of the disk space required. For example, on one
- particular server:</p>
- <pre><code>synapse=# select pg_size_pretty(pg_relation_size('events_order_room'));
- pg_size_pretty
- ----------------
- 288 MB
- (1 row)
- </code></pre>
- <p>On this server, it would be wise to ensure that at least 1152MB are free.</p>
- <p>The additional disk space will be freed once the migration completes.</p>
- <p>SQLite databases are unaffected by this change.</p>
- <h1 id="upgrading-to-v1370"><a class="header" href="#upgrading-to-v1370">Upgrading to v1.37.0</a></h1>
- <h2 id="deprecation-of-the-current-spam-checker-interface"><a class="header" href="#deprecation-of-the-current-spam-checker-interface">Deprecation of the current spam checker interface</a></h2>
- <p>The current spam checker interface is deprecated in favour of a new generic modules system.
- Authors of spam checker modules can refer to <a href="https://matrix-org.github.io/synapse/develop/modules.html#porting-an-existing-module-that-uses-the-old-interface">this
- documentation</a>
- to update their modules. Synapse administrators can refer to <a href="https://matrix-org.github.io/synapse/develop/modules.html#using-modules">this
- documentation</a>
- to update their configuration once the modules they are using have been updated.</p>
- <p>We plan to remove support for the current spam checker interface in August 2021.</p>
- <p>More module interfaces will be ported over to this new generic system in future versions
- of Synapse.</p>
- <h1 id="upgrading-to-v1340"><a class="header" href="#upgrading-to-v1340">Upgrading to v1.34.0</a></h1>
- <h2 id="room_invite_state_types-configuration-setting"><a class="header" href="#room_invite_state_types-configuration-setting"><code>room_invite_state_types</code> configuration setting</a></h2>
- <p>The <code>room_invite_state_types</code> configuration setting has been deprecated
- and replaced with <code>room_prejoin_state</code>. See the <a href="https://github.com/matrix-org/synapse/blob/v1.34.0/docs/sample_config.yaml#L1515">sample configuration
- file</a>.</p>
- <p>If you have set <code>room_invite_state_types</code> to the default value you
- should simply remove it from your configuration file. The default value
- used to be:</p>
- <pre><code class="language-yaml">room_invite_state_types:
- - "m.room.join_rules"
- - "m.room.canonical_alias"
- - "m.room.avatar"
- - "m.room.encryption"
- - "m.room.name"
- </code></pre>
- <p>If you have customised this value, you should remove
- <code>room_invite_state_types</code> and configure <code>room_prejoin_state</code> instead.</p>
- <h1 id="upgrading-to-v1330"><a class="header" href="#upgrading-to-v1330">Upgrading to v1.33.0</a></h1>
- <h2 id="account-validity-html-templates-can-now-display-a-users-expiration-date"><a class="header" href="#account-validity-html-templates-can-now-display-a-users-expiration-date">Account Validity HTML templates can now display a user's expiration date</a></h2>
- <p>This may affect you if you have enabled the account validity feature,
- and have made use of a custom HTML template specified by the
- <code>account_validity.template_dir</code> or
- <code>account_validity.account_renewed_html_path</code> Synapse config options.</p>
- <p>The template can now accept an <code>expiration_ts</code> variable, which
- represents the unix timestamp in milliseconds for the future date of
- which their account has been renewed until. See the <a href="https://github.com/matrix-org/synapse/blob/release-v1.33.0/synapse/res/templates/account_renewed.html">default
- template</a>
- for an example of usage.</p>
- <p>ALso note that a new HTML template, <code>account_previously_renewed.html</code>,
- has been added. This is is shown to users when they attempt to renew
- their account with a valid renewal token that has already been used
- before. The default template contents can been found
- <a href="https://github.com/matrix-org/synapse/blob/release-v1.33.0/synapse/res/templates/account_previously_renewed.html">here</a>,
- and can also accept an <code>expiration_ts</code> variable. This template replaces
- the error message users would previously see upon attempting to use a
- valid renewal token more than once.</p>
- <h1 id="upgrading-to-v1320"><a class="header" href="#upgrading-to-v1320">Upgrading to v1.32.0</a></h1>
- <h2 id="regression-causing-connected-prometheus-instances-to-become-overwhelmed"><a class="header" href="#regression-causing-connected-prometheus-instances-to-become-overwhelmed">Regression causing connected Prometheus instances to become overwhelmed</a></h2>
- <p>This release introduces <a href="https://github.com/matrix-org/synapse/issues/9853">a
- regression</a> that can
- overwhelm connected Prometheus instances. This issue is not present in
- Synapse v1.32.0rc1.</p>
- <p>If you have been affected, please downgrade to 1.31.0. You then may need
- to remove excess writeahead logs in order for Prometheus to recover.
- Instructions for doing so are provided
- <a href="https://github.com/matrix-org/synapse/pull/9854#issuecomment-823472183">here</a>.</p>
- <h2 id="dropping-support-for-old-python-postgres-and-sqlite-versions"><a class="header" href="#dropping-support-for-old-python-postgres-and-sqlite-versions">Dropping support for old Python, Postgres and SQLite versions</a></h2>
- <p>In line with our <a href="https://github.com/matrix-org/synapse/blob/release-v1.32.0/docs/deprecation_policy.md">deprecation
- policy</a>,
- we've dropped support for Python 3.5 and PostgreSQL 9.5, as they are no
- longer supported upstream.</p>
- <p>This release of Synapse requires Python 3.6+ and PostgresSQL 9.6+ or
- SQLite 3.22+.</p>
- <h2 id="removal-of-old-list-accounts-admin-api"><a class="header" href="#removal-of-old-list-accounts-admin-api">Removal of old List Accounts Admin API</a></h2>
- <p>The deprecated v1 "list accounts" admin API
- (<code>GET /_synapse/admin/v1/users/<user_id></code>) has been removed in this
- version.</p>
- <p>The <a href="https://github.com/matrix-org/synapse/blob/master/docs/admin_api/user_admin_api.rst#list-accounts">v2 list accounts
- API</a>
- has been available since Synapse 1.7.0 (2019-12-13), and is accessible
- under <code>GET /_synapse/admin/v2/users</code>.</p>
- <p>The deprecation of the old endpoint was announced with Synapse 1.28.0
- (released on 2021-02-25).</p>
- <h2 id="application-services-must-use-type-mloginapplication_service-when-registering-users"><a class="header" href="#application-services-must-use-type-mloginapplication_service-when-registering-users">Application Services must use type <code>m.login.application_service</code> when registering users</a></h2>
- <p>In compliance with the <a href="https://matrix.org/docs/spec/application_service/r0.1.2#server-admin-style-permissions">Application Service
- spec</a>,
- Application Services are now required to use the
- <code>m.login.application_service</code> type when registering users via the
- <code>/_matrix/client/r0/register</code> endpoint. This behaviour was deprecated in
- Synapse v1.30.0.</p>
- <p>Please ensure your Application Services are up to date.</p>
- <h1 id="upgrading-to-v1290"><a class="header" href="#upgrading-to-v1290">Upgrading to v1.29.0</a></h1>
- <h2 id="requirement-for-x-forwarded-proto-header"><a class="header" href="#requirement-for-x-forwarded-proto-header">Requirement for X-Forwarded-Proto header</a></h2>
- <p>When using Synapse with a reverse proxy (in particular, when using the
- [x_forwarded]{.title-ref} option on an HTTP listener), Synapse now
- expects to receive an [X-Forwarded-Proto]{.title-ref} header on incoming
- HTTP requests. If it is not set, Synapse will log a warning on each
- received request.</p>
- <p>To avoid the warning, administrators using a reverse proxy should ensure
- that the reverse proxy sets [X-Forwarded-Proto]{.title-ref} header to
- [https]{.title-ref} or [http]{.title-ref} to indicate the protocol used
- by the client.</p>
- <p>Synapse also requires the [Host]{.title-ref} header to be preserved.</p>
- <p>See the <a href="../reverse_proxy.html">reverse proxy documentation</a>, where the
- example configurations have been updated to show how to set these
- headers.</p>
- <p>(Users of <a href="https://caddyserver.com/">Caddy</a> are unaffected, since we
- believe it sets [X-Forwarded-Proto]{.title-ref} by default.)</p>
- <h1 id="upgrading-to-v1270"><a class="header" href="#upgrading-to-v1270">Upgrading to v1.27.0</a></h1>
- <h2 id="changes-to-callback-uri-for-oauth2--openid-connect-and-saml2"><a class="header" href="#changes-to-callback-uri-for-oauth2--openid-connect-and-saml2">Changes to callback URI for OAuth2 / OpenID Connect and SAML2</a></h2>
- <p>This version changes the URI used for callbacks from OAuth2 and SAML2
- identity providers:</p>
- <ul>
- <li>
- <p>If your server is configured for single sign-on via an OpenID
- Connect or OAuth2 identity provider, you will need to add
- <code>[synapse public baseurl]/_synapse/client/oidc/callback</code> to the list
- of permitted "redirect URIs" at the identity provider.</p>
- <p>See the <a href="../openid.html">OpenID docs</a> for more information on setting
- up OpenID Connect.</p>
- </li>
- <li>
- <p>If your server is configured for single sign-on via a SAML2 identity
- provider, you will need to add
- <code>[synapse public baseurl]/_synapse/client/saml2/authn_response</code> as a
- permitted "ACS location" (also known as "allowed callback URLs")
- at the identity provider.</p>
- <p>The "Issuer" in the "AuthnRequest" to the SAML2 identity
- provider is also updated to
- <code>[synapse public baseurl]/_synapse/client/saml2/metadata.xml</code>. If
- your SAML2 identity provider uses this property to validate or
- otherwise identify Synapse, its configuration will need to be
- updated to use the new URL. Alternatively you could create a new,
- separate "EntityDescriptor" in your SAML2 identity provider with
- the new URLs and leave the URLs in the existing "EntityDescriptor"
- as they were.</p>
- </li>
- </ul>
- <h2 id="changes-to-html-templates"><a class="header" href="#changes-to-html-templates">Changes to HTML templates</a></h2>
- <p>The HTML templates for SSO and email notifications now have <a href="https://jinja.palletsprojects.com/en/2.11.x/api/#autoescaping">Jinja2's
- autoescape</a>
- enabled for files ending in <code>.html</code>, <code>.htm</code>, and <code>.xml</code>. If you have
- customised these templates and see issues when viewing them you might
- need to update them. It is expected that most configurations will need
- no changes.</p>
- <p>If you have customised the templates <em>names</em> for these templates, it is
- recommended to verify they end in <code>.html</code> to ensure autoescape is
- enabled.</p>
- <p>The above applies to the following templates:</p>
- <ul>
- <li><code>add_threepid.html</code></li>
- <li><code>add_threepid_failure.html</code></li>
- <li><code>add_threepid_success.html</code></li>
- <li><code>notice_expiry.html</code></li>
- <li><code>notice_expiry.html</code></li>
- <li><code>notif_mail.html</code> (which, by default, includes <code>room.html</code> and
- <code>notif.html</code>)</li>
- <li><code>password_reset.html</code></li>
- <li><code>password_reset_confirmation.html</code></li>
- <li><code>password_reset_failure.html</code></li>
- <li><code>password_reset_success.html</code></li>
- <li><code>registration.html</code></li>
- <li><code>registration_failure.html</code></li>
- <li><code>registration_success.html</code></li>
- <li><code>sso_account_deactivated.html</code></li>
- <li><code>sso_auth_bad_user.html</code></li>
- <li><code>sso_auth_confirm.html</code></li>
- <li><code>sso_auth_success.html</code></li>
- <li><code>sso_error.html</code></li>
- <li><code>sso_login_idp_picker.html</code></li>
- <li><code>sso_redirect_confirm.html</code></li>
- </ul>
- <h1 id="upgrading-to-v1260"><a class="header" href="#upgrading-to-v1260">Upgrading to v1.26.0</a></h1>
- <h2 id="rolling-back-to-v1250-after-a-failed-upgrade"><a class="header" href="#rolling-back-to-v1250-after-a-failed-upgrade">Rolling back to v1.25.0 after a failed upgrade</a></h2>
- <p>v1.26.0 includes a lot of large changes. If something problematic
- occurs, you may want to roll-back to a previous version of Synapse.
- Because v1.26.0 also includes a new database schema version, reverting
- that version is also required alongside the generic rollback
- instructions mentioned above. In short, to roll back to v1.25.0 you need
- to:</p>
- <ol>
- <li>
- <p>Stop the server</p>
- </li>
- <li>
- <p>Decrease the schema version in the database:</p>
- <pre><code class="language-sql">UPDATE schema_version SET version = 58;
- </code></pre>
- </li>
- <li>
- <p>Delete the ignored users & chain cover data:</p>
- <pre><code class="language-sql">DROP TABLE IF EXISTS ignored_users;
- UPDATE rooms SET has_auth_chain_index = false;
- </code></pre>
- <p>For PostgreSQL run:</p>
- <pre><code class="language-sql">TRUNCATE event_auth_chain_links;
- TRUNCATE event_auth_chains;
- </code></pre>
- <p>For SQLite run:</p>
- <pre><code class="language-sql">DELETE FROM event_auth_chain_links;
- DELETE FROM event_auth_chains;
- </code></pre>
- </li>
- <li>
- <p>Mark the deltas as not run (so they will re-run on upgrade).</p>
- <pre><code class="language-sql">DELETE FROM applied_schema_deltas WHERE version = 59 AND file = "59/01ignored_user.py";
- DELETE FROM applied_schema_deltas WHERE version = 59 AND file = "59/06chain_cover_index.sql";
- </code></pre>
- </li>
- <li>
- <p>Downgrade Synapse by following the instructions for your
- installation method in the "Rolling back to older versions"
- section above.</p>
- </li>
- </ol>
- <h1 id="upgrading-to-v1250"><a class="header" href="#upgrading-to-v1250">Upgrading to v1.25.0</a></h1>
- <h2 id="last-release-supporting-python-35"><a class="header" href="#last-release-supporting-python-35">Last release supporting Python 3.5</a></h2>
- <p>This is the last release of Synapse which guarantees support with Python
- 3.5, which passed its upstream End of Life date several months ago.</p>
- <p>We will attempt to maintain support through March 2021, but without
- guarantees.</p>
- <p>In the future, Synapse will follow upstream schedules for ending support
- of older versions of Python and PostgreSQL. Please upgrade to at least
- Python 3.6 and PostgreSQL 9.6 as soon as possible.</p>
- <h2 id="blacklisting-ip-ranges"><a class="header" href="#blacklisting-ip-ranges">Blacklisting IP ranges</a></h2>
- <p>Synapse v1.25.0 includes new settings, <code>ip_range_blacklist</code> and
- <code>ip_range_whitelist</code>, for controlling outgoing requests from Synapse for
- federation, identity servers, push, and for checking key validity for
- third-party invite events. The previous setting,
- <code>federation_ip_range_blacklist</code>, is deprecated. The new
- <code>ip_range_blacklist</code> defaults to private IP ranges if it is not defined.</p>
- <p>If you have never customised <code>federation_ip_range_blacklist</code> it is
- recommended that you remove that setting.</p>
- <p>If you have customised <code>federation_ip_range_blacklist</code> you should update
- the setting name to <code>ip_range_blacklist</code>.</p>
- <p>If you have a custom push server that is reached via private IP space
- you may need to customise <code>ip_range_blacklist</code> or <code>ip_range_whitelist</code>.</p>
- <h1 id="upgrading-to-v1240"><a class="header" href="#upgrading-to-v1240">Upgrading to v1.24.0</a></h1>
- <h2 id="custom-openid-connect-mapping-provider-breaking-change"><a class="header" href="#custom-openid-connect-mapping-provider-breaking-change">Custom OpenID Connect mapping provider breaking change</a></h2>
- <p>This release allows the OpenID Connect mapping provider to perform
- normalisation of the localpart of the Matrix ID. This allows for the
- mapping provider to specify different algorithms, instead of the
- <a href="https://matrix.org/docs/spec/appendices#mapping-from-other-character-sets">default
- way</a>.</p>
- <p>If your Synapse configuration uses a custom mapping provider
- ([oidc_config.user_mapping_provider.module]{.title-ref} is specified and
- not equal to
- [synapse.handlers.oidc_handler.JinjaOidcMappingProvider]{.title-ref})
- then you <em>must</em> ensure that [map_user_attributes]{.title-ref} of the
- mapping provider performs some normalisation of the
- [localpart]{.title-ref} returned. To match previous behaviour you can
- use the [map_username_to_mxid_localpart]{.title-ref} function provided
- by Synapse. An example is shown below:</p>
- <pre><code class="language-python">from synapse.types import map_username_to_mxid_localpart
- class MyMappingProvider:
- def map_user_attributes(self, userinfo, token):
- # ... your custom logic ...
- sso_user_id = ...
- localpart = map_username_to_mxid_localpart(sso_user_id)
- return {"localpart": localpart}
- </code></pre>
- <h2 id="removal-historical-synapse-admin-api"><a class="header" href="#removal-historical-synapse-admin-api">Removal historical Synapse Admin API</a></h2>
- <p>Historically, the Synapse Admin API has been accessible under:</p>
- <ul>
- <li><code>/_matrix/client/api/v1/admin</code></li>
- <li><code>/_matrix/client/unstable/admin</code></li>
- <li><code>/_matrix/client/r0/admin</code></li>
- <li><code>/_synapse/admin/v1</code></li>
- </ul>
- <p>The endpoints with <code>/_matrix/client/*</code> prefixes have been removed as of
- v1.24.0. The Admin API is now only accessible under:</p>
- <ul>
- <li><code>/_synapse/admin/v1</code></li>
- </ul>
- <p>The only exception is the [/admin/whois]{.title-ref} endpoint, which is
- <a href="https://matrix.org/docs/spec/client_server/r0.6.1#get-matrix-client-r0-admin-whois-userid">also available via the client-server
- API</a>.</p>
- <p>The deprecation of the old endpoints was announced with Synapse 1.20.0
- (released on 2020-09-22) and makes it easier for homeserver admins to
- lock down external access to the Admin API endpoints.</p>
- <h1 id="upgrading-to-v1230"><a class="header" href="#upgrading-to-v1230">Upgrading to v1.23.0</a></h1>
- <h2 id="structured-logging-configuration-breaking-changes"><a class="header" href="#structured-logging-configuration-breaking-changes">Structured logging configuration breaking changes</a></h2>
- <p>This release deprecates use of the <code>structured: true</code> logging
- configuration for structured logging. If your logging configuration
- contains <code>structured: true</code> then it should be modified based on the
- <a href="../structured_logging.html">structured logging
- documentation</a>.</p>
- <p>The <code>structured</code> and <code>drains</code> logging options are now deprecated and
- should be replaced by standard logging configuration of <code>handlers</code> and
- <code>formatters</code>.</p>
- <p>A future will release of Synapse will make using <code>structured: true</code> an
- error.</p>
- <h1 id="upgrading-to-v1220"><a class="header" href="#upgrading-to-v1220">Upgrading to v1.22.0</a></h1>
- <h2 id="thirdpartyeventrules-breaking-changes"><a class="header" href="#thirdpartyeventrules-breaking-changes">ThirdPartyEventRules breaking changes</a></h2>
- <p>This release introduces a backwards-incompatible change to modules
- making use of <code>ThirdPartyEventRules</code> in Synapse. If you make use of a
- module defined under the <code>third_party_event_rules</code> config option, please
- make sure it is updated to handle the below change:</p>
- <p>The <code>http_client</code> argument is no longer passed to modules as they are
- initialised. Instead, modules are expected to make use of the
- <code>http_client</code> property on the <code>ModuleApi</code> class. Modules are now passed
- a <code>module_api</code> argument during initialisation, which is an instance of
- <code>ModuleApi</code>. <code>ModuleApi</code> instances have a <code>http_client</code> property which
- acts the same as the <code>http_client</code> argument previously passed to
- <code>ThirdPartyEventRules</code> modules.</p>
- <h1 id="upgrading-to-v1210"><a class="header" href="#upgrading-to-v1210">Upgrading to v1.21.0</a></h1>
- <h2 id="forwarding-_synapseclient-through-your-reverse-proxy"><a class="header" href="#forwarding-_synapseclient-through-your-reverse-proxy">Forwarding <code>/_synapse/client</code> through your reverse proxy</a></h2>
- <p>The <a href="https://github.com/matrix-org/synapse/blob/develop/docs/reverse_proxy.md">reverse proxy
- documentation</a>
- has been updated to include reverse proxy directives for
- <code>/_synapse/client/*</code> endpoints. As the user password reset flow now uses
- endpoints under this prefix, <strong>you must update your reverse proxy
- configurations for user password reset to work</strong>.</p>
- <p>Additionally, note that the <a href="https://github.com/matrix-org/synapse/blob/develop/docs/workers.md">Synapse worker documentation</a> has been updated to</p>
- <p>: state that the <code>/_synapse/client/password_reset/email/submit_token</code>
- endpoint can be handled</p>
- <p>by all workers. If you make use of Synapse's worker feature, please
- update your reverse proxy configuration to reflect this change.</p>
- <h2 id="new-html-templates"><a class="header" href="#new-html-templates">New HTML templates</a></h2>
- <p>A new HTML template,
- <a href="https://github.com/matrix-org/synapse/blob/develop/synapse/res/templates/password_reset_confirmation.html">password_reset_confirmation.html</a>,
- has been added to the <code>synapse/res/templates</code> directory. If you are
- using a custom template directory, you may want to copy the template
- over and modify it.</p>
- <p>Note that as of v1.20.0, templates do not need to be included in custom
- template directories for Synapse to start. The default templates will be
- used if a custom template cannot be found.</p>
- <p>This page will appear to the user after clicking a password reset link
- that has been emailed to them.</p>
- <p>To complete password reset, the page must include a way to make a
- [POST]{.title-ref} request to
- <code>/_synapse/client/password_reset/{medium}/submit_token</code> with the query
- parameters from the original link, presented as a URL-encoded form. See
- the file itself for more details.</p>
- <h2 id="updated-single-sign-on-html-templates"><a class="header" href="#updated-single-sign-on-html-templates">Updated Single Sign-on HTML Templates</a></h2>
- <p>The <code>saml_error.html</code> template was removed from Synapse and replaced
- with the <code>sso_error.html</code> template. If your Synapse is configured to use
- SAML and a custom <code>sso_redirect_confirm_template_dir</code> configuration then
- any customisations of the <code>saml_error.html</code> template will need to be
- merged into the <code>sso_error.html</code> template. These templates are similar,
- but the parameters are slightly different:</p>
- <ul>
- <li>The <code>msg</code> parameter should be renamed to <code>error_description</code>.</li>
- <li>There is no longer a <code>code</code> parameter for the response code.</li>
- <li>A string <code>error</code> parameter is available that includes a short hint
- of why a user is seeing the error page.</li>
- </ul>
- <h1 id="upgrading-to-v1180"><a class="header" href="#upgrading-to-v1180">Upgrading to v1.18.0</a></h1>
- <h2 id="docker--py3title-ref-suffix-will-be-removed-in-future-versions"><a class="header" href="#docker--py3title-ref-suffix-will-be-removed-in-future-versions">Docker [-py3]{.title-ref} suffix will be removed in future versions</a></h2>
- <p>From 10th August 2020, we will no longer publish Docker images with the
- [-py3]{.title-ref} tag suffix. The images tagged with the
- [-py3]{.title-ref} suffix have been identical to the non-suffixed tags
- since release 0.99.0, and the suffix is obsolete.</p>
- <p>On 10th August, we will remove the [latest-py3]{.title-ref} tag.
- Existing per-release tags (such as [v1.18.0-py3]{.title-ref}) will not
- be removed, but no new [-py3]{.title-ref} tags will be added.</p>
- <p>Scripts relying on the [-py3]{.title-ref} suffix will need to be
- updated.</p>
- <h2 id="redis-replication-is-now-recommended-in-lieu-of-tcp-replication"><a class="header" href="#redis-replication-is-now-recommended-in-lieu-of-tcp-replication">Redis replication is now recommended in lieu of TCP replication</a></h2>
- <p>When setting up worker processes, we now recommend the use of a Redis
- server for replication. <strong>The old direct TCP connection method is
- deprecated and will be removed in a future release.</strong> See
- <a href="../workers.html">workers</a> for more details.</p>
- <h1 id="upgrading-to-v1140"><a class="header" href="#upgrading-to-v1140">Upgrading to v1.14.0</a></h1>
- <p>This version includes a database update which is run as part of the
- upgrade, and which may take a couple of minutes in the case of a large
- server. Synapse will not respond to HTTP requests while this update is
- taking place.</p>
- <h1 id="upgrading-to-v1130"><a class="header" href="#upgrading-to-v1130">Upgrading to v1.13.0</a></h1>
- <h2 id="incorrect-database-migration-in-old-synapse-versions"><a class="header" href="#incorrect-database-migration-in-old-synapse-versions">Incorrect database migration in old synapse versions</a></h2>
- <p>A bug was introduced in Synapse 1.4.0 which could cause the room
- directory to be incomplete or empty if Synapse was upgraded directly
- from v1.2.1 or earlier, to versions between v1.4.0 and v1.12.x.</p>
- <p>This will <em>not</em> be a problem for Synapse installations which were:</p>
- <p>: - created at v1.4.0 or later,
- - upgraded via v1.3.x, or
- - upgraded straight from v1.2.1 or earlier to v1.13.0 or later.</p>
- <p>If completeness of the room directory is a concern, installations which
- are affected can be repaired as follows:</p>
- <ol>
- <li>
- <p>Run the following sql from a [psql]{.title-ref} or
- [sqlite3]{.title-ref} console:</p>
- <pre><code class="language-sql">INSERT INTO background_updates (update_name, progress_json, depends_on) VALUES
- ('populate_stats_process_rooms', '{}', 'current_state_events_membership');
- INSERT INTO background_updates (update_name, progress_json, depends_on) VALUES
- ('populate_stats_process_users', '{}', 'populate_stats_process_rooms');
- </code></pre>
- </li>
- <li>
- <p>Restart synapse.</p>
- </li>
- </ol>
- <h2 id="new-single-sign-on-html-templates"><a class="header" href="#new-single-sign-on-html-templates">New Single Sign-on HTML Templates</a></h2>
- <p>New templates (<code>sso_auth_confirm.html</code>, <code>sso_auth_success.html</code>, and
- <code>sso_account_deactivated.html</code>) were added to Synapse. If your Synapse
- is configured to use SSO and a custom
- <code>sso_redirect_confirm_template_dir</code> configuration then these templates
- will need to be copied from
- <a href="synapse/res/templates">synapse/res/templates</a> into that directory.</p>
- <h2 id="synapse-sso-plugins-method-deprecation"><a class="header" href="#synapse-sso-plugins-method-deprecation">Synapse SSO Plugins Method Deprecation</a></h2>
- <p>Plugins using the <code>complete_sso_login</code> method of
- <code>synapse.module_api.ModuleApi</code> should update to using the async/await
- version <code>complete_sso_login_async</code> which includes additional checks. The
- non-async version is considered deprecated.</p>
- <h2 id="rolling-back-to-v1124-after-a-failed-upgrade"><a class="header" href="#rolling-back-to-v1124-after-a-failed-upgrade">Rolling back to v1.12.4 after a failed upgrade</a></h2>
- <p>v1.13.0 includes a lot of large changes. If something problematic
- occurs, you may want to roll-back to a previous version of Synapse.
- Because v1.13.0 also includes a new database schema version, reverting
- that version is also required alongside the generic rollback
- instructions mentioned above. In short, to roll back to v1.12.4 you need
- to:</p>
- <ol>
- <li>
- <p>Stop the server</p>
- </li>
- <li>
- <p>Decrease the schema version in the database:</p>
- <pre><code class="language-sql">UPDATE schema_version SET version = 57;
- </code></pre>
- </li>
- <li>
- <p>Downgrade Synapse by following the instructions for your
- installation method in the "Rolling back to older versions"
- section above.</p>
- </li>
- </ol>
- <h1 id="upgrading-to-v1120"><a class="header" href="#upgrading-to-v1120">Upgrading to v1.12.0</a></h1>
- <p>This version includes a database update which is run as part of the
- upgrade, and which may take some time (several hours in the case of a
- large server). Synapse will not respond to HTTP requests while this
- update is taking place.</p>
- <p>This is only likely to be a problem in the case of a server which is
- participating in many rooms.</p>
- <ol start="0">
- <li>
- <p>As with all upgrades, it is recommended that you have a recent
- backup of your database which can be used for recovery in the event
- of any problems.</p>
- </li>
- <li>
- <p>As an initial check to see if you will be affected, you can try
- running the following query from the [psql]{.title-ref} or
- [sqlite3]{.title-ref} console. It is safe to run it while Synapse is
- still running.</p>
- <pre><code class="language-sql">SELECT MAX(q.v) FROM (
- SELECT (
- SELECT ej.json AS v
- FROM state_events se INNER JOIN event_json ej USING (event_id)
- WHERE se.room_id=rooms.room_id AND se.type='m.room.create' AND se.state_key=''
- LIMIT 1
- ) FROM rooms WHERE rooms.room_version IS NULL
- ) q;
- </code></pre>
- <p>This query will take about the same amount of time as the upgrade
- process: ie, if it takes 5 minutes, then it is likely that Synapse
- will be unresponsive for 5 minutes during the upgrade.</p>
- <p>If you consider an outage of this duration to be acceptable, no
- further action is necessary and you can simply start Synapse 1.12.0.</p>
- <p>If you would prefer to reduce the downtime, continue with the steps
- below.</p>
- </li>
- <li>
- <p>The easiest workaround for this issue is to manually create a new
- index before upgrading. On PostgreSQL, his can be done as follows:</p>
- <pre><code class="language-sql">CREATE INDEX CONCURRENTLY tmp_upgrade_1_12_0_index
- ON state_events(room_id) WHERE type = 'm.room.create';
- </code></pre>
- <p>The above query may take some time, but is also safe to run while
- Synapse is running.</p>
- <p>We assume that no SQLite users have databases large enough to be
- affected. If you <em>are</em> affected, you can run a similar query,
- omitting the <code>CONCURRENTLY</code> keyword. Note however that this
- operation may in itself cause Synapse to stop running for some time.
- Synapse admins are reminded that <a href="https://github.com/matrix-org/synapse/blob/master/README.rst#using-postgresql">SQLite is not recommended for use
- outside a test
- environment</a>.</p>
- </li>
- <li>
- <p>Once the index has been created, the <code>SELECT</code> query in step 1 above
- should complete quickly. It is therefore safe to upgrade to Synapse
- 1.12.0.</p>
- </li>
- <li>
- <p>Once Synapse 1.12.0 has successfully started and is responding to
- HTTP requests, the temporary index can be removed:</p>
- <pre><code class="language-sql">DROP INDEX tmp_upgrade_1_12_0_index;
- </code></pre>
- </li>
- </ol>
- <h1 id="upgrading-to-v1100"><a class="header" href="#upgrading-to-v1100">Upgrading to v1.10.0</a></h1>
- <p>Synapse will now log a warning on start up if used with a PostgreSQL
- database that has a non-recommended locale set.</p>
- <p>See <a href="../postgres.html">Postgres</a> for details.</p>
- <h1 id="upgrading-to-v180"><a class="header" href="#upgrading-to-v180">Upgrading to v1.8.0</a></h1>
- <p>Specifying a <code>log_file</code> config option will now cause Synapse to refuse
- to start, and should be replaced by with the <code>log_config</code> option.
- Support for the <code>log_file</code> option was removed in v1.3.0 and has since
- had no effect.</p>
- <h1 id="upgrading-to-v170"><a class="header" href="#upgrading-to-v170">Upgrading to v1.7.0</a></h1>
- <p>In an attempt to configure Synapse in a privacy preserving way, the
- default behaviours of <code>allow_public_rooms_without_auth</code> and
- <code>allow_public_rooms_over_federation</code> have been inverted. This means that
- by default, only authenticated users querying the Client/Server API will
- be able to query the room directory, and relatedly that the server will
- not share room directory information with other servers over federation.</p>
- <p>If your installation does not explicitly set these settings one way or
- the other and you want either setting to be <code>true</code> then it will
- necessary to update your homeserver configuration file accordingly.</p>
- <p>For more details on the surrounding context see our
- <a href="https://matrix.org/blog/2019/11/09/avoiding-unwelcome-visitors-on-private-matrix-servers">explainer</a>.</p>
- <h1 id="upgrading-to-v150"><a class="header" href="#upgrading-to-v150">Upgrading to v1.5.0</a></h1>
- <p>This release includes a database migration which may take several
- minutes to complete if there are a large number (more than a million or
- so) of entries in the <code>devices</code> table. This is only likely to a be a
- problem on very large installations.</p>
- <h1 id="upgrading-to-v140"><a class="header" href="#upgrading-to-v140">Upgrading to v1.4.0</a></h1>
- <h2 id="new-custom-templates"><a class="header" href="#new-custom-templates">New custom templates</a></h2>
- <p>If you have configured a custom template directory with the
- <code>email.template_dir</code> option, be aware that there are new templates
- regarding registration and threepid management (see below) that must be
- included.</p>
- <ul>
- <li><code>registration.html</code> and <code>registration.txt</code></li>
- <li><code>registration_success.html</code> and <code>registration_failure.html</code></li>
- <li><code>add_threepid.html</code> and <code>add_threepid.txt</code></li>
- <li><code>add_threepid_failure.html</code> and <code>add_threepid_success.html</code></li>
- </ul>
- <p>Synapse will expect these files to exist inside the configured template
- directory, and <strong>will fail to start</strong> if they are absent. To view the
- default templates, see
- <a href="https://github.com/matrix-org/synapse/tree/master/synapse/res/templates">synapse/res/templates</a>.</p>
- <h2 id="3pid-verification-changes"><a class="header" href="#3pid-verification-changes">3pid verification changes</a></h2>
- <p><strong>Note: As of this release, users will be unable to add phone numbers or
- email addresses to their accounts, without changes to the Synapse
- configuration. This includes adding an email address during
- registration.</strong></p>
- <p>It is possible for a user to associate an email address or phone number
- with their account, for a number of reasons:</p>
- <ul>
- <li>for use when logging in, as an alternative to the user id.</li>
- <li>in the case of email, as an alternative contact to help with account
- recovery.</li>
- <li>in the case of email, to receive notifications of missed messages.</li>
- </ul>
- <p>Before an email address or phone number can be added to a user's
- account, or before such an address is used to carry out a
- password-reset, Synapse must confirm the operation with the owner of the
- email address or phone number. It does this by sending an email or text
- giving the user a link or token to confirm receipt. This process is
- known as '3pid verification'. ('3pid', or 'threepid', stands for
- third-party identifier, and we use it to refer to external identifiers
- such as email addresses and phone numbers.)</p>
- <p>Previous versions of Synapse delegated the task of 3pid verification to
- an identity server by default. In most cases this server is <code>vector.im</code>
- or <code>matrix.org</code>.</p>
- <p>In Synapse 1.4.0, for security and privacy reasons, the homeserver will
- no longer delegate this task to an identity server by default. Instead,
- the server administrator will need to explicitly decide how they would
- like the verification messages to be sent.</p>
- <p>In the medium term, the <code>vector.im</code> and <code>matrix.org</code> identity servers
- will disable support for delegated 3pid verification entirely. However,
- in order to ease the transition, they will retain the capability for a
- limited period. Delegated email verification will be disabled on Monday
- 2nd December 2019 (giving roughly 2 months notice). Disabling delegated
- SMS verification will follow some time after that once SMS verification
- support lands in Synapse.</p>
- <p>Once delegated 3pid verification support has been disabled in the
- <code>vector.im</code> and <code>matrix.org</code> identity servers, all Synapse versions that
- depend on those instances will be unable to verify email and phone
- numbers through them. There are no imminent plans to remove delegated
- 3pid verification from Sydent generally. (Sydent is the identity server
- project that backs the <code>vector.im</code> and <code>matrix.org</code> instances).</p>
- <h3 id="email-1"><a class="header" href="#email-1">Email</a></h3>
- <p>Following upgrade, to continue verifying email (e.g. as part of the
- registration process), admins can either:-</p>
- <ul>
- <li>Configure Synapse to use an email server.</li>
- <li>Run or choose an identity server which allows delegated email
- verification and delegate to it.</li>
- </ul>
- <h4 id="configure-smtp-in-synapse"><a class="header" href="#configure-smtp-in-synapse">Configure SMTP in Synapse</a></h4>
- <p>To configure an SMTP server for Synapse, modify the configuration
- section headed <code>email</code>, and be sure to have at least the
- <code>smtp_host, smtp_port</code> and <code>notif_from</code> fields filled out.</p>
- <p>You may also need to set <code>smtp_user</code>, <code>smtp_pass</code>, and
- <code>require_transport_security</code>.</p>
- <p>See the <a href="docs/sample_config.yaml">sample configuration file</a> for more
- details on these settings.</p>
- <h4 id="delegate-email-to-an-identity-server"><a class="header" href="#delegate-email-to-an-identity-server">Delegate email to an identity server</a></h4>
- <p>Some admins will wish to continue using email verification as part of
- the registration process, but will not immediately have an appropriate
- SMTP server at hand.</p>
- <p>To this end, we will continue to support email verification delegation
- via the <code>vector.im</code> and <code>matrix.org</code> identity servers for two months.
- Support for delegated email verification will be disabled on Monday 2nd
- December.</p>
- <p>The <code>account_threepid_delegates</code> dictionary defines whether the
- homeserver should delegate an external server (typically an <a href="https://matrix.org/docs/spec/identity_service/r0.2.1">identity
- server</a>) to handle
- sending confirmation messages via email and SMS.</p>
- <p>So to delegate email verification, in <code>homeserver.yaml</code>, set
- <code>account_threepid_delegates.email</code> to the base URL of an identity
- server. For example:</p>
- <pre><code class="language-yaml">account_threepid_delegates:
- email: https://example.com # Delegate email sending to example.com
- </code></pre>
- <p>Note that <code>account_threepid_delegates.email</code> replaces the deprecated
- <code>email.trust_identity_server_for_password_resets</code>: if
- <code>email.trust_identity_server_for_password_resets</code> is set to <code>true</code>, and
- <code>account_threepid_delegates.email</code> is not set, then the first entry in
- <code>trusted_third_party_id_servers</code> will be used as the
- <code>account_threepid_delegate</code> for email. This is to ensure compatibility
- with existing Synapse installs that set up external server handling for
- these tasks before v1.4.0. If
- <code>email.trust_identity_server_for_password_resets</code> is <code>true</code> and no
- trusted identity server domains are configured, Synapse will report an
- error and refuse to start.</p>
- <p>If <code>email.trust_identity_server_for_password_resets</code> is <code>false</code> or
- absent and no <code>email</code> delegate is configured in
- <code>account_threepid_delegates</code>, then Synapse will send email verification
- messages itself, using the configured SMTP server (see above). that
- type.</p>
- <h3 id="phone-numbers"><a class="header" href="#phone-numbers">Phone numbers</a></h3>
- <p>Synapse does not support phone-number verification itself, so the only
- way to maintain the ability for users to add phone numbers to their
- accounts will be by continuing to delegate phone number verification to
- the <code>matrix.org</code> and <code>vector.im</code> identity servers (or another identity
- server that supports SMS sending).</p>
- <p>The <code>account_threepid_delegates</code> dictionary defines whether the
- homeserver should delegate an external server (typically an <a href="https://matrix.org/docs/spec/identity_service/r0.2.1">identity
- server</a>) to handle
- sending confirmation messages via email and SMS.</p>
- <p>So to delegate phone number verification, in <code>homeserver.yaml</code>, set
- <code>account_threepid_delegates.msisdn</code> to the base URL of an identity
- server. For example:</p>
- <pre><code class="language-yaml">account_threepid_delegates:
- msisdn: https://example.com # Delegate sms sending to example.com
- </code></pre>
- <p>The <code>matrix.org</code> and <code>vector.im</code> identity servers will continue to
- support delegated phone number verification via SMS until such time as
- it is possible for admins to configure their servers to perform phone
- number verification directly. More details will follow in a future
- release.</p>
- <h2 id="rolling-back-to-v131"><a class="header" href="#rolling-back-to-v131">Rolling back to v1.3.1</a></h2>
- <p>If you encounter problems with v1.4.0, it should be possible to roll
- back to v1.3.1, subject to the following:</p>
- <ul>
- <li>
- <p>The 'room statistics' engine was heavily reworked in this release
- (see <a href="https://github.com/matrix-org/synapse/pull/5971">#5971</a>),
- including significant changes to the database schema, which are not
- easily reverted. This will cause the room statistics engine to stop
- updating when you downgrade.</p>
- <p>The room statistics are essentially unused in v1.3.1 (in future
- versions of Synapse, they will be used to populate the room
- directory), so there should be no loss of functionality. However,
- the statistics engine will write errors to the logs, which can be
- avoided by setting the following in <code>homeserver.yaml</code>:</p>
- <pre><code class="language-yaml">stats:
- enabled: false
- </code></pre>
- <p>Don't forget to re-enable it when you upgrade again, in preparation
- for its use in the room directory!</p>
- </li>
- </ul>
- <h1 id="upgrading-to-v120"><a class="header" href="#upgrading-to-v120">Upgrading to v1.2.0</a></h1>
- <p>Some counter metrics have been renamed, with the old names deprecated.
- See <a href="../metrics-howto.html#renaming-of-metrics--deprecation-of-old-names-in-12">the metrics
- documentation</a>
- for details.</p>
- <h1 id="upgrading-to-v110"><a class="header" href="#upgrading-to-v110">Upgrading to v1.1.0</a></h1>
- <p>Synapse v1.1.0 removes support for older Python and PostgreSQL versions,
- as outlined in <a href="https://matrix.org/blog/2019/04/08/synapse-deprecating-postgres-9-4-and-python-2-x">our deprecation
- notice</a>.</p>
- <h2 id="minimum-python-version"><a class="header" href="#minimum-python-version">Minimum Python Version</a></h2>
- <p>Synapse v1.1.0 has a minimum Python requirement of Python 3.5. Python
- 3.6 or Python 3.7 are recommended as they have improved internal string
- handling, significantly reducing memory usage.</p>
- <p>If you use current versions of the Matrix.org-distributed Debian
- packages or Docker images, action is not required.</p>
- <p>If you install Synapse in a Python virtual environment, please see
- "Upgrading to v0.34.0" for notes on setting up a new virtualenv under
- Python 3.</p>
- <h2 id="minimum-postgresql-version"><a class="header" href="#minimum-postgresql-version">Minimum PostgreSQL Version</a></h2>
- <p>If using PostgreSQL under Synapse, you will need to use PostgreSQL 9.5
- or above. Please see the <a href="https://www.postgresql.org/docs/11/upgrading.html">PostgreSQL
- documentation</a> for
- more details on upgrading your database.</p>
- <h1 id="upgrading-to-v10"><a class="header" href="#upgrading-to-v10">Upgrading to v1.0</a></h1>
- <h2 id="validation-of-tls-certificates"><a class="header" href="#validation-of-tls-certificates">Validation of TLS certificates</a></h2>
- <p>Synapse v1.0 is the first release to enforce validation of TLS
- certificates for the federation API. It is therefore essential that your
- certificates are correctly configured. See the
- <a href="../MSC1711_certificates_FAQ.html">FAQ</a> for more information.</p>
- <p>Note, v1.0 installations will also no longer be able to federate with
- servers that have not correctly configured their certificates.</p>
- <p>In rare cases, it may be desirable to disable certificate checking: for
- example, it might be essential to be able to federate with a given
- legacy server in a closed federation. This can be done in one of two
- ways:-</p>
- <ul>
- <li>Configure the global switch <code>federation_verify_certificates</code> to
- <code>false</code>.</li>
- <li>Configure a whitelist of server domains to trust via
- <code>federation_certificate_verification_whitelist</code>.</li>
- </ul>
- <p>See the <a href="docs/sample_config.yaml">sample configuration file</a> for more
- details on these settings.</p>
- <h2 id="email-2"><a class="header" href="#email-2">Email</a></h2>
- <p>When a user requests a password reset, Synapse will send an email to the
- user to confirm the request.</p>
- <p>Previous versions of Synapse delegated the job of sending this email to
- an identity server. If the identity server was somehow malicious or
- became compromised, it would be theoretically possible to hijack an
- account through this means.</p>
- <p>Therefore, by default, Synapse v1.0 will send the confirmation email
- itself. If Synapse is not configured with an SMTP server, password reset
- via email will be disabled.</p>
- <p>To configure an SMTP server for Synapse, modify the configuration
- section headed <code>email</code>, and be sure to have at least the <code>smtp_host</code>,
- <code>smtp_port</code> and <code>notif_from</code> fields filled out. You may also need to set
- <code>smtp_user</code>, <code>smtp_pass</code>, and <code>require_transport_security</code>.</p>
- <p>If you are absolutely certain that you wish to continue using an
- identity server for password resets, set
- <code>trust_identity_server_for_password_resets</code> to <code>true</code>.</p>
- <p>See the <a href="docs/sample_config.yaml">sample configuration file</a> for more
- details on these settings.</p>
- <h2 id="new-email-templates"><a class="header" href="#new-email-templates">New email templates</a></h2>
- <p>Some new templates have been added to the default template directory for the purpose of
- the homeserver sending its own password reset emails. If you have configured a
- custom <code>template_dir</code> in your Synapse config, these files will need to be added.</p>
- <p><code>password_reset.html</code> and <code>password_reset.txt</code> are HTML and plain text
- templates respectively that contain the contents of what will be emailed
- to the user upon attempting to reset their password via email.
- <code>password_reset_success.html</code> and <code>password_reset_failure.html</code> are HTML
- files that the content of which (assuming no redirect URL is set) will
- be shown to the user after they attempt to click the link in the email
- sent to them.</p>
- <h1 id="upgrading-to-v0990"><a class="header" href="#upgrading-to-v0990">Upgrading to v0.99.0</a></h1>
- <p>Please be aware that, before Synapse v1.0 is released around March 2019,
- you will need to replace any self-signed certificates with those
- verified by a root CA. Information on how to do so can be found at <a href="../ACME.html">the
- ACME docs</a>.</p>
- <p>For more information on configuring TLS certificates see the
- <a href="../MSC1711_certificates_FAQ.html">FAQ</a>.</p>
- <h1 id="upgrading-to-v0340"><a class="header" href="#upgrading-to-v0340">Upgrading to v0.34.0</a></h1>
- <ol>
- <li>
- <p>This release is the first to fully support Python 3. Synapse will
- now run on Python versions 3.5, or 3.6 (as well as 2.7). We
- recommend switching to Python 3, as it has been shown to give
- performance improvements.</p>
- <p>For users who have installed Synapse into a virtualenv, we recommend
- doing this by creating a new virtualenv. For example:</p>
- <pre><code>virtualenv -p python3 ~/synapse/env3
- source ~/synapse/env3/bin/activate
- pip install matrix-synapse
- </code></pre>
- <p>You can then start synapse as normal, having activated the new
- virtualenv:</p>
- <pre><code>cd ~/synapse
- source env3/bin/activate
- synctl start
- </code></pre>
- <p>Users who have installed from distribution packages should see the
- relevant package documentation. See below for notes on Debian
- packages.</p>
- <ul>
- <li>
- <p>When upgrading to Python 3, you <strong>must</strong> make sure that your log
- files are configured as UTF-8, by adding <code>encoding: utf8</code> to the
- <code>RotatingFileHandler</code> configuration (if you have one) in your
- <code><server>.log.config</code> file. For example, if your <code>log.config</code>
- file contains:</p>
- <pre><code>handlers:
- file:
- class: logging.handlers.RotatingFileHandler
- formatter: precise
- filename: homeserver.log
- maxBytes: 104857600
- backupCount: 10
- filters: [context]
- console:
- class: logging.StreamHandler
- formatter: precise
- filters: [context]
- </code></pre>
- <p>Then you should update this to be:</p>
- <pre><code>handlers:
- file:
- class: logging.handlers.RotatingFileHandler
- formatter: precise
- filename: homeserver.log
- maxBytes: 104857600
- backupCount: 10
- filters: [context]
- encoding: utf8
- console:
- class: logging.StreamHandler
- formatter: precise
- filters: [context]
- </code></pre>
- <p>There is no need to revert this change if downgrading to
- Python 2.</p>
- </li>
- </ul>
- <p>We are also making available Debian packages which will run Synapse
- on Python 3. You can switch to these packages with
- <code>apt-get install matrix-synapse-py3</code>, however, please read
- <a href="https://github.com/matrix-org/synapse/blob/release-v0.34.0/debian/NEWS">debian/NEWS</a>
- before doing so. The existing <code>matrix-synapse</code> packages will
- continue to use Python 2 for the time being.</p>
- </li>
- <li>
- <p>This release removes the <code>riot.im</code> from the default list of trusted
- identity servers.</p>
- <p>If <code>riot.im</code> is in your homeserver's list of
- <code>trusted_third_party_id_servers</code>, you should remove it. It was added
- in case a hypothetical future identity server was put there. If you
- don't remove it, users may be unable to deactivate their accounts.</p>
- </li>
- <li>
- <p>This release no longer installs the (unmaintained) Matrix Console
- web client as part of the default installation. It is possible to
- re-enable it by installing it separately and setting the
- <code>web_client_location</code> config option, but please consider switching
- to another client.</p>
- </li>
- </ol>
- <h1 id="upgrading-to-v0337"><a class="header" href="#upgrading-to-v0337">Upgrading to v0.33.7</a></h1>
- <p>This release removes the example email notification templates from
- <code>res/templates</code> (they are now internal to the python package). This
- should only affect you if you (a) deploy your Synapse instance from a
- git checkout or a github snapshot URL, and (b) have email notifications
- enabled.</p>
- <p>If you have email notifications enabled, you should ensure that
- <code>email.template_dir</code> is either configured to point at a directory where
- you have installed customised templates, or leave it unset to use the
- default templates.</p>
- <h1 id="upgrading-to-v0273"><a class="header" href="#upgrading-to-v0273">Upgrading to v0.27.3</a></h1>
- <p>This release expands the anonymous usage stats sent if the opt-in
- <code>report_stats</code> configuration is set to <code>true</code>. We now capture RSS memory
- and cpu use at a very coarse level. This requires administrators to
- install the optional <code>psutil</code> python module.</p>
- <p>We would appreciate it if you could assist by ensuring this module is
- available and <code>report_stats</code> is enabled. This will let us see if
- performance changes to synapse are having an impact to the general
- community.</p>
- <h1 id="upgrading-to-v0150"><a class="header" href="#upgrading-to-v0150">Upgrading to v0.15.0</a></h1>
- <p>If you want to use the new URL previewing API
- (<code>/_matrix/media/r0/preview_url</code>) then you have to explicitly enable it
- in the config and update your dependencies dependencies. See README.rst
- for details.</p>
- <h1 id="upgrading-to-v0110"><a class="header" href="#upgrading-to-v0110">Upgrading to v0.11.0</a></h1>
- <p>This release includes the option to send anonymous usage stats to
- matrix.org, and requires that administrators explictly opt in or out by
- setting the <code>report_stats</code> option to either <code>true</code> or <code>false</code>.</p>
- <p>We would really appreciate it if you could help our project out by
- reporting anonymized usage statistics from your homeserver. Only very
- basic aggregate data (e.g. number of users) will be reported, but it
- helps us to track the growth of the Matrix community, and helps us to
- make Matrix a success, as well as to convince other networks that they
- should peer with us.</p>
- <h1 id="upgrading-to-v090"><a class="header" href="#upgrading-to-v090">Upgrading to v0.9.0</a></h1>
- <p>Application services have had a breaking API change in this version.</p>
- <p>They can no longer register themselves with a home server using the AS
- HTTP API. This decision was made because a compromised application
- service with free reign to register any regex in effect grants full
- read/write access to the home server if a regex of <code>.*</code> is used. An
- attack where a compromised AS re-registers itself with <code>.*</code> was deemed
- too big of a security risk to ignore, and so the ability to register
- with the HS remotely has been removed.</p>
- <p>It has been replaced by specifying a list of application service
- registrations in <code>homeserver.yaml</code>:</p>
- <pre><code>app_service_config_files: ["registration-01.yaml", "registration-02.yaml"]
- </code></pre>
- <p>Where <code>registration-01.yaml</code> looks like:</p>
- <pre><code>url: <String> # e.g. "https://my.application.service.com"
- as_token: <String>
- hs_token: <String>
- sender_localpart: <String> # This is a new field which denotes the user_id localpart when using the AS token
- namespaces:
- users:
- - exclusive: <Boolean>
- regex: <String> # e.g. "@prefix_.*"
- aliases:
- - exclusive: <Boolean>
- regex: <String>
- rooms:
- - exclusive: <Boolean>
- regex: <String>
- </code></pre>
- <h1 id="upgrading-to-v080"><a class="header" href="#upgrading-to-v080">Upgrading to v0.8.0</a></h1>
- <p>Servers which use captchas will need to add their public key to:</p>
- <pre><code>static/client/register/register_config.js
- window.matrixRegistrationConfig = {
- recaptcha_public_key: "YOUR_PUBLIC_KEY"
- };
- </code></pre>
- <p>This is required in order to support registration fallback (typically
- used on mobile devices).</p>
- <h1 id="upgrading-to-v070"><a class="header" href="#upgrading-to-v070">Upgrading to v0.7.0</a></h1>
- <p>New dependencies are:</p>
- <ul>
- <li>pydenticon</li>
- <li>simplejson</li>
- <li>syutil</li>
- <li>matrix-angular-sdk</li>
- </ul>
- <p>To pull in these dependencies in a virtual env, run:</p>
- <pre><code>python synapse/python_dependencies.py | xargs -n 1 pip install
- </code></pre>
- <h1 id="upgrading-to-v060"><a class="header" href="#upgrading-to-v060">Upgrading to v0.6.0</a></h1>
- <p>To pull in new dependencies, run:</p>
- <pre><code>python setup.py develop --user
- </code></pre>
- <p>This update includes a change to the database schema. To upgrade you
- first need to upgrade the database by running:</p>
- <pre><code>python scripts/upgrade_db_to_v0.6.0.py <db> <server_name> <signing_key>
- </code></pre>
- <p>Where [<db>]{.title-ref} is the location of the database,
- [<server_name>]{.title-ref} is the server name as specified in the
- synapse configuration, and [<signing_key>]{.title-ref} is the location
- of the signing key as specified in the synapse configuration.</p>
- <p>This may take some time to complete. Failures of signatures and content
- hashes can safely be ignored.</p>
- <h1 id="upgrading-to-v051"><a class="header" href="#upgrading-to-v051">Upgrading to v0.5.1</a></h1>
- <p>Depending on precisely when you installed v0.5.0 you may have ended up
- with a stale release of the reference matrix webclient installed as a
- python module. To uninstall it and ensure you are depending on the
- latest module, please run:</p>
- <pre><code>$ pip uninstall syweb
- </code></pre>
- <h1 id="upgrading-to-v050"><a class="header" href="#upgrading-to-v050">Upgrading to v0.5.0</a></h1>
- <p>The webclient has been split out into a seperate repository/pacakage in
- this release. Before you restart your homeserver you will need to pull
- in the webclient package by running:</p>
- <pre><code>python setup.py develop --user
- </code></pre>
- <p>This release completely changes the database schema and so requires
- upgrading it before starting the new version of the homeserver.</p>
- <p>The script "database-prepare-for-0.5.0.sh" should be used to upgrade
- the database. This will save all user information, such as logins and
- profiles, but will otherwise purge the database. This includes messages,
- which rooms the home server was a member of and room alias mappings.</p>
- <p>If you would like to keep your history, please take a copy of your
- database file and ask for help in #matrix:matrix.org. The upgrade
- process is, unfortunately, non trivial and requires human intervention
- to resolve any resulting conflicts during the upgrade process.</p>
- <p>Before running the command the homeserver should be first completely
- shutdown. To run it, simply specify the location of the database, e.g.:</p>
- <blockquote>
- <p>./scripts/database-prepare-for-0.5.0.sh "homeserver.db"</p>
- </blockquote>
- <p>Once this has successfully completed it will be safe to restart the
- homeserver. You may notice that the homeserver takes a few seconds
- longer to restart than usual as it reinitializes the database.</p>
- <p>On startup of the new version, users can either rejoin remote rooms
- using room aliases or by being reinvited. Alternatively, if any other
- homeserver sends a message to a room that the homeserver was previously
- in the local HS will automatically rejoin the room.</p>
- <h1 id="upgrading-to-v040"><a class="header" href="#upgrading-to-v040">Upgrading to v0.4.0</a></h1>
- <p>This release needs an updated syutil version. Run:</p>
- <pre><code>python setup.py develop
- </code></pre>
- <p>You will also need to upgrade your configuration as the signing key
- format has changed. Run:</p>
- <pre><code>python -m synapse.app.homeserver --config-path <CONFIG> --generate-config
- </code></pre>
- <h1 id="upgrading-to-v030"><a class="header" href="#upgrading-to-v030">Upgrading to v0.3.0</a></h1>
- <p>This registration API now closely matches the login API. This introduces
- a bit more backwards and forwards between the HS and the client, but
- this improves the overall flexibility of the API. You can now GET on
- /register to retrieve a list of valid registration flows. Upon choosing
- one, they are submitted in the same way as login, e.g:</p>
- <pre><code>{
- type: m.login.password,
- user: foo,
- password: bar
- }
- </code></pre>
- <p>The default HS supports 2 flows, with and without Identity Server email
- authentication. Enabling captcha on the HS will add in an extra step to
- all flows: <code>m.login.recaptcha</code> which must be completed before you can
- transition to the next stage. There is a new login type:
- <code>m.login.email.identity</code> which contains the <code>threepidCreds</code> key which
- were previously sent in the original register request. For more
- information on this, see the specification.</p>
- <h2 id="web-client"><a class="header" href="#web-client">Web Client</a></h2>
- <p>The VoIP specification has changed between v0.2.0 and v0.3.0. Users
- should refresh any browser tabs to get the latest web client code. Users
- on v0.2.0 of the web client will not be able to call those on v0.3.0 and
- vice versa.</p>
- <h1 id="upgrading-to-v020"><a class="header" href="#upgrading-to-v020">Upgrading to v0.2.0</a></h1>
- <p>The home server now requires setting up of SSL config before it can run.
- To automatically generate default config use:</p>
- <pre><code>$ python synapse/app/homeserver.py \
- --server-name machine.my.domain.name \
- --bind-port 8448 \
- --config-path homeserver.config \
- --generate-config
- </code></pre>
- <p>This config can be edited if desired, for example to specify a different
- SSL certificate to use. Once done you can run the home server using:</p>
- <pre><code>$ python synapse/app/homeserver.py --config-path homeserver.config
- </code></pre>
- <p>See the README.rst for more information.</p>
- <p>Also note that some config options have been renamed, including:</p>
- <ul>
- <li>"host" to "server-name"</li>
- <li>"database" to "database-path"</li>
- <li>"port" to "bind-port" and "unsecure-port"</li>
- </ul>
- <h1 id="upgrading-to-v001"><a class="header" href="#upgrading-to-v001">Upgrading to v0.0.1</a></h1>
- <p>This release completely changes the database schema and so requires
- upgrading it before starting the new version of the homeserver.</p>
- <p>The script "database-prepare-for-0.0.1.sh" should be used to upgrade
- the database. This will save all user information, such as logins and
- profiles, but will otherwise purge the database. This includes messages,
- which rooms the home server was a member of and room alias mappings.</p>
- <p>Before running the command the homeserver should be first completely
- shutdown. To run it, simply specify the location of the database, e.g.:</p>
- <blockquote>
- <p>./scripts/database-prepare-for-0.0.1.sh "homeserver.db"</p>
- </blockquote>
- <p>Once this has successfully completed it will be safe to restart the
- homeserver. You may notice that the homeserver takes a few seconds
- longer to restart than usual as it reinitializes the database.</p>
- <p>On startup of the new version, users can either rejoin remote rooms
- using room aliases or by being reinvited. Alternatively, if any other
- homeserver sends a message to a room that the homeserver was previously
- in the local HS will automatically rejoin the room.</p>
- <div style="break-before: page; page-break-before: always;"></div><h1 id="msc1711-certificates-faq"><a class="header" href="#msc1711-certificates-faq">MSC1711 Certificates FAQ</a></h1>
- <h2 id="historical-note"><a class="header" href="#historical-note">Historical Note</a></h2>
- <p>This document was originally written to guide server admins through the upgrade
- path towards Synapse 1.0. Specifically,
- <a href="https://github.com/matrix-org/matrix-doc/blob/master/proposals/1711-x509-for-federation.md">MSC1711</a>
- required that all servers present valid TLS certificates on their federation
- API. Admins were encouraged to achieve compliance from version 0.99.0 (released
- in February 2019) ahead of version 1.0 (released June 2019) enforcing the
- certificate checks.</p>
- <p>Much of what follows is now outdated since most admins will have already
- upgraded, however it may be of use to those with old installs returning to the
- project.</p>
- <p>If you are setting up a server from scratch you almost certainly should look at
- the <a href="setup/installation.html">installation guide</a> instead.</p>
- <h2 id="introduction-1"><a class="header" href="#introduction-1">Introduction</a></h2>
- <p>The goal of Synapse 0.99.0 is to act as a stepping stone to Synapse 1.0.0. It
- supports the r0.1 release of the server to server specification, but is
- compatible with both the legacy Matrix federation behaviour (pre-r0.1) as well
- as post-r0.1 behaviour, in order to allow for a smooth upgrade across the
- federation.</p>
- <p>The most important thing to know is that Synapse 1.0.0 will require a valid TLS
- certificate on federation endpoints. Self signed certificates will not be
- sufficient.</p>
- <p>Synapse 0.99.0 makes it easy to configure TLS certificates and will
- interoperate with both >= 1.0.0 servers as well as existing servers yet to
- upgrade.</p>
- <p><strong>It is critical that all admins upgrade to 0.99.0 and configure a valid TLS
- certificate.</strong> Admins will have 1 month to do so, after which 1.0.0 will be
- released and those servers without a valid certificate will not longer be able
- to federate with >= 1.0.0 servers.</p>
- <p>Full details on how to carry out this configuration change is given
- <a href="MSC1711_certificates_FAQ.html#configuring-certificates-for-compatibility-with-synapse-100">below</a>. A
- timeline and some frequently asked questions are also given below.</p>
- <p>For more details and context on the release of the r0.1 Server/Server API and
- imminent Matrix 1.0 release, you can also see our
- <a href="https://matrix.org/blog/2019/02/04/matrix-at-fosdem-2019/">main talk from FOSDEM 2019</a>.</p>
- <h2 id="contents"><a class="header" href="#contents">Contents</a></h2>
- <ul>
- <li>Timeline</li>
- <li>Configuring certificates for compatibility with Synapse 1.0</li>
- <li>FAQ
- <ul>
- <li>Synapse 0.99.0 has just been released, what do I need to do right now?</li>
- <li>How do I upgrade?</li>
- <li>What will happen if I do not set up a valid federation certificate
- immediately?</li>
- <li>What will happen if I do nothing at all?</li>
- <li>When do I need a SRV record or .well-known URI?</li>
- <li>Can I still use an SRV record?</li>
- <li>I have created a .well-known URI. Do I still need an SRV record?</li>
- <li>It used to work just fine, why are you breaking everything?</li>
- <li>Can I manage my own certificates rather than having Synapse renew
- certificates itself?</li>
- <li>Do you still recommend against using a reverse proxy on the federation port?</li>
- <li>Do I still need to give my TLS certificates to Synapse if I am using a
- reverse proxy?</li>
- <li>Do I need the same certificate for the client and federation port?</li>
- <li>How do I tell Synapse to reload my keys/certificates after I replace them?</li>
- </ul>
- </li>
- </ul>
- <h2 id="timeline"><a class="header" href="#timeline">Timeline</a></h2>
- <p><strong>5th Feb 2019 - Synapse 0.99.0 is released.</strong></p>
- <p>All server admins are encouraged to upgrade.</p>
- <p>0.99.0:</p>
- <ul>
- <li>
- <p>provides support for ACME to make setting up Let's Encrypt certs easy, as
- well as .well-known support.</p>
- </li>
- <li>
- <p>does not enforce that a valid CA cert is present on the federation API, but
- rather makes it easy to set one up.</p>
- </li>
- <li>
- <p>provides support for .well-known</p>
- </li>
- </ul>
- <p>Admins should upgrade and configure a valid CA cert. Homeservers that require a
- .well-known entry (see below), should retain their SRV record and use it
- alongside their .well-known record.</p>
- <p><strong>10th June 2019 - Synapse 1.0.0 is released</strong></p>
- <p>1.0.0 is scheduled for release on 10th June. In
- accordance with the the <a href="https://matrix.org/docs/spec/server_server/r0.1.0.html">S2S spec</a>
- 1.0.0 will enforce certificate validity. This means that any homeserver without a
- valid certificate after this point will no longer be able to federate with
- 1.0.0 servers.</p>
- <h2 id="configuring-certificates-for-compatibility-with-synapse-100"><a class="header" href="#configuring-certificates-for-compatibility-with-synapse-100">Configuring certificates for compatibility with Synapse 1.0.0</a></h2>
- <h3 id="if-you-do-not-currently-have-an-srv-record"><a class="header" href="#if-you-do-not-currently-have-an-srv-record">If you do not currently have an SRV record</a></h3>
- <p>In this case, your <code>server_name</code> points to the host where your Synapse is
- running. There is no need to create a <code>.well-known</code> URI or an SRV record, but
- you will need to give Synapse a valid, signed, certificate.</p>
- <h3 id="if-you-do-have-an-srv-record-currently"><a class="header" href="#if-you-do-have-an-srv-record-currently">If you do have an SRV record currently</a></h3>
- <p>If you are using an SRV record, your matrix domain (<code>server_name</code>) may not
- point to the same host that your Synapse is running on (the 'target
- domain'). (If it does, you can follow the recommendation above; otherwise, read
- on.)</p>
- <p>Let's assume that your <code>server_name</code> is <code>example.com</code>, and your Synapse is
- hosted at a target domain of <code>customer.example.net</code>. Currently you should have
- an SRV record which looks like:</p>
- <pre><code>_matrix._tcp.example.com. IN SRV 10 5 8000 customer.example.net.
- </code></pre>
- <p>In this situation, you have three choices for how to proceed:</p>
- <h4 id="option-1-give-synapse-a-certificate-for-your-matrix-domain"><a class="header" href="#option-1-give-synapse-a-certificate-for-your-matrix-domain">Option 1: give Synapse a certificate for your matrix domain</a></h4>
- <p>Synapse 1.0 will expect your server to present a TLS certificate for your
- <code>server_name</code> (<code>example.com</code> in the above example). You can achieve this by acquiring a
- certificate for the <code>server_name</code> yourself (for example, using <code>certbot</code>), and giving it
- and the key to Synapse via <code>tls_certificate_path</code> and <code>tls_private_key_path</code>.</p>
- <h4 id="option-2-run-synapse-behind-a-reverse-proxy"><a class="header" href="#option-2-run-synapse-behind-a-reverse-proxy">Option 2: run Synapse behind a reverse proxy</a></h4>
- <p>If you have an existing reverse proxy set up with correct TLS certificates for
- your domain, you can simply route all traffic through the reverse proxy by
- updating the SRV record appropriately (or removing it, if the proxy listens on
- 8448).</p>
- <p>See <a href="reverse_proxy.html">the reverse proxy documentation</a> for information on setting up a
- reverse proxy.</p>
- <h4 id="option-3-add-a-well-known-file-to-delegate-your-matrix-traffic"><a class="header" href="#option-3-add-a-well-known-file-to-delegate-your-matrix-traffic">Option 3: add a .well-known file to delegate your matrix traffic</a></h4>
- <p>This will allow you to keep Synapse on a separate domain, without having to
- give it a certificate for the matrix domain.</p>
- <p>You can do this with a <code>.well-known</code> file as follows:</p>
- <ol>
- <li>
- <p>Keep the SRV record in place - it is needed for backwards compatibility
- with Synapse 0.34 and earlier.</p>
- </li>
- <li>
- <p>Give Synapse a certificate corresponding to the target domain
- (<code>customer.example.net</code> in the above example). You can do this by acquire a
- certificate for the target domain and giving it to Synapse via <code>tls_certificate_path</code>
- and <code>tls_private_key_path</code>.</p>
- </li>
- <li>
- <p>Restart Synapse to ensure the new certificate is loaded.</p>
- </li>
- <li>
- <p>Arrange for a <code>.well-known</code> file at
- <code>https://<server_name>/.well-known/matrix/server</code> with contents:</p>
- <pre><code class="language-json">{"m.server": "<target server name>"}
- </code></pre>
- <p>where the target server name is resolved as usual (i.e. SRV lookup, falling
- back to talking to port 8448).</p>
- <p>In the above example, where synapse is listening on port 8000,
- <code>https://example.com/.well-known/matrix/server</code> should have <code>m.server</code> set to one of:</p>
- <ol>
- <li>
- <p><code>customer.example.net</code> ─ with a SRV record on
- <code>_matrix._tcp.customer.example.com</code> pointing to port 8000, or:</p>
- </li>
- <li>
- <p><code>customer.example.net</code> ─ updating synapse to listen on the default port
- 8448, or:</p>
- </li>
- <li>
- <p><code>customer.example.net:8000</code> ─ ensuring that if there is a reverse proxy
- on <code>customer.example.net:8000</code> it correctly handles HTTP requests with
- Host header set to <code>customer.example.net:8000</code>.</p>
- </li>
- </ol>
- </li>
- </ol>
- <h2 id="faq"><a class="header" href="#faq">FAQ</a></h2>
- <h3 id="synapse-0990-has-just-been-released-what-do-i-need-to-do-right-now"><a class="header" href="#synapse-0990-has-just-been-released-what-do-i-need-to-do-right-now">Synapse 0.99.0 has just been released, what do I need to do right now?</a></h3>
- <p>Upgrade as soon as you can in preparation for Synapse 1.0.0, and update your
- TLS certificates as <a href="MSC1711_certificates_FAQ.html#configuring-certificates-for-compatibility-with-synapse-100">above</a>.</p>
- <h3 id="what-will-happen-if-i-do-not-set-up-a-valid-federation-certificate-immediately"><a class="header" href="#what-will-happen-if-i-do-not-set-up-a-valid-federation-certificate-immediately">What will happen if I do not set up a valid federation certificate immediately?</a></h3>
- <p>Nothing initially, but once 1.0.0 is in the wild it will not be possible to
- federate with 1.0.0 servers.</p>
- <h3 id="what-will-happen-if-i-do-nothing-at-all"><a class="header" href="#what-will-happen-if-i-do-nothing-at-all">What will happen if I do nothing at all?</a></h3>
- <p>If the admin takes no action at all, and remains on a Synapse < 0.99.0 then the
- homeserver will be unable to federate with those who have implemented
- .well-known. Then, as above, once the month upgrade window has expired the
- homeserver will not be able to federate with any Synapse >= 1.0.0</p>
- <h3 id="when-do-i-need-a-srv-record-or-well-known-uri"><a class="header" href="#when-do-i-need-a-srv-record-or-well-known-uri">When do I need a SRV record or .well-known URI?</a></h3>
- <p>If your homeserver listens on the default federation port (8448), and your
- <code>server_name</code> points to the host that your homeserver runs on, you do not need an
- SRV record or <code>.well-known/matrix/server</code> URI.</p>
- <p>For instance, if you registered <code>example.com</code> and pointed its DNS A record at a
- fresh Upcloud VPS or similar, you could install Synapse 0.99 on that host,
- giving it a server_name of <code>example.com</code>, and it would automatically generate a
- valid TLS certificate for you via Let's Encrypt and no SRV record or
- <code>.well-known</code> URI would be needed.</p>
- <p>This is the common case, although you can add an SRV record or
- <code>.well-known/matrix/server</code> URI for completeness if you wish.</p>
- <p><strong>However</strong>, if your server does not listen on port 8448, or if your <code>server_name</code>
- does not point to the host that your homeserver runs on, you will need to let
- other servers know how to find it.</p>
- <p>In this case, you should see <a href="MSC1711_certificates_FAQ.html#if-you-do-have-an-srv-record-currently">"If you do have an SRV record
- currently"</a> above.</p>
- <h3 id="can-i-still-use-an-srv-record"><a class="header" href="#can-i-still-use-an-srv-record">Can I still use an SRV record?</a></h3>
- <p>Firstly, if you didn't need an SRV record before (because your server is
- listening on port 8448 of your server_name), you certainly don't need one now:
- the defaults are still the same.</p>
- <p>If you previously had an SRV record, you can keep using it provided you are
- able to give Synapse a TLS certificate corresponding to your server name. For
- example, suppose you had the following SRV record, which directs matrix traffic
- for example.com to matrix.example.com:443:</p>
- <pre><code>_matrix._tcp.example.com. IN SRV 10 5 443 matrix.example.com
- </code></pre>
- <p>In this case, Synapse must be given a certificate for example.com - or be
- configured to acquire one from Let's Encrypt.</p>
- <p>If you are unable to give Synapse a certificate for your server_name, you will
- also need to use a .well-known URI instead. However, see also "I have created a
- .well-known URI. Do I still need an SRV record?".</p>
- <h3 id="i-have-created-a-well-known-uri-do-i-still-need-an-srv-record"><a class="header" href="#i-have-created-a-well-known-uri-do-i-still-need-an-srv-record">I have created a .well-known URI. Do I still need an SRV record?</a></h3>
- <p>As of Synapse 0.99, Synapse will first check for the existence of a <code>.well-known</code>
- URI and follow any delegation it suggests. It will only then check for the
- existence of an SRV record.</p>
- <p>That means that the SRV record will often be redundant. However, you should
- remember that there may still be older versions of Synapse in the federation
- which do not understand <code>.well-known</code> URIs, so if you removed your SRV record you
- would no longer be able to federate with them.</p>
- <p>It is therefore best to leave the SRV record in place for now. Synapse 0.34 and
- earlier will follow the SRV record (and not care about the invalid
- certificate). Synapse 0.99 and later will follow the .well-known URI, with the
- correct certificate chain.</p>
- <h3 id="it-used-to-work-just-fine-why-are-you-breaking-everything"><a class="header" href="#it-used-to-work-just-fine-why-are-you-breaking-everything">It used to work just fine, why are you breaking everything?</a></h3>
- <p>We have always wanted Matrix servers to be as easy to set up as possible, and
- so back when we started federation in 2014 we didn't want admins to have to go
- through the cumbersome process of buying a valid TLS certificate to run a
- server. This was before Let's Encrypt came along and made getting a free and
- valid TLS certificate straightforward. So instead, we adopted a system based on
- <a href="https://en.wikipedia.org/wiki/Convergence_(SSL)">Perspectives</a>: an approach
- where you check a set of "notary servers" (in practice, homeservers) to vouch
- for the validity of a certificate rather than having it signed by a CA. As long
- as enough different notaries agree on the certificate's validity, then it is
- trusted.</p>
- <p>However, in practice this has never worked properly. Most people only use the
- default notary server (matrix.org), leading to inadvertent centralisation which
- we want to eliminate. Meanwhile, we never implemented the full consensus
- algorithm to query the servers participating in a room to determine consensus
- on whether a given certificate is valid. This is fiddly to get right
- (especially in face of sybil attacks), and we found ourselves questioning
- whether it was worth the effort to finish the work and commit to maintaining a
- secure certificate validation system as opposed to focusing on core Matrix
- development.</p>
- <p>Meanwhile, Let's Encrypt came along in 2016, and put the final nail in the
- coffin of the Perspectives project (which was already pretty dead). So, the
- Spec Core Team decided that a better approach would be to mandate valid TLS
- certificates for federation alongside the rest of the Web. More details can be
- found in
- <a href="https://github.com/matrix-org/matrix-doc/blob/master/proposals/1711-x509-for-federation.md#background-the-failure-of-the-perspectives-approach">MSC1711</a>.</p>
- <p>This results in a breaking change, which is disruptive, but absolutely critical
- for the security model. However, the existence of Let's Encrypt as a trivial
- way to replace the old self-signed certificates with valid CA-signed ones helps
- smooth things over massively, especially as Synapse can now automate Let's
- Encrypt certificate generation if needed.</p>
- <h3 id="can-i-manage-my-own-certificates-rather-than-having-synapse-renew-certificates-itself"><a class="header" href="#can-i-manage-my-own-certificates-rather-than-having-synapse-renew-certificates-itself">Can I manage my own certificates rather than having Synapse renew certificates itself?</a></h3>
- <p>Yes, you are welcome to manage your certificates yourself. Synapse will only
- attempt to obtain certificates from Let's Encrypt if you configure it to do
- so.The only requirement is that there is a valid TLS cert present for
- federation end points.</p>
- <h3 id="do-you-still-recommend-against-using-a-reverse-proxy-on-the-federation-port-1"><a class="header" href="#do-you-still-recommend-against-using-a-reverse-proxy-on-the-federation-port-1">Do you still recommend against using a reverse proxy on the federation port?</a></h3>
- <p>We no longer actively recommend against using a reverse proxy. Many admins will
- find it easier to direct federation traffic to a reverse proxy and manage their
- own TLS certificates, and this is a supported configuration.</p>
- <p>See <a href="reverse_proxy.html">the reverse proxy documentation</a> for information on setting up a
- reverse proxy.</p>
- <h3 id="do-i-still-need-to-give-my-tls-certificates-to-synapse-if-i-am-using-a-reverse-proxy-1"><a class="header" href="#do-i-still-need-to-give-my-tls-certificates-to-synapse-if-i-am-using-a-reverse-proxy-1">Do I still need to give my TLS certificates to Synapse if I am using a reverse proxy?</a></h3>
- <p>Practically speaking, this is no longer necessary.</p>
- <p>If you are using a reverse proxy for all of your TLS traffic, then you can set
- <code>no_tls: True</code>. In that case, the only reason Synapse needs the certificate is
- to populate a legacy 'tls_fingerprints' field in the federation API. This is
- ignored by Synapse 0.99.0 and later, and the only time pre-0.99 Synapses will
- check it is when attempting to fetch the server keys - and generally this is
- delegated via <code>matrix.org</code>, which is on 0.99.0.</p>
- <p>However, there is a bug in Synapse 0.99.0
- <a href="https://github.com/matrix-org/synapse/issues/4554">4554</a> which prevents
- Synapse from starting if you do not give it a TLS certificate. To work around
- this, you can give it any TLS certificate at all. This will be fixed soon.</p>
- <h3 id="do-i-need-the-same-certificate-for-the-client-and-federation-port-1"><a class="header" href="#do-i-need-the-same-certificate-for-the-client-and-federation-port-1">Do I need the same certificate for the client and federation port?</a></h3>
- <p>No. There is nothing stopping you from using different certificates,
- particularly if you are using a reverse proxy. However, Synapse will use the
- same certificate on any ports where TLS is configured.</p>
- <h3 id="how-do-i-tell-synapse-to-reload-my-keyscertificates-after-i-replace-them"><a class="header" href="#how-do-i-tell-synapse-to-reload-my-keyscertificates-after-i-replace-them">How do I tell Synapse to reload my keys/certificates after I replace them?</a></h3>
- <p>Synapse will reload the keys and certificates when it receives a SIGHUP - for
- example <code>kill -HUP $(cat homeserver.pid)</code>. Alternatively, simply restart
- Synapse, though this will result in downtime while it restarts.</p>
- <div style="break-before: page; page-break-before: always;"></div><h1 id="setting-up-federation"><a class="header" href="#setting-up-federation">Setting up federation</a></h1>
- <p>Federation is the process by which users on different servers can participate
- in the same room. For this to work, those other servers must be able to contact
- yours to send messages.</p>
- <p>The <code>server_name</code> configured in the Synapse configuration file (often
- <code>homeserver.yaml</code>) defines how resources (users, rooms, etc.) will be
- identified (eg: <code>@user:example.com</code>, <code>#room:example.com</code>). By default,
- it is also the domain that other servers will use to try to reach your
- server (via port 8448). This is easy to set up and will work provided
- you set the <code>server_name</code> to match your machine's public DNS hostname.</p>
- <p>For this default configuration to work, you will need to listen for TLS
- connections on port 8448. The preferred way to do that is by using a
- reverse proxy: see <a href="reverse_proxy.html">the reverse proxy documentation</a> for instructions
- on how to correctly set one up.</p>
- <p>In some cases you might not want to run Synapse on the machine that has
- the <code>server_name</code> as its public DNS hostname, or you might want federation
- traffic to use a different port than 8448. For example, you might want to
- have your user names look like <code>@user:example.com</code>, but you want to run
- Synapse on <code>synapse.example.com</code> on port 443. This can be done using
- delegation, which allows an admin to control where federation traffic should
- be sent. See <a href="delegate.html">the delegation documentation</a> for instructions on how to set this up.</p>
- <p>Once federation has been configured, you should be able to join a room over
- federation. A good place to start is <code>#synapse:matrix.org</code> - a room for
- Synapse admins.</p>
- <h2 id="troubleshooting-2"><a class="header" href="#troubleshooting-2">Troubleshooting</a></h2>
- <p>You can use the <a href="https://matrix.org/federationtester">federation tester</a>
- to check if your homeserver is configured correctly. Alternatively try the
- <a href="https://matrix.org/federationtester/api/report?server_name=DOMAIN">JSON API used by the federation tester</a>.
- Note that you'll have to modify this URL to replace <code>DOMAIN</code> with your
- <code>server_name</code>. Hitting the API directly provides extra detail.</p>
- <p>The typical failure mode for federation is that when the server tries to join
- a room, it is rejected with "401: Unauthorized". Generally this means that other
- servers in the room could not access yours. (Joining a room over federation is
- a complicated dance which requires connections in both directions).</p>
- <p>Another common problem is that people on other servers can't join rooms that
- you invite them to. This can be caused by an incorrectly-configured reverse
- proxy: see <a href="reverse_proxy.html">the reverse proxy documentation</a> for instructions on how
- to correctly configure a reverse proxy.</p>
- <h3 id="known-issues"><a class="header" href="#known-issues">Known issues</a></h3>
- <p><strong>HTTP <code>308 Permanent Redirect</code> redirects are not followed</strong>: Due to missing features
- in the HTTP library used by Synapse, 308 redirects are currently not followed by
- federating servers, which can cause <code>M_UNKNOWN</code> or <code>401 Unauthorized</code> errors. This
- may affect users who are redirecting apex-to-www (e.g. <code>example.com</code> -> <code>www.example.com</code>),
- and especially users of the Kubernetes <em>Nginx Ingress</em> module, which uses 308 redirect
- codes by default. For those Kubernetes users, <a href="https://stackoverflow.com/a/52617528/5096871">this Stackoverflow post</a>
- might be helpful. For other users, switching to a <code>301 Moved Permanently</code> code may be
- an option. 308 redirect codes will be supported properly in a future
- release of Synapse.</p>
- <h2 id="running-a-demo-federation-of-synapses"><a class="header" href="#running-a-demo-federation-of-synapses">Running a demo federation of Synapses</a></h2>
- <p>If you want to get up and running quickly with a trio of homeservers in a
- private federation, there is a script in the <code>demo</code> directory. This is mainly
- useful just for development purposes. See <a href="https://github.com/matrix-org/synapse/tree/develop/demo/">demo/README</a>.</p>
- <div style="break-before: page; page-break-before: always;"></div><h1 id="configuration-1"><a class="header" href="#configuration-1">Configuration</a></h1>
- <p>This section contains information on tweaking Synapse via the various options in the configuration file. A configuration
- file should have been generated when you <a href="usage/configuration/../../setup/installation.html">installed Synapse</a>.</p>
- <div style="break-before: page; page-break-before: always;"></div><h1 id="homeserver-sample-configuration-file"><a class="header" href="#homeserver-sample-configuration-file">Homeserver Sample Configuration File</a></h1>
- <p>Below is a sample homeserver configuration file. The homeserver configuration file
- can be tweaked to change the behaviour of your homeserver. A restart of the server is
- generally required to apply any changes made to this file.</p>
- <p>Note that the contents below are <em>not</em> intended to be copied and used as the basis for
- a real homeserver.yaml. Instead, if you are starting from scratch, please generate
- a fresh config using Synapse by following the instructions in
- <a href="usage/configuration/../../setup/installation.html">Installation</a>.</p>
- <pre><code class="language-yaml"># This file is maintained as an up-to-date snapshot of the default
- # homeserver.yaml configuration generated by Synapse.
- #
- # It is intended to act as a reference for the default configuration,
- # helping admins keep track of new options and other changes, and compare
- # their configs with the current default. As such, many of the actual
- # config values shown are placeholders.
- #
- # It is *not* intended to be copied and used as the basis for a real
- # homeserver.yaml. Instead, if you are starting from scratch, please generate
- # a fresh config using Synapse by following the instructions in
- # https://matrix-org.github.io/synapse/latest/setup/installation.html.
- # Configuration options that take a time period can be set using a number
- # followed by a letter. Letters have the following meanings:
- # s = second
- # m = minute
- # h = hour
- # d = day
- # w = week
- # y = year
- # For example, setting redaction_retention_period: 5m would remove redacted
- # messages from the database after 5 minutes, rather than 5 months.
- ################################################################################
- # Configuration file for Synapse.
- #
- # This is a YAML file: see [1] for a quick introduction. Note in particular
- # that *indentation is important*: all the elements of a list or dictionary
- # should have the same indentation.
- #
- # [1] https://docs.ansible.com/ansible/latest/reference_appendices/YAMLSyntax.html
- ## Modules ##
- # Server admins can expand Synapse's functionality with external modules.
- #
- # See https://matrix-org.github.io/synapse/latest/modules.html for more
- # documentation on how to configure or create custom modules for Synapse.
- #
- modules:
- # - module: my_super_module.MySuperClass
- # config:
- # do_thing: true
- # - module: my_other_super_module.SomeClass
- # config: {}
- ## Server ##
- # The public-facing domain of the server
- #
- # The server_name name will appear at the end of usernames and room addresses
- # created on this server. For example if the server_name was example.com,
- # usernames on this server would be in the format @user:example.com
- #
- # In most cases you should avoid using a matrix specific subdomain such as
- # matrix.example.com or synapse.example.com as the server_name for the same
- # reasons you wouldn't use user@email.example.com as your email address.
- # See https://matrix-org.github.io/synapse/latest/delegate.html
- # for information on how to host Synapse on a subdomain while preserving
- # a clean server_name.
- #
- # The server_name cannot be changed later so it is important to
- # configure this correctly before you start Synapse. It should be all
- # lowercase and may contain an explicit port.
- # Examples: matrix.org, localhost:8080
- #
- server_name: "SERVERNAME"
- # When running as a daemon, the file to store the pid in
- #
- pid_file: DATADIR/homeserver.pid
- # The absolute URL to the web client which /_matrix/client will redirect
- # to if 'webclient' is configured under the 'listeners' configuration.
- #
- # This option can be also set to the filesystem path to the web client
- # which will be served at /_matrix/client/ if 'webclient' is configured
- # under the 'listeners' configuration, however this is a security risk:
- # https://github.com/matrix-org/synapse#security-note
- #
- #web_client_location: https://riot.example.com/
- # The public-facing base URL that clients use to access this Homeserver (not
- # including _matrix/...). This is the same URL a user might enter into the
- # 'Custom Homeserver URL' field on their client. If you use Synapse with a
- # reverse proxy, this should be the URL to reach Synapse via the proxy.
- # Otherwise, it should be the URL to reach Synapse's client HTTP listener (see
- # 'listeners' below).
- #
- #public_baseurl: https://example.com/
- # Set the soft limit on the number of file descriptors synapse can use
- # Zero is used to indicate synapse should set the soft limit to the
- # hard limit.
- #
- #soft_file_limit: 0
- # Presence tracking allows users to see the state (e.g online/offline)
- # of other local and remote users.
- #
- presence:
- # Uncomment to disable presence tracking on this homeserver. This option
- # replaces the previous top-level 'use_presence' option.
- #
- #enabled: false
- # Presence routers are third-party modules that can specify additional logic
- # to where presence updates from users are routed.
- #
- presence_router:
- # The custom module's class. Uncomment to use a custom presence router module.
- #
- #module: "my_custom_router.PresenceRouter"
- # Configuration options of the custom module. Refer to your module's
- # documentation for available options.
- #
- #config:
- # example_option: 'something'
- # Whether to require authentication to retrieve profile data (avatars,
- # display names) of other users through the client API. Defaults to
- # 'false'. Note that profile data is also available via the federation
- # API, unless allow_profile_lookup_over_federation is set to false.
- #
- #require_auth_for_profile_requests: true
- # Uncomment to require a user to share a room with another user in order
- # to retrieve their profile information. Only checked on Client-Server
- # requests. Profile requests from other servers should be checked by the
- # requesting server. Defaults to 'false'.
- #
- #limit_profile_requests_to_users_who_share_rooms: true
- # Uncomment to prevent a user's profile data from being retrieved and
- # displayed in a room until they have joined it. By default, a user's
- # profile data is included in an invite event, regardless of the values
- # of the above two settings, and whether or not the users share a server.
- # Defaults to 'true'.
- #
- #include_profile_data_on_invite: false
- # If set to 'true', removes the need for authentication to access the server's
- # public rooms directory through the client API, meaning that anyone can
- # query the room directory. Defaults to 'false'.
- #
- #allow_public_rooms_without_auth: true
- # If set to 'true', allows any other homeserver to fetch the server's public
- # rooms directory via federation. Defaults to 'false'.
- #
- #allow_public_rooms_over_federation: true
- # The default room version for newly created rooms.
- #
- # Known room versions are listed here:
- # https://matrix.org/docs/spec/#complete-list-of-room-versions
- #
- # For example, for room version 1, default_room_version should be set
- # to "1".
- #
- #default_room_version: "6"
- # The GC threshold parameters to pass to `gc.set_threshold`, if defined
- #
- #gc_thresholds: [700, 10, 10]
- # The minimum time in seconds between each GC for a generation, regardless of
- # the GC thresholds. This ensures that we don't do GC too frequently.
- #
- # A value of `[1s, 10s, 30s]` indicates that a second must pass between consecutive
- # generation 0 GCs, etc.
- #
- # Defaults to `[1s, 10s, 30s]`.
- #
- #gc_min_interval: [0.5s, 30s, 1m]
- # Set the limit on the returned events in the timeline in the get
- # and sync operations. The default value is 100. -1 means no upper limit.
- #
- # Uncomment the following to increase the limit to 5000.
- #
- #filter_timeline_limit: 5000
- # Whether room invites to users on this server should be blocked
- # (except those sent by local server admins). The default is False.
- #
- #block_non_admin_invites: true
- # Room searching
- #
- # If disabled, new messages will not be indexed for searching and users
- # will receive errors when searching for messages. Defaults to enabled.
- #
- #enable_search: false
- # Prevent outgoing requests from being sent to the following blacklisted IP address
- # CIDR ranges. If this option is not specified then it defaults to private IP
- # address ranges (see the example below).
- #
- # The blacklist applies to the outbound requests for federation, identity servers,
- # push servers, and for checking key validity for third-party invite events.
- #
- # (0.0.0.0 and :: are always blacklisted, whether or not they are explicitly
- # listed here, since they correspond to unroutable addresses.)
- #
- # This option replaces federation_ip_range_blacklist in Synapse v1.25.0.
- #
- #ip_range_blacklist:
- # - '127.0.0.0/8'
- # - '10.0.0.0/8'
- # - '172.16.0.0/12'
- # - '192.168.0.0/16'
- # - '100.64.0.0/10'
- # - '192.0.0.0/24'
- # - '169.254.0.0/16'
- # - '192.88.99.0/24'
- # - '198.18.0.0/15'
- # - '192.0.2.0/24'
- # - '198.51.100.0/24'
- # - '203.0.113.0/24'
- # - '224.0.0.0/4'
- # - '::1/128'
- # - 'fe80::/10'
- # - 'fc00::/7'
- # - '2001:db8::/32'
- # - 'ff00::/8'
- # - 'fec0::/10'
- # List of IP address CIDR ranges that should be allowed for federation,
- # identity servers, push servers, and for checking key validity for
- # third-party invite events. This is useful for specifying exceptions to
- # wide-ranging blacklisted target IP ranges - e.g. for communication with
- # a push server only visible in your network.
- #
- # This whitelist overrides ip_range_blacklist and defaults to an empty
- # list.
- #
- #ip_range_whitelist:
- # - '192.168.1.1'
- # List of ports that Synapse should listen on, their purpose and their
- # configuration.
- #
- # Options for each listener include:
- #
- # port: the TCP port to bind to
- #
- # bind_addresses: a list of local addresses to listen on. The default is
- # 'all local interfaces'.
- #
- # type: the type of listener. Normally 'http', but other valid options are:
- # 'manhole' (see https://matrix-org.github.io/synapse/latest/manhole.html),
- # 'metrics' (see https://matrix-org.github.io/synapse/latest/metrics-howto.html),
- # 'replication' (see https://matrix-org.github.io/synapse/latest/workers.html).
- #
- # tls: set to true to enable TLS for this listener. Will use the TLS
- # key/cert specified in tls_private_key_path / tls_certificate_path.
- #
- # x_forwarded: Only valid for an 'http' listener. Set to true to use the
- # X-Forwarded-For header as the client IP. Useful when Synapse is
- # behind a reverse-proxy.
- #
- # resources: Only valid for an 'http' listener. A list of resources to host
- # on this port. Options for each resource are:
- #
- # names: a list of names of HTTP resources. See below for a list of
- # valid resource names.
- #
- # compress: set to true to enable HTTP compression for this resource.
- #
- # additional_resources: Only valid for an 'http' listener. A map of
- # additional endpoints which should be loaded via dynamic modules.
- #
- # Valid resource names are:
- #
- # client: the client-server API (/_matrix/client), and the synapse admin
- # API (/_synapse/admin). Also implies 'media' and 'static'.
- #
- # consent: user consent forms (/_matrix/consent).
- # See https://matrix-org.github.io/synapse/latest/consent_tracking.html.
- #
- # federation: the server-server API (/_matrix/federation). Also implies
- # 'media', 'keys', 'openid'
- #
- # keys: the key discovery API (/_matrix/keys).
- #
- # media: the media API (/_matrix/media).
- #
- # metrics: the metrics interface.
- # See https://matrix-org.github.io/synapse/latest/metrics-howto.html.
- #
- # openid: OpenID authentication.
- #
- # replication: the HTTP replication API (/_synapse/replication).
- # See https://matrix-org.github.io/synapse/latest/workers.html.
- #
- # static: static resources under synapse/static (/_matrix/static). (Mostly
- # useful for 'fallback authentication'.)
- #
- # webclient: A web client. Requires web_client_location to be set.
- #
- listeners:
- # TLS-enabled listener: for when matrix traffic is sent directly to synapse.
- #
- # Disabled by default. To enable it, uncomment the following. (Note that you
- # will also need to give Synapse a TLS key and certificate: see the TLS section
- # below.)
- #
- #- port: 8448
- # type: http
- # tls: true
- # resources:
- # - names: [client, federation]
- # Unsecure HTTP listener: for when matrix traffic passes through a reverse proxy
- # that unwraps TLS.
- #
- # If you plan to use a reverse proxy, please see
- # https://matrix-org.github.io/synapse/latest/reverse_proxy.html.
- #
- - port: 8008
- tls: false
- type: http
- x_forwarded: true
- bind_addresses: ['::1', '127.0.0.1']
- resources:
- - names: [client, federation]
- compress: false
- # example additional_resources:
- #
- #additional_resources:
- # "/_matrix/my/custom/endpoint":
- # module: my_module.CustomRequestHandler
- # config: {}
- # Turn on the twisted ssh manhole service on localhost on the given
- # port.
- #
- #- port: 9000
- # bind_addresses: ['::1', '127.0.0.1']
- # type: manhole
- # Forward extremities can build up in a room due to networking delays between
- # homeservers. Once this happens in a large room, calculation of the state of
- # that room can become quite expensive. To mitigate this, once the number of
- # forward extremities reaches a given threshold, Synapse will send an
- # org.matrix.dummy_event event, which will reduce the forward extremities
- # in the room.
- #
- # This setting defines the threshold (i.e. number of forward extremities in the
- # room) at which dummy events are sent. The default value is 10.
- #
- #dummy_events_threshold: 5
- ## Homeserver blocking ##
- # How to reach the server admin, used in ResourceLimitError
- #
- #admin_contact: 'mailto:admin@server.com'
- # Global blocking
- #
- #hs_disabled: false
- #hs_disabled_message: 'Human readable reason for why the HS is blocked'
- # Monthly Active User Blocking
- #
- # Used in cases where the admin or server owner wants to limit to the
- # number of monthly active users.
- #
- # 'limit_usage_by_mau' disables/enables monthly active user blocking. When
- # enabled and a limit is reached the server returns a 'ResourceLimitError'
- # with error type Codes.RESOURCE_LIMIT_EXCEEDED
- #
- # 'max_mau_value' is the hard limit of monthly active users above which
- # the server will start blocking user actions.
- #
- # 'mau_trial_days' is a means to add a grace period for active users. It
- # means that users must be active for this number of days before they
- # can be considered active and guards against the case where lots of users
- # sign up in a short space of time never to return after their initial
- # session.
- #
- # 'mau_limit_alerting' is a means of limiting client side alerting
- # should the mau limit be reached. This is useful for small instances
- # where the admin has 5 mau seats (say) for 5 specific people and no
- # interest increasing the mau limit further. Defaults to True, which
- # means that alerting is enabled
- #
- #limit_usage_by_mau: false
- #max_mau_value: 50
- #mau_trial_days: 2
- #mau_limit_alerting: false
- # If enabled, the metrics for the number of monthly active users will
- # be populated, however no one will be limited. If limit_usage_by_mau
- # is true, this is implied to be true.
- #
- #mau_stats_only: false
- # Sometimes the server admin will want to ensure certain accounts are
- # never blocked by mau checking. These accounts are specified here.
- #
- #mau_limit_reserved_threepids:
- # - medium: 'email'
- # address: 'reserved_user@example.com'
- # Used by phonehome stats to group together related servers.
- #server_context: context
- # Resource-constrained homeserver settings
- #
- # When this is enabled, the room "complexity" will be checked before a user
- # joins a new remote room. If it is above the complexity limit, the server will
- # disallow joining, or will instantly leave.
- #
- # Room complexity is an arbitrary measure based on factors such as the number of
- # users in the room.
- #
- limit_remote_rooms:
- # Uncomment to enable room complexity checking.
- #
- #enabled: true
- # the limit above which rooms cannot be joined. The default is 1.0.
- #
- #complexity: 0.5
- # override the error which is returned when the room is too complex.
- #
- #complexity_error: "This room is too complex."
- # allow server admins to join complex rooms. Default is false.
- #
- #admins_can_join: true
- # Whether to require a user to be in the room to add an alias to it.
- # Defaults to 'true'.
- #
- #require_membership_for_aliases: false
- # Whether to allow per-room membership profiles through the send of membership
- # events with profile information that differ from the target's global profile.
- # Defaults to 'true'.
- #
- #allow_per_room_profiles: false
- # How long to keep redacted events in unredacted form in the database. After
- # this period redacted events get replaced with their redacted form in the DB.
- #
- # Defaults to `7d`. Set to `null` to disable.
- #
- #redaction_retention_period: 28d
- # How long to track users' last seen time and IPs in the database.
- #
- # Defaults to `28d`. Set to `null` to disable clearing out of old rows.
- #
- #user_ips_max_age: 14d
- # Message retention policy at the server level.
- #
- # Room admins and mods can define a retention period for their rooms using the
- # 'm.room.retention' state event, and server admins can cap this period by setting
- # the 'allowed_lifetime_min' and 'allowed_lifetime_max' config options.
- #
- # If this feature is enabled, Synapse will regularly look for and purge events
- # which are older than the room's maximum retention period. Synapse will also
- # filter events received over federation so that events that should have been
- # purged are ignored and not stored again.
- #
- retention:
- # The message retention policies feature is disabled by default. Uncomment the
- # following line to enable it.
- #
- #enabled: true
- # Default retention policy. If set, Synapse will apply it to rooms that lack the
- # 'm.room.retention' state event. Currently, the value of 'min_lifetime' doesn't
- # matter much because Synapse doesn't take it into account yet.
- #
- #default_policy:
- # min_lifetime: 1d
- # max_lifetime: 1y
- # Retention policy limits. If set, and the state of a room contains a
- # 'm.room.retention' event in its state which contains a 'min_lifetime' or a
- # 'max_lifetime' that's out of these bounds, Synapse will cap the room's policy
- # to these limits when running purge jobs.
- #
- #allowed_lifetime_min: 1d
- #allowed_lifetime_max: 1y
- # Server admins can define the settings of the background jobs purging the
- # events which lifetime has expired under the 'purge_jobs' section.
- #
- # If no configuration is provided, a single job will be set up to delete expired
- # events in every room daily.
- #
- # Each job's configuration defines which range of message lifetimes the job
- # takes care of. For example, if 'shortest_max_lifetime' is '2d' and
- # 'longest_max_lifetime' is '3d', the job will handle purging expired events in
- # rooms whose state defines a 'max_lifetime' that's both higher than 2 days, and
- # lower than or equal to 3 days. Both the minimum and the maximum value of a
- # range are optional, e.g. a job with no 'shortest_max_lifetime' and a
- # 'longest_max_lifetime' of '3d' will handle every room with a retention policy
- # which 'max_lifetime' is lower than or equal to three days.
- #
- # The rationale for this per-job configuration is that some rooms might have a
- # retention policy with a low 'max_lifetime', where history needs to be purged
- # of outdated messages on a more frequent basis than for the rest of the rooms
- # (e.g. every 12h), but not want that purge to be performed by a job that's
- # iterating over every room it knows, which could be heavy on the server.
- #
- # If any purge job is configured, it is strongly recommended to have at least
- # a single job with neither 'shortest_max_lifetime' nor 'longest_max_lifetime'
- # set, or one job without 'shortest_max_lifetime' and one job without
- # 'longest_max_lifetime' set. Otherwise some rooms might be ignored, even if
- # 'allowed_lifetime_min' and 'allowed_lifetime_max' are set, because capping a
- # room's policy to these values is done after the policies are retrieved from
- # Synapse's database (which is done using the range specified in a purge job's
- # configuration).
- #
- #purge_jobs:
- # - longest_max_lifetime: 3d
- # interval: 12h
- # - shortest_max_lifetime: 3d
- # interval: 1d
- # Inhibits the /requestToken endpoints from returning an error that might leak
- # information about whether an e-mail address is in use or not on this
- # homeserver.
- # Note that for some endpoints the error situation is the e-mail already being
- # used, and for others the error is entering the e-mail being unused.
- # If this option is enabled, instead of returning an error, these endpoints will
- # act as if no error happened and return a fake session ID ('sid') to clients.
- #
- #request_token_inhibit_3pid_errors: true
- # A list of domains that the domain portion of 'next_link' parameters
- # must match.
- #
- # This parameter is optionally provided by clients while requesting
- # validation of an email or phone number, and maps to a link that
- # users will be automatically redirected to after validation
- # succeeds. Clients can make use this parameter to aid the validation
- # process.
- #
- # The whitelist is applied whether the homeserver or an
- # identity server is handling validation.
- #
- # The default value is no whitelist functionality; all domains are
- # allowed. Setting this value to an empty list will instead disallow
- # all domains.
- #
- #next_link_domain_whitelist: ["matrix.org"]
- ## TLS ##
- # PEM-encoded X509 certificate for TLS.
- # This certificate, as of Synapse 1.0, will need to be a valid and verifiable
- # certificate, signed by a recognised Certificate Authority.
- #
- # Be sure to use a `.pem` file that includes the full certificate chain including
- # any intermediate certificates (for instance, if using certbot, use
- # `fullchain.pem` as your certificate, not `cert.pem`).
- #
- #tls_certificate_path: "CONFDIR/SERVERNAME.tls.crt"
- # PEM-encoded private key for TLS
- #
- #tls_private_key_path: "CONFDIR/SERVERNAME.tls.key"
- # Whether to verify TLS server certificates for outbound federation requests.
- #
- # Defaults to `true`. To disable certificate verification, uncomment the
- # following line.
- #
- #federation_verify_certificates: false
- # The minimum TLS version that will be used for outbound federation requests.
- #
- # Defaults to `1`. Configurable to `1`, `1.1`, `1.2`, or `1.3`. Note
- # that setting this value higher than `1.2` will prevent federation to most
- # of the public Matrix network: only configure it to `1.3` if you have an
- # entirely private federation setup and you can ensure TLS 1.3 support.
- #
- #federation_client_minimum_tls_version: 1.2
- # Skip federation certificate verification on the following whitelist
- # of domains.
- #
- # This setting should only be used in very specific cases, such as
- # federation over Tor hidden services and similar. For private networks
- # of homeservers, you likely want to use a private CA instead.
- #
- # Only effective if federation_verify_certicates is `true`.
- #
- #federation_certificate_verification_whitelist:
- # - lon.example.com
- # - *.domain.com
- # - *.onion
- # List of custom certificate authorities for federation traffic.
- #
- # This setting should only normally be used within a private network of
- # homeservers.
- #
- # Note that this list will replace those that are provided by your
- # operating environment. Certificates must be in PEM format.
- #
- #federation_custom_ca_list:
- # - myCA1.pem
- # - myCA2.pem
- # - myCA3.pem
- ## Federation ##
- # Restrict federation to the following whitelist of domains.
- # N.B. we recommend also firewalling your federation listener to limit
- # inbound federation traffic as early as possible, rather than relying
- # purely on this application-layer restriction. If not specified, the
- # default is to whitelist everything.
- #
- #federation_domain_whitelist:
- # - lon.example.com
- # - nyc.example.com
- # - syd.example.com
- # Report prometheus metrics on the age of PDUs being sent to and received from
- # the following domains. This can be used to give an idea of "delay" on inbound
- # and outbound federation, though be aware that any delay can be due to problems
- # at either end or with the intermediate network.
- #
- # By default, no domains are monitored in this way.
- #
- #federation_metrics_domains:
- # - matrix.org
- # - example.com
- # Uncomment to disable profile lookup over federation. By default, the
- # Federation API allows other homeservers to obtain profile data of any user
- # on this homeserver. Defaults to 'true'.
- #
- #allow_profile_lookup_over_federation: false
- # Uncomment to disable device display name lookup over federation. By default, the
- # Federation API allows other homeservers to obtain device display names of any user
- # on this homeserver. Defaults to 'true'.
- #
- #allow_device_name_lookup_over_federation: false
- ## Caching ##
- # Caching can be configured through the following options.
- #
- # A cache 'factor' is a multiplier that can be applied to each of
- # Synapse's caches in order to increase or decrease the maximum
- # number of entries that can be stored.
- # The number of events to cache in memory. Not affected by
- # caches.global_factor.
- #
- #event_cache_size: 10K
- caches:
- # Controls the global cache factor, which is the default cache factor
- # for all caches if a specific factor for that cache is not otherwise
- # set.
- #
- # This can also be set by the "SYNAPSE_CACHE_FACTOR" environment
- # variable. Setting by environment variable takes priority over
- # setting through the config file.
- #
- # Defaults to 0.5, which will half the size of all caches.
- #
- #global_factor: 1.0
- # A dictionary of cache name to cache factor for that individual
- # cache. Overrides the global cache factor for a given cache.
- #
- # These can also be set through environment variables comprised
- # of "SYNAPSE_CACHE_FACTOR_" + the name of the cache in capital
- # letters and underscores. Setting by environment variable
- # takes priority over setting through the config file.
- # Ex. SYNAPSE_CACHE_FACTOR_GET_USERS_WHO_SHARE_ROOM_WITH_USER=2.0
- #
- # Some caches have '*' and other characters that are not
- # alphanumeric or underscores. These caches can be named with or
- # without the special characters stripped. For example, to specify
- # the cache factor for `*stateGroupCache*` via an environment
- # variable would be `SYNAPSE_CACHE_FACTOR_STATEGROUPCACHE=2.0`.
- #
- per_cache_factors:
- #get_users_who_share_room_with_user: 2.0
- # Controls how long an entry can be in a cache without having been
- # accessed before being evicted. Defaults to None, which means
- # entries are never evicted based on time.
- #
- #expiry_time: 30m
- ## Database ##
- # The 'database' setting defines the database that synapse uses to store all of
- # its data.
- #
- # 'name' gives the database engine to use: either 'sqlite3' (for SQLite) or
- # 'psycopg2' (for PostgreSQL).
- #
- # 'args' gives options which are passed through to the database engine,
- # except for options starting 'cp_', which are used to configure the Twisted
- # connection pool. For a reference to valid arguments, see:
- # * for sqlite: https://docs.python.org/3/library/sqlite3.html#sqlite3.connect
- # * for postgres: https://www.postgresql.org/docs/current/libpq-connect.html#LIBPQ-PARAMKEYWORDS
- # * for the connection pool: https://twistedmatrix.com/documents/current/api/twisted.enterprise.adbapi.ConnectionPool.html#__init__
- #
- #
- # Example SQLite configuration:
- #
- #database:
- # name: sqlite3
- # args:
- # database: /path/to/homeserver.db
- #
- #
- # Example Postgres configuration:
- #
- #database:
- # name: psycopg2
- # args:
- # user: synapse_user
- # password: secretpassword
- # database: synapse
- # host: localhost
- # port: 5432
- # cp_min: 5
- # cp_max: 10
- #
- # For more information on using Synapse with Postgres,
- # see https://matrix-org.github.io/synapse/latest/postgres.html.
- #
- database:
- name: sqlite3
- args:
- database: DATADIR/homeserver.db
- ## Logging ##
- # A yaml python logging config file as described by
- # https://docs.python.org/3.7/library/logging.config.html#configuration-dictionary-schema
- #
- log_config: "CONFDIR/SERVERNAME.log.config"
- ## Ratelimiting ##
- # Ratelimiting settings for client actions (registration, login, messaging).
- #
- # Each ratelimiting configuration is made of two parameters:
- # - per_second: number of requests a client can send per second.
- # - burst_count: number of requests a client can send before being throttled.
- #
- # Synapse currently uses the following configurations:
- # - one for messages that ratelimits sending based on the account the client
- # is using
- # - one for registration that ratelimits registration requests based on the
- # client's IP address.
- # - one for login that ratelimits login requests based on the client's IP
- # address.
- # - one for login that ratelimits login requests based on the account the
- # client is attempting to log into.
- # - one for login that ratelimits login requests based on the account the
- # client is attempting to log into, based on the amount of failed login
- # attempts for this account.
- # - one for ratelimiting redactions by room admins. If this is not explicitly
- # set then it uses the same ratelimiting as per rc_message. This is useful
- # to allow room admins to deal with abuse quickly.
- # - two for ratelimiting number of rooms a user can join, "local" for when
- # users are joining rooms the server is already in (this is cheap) vs
- # "remote" for when users are trying to join rooms not on the server (which
- # can be more expensive)
- # - one for ratelimiting how often a user or IP can attempt to validate a 3PID.
- # - two for ratelimiting how often invites can be sent in a room or to a
- # specific user.
- #
- # The defaults are as shown below.
- #
- #rc_message:
- # per_second: 0.2
- # burst_count: 10
- #
- #rc_registration:
- # per_second: 0.17
- # burst_count: 3
- #
- #rc_login:
- # address:
- # per_second: 0.17
- # burst_count: 3
- # account:
- # per_second: 0.17
- # burst_count: 3
- # failed_attempts:
- # per_second: 0.17
- # burst_count: 3
- #
- #rc_admin_redaction:
- # per_second: 1
- # burst_count: 50
- #
- #rc_joins:
- # local:
- # per_second: 0.1
- # burst_count: 10
- # remote:
- # per_second: 0.01
- # burst_count: 10
- #
- #rc_3pid_validation:
- # per_second: 0.003
- # burst_count: 5
- #
- #rc_invites:
- # per_room:
- # per_second: 0.3
- # burst_count: 10
- # per_user:
- # per_second: 0.003
- # burst_count: 5
- # Ratelimiting settings for incoming federation
- #
- # The rc_federation configuration is made up of the following settings:
- # - window_size: window size in milliseconds
- # - sleep_limit: number of federation requests from a single server in
- # a window before the server will delay processing the request.
- # - sleep_delay: duration in milliseconds to delay processing events
- # from remote servers by if they go over the sleep limit.
- # - reject_limit: maximum number of concurrent federation requests
- # allowed from a single server
- # - concurrent: number of federation requests to concurrently process
- # from a single server
- #
- # The defaults are as shown below.
- #
- #rc_federation:
- # window_size: 1000
- # sleep_limit: 10
- # sleep_delay: 500
- # reject_limit: 50
- # concurrent: 3
- # Target outgoing federation transaction frequency for sending read-receipts,
- # per-room.
- #
- # If we end up trying to send out more read-receipts, they will get buffered up
- # into fewer transactions.
- #
- #federation_rr_transactions_per_room_per_second: 50
- ## Media Store ##
- # Enable the media store service in the Synapse master. Uncomment the
- # following if you are using a separate media store worker.
- #
- #enable_media_repo: false
- # Directory where uploaded images and attachments are stored.
- #
- media_store_path: "DATADIR/media_store"
- # Media storage providers allow media to be stored in different
- # locations.
- #
- #media_storage_providers:
- # - module: file_system
- # # Whether to store newly uploaded local files
- # store_local: false
- # # Whether to store newly downloaded remote files
- # store_remote: false
- # # Whether to wait for successful storage for local uploads
- # store_synchronous: false
- # config:
- # directory: /mnt/some/other/directory
- # The largest allowed upload size in bytes
- #
- # If you are using a reverse proxy you may also need to set this value in
- # your reverse proxy's config. Notably Nginx has a small max body size by default.
- # See https://matrix-org.github.io/synapse/latest/reverse_proxy.html.
- #
- #max_upload_size: 50M
- # Maximum number of pixels that will be thumbnailed
- #
- #max_image_pixels: 32M
- # Whether to generate new thumbnails on the fly to precisely match
- # the resolution requested by the client. If true then whenever
- # a new resolution is requested by the client the server will
- # generate a new thumbnail. If false the server will pick a thumbnail
- # from a precalculated list.
- #
- #dynamic_thumbnails: false
- # List of thumbnails to precalculate when an image is uploaded.
- #
- #thumbnail_sizes:
- # - width: 32
- # height: 32
- # method: crop
- # - width: 96
- # height: 96
- # method: crop
- # - width: 320
- # height: 240
- # method: scale
- # - width: 640
- # height: 480
- # method: scale
- # - width: 800
- # height: 600
- # method: scale
- # Is the preview URL API enabled?
- #
- # 'false' by default: uncomment the following to enable it (and specify a
- # url_preview_ip_range_blacklist blacklist).
- #
- #url_preview_enabled: true
- # List of IP address CIDR ranges that the URL preview spider is denied
- # from accessing. There are no defaults: you must explicitly
- # specify a list for URL previewing to work. You should specify any
- # internal services in your network that you do not want synapse to try
- # to connect to, otherwise anyone in any Matrix room could cause your
- # synapse to issue arbitrary GET requests to your internal services,
- # causing serious security issues.
- #
- # (0.0.0.0 and :: are always blacklisted, whether or not they are explicitly
- # listed here, since they correspond to unroutable addresses.)
- #
- # This must be specified if url_preview_enabled is set. It is recommended that
- # you uncomment the following list as a starting point.
- #
- #url_preview_ip_range_blacklist:
- # - '127.0.0.0/8'
- # - '10.0.0.0/8'
- # - '172.16.0.0/12'
- # - '192.168.0.0/16'
- # - '100.64.0.0/10'
- # - '192.0.0.0/24'
- # - '169.254.0.0/16'
- # - '192.88.99.0/24'
- # - '198.18.0.0/15'
- # - '192.0.2.0/24'
- # - '198.51.100.0/24'
- # - '203.0.113.0/24'
- # - '224.0.0.0/4'
- # - '::1/128'
- # - 'fe80::/10'
- # - 'fc00::/7'
- # - '2001:db8::/32'
- # - 'ff00::/8'
- # - 'fec0::/10'
- # List of IP address CIDR ranges that the URL preview spider is allowed
- # to access even if they are specified in url_preview_ip_range_blacklist.
- # This is useful for specifying exceptions to wide-ranging blacklisted
- # target IP ranges - e.g. for enabling URL previews for a specific private
- # website only visible in your network.
- #
- #url_preview_ip_range_whitelist:
- # - '192.168.1.1'
- # Optional list of URL matches that the URL preview spider is
- # denied from accessing. You should use url_preview_ip_range_blacklist
- # in preference to this, otherwise someone could define a public DNS
- # entry that points to a private IP address and circumvent the blacklist.
- # This is more useful if you know there is an entire shape of URL that
- # you know that will never want synapse to try to spider.
- #
- # Each list entry is a dictionary of url component attributes as returned
- # by urlparse.urlsplit as applied to the absolute form of the URL. See
- # https://docs.python.org/2/library/urlparse.html#urlparse.urlsplit
- # The values of the dictionary are treated as an filename match pattern
- # applied to that component of URLs, unless they start with a ^ in which
- # case they are treated as a regular expression match. If all the
- # specified component matches for a given list item succeed, the URL is
- # blacklisted.
- #
- #url_preview_url_blacklist:
- # # blacklist any URL with a username in its URI
- # - username: '*'
- #
- # # blacklist all *.google.com URLs
- # - netloc: 'google.com'
- # - netloc: '*.google.com'
- #
- # # blacklist all plain HTTP URLs
- # - scheme: 'http'
- #
- # # blacklist http(s)://www.acme.com/foo
- # - netloc: 'www.acme.com'
- # path: '/foo'
- #
- # # blacklist any URL with a literal IPv4 address
- # - netloc: '^[0-9]+\.[0-9]+\.[0-9]+\.[0-9]+$'
- # The largest allowed URL preview spidering size in bytes
- #
- #max_spider_size: 10M
- # A list of values for the Accept-Language HTTP header used when
- # downloading webpages during URL preview generation. This allows
- # Synapse to specify the preferred languages that URL previews should
- # be in when communicating with remote servers.
- #
- # Each value is a IETF language tag; a 2-3 letter identifier for a
- # language, optionally followed by subtags separated by '-', specifying
- # a country or region variant.
- #
- # Multiple values can be provided, and a weight can be added to each by
- # using quality value syntax (;q=). '*' translates to any language.
- #
- # Defaults to "en".
- #
- # Example:
- #
- # url_preview_accept_language:
- # - en-UK
- # - en-US;q=0.9
- # - fr;q=0.8
- # - *;q=0.7
- #
- url_preview_accept_language:
- # - en
- ## Captcha ##
- # See docs/CAPTCHA_SETUP.md for full details of configuring this.
- # This homeserver's ReCAPTCHA public key. Must be specified if
- # enable_registration_captcha is enabled.
- #
- #recaptcha_public_key: "YOUR_PUBLIC_KEY"
- # This homeserver's ReCAPTCHA private key. Must be specified if
- # enable_registration_captcha is enabled.
- #
- #recaptcha_private_key: "YOUR_PRIVATE_KEY"
- # Uncomment to enable ReCaptcha checks when registering, preventing signup
- # unless a captcha is answered. Requires a valid ReCaptcha
- # public/private key. Defaults to 'false'.
- #
- #enable_registration_captcha: true
- # The API endpoint to use for verifying m.login.recaptcha responses.
- # Defaults to "https://www.recaptcha.net/recaptcha/api/siteverify".
- #
- #recaptcha_siteverify_api: "https://my.recaptcha.site"
- ## TURN ##
- # The public URIs of the TURN server to give to clients
- #
- #turn_uris: []
- # The shared secret used to compute passwords for the TURN server
- #
- #turn_shared_secret: "YOUR_SHARED_SECRET"
- # The Username and password if the TURN server needs them and
- # does not use a token
- #
- #turn_username: "TURNSERVER_USERNAME"
- #turn_password: "TURNSERVER_PASSWORD"
- # How long generated TURN credentials last
- #
- #turn_user_lifetime: 1h
- # Whether guests should be allowed to use the TURN server.
- # This defaults to True, otherwise VoIP will be unreliable for guests.
- # However, it does introduce a slight security risk as it allows users to
- # connect to arbitrary endpoints without having first signed up for a
- # valid account (e.g. by passing a CAPTCHA).
- #
- #turn_allow_guests: true
- ## Registration ##
- #
- # Registration can be rate-limited using the parameters in the "Ratelimiting"
- # section of this file.
- # Enable registration for new users.
- #
- #enable_registration: false
- # Time that a user's session remains valid for, after they log in.
- #
- # Note that this is not currently compatible with guest logins.
- #
- # Note also that this is calculated at login time: changes are not applied
- # retrospectively to users who have already logged in.
- #
- # By default, this is infinite.
- #
- #session_lifetime: 24h
- # The user must provide all of the below types of 3PID when registering.
- #
- #registrations_require_3pid:
- # - email
- # - msisdn
- # Explicitly disable asking for MSISDNs from the registration
- # flow (overrides registrations_require_3pid if MSISDNs are set as required)
- #
- #disable_msisdn_registration: true
- # Mandate that users are only allowed to associate certain formats of
- # 3PIDs with accounts on this server.
- #
- #allowed_local_3pids:
- # - medium: email
- # pattern: '^[^@]+@matrix\.org$'
- # - medium: email
- # pattern: '^[^@]+@vector\.im$'
- # - medium: msisdn
- # pattern: '\+44'
- # Enable 3PIDs lookup requests to identity servers from this server.
- #
- #enable_3pid_lookup: true
- # If set, allows registration of standard or admin accounts by anyone who
- # has the shared secret, even if registration is otherwise disabled.
- #
- #registration_shared_secret: <PRIVATE STRING>
- # Set the number of bcrypt rounds used to generate password hash.
- # Larger numbers increase the work factor needed to generate the hash.
- # The default number is 12 (which equates to 2^12 rounds).
- # N.B. that increasing this will exponentially increase the time required
- # to register or login - e.g. 24 => 2^24 rounds which will take >20 mins.
- #
- #bcrypt_rounds: 12
- # Allows users to register as guests without a password/email/etc, and
- # participate in rooms hosted on this server which have been made
- # accessible to anonymous users.
- #
- #allow_guest_access: false
- # The identity server which we suggest that clients should use when users log
- # in on this server.
- #
- # (By default, no suggestion is made, so it is left up to the client.
- # This setting is ignored unless public_baseurl is also set.)
- #
- #default_identity_server: https://matrix.org
- # Handle threepid (email/phone etc) registration and password resets through a set of
- # *trusted* identity servers. Note that this allows the configured identity server to
- # reset passwords for accounts!
- #
- # Be aware that if `email` is not set, and SMTP options have not been
- # configured in the email config block, registration and user password resets via
- # email will be globally disabled.
- #
- # Additionally, if `msisdn` is not set, registration and password resets via msisdn
- # will be disabled regardless, and users will not be able to associate an msisdn
- # identifier to their account. This is due to Synapse currently not supporting
- # any method of sending SMS messages on its own.
- #
- # To enable using an identity server for operations regarding a particular third-party
- # identifier type, set the value to the URL of that identity server as shown in the
- # examples below.
- #
- # Servers handling the these requests must answer the `/requestToken` endpoints defined
- # by the Matrix Identity Service API specification:
- # https://matrix.org/docs/spec/identity_service/latest
- #
- # If a delegate is specified, the config option public_baseurl must also be filled out.
- #
- account_threepid_delegates:
- #email: https://example.com # Delegate email sending to example.com
- #msisdn: http://localhost:8090 # Delegate SMS sending to this local process
- # Whether users are allowed to change their displayname after it has
- # been initially set. Useful when provisioning users based on the
- # contents of a third-party directory.
- #
- # Does not apply to server administrators. Defaults to 'true'
- #
- #enable_set_displayname: false
- # Whether users are allowed to change their avatar after it has been
- # initially set. Useful when provisioning users based on the contents
- # of a third-party directory.
- #
- # Does not apply to server administrators. Defaults to 'true'
- #
- #enable_set_avatar_url: false
- # Whether users can change the 3PIDs associated with their accounts
- # (email address and msisdn).
- #
- # Defaults to 'true'
- #
- #enable_3pid_changes: false
- # Users who register on this homeserver will automatically be joined
- # to these rooms.
- #
- # By default, any room aliases included in this list will be created
- # as a publicly joinable room when the first user registers for the
- # homeserver. This behaviour can be customised with the settings below.
- # If the room already exists, make certain it is a publicly joinable
- # room. The join rule of the room must be set to 'public'.
- #
- #auto_join_rooms:
- # - "#example:example.com"
- # Where auto_join_rooms are specified, setting this flag ensures that the
- # the rooms exist by creating them when the first user on the
- # homeserver registers.
- #
- # By default the auto-created rooms are publicly joinable from any federated
- # server. Use the autocreate_auto_join_rooms_federated and
- # autocreate_auto_join_room_preset settings below to customise this behaviour.
- #
- # Setting to false means that if the rooms are not manually created,
- # users cannot be auto-joined since they do not exist.
- #
- # Defaults to true. Uncomment the following line to disable automatically
- # creating auto-join rooms.
- #
- #autocreate_auto_join_rooms: false
- # Whether the auto_join_rooms that are auto-created are available via
- # federation. Only has an effect if autocreate_auto_join_rooms is true.
- #
- # Note that whether a room is federated cannot be modified after
- # creation.
- #
- # Defaults to true: the room will be joinable from other servers.
- # Uncomment the following to prevent users from other homeservers from
- # joining these rooms.
- #
- #autocreate_auto_join_rooms_federated: false
- # The room preset to use when auto-creating one of auto_join_rooms. Only has an
- # effect if autocreate_auto_join_rooms is true.
- #
- # This can be one of "public_chat", "private_chat", or "trusted_private_chat".
- # If a value of "private_chat" or "trusted_private_chat" is used then
- # auto_join_mxid_localpart must also be configured.
- #
- # Defaults to "public_chat", meaning that the room is joinable by anyone, including
- # federated servers if autocreate_auto_join_rooms_federated is true (the default).
- # Uncomment the following to require an invitation to join these rooms.
- #
- #autocreate_auto_join_room_preset: private_chat
- # The local part of the user id which is used to create auto_join_rooms if
- # autocreate_auto_join_rooms is true. If this is not provided then the
- # initial user account that registers will be used to create the rooms.
- #
- # The user id is also used to invite new users to any auto-join rooms which
- # are set to invite-only.
- #
- # It *must* be configured if autocreate_auto_join_room_preset is set to
- # "private_chat" or "trusted_private_chat".
- #
- # Note that this must be specified in order for new users to be correctly
- # invited to any auto-join rooms which have been set to invite-only (either
- # at the time of creation or subsequently).
- #
- # Note that, if the room already exists, this user must be joined and
- # have the appropriate permissions to invite new members.
- #
- #auto_join_mxid_localpart: system
- # When auto_join_rooms is specified, setting this flag to false prevents
- # guest accounts from being automatically joined to the rooms.
- #
- # Defaults to true.
- #
- #auto_join_rooms_for_guests: false
- ## Metrics ###
- # Enable collection and rendering of performance metrics
- #
- #enable_metrics: false
- # Enable sentry integration
- # NOTE: While attempts are made to ensure that the logs don't contain
- # any sensitive information, this cannot be guaranteed. By enabling
- # this option the sentry server may therefore receive sensitive
- # information, and it in turn may then diseminate sensitive information
- # through insecure notification channels if so configured.
- #
- #sentry:
- # dsn: "..."
- # Flags to enable Prometheus metrics which are not suitable to be
- # enabled by default, either for performance reasons or limited use.
- #
- metrics_flags:
- # Publish synapse_federation_known_servers, a gauge of the number of
- # servers this homeserver knows about, including itself. May cause
- # performance problems on large homeservers.
- #
- #known_servers: true
- # Whether or not to report anonymized homeserver usage statistics.
- #
- #report_stats: true|false
- # The endpoint to report the anonymized homeserver usage statistics to.
- # Defaults to https://matrix.org/report-usage-stats/push
- #
- #report_stats_endpoint: https://example.com/report-usage-stats/push
- ## API Configuration ##
- # Controls for the state that is shared with users who receive an invite
- # to a room
- #
- room_prejoin_state:
- # By default, the following state event types are shared with users who
- # receive invites to the room:
- #
- # - m.room.join_rules
- # - m.room.canonical_alias
- # - m.room.avatar
- # - m.room.encryption
- # - m.room.name
- # - m.room.create
- #
- # Uncomment the following to disable these defaults (so that only the event
- # types listed in 'additional_event_types' are shared). Defaults to 'false'.
- #
- #disable_default_event_types: true
- # Additional state event types to share with users when they are invited
- # to a room.
- #
- # By default, this list is empty (so only the default event types are shared).
- #
- #additional_event_types:
- # - org.example.custom.event.type
- # A list of application service config files to use
- #
- #app_service_config_files:
- # - app_service_1.yaml
- # - app_service_2.yaml
- # Uncomment to enable tracking of application service IP addresses. Implicitly
- # enables MAU tracking for application service users.
- #
- #track_appservice_user_ips: true
- # a secret which is used to sign access tokens. If none is specified,
- # the registration_shared_secret is used, if one is given; otherwise,
- # a secret key is derived from the signing key.
- #
- #macaroon_secret_key: <PRIVATE STRING>
- # a secret which is used to calculate HMACs for form values, to stop
- # falsification of values. Must be specified for the User Consent
- # forms to work.
- #
- #form_secret: <PRIVATE STRING>
- ## Signing Keys ##
- # Path to the signing key to sign messages with
- #
- signing_key_path: "CONFDIR/SERVERNAME.signing.key"
- # The keys that the server used to sign messages with but won't use
- # to sign new messages.
- #
- old_signing_keys:
- # For each key, `key` should be the base64-encoded public key, and
- # `expired_ts`should be the time (in milliseconds since the unix epoch) that
- # it was last used.
- #
- # It is possible to build an entry from an old signing.key file using the
- # `export_signing_key` script which is provided with synapse.
- #
- # For example:
- #
- #"ed25519:id": { key: "base64string", expired_ts: 123456789123 }
- # How long key response published by this server is valid for.
- # Used to set the valid_until_ts in /key/v2 APIs.
- # Determines how quickly servers will query to check which keys
- # are still valid.
- #
- #key_refresh_interval: 1d
- # The trusted servers to download signing keys from.
- #
- # When we need to fetch a signing key, each server is tried in parallel.
- #
- # Normally, the connection to the key server is validated via TLS certificates.
- # Additional security can be provided by configuring a `verify key`, which
- # will make synapse check that the response is signed by that key.
- #
- # This setting supercedes an older setting named `perspectives`. The old format
- # is still supported for backwards-compatibility, but it is deprecated.
- #
- # 'trusted_key_servers' defaults to matrix.org, but using it will generate a
- # warning on start-up. To suppress this warning, set
- # 'suppress_key_server_warning' to true.
- #
- # Options for each entry in the list include:
- #
- # server_name: the name of the server. required.
- #
- # verify_keys: an optional map from key id to base64-encoded public key.
- # If specified, we will check that the response is signed by at least
- # one of the given keys.
- #
- # accept_keys_insecurely: a boolean. Normally, if `verify_keys` is unset,
- # and federation_verify_certificates is not `true`, synapse will refuse
- # to start, because this would allow anyone who can spoof DNS responses
- # to masquerade as the trusted key server. If you know what you are doing
- # and are sure that your network environment provides a secure connection
- # to the key server, you can set this to `true` to override this
- # behaviour.
- #
- # An example configuration might look like:
- #
- #trusted_key_servers:
- # - server_name: "my_trusted_server.example.com"
- # verify_keys:
- # "ed25519:auto": "abcdefghijklmnopqrstuvwxyzabcdefghijklmopqr"
- # - server_name: "my_other_trusted_server.example.com"
- #
- trusted_key_servers:
- - server_name: "matrix.org"
- # Uncomment the following to disable the warning that is emitted when the
- # trusted_key_servers include 'matrix.org'. See above.
- #
- #suppress_key_server_warning: true
- # The signing keys to use when acting as a trusted key server. If not specified
- # defaults to the server signing key.
- #
- # Can contain multiple keys, one per line.
- #
- #key_server_signing_keys_path: "key_server_signing_keys.key"
- ## Single sign-on integration ##
- # The following settings can be used to make Synapse use a single sign-on
- # provider for authentication, instead of its internal password database.
- #
- # You will probably also want to set the following options to `false` to
- # disable the regular login/registration flows:
- # * enable_registration
- # * password_config.enabled
- #
- # You will also want to investigate the settings under the "sso" configuration
- # section below.
- # Enable SAML2 for registration and login. Uses pysaml2.
- #
- # At least one of `sp_config` or `config_path` must be set in this section to
- # enable SAML login.
- #
- # Once SAML support is enabled, a metadata file will be exposed at
- # https://<server>:<port>/_synapse/client/saml2/metadata.xml, which you may be able to
- # use to configure your SAML IdP with. Alternatively, you can manually configure
- # the IdP to use an ACS location of
- # https://<server>:<port>/_synapse/client/saml2/authn_response.
- #
- saml2_config:
- # `sp_config` is the configuration for the pysaml2 Service Provider.
- # See pysaml2 docs for format of config.
- #
- # Default values will be used for the 'entityid' and 'service' settings,
- # so it is not normally necessary to specify them unless you need to
- # override them.
- #
- sp_config:
- # Point this to the IdP's metadata. You must provide either a local
- # file via the `local` attribute or (preferably) a URL via the
- # `remote` attribute.
- #
- #metadata:
- # local: ["saml2/idp.xml"]
- # remote:
- # - url: https://our_idp/metadata.xml
- # Allowed clock difference in seconds between the homeserver and IdP.
- #
- # Uncomment the below to increase the accepted time difference from 0 to 3 seconds.
- #
- #accepted_time_diff: 3
- # By default, the user has to go to our login page first. If you'd like
- # to allow IdP-initiated login, set 'allow_unsolicited: true' in a
- # 'service.sp' section:
- #
- #service:
- # sp:
- # allow_unsolicited: true
- # The examples below are just used to generate our metadata xml, and you
- # may well not need them, depending on your setup. Alternatively you
- # may need a whole lot more detail - see the pysaml2 docs!
- #description: ["My awesome SP", "en"]
- #name: ["Test SP", "en"]
- #ui_info:
- # display_name:
- # - lang: en
- # text: "Display Name is the descriptive name of your service."
- # description:
- # - lang: en
- # text: "Description should be a short paragraph explaining the purpose of the service."
- # information_url:
- # - lang: en
- # text: "https://example.com/terms-of-service"
- # privacy_statement_url:
- # - lang: en
- # text: "https://example.com/privacy-policy"
- # keywords:
- # - lang: en
- # text: ["Matrix", "Element"]
- # logo:
- # - lang: en
- # text: "https://example.com/logo.svg"
- # width: "200"
- # height: "80"
- #organization:
- # name: Example com
- # display_name:
- # - ["Example co", "en"]
- # url: "http://example.com"
- #contact_person:
- # - given_name: Bob
- # sur_name: "the Sysadmin"
- # email_address": ["admin@example.com"]
- # contact_type": technical
- # Instead of putting the config inline as above, you can specify a
- # separate pysaml2 configuration file:
- #
- #config_path: "CONFDIR/sp_conf.py"
- # The lifetime of a SAML session. This defines how long a user has to
- # complete the authentication process, if allow_unsolicited is unset.
- # The default is 15 minutes.
- #
- #saml_session_lifetime: 5m
- # An external module can be provided here as a custom solution to
- # mapping attributes returned from a saml provider onto a matrix user.
- #
- user_mapping_provider:
- # The custom module's class. Uncomment to use a custom module.
- #
- #module: mapping_provider.SamlMappingProvider
- # Custom configuration values for the module. Below options are
- # intended for the built-in provider, they should be changed if
- # using a custom module. This section will be passed as a Python
- # dictionary to the module's `parse_config` method.
- #
- config:
- # The SAML attribute (after mapping via the attribute maps) to use
- # to derive the Matrix ID from. 'uid' by default.
- #
- # Note: This used to be configured by the
- # saml2_config.mxid_source_attribute option. If that is still
- # defined, its value will be used instead.
- #
- #mxid_source_attribute: displayName
- # The mapping system to use for mapping the saml attribute onto a
- # matrix ID.
- #
- # Options include:
- # * 'hexencode' (which maps unpermitted characters to '=xx')
- # * 'dotreplace' (which replaces unpermitted characters with
- # '.').
- # The default is 'hexencode'.
- #
- # Note: This used to be configured by the
- # saml2_config.mxid_mapping option. If that is still defined, its
- # value will be used instead.
- #
- #mxid_mapping: dotreplace
- # In previous versions of synapse, the mapping from SAML attribute to
- # MXID was always calculated dynamically rather than stored in a
- # table. For backwards- compatibility, we will look for user_ids
- # matching such a pattern before creating a new account.
- #
- # This setting controls the SAML attribute which will be used for this
- # backwards-compatibility lookup. Typically it should be 'uid', but if
- # the attribute maps are changed, it may be necessary to change it.
- #
- # The default is 'uid'.
- #
- #grandfathered_mxid_source_attribute: upn
- # It is possible to configure Synapse to only allow logins if SAML attributes
- # match particular values. The requirements can be listed under
- # `attribute_requirements` as shown below. All of the listed attributes must
- # match for the login to be permitted.
- #
- #attribute_requirements:
- # - attribute: userGroup
- # value: "staff"
- # - attribute: department
- # value: "sales"
- # If the metadata XML contains multiple IdP entities then the `idp_entityid`
- # option must be set to the entity to redirect users to.
- #
- # Most deployments only have a single IdP entity and so should omit this
- # option.
- #
- #idp_entityid: 'https://our_idp/entityid'
- # List of OpenID Connect (OIDC) / OAuth 2.0 identity providers, for registration
- # and login.
- #
- # Options for each entry include:
- #
- # idp_id: a unique identifier for this identity provider. Used internally
- # by Synapse; should be a single word such as 'github'.
- #
- # Note that, if this is changed, users authenticating via that provider
- # will no longer be recognised as the same user!
- #
- # (Use "oidc" here if you are migrating from an old "oidc_config"
- # configuration.)
- #
- # idp_name: A user-facing name for this identity provider, which is used to
- # offer the user a choice of login mechanisms.
- #
- # idp_icon: An optional icon for this identity provider, which is presented
- # by clients and Synapse's own IdP picker page. If given, must be an
- # MXC URI of the format mxc://<server-name>/<media-id>. (An easy way to
- # obtain such an MXC URI is to upload an image to an (unencrypted) room
- # and then copy the "url" from the source of the event.)
- #
- # idp_brand: An optional brand for this identity provider, allowing clients
- # to style the login flow according to the identity provider in question.
- # See the spec for possible options here.
- #
- # discover: set to 'false' to disable the use of the OIDC discovery mechanism
- # to discover endpoints. Defaults to true.
- #
- # issuer: Required. The OIDC issuer. Used to validate tokens and (if discovery
- # is enabled) to discover the provider's endpoints.
- #
- # client_id: Required. oauth2 client id to use.
- #
- # client_secret: oauth2 client secret to use. May be omitted if
- # client_secret_jwt_key is given, or if client_auth_method is 'none'.
- #
- # client_secret_jwt_key: Alternative to client_secret: details of a key used
- # to create a JSON Web Token to be used as an OAuth2 client secret. If
- # given, must be a dictionary with the following properties:
- #
- # key: a pem-encoded signing key. Must be a suitable key for the
- # algorithm specified. Required unless 'key_file' is given.
- #
- # key_file: the path to file containing a pem-encoded signing key file.
- # Required unless 'key' is given.
- #
- # jwt_header: a dictionary giving properties to include in the JWT
- # header. Must include the key 'alg', giving the algorithm used to
- # sign the JWT, such as "ES256", using the JWA identifiers in
- # RFC7518.
- #
- # jwt_payload: an optional dictionary giving properties to include in
- # the JWT payload. Normally this should include an 'iss' key.
- #
- # client_auth_method: auth method to use when exchanging the token. Valid
- # values are 'client_secret_basic' (default), 'client_secret_post' and
- # 'none'.
- #
- # scopes: list of scopes to request. This should normally include the "openid"
- # scope. Defaults to ["openid"].
- #
- # authorization_endpoint: the oauth2 authorization endpoint. Required if
- # provider discovery is disabled.
- #
- # token_endpoint: the oauth2 token endpoint. Required if provider discovery is
- # disabled.
- #
- # userinfo_endpoint: the OIDC userinfo endpoint. Required if discovery is
- # disabled and the 'openid' scope is not requested.
- #
- # jwks_uri: URI where to fetch the JWKS. Required if discovery is disabled and
- # the 'openid' scope is used.
- #
- # skip_verification: set to 'true' to skip metadata verification. Use this if
- # you are connecting to a provider that is not OpenID Connect compliant.
- # Defaults to false. Avoid this in production.
- #
- # user_profile_method: Whether to fetch the user profile from the userinfo
- # endpoint. Valid values are: 'auto' or 'userinfo_endpoint'.
- #
- # Defaults to 'auto', which fetches the userinfo endpoint if 'openid' is
- # included in 'scopes'. Set to 'userinfo_endpoint' to always fetch the
- # userinfo endpoint.
- #
- # allow_existing_users: set to 'true' to allow a user logging in via OIDC to
- # match a pre-existing account instead of failing. This could be used if
- # switching from password logins to OIDC. Defaults to false.
- #
- # user_mapping_provider: Configuration for how attributes returned from a OIDC
- # provider are mapped onto a matrix user. This setting has the following
- # sub-properties:
- #
- # module: The class name of a custom mapping module. Default is
- # 'synapse.handlers.oidc.JinjaOidcMappingProvider'.
- # See https://matrix-org.github.io/synapse/latest/sso_mapping_providers.html#openid-mapping-providers
- # for information on implementing a custom mapping provider.
- #
- # config: Configuration for the mapping provider module. This section will
- # be passed as a Python dictionary to the user mapping provider
- # module's `parse_config` method.
- #
- # For the default provider, the following settings are available:
- #
- # subject_claim: name of the claim containing a unique identifier
- # for the user. Defaults to 'sub', which OpenID Connect
- # compliant providers should provide.
- #
- # localpart_template: Jinja2 template for the localpart of the MXID.
- # If this is not set, the user will be prompted to choose their
- # own username (see 'sso_auth_account_details.html' in the 'sso'
- # section of this file).
- #
- # display_name_template: Jinja2 template for the display name to set
- # on first login. If unset, no displayname will be set.
- #
- # email_template: Jinja2 template for the email address of the user.
- # If unset, no email address will be added to the account.
- #
- # extra_attributes: a map of Jinja2 templates for extra attributes
- # to send back to the client during login.
- # Note that these are non-standard and clients will ignore them
- # without modifications.
- #
- # When rendering, the Jinja2 templates are given a 'user' variable,
- # which is set to the claims returned by the UserInfo Endpoint and/or
- # in the ID Token.
- #
- # It is possible to configure Synapse to only allow logins if certain attributes
- # match particular values in the OIDC userinfo. The requirements can be listed under
- # `attribute_requirements` as shown below. All of the listed attributes must
- # match for the login to be permitted. Additional attributes can be added to
- # userinfo by expanding the `scopes` section of the OIDC config to retrieve
- # additional information from the OIDC provider.
- #
- # If the OIDC claim is a list, then the attribute must match any value in the list.
- # Otherwise, it must exactly match the value of the claim. Using the example
- # below, the `family_name` claim MUST be "Stephensson", but the `groups`
- # claim MUST contain "admin".
- #
- # attribute_requirements:
- # - attribute: family_name
- # value: "Stephensson"
- # - attribute: groups
- # value: "admin"
- #
- # See https://matrix-org.github.io/synapse/latest/openid.html
- # for information on how to configure these options.
- #
- # For backwards compatibility, it is also possible to configure a single OIDC
- # provider via an 'oidc_config' setting. This is now deprecated and admins are
- # advised to migrate to the 'oidc_providers' format. (When doing that migration,
- # use 'oidc' for the idp_id to ensure that existing users continue to be
- # recognised.)
- #
- oidc_providers:
- # Generic example
- #
- #- idp_id: my_idp
- # idp_name: "My OpenID provider"
- # idp_icon: "mxc://example.com/mediaid"
- # discover: false
- # issuer: "https://accounts.example.com/"
- # client_id: "provided-by-your-issuer"
- # client_secret: "provided-by-your-issuer"
- # client_auth_method: client_secret_post
- # scopes: ["openid", "profile"]
- # authorization_endpoint: "https://accounts.example.com/oauth2/auth"
- # token_endpoint: "https://accounts.example.com/oauth2/token"
- # userinfo_endpoint: "https://accounts.example.com/userinfo"
- # jwks_uri: "https://accounts.example.com/.well-known/jwks.json"
- # skip_verification: true
- # user_mapping_provider:
- # config:
- # subject_claim: "id"
- # localpart_template: "{{ user.login }}"
- # display_name_template: "{{ user.name }}"
- # email_template: "{{ user.email }}"
- # attribute_requirements:
- # - attribute: userGroup
- # value: "synapseUsers"
- # Enable Central Authentication Service (CAS) for registration and login.
- #
- cas_config:
- # Uncomment the following to enable authorization against a CAS server.
- # Defaults to false.
- #
- #enabled: true
- # The URL of the CAS authorization endpoint.
- #
- #server_url: "https://cas-server.com"
- # The attribute of the CAS response to use as the display name.
- #
- # If unset, no displayname will be set.
- #
- #displayname_attribute: name
- # It is possible to configure Synapse to only allow logins if CAS attributes
- # match particular values. All of the keys in the mapping below must exist
- # and the values must match the given value. Alternately if the given value
- # is None then any value is allowed (the attribute just must exist).
- # All of the listed attributes must match for the login to be permitted.
- #
- #required_attributes:
- # userGroup: "staff"
- # department: None
- # Additional settings to use with single-sign on systems such as OpenID Connect,
- # SAML2 and CAS.
- #
- sso:
- # A list of client URLs which are whitelisted so that the user does not
- # have to confirm giving access to their account to the URL. Any client
- # whose URL starts with an entry in the following list will not be subject
- # to an additional confirmation step after the SSO login is completed.
- #
- # WARNING: An entry such as "https://my.client" is insecure, because it
- # will also match "https://my.client.evil.site", exposing your users to
- # phishing attacks from evil.site. To avoid this, include a slash after the
- # hostname: "https://my.client/".
- #
- # If public_baseurl is set, then the login fallback page (used by clients
- # that don't natively support the required login flows) is whitelisted in
- # addition to any URLs in this list.
- #
- # By default, this list is empty.
- #
- #client_whitelist:
- # - https://riot.im/develop
- # - https://my.custom.client/
- # Uncomment to keep a user's profile fields in sync with information from
- # the identity provider. Currently only syncing the displayname is
- # supported. Fields are checked on every SSO login, and are updated
- # if necessary.
- #
- # Note that enabling this option will override user profile information,
- # regardless of whether users have opted-out of syncing that
- # information when first signing in. Defaults to false.
- #
- #update_profile_information: true
- # Directory in which Synapse will try to find the template files below.
- # If not set, or the files named below are not found within the template
- # directory, default templates from within the Synapse package will be used.
- #
- # Synapse will look for the following templates in this directory:
- #
- # * HTML page to prompt the user to choose an Identity Provider during
- # login: 'sso_login_idp_picker.html'.
- #
- # This is only used if multiple SSO Identity Providers are configured.
- #
- # When rendering, this template is given the following variables:
- # * redirect_url: the URL that the user will be redirected to after
- # login.
- #
- # * server_name: the homeserver's name.
- #
- # * providers: a list of available Identity Providers. Each element is
- # an object with the following attributes:
- #
- # * idp_id: unique identifier for the IdP
- # * idp_name: user-facing name for the IdP
- # * idp_icon: if specified in the IdP config, an MXC URI for an icon
- # for the IdP
- # * idp_brand: if specified in the IdP config, a textual identifier
- # for the brand of the IdP
- #
- # The rendered HTML page should contain a form which submits its results
- # back as a GET request, with the following query parameters:
- #
- # * redirectUrl: the client redirect URI (ie, the `redirect_url` passed
- # to the template)
- #
- # * idp: the 'idp_id' of the chosen IDP.
- #
- # * HTML page to prompt new users to enter a userid and confirm other
- # details: 'sso_auth_account_details.html'. This is only shown if the
- # SSO implementation (with any user_mapping_provider) does not return
- # a localpart.
- #
- # When rendering, this template is given the following variables:
- #
- # * server_name: the homeserver's name.
- #
- # * idp: details of the SSO Identity Provider that the user logged in
- # with: an object with the following attributes:
- #
- # * idp_id: unique identifier for the IdP
- # * idp_name: user-facing name for the IdP
- # * idp_icon: if specified in the IdP config, an MXC URI for an icon
- # for the IdP
- # * idp_brand: if specified in the IdP config, a textual identifier
- # for the brand of the IdP
- #
- # * user_attributes: an object containing details about the user that
- # we received from the IdP. May have the following attributes:
- #
- # * display_name: the user's display_name
- # * emails: a list of email addresses
- #
- # The template should render a form which submits the following fields:
- #
- # * username: the localpart of the user's chosen user id
- #
- # * HTML page allowing the user to consent to the server's terms and
- # conditions. This is only shown for new users, and only if
- # `user_consent.require_at_registration` is set.
- #
- # When rendering, this template is given the following variables:
- #
- # * server_name: the homeserver's name.
- #
- # * user_id: the user's matrix proposed ID.
- #
- # * user_profile.display_name: the user's proposed display name, if any.
- #
- # * consent_version: the version of the terms that the user will be
- # shown
- #
- # * terms_url: a link to the page showing the terms.
- #
- # The template should render a form which submits the following fields:
- #
- # * accepted_version: the version of the terms accepted by the user
- # (ie, 'consent_version' from the input variables).
- #
- # * HTML page for a confirmation step before redirecting back to the client
- # with the login token: 'sso_redirect_confirm.html'.
- #
- # When rendering, this template is given the following variables:
- #
- # * redirect_url: the URL the user is about to be redirected to.
- #
- # * display_url: the same as `redirect_url`, but with the query
- # parameters stripped. The intention is to have a
- # human-readable URL to show to users, not to use it as
- # the final address to redirect to.
- #
- # * server_name: the homeserver's name.
- #
- # * new_user: a boolean indicating whether this is the user's first time
- # logging in.
- #
- # * user_id: the user's matrix ID.
- #
- # * user_profile.avatar_url: an MXC URI for the user's avatar, if any.
- # None if the user has not set an avatar.
- #
- # * user_profile.display_name: the user's display name. None if the user
- # has not set a display name.
- #
- # * HTML page which notifies the user that they are authenticating to confirm
- # an operation on their account during the user interactive authentication
- # process: 'sso_auth_confirm.html'.
- #
- # When rendering, this template is given the following variables:
- # * redirect_url: the URL the user is about to be redirected to.
- #
- # * description: the operation which the user is being asked to confirm
- #
- # * idp: details of the Identity Provider that we will use to confirm
- # the user's identity: an object with the following attributes:
- #
- # * idp_id: unique identifier for the IdP
- # * idp_name: user-facing name for the IdP
- # * idp_icon: if specified in the IdP config, an MXC URI for an icon
- # for the IdP
- # * idp_brand: if specified in the IdP config, a textual identifier
- # for the brand of the IdP
- #
- # * HTML page shown after a successful user interactive authentication session:
- # 'sso_auth_success.html'.
- #
- # Note that this page must include the JavaScript which notifies of a successful authentication
- # (see https://matrix.org/docs/spec/client_server/r0.6.0#fallback).
- #
- # This template has no additional variables.
- #
- # * HTML page shown after a user-interactive authentication session which
- # does not map correctly onto the expected user: 'sso_auth_bad_user.html'.
- #
- # When rendering, this template is given the following variables:
- # * server_name: the homeserver's name.
- # * user_id_to_verify: the MXID of the user that we are trying to
- # validate.
- #
- # * HTML page shown during single sign-on if a deactivated user (according to Synapse's database)
- # attempts to login: 'sso_account_deactivated.html'.
- #
- # This template has no additional variables.
- #
- # * HTML page to display to users if something goes wrong during the
- # OpenID Connect authentication process: 'sso_error.html'.
- #
- # When rendering, this template is given two variables:
- # * error: the technical name of the error
- # * error_description: a human-readable message for the error
- #
- # You can see the default templates at:
- # https://github.com/matrix-org/synapse/tree/master/synapse/res/templates
- #
- #template_dir: "res/templates"
- # JSON web token integration. The following settings can be used to make
- # Synapse JSON web tokens for authentication, instead of its internal
- # password database.
- #
- # Each JSON Web Token needs to contain a "sub" (subject) claim, which is
- # used as the localpart of the mxid.
- #
- # Additionally, the expiration time ("exp"), not before time ("nbf"),
- # and issued at ("iat") claims are validated if present.
- #
- # Note that this is a non-standard login type and client support is
- # expected to be non-existent.
- #
- # See https://matrix-org.github.io/synapse/latest/jwt.html.
- #
- #jwt_config:
- # Uncomment the following to enable authorization using JSON web
- # tokens. Defaults to false.
- #
- #enabled: true
- # This is either the private shared secret or the public key used to
- # decode the contents of the JSON web token.
- #
- # Required if 'enabled' is true.
- #
- #secret: "provided-by-your-issuer"
- # The algorithm used to sign the JSON web token.
- #
- # Supported algorithms are listed at
- # https://pyjwt.readthedocs.io/en/latest/algorithms.html
- #
- # Required if 'enabled' is true.
- #
- #algorithm: "provided-by-your-issuer"
- # The issuer to validate the "iss" claim against.
- #
- # Optional, if provided the "iss" claim will be required and
- # validated for all JSON web tokens.
- #
- #issuer: "provided-by-your-issuer"
- # A list of audiences to validate the "aud" claim against.
- #
- # Optional, if provided the "aud" claim will be required and
- # validated for all JSON web tokens.
- #
- # Note that if the "aud" claim is included in a JSON web token then
- # validation will fail without configuring audiences.
- #
- #audiences:
- # - "provided-by-your-issuer"
- password_config:
- # Uncomment to disable password login
- #
- #enabled: false
- # Uncomment to disable authentication against the local password
- # database. This is ignored if `enabled` is false, and is only useful
- # if you have other password_providers.
- #
- #localdb_enabled: false
- # Uncomment and change to a secret random string for extra security.
- # DO NOT CHANGE THIS AFTER INITIAL SETUP!
- #
- #pepper: "EVEN_MORE_SECRET"
- # Define and enforce a password policy. Each parameter is optional.
- # This is an implementation of MSC2000.
- #
- policy:
- # Whether to enforce the password policy.
- # Defaults to 'false'.
- #
- #enabled: true
- # Minimum accepted length for a password.
- # Defaults to 0.
- #
- #minimum_length: 15
- # Whether a password must contain at least one digit.
- # Defaults to 'false'.
- #
- #require_digit: true
- # Whether a password must contain at least one symbol.
- # A symbol is any character that's not a number or a letter.
- # Defaults to 'false'.
- #
- #require_symbol: true
- # Whether a password must contain at least one lowercase letter.
- # Defaults to 'false'.
- #
- #require_lowercase: true
- # Whether a password must contain at least one lowercase letter.
- # Defaults to 'false'.
- #
- #require_uppercase: true
- ui_auth:
- # The amount of time to allow a user-interactive authentication session
- # to be active.
- #
- # This defaults to 0, meaning the user is queried for their credentials
- # before every action, but this can be overridden to allow a single
- # validation to be re-used. This weakens the protections afforded by
- # the user-interactive authentication process, by allowing for multiple
- # (and potentially different) operations to use the same validation session.
- #
- # This is ignored for potentially "dangerous" operations (including
- # deactivating an account, modifying an account password, and
- # adding a 3PID).
- #
- # Uncomment below to allow for credential validation to last for 15
- # seconds.
- #
- #session_timeout: "15s"
- # Configuration for sending emails from Synapse.
- #
- email:
- # The hostname of the outgoing SMTP server to use. Defaults to 'localhost'.
- #
- #smtp_host: mail.server
- # The port on the mail server for outgoing SMTP. Defaults to 25.
- #
- #smtp_port: 587
- # Username/password for authentication to the SMTP server. By default, no
- # authentication is attempted.
- #
- #smtp_user: "exampleusername"
- #smtp_pass: "examplepassword"
- # Uncomment the following to require TLS transport security for SMTP.
- # By default, Synapse will connect over plain text, and will then switch to
- # TLS via STARTTLS *if the SMTP server supports it*. If this option is set,
- # Synapse will refuse to connect unless the server supports STARTTLS.
- #
- #require_transport_security: true
- # notif_from defines the "From" address to use when sending emails.
- # It must be set if email sending is enabled.
- #
- # The placeholder '%(app)s' will be replaced by the application name,
- # which is normally 'app_name' (below), but may be overridden by the
- # Matrix client application.
- #
- # Note that the placeholder must be written '%(app)s', including the
- # trailing 's'.
- #
- #notif_from: "Your Friendly %(app)s homeserver <noreply@example.com>"
- # app_name defines the default value for '%(app)s' in notif_from and email
- # subjects. It defaults to 'Matrix'.
- #
- #app_name: my_branded_matrix_server
- # Uncomment the following to enable sending emails for messages that the user
- # has missed. Disabled by default.
- #
- #enable_notifs: true
- # Uncomment the following to disable automatic subscription to email
- # notifications for new users. Enabled by default.
- #
- #notif_for_new_users: false
- # Custom URL for client links within the email notifications. By default
- # links will be based on "https://matrix.to".
- #
- # (This setting used to be called riot_base_url; the old name is still
- # supported for backwards-compatibility but is now deprecated.)
- #
- #client_base_url: "http://localhost/riot"
- # Configure the time that a validation email will expire after sending.
- # Defaults to 1h.
- #
- #validation_token_lifetime: 15m
- # The web client location to direct users to during an invite. This is passed
- # to the identity server as the org.matrix.web_client_location key. Defaults
- # to unset, giving no guidance to the identity server.
- #
- #invite_client_location: https://app.element.io
- # Directory in which Synapse will try to find the template files below.
- # If not set, or the files named below are not found within the template
- # directory, default templates from within the Synapse package will be used.
- #
- # Synapse will look for the following templates in this directory:
- #
- # * The contents of email notifications of missed events: 'notif_mail.html' and
- # 'notif_mail.txt'.
- #
- # * The contents of account expiry notice emails: 'notice_expiry.html' and
- # 'notice_expiry.txt'.
- #
- # * The contents of password reset emails sent by the homeserver:
- # 'password_reset.html' and 'password_reset.txt'
- #
- # * An HTML page that a user will see when they follow the link in the password
- # reset email. The user will be asked to confirm the action before their
- # password is reset: 'password_reset_confirmation.html'
- #
- # * HTML pages for success and failure that a user will see when they confirm
- # the password reset flow using the page above: 'password_reset_success.html'
- # and 'password_reset_failure.html'
- #
- # * The contents of address verification emails sent during registration:
- # 'registration.html' and 'registration.txt'
- #
- # * HTML pages for success and failure that a user will see when they follow
- # the link in an address verification email sent during registration:
- # 'registration_success.html' and 'registration_failure.html'
- #
- # * The contents of address verification emails sent when an address is added
- # to a Matrix account: 'add_threepid.html' and 'add_threepid.txt'
- #
- # * HTML pages for success and failure that a user will see when they follow
- # the link in an address verification email sent when an address is added
- # to a Matrix account: 'add_threepid_success.html' and
- # 'add_threepid_failure.html'
- #
- # You can see the default templates at:
- # https://github.com/matrix-org/synapse/tree/master/synapse/res/templates
- #
- #template_dir: "res/templates"
- # Subjects to use when sending emails from Synapse.
- #
- # The placeholder '%(app)s' will be replaced with the value of the 'app_name'
- # setting above, or by a value dictated by the Matrix client application.
- #
- # If a subject isn't overridden in this configuration file, the value used as
- # its example will be used.
- #
- #subjects:
- # Subjects for notification emails.
- #
- # On top of the '%(app)s' placeholder, these can use the following
- # placeholders:
- #
- # * '%(person)s', which will be replaced by the display name of the user(s)
- # that sent the message(s), e.g. "Alice and Bob".
- # * '%(room)s', which will be replaced by the name of the room the
- # message(s) have been sent to, e.g. "My super room".
- #
- # See the example provided for each setting to see which placeholder can be
- # used and how to use them.
- #
- # Subject to use to notify about one message from one or more user(s) in a
- # room which has a name.
- #message_from_person_in_room: "[%(app)s] You have a message on %(app)s from %(person)s in the %(room)s room..."
- #
- # Subject to use to notify about one message from one or more user(s) in a
- # room which doesn't have a name.
- #message_from_person: "[%(app)s] You have a message on %(app)s from %(person)s..."
- #
- # Subject to use to notify about multiple messages from one or more users in
- # a room which doesn't have a name.
- #messages_from_person: "[%(app)s] You have messages on %(app)s from %(person)s..."
- #
- # Subject to use to notify about multiple messages in a room which has a
- # name.
- #messages_in_room: "[%(app)s] You have messages on %(app)s in the %(room)s room..."
- #
- # Subject to use to notify about multiple messages in multiple rooms.
- #messages_in_room_and_others: "[%(app)s] You have messages on %(app)s in the %(room)s room and others..."
- #
- # Subject to use to notify about multiple messages from multiple persons in
- # multiple rooms. This is similar to the setting above except it's used when
- # the room in which the notification was triggered has no name.
- #messages_from_person_and_others: "[%(app)s] You have messages on %(app)s from %(person)s and others..."
- #
- # Subject to use to notify about an invite to a room which has a name.
- #invite_from_person_to_room: "[%(app)s] %(person)s has invited you to join the %(room)s room on %(app)s..."
- #
- # Subject to use to notify about an invite to a room which doesn't have a
- # name.
- #invite_from_person: "[%(app)s] %(person)s has invited you to chat on %(app)s..."
- # Subject for emails related to account administration.
- #
- # On top of the '%(app)s' placeholder, these one can use the
- # '%(server_name)s' placeholder, which will be replaced by the value of the
- # 'server_name' setting in your Synapse configuration.
- #
- # Subject to use when sending a password reset email.
- #password_reset: "[%(server_name)s] Password reset"
- #
- # Subject to use when sending a verification email to assert an address's
- # ownership.
- #email_validation: "[%(server_name)s] Validate your email"
- # Password providers allow homeserver administrators to integrate
- # their Synapse installation with existing authentication methods
- # ex. LDAP, external tokens, etc.
- #
- # For more information and known implementations, please see
- # https://matrix-org.github.io/synapse/latest/password_auth_providers.html
- #
- # Note: instances wishing to use SAML or CAS authentication should
- # instead use the `saml2_config` or `cas_config` options,
- # respectively.
- #
- password_providers:
- # # Example config for an LDAP auth provider
- # - module: "ldap_auth_provider.LdapAuthProvider"
- # config:
- # enabled: true
- # uri: "ldap://ldap.example.com:389"
- # start_tls: true
- # base: "ou=users,dc=example,dc=com"
- # attributes:
- # uid: "cn"
- # mail: "email"
- # name: "givenName"
- # #bind_dn:
- # #bind_password:
- # #filter: "(objectClass=posixAccount)"
- ## Push ##
- push:
- # Clients requesting push notifications can either have the body of
- # the message sent in the notification poke along with other details
- # like the sender, or just the event ID and room ID (`event_id_only`).
- # If clients choose the former, this option controls whether the
- # notification request includes the content of the event (other details
- # like the sender are still included). For `event_id_only` push, it
- # has no effect.
- #
- # For modern android devices the notification content will still appear
- # because it is loaded by the app. iPhone, however will send a
- # notification saying only that a message arrived and who it came from.
- #
- # The default value is "true" to include message details. Uncomment to only
- # include the event ID and room ID in push notification payloads.
- #
- #include_content: false
- # When a push notification is received, an unread count is also sent.
- # This number can either be calculated as the number of unread messages
- # for the user, or the number of *rooms* the user has unread messages in.
- #
- # The default value is "true", meaning push clients will see the number of
- # rooms with unread messages in them. Uncomment to instead send the number
- # of unread messages.
- #
- #group_unread_count_by_room: false
- ## Rooms ##
- # Controls whether locally-created rooms should be end-to-end encrypted by
- # default.
- #
- # Possible options are "all", "invite", and "off". They are defined as:
- #
- # * "all": any locally-created room
- # * "invite": any room created with the "private_chat" or "trusted_private_chat"
- # room creation presets
- # * "off": this option will take no effect
- #
- # The default value is "off".
- #
- # Note that this option will only affect rooms created after it is set. It
- # will also not affect rooms created by other servers.
- #
- #encryption_enabled_by_default_for_room_type: invite
- # Uncomment to allow non-server-admin users to create groups on this server
- #
- #enable_group_creation: true
- # If enabled, non server admins can only create groups with local parts
- # starting with this prefix
- #
- #group_creation_prefix: "unofficial_"
- # User Directory configuration
- #
- user_directory:
- # Defines whether users can search the user directory. If false then
- # empty responses are returned to all queries. Defaults to true.
- #
- # Uncomment to disable the user directory.
- #
- #enabled: false
- # Defines whether to search all users visible to your HS when searching
- # the user directory, rather than limiting to users visible in public
- # rooms. Defaults to false.
- #
- # If you set it true, you'll have to rebuild the user_directory search
- # indexes, see:
- # https://matrix-org.github.io/synapse/latest/user_directory.html
- #
- # Uncomment to return search results containing all known users, even if that
- # user does not share a room with the requester.
- #
- #search_all_users: true
- # Defines whether to prefer local users in search query results.
- # If True, local users are more likely to appear above remote users
- # when searching the user directory. Defaults to false.
- #
- # Uncomment to prefer local over remote users in user directory search
- # results.
- #
- #prefer_local_users: true
- # User Consent configuration
- #
- # for detailed instructions, see
- # https://matrix-org.github.io/synapse/latest/consent_tracking.html
- #
- # Parts of this section are required if enabling the 'consent' resource under
- # 'listeners', in particular 'template_dir' and 'version'.
- #
- # 'template_dir' gives the location of the templates for the HTML forms.
- # This directory should contain one subdirectory per language (eg, 'en', 'fr'),
- # and each language directory should contain the policy document (named as
- # '<version>.html') and a success page (success.html).
- #
- # 'version' specifies the 'current' version of the policy document. It defines
- # the version to be served by the consent resource if there is no 'v'
- # parameter.
- #
- # 'server_notice_content', if enabled, will send a user a "Server Notice"
- # asking them to consent to the privacy policy. The 'server_notices' section
- # must also be configured for this to work. Notices will *not* be sent to
- # guest users unless 'send_server_notice_to_guests' is set to true.
- #
- # 'block_events_error', if set, will block any attempts to send events
- # until the user consents to the privacy policy. The value of the setting is
- # used as the text of the error.
- #
- # 'require_at_registration', if enabled, will add a step to the registration
- # process, similar to how captcha works. Users will be required to accept the
- # policy before their account is created.
- #
- # 'policy_name' is the display name of the policy users will see when registering
- # for an account. Has no effect unless `require_at_registration` is enabled.
- # Defaults to "Privacy Policy".
- #
- #user_consent:
- # template_dir: res/templates/privacy
- # version: 1.0
- # server_notice_content:
- # msgtype: m.text
- # body: >-
- # To continue using this homeserver you must review and agree to the
- # terms and conditions at %(consent_uri)s
- # send_server_notice_to_guests: true
- # block_events_error: >-
- # To continue using this homeserver you must review and agree to the
- # terms and conditions at %(consent_uri)s
- # require_at_registration: false
- # policy_name: Privacy Policy
- #
- # Settings for local room and user statistics collection. See
- # https://matrix-org.github.io/synapse/latest/room_and_user_statistics.html.
- #
- stats:
- # Uncomment the following to disable room and user statistics. Note that doing
- # so may cause certain features (such as the room directory) not to work
- # correctly.
- #
- #enabled: false
- # Server Notices room configuration
- #
- # Uncomment this section to enable a room which can be used to send notices
- # from the server to users. It is a special room which cannot be left; notices
- # come from a special "notices" user id.
- #
- # If you uncomment this section, you *must* define the system_mxid_localpart
- # setting, which defines the id of the user which will be used to send the
- # notices.
- #
- # It's also possible to override the room name, the display name of the
- # "notices" user, and the avatar for the user.
- #
- #server_notices:
- # system_mxid_localpart: notices
- # system_mxid_display_name: "Server Notices"
- # system_mxid_avatar_url: "mxc://server.com/oumMVlgDnLYFaPVkExemNVVZ"
- # room_name: "Server Notices"
- # Uncomment to disable searching the public room list. When disabled
- # blocks searching local and remote room lists for local and remote
- # users by always returning an empty list for all queries.
- #
- #enable_room_list_search: false
- # The `alias_creation` option controls who's allowed to create aliases
- # on this server.
- #
- # The format of this option is a list of rules that contain globs that
- # match against user_id, room_id and the new alias (fully qualified with
- # server name). The action in the first rule that matches is taken,
- # which can currently either be "allow" or "deny".
- #
- # Missing user_id/room_id/alias fields default to "*".
- #
- # If no rules match the request is denied. An empty list means no one
- # can create aliases.
- #
- # Options for the rules include:
- #
- # user_id: Matches against the creator of the alias
- # alias: Matches against the alias being created
- # room_id: Matches against the room ID the alias is being pointed at
- # action: Whether to "allow" or "deny" the request if the rule matches
- #
- # The default is:
- #
- #alias_creation_rules:
- # - user_id: "*"
- # alias: "*"
- # room_id: "*"
- # action: allow
- # The `room_list_publication_rules` option controls who can publish and
- # which rooms can be published in the public room list.
- #
- # The format of this option is the same as that for
- # `alias_creation_rules`.
- #
- # If the room has one or more aliases associated with it, only one of
- # the aliases needs to match the alias rule. If there are no aliases
- # then only rules with `alias: *` match.
- #
- # If no rules match the request is denied. An empty list means no one
- # can publish rooms.
- #
- # Options for the rules include:
- #
- # user_id: Matches against the creator of the alias
- # room_id: Matches against the room ID being published
- # alias: Matches against any current local or canonical aliases
- # associated with the room
- # action: Whether to "allow" or "deny" the request if the rule matches
- #
- # The default is:
- #
- #room_list_publication_rules:
- # - user_id: "*"
- # alias: "*"
- # room_id: "*"
- # action: allow
- ## Opentracing ##
- # These settings enable opentracing, which implements distributed tracing.
- # This allows you to observe the causal chains of events across servers
- # including requests, key lookups etc., across any server running
- # synapse or any other other services which supports opentracing
- # (specifically those implemented with Jaeger).
- #
- opentracing:
- # tracing is disabled by default. Uncomment the following line to enable it.
- #
- #enabled: true
- # The list of homeservers we wish to send and receive span contexts and span baggage.
- # See https://matrix-org.github.io/synapse/latest/opentracing.html.
- #
- # This is a list of regexes which are matched against the server_name of the
- # homeserver.
- #
- # By default, it is empty, so no servers are matched.
- #
- #homeserver_whitelist:
- # - ".*"
- # A list of the matrix IDs of users whose requests will always be traced,
- # even if the tracing system would otherwise drop the traces due to
- # probabilistic sampling.
- #
- # By default, the list is empty.
- #
- #force_tracing_for_users:
- # - "@user1:server_name"
- # - "@user2:server_name"
- # Jaeger can be configured to sample traces at different rates.
- # All configuration options provided by Jaeger can be set here.
- # Jaeger's configuration is mostly related to trace sampling which
- # is documented here:
- # https://www.jaegertracing.io/docs/latest/sampling/.
- #
- #jaeger_config:
- # sampler:
- # type: const
- # param: 1
- # logging:
- # false
- ## Workers ##
- # Disables sending of outbound federation transactions on the main process.
- # Uncomment if using a federation sender worker.
- #
- #send_federation: false
- # It is possible to run multiple federation sender workers, in which case the
- # work is balanced across them.
- #
- # This configuration must be shared between all federation sender workers, and if
- # changed all federation sender workers must be stopped at the same time and then
- # started, to ensure that all instances are running with the same config (otherwise
- # events may be dropped).
- #
- #federation_sender_instances:
- # - federation_sender1
- # When using workers this should be a map from `worker_name` to the
- # HTTP replication listener of the worker, if configured.
- #
- #instance_map:
- # worker1:
- # host: localhost
- # port: 8034
- # Experimental: When using workers you can define which workers should
- # handle event persistence and typing notifications. Any worker
- # specified here must also be in the `instance_map`.
- #
- #stream_writers:
- # events: worker1
- # typing: worker1
- # The worker that is used to run background tasks (e.g. cleaning up expired
- # data). If not provided this defaults to the main process.
- #
- #run_background_tasks_on: worker1
- # A shared secret used by the replication APIs to authenticate HTTP requests
- # from workers.
- #
- # By default this is unused and traffic is not authenticated.
- #
- #worker_replication_secret: ""
- # Configuration for Redis when using workers. This *must* be enabled when
- # using workers (unless using old style direct TCP configuration).
- #
- redis:
- # Uncomment the below to enable Redis support.
- #
- #enabled: true
- # Optional host and port to use to connect to redis. Defaults to
- # localhost and 6379
- #
- #host: localhost
- #port: 6379
- # Optional password if configured on the Redis instance
- #
- #password: <secret_password>
- </code></pre>
- <div style="break-before: page; page-break-before: always;"></div><h1 id="logging-sample-configuration-file"><a class="header" href="#logging-sample-configuration-file">Logging Sample Configuration File</a></h1>
- <p>Below is a sample logging configuration file. This file can be tweaked to control how your
- homeserver will output logs. A restart of the server is generally required to apply any
- changes made to this file.</p>
- <p>Note that the contents below are <em>not</em> intended to be copied and used as the basis for
- a real homeserver.yaml. Instead, if you are starting from scratch, please generate
- a fresh config using Synapse by following the instructions in
- <a href="usage/configuration/../../setup/installation.html">Installation</a>.</p>
- <pre><code class="language-yaml"># Log configuration for Synapse.
- #
- # This is a YAML file containing a standard Python logging configuration
- # dictionary. See [1] for details on the valid settings.
- #
- # Synapse also supports structured logging for machine readable logs which can
- # be ingested by ELK stacks. See [2] for details.
- #
- # [1]: https://docs.python.org/3.7/library/logging.config.html#configuration-dictionary-schema
- # [2]: https://matrix-org.github.io/synapse/latest/structured_logging.html
- version: 1
- formatters:
- precise:
- format: '%(asctime)s - %(name)s - %(lineno)d - %(levelname)s - %(request)s - %(message)s'
- handlers:
- file:
- class: logging.handlers.TimedRotatingFileHandler
- formatter: precise
- filename: /var/log/matrix-synapse/homeserver.log
- when: midnight
- backupCount: 3 # Does not include the current log file.
- encoding: utf8
- # Default to buffering writes to log file for efficiency. This means that
- # will be a delay for INFO/DEBUG logs to get written, but WARNING/ERROR
- # logs will still be flushed immediately.
- buffer:
- class: logging.handlers.MemoryHandler
- target: file
- # The capacity is the number of log lines that are buffered before
- # being written to disk. Increasing this will lead to better
- # performance, at the expensive of it taking longer for log lines to
- # be written to disk.
- capacity: 10
- flushLevel: 30 # Flush for WARNING logs as well
- # A handler that writes logs to stderr. Unused by default, but can be used
- # instead of "buffer" and "file" in the logger handlers.
- console:
- class: logging.StreamHandler
- formatter: precise
- loggers:
- synapse.storage.SQL:
- # beware: increasing this to DEBUG will make synapse log sensitive
- # information such as access tokens.
- level: INFO
- twisted:
- # We send the twisted logging directly to the file handler,
- # to work around https://github.com/matrix-org/synapse/issues/3471
- # when using "buffer" logger. Use "console" to log to stderr instead.
- handlers: [file]
- propagate: false
- root:
- level: INFO
- # Write logs to the `buffer` handler, which will buffer them together in memory,
- # then write them to a file.
- #
- # Replace "buffer" with "console" to log to stderr instead. (Note that you'll
- # also need to update the configuration for the `twisted` logger above, in
- # this case.)
- #
- handlers: [buffer]
- disable_existing_loggers: false
- </code></pre>
- <div style="break-before: page; page-break-before: always;"></div><h1 id="structured-logging"><a class="header" href="#structured-logging">Structured Logging</a></h1>
- <p>A structured logging system can be useful when your logs are destined for a
- machine to parse and process. By maintaining its machine-readable characteristics,
- it enables more efficient searching and aggregations when consumed by software
- such as the "ELK stack".</p>
- <p>Synapse's structured logging system is configured via the file that Synapse's
- <code>log_config</code> config option points to. The file should include a formatter which
- uses the <code>synapse.logging.TerseJsonFormatter</code> class included with Synapse and a
- handler which uses the above formatter.</p>
- <p>There is also a <code>synapse.logging.JsonFormatter</code> option which does not include
- a timestamp in the resulting JSON. This is useful if the log ingester adds its
- own timestamp.</p>
- <p>A structured logging configuration looks similar to the following:</p>
- <pre><code class="language-yaml">version: 1
- formatters:
- structured:
- class: synapse.logging.TerseJsonFormatter
- handlers:
- file:
- class: logging.handlers.TimedRotatingFileHandler
- formatter: structured
- filename: /path/to/my/logs/homeserver.log
- when: midnight
- backupCount: 3 # Does not include the current log file.
- encoding: utf8
- loggers:
- synapse:
- level: INFO
- handlers: [remote]
- synapse.storage.SQL:
- level: WARNING
- </code></pre>
- <p>The above logging config will set Synapse as 'INFO' logging level by default,
- with the SQL layer at 'WARNING', and will log to a file, stored as JSON.</p>
- <p>It is also possible to figure Synapse to log to a remote endpoint by using the
- <code>synapse.logging.RemoteHandler</code> class included with Synapse. It takes the
- following arguments:</p>
- <ul>
- <li><code>host</code>: Hostname or IP address of the log aggregator.</li>
- <li><code>port</code>: Numerical port to contact on the host.</li>
- <li><code>maximum_buffer</code>: (Optional, defaults to 1000) The maximum buffer size to allow.</li>
- </ul>
- <p>A remote structured logging configuration looks similar to the following:</p>
- <pre><code class="language-yaml">version: 1
- formatters:
- structured:
- class: synapse.logging.TerseJsonFormatter
- handlers:
- remote:
- class: synapse.logging.RemoteHandler
- formatter: structured
- host: 10.1.2.3
- port: 9999
- loggers:
- synapse:
- level: INFO
- handlers: [remote]
- synapse.storage.SQL:
- level: WARNING
- </code></pre>
- <p>The above logging config will set Synapse as 'INFO' logging level by default,
- with the SQL layer at 'WARNING', and will log JSON formatted messages to a
- remote endpoint at 10.1.2.3:9999.</p>
- <h2 id="upgrading-from-legacy-structured-logging-configuration"><a class="header" href="#upgrading-from-legacy-structured-logging-configuration">Upgrading from legacy structured logging configuration</a></h2>
- <p>Versions of Synapse prior to v1.23.0 included a custom structured logging
- configuration which is deprecated. It used a <code>structured: true</code> flag and
- configured <code>drains</code> instead of <code>handlers</code> and <code>formatters</code>.</p>
- <p>Synapse currently automatically converts the old configuration to the new
- configuration, but this will be removed in a future version of Synapse. The
- following reference can be used to update your configuration. Based on the drain
- <code>type</code>, we can pick a new handler:</p>
- <ol>
- <li>For a type of <code>console</code>, <code>console_json</code>, or <code>console_json_terse</code>: a handler
- with a class of <code>logging.StreamHandler</code> and a <code>stream</code> of <code>ext://sys.stdout</code>
- or <code>ext://sys.stderr</code> should be used.</li>
- <li>For a type of <code>file</code> or <code>file_json</code>: a handler of <code>logging.FileHandler</code> with
- a location of the file path should be used.</li>
- <li>For a type of <code>network_json_terse</code>: a handler of <code>synapse.logging.RemoteHandler</code>
- with the host and port should be used.</li>
- </ol>
- <p>Then based on the drain <code>type</code> we can pick a new formatter:</p>
- <ol>
- <li>For a type of <code>console</code> or <code>file</code> no formatter is necessary.</li>
- <li>For a type of <code>console_json</code> or <code>file_json</code>: a formatter of
- <code>synapse.logging.JsonFormatter</code> should be used.</li>
- <li>For a type of <code>console_json_terse</code> or <code>network_json_terse</code>: a formatter of
- <code>synapse.logging.TerseJsonFormatter</code> should be used.</li>
- </ol>
- <p>For each new handler and formatter they should be added to the logging configuration
- and then assigned to either a logger or the root logger.</p>
- <p>An example legacy configuration:</p>
- <pre><code class="language-yaml">structured: true
- loggers:
- synapse:
- level: INFO
- synapse.storage.SQL:
- level: WARNING
- drains:
- console:
- type: console
- location: stdout
- file:
- type: file_json
- location: homeserver.log
- </code></pre>
- <p>Would be converted into a new configuration:</p>
- <pre><code class="language-yaml">version: 1
- formatters:
- json:
- class: synapse.logging.JsonFormatter
- handlers:
- console:
- class: logging.StreamHandler
- location: ext://sys.stdout
- file:
- class: logging.FileHandler
- formatter: json
- filename: homeserver.log
- loggers:
- synapse:
- level: INFO
- handlers: [console, file]
- synapse.storage.SQL:
- level: WARNING
- </code></pre>
- <p>The new logging configuration is a bit more verbose, but significantly more
- flexible. It allows for configuration that were not previously possible, such as
- sending plain logs over the network, or using different handlers for different
- modules.</p>
- <div style="break-before: page; page-break-before: always;"></div><h1 id="user-authentication"><a class="header" href="#user-authentication">User Authentication</a></h1>
- <p>Synapse supports multiple methods of authenticating users, either out-of-the-box or through custom pluggable
- authentication modules.</p>
- <p>Included in Synapse is support for authenticating users via:</p>
- <ul>
- <li>A username and password.</li>
- <li>An email address and password.</li>
- <li>Single Sign-On through the SAML, Open ID Connect or CAS protocols.</li>
- <li>JSON Web Tokens.</li>
- <li>An administrator's shared secret.</li>
- </ul>
- <p>Synapse can additionally be extended to support custom authentication schemes through optional "password auth provider"
- modules.</p>
- <div style="break-before: page; page-break-before: always;"></div><h1 id="configuring-synapse-to-authenticate-against-an-openid-connect-provider"><a class="header" href="#configuring-synapse-to-authenticate-against-an-openid-connect-provider">Configuring Synapse to authenticate against an OpenID Connect provider</a></h1>
- <p>Synapse can be configured to use an OpenID Connect Provider (OP) for
- authentication, instead of its own local password database.</p>
- <p>Any OP should work with Synapse, as long as it supports the authorization code
- flow. There are a few options for that:</p>
- <ul>
- <li>
- <p>start a local OP. Synapse has been tested with <a href="https://www.ory.sh/docs/hydra/">Hydra</a> and
- <a href="https://github.com/dexidp/dex">Dex</a>. Note that for an OP to work, it should be served under a
- secure (HTTPS) origin. A certificate signed with a self-signed, locally
- trusted CA should work. In that case, start Synapse with a <code>SSL_CERT_FILE</code>
- environment variable set to the path of the CA.</p>
- </li>
- <li>
- <p>set up a SaaS OP, like <a href="https://developers.google.com/identity/protocols/oauth2/openid-connect">Google</a>, <a href="https://auth0.com/">Auth0</a> or
- <a href="https://www.okta.com/">Okta</a>. Synapse has been tested with Auth0 and Google.</p>
- </li>
- </ul>
- <p>It may also be possible to use other OAuth2 providers which provide the
- <a href="https://tools.ietf.org/html/rfc6749#section-4.1">authorization code grant type</a>,
- such as <a href="https://developer.github.com/apps/building-oauth-apps/authorizing-oauth-apps">Github</a>.</p>
- <h2 id="preparing-synapse"><a class="header" href="#preparing-synapse">Preparing Synapse</a></h2>
- <p>The OpenID integration in Synapse uses the
- <a href="https://pypi.org/project/Authlib/"><code>authlib</code></a> library, which must be installed
- as follows:</p>
- <ul>
- <li>
- <p>The relevant libraries are included in the Docker images and Debian packages
- provided by <code>matrix.org</code> so no further action is needed.</p>
- </li>
- <li>
- <p>If you installed Synapse into a virtualenv, run <code>/path/to/env/bin/pip install matrix-synapse[oidc]</code> to install the necessary dependencies.</p>
- </li>
- <li>
- <p>For other installation mechanisms, see the documentation provided by the
- maintainer.</p>
- </li>
- </ul>
- <p>To enable the OpenID integration, you should then add a section to the <code>oidc_providers</code>
- setting in your configuration file (or uncomment one of the existing examples).
- See <a href="./sample_config.yaml">sample_config.yaml</a> for some sample settings, as well as
- the text below for example configurations for specific providers.</p>
- <h2 id="sample-configs"><a class="header" href="#sample-configs">Sample configs</a></h2>
- <p>Here are a few configs for providers that should work with Synapse.</p>
- <h3 id="microsoft-azure-active-directory"><a class="header" href="#microsoft-azure-active-directory">Microsoft Azure Active Directory</a></h3>
- <p>Azure AD can act as an OpenID Connect Provider. Register a new application under
- <em>App registrations</em> in the Azure AD management console. The RedirectURI for your
- application should point to your matrix server:
- <code>[synapse public baseurl]/_synapse/client/oidc/callback</code></p>
- <p>Go to <em>Certificates & secrets</em> and register a new client secret. Make note of your
- Directory (tenant) ID as it will be used in the Azure links.
- Edit your Synapse config file and change the <code>oidc_config</code> section:</p>
- <pre><code class="language-yaml">oidc_providers:
- - idp_id: microsoft
- idp_name: Microsoft
- issuer: "https://login.microsoftonline.com/<tenant id>/v2.0"
- client_id: "<client id>"
- client_secret: "<client secret>"
- scopes: ["openid", "profile"]
- authorization_endpoint: "https://login.microsoftonline.com/<tenant id>/oauth2/v2.0/authorize"
- token_endpoint: "https://login.microsoftonline.com/<tenant id>/oauth2/v2.0/token"
- userinfo_endpoint: "https://graph.microsoft.com/oidc/userinfo"
- user_mapping_provider:
- config:
- localpart_template: "{{ user.preferred_username.split('@')[0] }}"
- display_name_template: "{{ user.name }}"
- </code></pre>
- <h3 id="dex"><a class="header" href="#dex"><a href="https://github.com/dexidp/dex">Dex</a></a></h3>
- <p><a href="https://github.com/dexidp/dex">Dex</a> is a simple, open-source, certified OpenID Connect Provider.
- Although it is designed to help building a full-blown provider with an
- external database, it can be configured with static passwords in a config file.</p>
- <p>Follow the <a href="https://dexidp.io/docs/getting-started/">Getting Started guide</a>
- to install Dex.</p>
- <p>Edit <code>examples/config-dev.yaml</code> config file from the Dex repo to add a client:</p>
- <pre><code class="language-yaml">staticClients:
- - id: synapse
- secret: secret
- redirectURIs:
- - '[synapse public baseurl]/_synapse/client/oidc/callback'
- name: 'Synapse'
- </code></pre>
- <p>Run with <code>dex serve examples/config-dev.yaml</code>.</p>
- <p>Synapse config:</p>
- <pre><code class="language-yaml">oidc_providers:
- - idp_id: dex
- idp_name: "My Dex server"
- skip_verification: true # This is needed as Dex is served on an insecure endpoint
- issuer: "http://127.0.0.1:5556/dex"
- client_id: "synapse"
- client_secret: "secret"
- scopes: ["openid", "profile"]
- user_mapping_provider:
- config:
- localpart_template: "{{ user.name }}"
- display_name_template: "{{ user.name|capitalize }}"
- </code></pre>
- <h3 id="keycloak"><a class="header" href="#keycloak"><a href="https://www.keycloak.org/docs/latest/server_admin/#sso-protocols">Keycloak</a></a></h3>
- <p><a href="https://www.keycloak.org/docs/latest/server_admin/#sso-protocols">Keycloak</a> is an opensource IdP maintained by Red Hat.</p>
- <p>Follow the <a href="https://www.keycloak.org/getting-started">Getting Started Guide</a> to install Keycloak and set up a realm.</p>
- <ol>
- <li>
- <p>Click <code>Clients</code> in the sidebar and click <code>Create</code></p>
- </li>
- <li>
- <p>Fill in the fields as below:</p>
- </li>
- </ol>
- <table><thead><tr><th>Field</th><th>Value</th></tr></thead><tbody>
- <tr><td>Client ID</td><td><code>synapse</code></td></tr>
- <tr><td>Client Protocol</td><td><code>openid-connect</code></td></tr>
- </tbody></table>
- <ol start="3">
- <li>Click <code>Save</code></li>
- <li>Fill in the fields as below:</li>
- </ol>
- <table><thead><tr><th>Field</th><th>Value</th></tr></thead><tbody>
- <tr><td>Client ID</td><td><code>synapse</code></td></tr>
- <tr><td>Enabled</td><td><code>On</code></td></tr>
- <tr><td>Client Protocol</td><td><code>openid-connect</code></td></tr>
- <tr><td>Access Type</td><td><code>confidential</code></td></tr>
- <tr><td>Valid Redirect URIs</td><td><code>[synapse public baseurl]/_synapse/client/oidc/callback</code></td></tr>
- </tbody></table>
- <ol start="5">
- <li>Click <code>Save</code></li>
- <li>On the Credentials tab, update the fields:</li>
- </ol>
- <table><thead><tr><th>Field</th><th>Value</th></tr></thead><tbody>
- <tr><td>Client Authenticator</td><td><code>Client ID and Secret</code></td></tr>
- </tbody></table>
- <ol start="7">
- <li>Click <code>Regenerate Secret</code></li>
- <li>Copy Secret</li>
- </ol>
- <pre><code class="language-yaml">oidc_providers:
- - idp_id: keycloak
- idp_name: "My KeyCloak server"
- issuer: "https://127.0.0.1:8443/auth/realms/{realm_name}"
- client_id: "synapse"
- client_secret: "copy secret generated from above"
- scopes: ["openid", "profile"]
- user_mapping_provider:
- config:
- localpart_template: "{{ user.preferred_username }}"
- display_name_template: "{{ user.name }}"
- </code></pre>
- <h3 id="auth0"><a class="header" href="#auth0"><a href="https://auth0.com/">Auth0</a></a></h3>
- <ol>
- <li>
- <p>Create a regular web application for Synapse</p>
- </li>
- <li>
- <p>Set the Allowed Callback URLs to <code>[synapse public baseurl]/_synapse/client/oidc/callback</code></p>
- </li>
- <li>
- <p>Add a rule to add the <code>preferred_username</code> claim.</p>
- <details>
- <summary>Code sample</summary>
- <pre><code class="language-js">function addPersistenceAttribute(user, context, callback) {
- user.user_metadata = user.user_metadata || {};
- user.user_metadata.preferred_username = user.user_metadata.preferred_username || user.user_id;
- context.idToken.preferred_username = user.user_metadata.preferred_username;
- auth0.users.updateUserMetadata(user.user_id, user.user_metadata)
- .then(function(){
- callback(null, user, context);
- })
- .catch(function(err){
- callback(err);
- });
- }
- </code></pre>
- </li>
- </ol>
- </details>
- <p>Synapse config:</p>
- <pre><code class="language-yaml">oidc_providers:
- - idp_id: auth0
- idp_name: Auth0
- issuer: "https://your-tier.eu.auth0.com/" # TO BE FILLED
- client_id: "your-client-id" # TO BE FILLED
- client_secret: "your-client-secret" # TO BE FILLED
- scopes: ["openid", "profile"]
- user_mapping_provider:
- config:
- localpart_template: "{{ user.preferred_username }}"
- display_name_template: "{{ user.name }}"
- </code></pre>
- <h3 id="github"><a class="header" href="#github">GitHub</a></h3>
- <p>GitHub is a bit special as it is not an OpenID Connect compliant provider, but
- just a regular OAuth2 provider.</p>
- <p>The <a href="https://developer.github.com/v3/users/#get-the-authenticated-user"><code>/user</code> API endpoint</a>
- can be used to retrieve information on the authenticated user. As the Synapse
- login mechanism needs an attribute to uniquely identify users, and that endpoint
- does not return a <code>sub</code> property, an alternative <code>subject_claim</code> has to be set.</p>
- <ol>
- <li>Create a new OAuth application: https://github.com/settings/applications/new.</li>
- <li>Set the callback URL to <code>[synapse public baseurl]/_synapse/client/oidc/callback</code>.</li>
- </ol>
- <p>Synapse config:</p>
- <pre><code class="language-yaml">oidc_providers:
- - idp_id: github
- idp_name: Github
- idp_brand: "github" # optional: styling hint for clients
- discover: false
- issuer: "https://github.com/"
- client_id: "your-client-id" # TO BE FILLED
- client_secret: "your-client-secret" # TO BE FILLED
- authorization_endpoint: "https://github.com/login/oauth/authorize"
- token_endpoint: "https://github.com/login/oauth/access_token"
- userinfo_endpoint: "https://api.github.com/user"
- scopes: ["read:user"]
- user_mapping_provider:
- config:
- subject_claim: "id"
- localpart_template: "{{ user.login }}"
- display_name_template: "{{ user.name }}"
- </code></pre>
- <h3 id="google"><a class="header" href="#google"><a href="https://developers.google.com/identity/protocols/oauth2/openid-connect">Google</a></a></h3>
- <ol>
- <li>Set up a project in the Google API Console (see
- https://developers.google.com/identity/protocols/oauth2/openid-connect#appsetup).</li>
- <li>add an "OAuth Client ID" for a Web Application under "Credentials".</li>
- <li>Copy the Client ID and Client Secret, and add the following to your synapse config:
- <pre><code class="language-yaml">oidc_providers:
- - idp_id: google
- idp_name: Google
- idp_brand: "google" # optional: styling hint for clients
- issuer: "https://accounts.google.com/"
- client_id: "your-client-id" # TO BE FILLED
- client_secret: "your-client-secret" # TO BE FILLED
- scopes: ["openid", "profile"]
- user_mapping_provider:
- config:
- localpart_template: "{{ user.given_name|lower }}"
- display_name_template: "{{ user.name }}"
- </code></pre>
- </li>
- <li>Back in the Google console, add this Authorized redirect URI: <code>[synapse public baseurl]/_synapse/client/oidc/callback</code>.</li>
- </ol>
- <h3 id="twitch"><a class="header" href="#twitch">Twitch</a></h3>
- <ol>
- <li>Setup a developer account on <a href="https://dev.twitch.tv/">Twitch</a></li>
- <li>Obtain the OAuth 2.0 credentials by <a href="https://dev.twitch.tv/console/apps/">creating an app</a></li>
- <li>Add this OAuth Redirect URL: <code>[synapse public baseurl]/_synapse/client/oidc/callback</code></li>
- </ol>
- <p>Synapse config:</p>
- <pre><code class="language-yaml">oidc_providers:
- - idp_id: twitch
- idp_name: Twitch
- issuer: "https://id.twitch.tv/oauth2/"
- client_id: "your-client-id" # TO BE FILLED
- client_secret: "your-client-secret" # TO BE FILLED
- client_auth_method: "client_secret_post"
- user_mapping_provider:
- config:
- localpart_template: "{{ user.preferred_username }}"
- display_name_template: "{{ user.name }}"
- </code></pre>
- <h3 id="gitlab"><a class="header" href="#gitlab">GitLab</a></h3>
- <ol>
- <li>Create a <a href="https://gitlab.com/profile/applications">new application</a>.</li>
- <li>Add the <code>read_user</code> and <code>openid</code> scopes.</li>
- <li>Add this Callback URL: <code>[synapse public baseurl]/_synapse/client/oidc/callback</code></li>
- </ol>
- <p>Synapse config:</p>
- <pre><code class="language-yaml">oidc_providers:
- - idp_id: gitlab
- idp_name: Gitlab
- idp_brand: "gitlab" # optional: styling hint for clients
- issuer: "https://gitlab.com/"
- client_id: "your-client-id" # TO BE FILLED
- client_secret: "your-client-secret" # TO BE FILLED
- client_auth_method: "client_secret_post"
- scopes: ["openid", "read_user"]
- user_profile_method: "userinfo_endpoint"
- user_mapping_provider:
- config:
- localpart_template: '{{ user.nickname }}'
- display_name_template: '{{ user.name }}'
- </code></pre>
- <h3 id="facebook"><a class="header" href="#facebook">Facebook</a></h3>
- <p>Like Github, Facebook provide a custom OAuth2 API rather than an OIDC-compliant
- one so requires a little more configuration.</p>
- <ol start="0">
- <li>You will need a Facebook developer account. You can register for one
- <a href="https://developers.facebook.com/async/registration/">here</a>.</li>
- <li>On the <a href="https://developers.facebook.com/apps/">apps</a> page of the developer
- console, "Create App", and choose "Build Connected Experiences".</li>
- <li>Once the app is created, add "Facebook Login" and choose "Web". You don't
- need to go through the whole form here.</li>
- <li>In the left-hand menu, open "Products"/"Facebook Login"/"Settings".
- <ul>
- <li>Add <code>[synapse public baseurl]/_synapse/client/oidc/callback</code> as an OAuth Redirect
- URL.</li>
- </ul>
- </li>
- <li>In the left-hand menu, open "Settings/Basic". Here you can copy the "App ID"
- and "App Secret" for use below.</li>
- </ol>
- <p>Synapse config:</p>
- <pre><code class="language-yaml"> - idp_id: facebook
- idp_name: Facebook
- idp_brand: "facebook" # optional: styling hint for clients
- discover: false
- issuer: "https://facebook.com"
- client_id: "your-client-id" # TO BE FILLED
- client_secret: "your-client-secret" # TO BE FILLED
- scopes: ["openid", "email"]
- authorization_endpoint: https://facebook.com/dialog/oauth
- token_endpoint: https://graph.facebook.com/v9.0/oauth/access_token
- user_profile_method: "userinfo_endpoint"
- userinfo_endpoint: "https://graph.facebook.com/v9.0/me?fields=id,name,email,picture"
- user_mapping_provider:
- config:
- subject_claim: "id"
- display_name_template: "{{ user.name }}"
- </code></pre>
- <p>Relevant documents:</p>
- <ul>
- <li>https://developers.facebook.com/docs/facebook-login/manually-build-a-login-flow</li>
- <li>Using Facebook's Graph API: https://developers.facebook.com/docs/graph-api/using-graph-api/</li>
- <li>Reference to the User endpoint: https://developers.facebook.com/docs/graph-api/reference/user</li>
- </ul>
- <h3 id="gitea"><a class="header" href="#gitea">Gitea</a></h3>
- <p>Gitea is, like Github, not an OpenID provider, but just an OAuth2 provider.</p>
- <p>The <a href="https://try.gitea.io/api/swagger#/user/userGetCurrent"><code>/user</code> API endpoint</a>
- can be used to retrieve information on the authenticated user. As the Synapse
- login mechanism needs an attribute to uniquely identify users, and that endpoint
- does not return a <code>sub</code> property, an alternative <code>subject_claim</code> has to be set.</p>
- <ol>
- <li>Create a new application.</li>
- <li>Add this Callback URL: <code>[synapse public baseurl]/_synapse/client/oidc/callback</code></li>
- </ol>
- <p>Synapse config:</p>
- <pre><code class="language-yaml">oidc_providers:
- - idp_id: gitea
- idp_name: Gitea
- discover: false
- issuer: "https://your-gitea.com/"
- client_id: "your-client-id" # TO BE FILLED
- client_secret: "your-client-secret" # TO BE FILLED
- client_auth_method: client_secret_post
- scopes: [] # Gitea doesn't support Scopes
- authorization_endpoint: "https://your-gitea.com/login/oauth/authorize"
- token_endpoint: "https://your-gitea.com/login/oauth/access_token"
- userinfo_endpoint: "https://your-gitea.com/api/v1/user"
- user_mapping_provider:
- config:
- subject_claim: "id"
- localpart_template: "{{ user.login }}"
- display_name_template: "{{ user.full_name }}"
- </code></pre>
- <h3 id="xwiki"><a class="header" href="#xwiki">XWiki</a></h3>
- <p>Install <a href="https://extensions.xwiki.org/xwiki/bin/view/Extension/OpenID%20Connect/OpenID%20Connect%20Provider/">OpenID Connect Provider</a> extension in your <a href="https://www.xwiki.org">XWiki</a> instance.</p>
- <p>Synapse config:</p>
- <pre><code class="language-yaml">oidc_providers:
- - idp_id: xwiki
- idp_name: "XWiki"
- issuer: "https://myxwikihost/xwiki/oidc/"
- client_id: "your-client-id" # TO BE FILLED
- client_auth_method: none
- scopes: ["openid", "profile"]
- user_profile_method: "userinfo_endpoint"
- user_mapping_provider:
- config:
- localpart_template: "{{ user.preferred_username }}"
- display_name_template: "{{ user.name }}"
- </code></pre>
- <h2 id="apple"><a class="header" href="#apple">Apple</a></h2>
- <p>Configuring "Sign in with Apple" (SiWA) requires an Apple Developer account.</p>
- <p>You will need to create a new "Services ID" for SiWA, and create and download a
- private key with "SiWA" enabled.</p>
- <p>As well as the private key file, you will need:</p>
- <ul>
- <li>Client ID: the "identifier" you gave the "Services ID"</li>
- <li>Team ID: a 10-character ID associated with your developer account.</li>
- <li>Key ID: the 10-character identifier for the key.</li>
- </ul>
- <p>https://help.apple.com/developer-account/?lang=en#/dev77c875b7e has more
- documentation on setting up SiWA.</p>
- <p>The synapse config will look like this:</p>
- <pre><code class="language-yaml"> - idp_id: apple
- idp_name: Apple
- issuer: "https://appleid.apple.com"
- client_id: "your-client-id" # Set to the "identifier" for your "ServicesID"
- client_auth_method: "client_secret_post"
- client_secret_jwt_key:
- key_file: "/path/to/AuthKey_KEYIDCODE.p8" # point to your key file
- jwt_header:
- alg: ES256
- kid: "KEYIDCODE" # Set to the 10-char Key ID
- jwt_payload:
- iss: TEAMIDCODE # Set to the 10-char Team ID
- scopes: ["name", "email", "openid"]
- authorization_endpoint: https://appleid.apple.com/auth/authorize?response_mode=form_post
- user_mapping_provider:
- config:
- email_template: "{{ user.email }}"
- </code></pre>
- <div style="break-before: page; page-break-before: always;"></div><h1 id="sso-mapping-providers"><a class="header" href="#sso-mapping-providers">SSO Mapping Providers</a></h1>
- <p>A mapping provider is a Python class (loaded via a Python module) that
- works out how to map attributes of a SSO response to Matrix-specific
- user attributes. Details such as user ID localpart, displayname, and even avatar
- URLs are all things that can be mapped from talking to a SSO service.</p>
- <p>As an example, a SSO service may return the email address
- "john.smith@example.com" for a user, whereas Synapse will need to figure out how
- to turn that into a displayname when creating a Matrix user for this individual.
- It may choose <code>John Smith</code>, or <code>Smith, John [Example.com]</code> or any number of
- variations. As each Synapse configuration may want something different, this is
- where SAML mapping providers come into play.</p>
- <p>SSO mapping providers are currently supported for OpenID and SAML SSO
- configurations. Please see the details below for how to implement your own.</p>
- <p>It is up to the mapping provider whether the user should be assigned a predefined
- Matrix ID based on the SSO attributes, or if the user should be allowed to
- choose their own username.</p>
- <p>In the first case - where users are automatically allocated a Matrix ID - it is
- the responsibility of the mapping provider to normalise the SSO attributes and
- map them to a valid Matrix ID. The <a href="https://matrix.org/docs/spec/appendices#user-identifiers">specification for Matrix
- IDs</a> has some
- information about what is considered valid.</p>
- <p>If the mapping provider does not assign a Matrix ID, then Synapse will
- automatically serve an HTML page allowing the user to pick their own username.</p>
- <p>External mapping providers are provided to Synapse in the form of an external
- Python module. You can retrieve this module from <a href="https://pypi.org">PyPI</a> or elsewhere,
- but it must be importable via Synapse (e.g. it must be in the same virtualenv
- as Synapse). The Synapse config is then modified to point to the mapping provider
- (and optionally provide additional configuration for it).</p>
- <h2 id="openid-mapping-providers"><a class="header" href="#openid-mapping-providers">OpenID Mapping Providers</a></h2>
- <p>The OpenID mapping provider can be customized by editing the
- <code>oidc_config.user_mapping_provider.module</code> config option.</p>
- <p><code>oidc_config.user_mapping_provider.config</code> allows you to provide custom
- configuration options to the module. Check with the module's documentation for
- what options it provides (if any). The options listed by default are for the
- user mapping provider built in to Synapse. If using a custom module, you should
- comment these options out and use those specified by the module instead.</p>
- <h3 id="building-a-custom-openid-mapping-provider"><a class="header" href="#building-a-custom-openid-mapping-provider">Building a Custom OpenID Mapping Provider</a></h3>
- <p>A custom mapping provider must specify the following methods:</p>
- <ul>
- <li><code>__init__(self, parsed_config)</code>
- <ul>
- <li>Arguments:
- <ul>
- <li><code>parsed_config</code> - A configuration object that is the return value of the
- <code>parse_config</code> method. You should set any configuration options needed by
- the module here.</li>
- </ul>
- </li>
- </ul>
- </li>
- <li><code>parse_config(config)</code>
- <ul>
- <li>This method should have the <code>@staticmethod</code> decoration.</li>
- <li>Arguments:
- <ul>
- <li><code>config</code> - A <code>dict</code> representing the parsed content of the
- <code>oidc_config.user_mapping_provider.config</code> homeserver config option.
- Runs on homeserver startup. Providers should extract and validate
- any option values they need here.</li>
- </ul>
- </li>
- <li>Whatever is returned will be passed back to the user mapping provider module's
- <code>__init__</code> method during construction.</li>
- </ul>
- </li>
- <li><code>get_remote_user_id(self, userinfo)</code>
- <ul>
- <li>Arguments:
- <ul>
- <li><code>userinfo</code> - A <code>authlib.oidc.core.claims.UserInfo</code> object to extract user
- information from.</li>
- </ul>
- </li>
- <li>This method must return a string, which is the unique, immutable identifier
- for the user. Commonly the <code>sub</code> claim of the response.</li>
- </ul>
- </li>
- <li><code>map_user_attributes(self, userinfo, token, failures)</code>
- <ul>
- <li>This method must be async.</li>
- <li>Arguments:
- <ul>
- <li><code>userinfo</code> - A <code>authlib.oidc.core.claims.UserInfo</code> object to extract user
- information from.</li>
- <li><code>token</code> - A dictionary which includes information necessary to make
- further requests to the OpenID provider.</li>
- <li><code>failures</code> - An <code>int</code> that represents the amount of times the returned
- mxid localpart mapping has failed. This should be used
- to create a deduplicated mxid localpart which should be
- returned instead. For example, if this method returns
- <code>john.doe</code> as the value of <code>localpart</code> in the returned
- dict, and that is already taken on the homeserver, this
- method will be called again with the same parameters but
- with failures=1. The method should then return a different
- <code>localpart</code> value, such as <code>john.doe1</code>.</li>
- </ul>
- </li>
- <li>Returns a dictionary with two keys:
- <ul>
- <li><code>localpart</code>: A string, used to generate the Matrix ID. If this is
- <code>None</code>, the user is prompted to pick their own username. This is only used
- during a user's first login. Once a localpart has been associated with a
- remote user ID (see <code>get_remote_user_id</code>) it cannot be updated.</li>
- <li><code>displayname</code>: An optional string, the display name for the user.</li>
- </ul>
- </li>
- </ul>
- </li>
- <li><code>get_extra_attributes(self, userinfo, token)</code>
- <ul>
- <li>
- <p>This method must be async.</p>
- </li>
- <li>
- <p>Arguments:</p>
- <ul>
- <li><code>userinfo</code> - A <code>authlib.oidc.core.claims.UserInfo</code> object to extract user
- information from.</li>
- <li><code>token</code> - A dictionary which includes information necessary to make
- further requests to the OpenID provider.</li>
- </ul>
- </li>
- <li>
- <p>Returns a dictionary that is suitable to be serialized to JSON. This
- will be returned as part of the response during a successful login.</p>
- <p>Note that care should be taken to not overwrite any of the parameters
- usually returned as part of the <a href="https://matrix.org/docs/spec/client_server/latest#post-matrix-client-r0-login">login response</a>.</p>
- </li>
- </ul>
- </li>
- </ul>
- <h3 id="default-openid-mapping-provider"><a class="header" href="#default-openid-mapping-provider">Default OpenID Mapping Provider</a></h3>
- <p>Synapse has a built-in OpenID mapping provider if a custom provider isn't
- specified in the config. It is located at
- <a href="https://github.com/matrix-org/synapse/blob/develop/synapse/handlers/oidc.py"><code>synapse.handlers.oidc.JinjaOidcMappingProvider</code></a>.</p>
- <h2 id="saml-mapping-providers"><a class="header" href="#saml-mapping-providers">SAML Mapping Providers</a></h2>
- <p>The SAML mapping provider can be customized by editing the
- <code>saml2_config.user_mapping_provider.module</code> config option.</p>
- <p><code>saml2_config.user_mapping_provider.config</code> allows you to provide custom
- configuration options to the module. Check with the module's documentation for
- what options it provides (if any). The options listed by default are for the
- user mapping provider built in to Synapse. If using a custom module, you should
- comment these options out and use those specified by the module instead.</p>
- <h3 id="building-a-custom-saml-mapping-provider"><a class="header" href="#building-a-custom-saml-mapping-provider">Building a Custom SAML Mapping Provider</a></h3>
- <p>A custom mapping provider must specify the following methods:</p>
- <ul>
- <li><code>__init__(self, parsed_config, module_api)</code>
- <ul>
- <li>Arguments:
- <ul>
- <li><code>parsed_config</code> - A configuration object that is the return value of the
- <code>parse_config</code> method. You should set any configuration options needed by
- the module here.</li>
- <li><code>module_api</code> - a <code>synapse.module_api.ModuleApi</code> object which provides the
- stable API available for extension modules.</li>
- </ul>
- </li>
- </ul>
- </li>
- <li><code>parse_config(config)</code>
- <ul>
- <li>This method should have the <code>@staticmethod</code> decoration.</li>
- <li>Arguments:
- <ul>
- <li><code>config</code> - A <code>dict</code> representing the parsed content of the
- <code>saml_config.user_mapping_provider.config</code> homeserver config option.
- Runs on homeserver startup. Providers should extract and validate
- any option values they need here.</li>
- </ul>
- </li>
- <li>Whatever is returned will be passed back to the user mapping provider module's
- <code>__init__</code> method during construction.</li>
- </ul>
- </li>
- <li><code>get_saml_attributes(config)</code>
- <ul>
- <li>This method should have the <code>@staticmethod</code> decoration.</li>
- <li>Arguments:
- <ul>
- <li><code>config</code> - A object resulting from a call to <code>parse_config</code>.</li>
- </ul>
- </li>
- <li>Returns a tuple of two sets. The first set equates to the SAML auth
- response attributes that are required for the module to function, whereas
- the second set consists of those attributes which can be used if available,
- but are not necessary.</li>
- </ul>
- </li>
- <li><code>get_remote_user_id(self, saml_response, client_redirect_url)</code>
- <ul>
- <li>Arguments:
- <ul>
- <li><code>saml_response</code> - A <code>saml2.response.AuthnResponse</code> object to extract user
- information from.</li>
- <li><code>client_redirect_url</code> - A string, the URL that the client will be
- redirected to.</li>
- </ul>
- </li>
- <li>This method must return a string, which is the unique, immutable identifier
- for the user. Commonly the <code>uid</code> claim of the response.</li>
- </ul>
- </li>
- <li><code>saml_response_to_user_attributes(self, saml_response, failures, client_redirect_url)</code>
- <ul>
- <li>
- <p>Arguments:</p>
- <ul>
- <li><code>saml_response</code> - A <code>saml2.response.AuthnResponse</code> object to extract user
- information from.</li>
- <li><code>failures</code> - An <code>int</code> that represents the amount of times the returned
- mxid localpart mapping has failed. This should be used
- to create a deduplicated mxid localpart which should be
- returned instead. For example, if this method returns
- <code>john.doe</code> as the value of <code>mxid_localpart</code> in the returned
- dict, and that is already taken on the homeserver, this
- method will be called again with the same parameters but
- with failures=1. The method should then return a different
- <code>mxid_localpart</code> value, such as <code>john.doe1</code>.</li>
- <li><code>client_redirect_url</code> - A string, the URL that the client will be
- redirected to.</li>
- </ul>
- </li>
- <li>
- <p>This method must return a dictionary, which will then be used by Synapse
- to build a new user. The following keys are allowed:</p>
- <ul>
- <li><code>mxid_localpart</code> - A string, the mxid localpart of the new user. If this is
- <code>None</code>, the user is prompted to pick their own username. This is only used
- during a user's first login. Once a localpart has been associated with a
- remote user ID (see <code>get_remote_user_id</code>) it cannot be updated.</li>
- <li><code>displayname</code> - The displayname of the new user. If not provided, will default to
- the value of <code>mxid_localpart</code>.</li>
- <li><code>emails</code> - A list of emails for the new user. If not provided, will
- default to an empty list.</li>
- </ul>
- <p>Alternatively it can raise a <code>synapse.api.errors.RedirectException</code> to
- redirect the user to another page. This is useful to prompt the user for
- additional information, e.g. if you want them to provide their own username.
- It is the responsibility of the mapping provider to either redirect back
- to <code>client_redirect_url</code> (including any additional information) or to
- complete registration using methods from the <code>ModuleApi</code>.</p>
- </li>
- </ul>
- </li>
- </ul>
- <h3 id="default-saml-mapping-provider"><a class="header" href="#default-saml-mapping-provider">Default SAML Mapping Provider</a></h3>
- <p>Synapse has a built-in SAML mapping provider if a custom provider isn't
- specified in the config. It is located at
- <a href="https://github.com/matrix-org/synapse/blob/develop/synapse/handlers/saml.py"><code>synapse.handlers.saml.DefaultSamlMappingProvider</code></a>.</p>
- <div style="break-before: page; page-break-before: always;"></div><h1 id="password-auth-provider-modules"><a class="header" href="#password-auth-provider-modules">Password auth provider modules</a></h1>
- <p>Password auth providers offer a way for server administrators to
- integrate their Synapse installation with an existing authentication
- system.</p>
- <p>A password auth provider is a Python class which is dynamically loaded
- into Synapse, and provides a number of methods by which it can integrate
- with the authentication system.</p>
- <p>This document serves as a reference for those looking to implement their
- own password auth providers. Additionally, here is a list of known
- password auth provider module implementations:</p>
- <ul>
- <li><a href="https://github.com/matrix-org/matrix-synapse-ldap3/">matrix-synapse-ldap3</a></li>
- <li><a href="https://github.com/devture/matrix-synapse-shared-secret-auth">matrix-synapse-shared-secret-auth</a></li>
- <li><a href="https://github.com/ma1uta/matrix-synapse-rest-password-provider">matrix-synapse-rest-password-provider</a></li>
- </ul>
- <h2 id="required-methods"><a class="header" href="#required-methods">Required methods</a></h2>
- <p>Password auth provider classes must provide the following methods:</p>
- <ul>
- <li>
- <p><code>parse_config(config)</code>
- This method is passed the <code>config</code> object for this module from the
- homeserver configuration file.</p>
- <p>It should perform any appropriate sanity checks on the provided
- configuration, and return an object which is then passed into
- <code>__init__</code>.</p>
- <p>This method should have the <code>@staticmethod</code> decoration.</p>
- </li>
- <li>
- <p><code>__init__(self, config, account_handler)</code></p>
- <p>The constructor is passed the config object returned by
- <code>parse_config</code>, and a <code>synapse.module_api.ModuleApi</code> object which
- allows the password provider to check if accounts exist and/or create
- new ones.</p>
- </li>
- </ul>
- <h2 id="optional-methods"><a class="header" href="#optional-methods">Optional methods</a></h2>
- <p>Password auth provider classes may optionally provide the following methods:</p>
- <ul>
- <li>
- <p><code>get_db_schema_files(self)</code></p>
- <p>This method, if implemented, should return an Iterable of
- <code>(name, stream)</code> pairs of database schema files. Each file is applied
- in turn at initialisation, and a record is then made in the database
- so that it is not re-applied on the next start.</p>
- </li>
- <li>
- <p><code>get_supported_login_types(self)</code></p>
- <p>This method, if implemented, should return a <code>dict</code> mapping from a
- login type identifier (such as <code>m.login.password</code>) to an iterable
- giving the fields which must be provided by the user in the submission
- to <a href="https://matrix.org/docs/spec/client_server/latest#post-matrix-client-r0-login">the <code>/login</code> API</a>.
- These fields are passed in the <code>login_dict</code> dictionary to <code>check_auth</code>.</p>
- <p>For example, if a password auth provider wants to implement a custom
- login type of <code>com.example.custom_login</code>, where the client is expected
- to pass the fields <code>secret1</code> and <code>secret2</code>, the provider should
- implement this method and return the following dict:</p>
- <pre><code class="language-python">{"com.example.custom_login": ("secret1", "secret2")}
- </code></pre>
- </li>
- <li>
- <p><code>check_auth(self, username, login_type, login_dict)</code></p>
- <p>This method does the real work. If implemented, it
- will be called for each login attempt where the login type matches one
- of the keys returned by <code>get_supported_login_types</code>.</p>
- <p>It is passed the (possibly unqualified) <code>user</code> field provided by the client,
- the login type, and a dictionary of login secrets passed by the
- client.</p>
- <p>The method should return an <code>Awaitable</code> object, which resolves
- to the canonical <code>@localpart:domain</code> user ID if authentication is
- successful, and <code>None</code> if not.</p>
- <p>Alternatively, the <code>Awaitable</code> can resolve to a <code>(str, func)</code> tuple, in
- which case the second field is a callback which will be called with
- the result from the <code>/login</code> call (including <code>access_token</code>,
- <code>device_id</code>, etc.)</p>
- </li>
- <li>
- <p><code>check_3pid_auth(self, medium, address, password)</code></p>
- <p>This method, if implemented, is called when a user attempts to
- register or log in with a third party identifier, such as email. It is
- passed the medium (ex. "email"), an address (ex.
- "<a href="mailto:jdoe@example.com">jdoe@example.com</a>") and the user's password.</p>
- <p>The method should return an <code>Awaitable</code> object, which resolves
- to a <code>str</code> containing the user's (canonical) User id if
- authentication was successful, and <code>None</code> if not.</p>
- <p>As with <code>check_auth</code>, the <code>Awaitable</code> may alternatively resolve to a
- <code>(user_id, callback)</code> tuple.</p>
- </li>
- <li>
- <p><code>check_password(self, user_id, password)</code></p>
- <p>This method provides a simpler interface than
- <code>get_supported_login_types</code> and <code>check_auth</code> for password auth
- providers that just want to provide a mechanism for validating
- <code>m.login.password</code> logins.</p>
- <p>If implemented, it will be called to check logins with an
- <code>m.login.password</code> login type. It is passed a qualified
- <code>@localpart:domain</code> user id, and the password provided by the user.</p>
- <p>The method should return an <code>Awaitable</code> object, which resolves
- to <code>True</code> if authentication is successful, and <code>False</code> if not.</p>
- </li>
- <li>
- <p><code>on_logged_out(self, user_id, device_id, access_token)</code></p>
- <p>This method, if implemented, is called when a user logs out. It is
- passed the qualified user ID, the ID of the deactivated device (if
- any: access tokens are occasionally created without an associated
- device ID), and the (now deactivated) access token.</p>
- <p>It may return an <code>Awaitable</code> object; the logout request will
- wait for the <code>Awaitable</code> to complete, but the result is ignored.</p>
- </li>
- </ul>
- <div style="break-before: page; page-break-before: always;"></div><h1 id="jwt-login-type"><a class="header" href="#jwt-login-type">JWT Login Type</a></h1>
- <p>Synapse comes with a non-standard login type to support
- <a href="https://en.wikipedia.org/wiki/JSON_Web_Token">JSON Web Tokens</a>. In general the
- documentation for
- <a href="https://matrix.org/docs/spec/client_server/r0.6.1#login">the login endpoint</a>
- is still valid (and the mechanism works similarly to the
- <a href="https://matrix.org/docs/spec/client_server/r0.6.1#token-based">token based login</a>).</p>
- <p>To log in using a JSON Web Token, clients should submit a <code>/login</code> request as
- follows:</p>
- <pre><code class="language-json">{
- "type": "org.matrix.login.jwt",
- "token": "<jwt>"
- }
- </code></pre>
- <p>Note that the login type of <code>m.login.jwt</code> is supported, but is deprecated. This
- will be removed in a future version of Synapse.</p>
- <p>The <code>token</code> field should include the JSON web token with the following claims:</p>
- <ul>
- <li>The <code>sub</code> (subject) claim is required and should encode the local part of the
- user ID.</li>
- <li>The expiration time (<code>exp</code>), not before time (<code>nbf</code>), and issued at (<code>iat</code>)
- claims are optional, but validated if present.</li>
- <li>The issuer (<code>iss</code>) claim is optional, but required and validated if configured.</li>
- <li>The audience (<code>aud</code>) claim is optional, but required and validated if configured.
- Providing the audience claim when not configured will cause validation to fail.</li>
- </ul>
- <p>In the case that the token is not valid, the homeserver must respond with
- <code>403 Forbidden</code> and an error code of <code>M_FORBIDDEN</code>.</p>
- <p>As with other login types, there are additional fields (e.g. <code>device_id</code> and
- <code>initial_device_display_name</code>) which can be included in the above request.</p>
- <h2 id="preparing-synapse-1"><a class="header" href="#preparing-synapse-1">Preparing Synapse</a></h2>
- <p>The JSON Web Token integration in Synapse uses the
- <a href="https://pypi.org/project/pyjwt/"><code>PyJWT</code></a> library, which must be installed
- as follows:</p>
- <ul>
- <li>
- <p>The relevant libraries are included in the Docker images and Debian packages
- provided by <code>matrix.org</code> so no further action is needed.</p>
- </li>
- <li>
- <p>If you installed Synapse into a virtualenv, run <code>/path/to/env/bin/pip install synapse[pyjwt]</code> to install the necessary dependencies.</p>
- </li>
- <li>
- <p>For other installation mechanisms, see the documentation provided by the
- maintainer.</p>
- </li>
- </ul>
- <p>To enable the JSON web token integration, you should then add an <code>jwt_config</code> section
- to your configuration file (or uncomment the <code>enabled: true</code> line in the
- existing section). See <a href="./sample_config.yaml">sample_config.yaml</a> for some
- sample settings.</p>
- <h2 id="how-to-test-jwt-as-a-developer"><a class="header" href="#how-to-test-jwt-as-a-developer">How to test JWT as a developer</a></h2>
- <p>Although JSON Web Tokens are typically generated from an external server, the
- examples below use <a href="https://pyjwt.readthedocs.io/en/latest/">PyJWT</a> directly.</p>
- <ol>
- <li>
- <p>Configure Synapse with JWT logins, note that this example uses a pre-shared
- secret and an algorithm of HS256:</p>
- <pre><code class="language-yaml">jwt_config:
- enabled: true
- secret: "my-secret-token"
- algorithm: "HS256"
- </code></pre>
- </li>
- <li>
- <p>Generate a JSON web token:</p>
- <pre><code class="language-bash">$ pyjwt --key=my-secret-token --alg=HS256 encode sub=test-user
- eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJ0ZXN0LXVzZXIifQ.Ag71GT8v01UO3w80aqRPTeuVPBIBZkYhNTJJ-_-zQIc
- </code></pre>
- </li>
- <li>
- <p>Query for the login types and ensure <code>org.matrix.login.jwt</code> is there:</p>
- <pre><code class="language-bash">curl http://localhost:8080/_matrix/client/r0/login
- </code></pre>
- </li>
- <li>
- <p>Login used the generated JSON web token from above:</p>
- <pre><code class="language-bash">$ curl http://localhost:8082/_matrix/client/r0/login -X POST \
- --data '{"type":"org.matrix.login.jwt","token":"eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJ0ZXN0LXVzZXIifQ.Ag71GT8v01UO3w80aqRPTeuVPBIBZkYhNTJJ-_-zQIc"}'
- {
- "access_token": "<access token>",
- "device_id": "ACBDEFGHI",
- "home_server": "localhost:8080",
- "user_id": "@test-user:localhost:8480"
- }
- </code></pre>
- </li>
- </ol>
- <p>You should now be able to use the returned access token to query the client API.</p>
- <div style="break-before: page; page-break-before: always;"></div><h1 id="overview-2"><a class="header" href="#overview-2">Overview</a></h1>
- <p>A captcha can be enabled on your homeserver to help prevent bots from registering
- accounts. Synapse currently uses Google's reCAPTCHA service which requires API keys
- from Google.</p>
- <h2 id="getting-api-keys"><a class="header" href="#getting-api-keys">Getting API keys</a></h2>
- <ol>
- <li>Create a new site at <a href="https://www.google.com/recaptcha/admin/create">https://www.google.com/recaptcha/admin/create</a></li>
- <li>Set the label to anything you want</li>
- <li>Set the type to reCAPTCHA v2 using the "I'm not a robot" Checkbox option.
- This is the only type of captcha that works with Synapse.</li>
- <li>Add the public hostname for your server, as set in <code>public_baseurl</code>
- in <code>homeserver.yaml</code>, to the list of authorized domains. If you have not set
- <code>public_baseurl</code>, use <code>server_name</code>.</li>
- <li>Agree to the terms of service and submit.</li>
- <li>Copy your site key and secret key and add them to your <code>homeserver.yaml</code>
- configuration file
- <pre><code>recaptcha_public_key: YOUR_SITE_KEY
- recaptcha_private_key: YOUR_SECRET_KEY
- </code></pre>
- </li>
- <li>Enable the CAPTCHA for new registrations
- <pre><code>enable_registration_captcha: true
- </code></pre>
- </li>
- <li>Go to the settings page for the CAPTCHA you just created</li>
- <li>Uncheck the "Verify the origin of reCAPTCHA solutions" checkbox so that the
- captcha can be displayed in any client. If you do not disable this option then you
- must specify the domains of every client that is allowed to display the CAPTCHA.</li>
- </ol>
- <h2 id="configuring-ip-used-for-auth"><a class="header" href="#configuring-ip-used-for-auth">Configuring IP used for auth</a></h2>
- <p>The reCAPTCHA API requires that the IP address of the user who solved the
- CAPTCHA is sent. If the client is connecting through a proxy or load balancer,
- it may be required to use the <code>X-Forwarded-For</code> (XFF) header instead of the origin
- IP address. This can be configured using the <code>x_forwarded</code> directive in the
- listeners section of the <code>homeserver.yaml</code> configuration file.</p>
- <div style="break-before: page; page-break-before: always;"></div><h1 id="registering-an-application-service"><a class="header" href="#registering-an-application-service">Registering an Application Service</a></h1>
- <p>The registration of new application services depends on the homeserver used.
- In synapse, you need to create a new configuration file for your AS and add it
- to the list specified under the <code>app_service_config_files</code> config
- option in your synapse config.</p>
- <p>For example:</p>
- <pre><code class="language-yaml">app_service_config_files:
- - /home/matrix/.synapse/<your-AS>.yaml
- </code></pre>
- <p>The format of the AS configuration file is as follows:</p>
- <pre><code class="language-yaml">url: <base url of AS>
- as_token: <token AS will add to requests to HS>
- hs_token: <token HS will add to requests to AS>
- sender_localpart: <localpart of AS user>
- namespaces:
- users: # List of users we're interested in
- - exclusive: <bool>
- regex: <regex>
- group_id: <group>
- - ...
- aliases: [] # List of aliases we're interested in
- rooms: [] # List of room ids we're interested in
- </code></pre>
- <p><code>exclusive</code>: If enabled, only this application service is allowed to register users in its namespace(s).
- <code>group_id</code>: All users of this application service are dynamically joined to this group. This is useful for e.g user organisation or flairs.</p>
- <p>See the <a href="https://matrix.org/docs/spec/application_service/unstable.html">spec</a> for further details on how application services work.</p>
- <div style="break-before: page; page-break-before: always;"></div><h1 id="server-notices"><a class="header" href="#server-notices">Server Notices</a></h1>
- <p>'Server Notices' are a new feature introduced in Synapse 0.30. They provide a
- channel whereby server administrators can send messages to users on the server.</p>
- <p>They are used as part of communication of the server polices (see
- <a href="consent_tracking.html">Consent Tracking</a>), however the intention is that
- they may also find a use for features such as "Message of the day".</p>
- <p>This is a feature specific to Synapse, but it uses standard Matrix
- communication mechanisms, so should work with any Matrix client.</p>
- <h2 id="user-experience"><a class="header" href="#user-experience">User experience</a></h2>
- <p>When the user is first sent a server notice, they will get an invitation to a
- room (typically called 'Server Notices', though this is configurable in
- <code>homeserver.yaml</code>). They will be <strong>unable to reject</strong> this invitation -
- attempts to do so will receive an error.</p>
- <p>Once they accept the invitation, they will see the notice message in the room
- history; it will appear to have come from the 'server notices user' (see
- below).</p>
- <p>The user is prevented from sending any messages in this room by the power
- levels.</p>
- <p>Having joined the room, the user can leave the room if they want. Subsequent
- server notices will then cause a new room to be created.</p>
- <h2 id="synapse-configuration"><a class="header" href="#synapse-configuration">Synapse configuration</a></h2>
- <p>Server notices come from a specific user id on the server. Server
- administrators are free to choose the user id - something like <code>server</code> is
- suggested, meaning the notices will come from
- <code>@server:<your_server_name></code>. Once the Server Notices user is configured, that
- user id becomes a special, privileged user, so administrators should ensure
- that <strong>it is not already allocated</strong>.</p>
- <p>In order to support server notices, it is necessary to add some configuration
- to the <code>homeserver.yaml</code> file. In particular, you should add a <code>server_notices</code>
- section, which should look like this:</p>
- <pre><code class="language-yaml">server_notices:
- system_mxid_localpart: server
- system_mxid_display_name: "Server Notices"
- system_mxid_avatar_url: "mxc://server.com/oumMVlgDnLYFaPVkExemNVVZ"
- room_name: "Server Notices"
- </code></pre>
- <p>The only compulsory setting is <code>system_mxid_localpart</code>, which defines the user
- id of the Server Notices user, as above. <code>room_name</code> defines the name of the
- room which will be created.</p>
- <p><code>system_mxid_display_name</code> and <code>system_mxid_avatar_url</code> can be used to set the
- displayname and avatar of the Server Notices user.</p>
- <h2 id="sending-notices"><a class="header" href="#sending-notices">Sending notices</a></h2>
- <p>To send server notices to users you can use the
- <a href="admin_api/server_notices.html">admin_api</a>.</p>
- <div style="break-before: page; page-break-before: always;"></div><h1 id="support-in-synapse-for-tracking-agreement-to-server-terms-and-conditions"><a class="header" href="#support-in-synapse-for-tracking-agreement-to-server-terms-and-conditions">Support in Synapse for tracking agreement to server terms and conditions</a></h1>
- <p>Synapse 0.30 introduces support for tracking whether users have agreed to the
- terms and conditions set by the administrator of a server - and blocking access
- to the server until they have.</p>
- <p>There are several parts to this functionality; each requires some specific
- configuration in <code>homeserver.yaml</code> to be enabled.</p>
- <p>Note that various parts of the configuation and this document refer to the
- "privacy policy": agreement with a privacy policy is one particular use of this
- feature, but of course adminstrators can specify other terms and conditions
- unrelated to "privacy" per se.</p>
- <h2 id="collecting-policy-agreement-from-a-user"><a class="header" href="#collecting-policy-agreement-from-a-user">Collecting policy agreement from a user</a></h2>
- <p>Synapse can be configured to serve the user a simple policy form with an
- "accept" button. Clicking "Accept" records the user's acceptance in the
- database and shows a success page.</p>
- <p>To enable this, first create templates for the policy and success pages.
- These should be stored on the local filesystem.</p>
- <p>These templates use the <a href="http://jinja.pocoo.org">Jinja2</a> templating language,
- and <a href="https://github.com/matrix-org/synapse/tree/develop/docs/privacy_policy_templates/">docs/privacy_policy_templates</a>
- gives examples of the sort of thing that can be done.</p>
- <p>Note that the templates must be stored under a name giving the language of the
- template - currently this must always be <code>en</code> (for "English");
- internationalisation support is intended for the future.</p>
- <p>The template for the policy itself should be versioned and named according to
- the version: for example <code>1.0.html</code>. The version of the policy which the user
- has agreed to is stored in the database.</p>
- <p>Once the templates are in place, make the following changes to <code>homeserver.yaml</code>:</p>
- <ol>
- <li>
- <p>Add a <code>user_consent</code> section, which should look like:</p>
- <pre><code class="language-yaml">user_consent:
- template_dir: privacy_policy_templates
- version: 1.0
- </code></pre>
- <p><code>template_dir</code> points to the directory containing the policy
- templates. <code>version</code> defines the version of the policy which will be served
- to the user. In the example above, Synapse will serve
- <code>privacy_policy_templates/en/1.0.html</code>.</p>
- </li>
- <li>
- <p>Add a <code>form_secret</code> setting at the top level:</p>
- <pre><code class="language-yaml">form_secret: "<unique secret>"
- </code></pre>
- <p>This should be set to an arbitrary secret string (try <code>pwgen -y 30</code> to
- generate suitable secrets).</p>
- <p>More on what this is used for below.</p>
- </li>
- <li>
- <p>Add <code>consent</code> wherever the <code>client</code> resource is currently enabled in the
- <code>listeners</code> configuration. For example:</p>
- <pre><code class="language-yaml">listeners:
- - port: 8008
- resources:
- - names:
- - client
- - consent
- </code></pre>
- </li>
- </ol>
- <p>Finally, ensure that <code>jinja2</code> is installed. If you are using a virtualenv, this
- should be a matter of <code>pip install Jinja2</code>. On debian, try <code>apt-get install python-jinja2</code>.</p>
- <p>Once this is complete, and the server has been restarted, try visiting
- <code>https://<server>/_matrix/consent</code>. If correctly configured, this should give
- an error "Missing string query parameter 'u'". It is now possible to manually
- construct URIs where users can give their consent.</p>
- <h3 id="enabling-consent-tracking-at-registration"><a class="header" href="#enabling-consent-tracking-at-registration">Enabling consent tracking at registration</a></h3>
- <ol>
- <li>
- <p>Add the following to your configuration:</p>
- <pre><code class="language-yaml">user_consent:
- require_at_registration: true
- policy_name: "Privacy Policy" # or whatever you'd like to call the policy
- </code></pre>
- </li>
- <li>
- <p>In your consent templates, make use of the <code>public_version</code> variable to
- see if an unauthenticated user is viewing the page. This is typically
- wrapped around the form that would be used to actually agree to the document:</p>
- <pre><code>{% if not public_version %}
- <!-- The variables used here are only provided when the 'u' param is given to the homeserver -->
- <form method="post" action="consent">
- <input type="hidden" name="v" value="{{version}}"/>
- <input type="hidden" name="u" value="{{user}}"/>
- <input type="hidden" name="h" value="{{userhmac}}"/>
- <input type="submit" value="Sure thing!"/>
- </form>
- {% endif %}
- </code></pre>
- </li>
- <li>
- <p>Restart Synapse to apply the changes.</p>
- </li>
- </ol>
- <p>Visiting <code>https://<server>/_matrix/consent</code> should now give you a view of the privacy
- document. This is what users will be able to see when registering for accounts.</p>
- <h3 id="constructing-the-consent-uri"><a class="header" href="#constructing-the-consent-uri">Constructing the consent URI</a></h3>
- <p>It may be useful to manually construct the "consent URI" for a given user - for
- instance, in order to send them an email asking them to consent. To do this,
- take the base <code>https://<server>/_matrix/consent</code> URL and add the following
- query parameters:</p>
- <ul>
- <li>
- <p><code>u</code>: the user id of the user. This can either be a full MXID
- (<code>@user:server.com</code>) or just the localpart (<code>user</code>).</p>
- </li>
- <li>
- <p><code>h</code>: hex-encoded HMAC-SHA256 of <code>u</code> using the <code>form_secret</code> as a key. It is
- possible to calculate this on the commandline with something like:</p>
- <pre><code class="language-bash">echo -n '<user>' | openssl sha256 -hmac '<form_secret>'
- </code></pre>
- <p>This should result in a URI which looks something like:
- <code>https://<server>/_matrix/consent?u=<user>&h=68a152465a4d...</code>.</p>
- </li>
- </ul>
- <p>Note that not providing a <code>u</code> parameter will be interpreted as wanting to view
- the document from an unauthenticated perspective, such as prior to registration.
- Therefore, the <code>h</code> parameter is not required in this scenario. To enable this
- behaviour, set <code>require_at_registration</code> to <code>true</code> in your <code>user_consent</code> config.</p>
- <h2 id="sending-users-a-server-notice-asking-them-to-agree-to-the-policy"><a class="header" href="#sending-users-a-server-notice-asking-them-to-agree-to-the-policy">Sending users a server notice asking them to agree to the policy</a></h2>
- <p>It is possible to configure Synapse to send a <a href="server_notices.html">server
- notice</a> to anybody who has not yet agreed to the current
- version of the policy. To do so:</p>
- <ul>
- <li>
- <p>ensure that the consent resource is configured, as in the previous section</p>
- </li>
- <li>
- <p>ensure that server notices are configured, as in <a href="server_notices.html">the server notice documentation</a>.</p>
- </li>
- <li>
- <p>Add <code>server_notice_content</code> under <code>user_consent</code> in <code>homeserver.yaml</code>. For
- example:</p>
- <pre><code class="language-yaml">user_consent:
- server_notice_content:
- msgtype: m.text
- body: >-
- Please give your consent to the privacy policy at %(consent_uri)s.
- </code></pre>
- <p>Synapse automatically replaces the placeholder <code>%(consent_uri)s</code> with the
- consent uri for that user.</p>
- </li>
- <li>
- <p>ensure that <code>public_baseurl</code> is set in <code>homeserver.yaml</code>, and gives the base
- URI that clients use to connect to the server. (It is used to construct
- <code>consent_uri</code> in the server notice.)</p>
- </li>
- </ul>
- <h2 id="blocking-users-from-using-the-server-until-they-agree-to-the-policy"><a class="header" href="#blocking-users-from-using-the-server-until-they-agree-to-the-policy">Blocking users from using the server until they agree to the policy</a></h2>
- <p>Synapse can be configured to block any attempts to join rooms or send messages
- until the user has given their agreement to the policy. (Joining the server
- notices room is exempted from this).</p>
- <p>To enable this, add <code>block_events_error</code> under <code>user_consent</code>. For example:</p>
- <pre><code class="language-yaml">user_consent:
- block_events_error: >-
- You can't send any messages until you consent to the privacy policy at
- %(consent_uri)s.
- </code></pre>
- <p>Synapse automatically replaces the placeholder <code>%(consent_uri)s</code> with the
- consent uri for that user.</p>
- <p>ensure that <code>public_baseurl</code> is set in <code>homeserver.yaml</code>, and gives the base
- URI that clients use to connect to the server. (It is used to construct
- <code>consent_uri</code> in the error.)</p>
- <div style="break-before: page; page-break-before: always;"></div><h1 id="url-previews-1"><a class="header" href="#url-previews-1">URL Previews</a></h1>
- <p>Design notes on a URL previewing service for Matrix:</p>
- <p>Options are:</p>
- <ol>
- <li>Have an AS which listens for URLs, downloads them, and inserts an event that describes their metadata.</li>
- </ol>
- <ul>
- <li>Pros:
- <ul>
- <li>Decouples the implementation entirely from Synapse.</li>
- <li>Uses existing Matrix events & content repo to store the metadata.</li>
- </ul>
- </li>
- <li>Cons:
- <ul>
- <li>Which AS should provide this service for a room, and why should you trust it?</li>
- <li>Doesn't work well with E2E; you'd have to cut the AS into every room</li>
- <li>the AS would end up subscribing to every room anyway.</li>
- </ul>
- </li>
- </ul>
- <ol start="2">
- <li>Have a generic preview API (nothing to do with Matrix) that provides a previewing service:</li>
- </ol>
- <ul>
- <li>Pros:
- <ul>
- <li>Simple and flexible; can be used by any clients at any point</li>
- </ul>
- </li>
- <li>Cons:
- <ul>
- <li>If each HS provides one of these independently, all the HSes in a room may needlessly DoS the target URI</li>
- <li>We need somewhere to store the URL metadata rather than just using Matrix itself</li>
- <li>We can't piggyback on matrix to distribute the metadata between HSes.</li>
- </ul>
- </li>
- </ul>
- <ol start="3">
- <li>Make the synapse of the sending user responsible for spidering the URL and inserting an event asynchronously which describes the metadata.</li>
- </ol>
- <ul>
- <li>Pros:
- <ul>
- <li>Works transparently for all clients</li>
- <li>Piggy-backs nicely on using Matrix for distributing the metadata.</li>
- <li>No confusion as to which AS</li>
- </ul>
- </li>
- <li>Cons:
- <ul>
- <li>Doesn't work with E2E</li>
- <li>We might want to decouple the implementation of the spider from the HS, given spider behaviour can be quite complicated and evolve much more rapidly than the HS. It's more like a bot than a core part of the server.</li>
- </ul>
- </li>
- </ul>
- <ol start="4">
- <li>Make the sending client use the preview API and insert the event itself when successful.</li>
- </ol>
- <ul>
- <li>Pros:
- <ul>
- <li>Works well with E2E</li>
- <li>No custom server functionality</li>
- <li>Lets the client customise the preview that they send (like on FB)</li>
- </ul>
- </li>
- <li>Cons:
- <ul>
- <li>Entirely specific to the sending client, whereas it'd be nice if /any/ URL was correctly previewed if clients support it.</li>
- </ul>
- </li>
- </ul>
- <ol start="5">
- <li>Have the option of specifying a shared (centralised) previewing service used by a room, to avoid all the different HSes in the room DoSing the target.</li>
- </ol>
- <p>Best solution is probably a combination of both 2 and 4.</p>
- <ul>
- <li>Sending clients do their best to create and send a preview at the point of sending the message, perhaps delaying the message until the preview is computed? (This also lets the user validate the preview before sending)</li>
- <li>Receiving clients have the option of going and creating their own preview if one doesn't arrive soon enough (or if the original sender didn't create one)</li>
- </ul>
- <p>This is a bit magical though in that the preview could come from two entirely different sources - the sending HS or your local one. However, this can always be exposed to users: "Generate your own URL previews if none are available?"</p>
- <p>This is tantamount also to senders calculating their own thumbnails for sending in advance of the main content - we are trusting the sender not to lie about the content in the thumbnail. Whereas currently thumbnails are calculated by the receiving homeserver to avoid this attack.</p>
- <p>However, this kind of phishing attack does exist whether we let senders pick their thumbnails or not, in that a malicious sender can send normal text messages around the attachment claiming it to be legitimate. We could rely on (future) reputation/abuse management to punish users who phish (be it with bogus metadata or bogus descriptions). Bogus metadata is particularly bad though, especially if it's avoidable.</p>
- <p>As a first cut, let's do #2 and have the receiver hit the API to calculate its own previews (as it does currently for image thumbnails). We can then extend/optimise this to option 4 as a special extra if needed.</p>
- <h2 id="api"><a class="header" href="#api">API</a></h2>
- <pre><code>GET /_matrix/media/r0/preview_url?url=http://wherever.com
- 200 OK
- {
- "og:type" : "article"
- "og:url" : "https://twitter.com/matrixdotorg/status/684074366691356672"
- "og:title" : "Matrix on Twitter"
- "og:image" : "https://pbs.twimg.com/profile_images/500400952029888512/yI0qtFi7_400x400.png"
- "og:description" : "“Synapse 0.12 is out! Lots of polishing, performance &amp;amp; bugfixes: /sync API, /r0 prefix, fulltext search, 3PID invites https://t.co/5alhXLLEGP”"
- "og:site_name" : "Twitter"
- }
- </code></pre>
- <ul>
- <li>Downloads the URL
- <ul>
- <li>If HTML, just stores it in RAM and parses it for OG meta tags
- <ul>
- <li>Download any media OG meta tags to the media repo, and refer to them in the OG via mxc:// URIs.</li>
- </ul>
- </li>
- <li>If a media filetype we know we can thumbnail: store it on disk, and hand it to the thumbnailer. Generate OG meta tags from the thumbnailer contents.</li>
- <li>Otherwise, don't bother downloading further.</li>
- </ul>
- </li>
- </ul>
- <div style="break-before: page; page-break-before: always;"></div><h1 id="user-directory-api-implementation"><a class="header" href="#user-directory-api-implementation">User Directory API Implementation</a></h1>
- <p>The user directory is currently maintained based on the 'visible' users
- on this particular server - i.e. ones which your account shares a room with, or
- who are present in a publicly viewable room present on the server.</p>
- <p>The directory info is stored in various tables, which can (typically after
- DB corruption) get stale or out of sync. If this happens, for now the
- solution to fix it is to execute the SQL <a href="https://github.com/matrix-org/synapse/blob/master/synapse/storage/schema/main/delta/53/user_dir_populate.sql">here</a>
- and then restart synapse. This should then start a background task to
- flush the current tables and regenerate the directory.</p>
- <div style="break-before: page; page-break-before: always;"></div><h1 id="message-retention-policies"><a class="header" href="#message-retention-policies">Message retention policies</a></h1>
- <p>Synapse admins can enable support for message retention policies on
- their homeserver. Message retention policies exist at a room level,
- follow the semantics described in
- <a href="https://github.com/matrix-org/matrix-doc/blob/matthew/msc1763/proposals/1763-configurable-retention-periods.md">MSC1763</a>,
- and allow server and room admins to configure how long messages should
- be kept in a homeserver's database before being purged from it.
- <strong>Please note that, as this feature isn't part of the Matrix
- specification yet, this implementation is to be considered as
- experimental.</strong> </p>
- <p>A message retention policy is mainly defined by its <code>max_lifetime</code>
- parameter, which defines how long a message can be kept around after
- it was sent to the room. If a room doesn't have a message retention
- policy, and there's no default one for a given server, then no message
- sent in that room is ever purged on that server.</p>
- <p>MSC1763 also specifies semantics for a <code>min_lifetime</code> parameter which
- defines the amount of time after which an event <em>can</em> get purged (after
- it was sent to the room), but Synapse doesn't currently support it
- beyond registering it.</p>
- <p>Both <code>max_lifetime</code> and <code>min_lifetime</code> are optional parameters.</p>
- <p>Note that message retention policies don't apply to state events.</p>
- <p>Once an event reaches its expiry date (defined as the time it was sent
- plus the value for <code>max_lifetime</code> in the room), two things happen:</p>
- <ul>
- <li>Synapse stops serving the event to clients via any endpoint.</li>
- <li>The message gets picked up by the next purge job (see the "Purge jobs"
- section) and is removed from Synapse's database.</li>
- </ul>
- <p>Since purge jobs don't run continuously, this means that an event might
- stay in a server's database for longer than the value for <code>max_lifetime</code>
- in the room would allow, though hidden from clients.</p>
- <p>Similarly, if a server (with support for message retention policies
- enabled) receives from another server an event that should have been
- purged according to its room's policy, then the receiving server will
- process and store that event until it's picked up by the next purge job,
- though it will always hide it from clients.</p>
- <p>Synapse requires at least one message in each room, so it will never
- delete the last message in a room. It will, however, hide it from
- clients.</p>
- <h2 id="server-configuration"><a class="header" href="#server-configuration">Server configuration</a></h2>
- <p>Support for this feature can be enabled and configured in the
- <code>retention</code> section of the Synapse configuration file (see the
- <a href="https://github.com/matrix-org/synapse/blob/v1.36.0/docs/sample_config.yaml#L451-L518">sample file</a>).</p>
- <p>To enable support for message retention policies, set the setting
- <code>enabled</code> in this section to <code>true</code>.</p>
- <h3 id="default-policy"><a class="header" href="#default-policy">Default policy</a></h3>
- <p>A default message retention policy is a policy defined in Synapse's
- configuration that is used by Synapse for every room that doesn't have a
- message retention policy configured in its state. This allows server
- admins to ensure that messages are never kept indefinitely in a server's
- database. </p>
- <p>A default policy can be defined as such, in the <code>retention</code> section of
- the configuration file:</p>
- <pre><code class="language-yaml"> default_policy:
- min_lifetime: 1d
- max_lifetime: 1y
- </code></pre>
- <p>Here, <code>min_lifetime</code> and <code>max_lifetime</code> have the same meaning and level
- of support as previously described. They can be expressed either as a
- duration (using the units <code>s</code> (seconds), <code>m</code> (minutes), <code>h</code> (hours),
- <code>d</code> (days), <code>w</code> (weeks) and <code>y</code> (years)) or as a number of milliseconds.</p>
- <h3 id="purge-jobs"><a class="header" href="#purge-jobs">Purge jobs</a></h3>
- <p>Purge jobs are the jobs that Synapse runs in the background to purge
- expired events from the database. They are only run if support for
- message retention policies is enabled in the server's configuration. If
- no configuration for purge jobs is configured by the server admin,
- Synapse will use a default configuration, which is described in the
- <a href="https://github.com/matrix-org/synapse/blob/v1.36.0/docs/sample_config.yaml#L451-L518">sample configuration file</a>.</p>
- <p>Some server admins might want a finer control on when events are removed
- depending on an event's room's policy. This can be done by setting the
- <code>purge_jobs</code> sub-section in the <code>retention</code> section of the configuration
- file. An example of such configuration could be:</p>
- <pre><code class="language-yaml"> purge_jobs:
- - longest_max_lifetime: 3d
- interval: 12h
- - shortest_max_lifetime: 3d
- longest_max_lifetime: 1w
- interval: 1d
- - shortest_max_lifetime: 1w
- interval: 2d
- </code></pre>
- <p>In this example, we define three jobs:</p>
- <ul>
- <li>one that runs twice a day (every 12 hours) and purges events in rooms
- which policy's <code>max_lifetime</code> is lower or equal to 3 days.</li>
- <li>one that runs once a day and purges events in rooms which policy's
- <code>max_lifetime</code> is between 3 days and a week.</li>
- <li>one that runs once every 2 days and purges events in rooms which
- policy's <code>max_lifetime</code> is greater than a week.</li>
- </ul>
- <p>Note that this example is tailored to show different configurations and
- features slightly more jobs than it's probably necessary (in practice, a
- server admin would probably consider it better to replace the two last
- jobs with one that runs once a day and handles rooms which which
- policy's <code>max_lifetime</code> is greater than 3 days).</p>
- <p>Keep in mind, when configuring these jobs, that a purge job can become
- quite heavy on the server if it targets many rooms, therefore prefer
- having jobs with a low interval that target a limited set of rooms. Also
- make sure to include a job with no minimum and one with no maximum to
- make sure your configuration handles every policy.</p>
- <p>As previously mentioned in this documentation, while a purge job that
- runs e.g. every day means that an expired event might stay in the
- database for up to a day after its expiry, Synapse hides expired events
- from clients as soon as they expire, so the event is not visible to
- local users between its expiry date and the moment it gets purged from
- the server's database.</p>
- <h3 id="lifetime-limits"><a class="header" href="#lifetime-limits">Lifetime limits</a></h3>
- <p>Server admins can set limits on the values of <code>max_lifetime</code> to use when
- purging old events in a room. These limits can be defined as such in the
- <code>retention</code> section of the configuration file:</p>
- <pre><code class="language-yaml"> allowed_lifetime_min: 1d
- allowed_lifetime_max: 1y
- </code></pre>
- <p>The limits are considered when running purge jobs. If necessary, the
- effective value of <code>max_lifetime</code> will be brought between
- <code>allowed_lifetime_min</code> and <code>allowed_lifetime_max</code> (inclusive).
- This means that, if the value of <code>max_lifetime</code> defined in the room's state
- is lower than <code>allowed_lifetime_min</code>, the value of <code>allowed_lifetime_min</code>
- will be used instead. Likewise, if the value of <code>max_lifetime</code> is higher
- than <code>allowed_lifetime_max</code>, the value of <code>allowed_lifetime_max</code> will be
- used instead.</p>
- <p>In the example above, we ensure Synapse never deletes events that are less
- than one day old, and that it always deletes events that are over a year
- old.</p>
- <p>If a default policy is set, and its <code>max_lifetime</code> value is lower than
- <code>allowed_lifetime_min</code> or higher than <code>allowed_lifetime_max</code>, the same
- process applies.</p>
- <p>Both parameters are optional; if one is omitted Synapse won't use it to
- adjust the effective value of <code>max_lifetime</code>.</p>
- <p>Like other settings in this section, these parameters can be expressed
- either as a duration or as a number of milliseconds.</p>
- <h2 id="room-configuration"><a class="header" href="#room-configuration">Room configuration</a></h2>
- <p>To configure a room's message retention policy, a room's admin or
- moderator needs to send a state event in that room with the type
- <code>m.room.retention</code> and the following content:</p>
- <pre><code class="language-json">{
- "max_lifetime": ...
- }
- </code></pre>
- <p>In this event's content, the <code>max_lifetime</code> parameter has the same
- meaning as previously described, and needs to be expressed in
- milliseconds. The event's content can also include a <code>min_lifetime</code>
- parameter, which has the same meaning and limited support as previously
- described.</p>
- <p>Note that over every server in the room, only the ones with support for
- message retention policies will actually remove expired events. This
- support is currently not enabled by default in Synapse.</p>
- <h2 id="note-on-reclaiming-disk-space"><a class="header" href="#note-on-reclaiming-disk-space">Note on reclaiming disk space</a></h2>
- <p>While purge jobs actually delete data from the database, the disk space
- used by the database might not decrease immediately on the database's
- host. However, even though the database engine won't free up the disk
- space, it will start writing new data into where the purged data was.</p>
- <p>If you want to reclaim the freed disk space anyway and return it to the
- operating system, the server admin needs to run <code>VACUUM FULL;</code> (or
- <code>VACUUM;</code> for SQLite databases) on Synapse's database (see the related
- <a href="https://www.postgresql.org/docs/current/sql-vacuum.html">PostgreSQL documentation</a>).</p>
- <div style="break-before: page; page-break-before: always;"></div><h1 id="modules"><a class="header" href="#modules">Modules</a></h1>
- <p>Synapse supports extending its functionality by configuring external modules.</p>
- <h2 id="using-modules"><a class="header" href="#using-modules">Using modules</a></h2>
- <p>To use a module on Synapse, add it to the <code>modules</code> section of the configuration file:</p>
- <pre><code class="language-yaml">modules:
- - module: my_super_module.MySuperClass
- config:
- do_thing: true
- - module: my_other_super_module.SomeClass
- config: {}
- </code></pre>
- <p>Each module is defined by a path to a Python class as well as a configuration. This
- information for a given module should be available in the module's own documentation.</p>
- <p><strong>Note</strong>: When using third-party modules, you effectively allow someone else to run
- custom code on your Synapse homeserver. Server admins are encouraged to verify the
- provenance of the modules they use on their homeserver and make sure the modules aren't
- running malicious code on their instance.</p>
- <p>Also note that we are currently in the process of migrating module interfaces to this
- system. While some interfaces might be compatible with it, others still require
- configuring modules in another part of Synapse's configuration file. Currently, only the
- spam checker interface is compatible with this new system.</p>
- <h2 id="writing-a-module"><a class="header" href="#writing-a-module">Writing a module</a></h2>
- <p>A module is a Python class that uses Synapse's module API to interact with the
- homeserver. It can register callbacks that Synapse will call on specific operations, as
- well as web resources to attach to Synapse's web server.</p>
- <p>When instantiated, a module is given its parsed configuration as well as an instance of
- the <code>synapse.module_api.ModuleApi</code> class. The configuration is a dictionary, and is
- either the output of the module's <code>parse_config</code> static method (see below), or the
- configuration associated with the module in Synapse's configuration file.</p>
- <p>See the documentation for the <code>ModuleApi</code> class
- <a href="https://github.com/matrix-org/synapse/blob/master/synapse/module_api/__init__.py">here</a>.</p>
- <h3 id="handling-the-modules-configuration"><a class="header" href="#handling-the-modules-configuration">Handling the module's configuration</a></h3>
- <p>A module can implement the following static method:</p>
- <pre><code class="language-python">@staticmethod
- def parse_config(config: dict) -> dict
- </code></pre>
- <p>This method is given a dictionary resulting from parsing the YAML configuration for the
- module. It may modify it (for example by parsing durations expressed as strings (e.g.
- "5d") into milliseconds, etc.), and return the modified dictionary. It may also verify
- that the configuration is correct, and raise an instance of
- <code>synapse.module_api.errors.ConfigError</code> if not.</p>
- <h3 id="registering-a-web-resource"><a class="header" href="#registering-a-web-resource">Registering a web resource</a></h3>
- <p>Modules can register web resources onto Synapse's web server using the following module
- API method:</p>
- <pre><code class="language-python">def ModuleApi.register_web_resource(path: str, resource: IResource) -> None
- </code></pre>
- <p>The path is the full absolute path to register the resource at. For example, if you
- register a resource for the path <code>/_synapse/client/my_super_module/say_hello</code>, Synapse
- will serve it at <code>http(s)://[HS_URL]/_synapse/client/my_super_module/say_hello</code>. Note
- that Synapse does not allow registering resources for several sub-paths in the <code>/_matrix</code>
- namespace (such as anything under <code>/_matrix/client</code> for example). It is strongly
- recommended that modules register their web resources under the <code>/_synapse/client</code>
- namespace.</p>
- <p>The provided resource is a Python class that implements Twisted's <a href="https://twistedmatrix.com/documents/current/api/twisted.web.resource.IResource.html">IResource</a>
- interface (such as <a href="https://twistedmatrix.com/documents/current/api/twisted.web.resource.Resource.html">Resource</a>).</p>
- <p>Only one resource can be registered for a given path. If several modules attempt to
- register a resource for the same path, the module that appears first in Synapse's
- configuration file takes priority.</p>
- <p>Modules <strong>must</strong> register their web resources in their <code>__init__</code> method.</p>
- <h3 id="registering-a-callback"><a class="header" href="#registering-a-callback">Registering a callback</a></h3>
- <p>Modules can use Synapse's module API to register callbacks. Callbacks are functions that
- Synapse will call when performing specific actions. Callbacks must be asynchronous, and
- are split in categories. A single module may implement callbacks from multiple categories,
- and is under no obligation to implement all callbacks from the categories it registers
- callbacks for.</p>
- <p>Modules can register callbacks using one of the module API's <code>register_[...]_callbacks</code>
- methods. The callback functions are passed to these methods as keyword arguments, with
- the callback name as the argument name and the function as its value. This is demonstrated
- in the example below. A <code>register_[...]_callbacks</code> method exists for each module type
- documented in this section.</p>
- <h4 id="spam-checker-callbacks"><a class="header" href="#spam-checker-callbacks">Spam checker callbacks</a></h4>
- <p>Spam checker callbacks allow module developers to implement spam mitigation actions for
- Synapse instances. Spam checker callbacks can be registered using the module API's
- <code>register_spam_checker_callbacks</code> method.</p>
- <p>The available spam checker callbacks are:</p>
- <pre><code class="language-python">async def check_event_for_spam(event: "synapse.events.EventBase") -> Union[bool, str]
- </code></pre>
- <p>Called when receiving an event from a client or via federation. The module can return
- either a <code>bool</code> to indicate whether the event must be rejected because of spam, or a <code>str</code>
- to indicate the event must be rejected because of spam and to give a rejection reason to
- forward to clients.</p>
- <pre><code class="language-python">async def user_may_invite(inviter: str, invitee: str, room_id: str) -> bool
- </code></pre>
- <p>Called when processing an invitation. The module must return a <code>bool</code> indicating whether
- the inviter can invite the invitee to the given room. Both inviter and invitee are
- represented by their Matrix user ID (e.g. <code>@alice:example.com</code>).</p>
- <pre><code class="language-python">async def user_may_create_room(user: str) -> bool
- </code></pre>
- <p>Called when processing a room creation request. The module must return a <code>bool</code> indicating
- whether the given user (represented by their Matrix user ID) is allowed to create a room.</p>
- <pre><code class="language-python">async def user_may_create_room_alias(user: str, room_alias: "synapse.types.RoomAlias") -> bool
- </code></pre>
- <p>Called when trying to associate an alias with an existing room. The module must return a
- <code>bool</code> indicating whether the given user (represented by their Matrix user ID) is allowed
- to set the given alias.</p>
- <pre><code class="language-python">async def user_may_publish_room(user: str, room_id: str) -> bool
- </code></pre>
- <p>Called when trying to publish a room to the homeserver's public rooms directory. The
- module must return a <code>bool</code> indicating whether the given user (represented by their
- Matrix user ID) is allowed to publish the given room.</p>
- <pre><code class="language-python">async def check_username_for_spam(user_profile: Dict[str, str]) -> bool
- </code></pre>
- <p>Called when computing search results in the user directory. The module must return a
- <code>bool</code> indicating whether the given user profile can appear in search results. The profile
- is represented as a dictionary with the following keys:</p>
- <ul>
- <li><code>user_id</code>: The Matrix ID for this user.</li>
- <li><code>display_name</code>: The user's display name.</li>
- <li><code>avatar_url</code>: The <code>mxc://</code> URL to the user's avatar.</li>
- </ul>
- <p>The module is given a copy of the original dictionary, so modifying it from within the
- module cannot modify a user's profile when included in user directory search results.</p>
- <pre><code class="language-python">async def check_registration_for_spam(
- email_threepid: Optional[dict],
- username: Optional[str],
- request_info: Collection[Tuple[str, str]],
- auth_provider_id: Optional[str] = None,
- ) -> "synapse.spam_checker_api.RegistrationBehaviour"
- </code></pre>
- <p>Called when registering a new user. The module must return a <code>RegistrationBehaviour</code>
- indicating whether the registration can go through or must be denied, or whether the user
- may be allowed to register but will be shadow banned.</p>
- <p>The arguments passed to this callback are:</p>
- <ul>
- <li><code>email_threepid</code>: The email address used for registering, if any.</li>
- <li><code>username</code>: The username the user would like to register. Can be <code>None</code>, meaning that
- Synapse will generate one later.</li>
- <li><code>request_info</code>: A collection of tuples, which first item is a user agent, and which
- second item is an IP address. These user agents and IP addresses are the ones that were
- used during the registration process.</li>
- <li><code>auth_provider_id</code>: The identifier of the SSO authentication provider, if any.</li>
- </ul>
- <pre><code class="language-python">async def check_media_file_for_spam(
- file_wrapper: "synapse.rest.media.v1.media_storage.ReadableFileWrapper",
- file_info: "synapse.rest.media.v1._base.FileInfo",
- ) -> bool
- </code></pre>
- <p>Called when storing a local or remote file. The module must return a boolean indicating
- whether the given file can be stored in the homeserver's media store.</p>
- <h4 id="account-validity-callbacks"><a class="header" href="#account-validity-callbacks">Account validity callbacks</a></h4>
- <p>Account validity callbacks allow module developers to add extra steps to verify the
- validity on an account, i.e. see if a user can be granted access to their account on the
- Synapse instance. Account validity callbacks can be registered using the module API's
- <code>register_account_validity_callbacks</code> method.</p>
- <p>The available account validity callbacks are:</p>
- <pre><code class="language-python">async def is_user_expired(user: str) -> Optional[bool]
- </code></pre>
- <p>Called when processing any authenticated request (except for logout requests). The module
- can return a <code>bool</code> to indicate whether the user has expired and should be locked out of
- their account, or <code>None</code> if the module wasn't able to figure it out. The user is
- represented by their Matrix user ID (e.g. <code>@alice:example.com</code>).</p>
- <p>If the module returns <code>True</code>, the current request will be denied with the error code
- <code>ORG_MATRIX_EXPIRED_ACCOUNT</code> and the HTTP status code 403. Note that this doesn't
- invalidate the user's access token.</p>
- <pre><code class="language-python">async def on_user_registration(user: str) -> None
- </code></pre>
- <p>Called after successfully registering a user, in case the module needs to perform extra
- operations to keep track of them. (e.g. add them to a database table). The user is
- represented by their Matrix user ID.</p>
- <h4 id="third-party-rules-callbacks"><a class="header" href="#third-party-rules-callbacks">Third party rules callbacks</a></h4>
- <p>Third party rules callbacks allow module developers to add extra checks to verify the
- validity of incoming events. Third party event rules callbacks can be registered using
- the module API's <code>register_third_party_rules_callbacks</code> method.</p>
- <p>The available third party rules callbacks are:</p>
- <pre><code class="language-python">async def check_event_allowed(
- event: "synapse.events.EventBase",
- state_events: "synapse.types.StateMap",
- ) -> Tuple[bool, Optional[dict]]
- </code></pre>
- <p><strong><span style="color:red">
- This callback is very experimental and can and will break without notice. Module developers
- are encouraged to implement <code>check_event_for_spam</code> from the spam checker category instead.
- </span></strong></p>
- <p>Called when processing any incoming event, with the event and a <code>StateMap</code>
- representing the current state of the room the event is being sent into. A <code>StateMap</code> is
- a dictionary that maps tuples containing an event type and a state key to the
- corresponding state event. For example retrieving the room's <code>m.room.create</code> event from
- the <code>state_events</code> argument would look like this: <code>state_events.get(("m.room.create", ""))</code>.
- The module must return a boolean indicating whether the event can be allowed.</p>
- <p>Note that this callback function processes incoming events coming via federation
- traffic (on top of client traffic). This means denying an event might cause the local
- copy of the room's history to diverge from that of remote servers. This may cause
- federation issues in the room. It is strongly recommended to only deny events using this
- callback function if the sender is a local user, or in a private federation in which all
- servers are using the same module, with the same configuration.</p>
- <p>If the boolean returned by the module is <code>True</code>, it may also tell Synapse to replace the
- event with new data by returning the new event's data as a dictionary. In order to do
- that, it is recommended the module calls <code>event.get_dict()</code> to get the current event as a
- dictionary, and modify the returned dictionary accordingly.</p>
- <p>Note that replacing the event only works for events sent by local users, not for events
- received over federation.</p>
- <pre><code class="language-python">async def on_create_room(
- requester: "synapse.types.Requester",
- request_content: dict,
- is_requester_admin: bool,
- ) -> None
- </code></pre>
- <p>Called when processing a room creation request, with the <code>Requester</code> object for the user
- performing the request, a dictionary representing the room creation request's JSON body
- (see <a href="https://matrix.org/docs/spec/client_server/latest#post-matrix-client-r0-createroom">the spec</a>
- for a list of possible parameters), and a boolean indicating whether the user performing
- the request is a server admin.</p>
- <p>Modules can modify the <code>request_content</code> (by e.g. adding events to its <code>initial_state</code>),
- or deny the room's creation by raising a <code>module_api.errors.SynapseError</code>.</p>
- <h3 id="porting-an-existing-module-that-uses-the-old-interface"><a class="header" href="#porting-an-existing-module-that-uses-the-old-interface">Porting an existing module that uses the old interface</a></h3>
- <p>In order to port a module that uses Synapse's old module interface, its author needs to:</p>
- <ul>
- <li>ensure the module's callbacks are all asynchronous.</li>
- <li>register their callbacks using one or more of the <code>register_[...]_callbacks</code> methods
- from the <code>ModuleApi</code> class in the module's <code>__init__</code> method (see <a href="modules.html#registering-a-callback">this section</a>
- for more info).</li>
- </ul>
- <p>Additionally, if the module is packaged with an additional web resource, the module
- should register this resource in its <code>__init__</code> method using the <code>register_web_resource</code>
- method from the <code>ModuleApi</code> class (see <a href="modules.html#registering-a-web-resource">this section</a> for
- more info).</p>
- <p>The module's author should also update any example in the module's configuration to only
- use the new <code>modules</code> section in Synapse's configuration file (see <a href="modules.html#using-modules">this section</a>
- for more info).</p>
- <h3 id="example"><a class="header" href="#example">Example</a></h3>
- <p>The example below is a module that implements the spam checker callback
- <code>user_may_create_room</code> to deny room creation to user <code>@evilguy:example.com</code>, and registers
- a web resource to the path <code>/_synapse/client/demo/hello</code> that returns a JSON object.</p>
- <pre><code class="language-python">import json
- from twisted.web.resource import Resource
- from twisted.web.server import Request
- from synapse.module_api import ModuleApi
- class DemoResource(Resource):
- def __init__(self, config):
- super(DemoResource, self).__init__()
- self.config = config
- def render_GET(self, request: Request):
- name = request.args.get(b"name")[0]
- request.setHeader(b"Content-Type", b"application/json")
- return json.dumps({"hello": name})
- class DemoModule:
- def __init__(self, config: dict, api: ModuleApi):
- self.config = config
- self.api = api
- self.api.register_web_resource(
- path="/_synapse/client/demo/hello",
- resource=DemoResource(self.config),
- )
- self.api.register_spam_checker_callbacks(
- user_may_create_room=self.user_may_create_room,
- )
- @staticmethod
- def parse_config(config):
- return config
- async def user_may_create_room(self, user: str) -> bool:
- if user == "@evilguy:example.com":
- return False
- return True
- </code></pre>
- <div style="break-before: page; page-break-before: always;"></div><h2 style="color:red">
- This page of the Synapse documentation is now deprecated. For up to date
- documentation on setting up or writing a spam checker module, please see
- <a href="modules.html">this page</a>.
- </h2>
- <h1 id="handling-spam-in-synapse"><a class="header" href="#handling-spam-in-synapse">Handling spam in Synapse</a></h1>
- <p>Synapse has support to customize spam checking behavior. It can plug into a
- variety of events and affect how they are presented to users on your homeserver.</p>
- <p>The spam checking behavior is implemented as a Python class, which must be
- able to be imported by the running Synapse.</p>
- <h2 id="python-spam-checker-class"><a class="header" href="#python-spam-checker-class">Python spam checker class</a></h2>
- <p>The Python class is instantiated with two objects:</p>
- <ul>
- <li>Any configuration (see below).</li>
- <li>An instance of <code>synapse.module_api.ModuleApi</code>.</li>
- </ul>
- <p>It then implements methods which return a boolean to alter behavior in Synapse.
- All the methods must be defined.</p>
- <p>There's a generic method for checking every event (<code>check_event_for_spam</code>), as
- well as some specific methods:</p>
- <ul>
- <li><code>user_may_invite</code></li>
- <li><code>user_may_create_room</code></li>
- <li><code>user_may_create_room_alias</code></li>
- <li><code>user_may_publish_room</code></li>
- <li><code>check_username_for_spam</code></li>
- <li><code>check_registration_for_spam</code></li>
- <li><code>check_media_file_for_spam</code></li>
- </ul>
- <p>The details of each of these methods (as well as their inputs and outputs)
- are documented in the <code>synapse.events.spamcheck.SpamChecker</code> class.</p>
- <p>The <code>ModuleApi</code> class provides a way for the custom spam checker class to
- call back into the homeserver internals.</p>
- <p>Additionally, a <code>parse_config</code> method is mandatory and receives the plugin config
- dictionary. After parsing, It must return an object which will be
- passed to <code>__init__</code> later.</p>
- <h3 id="example-1"><a class="header" href="#example-1">Example</a></h3>
- <pre><code class="language-python">from synapse.spam_checker_api import RegistrationBehaviour
- class ExampleSpamChecker:
- def __init__(self, config, api):
- self.config = config
- self.api = api
- @staticmethod
- def parse_config(config):
- return config
-
- async def check_event_for_spam(self, foo):
- return False # allow all events
- async def user_may_invite(self, inviter_userid, invitee_userid, room_id):
- return True # allow all invites
- async def user_may_create_room(self, userid):
- return True # allow all room creations
- async def user_may_create_room_alias(self, userid, room_alias):
- return True # allow all room aliases
- async def user_may_publish_room(self, userid, room_id):
- return True # allow publishing of all rooms
- async def check_username_for_spam(self, user_profile):
- return False # allow all usernames
- async def check_registration_for_spam(
- self,
- email_threepid,
- username,
- request_info,
- auth_provider_id,
- ):
- return RegistrationBehaviour.ALLOW # allow all registrations
- async def check_media_file_for_spam(self, file_wrapper, file_info):
- return False # allow all media
- </code></pre>
- <h2 id="configuration-2"><a class="header" href="#configuration-2">Configuration</a></h2>
- <p>Modify the <code>spam_checker</code> section of your <code>homeserver.yaml</code> in the following
- manner:</p>
- <p>Create a list entry with the keys <code>module</code> and <code>config</code>.</p>
- <ul>
- <li>
- <p><code>module</code> should point to the fully qualified Python class that implements your
- custom logic, e.g. <code>my_module.ExampleSpamChecker</code>.</p>
- </li>
- <li>
- <p><code>config</code> is a dictionary that gets passed to the spam checker class.</p>
- </li>
- </ul>
- <h3 id="example-2"><a class="header" href="#example-2">Example</a></h3>
- <p>This section might look like:</p>
- <pre><code class="language-yaml">spam_checker:
- - module: my_module.ExampleSpamChecker
- config:
- # Enable or disable a specific option in ExampleSpamChecker.
- my_custom_option: true
- </code></pre>
- <p>More spam checkers can be added in tandem by appending more items to the list. An
- action is blocked when at least one of the configured spam checkers flags it.</p>
- <h2 id="examples"><a class="header" href="#examples">Examples</a></h2>
- <p>The <a href="https://github.com/matrix-org/mjolnir">Mjolnir</a> project is a full fledged
- example using the Synapse spam checking API, including a bot for dynamic
- configuration.</p>
- <div style="break-before: page; page-break-before: always;"></div><h1 id="presence-router-module"><a class="header" href="#presence-router-module">Presence Router Module</a></h1>
- <p>Synapse supports configuring a module that can specify additional users
- (local or remote) to should receive certain presence updates from local
- users.</p>
- <p>Note that routing presence via Application Service transactions is not
- currently supported.</p>
- <p>The presence routing module is implemented as a Python class, which will
- be imported by the running Synapse.</p>
- <h2 id="python-presence-router-class"><a class="header" href="#python-presence-router-class">Python Presence Router Class</a></h2>
- <p>The Python class is instantiated with two objects:</p>
- <ul>
- <li>A configuration object of some type (see below).</li>
- <li>An instance of <code>synapse.module_api.ModuleApi</code>.</li>
- </ul>
- <p>It then implements methods related to presence routing.</p>
- <p>Note that one method of <code>ModuleApi</code> that may be useful is:</p>
- <pre><code class="language-python">async def ModuleApi.send_local_online_presence_to(users: Iterable[str]) -> None
- </code></pre>
- <p>which can be given a list of local or remote MXIDs to broadcast known, online user
- presence to (for those users that the receiving user is considered interested in).
- It does not include state for users who are currently offline, and it can only be
- called on workers that support sending federation. Additionally, this method must
- only be called from the process that has been configured to write to the
- the <a href="workers.html#stream-writers">presence stream</a>.
- By default, this is the main process, but another worker can be configured to do
- so.</p>
- <h3 id="module-structure"><a class="header" href="#module-structure">Module structure</a></h3>
- <p>Below is a list of possible methods that can be implemented, and whether they are
- required.</p>
- <h4 id="parse_config"><a class="header" href="#parse_config"><code>parse_config</code></a></h4>
- <pre><code class="language-python">def parse_config(config_dict: dict) -> Any
- </code></pre>
- <p><strong>Required.</strong> A static method that is passed a dictionary of config options, and
- should return a validated config object. This method is described further in
- <a href="presence_router_module.html#configuration">Configuration</a>.</p>
- <h4 id="get_users_for_states"><a class="header" href="#get_users_for_states"><code>get_users_for_states</code></a></h4>
- <pre><code class="language-python">async def get_users_for_states(
- self,
- state_updates: Iterable[UserPresenceState],
- ) -> Dict[str, Set[UserPresenceState]]:
- </code></pre>
- <p><strong>Required.</strong> An asynchronous method that is passed an iterable of user presence
- state. This method can determine whether a given presence update should be sent to certain
- users. It does this by returning a dictionary with keys representing local or remote
- Matrix User IDs, and values being a python set
- of <code>synapse.handlers.presence.UserPresenceState</code> instances.</p>
- <p>Synapse will then attempt to send the specified presence updates to each user when
- possible.</p>
- <h4 id="get_interested_users"><a class="header" href="#get_interested_users"><code>get_interested_users</code></a></h4>
- <pre><code class="language-python">async def get_interested_users(self, user_id: str) -> Union[Set[str], str]
- </code></pre>
- <p><strong>Required.</strong> An asynchronous method that is passed a single Matrix User ID. This
- method is expected to return the users that the passed in user may be interested in the
- presence of. Returned users may be local or remote. The presence routed as a result of
- what this method returns is sent in addition to the updates already sent between users
- that share a room together. Presence updates are deduplicated.</p>
- <p>This method should return a python set of Matrix User IDs, or the object
- <code>synapse.events.presence_router.PresenceRouter.ALL_USERS</code> to indicate that the passed
- user should receive presence information for <em>all</em> known users.</p>
- <p>For clarity, if the user <code>@alice:example.org</code> is passed to this method, and the Set
- <code>{"@bob:example.com", "@charlie:somewhere.org"}</code> is returned, this signifies that Alice
- should receive presence updates sent by Bob and Charlie, regardless of whether these
- users share a room.</p>
- <h3 id="example-3"><a class="header" href="#example-3">Example</a></h3>
- <p>Below is an example implementation of a presence router class.</p>
- <pre><code class="language-python">from typing import Dict, Iterable, Set, Union
- from synapse.events.presence_router import PresenceRouter
- from synapse.handlers.presence import UserPresenceState
- from synapse.module_api import ModuleApi
- class PresenceRouterConfig:
- def __init__(self):
- # Config options with their defaults
- # A list of users to always send all user presence updates to
- self.always_send_to_users = [] # type: List[str]
-
- # A list of users to ignore presence updates for. Does not affect
- # shared-room presence relationships
- self.blacklisted_users = [] # type: List[str]
- class ExamplePresenceRouter:
- """An example implementation of synapse.presence_router.PresenceRouter.
- Supports routing all presence to a configured set of users, or a subset
- of presence from certain users to members of certain rooms.
- Args:
- config: A configuration object.
- module_api: An instance of Synapse's ModuleApi.
- """
- def __init__(self, config: PresenceRouterConfig, module_api: ModuleApi):
- self._config = config
- self._module_api = module_api
- @staticmethod
- def parse_config(config_dict: dict) -> PresenceRouterConfig:
- """Parse a configuration dictionary from the homeserver config, do
- some validation and return a typed PresenceRouterConfig.
- Args:
- config_dict: The configuration dictionary.
- Returns:
- A validated config object.
- """
- # Initialise a typed config object
- config = PresenceRouterConfig()
- always_send_to_users = config_dict.get("always_send_to_users")
- blacklisted_users = config_dict.get("blacklisted_users")
- # Do some validation of config options... otherwise raise a
- # synapse.config.ConfigError.
- config.always_send_to_users = always_send_to_users
- config.blacklisted_users = blacklisted_users
- return config
- async def get_users_for_states(
- self,
- state_updates: Iterable[UserPresenceState],
- ) -> Dict[str, Set[UserPresenceState]]:
- """Given an iterable of user presence updates, determine where each one
- needs to go. Returned results will not affect presence updates that are
- sent between users who share a room.
- Args:
- state_updates: An iterable of user presence state updates.
- Returns:
- A dictionary of user_id -> set of UserPresenceState that the user should
- receive.
- """
- destination_users = {} # type: Dict[str, Set[UserPresenceState]
- # Ignore any updates for blacklisted users
- desired_updates = set()
- for update in state_updates:
- if update.state_key not in self._config.blacklisted_users:
- desired_updates.add(update)
- # Send all presence updates to specific users
- for user_id in self._config.always_send_to_users:
- destination_users[user_id] = desired_updates
- return destination_users
- async def get_interested_users(
- self,
- user_id: str,
- ) -> Union[Set[str], PresenceRouter.ALL_USERS]:
- """
- Retrieve a list of users that `user_id` is interested in receiving the
- presence of. This will be in addition to those they share a room with.
- Optionally, the object PresenceRouter.ALL_USERS can be returned to indicate
- that this user should receive all incoming local and remote presence updates.
- Note that this method will only be called for local users.
- Args:
- user_id: A user requesting presence updates.
- Returns:
- A set of user IDs to return additional presence updates for, or
- PresenceRouter.ALL_USERS to return presence updates for all other users.
- """
- if user_id in self._config.always_send_to_users:
- return PresenceRouter.ALL_USERS
- return set()
- </code></pre>
- <h4 id="a-note-on-get_users_for_states-and-get_interested_users"><a class="header" href="#a-note-on-get_users_for_states-and-get_interested_users">A note on <code>get_users_for_states</code> and <code>get_interested_users</code></a></h4>
- <p>Both of these methods are effectively two different sides of the same coin. The logic
- regarding which users should receive updates for other users should be the same
- between them.</p>
- <p><code>get_users_for_states</code> is called when presence updates come in from either federation
- or local users, and is used to either direct local presence to remote users, or to
- wake up the sync streams of local users to collect remote presence.</p>
- <p>In contrast, <code>get_interested_users</code> is used to determine the users that presence should
- be fetched for when a local user is syncing. This presence is then retrieved, before
- being fed through <code>get_users_for_states</code> once again, with only the syncing user's
- routing information pulled from the resulting dictionary.</p>
- <p>Their routing logic should thus line up, else you may run into unintended behaviour.</p>
- <h2 id="configuration-3"><a class="header" href="#configuration-3">Configuration</a></h2>
- <p>Once you've crafted your module and installed it into the same Python environment as
- Synapse, amend your homeserver config file with the following.</p>
- <pre><code class="language-yaml">presence:
- enabled: true
- presence_router:
- module: my_module.ExamplePresenceRouter
- config:
- # Any configuration options for your module. The below is an example.
- # of setting options for ExamplePresenceRouter.
- always_send_to_users: ["@presence_gobbler:example.org"]
- blacklisted_users:
- - "@alice:example.com"
- - "@bob:example.com"
- ...
- </code></pre>
- <p>The contents of <code>config</code> will be passed as a Python dictionary to the static
- <code>parse_config</code> method of your class. The object returned by this method will
- then be passed to the <code>__init__</code> method of your module as <code>config</code>.</p>
- <div style="break-before: page; page-break-before: always;"></div><h1 id="scaling-synapse-via-workers"><a class="header" href="#scaling-synapse-via-workers">Scaling synapse via workers</a></h1>
- <p>For small instances it recommended to run Synapse in the default monolith mode.
- For larger instances where performance is a concern it can be helpful to split
- out functionality into multiple separate python processes. These processes are
- called 'workers', and are (eventually) intended to scale horizontally
- independently.</p>
- <p>Synapse's worker support is under active development and subject to change as
- we attempt to rapidly scale ever larger Synapse instances. However we are
- documenting it here to help admins needing a highly scalable Synapse instance
- similar to the one running <code>matrix.org</code>.</p>
- <p>All processes continue to share the same database instance, and as such,
- workers only work with PostgreSQL-based Synapse deployments. SQLite should only
- be used for demo purposes and any admin considering workers should already be
- running PostgreSQL.</p>
- <p>See also <a href="https://matrix.org/blog/2020/11/03/how-we-fixed-synapses-scalability">Matrix.org blog post</a>
- for a higher level overview.</p>
- <h2 id="main-processworker-communication"><a class="header" href="#main-processworker-communication">Main process/worker communication</a></h2>
- <p>The processes communicate with each other via a Synapse-specific protocol called
- 'replication' (analogous to MySQL- or Postgres-style database replication) which
- feeds streams of newly written data between processes so they can be kept in
- sync with the database state.</p>
- <p>When configured to do so, Synapse uses a
- <a href="https://redis.io/topics/pubsub">Redis pub/sub channel</a> to send the replication
- stream between all configured Synapse processes. Additionally, processes may
- make HTTP requests to each other, primarily for operations which need to wait
- for a reply ─ such as sending an event.</p>
- <p>Redis support was added in v1.13.0 with it becoming the recommended method in
- v1.18.0. It replaced the old direct TCP connections (which is deprecated as of
- v1.18.0) to the main process. With Redis, rather than all the workers connecting
- to the main process, all the workers and the main process connect to Redis,
- which relays replication commands between processes. This can give a significant
- cpu saving on the main process and will be a prerequisite for upcoming
- performance improvements.</p>
- <p>If Redis support is enabled Synapse will use it as a shared cache, as well as a
- pub/sub mechanism.</p>
- <p>See the <a href="workers.html#architectural-diagram">Architectural diagram</a> section at the end for
- a visualisation of what this looks like.</p>
- <h2 id="setting-up-workers"><a class="header" href="#setting-up-workers">Setting up workers</a></h2>
- <p>A Redis server is required to manage the communication between the processes.
- The Redis server should be installed following the normal procedure for your
- distribution (e.g. <code>apt install redis-server</code> on Debian). It is safe to use an
- existing Redis deployment if you have one.</p>
- <p>Once installed, check that Redis is running and accessible from the host running
- Synapse, for example by executing <code>echo PING | nc -q1 localhost 6379</code> and seeing
- a response of <code>+PONG</code>.</p>
- <p>The appropriate dependencies must also be installed for Synapse. If using a
- virtualenv, these can be installed with:</p>
- <pre><code class="language-sh">pip install "matrix-synapse[redis]"
- </code></pre>
- <p>Note that these dependencies are included when synapse is installed with <code>pip install matrix-synapse[all]</code>. They are also included in the debian packages from
- <code>matrix.org</code> and in the docker images at
- https://hub.docker.com/r/matrixdotorg/synapse/.</p>
- <p>To make effective use of the workers, you will need to configure an HTTP
- reverse-proxy such as nginx or haproxy, which will direct incoming requests to
- the correct worker, or to the main synapse instance. See
- <a href="reverse_proxy.html">the reverse proxy documentation</a> for information on setting up a reverse
- proxy.</p>
- <p>When using workers, each worker process has its own configuration file which
- contains settings specific to that worker, such as the HTTP listener that it
- provides (if any), logging configuration, etc.</p>
- <p>Normally, the worker processes are configured to read from a shared
- configuration file as well as the worker-specific configuration files. This
- makes it easier to keep common configuration settings synchronised across all
- the processes.</p>
- <p>The main process is somewhat special in this respect: it does not normally
- need its own configuration file and can take all of its configuration from the
- shared configuration file.</p>
- <h3 id="shared-configuration"><a class="header" href="#shared-configuration">Shared configuration</a></h3>
- <p>Normally, only a couple of changes are needed to make an existing configuration
- file suitable for use with workers. First, you need to enable an "HTTP replication
- listener" for the main process; and secondly, you need to enable redis-based
- replication. Optionally, a shared secret can be used to authenticate HTTP
- traffic between workers. For example:</p>
- <pre><code class="language-yaml"># extend the existing `listeners` section. This defines the ports that the
- # main process will listen on.
- listeners:
- # The HTTP replication port
- - port: 9093
- bind_address: '127.0.0.1'
- type: http
- resources:
- - names: [replication]
- # Add a random shared secret to authenticate traffic.
- worker_replication_secret: ""
- redis:
- enabled: true
- </code></pre>
- <p>See the sample config for the full documentation of each option.</p>
- <p>Under <strong>no circumstances</strong> should the replication listener be exposed to the
- public internet; it has no authentication and is unencrypted.</p>
- <h3 id="worker-configuration"><a class="header" href="#worker-configuration">Worker configuration</a></h3>
- <p>In the config file for each worker, you must specify the type of worker
- application (<code>worker_app</code>), and you should specify a unique name for the worker
- (<code>worker_name</code>). The currently available worker applications are listed below.
- You must also specify the HTTP replication endpoint that it should talk to on
- the main synapse process. <code>worker_replication_host</code> should specify the host of
- the main synapse and <code>worker_replication_http_port</code> should point to the HTTP
- replication port. If the worker will handle HTTP requests then the
- <code>worker_listeners</code> option should be set with a <code>http</code> listener, in the same way
- as the <code>listeners</code> option in the shared config.</p>
- <p>For example:</p>
- <pre><code class="language-yaml">worker_app: synapse.app.generic_worker
- worker_name: worker1
- # The replication listener on the main synapse process.
- worker_replication_host: 127.0.0.1
- worker_replication_http_port: 9093
- worker_listeners:
- - type: http
- port: 8083
- resources:
- - names:
- - client
- - federation
- worker_log_config: /home/matrix/synapse/config/worker1_log_config.yaml
- </code></pre>
- <p>...is a full configuration for a generic worker instance, which will expose a
- plain HTTP endpoint on port 8083 separately serving various endpoints, e.g.
- <code>/sync</code>, which are listed below.</p>
- <p>Obviously you should configure your reverse-proxy to route the relevant
- endpoints to the worker (<code>localhost:8083</code> in the above example).</p>
- <h3 id="running-synapse-with-workers"><a class="header" href="#running-synapse-with-workers">Running Synapse with workers</a></h3>
- <p>Finally, you need to start your worker processes. This can be done with either
- <code>synctl</code> or your distribution's preferred service manager such as <code>systemd</code>. We
- recommend the use of <code>systemd</code> where available: for information on setting up
- <code>systemd</code> to start synapse workers, see
- <a href="systemd-with-workers">Systemd with Workers</a>. To use <code>synctl</code>, see
- <a href="synctl_workers.html">Using synctl with Workers</a>.</p>
- <h2 id="available-worker-applications"><a class="header" href="#available-worker-applications">Available worker applications</a></h2>
- <h3 id="synapseappgeneric_worker"><a class="header" href="#synapseappgeneric_worker"><code>synapse.app.generic_worker</code></a></h3>
- <p>This worker can handle API requests matching the following regular
- expressions:</p>
- <pre><code># Sync requests
- ^/_matrix/client/(v2_alpha|r0)/sync$
- ^/_matrix/client/(api/v1|v2_alpha|r0)/events$
- ^/_matrix/client/(api/v1|r0)/initialSync$
- ^/_matrix/client/(api/v1|r0)/rooms/[^/]+/initialSync$
- # Federation requests
- ^/_matrix/federation/v1/event/
- ^/_matrix/federation/v1/state/
- ^/_matrix/federation/v1/state_ids/
- ^/_matrix/federation/v1/backfill/
- ^/_matrix/federation/v1/get_missing_events/
- ^/_matrix/federation/v1/publicRooms
- ^/_matrix/federation/v1/query/
- ^/_matrix/federation/v1/make_join/
- ^/_matrix/federation/v1/make_leave/
- ^/_matrix/federation/v1/send_join/
- ^/_matrix/federation/v2/send_join/
- ^/_matrix/federation/v1/send_leave/
- ^/_matrix/federation/v2/send_leave/
- ^/_matrix/federation/v1/invite/
- ^/_matrix/federation/v2/invite/
- ^/_matrix/federation/v1/query_auth/
- ^/_matrix/federation/v1/event_auth/
- ^/_matrix/federation/v1/exchange_third_party_invite/
- ^/_matrix/federation/v1/user/devices/
- ^/_matrix/federation/v1/get_groups_publicised$
- ^/_matrix/key/v2/query
- # Inbound federation transaction request
- ^/_matrix/federation/v1/send/
- # Client API requests
- ^/_matrix/client/(api/v1|r0|unstable)/publicRooms$
- ^/_matrix/client/(api/v1|r0|unstable)/rooms/.*/joined_members$
- ^/_matrix/client/(api/v1|r0|unstable)/rooms/.*/context/.*$
- ^/_matrix/client/(api/v1|r0|unstable)/rooms/.*/members$
- ^/_matrix/client/(api/v1|r0|unstable)/rooms/.*/state$
- ^/_matrix/client/(api/v1|r0|unstable)/account/3pid$
- ^/_matrix/client/(api/v1|r0|unstable)/devices$
- ^/_matrix/client/(api/v1|r0|unstable)/keys/query$
- ^/_matrix/client/(api/v1|r0|unstable)/keys/changes$
- ^/_matrix/client/versions$
- ^/_matrix/client/(api/v1|r0|unstable)/voip/turnServer$
- ^/_matrix/client/(api/v1|r0|unstable)/joined_groups$
- ^/_matrix/client/(api/v1|r0|unstable)/publicised_groups$
- ^/_matrix/client/(api/v1|r0|unstable)/publicised_groups/
- ^/_matrix/client/(api/v1|r0|unstable)/rooms/.*/event/
- ^/_matrix/client/(api/v1|r0|unstable)/joined_rooms$
- ^/_matrix/client/(api/v1|r0|unstable)/search$
- # Registration/login requests
- ^/_matrix/client/(api/v1|r0|unstable)/login$
- ^/_matrix/client/(r0|unstable)/register$
- # Event sending requests
- ^/_matrix/client/(api/v1|r0|unstable)/rooms/.*/redact
- ^/_matrix/client/(api/v1|r0|unstable)/rooms/.*/send
- ^/_matrix/client/(api/v1|r0|unstable)/rooms/.*/state/
- ^/_matrix/client/(api/v1|r0|unstable)/rooms/.*/(join|invite|leave|ban|unban|kick)$
- ^/_matrix/client/(api/v1|r0|unstable)/join/
- ^/_matrix/client/(api/v1|r0|unstable)/profile/
- </code></pre>
- <p>Additionally, the following REST endpoints can be handled for GET requests:</p>
- <pre><code>^/_matrix/federation/v1/groups/
- </code></pre>
- <p>Pagination requests can also be handled, but all requests for a given
- room must be routed to the same instance. Additionally, care must be taken to
- ensure that the purge history admin API is not used while pagination requests
- for the room are in flight:</p>
- <pre><code>^/_matrix/client/(api/v1|r0|unstable)/rooms/.*/messages$
- </code></pre>
- <p>Additionally, the following endpoints should be included if Synapse is configured
- to use SSO (you only need to include the ones for whichever SSO provider you're
- using):</p>
- <pre><code># for all SSO providers
- ^/_matrix/client/(api/v1|r0|unstable)/login/sso/redirect
- ^/_synapse/client/pick_idp$
- ^/_synapse/client/pick_username
- ^/_synapse/client/new_user_consent$
- ^/_synapse/client/sso_register$
- # OpenID Connect requests.
- ^/_synapse/client/oidc/callback$
- # SAML requests.
- ^/_synapse/client/saml2/authn_response$
- # CAS requests.
- ^/_matrix/client/(api/v1|r0|unstable)/login/cas/ticket$
- </code></pre>
- <p>Ensure that all SSO logins go to a single process.
- For multiple workers not handling the SSO endpoints properly, see
- <a href="https://github.com/matrix-org/synapse/issues/7530">#7530</a> and
- <a href="https://github.com/matrix-org/synapse/issues/9427">#9427</a>.</p>
- <p>Note that a HTTP listener with <code>client</code> and <code>federation</code> resources must be
- configured in the <code>worker_listeners</code> option in the worker config.</p>
- <h4 id="load-balancing"><a class="header" href="#load-balancing">Load balancing</a></h4>
- <p>It is possible to run multiple instances of this worker app, with incoming requests
- being load-balanced between them by the reverse-proxy. However, different endpoints
- have different characteristics and so admins
- may wish to run multiple groups of workers handling different endpoints so that
- load balancing can be done in different ways.</p>
- <p>For <code>/sync</code> and <code>/initialSync</code> requests it will be more efficient if all
- requests from a particular user are routed to a single instance. Extracting a
- user ID from the access token or <code>Authorization</code> header is currently left as an
- exercise for the reader. Admins may additionally wish to separate out <code>/sync</code>
- requests that have a <code>since</code> query parameter from those that don't (and
- <code>/initialSync</code>), as requests that don't are known as "initial sync" that happens
- when a user logs in on a new device and can be <em>very</em> resource intensive, so
- isolating these requests will stop them from interfering with other users ongoing
- syncs.</p>
- <p>Federation and client requests can be balanced via simple round robin.</p>
- <p>The inbound federation transaction request <code>^/_matrix/federation/v1/send/</code>
- should be balanced by source IP so that transactions from the same remote server
- go to the same process.</p>
- <p>Registration/login requests can be handled separately purely to help ensure that
- unexpected load doesn't affect new logins and sign ups.</p>
- <p>Finally, event sending requests can be balanced by the room ID in the URI (or
- the full URI, or even just round robin), the room ID is the path component after
- <code>/rooms/</code>. If there is a large bridge connected that is sending or may send lots
- of events, then a dedicated set of workers can be provisioned to limit the
- effects of bursts of events from that bridge on events sent by normal users.</p>
- <h4 id="stream-writers"><a class="header" href="#stream-writers">Stream writers</a></h4>
- <p>Additionally, there is <em>experimental</em> support for moving writing of specific
- streams (such as events) off of the main process to a particular worker. (This
- is only supported with Redis-based replication.)</p>
- <p>Currently supported streams are <code>events</code> and <code>typing</code>.</p>
- <p>To enable this, the worker must have a HTTP replication listener configured,
- have a <code>worker_name</code> and be listed in the <code>instance_map</code> config. For example to
- move event persistence off to a dedicated worker, the shared configuration would
- include:</p>
- <pre><code class="language-yaml">instance_map:
- event_persister1:
- host: localhost
- port: 8034
- stream_writers:
- events: event_persister1
- </code></pre>
- <p>The <code>events</code> stream also experimentally supports having multiple writers, where
- work is sharded between them by room ID. Note that you <em>must</em> restart all worker
- instances when adding or removing event persisters. An example <code>stream_writers</code>
- configuration with multiple writers:</p>
- <pre><code class="language-yaml">stream_writers:
- events:
- - event_persister1
- - event_persister2
- </code></pre>
- <h4 id="background-tasks"><a class="header" href="#background-tasks">Background tasks</a></h4>
- <p>There is also <em>experimental</em> support for moving background tasks to a separate
- worker. Background tasks are run periodically or started via replication. Exactly
- which tasks are configured to run depends on your Synapse configuration (e.g. if
- stats is enabled).</p>
- <p>To enable this, the worker must have a <code>worker_name</code> and can be configured to run
- background tasks. For example, to move background tasks to a dedicated worker,
- the shared configuration would include:</p>
- <pre><code class="language-yaml">run_background_tasks_on: background_worker
- </code></pre>
- <p>You might also wish to investigate the <code>update_user_directory</code> and
- <code>media_instance_running_background_jobs</code> settings.</p>
- <h3 id="synapseapppusher"><a class="header" href="#synapseapppusher"><code>synapse.app.pusher</code></a></h3>
- <p>Handles sending push notifications to sygnal and email. Doesn't handle any
- REST endpoints itself, but you should set <code>start_pushers: False</code> in the
- shared configuration file to stop the main synapse sending push notifications.</p>
- <p>To run multiple instances at once the <code>pusher_instances</code> option should list all
- pusher instances by their worker name, e.g.:</p>
- <pre><code class="language-yaml">pusher_instances:
- - pusher_worker1
- - pusher_worker2
- </code></pre>
- <h3 id="synapseappappservice"><a class="header" href="#synapseappappservice"><code>synapse.app.appservice</code></a></h3>
- <p>Handles sending output traffic to Application Services. Doesn't handle any
- REST endpoints itself, but you should set <code>notify_appservices: False</code> in the
- shared configuration file to stop the main synapse sending appservice notifications.</p>
- <p>Note this worker cannot be load-balanced: only one instance should be active.</p>
- <h3 id="synapseappfederation_sender"><a class="header" href="#synapseappfederation_sender"><code>synapse.app.federation_sender</code></a></h3>
- <p>Handles sending federation traffic to other servers. Doesn't handle any
- REST endpoints itself, but you should set <code>send_federation: False</code> in the
- shared configuration file to stop the main synapse sending this traffic.</p>
- <p>If running multiple federation senders then you must list each
- instance in the <code>federation_sender_instances</code> option by their <code>worker_name</code>.
- All instances must be stopped and started when adding or removing instances.
- For example:</p>
- <pre><code class="language-yaml">federation_sender_instances:
- - federation_sender1
- - federation_sender2
- </code></pre>
- <h3 id="synapseappmedia_repository"><a class="header" href="#synapseappmedia_repository"><code>synapse.app.media_repository</code></a></h3>
- <p>Handles the media repository. It can handle all endpoints starting with:</p>
- <pre><code>/_matrix/media/
- </code></pre>
- <p>... and the following regular expressions matching media-specific administration APIs:</p>
- <pre><code>^/_synapse/admin/v1/purge_media_cache$
- ^/_synapse/admin/v1/room/.*/media.*$
- ^/_synapse/admin/v1/user/.*/media.*$
- ^/_synapse/admin/v1/media/.*$
- ^/_synapse/admin/v1/quarantine_media/.*$
- </code></pre>
- <p>You should also set <code>enable_media_repo: False</code> in the shared configuration
- file to stop the main synapse running background jobs related to managing the
- media repository.</p>
- <p>In the <code>media_repository</code> worker configuration file, configure the http listener to
- expose the <code>media</code> resource. For example:</p>
- <pre><code class="language-yaml"> worker_listeners:
- - type: http
- port: 8085
- resources:
- - names:
- - media
- </code></pre>
- <p>Note that if running multiple media repositories they must be on the same server
- and you must configure a single instance to run the background tasks, e.g.:</p>
- <pre><code class="language-yaml"> media_instance_running_background_jobs: "media-repository-1"
- </code></pre>
- <p>Note that if a reverse proxy is used , then <code>/_matrix/media/</code> must be routed for both inbound client and federation requests (if they are handled separately).</p>
- <h3 id="synapseappuser_dir"><a class="header" href="#synapseappuser_dir"><code>synapse.app.user_dir</code></a></h3>
- <p>Handles searches in the user directory. It can handle REST endpoints matching
- the following regular expressions:</p>
- <pre><code>^/_matrix/client/(api/v1|r0|unstable)/user_directory/search$
- </code></pre>
- <p>When using this worker you must also set <code>update_user_directory: False</code> in the
- shared configuration file to stop the main synapse running background
- jobs related to updating the user directory.</p>
- <h3 id="synapseappfrontend_proxy"><a class="header" href="#synapseappfrontend_proxy"><code>synapse.app.frontend_proxy</code></a></h3>
- <p>Proxies some frequently-requested client endpoints to add caching and remove
- load from the main synapse. It can handle REST endpoints matching the following
- regular expressions:</p>
- <pre><code>^/_matrix/client/(api/v1|r0|unstable)/keys/upload
- </code></pre>
- <p>If <code>use_presence</code> is False in the homeserver config, it can also handle REST
- endpoints matching the following regular expressions:</p>
- <pre><code>^/_matrix/client/(api/v1|r0|unstable)/presence/[^/]+/status
- </code></pre>
- <p>This "stub" presence handler will pass through <code>GET</code> request but make the
- <code>PUT</code> effectively a no-op.</p>
- <p>It will proxy any requests it cannot handle to the main synapse instance. It
- must therefore be configured with the location of the main instance, via
- the <code>worker_main_http_uri</code> setting in the <code>frontend_proxy</code> worker configuration
- file. For example:</p>
- <pre><code>worker_main_http_uri: http://127.0.0.1:8008
- </code></pre>
- <h3 id="historical-apps"><a class="header" href="#historical-apps">Historical apps</a></h3>
- <p><em>Note:</em> Historically there used to be more apps, however they have been
- amalgamated into a single <code>synapse.app.generic_worker</code> app. The remaining apps
- are ones that do specific processing unrelated to requests, e.g. the <code>pusher</code>
- that handles sending out push notifications for new events. The intention is for
- all these to be folded into the <code>generic_worker</code> app and to use config to define
- which processes handle the various proccessing such as push notifications.</p>
- <h2 id="migration-from-old-config"><a class="header" href="#migration-from-old-config">Migration from old config</a></h2>
- <p>There are two main independent changes that have been made: introducing Redis
- support and merging apps into <code>synapse.app.generic_worker</code>. Both these changes
- are backwards compatible and so no changes to the config are required, however
- server admins are encouraged to plan to migrate to Redis as the old style direct
- TCP replication config is deprecated.</p>
- <p>To migrate to Redis add the <code>redis</code> config as above, and optionally remove the
- TCP <code>replication</code> listener from master and <code>worker_replication_port</code> from worker
- config.</p>
- <p>To migrate apps to use <code>synapse.app.generic_worker</code> simply update the
- <code>worker_app</code> option in the worker configs, and where worker are started (e.g.
- in systemd service files, but not required for synctl).</p>
- <h2 id="architectural-diagram"><a class="header" href="#architectural-diagram">Architectural diagram</a></h2>
- <p>The following shows an example setup using Redis and a reverse proxy:</p>
- <pre><code> Clients & Federation
- |
- v
- +-----------+
- | |
- | Reverse |
- | Proxy |
- | |
- +-----------+
- | | |
- | | | HTTP requests
- +-------------------+ | +-----------+
- | +---+ |
- | | |
- v v v
- +--------------+ +--------------+ +--------------+ +--------------+
- | Main | | Generic | | Generic | | Event |
- | Process | | Worker 1 | | Worker 2 | | Persister |
- +--------------+ +--------------+ +--------------+ +--------------+
- ^ ^ | ^ | | ^ | ^ ^
- | | | | | | | | | |
- | | | | | HTTP | | | | |
- | +----------+<--|---|---------+ | | | |
- | | +-------------|-->+----------+ |
- | | | |
- | | | |
- v v v v
- ====================================================================
- Redis pub/sub channel
- </code></pre>
- <div style="break-before: page; page-break-before: always;"></div><h3 id="using-synctl-with-workers"><a class="header" href="#using-synctl-with-workers">Using synctl with workers</a></h3>
- <p>If you want to use <code>synctl</code> to manage your synapse processes, you will need to
- create an an additional configuration file for the main synapse process. That
- configuration should look like this:</p>
- <pre><code class="language-yaml">worker_app: synapse.app.homeserver
- </code></pre>
- <p>Additionally, each worker app must be configured with the name of a "pid file",
- to which it will write its process ID when it starts. For example, for a
- synchrotron, you might write:</p>
- <pre><code class="language-yaml">worker_pid_file: /home/matrix/synapse/worker1.pid
- </code></pre>
- <p>Finally, to actually run your worker-based synapse, you must pass synctl the <code>-a</code>
- commandline option to tell it to operate on all the worker configurations found
- in the given directory, e.g.:</p>
- <pre><code>synctl -a $CONFIG/workers start
- </code></pre>
- <p>Currently one should always restart all workers when restarting or upgrading
- synapse, unless you explicitly know it's safe not to. For instance, restarting
- synapse without restarting all the synchrotrons may result in broken typing
- notifications.</p>
- <p>To manipulate a specific worker, you pass the -w option to synctl:</p>
- <pre><code>synctl -w $CONFIG/workers/worker1.yaml restart
- </code></pre>
- <div style="break-before: page; page-break-before: always;"></div><h1 id="setting-up-synapse-with-workers-and-systemd"><a class="header" href="#setting-up-synapse-with-workers-and-systemd">Setting up Synapse with Workers and Systemd</a></h1>
- <p>This is a setup for managing synapse with systemd, including support for
- managing workers. It provides a <code>matrix-synapse</code> service for the master, as
- well as a <code>matrix-synapse-worker@</code> service template for any workers you
- require. Additionally, to group the required services, it sets up a
- <code>matrix-synapse.target</code>.</p>
- <p>See the folder <a href="https://github.com/matrix-org/synapse/tree/develop/docs/systemd-with-workers/system/">system</a>
- for the systemd unit files.</p>
- <p>The folder <a href="https://github.com/matrix-org/synapse/tree/develop/docs/systemd-with-workers/workers/">workers</a>
- contains an example configuration for the <code>federation_reader</code> worker.</p>
- <h2 id="synapse-configuration-files"><a class="header" href="#synapse-configuration-files">Synapse configuration files</a></h2>
- <p>See <a href="systemd-with-workers/../workers.html">the worker documentation</a> for information on how to set up the
- configuration files and reverse-proxy correctly.
- Below is a sample <code>federation_reader</code> worker configuration file.</p>
- <pre><code class="language-yaml">worker_app: synapse.app.federation_reader
- worker_name: federation_reader1
- worker_replication_host: 127.0.0.1
- worker_replication_http_port: 9093
- worker_listeners:
- - type: http
- port: 8011
- resources:
- - names: [federation]
- worker_log_config: /etc/matrix-synapse/federation-reader-log.yaml
- </code></pre>
- <p>Systemd manages daemonization itself, so ensure that none of the configuration
- files set either <code>daemonize</code> or <code>worker_daemonize</code>.</p>
- <p>The config files of all workers are expected to be located in
- <code>/etc/matrix-synapse/workers</code>. If you want to use a different location, edit
- the provided <code>*.service</code> files accordingly.</p>
- <p>There is no need for a separate configuration file for the master process.</p>
- <h2 id="set-up"><a class="header" href="#set-up">Set up</a></h2>
- <ol>
- <li>Adjust synapse configuration files as above.</li>
- <li>Copy the <code>*.service</code> and <code>*.target</code> files in <a href="https://github.com/matrix-org/synapse/tree/develop/docs/systemd-with-workers/system/">system</a>
- to <code>/etc/systemd/system</code>.</li>
- <li>Run <code>systemctl daemon-reload</code> to tell systemd to load the new unit files.</li>
- <li>Run <code>systemctl enable matrix-synapse.service</code>. This will configure the
- synapse master process to be started as part of the <code>matrix-synapse.target</code>
- target.</li>
- <li>For each worker process to be enabled, run <code>systemctl enable matrix-synapse-worker@<worker_name>.service</code>. For each <code><worker_name></code>, there
- should be a corresponding configuration file.
- <code>/etc/matrix-synapse/workers/<worker_name>.yaml</code>.</li>
- <li>Start all the synapse processes with <code>systemctl start matrix-synapse.target</code>.</li>
- <li>Tell systemd to start synapse on boot with <code>systemctl enable matrix-synapse.target</code>.</li>
- </ol>
- <h2 id="usage"><a class="header" href="#usage">Usage</a></h2>
- <p>Once the services are correctly set up, you can use the following commands
- to manage your synapse installation:</p>
- <pre><code class="language-sh"># Restart Synapse master and all workers
- systemctl restart matrix-synapse.target
- # Stop Synapse and all workers
- systemctl stop matrix-synapse.target
- # Restart the master alone
- systemctl start matrix-synapse.service
- # Restart a specific worker (eg. federation_reader); the master is
- # unaffected by this.
- systemctl restart matrix-synapse-worker@federation_reader.service
- # Add a new worker (assuming all configs are set up already)
- systemctl enable matrix-synapse-worker@federation_writer.service
- systemctl restart matrix-synapse.target
- </code></pre>
- <h2 id="hardening"><a class="header" href="#hardening">Hardening</a></h2>
- <p><strong>Optional:</strong> If further hardening is desired, the file
- <code>override-hardened.conf</code> may be copied from
- <a href="https://github.com/matrix-org/synapse/tree/develop/contrib/systemd/">contrib/systemd/override-hardened.conf</a>
- in this repository to the location
- <code>/etc/systemd/system/matrix-synapse.service.d/override-hardened.conf</code> (the
- directory may have to be created). It enables certain sandboxing features in
- systemd to further secure the synapse service. You may read the comments to
- understand what the override file is doing. The same file will need to be copied to
- <code>/etc/systemd/system/matrix-synapse-worker@.service.d/override-hardened-worker.conf</code>
- (this directory may also have to be created) in order to apply the same
- hardening options to any worker processes.</p>
- <p>Once these files have been copied to their appropriate locations, simply reload
- systemd's manager config files and restart all Synapse services to apply the hardening options. They will automatically
- be applied at every restart as long as the override files are present at the
- specified locations.</p>
- <pre><code class="language-sh">systemctl daemon-reload
- # Restart services
- systemctl restart matrix-synapse.target
- </code></pre>
- <p>In order to see their effect, you may run <code>systemd-analyze security matrix-synapse.service</code> before and after applying the hardening options to see
- the changes being applied at a glance.</p>
- <div style="break-before: page; page-break-before: always;"></div><h1 id="administration"><a class="header" href="#administration">Administration</a></h1>
- <p>This section contains information on managing your Synapse homeserver. This includes:</p>
- <ul>
- <li>Managing users, rooms and media via the Admin API.</li>
- <li>Setting up metrics and monitoring to give you insight into your homeserver's health.</li>
- <li>Configuring structured logging.</li>
- </ul>
- <div style="break-before: page; page-break-before: always;"></div><h1 id="the-admin-api"><a class="header" href="#the-admin-api">The Admin API</a></h1>
- <h2 id="authenticate-as-a-server-admin"><a class="header" href="#authenticate-as-a-server-admin">Authenticate as a server admin</a></h2>
- <p>Many of the API calls in the admin api will require an <code>access_token</code> for a
- server admin. (Note that a server admin is distinct from a room admin.)</p>
- <p>A user can be marked as a server admin by updating the database directly, e.g.:</p>
- <pre><code class="language-sql">UPDATE users SET admin = 1 WHERE name = '@foo:bar.com';
- </code></pre>
- <p>A new server admin user can also be created using the <code>register_new_matrix_user</code>
- command. This is a script that is located in the <code>scripts/</code> directory, or possibly
- already on your <code>$PATH</code> depending on how Synapse was installed.</p>
- <p>Finding your user's <code>access_token</code> is client-dependent, but will usually be shown in the client's settings.</p>
- <h2 id="making-an-admin-api-request"><a class="header" href="#making-an-admin-api-request">Making an Admin API request</a></h2>
- <p>Once you have your <code>access_token</code>, you will need to authenticate each request to an Admin API endpoint by
- providing the token as either a query parameter or a request header. To add it as a request header in cURL:</p>
- <pre><code class="language-sh">curl --header "Authorization: Bearer <access_token>" <the_rest_of_your_API_request>
- </code></pre>
- <p>For more details on access tokens in Matrix, please refer to the complete
- <a href="https://matrix.org/docs/spec/client_server/r0.6.1#using-access-tokens">matrix spec documentation</a>.</p>
- <div style="break-before: page; page-break-before: always;"></div><h1 id="account-validity-api"><a class="header" href="#account-validity-api">Account validity API</a></h1>
- <p>This API allows a server administrator to manage the validity of an account. To
- use it, you must enable the account validity feature (under
- <code>account_validity</code>) in Synapse's configuration.</p>
- <h2 id="renew-account"><a class="header" href="#renew-account">Renew account</a></h2>
- <p>This API extends the validity of an account by as much time as configured in the
- <code>period</code> parameter from the <code>account_validity</code> configuration.</p>
- <p>The API is:</p>
- <pre><code>POST /_synapse/admin/v1/account_validity/validity
- </code></pre>
- <p>with the following body:</p>
- <pre><code class="language-json">{
- "user_id": "<user ID for the account to renew>",
- "expiration_ts": 0,
- "enable_renewal_emails": true
- }
- </code></pre>
- <p><code>expiration_ts</code> is an optional parameter and overrides the expiration date,
- which otherwise defaults to now + validity period.</p>
- <p><code>enable_renewal_emails</code> is also an optional parameter and enables/disables
- sending renewal emails to the user. Defaults to true.</p>
- <p>The API returns with the new expiration date for this account, as a timestamp in
- milliseconds since epoch:</p>
- <pre><code class="language-json">{
- "expiration_ts": 0
- }
- </code></pre>
- <div style="break-before: page; page-break-before: always;"></div><h1 id="delete-a-local-group"><a class="header" href="#delete-a-local-group">Delete a local group</a></h1>
- <p>This API lets a server admin delete a local group. Doing so will kick all
- users out of the group so that their clients will correctly handle the group
- being deleted.</p>
- <p>The API is:</p>
- <pre><code>POST /_synapse/admin/v1/delete_group/<group_id>
- </code></pre>
- <p>To use it, you will need to authenticate by providing an <code>access_token</code> for a
- server admin: see <a href="admin_api/../usage/administration/admin_api">Admin API</a>.</p>
- <div style="break-before: page; page-break-before: always;"></div><h1 id="show-reported-events"><a class="header" href="#show-reported-events">Show reported events</a></h1>
- <p>This API returns information about reported events.</p>
- <p>The api is:</p>
- <pre><code>GET /_synapse/admin/v1/event_reports?from=0&limit=10
- </code></pre>
- <p>To use it, you will need to authenticate by providing an <code>access_token</code> for a
- server admin: see <a href="admin_api/../usage/administration/admin_api">Admin API</a>.</p>
- <p>It returns a JSON body like the following:</p>
- <pre><code class="language-json">{
- "event_reports": [
- {
- "event_id": "$bNUFCwGzWca1meCGkjp-zwslF-GfVcXukvRLI1_FaVY",
- "id": 2,
- "reason": "foo",
- "score": -100,
- "received_ts": 1570897107409,
- "canonical_alias": "#alias1:matrix.org",
- "room_id": "!ERAgBpSOcCCuTJqQPk:matrix.org",
- "name": "Matrix HQ",
- "sender": "@foobar:matrix.org",
- "user_id": "@foo:matrix.org"
- },
- {
- "event_id": "$3IcdZsDaN_En-S1DF4EMCy3v4gNRKeOJs8W5qTOKj4I",
- "id": 3,
- "reason": "bar",
- "score": -100,
- "received_ts": 1598889612059,
- "canonical_alias": "#alias2:matrix.org",
- "room_id": "!eGvUQuTCkHGVwNMOjv:matrix.org",
- "name": "Your room name here",
- "sender": "@foobar:matrix.org",
- "user_id": "@bar:matrix.org"
- }
- ],
- "next_token": 2,
- "total": 4
- }
- </code></pre>
- <p>To paginate, check for <code>next_token</code> and if present, call the endpoint again with <code>from</code>
- set to the value of <code>next_token</code>. This will return a new page.</p>
- <p>If the endpoint does not return a <code>next_token</code> then there are no more reports to
- paginate through.</p>
- <p><strong>URL parameters:</strong></p>
- <ul>
- <li><code>limit</code>: integer - Is optional but is used for pagination, denoting the maximum number
- of items to return in this call. Defaults to <code>100</code>.</li>
- <li><code>from</code>: integer - Is optional but used for pagination, denoting the offset in the
- returned results. This should be treated as an opaque value and not explicitly set to
- anything other than the return value of <code>next_token</code> from a previous call. Defaults to <code>0</code>.</li>
- <li><code>dir</code>: string - Direction of event report order. Whether to fetch the most recent
- first (<code>b</code>) or the oldest first (<code>f</code>). Defaults to <code>b</code>.</li>
- <li><code>user_id</code>: string - Is optional and filters to only return users with user IDs that
- contain this value. This is the user who reported the event and wrote the reason.</li>
- <li><code>room_id</code>: string - Is optional and filters to only return rooms with room IDs that
- contain this value.</li>
- </ul>
- <p><strong>Response</strong></p>
- <p>The following fields are returned in the JSON response body:</p>
- <ul>
- <li><code>id</code>: integer - ID of event report.</li>
- <li><code>received_ts</code>: integer - The timestamp (in milliseconds since the unix epoch) when this
- report was sent.</li>
- <li><code>room_id</code>: string - The ID of the room in which the event being reported is located.</li>
- <li><code>name</code>: string - The name of the room.</li>
- <li><code>event_id</code>: string - The ID of the reported event.</li>
- <li><code>user_id</code>: string - This is the user who reported the event and wrote the reason.</li>
- <li><code>reason</code>: string - Comment made by the <code>user_id</code> in this report. May be blank or <code>null</code>.</li>
- <li><code>score</code>: integer - Content is reported based upon a negative score, where -100 is
- "most offensive" and 0 is "inoffensive". May be <code>null</code>.</li>
- <li><code>sender</code>: string - This is the ID of the user who sent the original message/event that
- was reported.</li>
- <li><code>canonical_alias</code>: string - The canonical alias of the room. <code>null</code> if the room does not
- have a canonical alias set.</li>
- <li><code>next_token</code>: integer - Indication for pagination. See above.</li>
- <li><code>total</code>: integer - Total number of event reports related to the query
- (<code>user_id</code> and <code>room_id</code>).</li>
- </ul>
- <h1 id="show-details-of-a-specific-event-report"><a class="header" href="#show-details-of-a-specific-event-report">Show details of a specific event report</a></h1>
- <p>This API returns information about a specific event report.</p>
- <p>The api is:</p>
- <pre><code>GET /_synapse/admin/v1/event_reports/<report_id>
- </code></pre>
- <p>To use it, you will need to authenticate by providing an <code>access_token</code> for a
- server admin: see <a href="admin_api/../usage/administration/admin_api">Admin API</a>.</p>
- <p>It returns a JSON body like the following:</p>
- <pre><code class="language-jsonc">{
- "event_id": "$bNUFCwGzWca1meCGkjp-zwslF-GfVcXukvRLI1_FaVY",
- "event_json": {
- "auth_events": [
- "$YK4arsKKcc0LRoe700pS8DSjOvUT4NDv0HfInlMFw2M",
- "$oggsNXxzPFRE3y53SUNd7nsj69-QzKv03a1RucHu-ws"
- ],
- "content": {
- "body": "matrix.org: This Week in Matrix",
- "format": "org.matrix.custom.html",
- "formatted_body": "<strong>matrix.org</strong>:<br><a href=\"https://matrix.org/blog/\"><strong>This Week in Matrix</strong></a>",
- "msgtype": "m.notice"
- },
- "depth": 546,
- "hashes": {
- "sha256": "xK1//xnmvHJIOvbgXlkI8eEqdvoMmihVDJ9J4SNlsAw"
- },
- "origin": "matrix.org",
- "origin_server_ts": 1592291711430,
- "prev_events": [
- "$YK4arsKKcc0LRoe700pS8DSjOvUT4NDv0HfInlMFw2M"
- ],
- "prev_state": [],
- "room_id": "!ERAgBpSOcCCuTJqQPk:matrix.org",
- "sender": "@foobar:matrix.org",
- "signatures": {
- "matrix.org": {
- "ed25519:a_JaEG": "cs+OUKW/iHx5pEidbWxh0UiNNHwe46Ai9LwNz+Ah16aWDNszVIe2gaAcVZfvNsBhakQTew51tlKmL2kspXk/Dg"
- }
- },
- "type": "m.room.message",
- "unsigned": {
- "age_ts": 1592291711430,
- }
- },
- "id": <report_id>,
- "reason": "foo",
- "score": -100,
- "received_ts": 1570897107409,
- "canonical_alias": "#alias1:matrix.org",
- "room_id": "!ERAgBpSOcCCuTJqQPk:matrix.org",
- "name": "Matrix HQ",
- "sender": "@foobar:matrix.org",
- "user_id": "@foo:matrix.org"
- }
- </code></pre>
- <p><strong>URL parameters:</strong></p>
- <ul>
- <li><code>report_id</code>: string - The ID of the event report.</li>
- </ul>
- <p><strong>Response</strong></p>
- <p>The following fields are returned in the JSON response body:</p>
- <ul>
- <li><code>id</code>: integer - ID of event report.</li>
- <li><code>received_ts</code>: integer - The timestamp (in milliseconds since the unix epoch) when this
- report was sent.</li>
- <li><code>room_id</code>: string - The ID of the room in which the event being reported is located.</li>
- <li><code>name</code>: string - The name of the room.</li>
- <li><code>event_id</code>: string - The ID of the reported event.</li>
- <li><code>user_id</code>: string - This is the user who reported the event and wrote the reason.</li>
- <li><code>reason</code>: string - Comment made by the <code>user_id</code> in this report. May be blank.</li>
- <li><code>score</code>: integer - Content is reported based upon a negative score, where -100 is
- "most offensive" and 0 is "inoffensive".</li>
- <li><code>sender</code>: string - This is the ID of the user who sent the original message/event that
- was reported.</li>
- <li><code>canonical_alias</code>: string - The canonical alias of the room. <code>null</code> if the room does not
- have a canonical alias set.</li>
- <li><code>event_json</code>: object - Details of the original event that was reported.</li>
- </ul>
- <div style="break-before: page; page-break-before: always;"></div><h1 id="contents-1"><a class="header" href="#contents-1">Contents</a></h1>
- <ul>
- <li><a href="admin_api/media_admin_api.html#querying-media">Querying media</a>
- <ul>
- <li><a href="admin_api/media_admin_api.html#list-all-media-in-a-room">List all media in a room</a></li>
- <li><a href="admin_api/media_admin_api.html#list-all-media-uploaded-by-a-user">List all media uploaded by a user</a></li>
- </ul>
- </li>
- <li><a href="admin_api/media_admin_api.html#quarantine-media">Quarantine media</a>
- <ul>
- <li><a href="admin_api/media_admin_api.html#quarantining-media-by-id">Quarantining media by ID</a></li>
- <li><a href="admin_api/media_admin_api.html#remove-media-from-quarantine-by-id">Remove media from quarantine by ID</a></li>
- <li><a href="admin_api/media_admin_api.html#quarantining-media-in-a-room">Quarantining media in a room</a></li>
- <li><a href="admin_api/media_admin_api.html#quarantining-all-media-of-a-user">Quarantining all media of a user</a></li>
- <li><a href="admin_api/media_admin_api.html#protecting-media-from-being-quarantined">Protecting media from being quarantined</a></li>
- <li><a href="admin_api/media_admin_api.html#unprotecting-media-from-being-quarantined">Unprotecting media from being quarantined</a></li>
- </ul>
- </li>
- <li><a href="admin_api/media_admin_api.html#delete-local-media">Delete local media</a>
- <ul>
- <li><a href="admin_api/media_admin_api.html#delete-a-specific-local-media">Delete a specific local media</a></li>
- <li><a href="admin_api/media_admin_api.html#delete-local-media-by-date-or-size">Delete local media by date or size</a></li>
- </ul>
- </li>
- <li><a href="admin_api/media_admin_api.html#purge-remote-media-api">Purge Remote Media API</a></li>
- </ul>
- <h1 id="querying-media"><a class="header" href="#querying-media">Querying media</a></h1>
- <p>These APIs allow extracting media information from the homeserver.</p>
- <h2 id="list-all-media-in-a-room"><a class="header" href="#list-all-media-in-a-room">List all media in a room</a></h2>
- <p>This API gets a list of known media in a room.
- However, it only shows media from unencrypted events or rooms.</p>
- <p>The API is:</p>
- <pre><code>GET /_synapse/admin/v1/room/<room_id>/media
- </code></pre>
- <p>To use it, you will need to authenticate by providing an <code>access_token</code> for a
- server admin: see <a href="admin_api/../usage/administration/admin_api">Admin API</a>.</p>
- <p>The API returns a JSON body like the following:</p>
- <pre><code class="language-json">{
- "local": [
- "mxc://localhost/xwvutsrqponmlkjihgfedcba",
- "mxc://localhost/abcdefghijklmnopqrstuvwx"
- ],
- "remote": [
- "mxc://matrix.org/xwvutsrqponmlkjihgfedcba",
- "mxc://matrix.org/abcdefghijklmnopqrstuvwx"
- ]
- }
- </code></pre>
- <h2 id="list-all-media-uploaded-by-a-user"><a class="header" href="#list-all-media-uploaded-by-a-user">List all media uploaded by a user</a></h2>
- <p>Listing all media that has been uploaded by a local user can be achieved through
- the use of the <a href="admin_api/user_admin_api.html#list-media-of-a-user">List media of a user</a>
- Admin API.</p>
- <h1 id="quarantine-media"><a class="header" href="#quarantine-media">Quarantine media</a></h1>
- <p>Quarantining media means that it is marked as inaccessible by users. It applies
- to any local media, and any locally-cached copies of remote media.</p>
- <p>The media file itself (and any thumbnails) is not deleted from the server.</p>
- <h2 id="quarantining-media-by-id"><a class="header" href="#quarantining-media-by-id">Quarantining media by ID</a></h2>
- <p>This API quarantines a single piece of local or remote media.</p>
- <p>Request:</p>
- <pre><code>POST /_synapse/admin/v1/media/quarantine/<server_name>/<media_id>
- {}
- </code></pre>
- <p>Where <code>server_name</code> is in the form of <code>example.org</code>, and <code>media_id</code> is in the
- form of <code>abcdefg12345...</code>.</p>
- <p>Response:</p>
- <pre><code class="language-json">{}
- </code></pre>
- <h2 id="remove-media-from-quarantine-by-id"><a class="header" href="#remove-media-from-quarantine-by-id">Remove media from quarantine by ID</a></h2>
- <p>This API removes a single piece of local or remote media from quarantine.</p>
- <p>Request:</p>
- <pre><code>POST /_synapse/admin/v1/media/unquarantine/<server_name>/<media_id>
- {}
- </code></pre>
- <p>Where <code>server_name</code> is in the form of <code>example.org</code>, and <code>media_id</code> is in the
- form of <code>abcdefg12345...</code>.</p>
- <p>Response:</p>
- <pre><code class="language-json">{}
- </code></pre>
- <h2 id="quarantining-media-in-a-room"><a class="header" href="#quarantining-media-in-a-room">Quarantining media in a room</a></h2>
- <p>This API quarantines all local and remote media in a room.</p>
- <p>Request:</p>
- <pre><code>POST /_synapse/admin/v1/room/<room_id>/media/quarantine
- {}
- </code></pre>
- <p>Where <code>room_id</code> is in the form of <code>!roomid12345:example.org</code>.</p>
- <p>Response:</p>
- <pre><code class="language-json">{
- "num_quarantined": 10
- }
- </code></pre>
- <p>The following fields are returned in the JSON response body:</p>
- <ul>
- <li><code>num_quarantined</code>: integer - The number of media items successfully quarantined</li>
- </ul>
- <p>Note that there is a legacy endpoint, <code>POST /_synapse/admin/v1/quarantine_media/<room_id></code>, that operates the same.
- However, it is deprecated and may be removed in a future release.</p>
- <h2 id="quarantining-all-media-of-a-user"><a class="header" href="#quarantining-all-media-of-a-user">Quarantining all media of a user</a></h2>
- <p>This API quarantines all <em>local</em> media that a <em>local</em> user has uploaded. That is to say, if
- you would like to quarantine media uploaded by a user on a remote homeserver, you should
- instead use one of the other APIs.</p>
- <p>Request:</p>
- <pre><code>POST /_synapse/admin/v1/user/<user_id>/media/quarantine
- {}
- </code></pre>
- <p>URL Parameters</p>
- <ul>
- <li><code>user_id</code>: string - User ID in the form of <code>@bob:example.org</code></li>
- </ul>
- <p>Response:</p>
- <pre><code class="language-json">{
- "num_quarantined": 10
- }
- </code></pre>
- <p>The following fields are returned in the JSON response body:</p>
- <ul>
- <li><code>num_quarantined</code>: integer - The number of media items successfully quarantined</li>
- </ul>
- <h2 id="protecting-media-from-being-quarantined"><a class="header" href="#protecting-media-from-being-quarantined">Protecting media from being quarantined</a></h2>
- <p>This API protects a single piece of local media from being quarantined using the
- above APIs. This is useful for sticker packs and other shared media which you do
- not want to get quarantined, especially when
- <a href="admin_api/media_admin_api.html#quarantining-media-in-a-room">quarantining media in a room</a>.</p>
- <p>Request:</p>
- <pre><code>POST /_synapse/admin/v1/media/protect/<media_id>
- {}
- </code></pre>
- <p>Where <code>media_id</code> is in the form of <code>abcdefg12345...</code>.</p>
- <p>Response:</p>
- <pre><code class="language-json">{}
- </code></pre>
- <h2 id="unprotecting-media-from-being-quarantined"><a class="header" href="#unprotecting-media-from-being-quarantined">Unprotecting media from being quarantined</a></h2>
- <p>This API reverts the protection of a media.</p>
- <p>Request:</p>
- <pre><code>POST /_synapse/admin/v1/media/unprotect/<media_id>
- {}
- </code></pre>
- <p>Where <code>media_id</code> is in the form of <code>abcdefg12345...</code>.</p>
- <p>Response:</p>
- <pre><code class="language-json">{}
- </code></pre>
- <h1 id="delete-local-media"><a class="header" href="#delete-local-media">Delete local media</a></h1>
- <p>This API deletes the <em>local</em> media from the disk of your own server.
- This includes any local thumbnails and copies of media downloaded from
- remote homeservers.
- This API will not affect media that has been uploaded to external
- media repositories (e.g https://github.com/turt2live/matrix-media-repo/).
- See also <a href="admin_api/media_admin_api.html#purge-remote-media-api">Purge Remote Media API</a>.</p>
- <h2 id="delete-a-specific-local-media"><a class="header" href="#delete-a-specific-local-media">Delete a specific local media</a></h2>
- <p>Delete a specific <code>media_id</code>.</p>
- <p>Request:</p>
- <pre><code>DELETE /_synapse/admin/v1/media/<server_name>/<media_id>
- {}
- </code></pre>
- <p>URL Parameters</p>
- <ul>
- <li><code>server_name</code>: string - The name of your local server (e.g <code>matrix.org</code>)</li>
- <li><code>media_id</code>: string - The ID of the media (e.g <code>abcdefghijklmnopqrstuvwx</code>)</li>
- </ul>
- <p>Response:</p>
- <pre><code class="language-json">{
- "deleted_media": [
- "abcdefghijklmnopqrstuvwx"
- ],
- "total": 1
- }
- </code></pre>
- <p>The following fields are returned in the JSON response body:</p>
- <ul>
- <li><code>deleted_media</code>: an array of strings - List of deleted <code>media_id</code></li>
- <li><code>total</code>: integer - Total number of deleted <code>media_id</code></li>
- </ul>
- <h2 id="delete-local-media-by-date-or-size"><a class="header" href="#delete-local-media-by-date-or-size">Delete local media by date or size</a></h2>
- <p>Request:</p>
- <pre><code>POST /_synapse/admin/v1/media/<server_name>/delete?before_ts=<before_ts>
- {}
- </code></pre>
- <p>URL Parameters</p>
- <ul>
- <li><code>server_name</code>: string - The name of your local server (e.g <code>matrix.org</code>).</li>
- <li><code>before_ts</code>: string representing a positive integer - Unix timestamp in ms.
- Files that were last used before this timestamp will be deleted. It is the timestamp of
- last access and not the timestamp creation.</li>
- <li><code>size_gt</code>: Optional - string representing a positive integer - Size of the media in bytes.
- Files that are larger will be deleted. Defaults to <code>0</code>.</li>
- <li><code>keep_profiles</code>: Optional - string representing a boolean - Switch to also delete files
- that are still used in image data (e.g user profile, room avatar).
- If <code>false</code> these files will be deleted. Defaults to <code>true</code>.</li>
- </ul>
- <p>Response:</p>
- <pre><code class="language-json">{
- "deleted_media": [
- "abcdefghijklmnopqrstuvwx",
- "abcdefghijklmnopqrstuvwz"
- ],
- "total": 2
- }
- </code></pre>
- <p>The following fields are returned in the JSON response body:</p>
- <ul>
- <li><code>deleted_media</code>: an array of strings - List of deleted <code>media_id</code></li>
- <li><code>total</code>: integer - Total number of deleted <code>media_id</code></li>
- </ul>
- <h1 id="purge-remote-media-api"><a class="header" href="#purge-remote-media-api">Purge Remote Media API</a></h1>
- <p>The purge remote media API allows server admins to purge old cached remote media.</p>
- <p>The API is:</p>
- <pre><code>POST /_synapse/admin/v1/purge_media_cache?before_ts=<unix_timestamp_in_ms>
- {}
- </code></pre>
- <p>URL Parameters</p>
- <ul>
- <li><code>unix_timestamp_in_ms</code>: string representing a positive integer - Unix timestamp in ms.
- All cached media that was last accessed before this timestamp will be removed.</li>
- </ul>
- <p>Response:</p>
- <pre><code class="language-json">{
- "deleted": 10
- }
- </code></pre>
- <p>The following fields are returned in the JSON response body:</p>
- <ul>
- <li><code>deleted</code>: integer - The number of media items successfully deleted</li>
- </ul>
- <p>To use it, you will need to authenticate by providing an <code>access_token</code> for a
- server admin: see <a href="admin_api/../usage/administration/admin_api">Admin API</a>.</p>
- <p>If the user re-requests purged remote media, synapse will re-request the media
- from the originating server.</p>
- <div style="break-before: page; page-break-before: always;"></div><h1 id="purge-history-api"><a class="header" href="#purge-history-api">Purge History API</a></h1>
- <p>The purge history API allows server admins to purge historic events from their
- database, reclaiming disk space.</p>
- <p>Depending on the amount of history being purged a call to the API may take
- several minutes or longer. During this period users will not be able to
- paginate further back in the room from the point being purged from.</p>
- <p>Note that Synapse requires at least one message in each room, so it will never
- delete the last message in a room.</p>
- <p>The API is:</p>
- <pre><code>POST /_synapse/admin/v1/purge_history/<room_id>[/<event_id>]
- </code></pre>
- <p>To use it, you will need to authenticate by providing an <code>access_token</code> for a
- server admin: <a href="admin_api/../usage/administration/admin_api">Admin API</a></p>
- <p>By default, events sent by local users are not deleted, as they may represent
- the only copies of this content in existence. (Events sent by remote users are
- deleted.)</p>
- <p>Room state data (such as joins, leaves, topic) is always preserved.</p>
- <p>To delete local message events as well, set <code>delete_local_events</code> in the body:</p>
- <pre><code>{
- "delete_local_events": true
- }
- </code></pre>
- <p>The caller must specify the point in the room to purge up to. This can be
- specified by including an event_id in the URI, or by setting a
- <code>purge_up_to_event_id</code> or <code>purge_up_to_ts</code> in the request body. If an event
- id is given, that event (and others at the same graph depth) will be retained.
- If <code>purge_up_to_ts</code> is given, it should be a timestamp since the unix epoch,
- in milliseconds.</p>
- <p>The API starts the purge running, and returns immediately with a JSON body with
- a purge id:</p>
- <pre><code class="language-json">{
- "purge_id": "<opaque id>"
- }
- </code></pre>
- <h2 id="purge-status-query"><a class="header" href="#purge-status-query">Purge status query</a></h2>
- <p>It is possible to poll for updates on recent purges with a second API;</p>
- <pre><code>GET /_synapse/admin/v1/purge_history_status/<purge_id>
- </code></pre>
- <p>Again, you will need to authenticate by providing an <code>access_token</code> for a
- server admin.</p>
- <p>This API returns a JSON body like the following:</p>
- <pre><code class="language-json">{
- "status": "active"
- }
- </code></pre>
- <p>The status will be one of <code>active</code>, <code>complete</code>, or <code>failed</code>.</p>
- <h2 id="reclaim-disk-space-postgres"><a class="header" href="#reclaim-disk-space-postgres">Reclaim disk space (Postgres)</a></h2>
- <p>To reclaim the disk space and return it to the operating system, you need to run
- <code>VACUUM FULL;</code> on the database.</p>
- <p><a href="https://www.postgresql.org/docs/current/sql-vacuum.html">https://www.postgresql.org/docs/current/sql-vacuum.html</a></p>
- <div style="break-before: page; page-break-before: always;"></div><h1 id="deprecated-purge-room-api"><a class="header" href="#deprecated-purge-room-api">Deprecated: Purge room API</a></h1>
- <p><strong>The old Purge room API is deprecated and will be removed in a future release.
- See the new <a href="admin_api/rooms.html#delete-room-api">Delete Room API</a> for more details.</strong></p>
- <p>This API will remove all trace of a room from your database.</p>
- <p>All local users must have left the room before it can be removed.</p>
- <p>The API is:</p>
- <pre><code>POST /_synapse/admin/v1/purge_room
- {
- "room_id": "!room:id"
- }
- </code></pre>
- <p>You must authenticate using the access token of an admin user.</p>
- <div style="break-before: page; page-break-before: always;"></div><h1 id="shared-secret-registration"><a class="header" href="#shared-secret-registration">Shared-Secret Registration</a></h1>
- <p>This API allows for the creation of users in an administrative and
- non-interactive way. This is generally used for bootstrapping a Synapse
- instance with administrator accounts.</p>
- <p>To authenticate yourself to the server, you will need both the shared secret
- (<code>registration_shared_secret</code> in the homeserver configuration), and a
- one-time nonce. If the registration shared secret is not configured, this API
- is not enabled.</p>
- <p>To fetch the nonce, you need to request one from the API:</p>
- <pre><code>> GET /_synapse/admin/v1/register
- < {"nonce": "thisisanonce"}
- </code></pre>
- <p>Once you have the nonce, you can make a <code>POST</code> to the same URL with a JSON
- body containing the nonce, username, password, whether they are an admin
- (optional, False by default), and a HMAC digest of the content. Also you can
- set the displayname (optional, <code>username</code> by default).</p>
- <p>As an example:</p>
- <pre><code>> POST /_synapse/admin/v1/register
- > {
- "nonce": "thisisanonce",
- "username": "pepper_roni",
- "displayname": "Pepper Roni",
- "password": "pizza",
- "admin": true,
- "mac": "mac_digest_here"
- }
- < {
- "access_token": "token_here",
- "user_id": "@pepper_roni:localhost",
- "home_server": "test",
- "device_id": "device_id_here"
- }
- </code></pre>
- <p>The MAC is the hex digest output of the HMAC-SHA1 algorithm, with the key being
- the shared secret and the content being the nonce, user, password, either the
- string "admin" or "notadmin", and optionally the user_type
- each separated by NULs. For an example of generation in Python:</p>
- <pre><code class="language-python">import hmac, hashlib
- def generate_mac(nonce, user, password, admin=False, user_type=None):
- mac = hmac.new(
- key=shared_secret,
- digestmod=hashlib.sha1,
- )
- mac.update(nonce.encode('utf8'))
- mac.update(b"\x00")
- mac.update(user.encode('utf8'))
- mac.update(b"\x00")
- mac.update(password.encode('utf8'))
- mac.update(b"\x00")
- mac.update(b"admin" if admin else b"notadmin")
- if user_type:
- mac.update(b"\x00")
- mac.update(user_type.encode('utf8'))
- return mac.hexdigest()
- </code></pre>
- <div style="break-before: page; page-break-before: always;"></div><h1 id="edit-room-membership-api"><a class="header" href="#edit-room-membership-api">Edit Room Membership API</a></h1>
- <p>This API allows an administrator to join an user account with a given <code>user_id</code>
- to a room with a given <code>room_id_or_alias</code>. You can only modify the membership of
- local users. The server administrator must be in the room and have permission to
- invite users.</p>
- <h2 id="parameters"><a class="header" href="#parameters">Parameters</a></h2>
- <p>The following parameters are available:</p>
- <ul>
- <li><code>user_id</code> - Fully qualified user: for example, <code>@user:server.com</code>.</li>
- <li><code>room_id_or_alias</code> - The room identifier or alias to join: for example,
- <code>!636q39766251:server.com</code>.</li>
- </ul>
- <h2 id="usage-1"><a class="header" href="#usage-1">Usage</a></h2>
- <pre><code>POST /_synapse/admin/v1/join/<room_id_or_alias>
- {
- "user_id": "@user:server.com"
- }
- </code></pre>
- <p>To use it, you will need to authenticate by providing an <code>access_token</code> for a
- server admin: see <a href="admin_api/../usage/administration/admin_api">Admin API</a>.</p>
- <p>Response:</p>
- <pre><code>{
- "room_id": "!636q39766251:server.com"
- }
- </code></pre>
- <div style="break-before: page; page-break-before: always;"></div><h1 id="contents-2"><a class="header" href="#contents-2">Contents</a></h1>
- <ul>
- <li><a href="admin_api/rooms.html#list-room-api">List Room API</a></li>
- <li><a href="admin_api/rooms.html#room-details-api">Room Details API</a></li>
- <li><a href="admin_api/rooms.html#room-members-api">Room Members API</a></li>
- <li><a href="admin_api/rooms.html#room-state-api">Room State API</a></li>
- <li><a href="admin_api/rooms.html#delete-room-api">Delete Room API</a>
- <ul>
- <li><a href="admin_api/rooms.html#undoing-room-shutdowns">Undoing room shutdowns</a></li>
- </ul>
- </li>
- <li><a href="admin_api/rooms.html#make-room-admin-api">Make Room Admin API</a></li>
- <li><a href="admin_api/rooms.html#forward-extremities-admin-api">Forward Extremities Admin API</a></li>
- <li><a href="admin_api/rooms.html#event-context-api">Event Context API</a></li>
- </ul>
- <h1 id="list-room-api"><a class="header" href="#list-room-api">List Room API</a></h1>
- <p>The List Room admin API allows server admins to get a list of rooms on their
- server. There are various parameters available that allow for filtering and
- sorting the returned list. This API supports pagination.</p>
- <p><strong>Parameters</strong></p>
- <p>The following query parameters are available:</p>
- <ul>
- <li><code>from</code> - Offset in the returned list. Defaults to <code>0</code>.</li>
- <li><code>limit</code> - Maximum amount of rooms to return. Defaults to <code>100</code>.</li>
- <li><code>order_by</code> - The method in which to sort the returned list of rooms. Valid values are:
- <ul>
- <li><code>alphabetical</code> - Same as <code>name</code>. This is deprecated.</li>
- <li><code>size</code> - Same as <code>joined_members</code>. This is deprecated.</li>
- <li><code>name</code> - Rooms are ordered alphabetically by room name. This is the default.</li>
- <li><code>canonical_alias</code> - Rooms are ordered alphabetically by main alias address of the room.</li>
- <li><code>joined_members</code> - Rooms are ordered by the number of members. Largest to smallest.</li>
- <li><code>joined_local_members</code> - Rooms are ordered by the number of local members. Largest to smallest.</li>
- <li><code>version</code> - Rooms are ordered by room version. Largest to smallest.</li>
- <li><code>creator</code> - Rooms are ordered alphabetically by creator of the room.</li>
- <li><code>encryption</code> - Rooms are ordered alphabetically by the end-to-end encryption algorithm.</li>
- <li><code>federatable</code> - Rooms are ordered by whether the room is federatable.</li>
- <li><code>public</code> - Rooms are ordered by visibility in room list.</li>
- <li><code>join_rules</code> - Rooms are ordered alphabetically by join rules of the room.</li>
- <li><code>guest_access</code> - Rooms are ordered alphabetically by guest access option of the room.</li>
- <li><code>history_visibility</code> - Rooms are ordered alphabetically by visibility of history of the room.</li>
- <li><code>state_events</code> - Rooms are ordered by number of state events. Largest to smallest.</li>
- </ul>
- </li>
- <li><code>dir</code> - Direction of room order. Either <code>f</code> for forwards or <code>b</code> for backwards. Setting
- this value to <code>b</code> will reverse the above sort order. Defaults to <code>f</code>.</li>
- <li><code>search_term</code> - Filter rooms by their room name. Search term can be contained in any
- part of the room name. Defaults to no filtering.</li>
- </ul>
- <p><strong>Response</strong></p>
- <p>The following fields are possible in the JSON response body:</p>
- <ul>
- <li><code>rooms</code> - An array of objects, each containing information about a room.
- <ul>
- <li>Room objects contain the following fields:
- <ul>
- <li><code>room_id</code> - The ID of the room.</li>
- <li><code>name</code> - The name of the room.</li>
- <li><code>canonical_alias</code> - The canonical (main) alias address of the room.</li>
- <li><code>joined_members</code> - How many users are currently in the room.</li>
- <li><code>joined_local_members</code> - How many local users are currently in the room.</li>
- <li><code>version</code> - The version of the room as a string.</li>
- <li><code>creator</code> - The <code>user_id</code> of the room creator.</li>
- <li><code>encryption</code> - Algorithm of end-to-end encryption of messages. Is <code>null</code> if encryption is not active.</li>
- <li><code>federatable</code> - Whether users on other servers can join this room.</li>
- <li><code>public</code> - Whether the room is visible in room directory.</li>
- <li><code>join_rules</code> - The type of rules used for users wishing to join this room. One of: ["public", "knock", "invite", "private"].</li>
- <li><code>guest_access</code> - Whether guests can join the room. One of: ["can_join", "forbidden"].</li>
- <li><code>history_visibility</code> - Who can see the room history. One of: ["invited", "joined", "shared", "world_readable"].</li>
- <li><code>state_events</code> - Total number of state_events of a room. Complexity of the room.</li>
- </ul>
- </li>
- </ul>
- </li>
- <li><code>offset</code> - The current pagination offset in rooms. This parameter should be
- used instead of <code>next_token</code> for room offset as <code>next_token</code> is
- not intended to be parsed.</li>
- <li><code>total_rooms</code> - The total number of rooms this query can return. Using this
- and <code>offset</code>, you have enough information to know the current
- progression through the list.</li>
- <li><code>next_batch</code> - If this field is present, we know that there are potentially
- more rooms on the server that did not all fit into this response.
- We can use <code>next_batch</code> to get the "next page" of results. To do
- so, simply repeat your request, setting the <code>from</code> parameter to
- the value of <code>next_batch</code>.</li>
- <li><code>prev_batch</code> - If this field is present, it is possible to paginate backwards.
- Use <code>prev_batch</code> for the <code>from</code> value in the next request to
- get the "previous page" of results.</li>
- </ul>
- <p>The API is:</p>
- <p>A standard request with no filtering:</p>
- <pre><code>GET /_synapse/admin/v1/rooms
- </code></pre>
- <p>A response body like the following is returned:</p>
- <pre><code class="language-jsonc">{
- "rooms": [
- {
- "room_id": "!OGEhHVWSdvArJzumhm:matrix.org",
- "name": "Matrix HQ",
- "canonical_alias": "#matrix:matrix.org",
- "joined_members": 8326,
- "joined_local_members": 2,
- "version": "1",
- "creator": "@foo:matrix.org",
- "encryption": null,
- "federatable": true,
- "public": true,
- "join_rules": "invite",
- "guest_access": null,
- "history_visibility": "shared",
- "state_events": 93534
- },
- ... (8 hidden items) ...
- {
- "room_id": "!xYvNcQPhnkrdUmYczI:matrix.org",
- "name": "This Week In Matrix (TWIM)",
- "canonical_alias": "#twim:matrix.org",
- "joined_members": 314,
- "joined_local_members": 20,
- "version": "4",
- "creator": "@foo:matrix.org",
- "encryption": "m.megolm.v1.aes-sha2",
- "federatable": true,
- "public": false,
- "join_rules": "invite",
- "guest_access": null,
- "history_visibility": "shared",
- "state_events": 8345
- }
- ],
- "offset": 0,
- "total_rooms": 10
- }
- </code></pre>
- <p>Filtering by room name:</p>
- <pre><code>GET /_synapse/admin/v1/rooms?search_term=TWIM
- </code></pre>
- <p>A response body like the following is returned:</p>
- <pre><code class="language-json">{
- "rooms": [
- {
- "room_id": "!xYvNcQPhnkrdUmYczI:matrix.org",
- "name": "This Week In Matrix (TWIM)",
- "canonical_alias": "#twim:matrix.org",
- "joined_members": 314,
- "joined_local_members": 20,
- "version": "4",
- "creator": "@foo:matrix.org",
- "encryption": "m.megolm.v1.aes-sha2",
- "federatable": true,
- "public": false,
- "join_rules": "invite",
- "guest_access": null,
- "history_visibility": "shared",
- "state_events": 8
- }
- ],
- "offset": 0,
- "total_rooms": 1
- }
- </code></pre>
- <p>Paginating through a list of rooms:</p>
- <pre><code>GET /_synapse/admin/v1/rooms?order_by=size
- </code></pre>
- <p>A response body like the following is returned:</p>
- <pre><code class="language-jsonc">{
- "rooms": [
- {
- "room_id": "!OGEhHVWSdvArJzumhm:matrix.org",
- "name": "Matrix HQ",
- "canonical_alias": "#matrix:matrix.org",
- "joined_members": 8326,
- "joined_local_members": 2,
- "version": "1",
- "creator": "@foo:matrix.org",
- "encryption": null,
- "federatable": true,
- "public": true,
- "join_rules": "invite",
- "guest_access": null,
- "history_visibility": "shared",
- "state_events": 93534
- },
- ... (98 hidden items) ...
- {
- "room_id": "!xYvNcQPhnkrdUmYczI:matrix.org",
- "name": "This Week In Matrix (TWIM)",
- "canonical_alias": "#twim:matrix.org",
- "joined_members": 314,
- "joined_local_members": 20,
- "version": "4",
- "creator": "@foo:matrix.org",
- "encryption": "m.megolm.v1.aes-sha2",
- "federatable": true,
- "public": false,
- "join_rules": "invite",
- "guest_access": null,
- "history_visibility": "shared",
- "state_events": 8345
- }
- ],
- "offset": 0,
- "total_rooms": 150
- "next_token": 100
- }
- </code></pre>
- <p>The presence of the <code>next_token</code> parameter tells us that there are more rooms
- than returned in this request, and we need to make another request to get them.
- To get the next batch of room results, we repeat our request, setting the <code>from</code>
- parameter to the value of <code>next_token</code>.</p>
- <pre><code>GET /_synapse/admin/v1/rooms?order_by=size&from=100
- </code></pre>
- <p>A response body like the following is returned:</p>
- <pre><code class="language-jsonc">{
- "rooms": [
- {
- "room_id": "!mscvqgqpHYjBGDxNym:matrix.org",
- "name": "Music Theory",
- "canonical_alias": "#musictheory:matrix.org",
- "joined_members": 127,
- "joined_local_members": 2,
- "version": "1",
- "creator": "@foo:matrix.org",
- "encryption": null,
- "federatable": true,
- "public": true,
- "join_rules": "invite",
- "guest_access": null,
- "history_visibility": "shared",
- "state_events": 93534
- },
- ... (48 hidden items) ...
- {
- "room_id": "!twcBhHVdZlQWuuxBhN:termina.org.uk",
- "name": "weechat-matrix",
- "canonical_alias": "#weechat-matrix:termina.org.uk",
- "joined_members": 137,
- "joined_local_members": 20,
- "version": "4",
- "creator": "@foo:termina.org.uk",
- "encryption": null,
- "federatable": true,
- "public": true,
- "join_rules": "invite",
- "guest_access": null,
- "history_visibility": "shared",
- "state_events": 8345
- }
- ],
- "offset": 100,
- "prev_batch": 0,
- "total_rooms": 150
- }
- </code></pre>
- <p>Once the <code>next_token</code> parameter is no longer present, we know we've reached the
- end of the list.</p>
- <h1 id="room-details-api"><a class="header" href="#room-details-api">Room Details API</a></h1>
- <p>The Room Details admin API allows server admins to get all details of a room.</p>
- <p>The following fields are possible in the JSON response body:</p>
- <ul>
- <li><code>room_id</code> - The ID of the room.</li>
- <li><code>name</code> - The name of the room.</li>
- <li><code>topic</code> - The topic of the room.</li>
- <li><code>avatar</code> - The <code>mxc</code> URI to the avatar of the room.</li>
- <li><code>canonical_alias</code> - The canonical (main) alias address of the room.</li>
- <li><code>joined_members</code> - How many users are currently in the room.</li>
- <li><code>joined_local_members</code> - How many local users are currently in the room.</li>
- <li><code>joined_local_devices</code> - How many local devices are currently in the room.</li>
- <li><code>version</code> - The version of the room as a string.</li>
- <li><code>creator</code> - The <code>user_id</code> of the room creator.</li>
- <li><code>encryption</code> - Algorithm of end-to-end encryption of messages. Is <code>null</code> if encryption is not active.</li>
- <li><code>federatable</code> - Whether users on other servers can join this room.</li>
- <li><code>public</code> - Whether the room is visible in room directory.</li>
- <li><code>join_rules</code> - The type of rules used for users wishing to join this room. One of: ["public", "knock", "invite", "private"].</li>
- <li><code>guest_access</code> - Whether guests can join the room. One of: ["can_join", "forbidden"].</li>
- <li><code>history_visibility</code> - Who can see the room history. One of: ["invited", "joined", "shared", "world_readable"].</li>
- <li><code>state_events</code> - Total number of state_events of a room. Complexity of the room.</li>
- </ul>
- <p>The API is:</p>
- <pre><code>GET /_synapse/admin/v1/rooms/<room_id>
- </code></pre>
- <p>A response body like the following is returned:</p>
- <pre><code class="language-json">{
- "room_id": "!mscvqgqpHYjBGDxNym:matrix.org",
- "name": "Music Theory",
- "avatar": "mxc://matrix.org/AQDaVFlbkQoErdOgqWRgiGSV",
- "topic": "Theory, Composition, Notation, Analysis",
- "canonical_alias": "#musictheory:matrix.org",
- "joined_members": 127,
- "joined_local_members": 2,
- "joined_local_devices": 2,
- "version": "1",
- "creator": "@foo:matrix.org",
- "encryption": null,
- "federatable": true,
- "public": true,
- "join_rules": "invite",
- "guest_access": null,
- "history_visibility": "shared",
- "state_events": 93534
- }
- </code></pre>
- <h1 id="room-members-api"><a class="header" href="#room-members-api">Room Members API</a></h1>
- <p>The Room Members admin API allows server admins to get a list of all members of a room.</p>
- <p>The response includes the following fields:</p>
- <ul>
- <li><code>members</code> - A list of all the members that are present in the room, represented by their ids.</li>
- <li><code>total</code> - Total number of members in the room.</li>
- </ul>
- <p>The API is:</p>
- <pre><code>GET /_synapse/admin/v1/rooms/<room_id>/members
- </code></pre>
- <p>A response body like the following is returned:</p>
- <pre><code class="language-json">{
- "members": [
- "@foo:matrix.org",
- "@bar:matrix.org",
- "@foobar:matrix.org"
- ],
- "total": 3
- }
- </code></pre>
- <h1 id="room-state-api"><a class="header" href="#room-state-api">Room State API</a></h1>
- <p>The Room State admin API allows server admins to get a list of all state events in a room.</p>
- <p>The response includes the following fields:</p>
- <ul>
- <li><code>state</code> - The current state of the room at the time of request.</li>
- </ul>
- <p>The API is:</p>
- <pre><code>GET /_synapse/admin/v1/rooms/<room_id>/state
- </code></pre>
- <p>A response body like the following is returned:</p>
- <pre><code class="language-json">{
- "state": [
- {"type": "m.room.create", "state_key": "", "etc": true},
- {"type": "m.room.power_levels", "state_key": "", "etc": true},
- {"type": "m.room.name", "state_key": "", "etc": true}
- ]
- }
- </code></pre>
- <h1 id="delete-room-api"><a class="header" href="#delete-room-api">Delete Room API</a></h1>
- <p>The Delete Room admin API allows server admins to remove rooms from server
- and block these rooms.</p>
- <p>Shuts down a room. Moves all local users and room aliases automatically to a
- new room if <code>new_room_user_id</code> is set. Otherwise local users only
- leave the room without any information.</p>
- <p>The new room will be created with the user specified by the <code>new_room_user_id</code> parameter
- as room administrator and will contain a message explaining what happened. Users invited
- to the new room will have power level <code>-10</code> by default, and thus be unable to speak.</p>
- <p>If <code>block</code> is <code>True</code> it prevents new joins to the old room.</p>
- <p>This API will remove all trace of the old room from your database after removing
- all local users. If <code>purge</code> is <code>true</code> (the default), all traces of the old room will
- be removed from your database after removing all local users. If you do not want
- this to happen, set <code>purge</code> to <code>false</code>.
- Depending on the amount of history being purged a call to the API may take
- several minutes or longer.</p>
- <p>The local server will only have the power to move local user and room aliases to
- the new room. Users on other servers will be unaffected.</p>
- <p>The API is:</p>
- <pre><code>DELETE /_synapse/admin/v1/rooms/<room_id>
- </code></pre>
- <p>with a body of:</p>
- <pre><code class="language-json">{
- "new_room_user_id": "@someuser:example.com",
- "room_name": "Content Violation Notification",
- "message": "Bad Room has been shutdown due to content violations on this server. Please review our Terms of Service.",
- "block": true,
- "purge": true
- }
- </code></pre>
- <p>To use it, you will need to authenticate by providing an <code>access_token</code> for a
- server admin: see <a href="admin_api/../usage/administration/admin_api">Admin API</a>.</p>
- <p>A response body like the following is returned:</p>
- <pre><code class="language-json">{
- "kicked_users": [
- "@foobar:example.com"
- ],
- "failed_to_kick_users": [],
- "local_aliases": [
- "#badroom:example.com",
- "#evilsaloon:example.com"
- ],
- "new_room_id": "!newroomid:example.com"
- }
- </code></pre>
- <p><strong>Parameters</strong></p>
- <p>The following parameters should be set in the URL:</p>
- <ul>
- <li><code>room_id</code> - The ID of the room.</li>
- </ul>
- <p>The following JSON body parameters are available:</p>
- <ul>
- <li><code>new_room_user_id</code> - Optional. If set, a new room will be created with this user ID
- as the creator and admin, and all users in the old room will be moved into that
- room. If not set, no new room will be created and the users will just be removed
- from the old room. The user ID must be on the local server, but does not necessarily
- have to belong to a registered user.</li>
- <li><code>room_name</code> - Optional. A string representing the name of the room that new users will be
- invited to. Defaults to <code>Content Violation Notification</code></li>
- <li><code>message</code> - Optional. A string containing the first message that will be sent as
- <code>new_room_user_id</code> in the new room. Ideally this will clearly convey why the
- original room was shut down. Defaults to <code>Sharing illegal content on this server is not permitted and rooms in violation will be blocked.</code></li>
- <li><code>block</code> - Optional. If set to <code>true</code>, this room will be added to a blocking list, preventing
- future attempts to join the room. Defaults to <code>false</code>.</li>
- <li><code>purge</code> - Optional. If set to <code>true</code>, it will remove all traces of the room from your database.
- Defaults to <code>true</code>.</li>
- <li><code>force_purge</code> - Optional, and ignored unless <code>purge</code> is <code>true</code>. If set to <code>true</code>, it
- will force a purge to go ahead even if there are local users still in the room. Do not
- use this unless a regular <code>purge</code> operation fails, as it could leave those users'
- clients in a confused state.</li>
- </ul>
- <p>The JSON body must not be empty. The body must be at least <code>{}</code>.</p>
- <p><strong>Response</strong></p>
- <p>The following fields are returned in the JSON response body:</p>
- <ul>
- <li><code>kicked_users</code> - An array of users (<code>user_id</code>) that were kicked.</li>
- <li><code>failed_to_kick_users</code> - An array of users (<code>user_id</code>) that that were not kicked.</li>
- <li><code>local_aliases</code> - An array of strings representing the local aliases that were migrated from
- the old room to the new.</li>
- <li><code>new_room_id</code> - A string representing the room ID of the new room.</li>
- </ul>
- <h2 id="undoing-room-shutdowns"><a class="header" href="#undoing-room-shutdowns">Undoing room shutdowns</a></h2>
- <p><em>Note</em>: This guide may be outdated by the time you read it. By nature of room shutdowns being performed at the database level,
- the structure can and does change without notice.</p>
- <p>First, it's important to understand that a room shutdown is very destructive. Undoing a shutdown is not as simple as pretending it
- never happened - work has to be done to move forward instead of resetting the past. In fact, in some cases it might not be possible
- to recover at all:</p>
- <ul>
- <li>If the room was invite-only, your users will need to be re-invited.</li>
- <li>If the room no longer has any members at all, it'll be impossible to rejoin.</li>
- <li>The first user to rejoin will have to do so via an alias on a different server.</li>
- </ul>
- <p>With all that being said, if you still want to try and recover the room:</p>
- <ol>
- <li>For safety reasons, shut down Synapse.</li>
- <li>In the database, run <code>DELETE FROM blocked_rooms WHERE room_id = '!example:example.org';</code>
- <ul>
- <li>For caution: it's recommended to run this in a transaction: <code>BEGIN; DELETE ...;</code>, verify you got 1 result, then <code>COMMIT;</code>.</li>
- <li>The room ID is the same one supplied to the shutdown room API, not the Content Violation room.</li>
- </ul>
- </li>
- <li>Restart Synapse.</li>
- </ol>
- <p>You will have to manually handle, if you so choose, the following:</p>
- <ul>
- <li>Aliases that would have been redirected to the Content Violation room.</li>
- <li>Users that would have been booted from the room (and will have been force-joined to the Content Violation room).</li>
- <li>Removal of the Content Violation room if desired.</li>
- </ul>
- <h2 id="deprecated-endpoint"><a class="header" href="#deprecated-endpoint">Deprecated endpoint</a></h2>
- <p>The previous deprecated API will be removed in a future release, it was:</p>
- <pre><code>POST /_synapse/admin/v1/rooms/<room_id>/delete
- </code></pre>
- <p>It behaves the same way than the current endpoint except the path and the method.</p>
- <h1 id="make-room-admin-api"><a class="header" href="#make-room-admin-api">Make Room Admin API</a></h1>
- <p>Grants another user the highest power available to a local user who is in the room.
- If the user is not in the room, and it is not publicly joinable, then invite the user.</p>
- <p>By default the server admin (the caller) is granted power, but another user can
- optionally be specified, e.g.:</p>
- <pre><code>POST /_synapse/admin/v1/rooms/<room_id_or_alias>/make_room_admin
- {
- "user_id": "@foo:example.com"
- }
- </code></pre>
- <h1 id="forward-extremities-admin-api"><a class="header" href="#forward-extremities-admin-api">Forward Extremities Admin API</a></h1>
- <p>Enables querying and deleting forward extremities from rooms. When a lot of forward
- extremities accumulate in a room, performance can become degraded. For details, see
- <a href="https://github.com/matrix-org/synapse/issues/1760">#1760</a>.</p>
- <h2 id="check-for-forward-extremities"><a class="header" href="#check-for-forward-extremities">Check for forward extremities</a></h2>
- <p>To check the status of forward extremities for a room:</p>
- <pre><code>GET /_synapse/admin/v1/rooms/<room_id_or_alias>/forward_extremities
- </code></pre>
- <p>A response as follows will be returned:</p>
- <pre><code class="language-json">{
- "count": 1,
- "results": [
- {
- "event_id": "$M5SP266vsnxctfwFgFLNceaCo3ujhRtg_NiiHabcdefgh",
- "state_group": 439,
- "depth": 123,
- "received_ts": 1611263016761
- }
- ]
- }
- </code></pre>
- <h2 id="deleting-forward-extremities"><a class="header" href="#deleting-forward-extremities">Deleting forward extremities</a></h2>
- <p><strong>WARNING</strong>: Please ensure you know what you're doing and have read
- the related issue <a href="https://github.com/matrix-org/synapse/issues/1760">#1760</a>.
- Under no situations should this API be executed as an automated maintenance task!</p>
- <p>If a room has lots of forward extremities, the extra can be
- deleted as follows:</p>
- <pre><code>DELETE /_synapse/admin/v1/rooms/<room_id_or_alias>/forward_extremities
- </code></pre>
- <p>A response as follows will be returned, indicating the amount of forward extremities
- that were deleted.</p>
- <pre><code class="language-json">{
- "deleted": 1
- }
- </code></pre>
- <h1 id="event-context-api"><a class="header" href="#event-context-api">Event Context API</a></h1>
- <p>This API lets a client find the context of an event. This is designed primarily to investigate abuse reports.</p>
- <pre><code>GET /_synapse/admin/v1/rooms/<room_id>/context/<event_id>
- </code></pre>
- <p>This API mimmicks <a href="https://matrix.org/docs/spec/client_server/r0.6.1#get-matrix-client-r0-rooms-roomid-context-eventid">GET /_matrix/client/r0/rooms/{roomId}/context/{eventId}</a>. Please refer to the link for all details on parameters and reseponse.</p>
- <p>Example response:</p>
- <pre><code class="language-json">{
- "end": "t29-57_2_0_2",
- "events_after": [
- {
- "content": {
- "body": "This is an example text message",
- "msgtype": "m.text",
- "format": "org.matrix.custom.html",
- "formatted_body": "<b>This is an example text message</b>"
- },
- "type": "m.room.message",
- "event_id": "$143273582443PhrSn:example.org",
- "room_id": "!636q39766251:example.com",
- "sender": "@example:example.org",
- "origin_server_ts": 1432735824653,
- "unsigned": {
- "age": 1234
- }
- }
- ],
- "event": {
- "content": {
- "body": "filename.jpg",
- "info": {
- "h": 398,
- "w": 394,
- "mimetype": "image/jpeg",
- "size": 31037
- },
- "url": "mxc://example.org/JWEIFJgwEIhweiWJE",
- "msgtype": "m.image"
- },
- "type": "m.room.message",
- "event_id": "$f3h4d129462ha:example.com",
- "room_id": "!636q39766251:example.com",
- "sender": "@example:example.org",
- "origin_server_ts": 1432735824653,
- "unsigned": {
- "age": 1234
- }
- },
- "events_before": [
- {
- "content": {
- "body": "something-important.doc",
- "filename": "something-important.doc",
- "info": {
- "mimetype": "application/msword",
- "size": 46144
- },
- "msgtype": "m.file",
- "url": "mxc://example.org/FHyPlCeYUSFFxlgbQYZmoEoe"
- },
- "type": "m.room.message",
- "event_id": "$143273582443PhrSn:example.org",
- "room_id": "!636q39766251:example.com",
- "sender": "@example:example.org",
- "origin_server_ts": 1432735824653,
- "unsigned": {
- "age": 1234
- }
- }
- ],
- "start": "t27-54_2_0_2",
- "state": [
- {
- "content": {
- "creator": "@example:example.org",
- "room_version": "1",
- "m.federate": true,
- "predecessor": {
- "event_id": "$something:example.org",
- "room_id": "!oldroom:example.org"
- }
- },
- "type": "m.room.create",
- "event_id": "$143273582443PhrSn:example.org",
- "room_id": "!636q39766251:example.com",
- "sender": "@example:example.org",
- "origin_server_ts": 1432735824653,
- "unsigned": {
- "age": 1234
- },
- "state_key": ""
- },
- {
- "content": {
- "membership": "join",
- "avatar_url": "mxc://example.org/SEsfnsuifSDFSSEF",
- "displayname": "Alice Margatroid"
- },
- "type": "m.room.member",
- "event_id": "$143273582443PhrSn:example.org",
- "room_id": "!636q39766251:example.com",
- "sender": "@example:example.org",
- "origin_server_ts": 1432735824653,
- "unsigned": {
- "age": 1234
- },
- "state_key": "@alice:example.org"
- }
- ]
- }
- </code></pre>
- <div style="break-before: page; page-break-before: always;"></div><h1 id="server-notices-1"><a class="header" href="#server-notices-1">Server Notices</a></h1>
- <p>The API to send notices is as follows:</p>
- <pre><code>POST /_synapse/admin/v1/send_server_notice
- </code></pre>
- <p>or:</p>
- <pre><code>PUT /_synapse/admin/v1/send_server_notice/{txnId}
- </code></pre>
- <p>You will need to authenticate with an access token for an admin user.</p>
- <p>When using the <code>PUT</code> form, retransmissions with the same transaction ID will be
- ignored in the same way as with <code>PUT /_matrix/client/r0/rooms/{roomId}/send/{eventType}/{txnId}</code>.</p>
- <p>The request body should look something like the following:</p>
- <pre><code class="language-json">{
- "user_id": "@target_user:server_name",
- "content": {
- "msgtype": "m.text",
- "body": "This is my message"
- }
- }
- </code></pre>
- <p>You can optionally include the following additional parameters:</p>
- <ul>
- <li><code>type</code>: the type of event. Defaults to <code>m.room.message</code>.</li>
- <li><code>state_key</code>: Setting this will result in a state event being sent.</li>
- </ul>
- <p>Once the notice has been sent, the API will return the following response:</p>
- <pre><code class="language-json">{
- "event_id": "<event_id>"
- }
- </code></pre>
- <p>Note that server notices must be enabled in <code>homeserver.yaml</code> before this API
- can be used. See <a href="admin_api/../server_notices.html">the server notices documentation</a> for more information.</p>
- <div style="break-before: page; page-break-before: always;"></div><h1 id="deprecated-shutdown-room-api"><a class="header" href="#deprecated-shutdown-room-api">Deprecated: Shutdown room API</a></h1>
- <p><strong>The old Shutdown room API is deprecated and will be removed in a future release.
- See the new <a href="admin_api/rooms.html#delete-room-api">Delete Room API</a> for more details.</strong></p>
- <p>Shuts down a room, preventing new joins and moves local users and room aliases automatically
- to a new room. The new room will be created with the user specified by the
- <code>new_room_user_id</code> parameter as room administrator and will contain a message
- explaining what happened. Users invited to the new room will have power level
- -10 by default, and thus be unable to speak. The old room's power levels will be changed to
- disallow any further invites or joins.</p>
- <p>The local server will only have the power to move local user and room aliases to
- the new room. Users on other servers will be unaffected.</p>
- <h2 id="api-1"><a class="header" href="#api-1">API</a></h2>
- <p>You will need to authenticate with an access token for an admin user.</p>
- <h3 id="url"><a class="header" href="#url">URL</a></h3>
- <p><code>POST /_synapse/admin/v1/shutdown_room/{room_id}</code></p>
- <h3 id="url-parameters"><a class="header" href="#url-parameters">URL Parameters</a></h3>
- <ul>
- <li><code>room_id</code> - The ID of the room (e.g <code>!someroom:example.com</code>)</li>
- </ul>
- <h3 id="json-body-parameters"><a class="header" href="#json-body-parameters">JSON Body Parameters</a></h3>
- <ul>
- <li><code>new_room_user_id</code> - Required. A string representing the user ID of the user that will admin
- the new room that all users in the old room will be moved to.</li>
- <li><code>room_name</code> - Optional. A string representing the name of the room that new users will be
- invited to.</li>
- <li><code>message</code> - Optional. A string containing the first message that will be sent as
- <code>new_room_user_id</code> in the new room. Ideally this will clearly convey why the
- original room was shut down.</li>
- </ul>
- <p>If not specified, the default value of <code>room_name</code> is "Content Violation
- Notification". The default value of <code>message</code> is "Sharing illegal content on
- othis server is not permitted and rooms in violation will be blocked."</p>
- <h3 id="response-parameters"><a class="header" href="#response-parameters">Response Parameters</a></h3>
- <ul>
- <li><code>kicked_users</code> - An integer number representing the number of users that
- were kicked.</li>
- <li><code>failed_to_kick_users</code> - An integer number representing the number of users
- that were not kicked.</li>
- <li><code>local_aliases</code> - An array of strings representing the local aliases that were migrated from
- the old room to the new.</li>
- <li><code>new_room_id</code> - A string representing the room ID of the new room.</li>
- </ul>
- <h2 id="example-4"><a class="header" href="#example-4">Example</a></h2>
- <p>Request:</p>
- <pre><code>POST /_synapse/admin/v1/shutdown_room/!somebadroom%3Aexample.com
- {
- "new_room_user_id": "@someuser:example.com",
- "room_name": "Content Violation Notification",
- "message": "Bad Room has been shutdown due to content violations on this server. Please review our Terms of Service."
- }
- </code></pre>
- <p>Response:</p>
- <pre><code>{
- "kicked_users": 5,
- "failed_to_kick_users": 0,
- "local_aliases": ["#badroom:example.com", "#evilsaloon:example.com],
- "new_room_id": "!newroomid:example.com",
- },
- </code></pre>
- <h2 id="undoing-room-shutdowns-1"><a class="header" href="#undoing-room-shutdowns-1">Undoing room shutdowns</a></h2>
- <p><em>Note</em>: This guide may be outdated by the time you read it. By nature of room shutdowns being performed at the database level,
- the structure can and does change without notice.</p>
- <p>First, it's important to understand that a room shutdown is very destructive. Undoing a shutdown is not as simple as pretending it
- never happened - work has to be done to move forward instead of resetting the past. In fact, in some cases it might not be possible
- to recover at all:</p>
- <ul>
- <li>If the room was invite-only, your users will need to be re-invited.</li>
- <li>If the room no longer has any members at all, it'll be impossible to rejoin.</li>
- <li>The first user to rejoin will have to do so via an alias on a different server.</li>
- </ul>
- <p>With all that being said, if you still want to try and recover the room:</p>
- <ol>
- <li>For safety reasons, shut down Synapse.</li>
- <li>In the database, run <code>DELETE FROM blocked_rooms WHERE room_id = '!example:example.org';</code>
- <ul>
- <li>For caution: it's recommended to run this in a transaction: <code>BEGIN; DELETE ...;</code>, verify you got 1 result, then <code>COMMIT;</code>.</li>
- <li>The room ID is the same one supplied to the shutdown room API, not the Content Violation room.</li>
- </ul>
- </li>
- <li>Restart Synapse.</li>
- </ol>
- <p>You will have to manually handle, if you so choose, the following:</p>
- <ul>
- <li>Aliases that would have been redirected to the Content Violation room.</li>
- <li>Users that would have been booted from the room (and will have been force-joined to the Content Violation room).</li>
- <li>Removal of the Content Violation room if desired.</li>
- </ul>
- <div style="break-before: page; page-break-before: always;"></div><h1 id="users-media-usage-statistics"><a class="header" href="#users-media-usage-statistics">Users' media usage statistics</a></h1>
- <p>Returns information about all local media usage of users. Gives the
- possibility to filter them by time and user.</p>
- <p>The API is:</p>
- <pre><code>GET /_synapse/admin/v1/statistics/users/media
- </code></pre>
- <p>To use it, you will need to authenticate by providing an <code>access_token</code>
- for a server admin: see <a href="admin_api/../usage/administration/admin_api">Admin API</a>.</p>
- <p>A response body like the following is returned:</p>
- <pre><code class="language-json">{
- "users": [
- {
- "displayname": "foo_user_0",
- "media_count": 2,
- "media_length": 134,
- "user_id": "@foo_user_0:test"
- },
- {
- "displayname": "foo_user_1",
- "media_count": 2,
- "media_length": 134,
- "user_id": "@foo_user_1:test"
- }
- ],
- "next_token": 3,
- "total": 10
- }
- </code></pre>
- <p>To paginate, check for <code>next_token</code> and if present, call the endpoint
- again with <code>from</code> set to the value of <code>next_token</code>. This will return a new page.</p>
- <p>If the endpoint does not return a <code>next_token</code> then there are no more
- reports to paginate through.</p>
- <p><strong>Parameters</strong></p>
- <p>The following parameters should be set in the URL:</p>
- <ul>
- <li><code>limit</code>: string representing a positive integer - Is optional but is
- used for pagination, denoting the maximum number of items to return
- in this call. Defaults to <code>100</code>.</li>
- <li><code>from</code>: string representing a positive integer - Is optional but used for pagination,
- denoting the offset in the returned results. This should be treated as an opaque value
- and not explicitly set to anything other than the return value of <code>next_token</code> from a
- previous call. Defaults to <code>0</code>.</li>
- <li><code>order_by</code> - string - The method in which to sort the returned list of users. Valid values are:
- <ul>
- <li><code>user_id</code> - Users are ordered alphabetically by <code>user_id</code>. This is the default.</li>
- <li><code>displayname</code> - Users are ordered alphabetically by <code>displayname</code>.</li>
- <li><code>media_length</code> - Users are ordered by the total size of uploaded media in bytes.
- Smallest to largest.</li>
- <li><code>media_count</code> - Users are ordered by number of uploaded media. Smallest to largest.</li>
- </ul>
- </li>
- <li><code>from_ts</code> - string representing a positive integer - Considers only
- files created at this timestamp or later. Unix timestamp in ms.</li>
- <li><code>until_ts</code> - string representing a positive integer - Considers only
- files created at this timestamp or earlier. Unix timestamp in ms.</li>
- <li><code>search_term</code> - string - Filter users by their user ID localpart <strong>or</strong> displayname.
- The search term can be found in any part of the string.
- Defaults to no filtering.</li>
- <li><code>dir</code> - string - Direction of order. Either <code>f</code> for forwards or <code>b</code> for backwards.
- Setting this value to <code>b</code> will reverse the above sort order. Defaults to <code>f</code>.</li>
- </ul>
- <p><strong>Response</strong></p>
- <p>The following fields are returned in the JSON response body:</p>
- <ul>
- <li><code>users</code> - An array of objects, each containing information
- about the user and their local media. Objects contain the following fields:
- <ul>
- <li><code>displayname</code> - string - Displayname of this user.</li>
- <li><code>media_count</code> - integer - Number of uploaded media by this user.</li>
- <li><code>media_length</code> - integer - Size of uploaded media in bytes by this user.</li>
- <li><code>user_id</code> - string - Fully-qualified user ID (ex. <code>@user:server.com</code>).</li>
- </ul>
- </li>
- <li><code>next_token</code> - integer - Opaque value used for pagination. See above.</li>
- <li><code>total</code> - integer - Total number of users after filtering.</li>
- </ul>
- <div style="break-before: page; page-break-before: always;"></div><h1 id="user-admin-api"><a class="header" href="#user-admin-api">User Admin API</a></h1>
- <h2 id="query-user-account"><a class="header" href="#query-user-account">Query User Account</a></h2>
- <p>This API returns information about a specific user account.</p>
- <p>The api is:</p>
- <pre><code>GET /_synapse/admin/v2/users/<user_id>
- </code></pre>
- <p>To use it, you will need to authenticate by providing an <code>access_token</code> for a
- server admin: <a href="admin_api/../usage/administration/admin_api">Admin API</a></p>
- <p>It returns a JSON body like the following:</p>
- <pre><code class="language-json">{
- "displayname": "User",
- "threepids": [
- {
- "medium": "email",
- "address": "<user_mail_1>"
- },
- {
- "medium": "email",
- "address": "<user_mail_2>"
- }
- ],
- "avatar_url": "<avatar_url>",
- "admin": 0,
- "deactivated": 0,
- "shadow_banned": 0,
- "password_hash": "$2b$12$p9B4GkqYdRTPGD",
- "creation_ts": 1560432506,
- "appservice_id": null,
- "consent_server_notice_sent": null,
- "consent_version": null,
- "external_ids": [
- {
- "auth_provider": "<provider1>",
- "external_id": "<user_id_provider_1>"
- },
- {
- "auth_provider": "<provider2>",
- "external_id": "<user_id_provider_2>"
- }
- ]
- }
- </code></pre>
- <p>URL parameters:</p>
- <ul>
- <li><code>user_id</code>: fully-qualified user id: for example, <code>@user:server.com</code>.</li>
- </ul>
- <h2 id="create-or-modify-account"><a class="header" href="#create-or-modify-account">Create or modify Account</a></h2>
- <p>This API allows an administrator to create or modify a user account with a
- specific <code>user_id</code>.</p>
- <p>This api is:</p>
- <pre><code>PUT /_synapse/admin/v2/users/<user_id>
- </code></pre>
- <p>with a body of:</p>
- <pre><code class="language-json">{
- "password": "user_password",
- "displayname": "User",
- "threepids": [
- {
- "medium": "email",
- "address": "<user_mail_1>"
- },
- {
- "medium": "email",
- "address": "<user_mail_2>"
- }
- ],
- "avatar_url": "<avatar_url>",
- "admin": false,
- "deactivated": false
- }
- </code></pre>
- <p>To use it, you will need to authenticate by providing an <code>access_token</code> for a
- server admin: <a href="admin_api/../usage/administration/admin_api">Admin API</a></p>
- <p>URL parameters:</p>
- <ul>
- <li><code>user_id</code>: fully-qualified user id: for example, <code>@user:server.com</code>.</li>
- </ul>
- <p>Body parameters:</p>
- <ul>
- <li>
- <p><code>password</code>, optional. If provided, the user's password is updated and all
- devices are logged out.</p>
- </li>
- <li>
- <p><code>displayname</code>, optional, defaults to the value of <code>user_id</code>.</p>
- </li>
- <li>
- <p><code>threepids</code>, optional, allows setting the third-party IDs (email, msisdn)
- belonging to a user.</p>
- </li>
- <li>
- <p><code>avatar_url</code>, optional, must be a
- <a href="https://matrix.org/docs/spec/client_server/r0.6.0#matrix-content-mxc-uris">MXC URI</a>.</p>
- </li>
- <li>
- <p><code>admin</code>, optional, defaults to <code>false</code>.</p>
- </li>
- <li>
- <p><code>deactivated</code>, optional. If unspecified, deactivation state will be left
- unchanged on existing accounts and set to <code>false</code> for new accounts.
- A user cannot be erased by deactivating with this API. For details on
- deactivating users see <a href="admin_api/user_admin_api.html#deactivate-account">Deactivate Account</a>.</p>
- </li>
- </ul>
- <p>If the user already exists then optional parameters default to the current value.</p>
- <p>In order to re-activate an account <code>deactivated</code> must be set to <code>false</code>. If
- users do not login via single-sign-on, a new <code>password</code> must be provided.</p>
- <h2 id="list-accounts"><a class="header" href="#list-accounts">List Accounts</a></h2>
- <p>This API returns all local user accounts.
- By default, the response is ordered by ascending user ID.</p>
- <pre><code>GET /_synapse/admin/v2/users?from=0&limit=10&guests=false
- </code></pre>
- <p>To use it, you will need to authenticate by providing an <code>access_token</code> for a
- server admin: <a href="admin_api/../usage/administration/admin_api">Admin API</a></p>
- <p>A response body like the following is returned:</p>
- <pre><code class="language-json">{
- "users": [
- {
- "name": "<user_id1>",
- "is_guest": 0,
- "admin": 0,
- "user_type": null,
- "deactivated": 0,
- "shadow_banned": 0,
- "displayname": "<User One>",
- "avatar_url": null
- }, {
- "name": "<user_id2>",
- "is_guest": 0,
- "admin": 1,
- "user_type": null,
- "deactivated": 0,
- "shadow_banned": 0,
- "displayname": "<User Two>",
- "avatar_url": "<avatar_url>"
- }
- ],
- "next_token": "100",
- "total": 200
- }
- </code></pre>
- <p>To paginate, check for <code>next_token</code> and if present, call the endpoint again
- with <code>from</code> set to the value of <code>next_token</code>. This will return a new page.</p>
- <p>If the endpoint does not return a <code>next_token</code> then there are no more users
- to paginate through.</p>
- <p><strong>Parameters</strong></p>
- <p>The following parameters should be set in the URL:</p>
- <ul>
- <li>
- <p><code>user_id</code> - Is optional and filters to only return users with user IDs
- that contain this value. This parameter is ignored when using the <code>name</code> parameter.</p>
- </li>
- <li>
- <p><code>name</code> - Is optional and filters to only return users with user ID localparts
- <strong>or</strong> displaynames that contain this value.</p>
- </li>
- <li>
- <p><code>guests</code> - string representing a bool - Is optional and if <code>false</code> will <strong>exclude</strong> guest users.
- Defaults to <code>true</code> to include guest users.</p>
- </li>
- <li>
- <p><code>deactivated</code> - string representing a bool - Is optional and if <code>true</code> will <strong>include</strong> deactivated users.
- Defaults to <code>false</code> to exclude deactivated users.</p>
- </li>
- <li>
- <p><code>limit</code> - string representing a positive integer - Is optional but is used for pagination,
- denoting the maximum number of items to return in this call. Defaults to <code>100</code>.</p>
- </li>
- <li>
- <p><code>from</code> - string representing a positive integer - Is optional but used for pagination,
- denoting the offset in the returned results. This should be treated as an opaque value and
- not explicitly set to anything other than the return value of <code>next_token</code> from a previous call.
- Defaults to <code>0</code>.</p>
- </li>
- <li>
- <p><code>order_by</code> - The method by which to sort the returned list of users.
- If the ordered field has duplicates, the second order is always by ascending <code>name</code>,
- which guarantees a stable ordering. Valid values are:</p>
- <ul>
- <li><code>name</code> - Users are ordered alphabetically by <code>name</code>. This is the default.</li>
- <li><code>is_guest</code> - Users are ordered by <code>is_guest</code> status.</li>
- <li><code>admin</code> - Users are ordered by <code>admin</code> status.</li>
- <li><code>user_type</code> - Users are ordered alphabetically by <code>user_type</code>.</li>
- <li><code>deactivated</code> - Users are ordered by <code>deactivated</code> status.</li>
- <li><code>shadow_banned</code> - Users are ordered by <code>shadow_banned</code> status.</li>
- <li><code>displayname</code> - Users are ordered alphabetically by <code>displayname</code>.</li>
- <li><code>avatar_url</code> - Users are ordered alphabetically by avatar URL.</li>
- </ul>
- </li>
- <li>
- <p><code>dir</code> - Direction of media order. Either <code>f</code> for forwards or <code>b</code> for backwards.
- Setting this value to <code>b</code> will reverse the above sort order. Defaults to <code>f</code>.</p>
- </li>
- </ul>
- <p>Caution. The database only has indexes on the columns <code>name</code> and <code>created_ts</code>.
- This means that if a different sort order is used (<code>is_guest</code>, <code>admin</code>,
- <code>user_type</code>, <code>deactivated</code>, <code>shadow_banned</code>, <code>avatar_url</code> or <code>displayname</code>),
- this can cause a large load on the database, especially for large environments.</p>
- <p><strong>Response</strong></p>
- <p>The following fields are returned in the JSON response body:</p>
- <ul>
- <li>
- <p><code>users</code> - An array of objects, each containing information about an user.
- User objects contain the following fields:</p>
- <ul>
- <li><code>name</code> - string - Fully-qualified user ID (ex. <code>@user:server.com</code>).</li>
- <li><code>is_guest</code> - bool - Status if that user is a guest account.</li>
- <li><code>admin</code> - bool - Status if that user is a server administrator.</li>
- <li><code>user_type</code> - string - Type of the user. Normal users are type <code>None</code>.
- This allows user type specific behaviour. There are also types <code>support</code> and <code>bot</code>. </li>
- <li><code>deactivated</code> - bool - Status if that user has been marked as deactivated.</li>
- <li><code>shadow_banned</code> - bool - Status if that user has been marked as shadow banned.</li>
- <li><code>displayname</code> - string - The user's display name if they have set one.</li>
- <li><code>avatar_url</code> - string - The user's avatar URL if they have set one.</li>
- </ul>
- </li>
- <li>
- <p><code>next_token</code>: string representing a positive integer - Indication for pagination. See above.</p>
- </li>
- <li>
- <p><code>total</code> - integer - Total number of media.</p>
- </li>
- </ul>
- <h2 id="query-current-sessions-for-a-user"><a class="header" href="#query-current-sessions-for-a-user">Query current sessions for a user</a></h2>
- <p>This API returns information about the active sessions for a specific user.</p>
- <p>The endpoints are:</p>
- <pre><code>GET /_synapse/admin/v1/whois/<user_id>
- </code></pre>
- <p>and:</p>
- <pre><code>GET /_matrix/client/r0/admin/whois/<userId>
- </code></pre>
- <p>See also: <a href="https://matrix.org/docs/spec/client_server/r0.6.1#get-matrix-client-r0-admin-whois-userid">Client Server
- API Whois</a>.</p>
- <p>To use it, you will need to authenticate by providing an <code>access_token</code> for a
- server admin: <a href="admin_api/../usage/administration/admin_api">Admin API</a></p>
- <p>It returns a JSON body like the following:</p>
- <pre><code class="language-json">{
- "user_id": "<user_id>",
- "devices": {
- "": {
- "sessions": [
- {
- "connections": [
- {
- "ip": "1.2.3.4",
- "last_seen": 1417222374433,
- "user_agent": "Mozilla/5.0 ..."
- },
- {
- "ip": "1.2.3.10",
- "last_seen": 1417222374500,
- "user_agent": "Dalvik/2.1.0 ..."
- }
- ]
- }
- ]
- }
- }
- }
- </code></pre>
- <p><code>last_seen</code> is measured in milliseconds since the Unix epoch.</p>
- <h2 id="deactivate-account"><a class="header" href="#deactivate-account">Deactivate Account</a></h2>
- <p>This API deactivates an account. It removes active access tokens, resets the
- password, and deletes third-party IDs (to prevent the user requesting a
- password reset).</p>
- <p>It can also mark the user as GDPR-erased. This means messages sent by the
- user will still be visible by anyone that was in the room when these messages
- were sent, but hidden from users joining the room afterwards.</p>
- <p>The api is:</p>
- <pre><code>POST /_synapse/admin/v1/deactivate/<user_id>
- </code></pre>
- <p>with a body of:</p>
- <pre><code class="language-json">{
- "erase": true
- }
- </code></pre>
- <p>To use it, you will need to authenticate by providing an <code>access_token</code> for a
- server admin: <a href="admin_api/../usage/administration/admin_api">Admin API</a></p>
- <p>The erase parameter is optional and defaults to <code>false</code>.
- An empty body may be passed for backwards compatibility.</p>
- <p>The following actions are performed when deactivating an user:</p>
- <ul>
- <li>Try to unpind 3PIDs from the identity server</li>
- <li>Remove all 3PIDs from the homeserver</li>
- <li>Delete all devices and E2EE keys</li>
- <li>Delete all access tokens</li>
- <li>Delete the password hash</li>
- <li>Removal from all rooms the user is a member of</li>
- <li>Remove the user from the user directory</li>
- <li>Reject all pending invites</li>
- <li>Remove all account validity information related to the user</li>
- </ul>
- <p>The following additional actions are performed during deactivation if <code>erase</code>
- is set to <code>true</code>:</p>
- <ul>
- <li>Remove the user's display name</li>
- <li>Remove the user's avatar URL</li>
- <li>Mark the user as erased</li>
- </ul>
- <h2 id="reset-password"><a class="header" href="#reset-password">Reset password</a></h2>
- <p>Changes the password of another user. This will automatically log the user out of all their devices.</p>
- <p>The api is:</p>
- <pre><code>POST /_synapse/admin/v1/reset_password/<user_id>
- </code></pre>
- <p>with a body of:</p>
- <pre><code class="language-json">{
- "new_password": "<secret>",
- "logout_devices": true
- }
- </code></pre>
- <p>To use it, you will need to authenticate by providing an <code>access_token</code> for a
- server admin: <a href="admin_api/../usage/administration/admin_api">Admin API</a></p>
- <p>The parameter <code>new_password</code> is required.
- The parameter <code>logout_devices</code> is optional and defaults to <code>true</code>.</p>
- <h2 id="get-whether-a-user-is-a-server-administrator-or-not"><a class="header" href="#get-whether-a-user-is-a-server-administrator-or-not">Get whether a user is a server administrator or not</a></h2>
- <p>The api is:</p>
- <pre><code>GET /_synapse/admin/v1/users/<user_id>/admin
- </code></pre>
- <p>To use it, you will need to authenticate by providing an <code>access_token</code> for a
- server admin: <a href="admin_api/../usage/administration/admin_api">Admin API</a></p>
- <p>A response body like the following is returned:</p>
- <pre><code class="language-json">{
- "admin": true
- }
- </code></pre>
- <h2 id="change-whether-a-user-is-a-server-administrator-or-not"><a class="header" href="#change-whether-a-user-is-a-server-administrator-or-not">Change whether a user is a server administrator or not</a></h2>
- <p>Note that you cannot demote yourself.</p>
- <p>The api is:</p>
- <pre><code>PUT /_synapse/admin/v1/users/<user_id>/admin
- </code></pre>
- <p>with a body of:</p>
- <pre><code class="language-json">{
- "admin": true
- }
- </code></pre>
- <p>To use it, you will need to authenticate by providing an <code>access_token</code> for a
- server admin: <a href="admin_api/../usage/administration/admin_api">Admin API</a></p>
- <h2 id="list-room-memberships-of-a-user"><a class="header" href="#list-room-memberships-of-a-user">List room memberships of a user</a></h2>
- <p>Gets a list of all <code>room_id</code> that a specific <code>user_id</code> is member.</p>
- <p>The API is:</p>
- <pre><code>GET /_synapse/admin/v1/users/<user_id>/joined_rooms
- </code></pre>
- <p>To use it, you will need to authenticate by providing an <code>access_token</code> for a
- server admin: <a href="admin_api/../usage/administration/admin_api">Admin API</a></p>
- <p>A response body like the following is returned:</p>
- <pre><code class="language-json"> {
- "joined_rooms": [
- "!DuGcnbhHGaSZQoNQR:matrix.org",
- "!ZtSaPCawyWtxfWiIy:matrix.org"
- ],
- "total": 2
- }
- </code></pre>
- <p>The server returns the list of rooms of which the user and the server
- are member. If the user is local, all the rooms of which the user is
- member are returned.</p>
- <p><strong>Parameters</strong></p>
- <p>The following parameters should be set in the URL:</p>
- <ul>
- <li><code>user_id</code> - fully qualified: for example, <code>@user:server.com</code>.</li>
- </ul>
- <p><strong>Response</strong></p>
- <p>The following fields are returned in the JSON response body:</p>
- <ul>
- <li><code>joined_rooms</code> - An array of <code>room_id</code>.</li>
- <li><code>total</code> - Number of rooms.</li>
- </ul>
- <h2 id="list-media-of-a-user"><a class="header" href="#list-media-of-a-user">List media of a user</a></h2>
- <p>Gets a list of all local media that a specific <code>user_id</code> has created.
- By default, the response is ordered by descending creation date and ascending media ID.
- The newest media is on top. You can change the order with parameters
- <code>order_by</code> and <code>dir</code>.</p>
- <p>The API is:</p>
- <pre><code>GET /_synapse/admin/v1/users/<user_id>/media
- </code></pre>
- <p>To use it, you will need to authenticate by providing an <code>access_token</code> for a
- server admin: <a href="admin_api/../usage/administration/admin_api">Admin API</a></p>
- <p>A response body like the following is returned:</p>
- <pre><code class="language-json">{
- "media": [
- {
- "created_ts": 100400,
- "last_access_ts": null,
- "media_id": "qXhyRzulkwLsNHTbpHreuEgo",
- "media_length": 67,
- "media_type": "image/png",
- "quarantined_by": null,
- "safe_from_quarantine": false,
- "upload_name": "test1.png"
- },
- {
- "created_ts": 200400,
- "last_access_ts": null,
- "media_id": "FHfiSnzoINDatrXHQIXBtahw",
- "media_length": 67,
- "media_type": "image/png",
- "quarantined_by": null,
- "safe_from_quarantine": false,
- "upload_name": "test2.png"
- }
- ],
- "next_token": 3,
- "total": 2
- }
- </code></pre>
- <p>To paginate, check for <code>next_token</code> and if present, call the endpoint again
- with <code>from</code> set to the value of <code>next_token</code>. This will return a new page.</p>
- <p>If the endpoint does not return a <code>next_token</code> then there are no more
- reports to paginate through.</p>
- <p><strong>Parameters</strong></p>
- <p>The following parameters should be set in the URL:</p>
- <ul>
- <li>
- <p><code>user_id</code> - string - fully qualified: for example, <code>@user:server.com</code>.</p>
- </li>
- <li>
- <p><code>limit</code>: string representing a positive integer - Is optional but is used for pagination,
- denoting the maximum number of items to return in this call. Defaults to <code>100</code>.</p>
- </li>
- <li>
- <p><code>from</code>: string representing a positive integer - Is optional but used for pagination,
- denoting the offset in the returned results. This should be treated as an opaque value and
- not explicitly set to anything other than the return value of <code>next_token</code> from a previous call.
- Defaults to <code>0</code>.</p>
- </li>
- <li>
- <p><code>order_by</code> - The method by which to sort the returned list of media.
- If the ordered field has duplicates, the second order is always by ascending <code>media_id</code>,
- which guarantees a stable ordering. Valid values are:</p>
- <ul>
- <li><code>media_id</code> - Media are ordered alphabetically by <code>media_id</code>.</li>
- <li><code>upload_name</code> - Media are ordered alphabetically by name the media was uploaded with.</li>
- <li><code>created_ts</code> - Media are ordered by when the content was uploaded in ms.
- Smallest to largest. This is the default.</li>
- <li><code>last_access_ts</code> - Media are ordered by when the content was last accessed in ms.
- Smallest to largest.</li>
- <li><code>media_length</code> - Media are ordered by length of the media in bytes.
- Smallest to largest.</li>
- <li><code>media_type</code> - Media are ordered alphabetically by MIME-type.</li>
- <li><code>quarantined_by</code> - Media are ordered alphabetically by the user ID that
- initiated the quarantine request for this media.</li>
- <li><code>safe_from_quarantine</code> - Media are ordered by the status if this media is safe
- from quarantining.</li>
- </ul>
- </li>
- <li>
- <p><code>dir</code> - Direction of media order. Either <code>f</code> for forwards or <code>b</code> for backwards.
- Setting this value to <code>b</code> will reverse the above sort order. Defaults to <code>f</code>.</p>
- </li>
- </ul>
- <p>If neither <code>order_by</code> nor <code>dir</code> is set, the default order is newest media on top
- (corresponds to <code>order_by</code> = <code>created_ts</code> and <code>dir</code> = <code>b</code>).</p>
- <p>Caution. The database only has indexes on the columns <code>media_id</code>,
- <code>user_id</code> and <code>created_ts</code>. This means that if a different sort order is used
- (<code>upload_name</code>, <code>last_access_ts</code>, <code>media_length</code>, <code>media_type</code>,
- <code>quarantined_by</code> or <code>safe_from_quarantine</code>), this can cause a large load on the
- database, especially for large environments.</p>
- <p><strong>Response</strong></p>
- <p>The following fields are returned in the JSON response body:</p>
- <ul>
- <li>
- <p><code>media</code> - An array of objects, each containing information about a media.
- Media objects contain the following fields:</p>
- <ul>
- <li>
- <p><code>created_ts</code> - integer - Timestamp when the content was uploaded in ms.</p>
- </li>
- <li>
- <p><code>last_access_ts</code> - integer - Timestamp when the content was last accessed in ms.</p>
- </li>
- <li>
- <p><code>media_id</code> - string - The id used to refer to the media.</p>
- </li>
- <li>
- <p><code>media_length</code> - integer - Length of the media in bytes.</p>
- </li>
- <li>
- <p><code>media_type</code> - string - The MIME-type of the media.</p>
- </li>
- <li>
- <p><code>quarantined_by</code> - string - The user ID that initiated the quarantine request
- for this media.</p>
- </li>
- <li>
- <p><code>safe_from_quarantine</code> - bool - Status if this media is safe from quarantining.</p>
- </li>
- <li>
- <p><code>upload_name</code> - string - The name the media was uploaded with.</p>
- </li>
- </ul>
- </li>
- <li>
- <p><code>next_token</code>: integer - Indication for pagination. See above.</p>
- </li>
- <li>
- <p><code>total</code> - integer - Total number of media.</p>
- </li>
- </ul>
- <h2 id="login-as-a-user"><a class="header" href="#login-as-a-user">Login as a user</a></h2>
- <p>Get an access token that can be used to authenticate as that user. Useful for
- when admins wish to do actions on behalf of a user.</p>
- <p>The API is:</p>
- <pre><code>POST /_synapse/admin/v1/users/<user_id>/login
- {}
- </code></pre>
- <p>An optional <code>valid_until_ms</code> field can be specified in the request body as an
- integer timestamp that specifies when the token should expire. By default tokens
- do not expire.</p>
- <p>A response body like the following is returned:</p>
- <pre><code class="language-json">{
- "access_token": "<opaque_access_token_string>"
- }
- </code></pre>
- <p>This API does <em>not</em> generate a new device for the user, and so will not appear
- their <code>/devices</code> list, and in general the target user should not be able to
- tell they have been logged in as.</p>
- <p>To expire the token call the standard <code>/logout</code> API with the token.</p>
- <p>Note: The token will expire if the <em>admin</em> user calls <code>/logout/all</code> from any
- of their devices, but the token will <em>not</em> expire if the target user does the
- same.</p>
- <h2 id="user-devices"><a class="header" href="#user-devices">User devices</a></h2>
- <h3 id="list-all-devices"><a class="header" href="#list-all-devices">List all devices</a></h3>
- <p>Gets information about all devices for a specific <code>user_id</code>.</p>
- <p>The API is:</p>
- <pre><code>GET /_synapse/admin/v2/users/<user_id>/devices
- </code></pre>
- <p>To use it, you will need to authenticate by providing an <code>access_token</code> for a
- server admin: <a href="admin_api/../usage/administration/admin_api">Admin API</a></p>
- <p>A response body like the following is returned:</p>
- <pre><code class="language-json">{
- "devices": [
- {
- "device_id": "QBUAZIFURK",
- "display_name": "android",
- "last_seen_ip": "1.2.3.4",
- "last_seen_ts": 1474491775024,
- "user_id": "<user_id>"
- },
- {
- "device_id": "AUIECTSRND",
- "display_name": "ios",
- "last_seen_ip": "1.2.3.5",
- "last_seen_ts": 1474491775025,
- "user_id": "<user_id>"
- }
- ],
- "total": 2
- }
- </code></pre>
- <p><strong>Parameters</strong></p>
- <p>The following parameters should be set in the URL:</p>
- <ul>
- <li><code>user_id</code> - fully qualified: for example, <code>@user:server.com</code>.</li>
- </ul>
- <p><strong>Response</strong></p>
- <p>The following fields are returned in the JSON response body:</p>
- <ul>
- <li>
- <p><code>devices</code> - An array of objects, each containing information about a device.
- Device objects contain the following fields:</p>
- <ul>
- <li><code>device_id</code> - Identifier of device.</li>
- <li><code>display_name</code> - Display name set by the user for this device.
- Absent if no name has been set.</li>
- <li><code>last_seen_ip</code> - The IP address where this device was last seen.
- (May be a few minutes out of date, for efficiency reasons).</li>
- <li><code>last_seen_ts</code> - The timestamp (in milliseconds since the unix epoch) when this
- devices was last seen. (May be a few minutes out of date, for efficiency reasons).</li>
- <li><code>user_id</code> - Owner of device.</li>
- </ul>
- </li>
- <li>
- <p><code>total</code> - Total number of user's devices.</p>
- </li>
- </ul>
- <h3 id="delete-multiple-devices"><a class="header" href="#delete-multiple-devices">Delete multiple devices</a></h3>
- <p>Deletes the given devices for a specific <code>user_id</code>, and invalidates
- any access token associated with them.</p>
- <p>The API is:</p>
- <pre><code>POST /_synapse/admin/v2/users/<user_id>/delete_devices
- {
- "devices": [
- "QBUAZIFURK",
- "AUIECTSRND"
- ],
- }
- </code></pre>
- <p>To use it, you will need to authenticate by providing an <code>access_token</code> for a
- server admin: <a href="admin_api/../usage/administration/admin_api">Admin API</a></p>
- <p>An empty JSON dict is returned.</p>
- <p><strong>Parameters</strong></p>
- <p>The following parameters should be set in the URL:</p>
- <ul>
- <li><code>user_id</code> - fully qualified: for example, <code>@user:server.com</code>.</li>
- </ul>
- <p>The following fields are required in the JSON request body:</p>
- <ul>
- <li><code>devices</code> - The list of device IDs to delete.</li>
- </ul>
- <h3 id="show-a-device"><a class="header" href="#show-a-device">Show a device</a></h3>
- <p>Gets information on a single device, by <code>device_id</code> for a specific <code>user_id</code>.</p>
- <p>The API is:</p>
- <pre><code>GET /_synapse/admin/v2/users/<user_id>/devices/<device_id>
- </code></pre>
- <p>To use it, you will need to authenticate by providing an <code>access_token</code> for a
- server admin: <a href="admin_api/../usage/administration/admin_api">Admin API</a></p>
- <p>A response body like the following is returned:</p>
- <pre><code class="language-json">{
- "device_id": "<device_id>",
- "display_name": "android",
- "last_seen_ip": "1.2.3.4",
- "last_seen_ts": 1474491775024,
- "user_id": "<user_id>"
- }
- </code></pre>
- <p><strong>Parameters</strong></p>
- <p>The following parameters should be set in the URL:</p>
- <ul>
- <li><code>user_id</code> - fully qualified: for example, <code>@user:server.com</code>.</li>
- <li><code>device_id</code> - The device to retrieve.</li>
- </ul>
- <p><strong>Response</strong></p>
- <p>The following fields are returned in the JSON response body:</p>
- <ul>
- <li><code>device_id</code> - Identifier of device.</li>
- <li><code>display_name</code> - Display name set by the user for this device.
- Absent if no name has been set.</li>
- <li><code>last_seen_ip</code> - The IP address where this device was last seen.
- (May be a few minutes out of date, for efficiency reasons).</li>
- <li><code>last_seen_ts</code> - The timestamp (in milliseconds since the unix epoch) when this
- devices was last seen. (May be a few minutes out of date, for efficiency reasons).</li>
- <li><code>user_id</code> - Owner of device.</li>
- </ul>
- <h3 id="update-a-device"><a class="header" href="#update-a-device">Update a device</a></h3>
- <p>Updates the metadata on the given <code>device_id</code> for a specific <code>user_id</code>.</p>
- <p>The API is:</p>
- <pre><code>PUT /_synapse/admin/v2/users/<user_id>/devices/<device_id>
- {
- "display_name": "My other phone"
- }
- </code></pre>
- <p>To use it, you will need to authenticate by providing an <code>access_token</code> for a
- server admin: <a href="admin_api/../usage/administration/admin_api">Admin API</a></p>
- <p>An empty JSON dict is returned.</p>
- <p><strong>Parameters</strong></p>
- <p>The following parameters should be set in the URL:</p>
- <ul>
- <li><code>user_id</code> - fully qualified: for example, <code>@user:server.com</code>.</li>
- <li><code>device_id</code> - The device to update.</li>
- </ul>
- <p>The following fields are required in the JSON request body:</p>
- <ul>
- <li><code>display_name</code> - The new display name for this device. If not given,
- the display name is unchanged.</li>
- </ul>
- <h3 id="delete-a-device"><a class="header" href="#delete-a-device">Delete a device</a></h3>
- <p>Deletes the given <code>device_id</code> for a specific <code>user_id</code>,
- and invalidates any access token associated with it.</p>
- <p>The API is:</p>
- <pre><code>DELETE /_synapse/admin/v2/users/<user_id>/devices/<device_id>
- {}
- </code></pre>
- <p>To use it, you will need to authenticate by providing an <code>access_token</code> for a
- server admin: <a href="admin_api/../usage/administration/admin_api">Admin API</a></p>
- <p>An empty JSON dict is returned.</p>
- <p><strong>Parameters</strong></p>
- <p>The following parameters should be set in the URL:</p>
- <ul>
- <li><code>user_id</code> - fully qualified: for example, <code>@user:server.com</code>.</li>
- <li><code>device_id</code> - The device to delete.</li>
- </ul>
- <h2 id="list-all-pushers"><a class="header" href="#list-all-pushers">List all pushers</a></h2>
- <p>Gets information about all pushers for a specific <code>user_id</code>.</p>
- <p>The API is:</p>
- <pre><code>GET /_synapse/admin/v1/users/<user_id>/pushers
- </code></pre>
- <p>To use it, you will need to authenticate by providing an <code>access_token</code> for a
- server admin: <a href="admin_api/../usage/administration/admin_api">Admin API</a></p>
- <p>A response body like the following is returned:</p>
- <pre><code class="language-json">{
- "pushers": [
- {
- "app_display_name":"HTTP Push Notifications",
- "app_id":"m.http",
- "data": {
- "url":"example.com"
- },
- "device_display_name":"pushy push",
- "kind":"http",
- "lang":"None",
- "profile_tag":"",
- "pushkey":"a@example.com"
- }
- ],
- "total": 1
- }
- </code></pre>
- <p><strong>Parameters</strong></p>
- <p>The following parameters should be set in the URL:</p>
- <ul>
- <li><code>user_id</code> - fully qualified: for example, <code>@user:server.com</code>.</li>
- </ul>
- <p><strong>Response</strong></p>
- <p>The following fields are returned in the JSON response body:</p>
- <ul>
- <li>
- <p><code>pushers</code> - An array containing the current pushers for the user</p>
- <ul>
- <li>
- <p><code>app_display_name</code> - string - A string that will allow the user to identify
- what application owns this pusher.</p>
- </li>
- <li>
- <p><code>app_id</code> - string - This is a reverse-DNS style identifier for the application.
- Max length, 64 chars.</p>
- </li>
- <li>
- <p><code>data</code> - A dictionary of information for the pusher implementation itself.</p>
- <ul>
- <li>
- <p><code>url</code> - string - Required if <code>kind</code> is <code>http</code>. The URL to use to send
- notifications to.</p>
- </li>
- <li>
- <p><code>format</code> - string - The format to use when sending notifications to the
- Push Gateway.</p>
- </li>
- </ul>
- </li>
- <li>
- <p><code>device_display_name</code> - string - A string that will allow the user to identify
- what device owns this pusher.</p>
- </li>
- <li>
- <p><code>profile_tag</code> - string - This string determines which set of device specific rules
- this pusher executes.</p>
- </li>
- <li>
- <p><code>kind</code> - string - The kind of pusher. "http" is a pusher that sends HTTP pokes.</p>
- </li>
- <li>
- <p><code>lang</code> - string - The preferred language for receiving notifications
- (e.g. 'en' or 'en-US')</p>
- </li>
- <li>
- <p><code>profile_tag</code> - string - This string determines which set of device specific rules
- this pusher executes.</p>
- </li>
- <li>
- <p><code>pushkey</code> - string - This is a unique identifier for this pusher.
- Max length, 512 bytes.</p>
- </li>
- </ul>
- </li>
- <li>
- <p><code>total</code> - integer - Number of pushers.</p>
- </li>
- </ul>
- <p>See also the
- <a href="https://matrix.org/docs/spec/client_server/latest#get-matrix-client-r0-pushers">Client-Server API Spec on pushers</a>.</p>
- <h2 id="shadow-banning-users"><a class="header" href="#shadow-banning-users">Shadow-banning users</a></h2>
- <p>Shadow-banning is a useful tool for moderating malicious or egregiously abusive users.
- A shadow-banned users receives successful responses to their client-server API requests,
- but the events are not propagated into rooms. This can be an effective tool as it
- (hopefully) takes longer for the user to realise they are being moderated before
- pivoting to another account.</p>
- <p>Shadow-banning a user should be used as a tool of last resort and may lead to confusing
- or broken behaviour for the client. A shadow-banned user will not receive any
- notification and it is generally more appropriate to ban or kick abusive users.
- A shadow-banned user will be unable to contact anyone on the server.</p>
- <p>The API is:</p>
- <pre><code>POST /_synapse/admin/v1/users/<user_id>/shadow_ban
- </code></pre>
- <p>To use it, you will need to authenticate by providing an <code>access_token</code> for a
- server admin: <a href="admin_api/../usage/administration/admin_api">Admin API</a></p>
- <p>An empty JSON dict is returned.</p>
- <p><strong>Parameters</strong></p>
- <p>The following parameters should be set in the URL:</p>
- <ul>
- <li><code>user_id</code> - The fully qualified MXID: for example, <code>@user:server.com</code>. The user must
- be local.</li>
- </ul>
- <h2 id="override-ratelimiting-for-users"><a class="header" href="#override-ratelimiting-for-users">Override ratelimiting for users</a></h2>
- <p>This API allows to override or disable ratelimiting for a specific user.
- There are specific APIs to set, get and delete a ratelimit.</p>
- <h3 id="get-status-of-ratelimit"><a class="header" href="#get-status-of-ratelimit">Get status of ratelimit</a></h3>
- <p>The API is:</p>
- <pre><code>GET /_synapse/admin/v1/users/<user_id>/override_ratelimit
- </code></pre>
- <p>To use it, you will need to authenticate by providing an <code>access_token</code> for a
- server admin: <a href="admin_api/../usage/administration/admin_api">Admin API</a></p>
- <p>A response body like the following is returned:</p>
- <pre><code class="language-json">{
- "messages_per_second": 0,
- "burst_count": 0
- }
- </code></pre>
- <p><strong>Parameters</strong></p>
- <p>The following parameters should be set in the URL:</p>
- <ul>
- <li><code>user_id</code> - The fully qualified MXID: for example, <code>@user:server.com</code>. The user must
- be local.</li>
- </ul>
- <p><strong>Response</strong></p>
- <p>The following fields are returned in the JSON response body:</p>
- <ul>
- <li><code>messages_per_second</code> - integer - The number of actions that can
- be performed in a second. <code>0</code> mean that ratelimiting is disabled for this user.</li>
- <li><code>burst_count</code> - integer - How many actions that can be performed before
- being limited.</li>
- </ul>
- <p>If <strong>no</strong> custom ratelimit is set, an empty JSON dict is returned.</p>
- <pre><code class="language-json">{}
- </code></pre>
- <h3 id="set-ratelimit"><a class="header" href="#set-ratelimit">Set ratelimit</a></h3>
- <p>The API is:</p>
- <pre><code>POST /_synapse/admin/v1/users/<user_id>/override_ratelimit
- </code></pre>
- <p>To use it, you will need to authenticate by providing an <code>access_token</code> for a
- server admin: <a href="admin_api/../usage/administration/admin_api">Admin API</a></p>
- <p>A response body like the following is returned:</p>
- <pre><code class="language-json">{
- "messages_per_second": 0,
- "burst_count": 0
- }
- </code></pre>
- <p><strong>Parameters</strong></p>
- <p>The following parameters should be set in the URL:</p>
- <ul>
- <li><code>user_id</code> - The fully qualified MXID: for example, <code>@user:server.com</code>. The user must
- be local.</li>
- </ul>
- <p>Body parameters:</p>
- <ul>
- <li><code>messages_per_second</code> - positive integer, optional. The number of actions that can
- be performed in a second. Defaults to <code>0</code>.</li>
- <li><code>burst_count</code> - positive integer, optional. How many actions that can be performed
- before being limited. Defaults to <code>0</code>.</li>
- </ul>
- <p>To disable users' ratelimit set both values to <code>0</code>.</p>
- <p><strong>Response</strong></p>
- <p>The following fields are returned in the JSON response body:</p>
- <ul>
- <li><code>messages_per_second</code> - integer - The number of actions that can
- be performed in a second.</li>
- <li><code>burst_count</code> - integer - How many actions that can be performed before
- being limited.</li>
- </ul>
- <h3 id="delete-ratelimit"><a class="header" href="#delete-ratelimit">Delete ratelimit</a></h3>
- <p>The API is:</p>
- <pre><code>DELETE /_synapse/admin/v1/users/<user_id>/override_ratelimit
- </code></pre>
- <p>To use it, you will need to authenticate by providing an <code>access_token</code> for a
- server admin: <a href="admin_api/../usage/administration/admin_api">Admin API</a></p>
- <p>An empty JSON dict is returned.</p>
- <pre><code class="language-json">{}
- </code></pre>
- <p><strong>Parameters</strong></p>
- <p>The following parameters should be set in the URL:</p>
- <ul>
- <li><code>user_id</code> - The fully qualified MXID: for example, <code>@user:server.com</code>. The user must
- be local.</li>
- </ul>
- <div style="break-before: page; page-break-before: always;"></div><h1 id="version-api"><a class="header" href="#version-api">Version API</a></h1>
- <p>This API returns the running Synapse version and the Python version
- on which Synapse is being run. This is useful when a Synapse instance
- is behind a proxy that does not forward the 'Server' header (which also
- contains Synapse version information).</p>
- <p>The api is:</p>
- <pre><code>GET /_synapse/admin/v1/server_version
- </code></pre>
- <p>It returns a JSON body like the following:</p>
- <pre><code class="language-json">{
- "server_version": "0.99.2rc1 (b=develop, abcdef123)",
- "python_version": "3.6.8"
- }
- </code></pre>
- <div style="break-before: page; page-break-before: always;"></div><h1 id="using-the-synapse-manhole"><a class="header" href="#using-the-synapse-manhole">Using the synapse manhole</a></h1>
- <p>The "manhole" allows server administrators to access a Python shell on a running
- Synapse installation. This is a very powerful mechanism for administration and
- debugging.</p>
- <p><strong><em>Security Warning</em></strong></p>
- <p>Note that this will give administrative access to synapse to <strong>all users</strong> with
- shell access to the server. It should therefore <strong>not</strong> be enabled in
- environments where untrusted users have shell access.</p>
- <hr />
- <p>To enable it, first uncomment the <code>manhole</code> listener configuration in
- <code>homeserver.yaml</code>. The configuration is slightly different if you're using docker.</p>
- <h4 id="docker-config"><a class="header" href="#docker-config">Docker config</a></h4>
- <p>If you are using Docker, set <code>bind_addresses</code> to <code>['0.0.0.0']</code> as shown:</p>
- <pre><code class="language-yaml">listeners:
- - port: 9000
- bind_addresses: ['0.0.0.0']
- type: manhole
- </code></pre>
- <p>When using <code>docker run</code> to start the server, you will then need to change the command to the following to include the
- <code>manhole</code> port forwarding. The <code>-p 127.0.0.1:9000:9000</code> below is important: it
- ensures that access to the <code>manhole</code> is only possible for local users.</p>
- <pre><code class="language-bash">docker run -d --name synapse \
- --mount type=volume,src=synapse-data,dst=/data \
- -p 8008:8008 \
- -p 127.0.0.1:9000:9000 \
- matrixdotorg/synapse:latest
- </code></pre>
- <h4 id="native-config"><a class="header" href="#native-config">Native config</a></h4>
- <p>If you are not using docker, set <code>bind_addresses</code> to <code>['::1', '127.0.0.1']</code> as shown.
- The <code>bind_addresses</code> in the example below is important: it ensures that access to the
- <code>manhole</code> is only possible for local users).</p>
- <pre><code class="language-yaml">listeners:
- - port: 9000
- bind_addresses: ['::1', '127.0.0.1']
- type: manhole
- </code></pre>
- <h4 id="accessing-synapse-manhole"><a class="header" href="#accessing-synapse-manhole">Accessing synapse manhole</a></h4>
- <p>Then restart synapse, and point an ssh client at port 9000 on localhost, using
- the username <code>matrix</code>:</p>
- <pre><code class="language-bash">ssh -p9000 matrix@localhost
- </code></pre>
- <p>The password is <code>rabbithole</code>.</p>
- <p>This gives a Python REPL in which <code>hs</code> gives access to the
- <code>synapse.server.HomeServer</code> object - which in turn gives access to many other
- parts of the process.</p>
- <p>Note that any call which returns a coroutine will need to be wrapped in <code>ensureDeferred</code>.</p>
- <p>As a simple example, retrieving an event from the database:</p>
- <pre><code class="language-pycon">>>> from twisted.internet import defer
- >>> defer.ensureDeferred(hs.get_datastore().get_event('$1416420717069yeQaw:matrix.org'))
- <Deferred at 0x7ff253fc6998 current result: <FrozenEvent event_id='$1416420717069yeQaw:matrix.org', type='m.room.create', state_key=''>>
- </code></pre>
- <div style="break-before: page; page-break-before: always;"></div><h1 id="how-to-monitor-synapse-metrics-using-prometheus"><a class="header" href="#how-to-monitor-synapse-metrics-using-prometheus">How to monitor Synapse metrics using Prometheus</a></h1>
- <ol>
- <li>
- <p>Install Prometheus:</p>
- <p>Follow instructions at
- <a href="http://prometheus.io/docs/introduction/install/">http://prometheus.io/docs/introduction/install/</a></p>
- </li>
- <li>
- <p>Enable Synapse metrics:</p>
- <p>There are two methods of enabling metrics in Synapse.</p>
- <p>The first serves the metrics as a part of the usual web server and
- can be enabled by adding the "metrics" resource to the existing
- listener as such:</p>
- <pre><code class="language-yaml"> resources:
- - names:
- - client
- - metrics
- </code></pre>
- <p>This provides a simple way of adding metrics to your Synapse
- installation, and serves under <code>/_synapse/metrics</code>. If you do not
- wish your metrics be publicly exposed, you will need to either
- filter it out at your load balancer, or use the second method.</p>
- <p>The second method runs the metrics server on a different port, in a
- different thread to Synapse. This can make it more resilient to
- heavy load meaning metrics cannot be retrieved, and can be exposed
- to just internal networks easier. The served metrics are available
- over HTTP only, and will be available at <code>/_synapse/metrics</code>.</p>
- <p>Add a new listener to homeserver.yaml:</p>
- <pre><code class="language-yaml"> listeners:
- - type: metrics
- port: 9000
- bind_addresses:
- - '0.0.0.0'
- </code></pre>
- <p>For both options, you will need to ensure that <code>enable_metrics</code> is
- set to <code>True</code>.</p>
- </li>
- <li>
- <p>Restart Synapse.</p>
- </li>
- <li>
- <p>Add a Prometheus target for Synapse.</p>
- <p>It needs to set the <code>metrics_path</code> to a non-default value (under
- <code>scrape_configs</code>):</p>
- <pre><code class="language-yaml"> - job_name: "synapse"
- scrape_interval: 15s
- metrics_path: "/_synapse/metrics"
- static_configs:
- - targets: ["my.server.here:port"]
- </code></pre>
- <p>where <code>my.server.here</code> is the IP address of Synapse, and <code>port</code> is
- the listener port configured with the <code>metrics</code> resource.</p>
- <p>If your prometheus is older than 1.5.2, you will need to replace
- <code>static_configs</code> in the above with <code>target_groups</code>.</p>
- </li>
- <li>
- <p>Restart Prometheus.</p>
- </li>
- <li>
- <p>Consider using the <a href="https://github.com/matrix-org/synapse/tree/master/contrib/grafana/">grafana dashboard</a>
- and required <a href="https://github.com/matrix-org/synapse/tree/master/contrib/prometheus/">recording rules</a> </p>
- </li>
- </ol>
- <h2 id="monitoring-workers"><a class="header" href="#monitoring-workers">Monitoring workers</a></h2>
- <p>To monitor a Synapse installation using <a href="workers.html">workers</a>,
- every worker needs to be monitored independently, in addition to
- the main homeserver process. This is because workers don't send
- their metrics to the main homeserver process, but expose them
- directly (if they are configured to do so).</p>
- <p>To allow collecting metrics from a worker, you need to add a
- <code>metrics</code> listener to its configuration, by adding the following
- under <code>worker_listeners</code>:</p>
- <pre><code class="language-yaml"> - type: metrics
- bind_address: ''
- port: 9101
- </code></pre>
- <p>The <code>bind_address</code> and <code>port</code> parameters should be set so that
- the resulting listener can be reached by prometheus, and they
- don't clash with an existing worker.
- With this example, the worker's metrics would then be available
- on <code>http://127.0.0.1:9101</code>.</p>
- <p>Example Prometheus target for Synapse with workers:</p>
- <pre><code class="language-yaml"> - job_name: "synapse"
- scrape_interval: 15s
- metrics_path: "/_synapse/metrics"
- static_configs:
- - targets: ["my.server.here:port"]
- labels:
- instance: "my.server"
- job: "master"
- index: 1
- - targets: ["my.workerserver.here:port"]
- labels:
- instance: "my.server"
- job: "generic_worker"
- index: 1
- - targets: ["my.workerserver.here:port"]
- labels:
- instance: "my.server"
- job: "generic_worker"
- index: 2
- - targets: ["my.workerserver.here:port"]
- labels:
- instance: "my.server"
- job: "media_repository"
- index: 1
- </code></pre>
- <p>Labels (<code>instance</code>, <code>job</code>, <code>index</code>) can be defined as anything.
- The labels are used to group graphs in grafana.</p>
- <h2 id="renaming-of-metrics--deprecation-of-old-names-in-12"><a class="header" href="#renaming-of-metrics--deprecation-of-old-names-in-12">Renaming of metrics & deprecation of old names in 1.2</a></h2>
- <p>Synapse 1.2 updates the Prometheus metrics to match the naming
- convention of the upstream <code>prometheus_client</code>. The old names are
- considered deprecated and will be removed in a future version of
- Synapse.</p>
- <table><thead><tr><th>New Name</th><th>Old Name</th></tr></thead><tbody>
- <tr><td>python_gc_objects_collected_total</td><td>python_gc_objects_collected</td></tr>
- <tr><td>python_gc_objects_uncollectable_total</td><td>python_gc_objects_uncollectable</td></tr>
- <tr><td>python_gc_collections_total</td><td>python_gc_collections</td></tr>
- <tr><td>process_cpu_seconds_total</td><td>process_cpu_seconds</td></tr>
- <tr><td>synapse_federation_client_sent_transactions_total</td><td>synapse_federation_client_sent_transactions</td></tr>
- <tr><td>synapse_federation_client_events_processed_total</td><td>synapse_federation_client_events_processed</td></tr>
- <tr><td>synapse_event_processing_loop_count_total</td><td>synapse_event_processing_loop_count</td></tr>
- <tr><td>synapse_event_processing_loop_room_count_total</td><td>synapse_event_processing_loop_room_count</td></tr>
- <tr><td>synapse_util_metrics_block_count_total</td><td>synapse_util_metrics_block_count</td></tr>
- <tr><td>synapse_util_metrics_block_time_seconds_total</td><td>synapse_util_metrics_block_time_seconds</td></tr>
- <tr><td>synapse_util_metrics_block_ru_utime_seconds_total</td><td>synapse_util_metrics_block_ru_utime_seconds</td></tr>
- <tr><td>synapse_util_metrics_block_ru_stime_seconds_total</td><td>synapse_util_metrics_block_ru_stime_seconds</td></tr>
- <tr><td>synapse_util_metrics_block_db_txn_count_total</td><td>synapse_util_metrics_block_db_txn_count</td></tr>
- <tr><td>synapse_util_metrics_block_db_txn_duration_seconds_total</td><td>synapse_util_metrics_block_db_txn_duration_seconds</td></tr>
- <tr><td>synapse_util_metrics_block_db_sched_duration_seconds_total</td><td>synapse_util_metrics_block_db_sched_duration_seconds</td></tr>
- <tr><td>synapse_background_process_start_count_total</td><td>synapse_background_process_start_count</td></tr>
- <tr><td>synapse_background_process_ru_utime_seconds_total</td><td>synapse_background_process_ru_utime_seconds</td></tr>
- <tr><td>synapse_background_process_ru_stime_seconds_total</td><td>synapse_background_process_ru_stime_seconds</td></tr>
- <tr><td>synapse_background_process_db_txn_count_total</td><td>synapse_background_process_db_txn_count</td></tr>
- <tr><td>synapse_background_process_db_txn_duration_seconds_total</td><td>synapse_background_process_db_txn_duration_seconds</td></tr>
- <tr><td>synapse_background_process_db_sched_duration_seconds_total</td><td>synapse_background_process_db_sched_duration_seconds</td></tr>
- <tr><td>synapse_storage_events_persisted_events_total</td><td>synapse_storage_events_persisted_events</td></tr>
- <tr><td>synapse_storage_events_persisted_events_sep_total</td><td>synapse_storage_events_persisted_events_sep</td></tr>
- <tr><td>synapse_storage_events_state_delta_total</td><td>synapse_storage_events_state_delta</td></tr>
- <tr><td>synapse_storage_events_state_delta_single_event_total</td><td>synapse_storage_events_state_delta_single_event</td></tr>
- <tr><td>synapse_storage_events_state_delta_reuse_delta_total</td><td>synapse_storage_events_state_delta_reuse_delta</td></tr>
- <tr><td>synapse_federation_server_received_pdus_total</td><td>synapse_federation_server_received_pdus</td></tr>
- <tr><td>synapse_federation_server_received_edus_total</td><td>synapse_federation_server_received_edus</td></tr>
- <tr><td>synapse_handler_presence_notified_presence_total</td><td>synapse_handler_presence_notified_presence</td></tr>
- <tr><td>synapse_handler_presence_federation_presence_out_total</td><td>synapse_handler_presence_federation_presence_out</td></tr>
- <tr><td>synapse_handler_presence_presence_updates_total</td><td>synapse_handler_presence_presence_updates</td></tr>
- <tr><td>synapse_handler_presence_timers_fired_total</td><td>synapse_handler_presence_timers_fired</td></tr>
- <tr><td>synapse_handler_presence_federation_presence_total</td><td>synapse_handler_presence_federation_presence</td></tr>
- <tr><td>synapse_handler_presence_bump_active_time_total</td><td>synapse_handler_presence_bump_active_time</td></tr>
- <tr><td>synapse_federation_client_sent_edus_total</td><td>synapse_federation_client_sent_edus</td></tr>
- <tr><td>synapse_federation_client_sent_pdu_destinations_count_total</td><td>synapse_federation_client_sent_pdu_destinations:count</td></tr>
- <tr><td>synapse_federation_client_sent_pdu_destinations_total</td><td>synapse_federation_client_sent_pdu_destinations:total</td></tr>
- <tr><td>synapse_handlers_appservice_events_processed_total</td><td>synapse_handlers_appservice_events_processed</td></tr>
- <tr><td>synapse_notifier_notified_events_total</td><td>synapse_notifier_notified_events</td></tr>
- <tr><td>synapse_push_bulk_push_rule_evaluator_push_rules_invalidation_counter_total</td><td>synapse_push_bulk_push_rule_evaluator_push_rules_invalidation_counter</td></tr>
- <tr><td>synapse_push_bulk_push_rule_evaluator_push_rules_state_size_counter_total</td><td>synapse_push_bulk_push_rule_evaluator_push_rules_state_size_counter</td></tr>
- <tr><td>synapse_http_httppusher_http_pushes_processed_total</td><td>synapse_http_httppusher_http_pushes_processed</td></tr>
- <tr><td>synapse_http_httppusher_http_pushes_failed_total</td><td>synapse_http_httppusher_http_pushes_failed</td></tr>
- <tr><td>synapse_http_httppusher_badge_updates_processed_total</td><td>synapse_http_httppusher_badge_updates_processed</td></tr>
- <tr><td>synapse_http_httppusher_badge_updates_failed_total</td><td>synapse_http_httppusher_badge_updates_failed</td></tr>
- </tbody></table>
- <h2 id="removal-of-deprecated-metrics--time-based-counters-becoming-histograms-in-0310"><a class="header" href="#removal-of-deprecated-metrics--time-based-counters-becoming-histograms-in-0310">Removal of deprecated metrics & time based counters becoming histograms in 0.31.0</a></h2>
- <p>The duplicated metrics deprecated in Synapse 0.27.0 have been removed.</p>
- <p>All time duration-based metrics have been changed to be seconds. This
- affects:</p>
- <table><thead><tr><th>msec -> sec metrics</th></tr></thead><tbody>
- <tr><td>python_gc_time</td></tr>
- <tr><td>python_twisted_reactor_tick_time</td></tr>
- <tr><td>synapse_storage_query_time</td></tr>
- <tr><td>synapse_storage_schedule_time</td></tr>
- <tr><td>synapse_storage_transaction_time</td></tr>
- </tbody></table>
- <p>Several metrics have been changed to be histograms, which sort entries
- into buckets and allow better analysis. The following metrics are now
- histograms:</p>
- <table><thead><tr><th>Altered metrics</th></tr></thead><tbody>
- <tr><td>python_gc_time</td></tr>
- <tr><td>python_twisted_reactor_pending_calls</td></tr>
- <tr><td>python_twisted_reactor_tick_time</td></tr>
- <tr><td>synapse_http_server_response_time_seconds</td></tr>
- <tr><td>synapse_storage_query_time</td></tr>
- <tr><td>synapse_storage_schedule_time</td></tr>
- <tr><td>synapse_storage_transaction_time</td></tr>
- </tbody></table>
- <h2 id="block-and-response-metrics-renamed-for-0270"><a class="header" href="#block-and-response-metrics-renamed-for-0270">Block and response metrics renamed for 0.27.0</a></h2>
- <p>Synapse 0.27.0 begins the process of rationalising the duplicate
- <code>*:count</code> metrics reported for the resource tracking for code blocks and
- HTTP requests.</p>
- <p>At the same time, the corresponding <code>*:total</code> metrics are being renamed,
- as the <code>:total</code> suffix no longer makes sense in the absence of a
- corresponding <code>:count</code> metric.</p>
- <p>To enable a graceful migration path, this release just adds new names
- for the metrics being renamed. A future release will remove the old
- ones.</p>
- <p>The following table shows the new metrics, and the old metrics which
- they are replacing.</p>
- <table><thead><tr><th>New name</th><th>Old name</th></tr></thead><tbody>
- <tr><td>synapse_util_metrics_block_count</td><td>synapse_util_metrics_block_timer:count</td></tr>
- <tr><td>synapse_util_metrics_block_count</td><td>synapse_util_metrics_block_ru_utime:count</td></tr>
- <tr><td>synapse_util_metrics_block_count</td><td>synapse_util_metrics_block_ru_stime:count</td></tr>
- <tr><td>synapse_util_metrics_block_count</td><td>synapse_util_metrics_block_db_txn_count:count</td></tr>
- <tr><td>synapse_util_metrics_block_count</td><td>synapse_util_metrics_block_db_txn_duration:count</td></tr>
- <tr><td>synapse_util_metrics_block_time_seconds</td><td>synapse_util_metrics_block_timer:total</td></tr>
- <tr><td>synapse_util_metrics_block_ru_utime_seconds</td><td>synapse_util_metrics_block_ru_utime:total</td></tr>
- <tr><td>synapse_util_metrics_block_ru_stime_seconds</td><td>synapse_util_metrics_block_ru_stime:total</td></tr>
- <tr><td>synapse_util_metrics_block_db_txn_count</td><td>synapse_util_metrics_block_db_txn_count:total</td></tr>
- <tr><td>synapse_util_metrics_block_db_txn_duration_seconds</td><td>synapse_util_metrics_block_db_txn_duration:total</td></tr>
- <tr><td>synapse_http_server_response_count</td><td>synapse_http_server_requests</td></tr>
- <tr><td>synapse_http_server_response_count</td><td>synapse_http_server_response_time:count</td></tr>
- <tr><td>synapse_http_server_response_count</td><td>synapse_http_server_response_ru_utime:count</td></tr>
- <tr><td>synapse_http_server_response_count</td><td>synapse_http_server_response_ru_stime:count</td></tr>
- <tr><td>synapse_http_server_response_count</td><td>synapse_http_server_response_db_txn_count:count</td></tr>
- <tr><td>synapse_http_server_response_count</td><td>synapse_http_server_response_db_txn_duration:count</td></tr>
- <tr><td>synapse_http_server_response_time_seconds</td><td>synapse_http_server_response_time:total</td></tr>
- <tr><td>synapse_http_server_response_ru_utime_seconds</td><td>synapse_http_server_response_ru_utime:total</td></tr>
- <tr><td>synapse_http_server_response_ru_stime_seconds</td><td>synapse_http_server_response_ru_stime:total</td></tr>
- <tr><td>synapse_http_server_response_db_txn_count</td><td>synapse_http_server_response_db_txn_count:total</td></tr>
- <tr><td>synapse_http_server_response_db_txn_duration_seconds</td><td>synapse_http_server_response_db_txn_duration:total</td></tr>
- </tbody></table>
- <h2 id="standard-metric-names"><a class="header" href="#standard-metric-names">Standard Metric Names</a></h2>
- <p>As of synapse version 0.18.2, the format of the process-wide metrics has
- been changed to fit prometheus standard naming conventions. Additionally
- the units have been changed to seconds, from miliseconds.</p>
- <table><thead><tr><th>New name</th><th>Old name</th></tr></thead><tbody>
- <tr><td>process_cpu_user_seconds_total</td><td>process_resource_utime / 1000</td></tr>
- <tr><td>process_cpu_system_seconds_total</td><td>process_resource_stime / 1000</td></tr>
- <tr><td>process_open_fds (no 'type' label)</td><td>process_fds</td></tr>
- </tbody></table>
- <p>The python-specific counts of garbage collector performance have been
- renamed.</p>
- <table><thead><tr><th>New name</th><th>Old name</th></tr></thead><tbody>
- <tr><td>python_gc_time</td><td>reactor_gc_time</td></tr>
- <tr><td>python_gc_unreachable_total</td><td>reactor_gc_unreachable</td></tr>
- <tr><td>python_gc_counts</td><td>reactor_gc_counts</td></tr>
- </tbody></table>
- <p>The twisted-specific reactor metrics have been renamed.</p>
- <table><thead><tr><th>New name</th><th>Old name</th></tr></thead><tbody>
- <tr><td>python_twisted_reactor_pending_calls</td><td>reactor_pending_calls</td></tr>
- <tr><td>python_twisted_reactor_tick_time</td><td>reactor_tick_time</td></tr>
- </tbody></table>
- <div style="break-before: page; page-break-before: always;"></div><h1 id="request-log-format"><a class="header" href="#request-log-format">Request log format</a></h1>
- <p>HTTP request logs are written by synapse (see <a href="usage/administration/../synapse/http/site.py"><code>site.py</code></a> for details).</p>
- <p>See the following for how to decode the dense data available from the default logging configuration.</p>
- <pre><code>2020-10-01 12:00:00,000 - synapse.access.http.8008 - 311 - INFO - PUT-1000- 192.168.0.1 - 8008 - {another-matrix-server.com} Processed request: 0.100sec/-0.000sec (0.000sec, 0.000sec) (0.001sec/0.090sec/3) 11B !200 "PUT /_matrix/federation/v1/send/1600000000000 HTTP/1.1" "Synapse/1.20.1" [0 dbevts]
- -AAAAAAAAAAAAAAAAAAAAA- -BBBBBBBBBBBBBBBBBBBBBB- -C- -DD- -EEEEEE- -FFFFFFFFF- -GG- -HHHHHHHHHHHHHHHHHHHHHHH- -IIIIII- -JJJJJJJ- -KKKKKK-, -LLLLLL- -MMMMMMM- -NNNNNN- O -P- -QQ- -RRRRRRRRRRRRRRRRRRRRRRRRRRRRRRRRRRRRRRRRRRRRRRRRRRRR- -SSSSSSSSSSSS- -TTTTTT-
- </code></pre>
- <table><thead><tr><th>Part</th><th>Explanation</th></tr></thead><tbody>
- <tr><td>AAAA</td><td>Timestamp request was logged (not recieved)</td></tr>
- <tr><td>BBBB</td><td>Logger name (<code>synapse.access.(http\|https).<tag></code>, where 'tag' is defined in the <code>listeners</code> config section, normally the port)</td></tr>
- <tr><td>CCCC</td><td>Line number in code</td></tr>
- <tr><td>DDDD</td><td>Log Level</td></tr>
- <tr><td>EEEE</td><td>Request Identifier (This identifier is shared by related log lines)</td></tr>
- <tr><td>FFFF</td><td>Source IP (Or X-Forwarded-For if enabled)</td></tr>
- <tr><td>GGGG</td><td>Server Port</td></tr>
- <tr><td>HHHH</td><td>Federated Server or Local User making request (blank if unauthenticated or not supplied)</td></tr>
- <tr><td>IIII</td><td>Total Time to process the request</td></tr>
- <tr><td>JJJJ</td><td>Time to send response over network once generated (this may be negative if the socket is closed before the response is generated)</td></tr>
- <tr><td>KKKK</td><td>Userland CPU time</td></tr>
- <tr><td>LLLL</td><td>System CPU time</td></tr>
- <tr><td>MMMM</td><td>Total time waiting for a free DB connection from the pool across all parallel DB work from this request</td></tr>
- <tr><td>NNNN</td><td>Total time waiting for response to DB queries across all parallel DB work from this request</td></tr>
- <tr><td>OOOO</td><td>Count of DB transactions performed</td></tr>
- <tr><td>PPPP</td><td>Response body size</td></tr>
- <tr><td>QQQQ</td><td>Response status code (prefixed with ! if the socket was closed before the response was generated)</td></tr>
- <tr><td>RRRR</td><td>Request</td></tr>
- <tr><td>SSSS</td><td>User-agent</td></tr>
- <tr><td>TTTT</td><td>Events fetched from DB to service this request (note that this does not include events fetched from the cache)</td></tr>
- </tbody></table>
- <p>MMMM / NNNN can be greater than IIII if there are multiple slow database queries
- running in parallel.</p>
- <p>Some actions can result in multiple identical http requests, which will return
- the same data, but only the first request will report time/transactions in
- <code>KKKK</code>/<code>LLLL</code>/<code>MMMM</code>/<code>NNNN</code>/<code>OOOO</code> - the others will be awaiting the first query to return a
- response and will simultaneously return with the first request, but with very
- small processing times.</p>
- <div style="break-before: page; page-break-before: always;"></div><!--
- Include the contents of CONTRIBUTING.md from the project root (where GitHub likes it
- to be)
- -->
- <h1 id="contributing"><a class="header" href="#contributing">Contributing</a></h1>
- <p>Welcome to Synapse</p>
- <p>This document aims to get you started with contributing to this repo! </p>
- <ul>
- <li><a href="development/contributing_guide.html#1-who-can-contribute-to-synapse">1. Who can contribute to Synapse?</a></li>
- <li><a href="development/contributing_guide.html#2-what-do-i-need">2. What do I need?</a></li>
- <li><a href="development/contributing_guide.html#3-get-the-source">3. Get the source.</a></li>
- <li><a href="development/contributing_guide.html#4-install-the-dependencies">4. Install the dependencies</a>
- <ul>
- <li><a href="development/contributing_guide.html#under-unix-macos-linux-bsd-">Under Unix (macOS, Linux, BSD, ...)</a></li>
- <li><a href="development/contributing_guide.html#under-windows">Under Windows</a></li>
- </ul>
- </li>
- <li><a href="development/contributing_guide.html#5-get-in-touch">5. Get in touch.</a></li>
- <li><a href="development/contributing_guide.html#6-pick-an-issue">6. Pick an issue.</a></li>
- <li><a href="development/contributing_guide.html#7-turn-coffee-and-documentation-into-code-and-documentation">7. Turn coffee and documentation into code and documentation!</a></li>
- <li><a href="development/contributing_guide.html#8-test-test-test">8. Test, test, test!</a>
- <ul>
- <li><a href="development/contributing_guide.html#run-the-linters">Run the linters.</a></li>
- <li><a href="development/contributing_guide.html#run-the-unit-tests">Run the unit tests.</a></li>
- <li><a href="development/contributing_guide.html#run-the-integration-tests">Run the integration tests.</a></li>
- </ul>
- </li>
- <li><a href="development/contributing_guide.html#9-submit-your-patch">9. Submit your patch.</a>
- <ul>
- <li><a href="development/contributing_guide.html#changelog">Changelog</a>
- <ul>
- <li><a href="development/contributing_guide.html#how-do-i-know-what-to-call-the-changelog-file-before-i-create-the-pr">How do I know what to call the changelog file before I create the PR?</a></li>
- <li><a href="development/contributing_guide.html#debian-changelog">Debian changelog</a></li>
- </ul>
- </li>
- <li><a href="development/contributing_guide.html#sign-off">Sign off</a></li>
- </ul>
- </li>
- <li><a href="development/contributing_guide.html#10-turn-feedback-into-better-code">10. Turn feedback into better code.</a></li>
- <li><a href="development/contributing_guide.html#11-find-a-new-issue">11. Find a new issue.</a></li>
- <li><a href="development/contributing_guide.html#notes-for-maintainers-on-merging-prs-etc">Notes for maintainers on merging PRs etc</a></li>
- <li><a href="development/contributing_guide.html#conclusion">Conclusion</a></li>
- </ul>
- <h1 id="1-who-can-contribute-to-synapse"><a class="header" href="#1-who-can-contribute-to-synapse">1. Who can contribute to Synapse?</a></h1>
- <p>Everyone is welcome to contribute code to <a href="https://github.com/matrix-org">matrix.org
- projects</a>, provided that they are willing to
- license their contributions under the same license as the project itself. We
- follow a simple 'inbound=outbound' model for contributions: the act of
- submitting an 'inbound' contribution means that the contributor agrees to
- license the code under the same terms as the project's overall 'outbound'
- license - in our case, this is almost always Apache Software License v2 (see
- <a href="development/LICENSE">LICENSE</a>).</p>
- <h1 id="2-what-do-i-need"><a class="header" href="#2-what-do-i-need">2. What do I need?</a></h1>
- <p>The code of Synapse is written in Python 3. To do pretty much anything, you'll need <a href="https://wiki.python.org/moin/BeginnersGuide/Download">a recent version of Python 3</a>.</p>
- <p>The source code of Synapse is hosted on GitHub. You will also need <a href="https://github.com/git-guides/install-git">a recent version of git</a>.</p>
- <p>For some tests, you will need <a href="https://docs.docker.com/get-docker/">a recent version of Docker</a>.</p>
- <h1 id="3-get-the-source"><a class="header" href="#3-get-the-source">3. Get the source.</a></h1>
- <p>The preferred and easiest way to contribute changes is to fork the relevant
- project on GitHub, and then <a href="https://help.github.com/articles/using-pull-requests/">create a pull request</a> to ask us to pull your
- changes into our repo.</p>
- <p>Please base your changes on the <code>develop</code> branch.</p>
- <pre><code class="language-sh">git clone git@github.com:YOUR_GITHUB_USER_NAME/synapse.git
- git checkout develop
- </code></pre>
- <p>If you need help getting started with git, this is beyond the scope of the document, but you
- can find many good git tutorials on the web.</p>
- <h1 id="4-install-the-dependencies"><a class="header" href="#4-install-the-dependencies">4. Install the dependencies</a></h1>
- <h2 id="under-unix-macos-linux-bsd-"><a class="header" href="#under-unix-macos-linux-bsd-">Under Unix (macOS, Linux, BSD, ...)</a></h2>
- <p>Once you have installed Python 3 and added the source, please open a terminal and
- setup a <em>virtualenv</em>, as follows:</p>
- <pre><code class="language-sh">cd path/where/you/have/cloned/the/repository
- python3 -m venv ./env
- source ./env/bin/activate
- pip install -e ".[all,lint,mypy,test]"
- pip install tox
- </code></pre>
- <p>This will install the developer dependencies for the project.</p>
- <h2 id="under-windows"><a class="header" href="#under-windows">Under Windows</a></h2>
- <p>TBD</p>
- <h1 id="5-get-in-touch"><a class="header" href="#5-get-in-touch">5. Get in touch.</a></h1>
- <p>Join our developer community on Matrix: #synapse-dev:matrix.org !</p>
- <h1 id="6-pick-an-issue"><a class="header" href="#6-pick-an-issue">6. Pick an issue.</a></h1>
- <p>Fix your favorite problem or perhaps find a <a href="https://github.com/matrix-org/synapse/issues?q=is%3Aopen+is%3Aissue+label%3A%22Good+First+Issue%22">Good First Issue</a>
- to work on.</p>
- <h1 id="7-turn-coffee-and-documentation-into-code-and-documentation"><a class="header" href="#7-turn-coffee-and-documentation-into-code-and-documentation">7. Turn coffee and documentation into code and documentation!</a></h1>
- <p>Synapse's code style is documented <a href="development/docs/code_style.html">here</a>. Please follow
- it, including the conventions for the <a href="development/docs/code_style.html#configuration-file-format">sample configuration
- file</a>.</p>
- <p>There is a growing amount of documentation located in the <a href="development/docs">docs</a>
- directory. This documentation is intended primarily for sysadmins running their
- own Synapse instance, as well as developers interacting externally with
- Synapse. <a href="development/docs/dev">docs/dev</a> exists primarily to house documentation for
- Synapse developers. <a href="development/docs/admin_api">docs/admin_api</a> houses documentation
- regarding Synapse's Admin API, which is used mostly by sysadmins and external
- service developers.</p>
- <p>If you add new files added to either of these folders, please use <a href="https://guides.github.com/features/mastering-markdown/">GitHub-Flavoured
- Markdown</a>.</p>
- <p>Some documentation also exists in <a href="https://github.com/matrix-org/synapse/wiki">Synapse's GitHub
- Wiki</a>, although this is primarily
- contributed to by community authors.</p>
- <h1 id="8-test-test-test"><a class="header" href="#8-test-test-test">8. Test, test, test!</a></h1>
- <p><a name="test-test-test"></a></p>
- <p>While you're developing and before submitting a patch, you'll
- want to test your code.</p>
- <h2 id="run-the-linters"><a class="header" href="#run-the-linters">Run the linters.</a></h2>
- <p>The linters look at your code and do two things:</p>
- <ul>
- <li>ensure that your code follows the coding style adopted by the project;</li>
- <li>catch a number of errors in your code.</li>
- </ul>
- <p>They're pretty fast, don't hesitate!</p>
- <pre><code class="language-sh">source ./env/bin/activate
- ./scripts-dev/lint.sh
- </code></pre>
- <p>Note that this script <em>will modify your files</em> to fix styling errors.
- Make sure that you have saved all your files.</p>
- <p>If you wish to restrict the linters to only the files changed since the last commit
- (much faster!), you can instead run:</p>
- <pre><code class="language-sh">source ./env/bin/activate
- ./scripts-dev/lint.sh -d
- </code></pre>
- <p>Or if you know exactly which files you wish to lint, you can instead run:</p>
- <pre><code class="language-sh">source ./env/bin/activate
- ./scripts-dev/lint.sh path/to/file1.py path/to/file2.py path/to/folder
- </code></pre>
- <h2 id="run-the-unit-tests"><a class="header" href="#run-the-unit-tests">Run the unit tests.</a></h2>
- <p>The unit tests run parts of Synapse, including your changes, to see if anything
- was broken. They are slower than the linters but will typically catch more errors.</p>
- <pre><code class="language-sh">source ./env/bin/activate
- trial tests
- </code></pre>
- <p>If you wish to only run <em>some</em> unit tests, you may specify
- another module instead of <code>tests</code> - or a test class or a method:</p>
- <pre><code class="language-sh">source ./env/bin/activate
- trial tests.rest.admin.test_room tests.handlers.test_admin.ExfiltrateData.test_invite
- </code></pre>
- <p>If your tests fail, you may wish to look at the logs (the default log level is <code>ERROR</code>):</p>
- <pre><code class="language-sh">less _trial_temp/test.log
- </code></pre>
- <p>To increase the log level for the tests, set <code>SYNAPSE_TEST_LOG_LEVEL</code>:</p>
- <pre><code class="language-sh">SYNAPSE_TEST_LOG_LEVEL=DEBUG trial tests
- </code></pre>
- <h2 id="run-the-integration-tests"><a class="header" href="#run-the-integration-tests">Run the integration tests.</a></h2>
- <p>The integration tests are a more comprehensive suite of tests. They
- run a full version of Synapse, including your changes, to check if
- anything was broken. They are slower than the unit tests but will
- typically catch more errors.</p>
- <p>The following command will let you run the integration test with the most common
- configuration:</p>
- <pre><code class="language-sh">$ docker run --rm -it -v /path/where/you/have/cloned/the/repository\:/src:ro -v /path/to/where/you/want/logs\:/logs matrixdotorg/sytest-synapse:py37
- </code></pre>
- <p>This configuration should generally cover your needs. For more details about other configurations, see <a href="https://github.com/matrix-org/sytest/blob/develop/docker/README.md">documentation in the SyTest repo</a>.</p>
- <h1 id="9-submit-your-patch"><a class="header" href="#9-submit-your-patch">9. Submit your patch.</a></h1>
- <p>Once you're happy with your patch, it's time to prepare a Pull Request.</p>
- <p>To prepare a Pull Request, please:</p>
- <ol>
- <li>verify that <a href="development/contributing_guide.html#test-test-test">all the tests pass</a>, including the coding style;</li>
- <li><a href="development/contributing_guide.html#sign-off">sign off</a> your contribution;</li>
- <li><code>git push</code> your commit to your fork of Synapse;</li>
- <li>on GitHub, <a href="https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/creating-a-pull-request">create the Pull Request</a>;</li>
- <li>add a <a href="development/contributing_guide.html#changelog">changelog entry</a> and push it to your Pull Request;</li>
- <li>for most contributors, that's all - however, if you are a member of the organization <code>matrix-org</code>, on GitHub, please request a review from <code>matrix.org / Synapse Core</code>.</li>
- </ol>
- <h2 id="changelog"><a class="header" href="#changelog">Changelog</a></h2>
- <p>All changes, even minor ones, need a corresponding changelog / newsfragment
- entry. These are managed by <a href="https://github.com/hawkowl/towncrier">Towncrier</a>.</p>
- <p>To create a changelog entry, make a new file in the <code>changelog.d</code> directory named
- in the format of <code>PRnumber.type</code>. The type can be one of the following:</p>
- <ul>
- <li><code>feature</code></li>
- <li><code>bugfix</code></li>
- <li><code>docker</code> (for updates to the Docker image)</li>
- <li><code>doc</code> (for updates to the documentation)</li>
- <li><code>removal</code> (also used for deprecations)</li>
- <li><code>misc</code> (for internal-only changes)</li>
- </ul>
- <p>This file will become part of our <a href="https://github.com/matrix-org/synapse/blob/master/CHANGES.md">changelog</a> at the next
- release, so the content of the file should be a short description of your
- change in the same style as the rest of the changelog. The file can contain Markdown
- formatting, and should end with a full stop (.) or an exclamation mark (!) for
- consistency.</p>
- <p>Adding credits to the changelog is encouraged, we value your
- contributions and would like to have you shouted out in the release notes!</p>
- <p>For example, a fix in PR #1234 would have its changelog entry in
- <code>changelog.d/1234.bugfix</code>, and contain content like:</p>
- <blockquote>
- <p>The security levels of Florbs are now validated when received
- via the <code>/federation/florb</code> endpoint. Contributed by Jane Matrix.</p>
- </blockquote>
- <p>If there are multiple pull requests involved in a single bugfix/feature/etc,
- then the content for each <code>changelog.d</code> file should be the same. Towncrier will
- merge the matching files together into a single changelog entry when we come to
- release.</p>
- <h3 id="how-do-i-know-what-to-call-the-changelog-file-before-i-create-the-pr"><a class="header" href="#how-do-i-know-what-to-call-the-changelog-file-before-i-create-the-pr">How do I know what to call the changelog file before I create the PR?</a></h3>
- <p>Obviously, you don't know if you should call your newsfile
- <code>1234.bugfix</code> or <code>5678.bugfix</code> until you create the PR, which leads to a
- chicken-and-egg problem.</p>
- <p>There are two options for solving this:</p>
- <ol>
- <li>
- <p>Open the PR without a changelog file, see what number you got, and <em>then</em>
- add the changelog file to your branch (see <a href="development/contributing_guide.html#updating-your-pull-request">Updating your pull
- request</a>), or:</p>
- </li>
- <li>
- <p>Look at the <a href="https://github.com/matrix-org/synapse/issues?q=">list of all
- issues/PRs</a>, add one to the
- highest number you see, and quickly open the PR before somebody else claims
- your number.</p>
- <p><a href="https://github.com/richvdh/scripts/blob/master/next_github_number.sh">This
- script</a>
- might be helpful if you find yourself doing this a lot.</p>
- </li>
- </ol>
- <p>Sorry, we know it's a bit fiddly, but it's <em>really</em> helpful for us when we come
- to put together a release!</p>
- <h3 id="debian-changelog"><a class="header" href="#debian-changelog">Debian changelog</a></h3>
- <p>Changes which affect the debian packaging files (in <code>debian</code>) are an
- exception to the rule that all changes require a <code>changelog.d</code> file.</p>
- <p>In this case, you will need to add an entry to the debian changelog for the
- next release. For this, run the following command:</p>
- <pre><code>dch
- </code></pre>
- <p>This will make up a new version number (if there isn't already an unreleased
- version in flight), and open an editor where you can add a new changelog entry.
- (Our release process will ensure that the version number and maintainer name is
- corrected for the release.)</p>
- <p>If your change affects both the debian packaging <em>and</em> files outside the debian
- directory, you will need both a regular newsfragment <em>and</em> an entry in the
- debian changelog. (Though typically such changes should be submitted as two
- separate pull requests.)</p>
- <h2 id="sign-off"><a class="header" href="#sign-off">Sign off</a></h2>
- <p>In order to have a concrete record that your contribution is intentional
- and you agree to license it under the same terms as the project's license, we've adopted the
- same lightweight approach that the Linux Kernel
- <a href="https://www.kernel.org/doc/html/latest/process/submitting-patches.html#sign-your-work-the-developer-s-certificate-of-origin%3E">submitting patches process</a>,
- <a href="https://github.com/docker/docker/blob/master/CONTRIBUTING.md">Docker</a>, and many other
- projects use: the DCO (Developer Certificate of Origin:
- http://developercertificate.org/). This is a simple declaration that you wrote
- the contribution or otherwise have the right to contribute it to Matrix:</p>
- <pre><code>Developer Certificate of Origin
- Version 1.1
- Copyright (C) 2004, 2006 The Linux Foundation and its contributors.
- 660 York Street, Suite 102,
- San Francisco, CA 94110 USA
- Everyone is permitted to copy and distribute verbatim copies of this
- license document, but changing it is not allowed.
- Developer's Certificate of Origin 1.1
- By making a contribution to this project, I certify that:
- (a) The contribution was created in whole or in part by me and I
- have the right to submit it under the open source license
- indicated in the file; or
- (b) The contribution is based upon previous work that, to the best
- of my knowledge, is covered under an appropriate open source
- license and I have the right under that license to submit that
- work with modifications, whether created in whole or in part
- by me, under the same open source license (unless I am
- permitted to submit under a different license), as indicated
- in the file; or
- (c) The contribution was provided directly to me by some other
- person who certified (a), (b) or (c) and I have not modified
- it.
- (d) I understand and agree that this project and the contribution
- are public and that a record of the contribution (including all
- personal information I submit with it, including my sign-off) is
- maintained indefinitely and may be redistributed consistent with
- this project or the open source license(s) involved.
- </code></pre>
- <p>If you agree to this for your contribution, then all that's needed is to
- include the line in your commit or pull request comment:</p>
- <pre><code>Signed-off-by: Your Name <your@email.example.org>
- </code></pre>
- <p>We accept contributions under a legally identifiable name, such as
- your name on government documentation or common-law names (names
- claimed by legitimate usage or repute). Unfortunately, we cannot
- accept anonymous contributions at this time.</p>
- <p>Git allows you to add this signoff automatically when using the <code>-s</code>
- flag to <code>git commit</code>, which uses the name and email set in your
- <code>user.name</code> and <code>user.email</code> git configs.</p>
- <h1 id="10-turn-feedback-into-better-code"><a class="header" href="#10-turn-feedback-into-better-code">10. Turn feedback into better code.</a></h1>
- <p>Once the Pull Request is opened, you will see a few things:</p>
- <ol>
- <li>our automated CI (Continuous Integration) pipeline will run (again) the linters, the unit tests, the integration tests and more;</li>
- <li>one or more of the developers will take a look at your Pull Request and offer feedback.</li>
- </ol>
- <p>From this point, you should:</p>
- <ol>
- <li>Look at the results of the CI pipeline.
- <ul>
- <li>If there is any error, fix the error.</li>
- </ul>
- </li>
- <li>If a developer has requested changes, make these changes and let us know if it is ready for a developer to review again.</li>
- <li>Create a new commit with the changes.
- <ul>
- <li>Please do NOT overwrite the history. New commits make the reviewer's life easier.</li>
- <li>Push this commits to your Pull Request.</li>
- </ul>
- </li>
- <li>Back to 1.</li>
- </ol>
- <p>Once both the CI and the developers are happy, the patch will be merged into Synapse and released shortly!</p>
- <h1 id="11-find-a-new-issue"><a class="header" href="#11-find-a-new-issue">11. Find a new issue.</a></h1>
- <p>By now, you know the drill!</p>
- <h1 id="notes-for-maintainers-on-merging-prs-etc"><a class="header" href="#notes-for-maintainers-on-merging-prs-etc">Notes for maintainers on merging PRs etc</a></h1>
- <p>There are some notes for those with commit access to the project on how we
- manage git <a href="development/docs/dev/git.html">here</a>.</p>
- <h1 id="conclusion"><a class="header" href="#conclusion">Conclusion</a></h1>
- <p>That's it! Matrix is a very open and collaborative project as you might expect
- given our obsession with open communication. If we're going to successfully
- matrix together all the fragmented communication technologies out there we are
- reliant on contributions and collaboration from the community to do so. So
- please get involved - and we hope you have as much fun hacking on Matrix as we
- do!</p>
- <div style="break-before: page; page-break-before: always;"></div><h1 id="code-style"><a class="header" href="#code-style">Code Style</a></h1>
- <h2 id="formatting-tools"><a class="header" href="#formatting-tools">Formatting tools</a></h2>
- <p>The Synapse codebase uses a number of code formatting tools in order to
- quickly and automatically check for formatting (and sometimes logical)
- errors in code.</p>
- <p>The necessary tools are detailed below.</p>
- <p>First install them with:</p>
- <pre><code>pip install -e ".[lint,mypy]"
- </code></pre>
- <ul>
- <li>
- <p><strong>black</strong></p>
- <p>The Synapse codebase uses <a href="https://pypi.org/project/black/">black</a>
- as an opinionated code formatter, ensuring all comitted code is
- properly formatted.</p>
- <p>Have <code>black</code> auto-format your code (it shouldn't change any
- functionality) with:</p>
- <pre><code>black . --exclude="\.tox|build|env"
- </code></pre>
- </li>
- <li>
- <p><strong>flake8</strong></p>
- <p><code>flake8</code> is a code checking tool. We require code to pass <code>flake8</code>
- before being merged into the codebase.</p>
- <p>Check all application and test code with:</p>
- <pre><code>flake8 synapse tests
- </code></pre>
- </li>
- <li>
- <p><strong>isort</strong></p>
- <p><code>isort</code> ensures imports are nicely formatted, and can suggest and
- auto-fix issues such as double-importing.</p>
- <p>Auto-fix imports with:</p>
- <pre><code>isort -rc synapse tests
- </code></pre>
- <p><code>-rc</code> means to recursively search the given directories.</p>
- </li>
- </ul>
- <p>It's worth noting that modern IDEs and text editors can run these tools
- automatically on save. It may be worth looking into whether this
- functionality is supported in your editor for a more convenient
- development workflow. It is not, however, recommended to run <code>flake8</code> on
- save as it takes a while and is very resource intensive.</p>
- <h2 id="general-rules"><a class="header" href="#general-rules">General rules</a></h2>
- <ul>
- <li><strong>Naming</strong>:
- <ul>
- <li>Use camel case for class and type names</li>
- <li>Use underscores for functions and variables.</li>
- </ul>
- </li>
- <li><strong>Docstrings</strong>: should follow the <a href="https://google.github.io/styleguide/pyguide.html#38-comments-and-docstrings">google code
- style</a>.
- See the
- <a href="http://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.html">examples</a>
- in the sphinx documentation.</li>
- <li><strong>Imports</strong>:
- <ul>
- <li>
- <p>Imports should be sorted by <code>isort</code> as described above.</p>
- </li>
- <li>
- <p>Prefer to import classes and functions rather than packages or
- modules.</p>
- <p>Example:</p>
- <pre><code>from synapse.types import UserID
- ...
- user_id = UserID(local, server)
- </code></pre>
- <p>is preferred over:</p>
- <pre><code>from synapse import types
- ...
- user_id = types.UserID(local, server)
- </code></pre>
- <p>(or any other variant).</p>
- <p>This goes against the advice in the Google style guide, but it
- means that errors in the name are caught early (at import time).</p>
- </li>
- <li>
- <p>Avoid wildcard imports (<code>from synapse.types import *</code>) and
- relative imports (<code>from .types import UserID</code>).</p>
- </li>
- </ul>
- </li>
- </ul>
- <h2 id="configuration-file-format"><a class="header" href="#configuration-file-format">Configuration file format</a></h2>
- <p>The <a href="./sample_config.yaml">sample configuration file</a> acts as a
- reference to Synapse's configuration options for server administrators.
- Remember that many readers will be unfamiliar with YAML and server
- administration in general, so that it is important that the file be as
- easy to understand as possible, which includes following a consistent
- format.</p>
- <p>Some guidelines follow:</p>
- <ul>
- <li>
- <p>Sections should be separated with a heading consisting of a single
- line prefixed and suffixed with <code>##</code>. There should be <strong>two</strong> blank
- lines before the section header, and <strong>one</strong> after.</p>
- </li>
- <li>
- <p>Each option should be listed in the file with the following format:</p>
- <ul>
- <li>
- <p>A comment describing the setting. Each line of this comment
- should be prefixed with a hash (<code>#</code>) and a space.</p>
- <p>The comment should describe the default behaviour (ie, what
- happens if the setting is omitted), as well as what the effect
- will be if the setting is changed.</p>
- <p>Often, the comment end with something like "uncomment the
- following to <do action>".</p>
- </li>
- <li>
- <p>A line consisting of only <code>#</code>.</p>
- </li>
- <li>
- <p>A commented-out example setting, prefixed with only <code>#</code>.</p>
- <p>For boolean (on/off) options, convention is that this example
- should be the <em>opposite</em> to the default (so the comment will end
- with "Uncomment the following to enable [or disable]
- <feature>." For other options, the example should give some
- non-default value which is likely to be useful to the reader.</p>
- </li>
- </ul>
- </li>
- <li>
- <p>There should be a blank line between each option.</p>
- </li>
- <li>
- <p>Where several settings are grouped into a single dict, <em>avoid</em> the
- convention where the whole block is commented out, resulting in
- comment lines starting <code># #</code>, as this is hard to read and confusing
- to edit. Instead, leave the top-level config option uncommented, and
- follow the conventions above for sub-options. Ensure that your code
- correctly handles the top-level option being set to <code>None</code> (as it
- will be if no sub-options are enabled).</p>
- </li>
- <li>
- <p>Lines should be wrapped at 80 characters.</p>
- </li>
- <li>
- <p>Use two-space indents.</p>
- </li>
- <li>
- <p><code>true</code> and <code>false</code> are spelt thus (as opposed to <code>True</code>, etc.)</p>
- </li>
- <li>
- <p>Use single quotes (<code>'</code>) rather than double-quotes (<code>"</code>) or backticks
- (<code>`</code>) to refer to configuration options.</p>
- </li>
- </ul>
- <p>Example:</p>
- <pre><code>## Frobnication ##
- # The frobnicator will ensure that all requests are fully frobnicated.
- # To enable it, uncomment the following.
- #
- #frobnicator_enabled: true
- # By default, the frobnicator will frobnicate with the default frobber.
- # The following will make it use an alternative frobber.
- #
- #frobincator_frobber: special_frobber
- # Settings for the frobber
- #
- frobber:
- # frobbing speed. Defaults to 1.
- #
- #speed: 10
- # frobbing distance. Defaults to 1000.
- #
- #distance: 100
- </code></pre>
- <p>Note that the sample configuration is generated from the synapse code
- and is maintained by a script, <code>scripts-dev/generate_sample_config</code>.
- Making sure that the output from this script matches the desired format
- is left as an exercise for the reader!</p>
- <div style="break-before: page; page-break-before: always;"></div><h1 id="some-notes-on-how-we-use-git"><a class="header" href="#some-notes-on-how-we-use-git">Some notes on how we use git</a></h1>
- <h2 id="on-keeping-the-commit-history-clean"><a class="header" href="#on-keeping-the-commit-history-clean">On keeping the commit history clean</a></h2>
- <p>In an ideal world, our git commit history would be a linear progression of
- commits each of which contains a single change building on what came
- before. Here, by way of an arbitrary example, is the top of <code>git log --graph b2dba0607</code>:</p>
- <img src="dev/git/clean.png" alt="clean git graph" width="500px">
- <p>Note how the commit comment explains clearly what is changing and why. Also
- note the <em>absence</em> of merge commits, as well as the absence of commits called
- things like (to pick a few culprits):
- <a href="https://github.com/matrix-org/synapse/commit/84691da6c">“pep8”</a>, <a href="https://github.com/matrix-org/synapse/commit/474810d9d">“fix broken
- test”</a>,
- <a href="https://github.com/matrix-org/synapse/commit/c9d72e457">“oops”</a>,
- <a href="https://github.com/matrix-org/synapse/commit/836358823">“typo”</a>, or <a href="https://github.com/matrix-org/synapse/commit/707374d5d">“Who's
- the president?”</a>.</p>
- <p>There are a number of reasons why keeping a clean commit history is a good
- thing:</p>
- <ul>
- <li>
- <p>From time to time, after a change lands, it turns out to be necessary to
- revert it, or to backport it to a release branch. Those operations are
- <em>much</em> easier when the change is contained in a single commit.</p>
- </li>
- <li>
- <p>Similarly, it's much easier to answer questions like “is the fix for
- <code>/publicRooms</code> on the release branch?” if that change consists of a single
- commit.</p>
- </li>
- <li>
- <p>Likewise: “what has changed on this branch in the last week?” is much
- clearer without merges and “pep8” commits everywhere.</p>
- </li>
- <li>
- <p>Sometimes we need to figure out where a bug got introduced, or some
- behaviour changed. One way of doing that is with <code>git bisect</code>: pick an
- arbitrary commit between the known good point and the known bad point, and
- see how the code behaves. However, that strategy fails if the commit you
- chose is the middle of someone's epic branch in which they broke the world
- before putting it back together again.</p>
- </li>
- </ul>
- <p>One counterargument is that it is sometimes useful to see how a PR evolved as
- it went through review cycles. This is true, but that information is always
- available via the GitHub UI (or via the little-known <a href="https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/checking-out-pull-requests-locally">refs/pull
- namespace</a>).</p>
- <p>Of course, in reality, things are more complicated than that. We have release
- branches as well as <code>develop</code> and <code>master</code>, and we deliberately merge changes
- between them. Bugs often slip through and have to be fixed later. That's all
- fine: this not a cast-iron rule which must be obeyed, but an ideal to aim
- towards.</p>
- <h2 id="merges-squashes-rebases-wtf"><a class="header" href="#merges-squashes-rebases-wtf">Merges, squashes, rebases: wtf?</a></h2>
- <p>Ok, so that's what we'd like to achieve. How do we achieve it?</p>
- <p>The TL;DR is: when you come to merge a pull request, you <em>probably</em> want to
- “squash and merge”:</p>
- <p><img src="dev/git/squash.png" alt="squash and merge" />.</p>
- <p>(This applies whether you are merging your own PR, or that of another
- contributor.)</p>
- <p>“Squash and merge”<sup id="a1"><a href="dev/git.html#f1">1</a></sup> takes all of the changes in the
- PR, and bundles them into a single commit. GitHub gives you the opportunity to
- edit the commit message before you confirm, and normally you should do so,
- because the default will be useless (again: <code>* woops typo</code> is not a useful
- thing to keep in the historical record).</p>
- <p>The main problem with this approach comes when you have a series of pull
- requests which build on top of one another: as soon as you squash-merge the
- first PR, you'll end up with a stack of conflicts to resolve in all of the
- others. In general, it's best to avoid this situation in the first place by
- trying not to have multiple related PRs in flight at the same time. Still,
- sometimes that's not possible and doing a regular merge is the lesser evil.</p>
- <p>Another occasion in which a regular merge makes more sense is a PR where you've
- deliberately created a series of commits each of which makes sense in its own
- right. For example: <a href="https://github.com/matrix-org/synapse/pull/6837">a PR which gradually propagates a refactoring operation
- through the codebase</a>, or <a href="https://github.com/matrix-org/synapse/pull/5987">a
- PR which is the culmination of several other
- PRs</a>. In this case the ability
- to figure out when a particular change/bug was introduced could be very useful.</p>
- <p>Ultimately: <strong>this is not a hard-and-fast-rule</strong>. If in doubt, ask yourself “do
- each of the commits I am about to merge make sense in their own right”, but
- remember that we're just doing our best to balance “keeping the commit history
- clean” with other factors.</p>
- <h2 id="git-branching-model"><a class="header" href="#git-branching-model">Git branching model</a></h2>
- <p>A <a href="https://nvie.com/posts/a-successful-git-branching-model/">lot</a>
- <a href="http://scottchacon.com/2011/08/31/github-flow.html">of</a>
- <a href="https://www.endoflineblog.com/gitflow-considered-harmful">words</a> have been
- written in the past about git branching models (no really, <a href="https://martinfowler.com/articles/branching-patterns.html">a
- lot</a>). I tend to
- think the whole thing is overblown. Fundamentally, it's not that
- complicated. Here's how we do it.</p>
- <p>Let's start with a picture:</p>
- <p><img src="dev/git/branches.jpg" alt="branching model" /></p>
- <p>It looks complicated, but it's really not. There's one basic rule: <em>anyone</em> is
- free to merge from <em>any</em> more-stable branch to <em>any</em> less-stable branch at
- <em>any</em> time<sup id="a2"><a href="dev/git.html#f2">2</a></sup>. (The principle behind this is that if a
- change is good enough for the more-stable branch, then it's also good enough go
- put in a less-stable branch.)</p>
- <p>Meanwhile, merging (or squashing, as per the above) from a less-stable to a
- more-stable branch is a deliberate action in which you want to publish a change
- or a set of changes to (some subset of) the world: for example, this happens
- when a PR is landed, or as part of our release process.</p>
- <p>So, what counts as a more- or less-stable branch? A little reflection will show
- that our active branches are ordered thus, from more-stable to less-stable:</p>
- <ul>
- <li><code>master</code> (tracks our last release).</li>
- <li><code>release-vX.Y</code> (the branch where we prepare the next release)<sup
- id="a3"><a href="dev/git.html#f3">3</a></sup>.</li>
- <li>PR branches which are targeting the release.</li>
- <li><code>develop</code> (our "mainline" branch containing our bleeding-edge).</li>
- <li>regular PR branches.</li>
- </ul>
- <p>The corollary is: if you have a bugfix that needs to land in both
- <code>release-vX.Y</code> <em>and</em> <code>develop</code>, then you should base your PR on
- <code>release-vX.Y</code>, get it merged there, and then merge from <code>release-vX.Y</code> to
- <code>develop</code>. (If a fix lands in <code>develop</code> and we later need it in a
- release-branch, we can of course cherry-pick it, but landing it in the release
- branch first helps reduce the chance of annoying conflicts.)</p>
- <hr />
- <p><b id="f1">[1]</b>: “Squash and merge” is GitHub's term for this
- operation. Given that there is no merge involved, I'm not convinced it's the
- most intuitive name. <a href="dev/git.html#a1">^</a></p>
- <p><b id="f2">[2]</b>: Well, anyone with commit access.<a href="dev/git.html#a2">^</a></p>
- <p><b id="f3">[3]</b>: Very, very occasionally (I think this has happened once in
- the history of Synapse), we've had two releases in flight at once. Obviously,
- <code>release-v1.2</code> is more-stable than <code>release-v1.3</code>. <a href="dev/git.html#a3">^</a></p>
- <div style="break-before: page; page-break-before: always;"></div><h1 id="opentracing"><a class="header" href="#opentracing">OpenTracing</a></h1>
- <h2 id="background"><a class="header" href="#background">Background</a></h2>
- <p>OpenTracing is a semi-standard being adopted by a number of distributed
- tracing platforms. It is a common api for facilitating vendor-agnostic
- tracing instrumentation. That is, we can use the OpenTracing api and
- select one of a number of tracer implementations to do the heavy lifting
- in the background. Our current selected implementation is Jaeger.</p>
- <p>OpenTracing is a tool which gives an insight into the causal
- relationship of work done in and between servers. The servers each track
- events and report them to a centralised server - in Synapse's case:
- Jaeger. The basic unit used to represent events is the span. The span
- roughly represents a single piece of work that was done and the time at
- which it occurred. A span can have child spans, meaning that the work of
- the child had to be completed for the parent span to complete, or it can
- have follow-on spans which represent work that is undertaken as a result
- of the parent but is not depended on by the parent to in order to
- finish.</p>
- <p>Since this is undertaken in a distributed environment a request to
- another server, such as an RPC or a simple GET, can be considered a span
- (a unit or work) for the local server. This causal link is what
- OpenTracing aims to capture and visualise. In order to do this metadata
- about the local server's span, i.e the 'span context', needs to be
- included with the request to the remote.</p>
- <p>It is up to the remote server to decide what it does with the spans it
- creates. This is called the sampling policy and it can be configured
- through Jaeger's settings.</p>
- <p>For OpenTracing concepts see
- <a href="https://opentracing.io/docs/overview/what-is-tracing/">https://opentracing.io/docs/overview/what-is-tracing/</a>.</p>
- <p>For more information about Jaeger's implementation see
- <a href="https://www.jaegertracing.io/docs/">https://www.jaegertracing.io/docs/</a></p>
- <h2 id="setting-up-opentracing"><a class="header" href="#setting-up-opentracing">Setting up OpenTracing</a></h2>
- <p>To receive OpenTracing spans, start up a Jaeger server. This can be done
- using docker like so:</p>
- <pre><code class="language-sh">docker run -d --name jaeger \
- -p 6831:6831/udp \
- -p 6832:6832/udp \
- -p 5778:5778 \
- -p 16686:16686 \
- -p 14268:14268 \
- jaegertracing/all-in-one:1
- </code></pre>
- <p>Latest documentation is probably at
- https://www.jaegertracing.io/docs/latest/getting-started.</p>
- <h2 id="enable-opentracing-in-synapse"><a class="header" href="#enable-opentracing-in-synapse">Enable OpenTracing in Synapse</a></h2>
- <p>OpenTracing is not enabled by default. It must be enabled in the
- homeserver config by uncommenting the config options under <code>opentracing</code>
- as shown in the <a href="./sample_config.yaml">sample config</a>. For example:</p>
- <pre><code class="language-yaml">opentracing:
- enabled: true
- homeserver_whitelist:
- - "mytrustedhomeserver.org"
- - "*.myotherhomeservers.com"
- </code></pre>
- <h2 id="homeserver-whitelisting"><a class="header" href="#homeserver-whitelisting">Homeserver whitelisting</a></h2>
- <p>The homeserver whitelist is configured using regular expressions. A list
- of regular expressions can be given and their union will be compared
- when propagating any spans contexts to another homeserver.</p>
- <p>Though it's mostly safe to send and receive span contexts to and from
- untrusted users since span contexts are usually opaque ids it can lead
- to two problems, namely:</p>
- <ul>
- <li>If the span context is marked as sampled by the sending homeserver
- the receiver will sample it. Therefore two homeservers with wildly
- different sampling policies could incur higher sampling counts than
- intended.</li>
- <li>Sending servers can attach arbitrary data to spans, known as
- 'baggage'. For safety this has been disabled in Synapse but that
- doesn't prevent another server sending you baggage which will be
- logged to OpenTracing's logs.</li>
- </ul>
- <h2 id="configuring-jaeger"><a class="header" href="#configuring-jaeger">Configuring Jaeger</a></h2>
- <p>Sampling strategies can be set as in this document:
- <a href="https://www.jaegertracing.io/docs/latest/sampling/">https://www.jaegertracing.io/docs/latest/sampling/</a>.</p>
- <div style="break-before: page; page-break-before: always;"></div><h1 id="synapse-database-schema-files"><a class="header" href="#synapse-database-schema-files">Synapse database schema files</a></h1>
- <p>Synapse's database schema is stored in the <code>synapse.storage.schema</code> module.</p>
- <h2 id="logical-databases"><a class="header" href="#logical-databases">Logical databases</a></h2>
- <p>Synapse supports splitting its datastore across multiple physical databases (which can
- be useful for large installations), and the schema files are therefore split according
- to the logical database they apply to.</p>
- <p>At the time of writing, the following "logical" databases are supported:</p>
- <ul>
- <li><code>state</code> - used to store Matrix room state (more specifically, <code>state_groups</code>,
- their relationships and contents).</li>
- <li><code>main</code> - stores everything else.</li>
- </ul>
- <p>Additionally, the <code>common</code> directory contains schema files for tables which must be
- present on <em>all</em> physical databases.</p>
- <h2 id="synapse-schema-versions"><a class="header" href="#synapse-schema-versions">Synapse schema versions</a></h2>
- <p>Synapse manages its database schema via "schema versions". These are mainly used to
- help avoid confusion if the Synapse codebase is rolled back after the database is
- updated. They work as follows:</p>
- <ul>
- <li>
- <p>The Synapse codebase defines a constant <code>synapse.storage.schema.SCHEMA_VERSION</code>
- which represents the expectations made about the database by that version. For
- example, as of Synapse v1.36, this is <code>59</code>.</p>
- </li>
- <li>
- <p>The database stores a "compatibility version" in
- <code>schema_compat_version.compat_version</code> which defines the <code>SCHEMA_VERSION</code> of the
- oldest version of Synapse which will work with the database. On startup, if
- <code>compat_version</code> is found to be newer than <code>SCHEMA_VERSION</code>, Synapse will refuse to
- start.</p>
- <p>Synapse automatically updates this field from
- <code>synapse.storage.schema.SCHEMA_COMPAT_VERSION</code>.</p>
- </li>
- <li>
- <p>Whenever a backwards-incompatible change is made to the database format (normally
- via a <code>delta</code> file), <code>synapse.storage.schema.SCHEMA_COMPAT_VERSION</code> is also updated
- so that administrators can not accidentally roll back to a too-old version of Synapse.</p>
- </li>
- </ul>
- <p>Generally, the goal is to maintain compatibility with at least one or two previous
- releases of Synapse, so any substantial change tends to require multiple releases and a
- bit of forward-planning to get right.</p>
- <p>As a worked example: we want to remove the <code>room_stats_historical</code> table. Here is how it
- might pan out.</p>
- <ol>
- <li>
- <p>Replace any code that <em>reads</em> from <code>room_stats_historical</code> with alternative
- implementations, but keep writing to it in case of rollback to an earlier version.
- Also, increase <code>synapse.storage.schema.SCHEMA_VERSION</code>. In this
- instance, there is no existing code which reads from <code>room_stats_historical</code>, so
- our starting point is:</p>
- <p>v1.36.0: <code>SCHEMA_VERSION=59</code>, <code>SCHEMA_COMPAT_VERSION=59</code></p>
- </li>
- <li>
- <p>Next (say in Synapse v1.37.0): remove the code that <em>writes</em> to
- <code>room_stats_historical</code>, but don’t yet remove the table in case of rollback to
- v1.36.0. Again, we increase <code>synapse.storage.schema.SCHEMA_VERSION</code>, but
- because we have not broken compatibility with v1.36, we do not yet update
- <code>SCHEMA_COMPAT_VERSION</code>. We now have:</p>
- <p>v1.37.0: <code>SCHEMA_VERSION=60</code>, <code>SCHEMA_COMPAT_VERSION=59</code>.</p>
- </li>
- <li>
- <p>Later (say in Synapse v1.38.0): we can remove the table altogether. This will
- break compatibility with v1.36.0, so we must update <code>SCHEMA_COMPAT_VERSION</code> accordingly.
- There is no need to update <code>synapse.storage.schema.SCHEMA_VERSION</code>, since there is no
- change to the Synapse codebase here. So we end up with:</p>
- <p>v1.38.0: <code>SCHEMA_VERSION=60</code>, <code>SCHEMA_COMPAT_VERSION=60</code>.</p>
- </li>
- </ol>
- <p>If in doubt about whether to update <code>SCHEMA_VERSION</code> or not, it is generally best to
- lean towards doing so.</p>
- <h2 id="full-schema-dumps"><a class="header" href="#full-schema-dumps">Full schema dumps</a></h2>
- <p>In the <code>full_schemas</code> directories, only the most recently-numbered snapshot is used
- (<code>54</code> at the time of writing). Older snapshots (eg, <code>16</code>) are present for historical
- reference only.</p>
- <h3 id="building-full-schema-dumps"><a class="header" href="#building-full-schema-dumps">Building full schema dumps</a></h3>
- <p>If you want to recreate these schemas, they need to be made from a database that
- has had all background updates run.</p>
- <p>To do so, use <code>scripts-dev/make_full_schema.sh</code>. This will produce new
- <code>full.sql.postgres</code> and <code>full.sql.sqlite</code> files.</p>
- <p>Ensure postgres is installed, then run:</p>
- <pre><code>./scripts-dev/make_full_schema.sh -p postgres_username -o output_dir/
- </code></pre>
- <p>NB at the time of writing, this script predates the split into separate <code>state</code>/<code>main</code>
- databases so will require updates to handle that correctly.</p>
- <h2 id="boolean-columns"><a class="header" href="#boolean-columns">Boolean columns</a></h2>
- <p>Boolean columns require special treatment, since SQLite treats booleans the
- same as integers.</p>
- <p>There are three separate aspects to this:</p>
- <ul>
- <li>
- <p>Any new boolean column must be added to the <code>BOOLEAN_COLUMNS</code> list in
- <code>scripts/synapse_port_db</code>. This tells the port script to cast the integer
- value from SQLite to a boolean before writing the value to the postgres
- database.</p>
- </li>
- <li>
- <p>Before SQLite 3.23, <code>TRUE</code> and <code>FALSE</code> were not recognised as constants by
- SQLite, and the <code>IS [NOT] TRUE</code>/<code>IS [NOT] FALSE</code> operators were not
- supported. This makes it necessary to avoid using <code>TRUE</code> and <code>FALSE</code>
- constants in SQL commands.</p>
- <p>For example, to insert a <code>TRUE</code> value into the database, write:</p>
- <pre><code class="language-python">txn.execute("INSERT INTO tbl(col) VALUES (?)", (True, ))
- </code></pre>
- </li>
- <li>
- <p>Default values for new boolean columns present a particular
- difficulty. Generally it is best to create separate schema files for
- Postgres and SQLite. For example:</p>
- <pre><code class="language-sql"># in 00delta.sql.postgres:
- ALTER TABLE tbl ADD COLUMN col BOOLEAN DEFAULT FALSE;
- </code></pre>
- <pre><code class="language-sql"># in 00delta.sql.sqlite:
- ALTER TABLE tbl ADD COLUMN col BOOLEAN DEFAULT 0;
- </code></pre>
- <p>Note that there is a particularly insidious failure mode here: the Postgres
- flavour will be accepted by SQLite 3.22, but will give a column whose
- default value is the <strong>string</strong> <code>"FALSE"</code> - which, when cast back to a boolean
- in Python, evaluates to <code>True</code>.</p>
- </li>
- </ul>
- <div style="break-before: page; page-break-before: always;"></div><h1 id="log-contexts"><a class="header" href="#log-contexts">Log Contexts</a></h1>
- <p>To help track the processing of individual requests, synapse uses a
- '<code>log context</code>' to track which request it is handling at any given
- moment. This is done via a thread-local variable; a <code>logging.Filter</code> is
- then used to fish the information back out of the thread-local variable
- and add it to each log record.</p>
- <p>Logcontexts are also used for CPU and database accounting, so that we
- can track which requests were responsible for high CPU use or database
- activity.</p>
- <p>The <code>synapse.logging.context</code> module provides a facilities for managing
- the current log context (as well as providing the <code>LoggingContextFilter</code>
- class).</p>
- <p>Asynchronous functions make the whole thing complicated, so this document describes
- how it all works, and how to write code which follows the rules.</p>
- <p>In this document, "awaitable" refers to any object which can be <code>await</code>ed. In the context of
- Synapse, that normally means either a coroutine or a Twisted
- <a href="https://twistedmatrix.com/documents/current/api/twisted.internet.defer.Deferred.html"><code>Deferred</code></a>.</p>
- <h2 id="logcontexts-without-asynchronous-code"><a class="header" href="#logcontexts-without-asynchronous-code">Logcontexts without asynchronous code</a></h2>
- <p>In the absence of any asynchronous voodoo, things are simple enough. As with
- any code of this nature, the rule is that our function should leave
- things as it found them:</p>
- <pre><code class="language-python">from synapse.logging import context # omitted from future snippets
- def handle_request(request_id):
- request_context = context.LoggingContext()
- calling_context = context.set_current_context(request_context)
- try:
- request_context.request = request_id
- do_request_handling()
- logger.debug("finished")
- finally:
- context.set_current_context(calling_context)
- def do_request_handling():
- logger.debug("phew") # this will be logged against request_id
- </code></pre>
- <p>LoggingContext implements the context management methods, so the above
- can be written much more succinctly as:</p>
- <pre><code class="language-python">def handle_request(request_id):
- with context.LoggingContext() as request_context:
- request_context.request = request_id
- do_request_handling()
- logger.debug("finished")
- def do_request_handling():
- logger.debug("phew")
- </code></pre>
- <h2 id="using-logcontexts-with-awaitables"><a class="header" href="#using-logcontexts-with-awaitables">Using logcontexts with awaitables</a></h2>
- <p>Awaitables break the linear flow of code so that there is no longer a single entry point
- where we should set the logcontext and a single exit point where we should remove it.</p>
- <p>Consider the example above, where <code>do_request_handling</code> needs to do some
- blocking operation, and returns an awaitable:</p>
- <pre><code class="language-python">async def handle_request(request_id):
- with context.LoggingContext() as request_context:
- request_context.request = request_id
- await do_request_handling()
- logger.debug("finished")
- </code></pre>
- <p>In the above flow:</p>
- <ul>
- <li>The logcontext is set</li>
- <li><code>do_request_handling</code> is called, and returns an awaitable</li>
- <li><code>handle_request</code> awaits the awaitable</li>
- <li>Execution of <code>handle_request</code> is suspended</li>
- </ul>
- <p>So we have stopped processing the request (and will probably go on to
- start processing the next), without clearing the logcontext.</p>
- <p>To circumvent this problem, synapse code assumes that, wherever you have
- an awaitable, you will want to <code>await</code> it. To that end, whereever
- functions return awaitables, we adopt the following conventions:</p>
- <p><strong>Rules for functions returning awaitables:</strong></p>
- <blockquote>
- <ul>
- <li>If the awaitable is already complete, the function returns with the
- same logcontext it started with.</li>
- <li>If the awaitable is incomplete, the function clears the logcontext
- before returning; when the awaitable completes, it restores the
- logcontext before running any callbacks.</li>
- </ul>
- </blockquote>
- <p>That sounds complicated, but actually it means a lot of code (including
- the example above) "just works". There are two cases:</p>
- <ul>
- <li>
- <p>If <code>do_request_handling</code> returns a completed awaitable, then the
- logcontext will still be in place. In this case, execution will
- continue immediately after the <code>await</code>; the "finished" line will
- be logged against the right context, and the <code>with</code> block restores
- the original context before we return to the caller.</p>
- </li>
- <li>
- <p>If the returned awaitable is incomplete, <code>do_request_handling</code> clears
- the logcontext before returning. The logcontext is therefore clear
- when <code>handle_request</code> <code>await</code>s the awaitable.</p>
- <p>Once <code>do_request_handling</code>'s awaitable completes, it will reinstate
- the logcontext, before running the second half of <code>handle_request</code>,
- so again the "finished" line will be logged against the right context,
- and the <code>with</code> block restores the original context.</p>
- </li>
- </ul>
- <p>As an aside, it's worth noting that <code>handle_request</code> follows our rules</p>
- <ul>
- <li>though that only matters if the caller has its own logcontext which it
- cares about.</li>
- </ul>
- <p>The following sections describe pitfalls and helpful patterns when
- implementing these rules.</p>
- <h2 id="always-await-your-awaitables"><a class="header" href="#always-await-your-awaitables">Always await your awaitables</a></h2>
- <p>Whenever you get an awaitable back from a function, you should <code>await</code> on
- it as soon as possible. Do not pass go; do not do any logging; do not
- call any other functions.</p>
- <pre><code class="language-python">async def fun():
- logger.debug("starting")
- await do_some_stuff() # just like this
- coro = more_stuff()
- result = await coro # also fine, of course
- return result
- </code></pre>
- <p>Provided this pattern is followed all the way back up to the callchain
- to where the logcontext was set, this will make things work out ok:
- provided <code>do_some_stuff</code> and <code>more_stuff</code> follow the rules above, then
- so will <code>fun</code>.</p>
- <p>It's all too easy to forget to <code>await</code>: for instance if we forgot that
- <code>do_some_stuff</code> returned an awaitable, we might plough on regardless. This
- leads to a mess; it will probably work itself out eventually, but not
- before a load of stuff has been logged against the wrong context.
- (Normally, other things will break, more obviously, if you forget to
- <code>await</code>, so this tends not to be a major problem in practice.)</p>
- <p>Of course sometimes you need to do something a bit fancier with your
- awaitable - not all code follows the linear A-then-B-then-C pattern.
- Notes on implementing more complex patterns are in later sections.</p>
- <h2 id="where-you-create-a-new-awaitable-make-it-follow-the-rules"><a class="header" href="#where-you-create-a-new-awaitable-make-it-follow-the-rules">Where you create a new awaitable, make it follow the rules</a></h2>
- <p>Most of the time, an awaitable comes from another synapse function.
- Sometimes, though, we need to make up a new awaitable, or we get an awaitable
- back from external code. We need to make it follow our rules.</p>
- <p>The easy way to do it is by using <code>context.make_deferred_yieldable</code>. Suppose we want to implement
- <code>sleep</code>, which returns a deferred which will run its callbacks after a
- given number of seconds. That might look like:</p>
- <pre><code class="language-python"># not a logcontext-rules-compliant function
- def get_sleep_deferred(seconds):
- d = defer.Deferred()
- reactor.callLater(seconds, d.callback, None)
- return d
- </code></pre>
- <p>That doesn't follow the rules, but we can fix it by calling it through
- <code>context.make_deferred_yieldable</code>:</p>
- <pre><code class="language-python">async def sleep(seconds):
- return await context.make_deferred_yieldable(get_sleep_deferred(seconds))
- </code></pre>
- <h2 id="fire-and-forget"><a class="header" href="#fire-and-forget">Fire-and-forget</a></h2>
- <p>Sometimes you want to fire off a chain of execution, but not wait for
- its result. That might look a bit like this:</p>
- <pre><code class="language-python">async def do_request_handling():
- await foreground_operation()
- # *don't* do this
- background_operation()
- logger.debug("Request handling complete")
- async def background_operation():
- await first_background_step()
- logger.debug("Completed first step")
- await second_background_step()
- logger.debug("Completed second step")
- </code></pre>
- <p>The above code does a couple of steps in the background after
- <code>do_request_handling</code> has finished. The log lines are still logged
- against the <code>request_context</code> logcontext, which may or may not be
- desirable. There are two big problems with the above, however. The first
- problem is that, if <code>background_operation</code> returns an incomplete
- awaitable, it will expect its caller to <code>await</code> immediately, so will have
- cleared the logcontext. In this example, that means that 'Request
- handling complete' will be logged without any context.</p>
- <p>The second problem, which is potentially even worse, is that when the
- awaitable returned by <code>background_operation</code> completes, it will restore
- the original logcontext. There is nothing waiting on that awaitable, so
- the logcontext will leak into the reactor and possibly get attached to
- some arbitrary future operation.</p>
- <p>There are two potential solutions to this.</p>
- <p>One option is to surround the call to <code>background_operation</code> with a
- <code>PreserveLoggingContext</code> call. That will reset the logcontext before
- starting <code>background_operation</code> (so the context restored when the
- deferred completes will be the empty logcontext), and will restore the
- current logcontext before continuing the foreground process:</p>
- <pre><code class="language-python">async def do_request_handling():
- await foreground_operation()
- # start background_operation off in the empty logcontext, to
- # avoid leaking the current context into the reactor.
- with PreserveLoggingContext():
- background_operation()
- # this will now be logged against the request context
- logger.debug("Request handling complete")
- </code></pre>
- <p>Obviously that option means that the operations done in
- <code>background_operation</code> would be not be logged against a logcontext
- (though that might be fixed by setting a different logcontext via a
- <code>with LoggingContext(...)</code> in <code>background_operation</code>).</p>
- <p>The second option is to use <code>context.run_in_background</code>, which wraps a
- function so that it doesn't reset the logcontext even when it returns
- an incomplete awaitable, and adds a callback to the returned awaitable to
- reset the logcontext. In other words, it turns a function that follows
- the Synapse rules about logcontexts and awaitables into one which behaves
- more like an external function --- the opposite operation to that
- described in the previous section. It can be used like this:</p>
- <pre><code class="language-python">async def do_request_handling():
- await foreground_operation()
- context.run_in_background(background_operation)
- # this will now be logged against the request context
- logger.debug("Request handling complete")
- </code></pre>
- <h2 id="passing-synapse-deferreds-into-third-party-functions"><a class="header" href="#passing-synapse-deferreds-into-third-party-functions">Passing synapse deferreds into third-party functions</a></h2>
- <p>A typical example of this is where we want to collect together two or
- more awaitables via <code>defer.gatherResults</code>:</p>
- <pre><code class="language-python">a1 = operation1()
- a2 = operation2()
- a3 = defer.gatherResults([a1, a2])
- </code></pre>
- <p>This is really a variation of the fire-and-forget problem above, in that
- we are firing off <code>a1</code> and <code>a2</code> without awaiting on them. The difference
- is that we now have third-party code attached to their callbacks. Anyway
- either technique given in the <a href="log_contexts.html#fire-and-forget">Fire-and-forget</a>
- section will work.</p>
- <p>Of course, the new awaitable returned by <code>gather</code> needs to be
- wrapped in order to make it follow the logcontext rules before we can
- yield it, as described in <a href="log_contexts.html#where-you-create-a-new-awaitable-make-it-follow-the-rules">Where you create a new awaitable, make it
- follow the
- rules</a>.</p>
- <p>So, option one: reset the logcontext before starting the operations to
- be gathered:</p>
- <pre><code class="language-python">async def do_request_handling():
- with PreserveLoggingContext():
- a1 = operation1()
- a2 = operation2()
- result = await defer.gatherResults([a1, a2])
- </code></pre>
- <p>In this case particularly, though, option two, of using
- <code>context.run_in_background</code> almost certainly makes more sense, so that
- <code>operation1</code> and <code>operation2</code> are both logged against the original
- logcontext. This looks like:</p>
- <pre><code class="language-python">async def do_request_handling():
- a1 = context.run_in_background(operation1)
- a2 = context.run_in_background(operation2)
- result = await make_deferred_yieldable(defer.gatherResults([a1, a2]))
- </code></pre>
- <h2 id="a-note-on-garbage-collection-of-awaitable-chains"><a class="header" href="#a-note-on-garbage-collection-of-awaitable-chains">A note on garbage-collection of awaitable chains</a></h2>
- <p>It turns out that our logcontext rules do not play nicely with awaitable
- chains which get orphaned and garbage-collected.</p>
- <p>Imagine we have some code that looks like this:</p>
- <pre><code class="language-python">listener_queue = []
- def on_something_interesting():
- for d in listener_queue:
- d.callback("foo")
- async def await_something_interesting():
- new_awaitable = defer.Deferred()
- listener_queue.append(new_awaitable)
- with PreserveLoggingContext():
- await new_awaitable
- </code></pre>
- <p>Obviously, the idea here is that we have a bunch of things which are
- waiting for an event. (It's just an example of the problem here, but a
- relatively common one.)</p>
- <p>Now let's imagine two further things happen. First of all, whatever was
- waiting for the interesting thing goes away. (Perhaps the request times
- out, or something <em>even more</em> interesting happens.)</p>
- <p>Secondly, let's suppose that we decide that the interesting thing is
- never going to happen, and we reset the listener queue:</p>
- <pre><code class="language-python">def reset_listener_queue():
- listener_queue.clear()
- </code></pre>
- <p>So, both ends of the awaitable chain have now dropped their references,
- and the awaitable chain is now orphaned, and will be garbage-collected at
- some point. Note that <code>await_something_interesting</code> is a coroutine,
- which Python implements as a generator function. When Python
- garbage-collects generator functions, it gives them a chance to
- clean up by making the <code>async</code> (or <code>yield</code>) raise a <code>GeneratorExit</code>
- exception. In our case, that means that the <code>__exit__</code> handler of
- <code>PreserveLoggingContext</code> will carefully restore the request context, but
- there is now nothing waiting for its return, so the request context is
- never cleared.</p>
- <p>To reiterate, this problem only arises when <em>both</em> ends of a awaitable
- chain are dropped. Dropping the the reference to an awaitable you're
- supposed to be awaiting is bad practice, so this doesn't
- actually happen too much. Unfortunately, when it does happen, it will
- lead to leaked logcontexts which are incredibly hard to track down.</p>
- <div style="break-before: page; page-break-before: always;"></div><h1 id="replication-architecture"><a class="header" href="#replication-architecture">Replication Architecture</a></h1>
- <h2 id="motivation"><a class="header" href="#motivation">Motivation</a></h2>
- <p>We'd like to be able to split some of the work that synapse does into
- multiple python processes. In theory multiple synapse processes could
- share a single postgresql database and we'd scale up by running more
- synapse processes. However much of synapse assumes that only one process
- is interacting with the database, both for assigning unique identifiers
- when inserting into tables, notifying components about new updates, and
- for invalidating its caches.</p>
- <p>So running multiple copies of the current code isn't an option. One way
- to run multiple processes would be to have a single writer process and
- multiple reader processes connected to the same database. In order to do
- this we'd need a way for the reader process to invalidate its in-memory
- caches when an update happens on the writer. One way to do this is for
- the writer to present an append-only log of updates which the readers
- can consume to invalidate their caches and to push updates to listening
- clients or pushers.</p>
- <p>Synapse already stores much of its data as an append-only log so that it
- can correctly respond to <code>/sync</code> requests so the amount of code changes
- needed to expose the append-only log to the readers should be fairly
- minimal.</p>
- <h2 id="architecture"><a class="header" href="#architecture">Architecture</a></h2>
- <h3 id="the-replication-protocol"><a class="header" href="#the-replication-protocol">The Replication Protocol</a></h3>
- <p>See <a href="tcp_replication.html">the TCP replication documentation</a>.</p>
- <h3 id="the-slaved-datastore"><a class="header" href="#the-slaved-datastore">The Slaved DataStore</a></h3>
- <p>There are read-only version of the synapse storage layer in
- <code>synapse/replication/slave/storage</code> that use the response of the
- replication API to invalidate their caches.</p>
- <div style="break-before: page; page-break-before: always;"></div><h1 id="tcp-replication"><a class="header" href="#tcp-replication">TCP Replication</a></h1>
- <h2 id="motivation-1"><a class="header" href="#motivation-1">Motivation</a></h2>
- <p>Previously the workers used an HTTP long poll mechanism to get updates
- from the master, which had the problem of causing a lot of duplicate
- work on the server. This TCP protocol replaces those APIs with the aim
- of increased efficiency.</p>
- <h2 id="overview-3"><a class="header" href="#overview-3">Overview</a></h2>
- <p>The protocol is based on fire and forget, line based commands. An
- example flow would be (where '>' indicates master to worker and
- '<' worker to master flows):</p>
- <pre><code>> SERVER example.com
- < REPLICATE
- > POSITION events master 53 53
- > RDATA events master 54 ["$foo1:bar.com", ...]
- > RDATA events master 55 ["$foo4:bar.com", ...]
- </code></pre>
- <p>The example shows the server accepting a new connection and sending its identity
- with the <code>SERVER</code> command, followed by the client server to respond with the
- position of all streams. The server then periodically sends <code>RDATA</code> commands
- which have the format <code>RDATA <stream_name> <instance_name> <token> <row></code>, where
- the format of <code><row></code> is defined by the individual streams. The
- <code><instance_name></code> is the name of the Synapse process that generated the data
- (usually "master").</p>
- <p>Error reporting happens by either the client or server sending an ERROR
- command, and usually the connection will be closed.</p>
- <p>Since the protocol is a simple line based, its possible to manually
- connect to the server using a tool like netcat. A few things should be
- noted when manually using the protocol:</p>
- <ul>
- <li>The federation stream is only available if federation sending has
- been disabled on the main process.</li>
- <li>The server will only time connections out that have sent a <code>PING</code>
- command. If a ping is sent then the connection will be closed if no
- further commands are receieved within 15s. Both the client and
- server protocol implementations will send an initial PING on
- connection and ensure at least one command every 5s is sent (not
- necessarily <code>PING</code>).</li>
- <li><code>RDATA</code> commands <em>usually</em> include a numeric token, however if the
- stream has multiple rows to replicate per token the server will send
- multiple <code>RDATA</code> commands, with all but the last having a token of
- <code>batch</code>. See the documentation on <code>commands.RdataCommand</code> for
- further details.</li>
- </ul>
- <h2 id="architecture-1"><a class="header" href="#architecture-1">Architecture</a></h2>
- <p>The basic structure of the protocol is line based, where the initial
- word of each line specifies the command. The rest of the line is parsed
- based on the command. For example, the RDATA command is defined as:</p>
- <pre><code>RDATA <stream_name> <instance_name> <token> <row_json>
- </code></pre>
- <p>(Note that <row_json> may contains spaces, but cannot contain
- newlines.)</p>
- <p>Blank lines are ignored.</p>
- <h3 id="keep-alives"><a class="header" href="#keep-alives">Keep alives</a></h3>
- <p>Both sides are expected to send at least one command every 5s or so, and
- should send a <code>PING</code> command if necessary. If either side do not receive
- a command within e.g. 15s then the connection should be closed.</p>
- <p>Because the server may be connected to manually using e.g. netcat, the
- timeouts aren't enabled until an initial <code>PING</code> command is seen. Both
- the client and server implementations below send a <code>PING</code> command
- immediately on connection to ensure the timeouts are enabled.</p>
- <p>This ensures that both sides can quickly realize if the tcp connection
- has gone and handle the situation appropriately.</p>
- <h3 id="start-up"><a class="header" href="#start-up">Start up</a></h3>
- <p>When a new connection is made, the server:</p>
- <ul>
- <li>Sends a <code>SERVER</code> command, which includes the identity of the server,
- allowing the client to detect if its connected to the expected
- server</li>
- <li>Sends a <code>PING</code> command as above, to enable the client to time out
- connections promptly.</li>
- </ul>
- <p>The client:</p>
- <ul>
- <li>Sends a <code>NAME</code> command, allowing the server to associate a human
- friendly name with the connection. This is optional.</li>
- <li>Sends a <code>PING</code> as above</li>
- <li>Sends a <code>REPLICATE</code> to get the current position of all streams.</li>
- <li>On receipt of a <code>SERVER</code> command, checks that the server name
- matches the expected server name.</li>
- </ul>
- <h3 id="error-handling"><a class="header" href="#error-handling">Error handling</a></h3>
- <p>If either side detects an error it can send an <code>ERROR</code> command and close
- the connection.</p>
- <p>If the client side loses the connection to the server it should
- reconnect, following the steps above.</p>
- <h3 id="congestion"><a class="header" href="#congestion">Congestion</a></h3>
- <p>If the server sends messages faster than the client can consume them the
- server will first buffer a (fairly large) number of commands and then
- disconnect the client. This ensures that we don't queue up an unbounded
- number of commands in memory and gives us a potential oppurtunity to
- squawk loudly. When/if the client recovers it can reconnect to the
- server and ask for missed messages.</p>
- <h3 id="reliability"><a class="header" href="#reliability">Reliability</a></h3>
- <p>In general the replication stream should be considered an unreliable
- transport since e.g. commands are not resent if the connection
- disappears.</p>
- <p>The exception to that are the replication streams, i.e. RDATA commands,
- since these include tokens which can be used to restart the stream on
- connection errors.</p>
- <p>The client should keep track of the token in the last RDATA command
- received for each stream so that on reconneciton it can start streaming
- from the correct place. Note: not all RDATA have valid tokens due to
- batching. See <code>RdataCommand</code> for more details.</p>
- <h3 id="example-5"><a class="header" href="#example-5">Example</a></h3>
- <p>An example iteraction is shown below. Each line is prefixed with '>'
- or '<' to indicate which side is sending, these are <em>not</em> included on
- the wire:</p>
- <pre><code>* connection established *
- > SERVER localhost:8823
- > PING 1490197665618
- < NAME synapse.app.appservice
- < PING 1490197665618
- < REPLICATE
- > POSITION events master 1 1
- > POSITION backfill master 1 1
- > POSITION caches master 1 1
- > RDATA caches master 2 ["get_user_by_id",["@01register-user:localhost:8823"],1490197670513]
- > RDATA events master 14 ["$149019767112vOHxz:localhost:8823",
- "!AFDCvgApUmpdfVjIXm:localhost:8823","m.room.guest_access","",null]
- < PING 1490197675618
- > ERROR server stopping
- * connection closed by server *
- </code></pre>
- <p>The <code>POSITION</code> command sent by the server is used to set the clients
- position without needing to send data with the <code>RDATA</code> command.</p>
- <p>An example of a batched set of <code>RDATA</code> is:</p>
- <pre><code>> RDATA caches master batch ["get_user_by_id",["@test:localhost:8823"],1490197670513]
- > RDATA caches master batch ["get_user_by_id",["@test2:localhost:8823"],1490197670513]
- > RDATA caches master batch ["get_user_by_id",["@test3:localhost:8823"],1490197670513]
- > RDATA caches master 54 ["get_user_by_id",["@test4:localhost:8823"],1490197670513]
- </code></pre>
- <p>In this case the client shouldn't advance their caches token until it
- sees the the last <code>RDATA</code>.</p>
- <h3 id="list-of-commands"><a class="header" href="#list-of-commands">List of commands</a></h3>
- <p>The list of valid commands, with which side can send it: server (S) or
- client (C):</p>
- <h4 id="server-s"><a class="header" href="#server-s">SERVER (S)</a></h4>
- <p>Sent at the start to identify which server the client is talking to</p>
- <h4 id="rdata-s"><a class="header" href="#rdata-s">RDATA (S)</a></h4>
- <p>A single update in a stream</p>
- <h4 id="position-s"><a class="header" href="#position-s">POSITION (S)</a></h4>
- <p>On receipt of a POSITION command clients should check if they have missed any
- updates, and if so then fetch them out of band. Sent in response to a
- REPLICATE command (but can happen at any time).</p>
- <p>The POSITION command includes the source of the stream. Currently all streams
- are written by a single process (usually "master"). If fetching missing
- updates via HTTP API, rather than via the DB, then processes should make the
- request to the appropriate process.</p>
- <p>Two positions are included, the "new" position and the last position sent respectively.
- This allows servers to tell instances that the positions have advanced but no
- data has been written, without clients needlessly checking to see if they
- have missed any updates.</p>
- <h4 id="error-s-c"><a class="header" href="#error-s-c">ERROR (S, C)</a></h4>
- <p>There was an error</p>
- <h4 id="ping-s-c"><a class="header" href="#ping-s-c">PING (S, C)</a></h4>
- <p>Sent periodically to ensure the connection is still alive</p>
- <h4 id="name-c"><a class="header" href="#name-c">NAME (C)</a></h4>
- <p>Sent at the start by client to inform the server who they are</p>
- <h4 id="replicate-c"><a class="header" href="#replicate-c">REPLICATE (C)</a></h4>
- <p>Asks the server for the current position of all streams.</p>
- <h4 id="user_sync-c"><a class="header" href="#user_sync-c">USER_SYNC (C)</a></h4>
- <p>A user has started or stopped syncing on this process.</p>
- <h4 id="clear_user_sync-c"><a class="header" href="#clear_user_sync-c">CLEAR_USER_SYNC (C)</a></h4>
- <p>The server should clear all associated user sync data from the worker.</p>
- <p>This is used when a worker is shutting down.</p>
- <h4 id="federation_ack-c"><a class="header" href="#federation_ack-c">FEDERATION_ACK (C)</a></h4>
- <p>Acknowledge receipt of some federation data</p>
- <h3 id="remote_server_up-s-c"><a class="header" href="#remote_server_up-s-c">REMOTE_SERVER_UP (S, C)</a></h3>
- <p>Inform other processes that a remote server may have come back online.</p>
- <p>See <code>synapse/replication/tcp/commands.py</code> for a detailed description and
- the format of each command.</p>
- <h3 id="cache-invalidation-stream"><a class="header" href="#cache-invalidation-stream">Cache Invalidation Stream</a></h3>
- <p>The cache invalidation stream is used to inform workers when they need
- to invalidate any of their caches in the data store. This is done by
- streaming all cache invalidations done on master down to the workers,
- assuming that any caches on the workers also exist on the master.</p>
- <p>Each individual cache invalidation results in a row being sent down
- replication, which includes the cache name (the name of the function)
- and they key to invalidate. For example:</p>
- <pre><code>> RDATA caches master 550953771 ["get_user_by_id", ["@bob:example.com"], 1550574873251]
- </code></pre>
- <p>Alternatively, an entire cache can be invalidated by sending down a <code>null</code>
- instead of the key. For example:</p>
- <pre><code>> RDATA caches master 550953772 ["get_user_by_id", null, 1550574873252]
- </code></pre>
- <p>However, there are times when a number of caches need to be invalidated
- at the same time with the same key. To reduce traffic we batch those
- invalidations into a single poke by defining a special cache name that
- workers understand to mean to expand to invalidate the correct caches.</p>
- <p>Currently the special cache names are declared in
- <code>synapse/storage/_base.py</code> and are:</p>
- <ol>
- <li><code>cs_cache_fake</code> ─ invalidates caches that depend on the current
- state</li>
- </ol>
- <div style="break-before: page; page-break-before: always;"></div><h1 id="internal-documentation"><a class="header" href="#internal-documentation">Internal Documentation</a></h1>
- <p>This section covers implementation documentation for various parts of Synapse.</p>
- <p>If a developer is planning to make a change to a feature of Synapse, it can be useful for
- general documentation of how that feature is implemented to be available. This saves the
- developer time in place of needing to understand how the feature works by reading the
- code.</p>
- <p>Documentation that would be more useful for the perspective of a system administrator,
- rather than a developer who's intending to change to code, should instead be placed
- under the Usage section of the documentation.</p>
- <div style="break-before: page; page-break-before: always;"></div><h1 id="how-to-test-saml-as-a-developer-without-a-server"><a class="header" href="#how-to-test-saml-as-a-developer-without-a-server">How to test SAML as a developer without a server</a></h1>
- <p>https://capriza.github.io/samling/samling.html (https://github.com/capriza/samling) is a great
- resource for being able to tinker with the SAML options within Synapse without needing to
- deploy and configure a complicated software stack.</p>
- <p>To make Synapse (and therefore Riot) use it:</p>
- <ol>
- <li>Use the samling.html URL above or deploy your own and visit the IdP Metadata tab.</li>
- <li>Copy the XML to your clipboard.</li>
- <li>On your Synapse server, create a new file <code>samling.xml</code> next to your <code>homeserver.yaml</code> with
- the XML from step 2 as the contents.</li>
- <li>Edit your <code>homeserver.yaml</code> to include:
- <pre><code class="language-yaml">saml2_config:
- sp_config:
- allow_unknown_attributes: true # Works around a bug with AVA Hashes: https://github.com/IdentityPython/pysaml2/issues/388
- metadata:
- local: ["samling.xml"]
- </code></pre>
- </li>
- <li>Ensure that your <code>homeserver.yaml</code> has a setting for <code>public_baseurl</code>:
- <pre><code class="language-yaml">public_baseurl: http://localhost:8080/
- </code></pre>
- </li>
- <li>Run <code>apt-get install xmlsec1</code> and <code>pip install --upgrade --force 'pysaml2>=4.5.0'</code> to ensure
- the dependencies are installed and ready to go.</li>
- <li>Restart Synapse.</li>
- </ol>
- <p>Then in Riot:</p>
- <ol>
- <li>Visit the login page with a Riot pointing at your homeserver.</li>
- <li>Click the Single Sign-On button.</li>
- <li>On the samling page, enter a Name Identifier and add a SAML Attribute for <code>uid=your_localpart</code>.
- The response must also be signed.</li>
- <li>Click "Next".</li>
- <li>Click "Post Response" (change nothing).</li>
- <li>You should be logged in.</li>
- </ol>
- <p>If you try and repeat this process, you may be automatically logged in using the information you
- gave previously. To fix this, open your developer console (<code>F12</code> or <code>Ctrl+Shift+I</code>) while on the
- samling page and clear the site data. In Chrome, this will be a button on the Application tab.</p>
- <div style="break-before: page; page-break-before: always;"></div><h1 id="how-to-test-cas-as-a-developer-without-a-server"><a class="header" href="#how-to-test-cas-as-a-developer-without-a-server">How to test CAS as a developer without a server</a></h1>
- <p>The <a href="https://github.com/jbittel/django-mama-cas">django-mama-cas</a> project is an
- easy to run CAS implementation built on top of Django.</p>
- <h2 id="prerequisites"><a class="header" href="#prerequisites">Prerequisites</a></h2>
- <ol>
- <li>Create a new virtualenv: <code>python3 -m venv <your virtualenv></code></li>
- <li>Activate your virtualenv: <code>source /path/to/your/virtualenv/bin/activate</code></li>
- <li>Install Django and django-mama-cas:
- <pre><code>python -m pip install "django<3" "django-mama-cas==2.4.0"
- </code></pre>
- </li>
- <li>Create a Django project in the current directory:
- <pre><code>django-admin startproject cas_test .
- </code></pre>
- </li>
- <li>Follow the <a href="https://django-mama-cas.readthedocs.io/en/latest/installation.html#configuring">install directions</a> for django-mama-cas</li>
- <li>Setup the SQLite database: <code>python manage.py migrate</code></li>
- <li>Create a user:
- <pre><code>python manage.py createsuperuser
- </code></pre>
- <ol>
- <li>Use whatever you want as the username and password.</li>
- <li>Leave the other fields blank.</li>
- </ol>
- </li>
- <li>Use the built-in Django test server to serve the CAS endpoints on port 8000:
- <pre><code>python manage.py runserver
- </code></pre>
- </li>
- </ol>
- <p>You should now have a Django project configured to serve CAS authentication with
- a single user created.</p>
- <h2 id="configure-synapse-and-element-to-use-cas"><a class="header" href="#configure-synapse-and-element-to-use-cas">Configure Synapse (and Element) to use CAS</a></h2>
- <ol>
- <li>Modify your <code>homeserver.yaml</code> to enable CAS and point it to your locally
- running Django test server:
- <pre><code class="language-yaml">cas_config:
- enabled: true
- server_url: "http://localhost:8000"
- service_url: "http://localhost:8081"
- #displayname_attribute: name
- #required_attributes:
- # name: value
- </code></pre>
- </li>
- <li>Restart Synapse.</li>
- </ol>
- <p>Note that the above configuration assumes the homeserver is running on port 8081
- and that the CAS server is on port 8000, both on localhost.</p>
- <h2 id="testing-the-configuration"><a class="header" href="#testing-the-configuration">Testing the configuration</a></h2>
- <p>Then in Element:</p>
- <ol>
- <li>Visit the login page with a Element pointing at your homeserver.</li>
- <li>Click the Single Sign-On button.</li>
- <li>Login using the credentials created with <code>createsuperuser</code>.</li>
- <li>You should be logged in.</li>
- </ol>
- <p>If you want to repeat this process you'll need to manually logout first:</p>
- <ol>
- <li>http://localhost:8000/admin/</li>
- <li>Click "logout" in the top right.</li>
- </ol>
- <div style="break-before: page; page-break-before: always;"></div><h1 id="auth-chain-difference-algorithm"><a class="header" href="#auth-chain-difference-algorithm">Auth Chain Difference Algorithm</a></h1>
- <p>The auth chain difference algorithm is used by V2 state resolution, where a
- naive implementation can be a significant source of CPU and DB usage.</p>
- <h3 id="definitions"><a class="header" href="#definitions">Definitions</a></h3>
- <p>A <em>state set</em> is a set of state events; e.g. the input of a state resolution
- algorithm is a collection of state sets.</p>
- <p>The <em>auth chain</em> of a set of events are all the events' auth events and <em>their</em>
- auth events, recursively (i.e. the events reachable by walking the graph induced
- by an event's auth events links).</p>
- <p>The <em>auth chain difference</em> of a collection of state sets is the union minus the
- intersection of the sets of auth chains corresponding to the state sets, i.e an
- event is in the auth chain difference if it is reachable by walking the auth
- event graph from at least one of the state sets but not from <em>all</em> of the state
- sets.</p>
- <h2 id="breadth-first-walk-algorithm"><a class="header" href="#breadth-first-walk-algorithm">Breadth First Walk Algorithm</a></h2>
- <p>A way of calculating the auth chain difference without calculating the full auth
- chains for each state set is to do a parallel breadth first walk (ordered by
- depth) of each state set's auth chain. By tracking which events are reachable
- from each state set we can finish early if every pending event is reachable from
- every state set.</p>
- <p>This can work well for state sets that have a small auth chain difference, but
- can be very inefficient for larger differences. However, this algorithm is still
- used if we don't have a chain cover index for the room (e.g. because we're in
- the process of indexing it).</p>
- <h2 id="chain-cover-index"><a class="header" href="#chain-cover-index">Chain Cover Index</a></h2>
- <p>Synapse computes auth chain differences by pre-computing a "chain cover" index
- for the auth chain in a room, allowing efficient reachability queries like "is
- event A in the auth chain of event B". This is done by assigning every event a
- <em>chain ID</em> and <em>sequence number</em> (e.g. <code>(5,3)</code>), and having a map of <em>links</em>
- between chains (e.g. <code>(5,3) -> (2,4)</code>) such that A is reachable by B (i.e. <code>A</code>
- is in the auth chain of <code>B</code>) if and only if either:</p>
- <ol>
- <li>A and B have the same chain ID and <code>A</code>'s sequence number is less than <code>B</code>'s
- sequence number; or</li>
- <li>there is a link <code>L</code> between <code>B</code>'s chain ID and <code>A</code>'s chain ID such that
- <code>L.start_seq_no</code> <= <code>B.seq_no</code> and <code>A.seq_no</code> <= <code>L.end_seq_no</code>.</li>
- </ol>
- <p>There are actually two potential implementations, one where we store links from
- each chain to every other reachable chain (the transitive closure of the links
- graph), and one where we remove redundant links (the transitive reduction of the
- links graph) e.g. if we have chains <code>C3 -> C2 -> C1</code> then the link <code>C3 -> C1</code>
- would not be stored. Synapse uses the former implementations so that it doesn't
- need to recurse to test reachability between chains.</p>
- <h3 id="example-6"><a class="header" href="#example-6">Example</a></h3>
- <p>An example auth graph would look like the following, where chains have been
- formed based on type/state_key and are denoted by colour and are labelled with
- <code>(chain ID, sequence number)</code>. Links are denoted by the arrows (links in grey
- are those that would be remove in the second implementation described above).</p>
- <p><img src="auth_chain_diff.dot.png" alt="Example" /></p>
- <p>Note that we don't include all links between events and their auth events, as
- most of those links would be redundant. For example, all events point to the
- create event, but each chain only needs the one link from it's base to the
- create event.</p>
- <h2 id="using-the-index"><a class="header" href="#using-the-index">Using the Index</a></h2>
- <p>This index can be used to calculate the auth chain difference of the state sets
- by looking at the chain ID and sequence numbers reachable from each state set:</p>
- <ol>
- <li>For every state set lookup the chain ID/sequence numbers of each state event</li>
- <li>Use the index to find all chains and the maximum sequence number reachable
- from each state set.</li>
- <li>The auth chain difference is then all events in each chain that have sequence
- numbers between the maximum sequence number reachable from <em>any</em> state set and
- the minimum reachable by <em>all</em> state sets (if any).</li>
- </ol>
- <p>Note that steps 2 is effectively calculating the auth chain for each state set
- (in terms of chain IDs and sequence numbers), and step 3 is calculating the
- difference between the union and intersection of the auth chains.</p>
- <h3 id="worked-example"><a class="header" href="#worked-example">Worked Example</a></h3>
- <p>For example, given the above graph, we can calculate the difference between
- state sets consisting of:</p>
- <ol>
- <li><code>S1</code>: Alice's invite <code>(4,1)</code> and Bob's second join <code>(2,2)</code>; and</li>
- <li><code>S2</code>: Alice's second join <code>(4,3)</code> and Bob's first join <code>(2,1)</code>.</li>
- </ol>
- <p>Using the index we see that the following auth chains are reachable from each
- state set:</p>
- <ol>
- <li><code>S1</code>: <code>(1,1)</code>, <code>(2,2)</code>, <code>(3,1)</code> & <code>(4,1)</code></li>
- <li><code>S2</code>: <code>(1,1)</code>, <code>(2,1)</code>, <code>(3,2)</code> & <code>(4,3)</code></li>
- </ol>
- <p>And so, for each the ranges that are in the auth chain difference:</p>
- <ol>
- <li>Chain 1: None, (since everything can reach the create event).</li>
- <li>Chain 2: The range <code>(1, 2]</code> (i.e. just <code>2</code>), as <code>1</code> is reachable by all state
- sets and the maximum reachable is <code>2</code> (corresponding to Bob's second join).</li>
- <li>Chain 3: Similarly the range <code>(1, 2]</code> (corresponding to the second power
- level).</li>
- <li>Chain 4: The range <code>(1, 3]</code> (corresponding to both of Alice's joins).</li>
- </ol>
- <p>So the final result is: Bob's second join <code>(2,2)</code>, the second power level
- <code>(3,2)</code> and both of Alice's joins <code>(4,2)</code> & <code>(4,3)</code>.</p>
- <div style="break-before: page; page-break-before: always;"></div><h1 id="media-repository"><a class="header" href="#media-repository">Media Repository</a></h1>
- <p><em>Synapse implementation-specific details for the media repository</em></p>
- <p>The media repository is where attachments and avatar photos are stored.
- It stores attachment content and thumbnails for media uploaded by local users.
- It caches attachment content and thumbnails for media uploaded by remote users.</p>
- <h2 id="storage"><a class="header" href="#storage">Storage</a></h2>
- <p>Each item of media is assigned a <code>media_id</code> when it is uploaded.
- The <code>media_id</code> is a randomly chosen, URL safe 24 character string.</p>
- <p>Metadata such as the MIME type, upload time and length are stored in the
- sqlite3 database indexed by <code>media_id</code>.</p>
- <p>Content is stored on the filesystem under a <code>"local_content"</code> directory.</p>
- <p>Thumbnails are stored under a <code>"local_thumbnails"</code> directory.</p>
- <p>The item with <code>media_id</code> <code>"aabbccccccccdddddddddddd"</code> is stored under
- <code>"local_content/aa/bb/ccccccccdddddddddddd"</code>. Its thumbnail with width
- <code>128</code> and height <code>96</code> and type <code>"image/jpeg"</code> is stored under
- <code>"local_thumbnails/aa/bb/ccccccccdddddddddddd/128-96-image-jpeg"</code></p>
- <p>Remote content is cached under <code>"remote_content"</code> directory. Each item of
- remote content is assigned a local <code>"filesystem_id"</code> to ensure that the
- directory structure <code>"remote_content/server_name/aa/bb/ccccccccdddddddddddd"</code>
- is appropriate. Thumbnails for remote content are stored under
- <code>"remote_thumbnails/server_name/..."</code></p>
- <div style="break-before: page; page-break-before: always;"></div><h1 id="room-and-user-statistics"><a class="header" href="#room-and-user-statistics">Room and User Statistics</a></h1>
- <p>Synapse maintains room and user statistics in various tables. These can be used
- for administrative purposes but are also used when generating the public room
- directory.</p>
- <h1 id="synapse-developer-documentation"><a class="header" href="#synapse-developer-documentation">Synapse Developer Documentation</a></h1>
- <h2 id="high-level-concepts"><a class="header" href="#high-level-concepts">High-Level Concepts</a></h2>
- <h3 id="definitions-1"><a class="header" href="#definitions-1">Definitions</a></h3>
- <ul>
- <li><strong>subject</strong>: Something we are tracking stats about – currently a room or user.</li>
- <li><strong>current row</strong>: An entry for a subject in the appropriate current statistics
- table. Each subject can have only one.</li>
- </ul>
- <h3 id="overview-4"><a class="header" href="#overview-4">Overview</a></h3>
- <p>Stats correspond to the present values. Current rows contain the most up-to-date
- statistics for a room. Each subject can only have one entry.</p>
- <div style="break-before: page; page-break-before: always;"></div><h1 id="deprecation-policy-for-platform-dependencies"><a class="header" href="#deprecation-policy-for-platform-dependencies">Deprecation Policy for Platform Dependencies</a></h1>
- <p>Synapse has a number of platform dependencies, including Python and PostgreSQL.
- This document outlines the policy towards which versions we support, and when we
- drop support for versions in the future.</p>
- <h2 id="policy"><a class="header" href="#policy">Policy</a></h2>
- <p>Synapse follows the upstream support life cycles for Python and PostgreSQL,
- i.e. when a version reaches End of Life Synapse will withdraw support for that
- version in future releases.</p>
- <p>Details on the upstream support life cycles for Python and PostgreSQL are
- documented at https://endoflife.date/python and
- https://endoflife.date/postgresql.</p>
- <h2 id="context"><a class="header" href="#context">Context</a></h2>
- <p>It is important for system admins to have a clear understanding of the platform
- requirements of Synapse and its deprecation policies so that they can
- effectively plan upgrading their infrastructure ahead of time. This is
- especially important in contexts where upgrading the infrastructure requires
- auditing and approval from a security team, or where otherwise upgrading is a
- long process.</p>
- <p>By following the upstream support life cycles Synapse can ensure that its
- dependencies continue to get security patches, while not requiring system admins
- to constantly update their platform dependencies to the latest versions.</p>
- </main>
- <nav class="nav-wrapper" aria-label="Page navigation">
- <!-- Mobile navigation buttons -->
- <div style="clear: both"></div>
- </nav>
- </div>
- </div>
- <nav class="nav-wide-wrapper" aria-label="Page navigation">
- </nav>
- </div>
- <script type="text/javascript">
- window.playground_copyable = true;
- </script>
- <script src="elasticlunr.min.js" type="text/javascript" charset="utf-8"></script>
- <script src="mark.min.js" type="text/javascript" charset="utf-8"></script>
- <script src="searcher.js" type="text/javascript" charset="utf-8"></script>
- <script src="clipboard.min.js" type="text/javascript" charset="utf-8"></script>
- <script src="highlight.js" type="text/javascript" charset="utf-8"></script>
- <script src="book.js" type="text/javascript" charset="utf-8"></script>
- <!-- Custom JS scripts -->
- <script type="text/javascript" src="docs/website_files/table-of-contents.js"></script>
- <script type="text/javascript" src="docs/website_files/version-picker.js"></script>
- <script type="text/javascript" src="docs/website_files/version.js"></script>
- <script type="text/javascript">
- window.addEventListener('load', function() {
- window.setTimeout(window.print, 100);
- });
- </script>
- </body>
- </html>
|
