MySQL Bugs: #106464: Docs indicate creating config files in /usr/sbin/

Bug #106464	Docs indicate creating config files in /usr/sbin/
Submitted:	15 Feb 2022 14:31	Modified:	17 Feb 2022 15:44
Reporter:	Matthew Boehm	Email Updates:
Status:	Not a Bug	Impact on me:	None
Category:	MySQL Server: Documentation	Severity:	S3 (Non-critical)
Version:		OS:	Any
Assigned to:		CPU Architecture:	Any

Description:
https://dev.mysql.com/doc/refman/8.0/en/keyring-component-installation.html

"Given the preceding manifest file properties, to configure the server to load component_keyring_file, create a global manifest file named mysqld.my in the mysqld installation directory"

The mysqld installation directory is /usr/sbin/ for most package installs. The documentation linked above indicates to the user that they should create a config file 'mysqld.my' inside the /usr/sbin/ directory. This is extremely bad practice as the sbin/ directory is only for system binaries, not for config files.

How to repeat:
-- Bad docs

Suggested fix:
Please fix the documentation to indicate a more correct location of keyring component config files.

Hi,

Thank you for your bug report.

However, our documentation does not indicate anywhere that configuration file should be created in /usr/sbin/ directory. 

Even in the case where our own packages are made to install it in /usr/sbin, our Documentation has already addressed that possibility by recommending to have a copy in the datadir.

We consider that this should be sufficient information.

Not a bug.

I'll once again copy/paste directly from the docs:

"create a global manifest file named mysqld.my in the mysqld installation directory"

Since "the mysqld installation directory" is /usr/sbin/, the docs instruct you to create the config file inside this directory.

The docs do NOT give you the option of using only a local manifest.

"optionally create a local manifest file"

The docs say use either: a global manifest (in sbin/), or use global + local (datadir)

Copy/paste from docs:

"To use a global manifest file only, "
"Alternatively, to use a global and local manifest file pair,"

There are no instruction in the docs indicating the use of local manifest only.

In addition to Matthew's comments, /usr is not intended for host-specific or changeable content, which one would presume the encryption key should be both of those. 

"Any information that is host-specific or varies with time is stored elsewhere."
https://tldp.org/LDP/Linux-Filesystem-Hierarchy/html/usr.html

Hi,

We had a short discussion on the subject and the unequivocal answer was that this feature is designed exactly as described in the manual.

Reference Manual is not a place for the explanation of why have decisions being made and features designed as they are designed, which is why Reference Manual contains sufficient info for the use of our products.

Not a bug.

https://en.wikipedia.org/wiki/Filesystem_Hierarchy_Standard

/usr/sbin - Non-essential system binaries

Everything you can google about "linux" and "/usr/sbin" says, unequivocally, that config files do not belong here; only binaries.

> Reference Manual is not a place for the explanation

I'm not asking for an explanation. I'm stating that the docs are incorrect and that the docs violate 100% the standard design and hierarchy of the linux filesystem.

`man heir` if you want more proof/evidence that the docs are incorrect.

Your RPM installation may place the mysqld binary under /usr/sbin, but this does not mean that all (standard!) installations do so.

https://dev.mysql.com/doc/refman/8.0/en/binary-installation.html#binary-installation-layou...:

"To install a compressed tar file binary distribution, unpack it at the installation location you choose (typically /usr/local/mysql)."

https://dev.mysql.com/doc/refman/8.0/en/source-installation-layout.html:

"By default, when you install MySQL after compiling it from source, the installation step installs files under /usr/local/mysql."

It is also quite possible to put it elsewhere. In my own case--purely for convenience in testing, AND I DO *NOT* AND YOU SHOULD *NOT* DO THIS IN PRODUCTION--I build from source and install everything under ~/bin/mysql-$version/.

So it's kind of necessary to generalise because the docs can't cover every possible case individually.

As for how the feature is implemented--I don't make those decisions, but it appears to me that a solution/workaround is provided in the docs. Did it work?

cheers

jon.

Hi Matthew, 

The documentation is not wrong. Yes it's unusual for configuration files to be stored where mysqld is installed. However the global manifest is not a standard configuration file.

So, this is not a documentation bug but more an implementation design. 

Regards,

> is not a documentation bug but more an implementation design

Ok. I'll absolutely agree that this is an implementation bug since we agree that custom configuration files do not belong in /usr/sbin/. Should I open a new bug or edit this one to clarify?

@Jon - /usr/local/mysql and ~/bin/mysql-$version are VERY different from /usr/sbin. There would be no issues placing config files in either of those locations. /usr/local is intended to have customizations (hence "local"). But the global system binaries (/usr/sbin) is not. Thus, having config files in /usr/sbin violates the very definition of the linux file system.