Documentation: How to change the RabbitMQ configuration file format to the new format

[mlsomers]

Is your feature request related to a problem? Please describe.

I have installed RabbitMQ on Windows using Chocolatey, default, nothing extras on the command line.

I found my configuration file in C:\Users\[my username]\AppData\Roaming\RabbitMQ\rabbitmq.config.

However, it is the old-style config, starting like this:

%% -*- mode: erlang -*-
%% ----------------------------------------------------------------------------
%% RabbitMQ Sample Configuration File.
%%
%% Related doc guide: http://www.rabbitmq.com/configure.html. See
%% http://rabbitmq.com/documentation.html for documentation ToC.
%% ----------------------------------------------------------------------------
[
 {rabbit,
  [%%
   %% Networking

I renamed it to advanced.config and created a new rabbitmq.config file with the new format:

ssl_options.cacertfile = ssl/cacert.pem
ssl_options.certfile   = ssl/cert.pem
ssl_options.keyfile    = ssl/key.pem
ssl_options.verify     = verify_none

The windows service starts without giving an error... log stays dead silent (in C:\Users\[user]\AppData\Roaming\RabbitMQ\log\[email protected]).. No response from management UI...

Starting the commandline:
C:\Program Files\RabbitMQ Server\rabbitmq_server-3.13.2\sbin>rabbitmq-server.bat finnally gives some useful output:

Failed to load advanced configuration file "c:/Users/[User]/AppData/Roaming/RabbitMQ/rabbitmq.config": 
{badfile,
 {parse_error,
  {1,
   erl_parse,
   ["syntax error before: ",
    "'.'"]}}}
 
 
BOOT FAILED
===========
Error during startup: {error,failed_to_read_advanced_configuration_file}

Since the documentation presents the new format almost everywhere I would like this new environment to also default to the new configuration style.

Describe the solution you'd like

A description of how to configure RabbitMq so that it will use the new format.

Describe alternatives you've considered

An alternative could be a conversion tool, but it seems that a 1-to-1 conversion will not work any way since there are quite some differences. For example:

Converted from https://www.rabbitmq.com/docs/management#single-listener-https :

management.ssl.port       = 15671
management.ssl.cacertfile = /path/to/ca_certificate.pem
management.ssl.certfile   = /path/to/server_certificate.pem
management.ssl.keyfile    = /path/to/server_key.pem

Should convert to this:

{management,
   {ssl,[
		{port,       15671},
   		{cacertfile, "/path/to/ca_certificate.pem"},
   		{certfile,   "/path/to/server_certificate.pem"},
   		{keyfile,    "/path/to/server_key.pem"}
   	]
   }
]},

But scroll down a bit and it appears to be completely different:

{rabbitmq_management,
  [{listener, [
	    {port,     15671},
	    {ssl,      true},
	    {ssl_opts, [
			{cacertfile, "/path/to/ca_certificate.pem"},
			{certfile,   "/path/to/server_certificate.pem"},
			{keyfile,    "/path/to/server_key.pem"}
			]
		}
	]}
]},

Additional context

No response

[lukebakken]

Hello, thanks for using RabbitMQ.

Neither Chocolatey nor the Windows RabbitMQ installer create a rabbitmq.config file, so it must be left over from a previous installation in your environment.

Here is a transcript of a 100% fresh install of Erlang 26 and RabbitMQ 3.13.2 on my Win 11 workstation:

> .\otp_win64_26.2.5.exe
C:\Users\lbakken\Downloads
> .\rabbitmq-server-3.13.2.exe
C:\Users\lbakken\Downloads
> dir C:\Users\lbakken\AppData\Roaming\RabbitMQ

    Directory: C:\Users\lbakken\AppData\Roaming\RabbitMQ

Mode                 LastWriteTime         Length Name
----                 -------------         ------ ----
-a---           5/22/2024  7:10 AM              3 advanced.config

C:\Users\lbakken\Downloads
> cat C:\Users\lbakken\AppData\Roaming\RabbitMQ\advanced.config
[].

created a new rabbitmq.config file with the new format

Yes, that format is correct, but the file MUST be named rabbitmq.conf for it to be parsed correctly. That is why you got the parse errors -

https://www.rabbitmq.com/docs/configure#config-file

I believe that the documentation is sufficient at this point. We would gladly review pull requests with suggested improvements.

[michaelklishin]

Should convert to this

What leads you to believe that? New config file keys can be anything, and the app environment they set up can be nested differently for any number of reasons, including backwards compatibility in this case.
We still support the original listener structure but most users, in particular the rabbitmq.conf users, should not know about that or care.

Those who are really curious can take a look at the translation schema files, e.g. the one used by the management plugin.

Where you will find how management.ssl.* keys are translated. But it's usually easier to simply use the docs, rabbitmq.conf conf supports the absolute majority of relevant keys that set simple values (which again, is the absolute majority of configuration keys).