MySQL Bugs: #115921: MySQL 8.0 component_keyring_file documentation is lacking details

Bug #115921	MySQL 8.0 component_keyring_file documentation is lacking details
Submitted:	23 Aug 2024 14:51	Modified:	23 Aug 2024 15:43
Reporter:	Pierre C. Dussault	Email Updates:
Status:	Verified	Impact on me:	None
Category:	MySQL Server: Documentation	Severity:	S3 (Non-critical)
Version:	8.0.39	OS:	Red Hat (Almalinux 8)
Assigned to:		CPU Architecture:	x86
Tags:	component_keyring_file

Description:
This bug report concerns the documentation.

The documentation for component_keyring_file is insufficient to get a working keyring. Guessing is required by the user in order to get the configuration working. Following the documentation step by step is not sufficient.

How to repeat:
8.4.4.4 Using the component_keyring_file File-Based Keyring Component

1. Slightly problematic:
* The documentation mentions the "installation directory of mysqld". This can be confusing.

2. Highly problematic:
* The documentaiton mentions that permissions for the component_keyring_file manifest should be root:mysql rw-r----- (in 8.4.4.2 Keyring Component Installation). However, it never mentions any kind of filesystem permissions for the component_keyring_file configuration file(s). You have to guess the permissions that are required (I made it work using the same ones as for the manifest file(s)). Relying on the default umask does not yield a working setup.

Suggested fix:
8.4.4.4 Using the component_keyring_file File-Based Keyring Component

1. For the Slightly problematic:
* It should say explicitly "the directory containing the mysqld executable".

2. For the Highly problematic:
* It should clearly and explicitly say what filesystem permissions are required for the component_keyring_file configuration file(s).

Also a third element to add

 3. Highly problematic:
The fact that the keyring file 'component_keyring_file' has to be manually created (with root:mysql rw-rw---- permissions) is not mentioned. There is a slight mention of the permissions in

    "The following instructions assume that a keyring data file named
    /usr/local/mysql/keyring/component_keyring_file is to be used in read/write
    fashion."

but that does not say that it has to be manually created by the user. It is also very vague in terms of permissions. It should say explicitly what permissions are required.

All filesystem permission requirements should be explicit and should ideally get their own concise bullet point on the page.

Also, if the file has to be manually created or not should be mentioned in a concise bullet point, possibly in the same aforementioned bullet point as for the permissions.

Weaving in filesystem permission requirements and whether or not a file has to be manually created in long, drawn out sentences makes it very hard to follow.

Hello Pierre-Charles Dussault,

Thank you for the report and feedback.

regards,
Umesh