From 55586e0a08ba96042b56ad5d8fbd57e59f4957f7 Mon Sep 17 00:00:00 2001
From: Shizuo Fujita <fujita@clear-code.com>
Date: Tue, 4 Aug 2026 15:07:33 +0900
Subject: [PATCH] buf_file, buf_file_single: document file_permission and
 dir_permission

Both buffer plugins accept `file_permission` and `dir_permission`, but
neither parameter was described in the documentation.

* `buf_file`: introduced by fluentd 2612e9f8 (buf_file2.rb, released in
  v0.14.0), renamed to buf_file.rb by 7ee586c6.
* `buf_file_single`: introduced by fluentd dac13f04, released in v1.7.0.

The description follows the `desc` strings declared in buf_file_single.rb
and the fallback chain implemented in both plugins: the plugin parameter
takes precedence, then the `<system>` setting, then 0644 / 0755.

Signed-off-by: Shizuo Fujita <fujita@clear-code.com>
---
 buffer/file.md        | 42 +++++++++++++++++++++++++++++++++++++++++
 buffer/file_single.md | 44 +++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 86 insertions(+)

diff --git a/buffer/file.md b/buffer/file.md
index 9394a20d..c5a2f56c 100644
--- a/buffer/file.md
+++ b/buffer/file.md
@@ -116,6 +116,48 @@ Changes the suffix of the buffer file.
 
 This parameter is useful when `.log` is not fit for your environment. See also [this issue's comment](https://github.com/fluent/fluentd/issues/2236#issuecomment-514733974).
 
+### `file_permission`
+
+| type | default | version |
+| :--- | :--- | :--- |
+| string | nil | 0.14.0 |
+
+The permission of the buffer chunk files, in the octal format. The same permission is applied to the `.meta` files.
+
+```text
+<match pattern>
+  ...
+  <buffer>
+    @type file
+    path /var/log/fluent/buf
+    file_permission 0600
+  </buffer>
+</match>
+```
+
+If this parameter is not set, [`file_permission`](../deployment/system-config.md#file_permission) in the [system configuration](../deployment/system-config.md) is used. If it is not set either, `0644` is used.
+
+### `dir_permission`
+
+| type | default | version |
+| :--- | :--- | :--- |
+| string | nil | 0.14.0 |
+
+The permission of the directory created to store the buffer chunk files, in the octal format.
+
+```text
+<match pattern>
+  ...
+  <buffer>
+    @type file
+    path /var/log/fluent/buf
+    dir_permission 0700
+  </buffer>
+</match>
+```
+
+If this parameter is not set, [`dir_permission`](../deployment/system-config.md#dir_permission) in the [system configuration](../deployment/system-config.md) is used. If it is not set either, `0755` is used.
+
 ## Tips
 
 ### Customize a filename of the buffer chunk
diff --git a/buffer/file_single.md b/buffer/file_single.md
index f3ab72b7..96ed138b 100644
--- a/buffer/file_single.md
+++ b/buffer/file_single.md
@@ -85,6 +85,50 @@ Specifies the chunk format for `calc_num_records`.
 
 With `auto`, the plugin decides the chunk format by `formatted_to_msgpack_binary?`. This option is useful when the output plugin does not implement `formatted_to_msgpack_binary?` correctly.
 
+### `file_permission`
+
+| type | required | default | version |
+| :--- | :---: | :--- | :--- |
+| string |  | nil | 1.7.0 |
+
+The permission of the buffer chunk files, in the octal format.
+
+```text
+<match pattern>
+  @type forward
+  # forward parameters
+  <buffer>
+    @type file_single
+    path /var/log/fluent/out_fwd
+    file_permission 0600
+  </buffer>
+</match>
+```
+
+If this parameter is not set, [`file_permission`](../deployment/system-config.md#file_permission) in the [system configuration](../deployment/system-config.md) is used. If it is not set either, `0644` is used.
+
+### `dir_permission`
+
+| type | required | default | version |
+| :--- | :---: | :--- | :--- |
+| string |  | nil | 1.7.0 |
+
+The permission of the directory created to store the buffer chunk files, in the octal format.
+
+```text
+<match pattern>
+  @type forward
+  # forward parameters
+  <buffer>
+    @type file_single
+    path /var/log/fluent/out_fwd
+    dir_permission 0700
+  </buffer>
+</match>
+```
+
+If this parameter is not set, [`dir_permission`](../deployment/system-config.md#dir_permission) in the [system configuration](../deployment/system-config.md) is used. If it is not set either, `0755` is used.
+
 ## Limitation
 
 ### chunk keys