Mode parameter for listeners only supports decimal

[deepbluev7]

Description

When setting a mode in the listener config when listening on a unix domain socket, the mode needs to be specified in decimal. That isn't very obvious from the documentation: https://matrix-org.github.io/synapse/latest/usage/configuration/config_documentation.html#listeners

The documentation says it defaults to 666, however it actually defaults to 0o666 or rather 438. This leads the reader to believe they can specify a different mode like 660, however they would need to specify 432. Specifying octal does not work with the yaml parser synapse uses (0o660 is parsed as a string).

It would be good if the documentation mentioned that or required the mode to be passed as a string.

Steps to reproduce

• setup a listener on a unix domain socket with a non-default mode. It will have the wrong values when checking the permissions of the created socket, if the value is passed as a decimal number, but is actually octal.

Homeserver

neko.dev

Synapse Version

1.92.0_rc1

Installation Method

Other (please mention below)

Database

postgres, one db

Workers

Multiple workers

Platform

Gentoo

Configuration

No response

Relevant log output

s-w--w-r-T 1 synapse synapse 0 Sep 11 16:56 /run/synapse/event_creator.replication.sock

when mode 660 is specified.

### Anything else that would be useful to know?

_No response_

[DMRobertson]

Specifying octal does not work with the yaml parser synapse uses (0o660 is parsed as a string).

That is a surprise, and does seem to contradict the yaml spec at first glance.

FWIW it seems like you should be able to use 0660:

$ python
Python 3.11.5 (main, Aug 28 2023, 00:00:00) [GCC 13.2.1 20230728 (Red Hat 13.2.1-1)] on linux
Type "help", "copyright", "credits" or "license" for more information.
>>> import yaml
>>> yaml.safe_load('0660')
432
>>> bin(_)
'0b110110000'

[deepbluev7]

I think your parser is only yaml 1.1 compliant (0o is yaml 1.2 afaik)? And yes, seems like 0660 works. I may have looked at the wrong file when testing that.

[DMRobertson]

Aha, very insightful: this is indeed yaml 1.1: https://yaml.org/spec/1.1/current.html#id858600. Xref yaml/pyyaml#116

[clokep]

So is the way forward just to document this and add a test? Or is there something better to do?

[deepbluev7]

Maybe the parameter should actually be a string, so that it can be parsed as octal unconditionally or one could add a warning, when the mode exceeds 0o666, because that suggests a user either set the executable bit (which is unnecessary) or passed it as decimal. I'm not sure how other applications handle such parameters, my postgres config just has a comment right next to the field, which makes it hard to get wrong, but synapse doesn't ship a default config anymore, so explicitly calling that out in the documentation and fixing the example might be enough.