[DOCS-4707] Fix ACL and logrotate guidance for rotating logs (#37711)

* [DOCS-4707] Fix ACL recursion and logrotate guidance for rotating logs

- Use recursive setfacl (-R) so existing log files get access, not just the directory
- Document default ACLs (-d) so newly rotated files inherit dd-agent access
- Explain the duplicate log entry error and how to avoid it
- Fix misleading link text and standardize on the dd-agent user ACL

* [DOCS-4707] Apply editorial review fixes

- Standardize on dd-agent username throughout
- Use exact logrotate error string
- Move 'however' to front of sentence
- Upgrade ACL reference link to https

* [DOCS-4707] Fix subject-verb agreement and remove unsanctioned italics

- 'ACLs need to be enabled' (plural subject)
- Remove italics from 'default' (italics reserved for product names)

* [DOCS-4707] Remove meta references to other sections

* Apply suggestions from code review

Co-authored-by: May Lee <may.lee@datadoghq.com>

---------

Co-authored-by: May Lee <may.lee@datadoghq.com>

Author: maxvp

content/en/logs/guide/setting-file-permissions-for-rotating-logs.md

@@ -19,11 +19,11 @@ The Datadog Agent runs under the `dd-agent` user and `dd-agent` group. This prev
 
 ## Setting permissions using ACLs
 
-In order to allow read-only access for `datadog-agent` only, [create ACLs and modify logrotate to persist the permissions changes][1].
+To allow read-only access for the `dd-agent` user, create [access control lists (ACLs)][1] and modify logrotate to persist the permission changes.
 
 ### Verifying ACLs are enabled on your system
 
-[ACLs needs to be enabled][2] on your file system to set permissions using the methods outlined in this article. Verify ACLs are enabled by using the`getfacl` and `setfacl` commands to set permissions for the `datadog-agent` user on a test directory, for example:
+[ACLs need to be enabled][2] on your file system to set permissions using the methods outlined in this article. Verify ACLs are enabled by using the`getfacl` and `setfacl` commands to set permissions for the `dd-agent` user on a test directory, for example:
 
 ```shell
 mkdir /var/log/test-dir
@@ -32,23 +32,33 @@ setfacl -m u:dd-agent:rx /var/log/test-dir
 getfacl /var/log/test-dir/
 ```
 
-The permissions set for `datadog-agent` appears in the output of getfacl if ACLs are enabled.
+The permissions set for `dd-agent` appears in the output of getfacl if ACLs are enabled.
 
 {{< img src="logs/faq/setting_file_permission.png" alt="Setting file permission" >}}
 
 ### Granting dd-agent read and execute permissions on log directories
 
-Once you have verified ACLs are enabled, grant read and execute permissions for the `datadog-agent` user on the appropriate directories for log collection. For example, to grant access to `/var/log/apache` , run:
+After you verify ACLs are enabled, grant read and execute permissions for the `dd-agent` user on the appropriate directories for log collection. A plain `setfacl -m` command applies the ACL only to the directory itself, not to the log files already inside it. Use the `-R` (recursive) flag to also grant access to existing files. For example, to grant access to `/var/log/apache`, run:
 
 ```shell
-setfacl -m u:dd-agent:rx /var/log/apache
+setfacl -R -m u:dd-agent:rx /var/log/apache
 ```
 
-[Learn more about how to configure ACLs on linux][3]
+To have new log files inherit this access automatically, set a default ACL on the directory with the `-d` flag:
+
+```shell
+setfacl -R -d -m u:dd-agent:rx /var/log/apache
+```
+
+A default ACL only applies to files created in the directory after the default has been set, including those that log rotation creates. This reduces the need for a separate logrotate rule. Files that already exist when you set the default ACL are unaffected, so run both commands above.
+
+[Learn more about how to configure ACLs on Linux][3]
 
 ### Setting permissions for log file rotation
 
-Setting the permissions once will not persist for rotating logs, as logrotate does not re-apply the ACL setting. For a more permanent solution add a rule to logrotate to reset the ACL in a new file:
+If you set a default ACL with the `-d` flag, log files created by a rotation inherit `dd-agent` access automatically, and no further configuration is required. However, a default ACL does not cover every rotation scheme. For example, a configuration that uses `copytruncate` keeps the original file (and its ACL) in place rather than creating a new file.
+
+When a default ACL does not apply to your setup, add a rule to logrotate to reset the ACL after each rotation. Avoid defining a rule for log files that another logrotate configuration already manages, because logrotate reports an `error: duplicate log entry for <FILE>` message when two configurations match the same file. Instead, add a `postrotate` script to the service's existing configuration, or create a separate file for paths that are not already managed:
 
 ```shell
 sudo touch /etc/logrotate.d/dd-agent_ACLs
@@ -59,8 +69,8 @@ Example file:
 ```text
 /var/log/apache/*.log {
  postrotate
- /usr/bin/setfacl -m g:dd-agent:rx /var/log/apache/access.log
- /usr/bin/setfacl -m g:dd-agent:rx /var/log/apache/error.log
+ /usr/bin/setfacl -m u:dd-agent:rx /var/log/apache/access.log
+ /usr/bin/setfacl -m u:dd-agent:rx /var/log/apache/error.log
  endscript
 }
 ```
@@ -114,4 +124,4 @@ Each common off-the-shelf application will follow a similar nomenclature. The ad
 
 [1]: https://help.ubuntu.com/community/FilePermissionsACLs
 [2]: https://www.tecmint.com/secure-files-using-acls-in-linux
-[3]: http://xmodulo.com/configure-access-control-lists-acls-linux.html
+[3]: https://www.xmodulo.com/configure-access-control-lists-acls-linux.html