This is an automated email from the ASF dual-hosted git repository.
sammichen pushed a commit to branch HDDS-10685
in repository https://gitbox.apache.org/repos/asf/ozone.git
The following commit(s) were added to refs/heads/HDDS-10685 by this push:
new fb9398a313 HDDS-11626. Document short-circuit read feature (#7529)
fb9398a313 is described below
commit fb9398a31314b4964ca86dc12cf4cafb67cdbd59
Author: Sammi Chen <[email protected]>
AuthorDate: Fri Feb 21 11:50:34 2025 +0800
HDDS-11626. Document short-circuit read feature (#7529)
---
.../docs/content/design/short-circuit-read.md | 29 +++++++
.../docs/content/feature/Short-Circuit-Read.md | 90 ++++++++++++++++++++++
.../docs/content/feature/Short-Circuit-Read.zh.md | 88 +++++++++++++++++++++
3 files changed, 207 insertions(+)
diff --git a/hadoop-hdds/docs/content/design/short-circuit-read.md
b/hadoop-hdds/docs/content/design/short-circuit-read.md
new file mode 100644
index 0000000000..104e213858
--- /dev/null
+++ b/hadoop-hdds/docs/content/design/short-circuit-read.md
@@ -0,0 +1,29 @@
+---
+title: Short Circuit Local Read in DN
+summary: Support read data from local disk file directly when the client and
data are co-located on the same server
+date: 2024-12-04
+jira: HDDS-10685
+status: implemented
+
+---
+<!--
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License. See accompanying LICENSE file.
+-->
+
+# Abstract
+
+Short-circuit local read feature bypasses the Datanode, allowing the client to
read the file from the local disk directly when the client is co-located with
the data on the same server.
+
+# Link
+
+https://issues.apache.org/jira/secure/attachment/13068166/ShortCircuitReadInOzone-V1.pdf
\ No newline at end of file
diff --git a/hadoop-hdds/docs/content/feature/Short-Circuit-Read.md
b/hadoop-hdds/docs/content/feature/Short-Circuit-Read.md
new file mode 100644
index 0000000000..5178935d01
--- /dev/null
+++ b/hadoop-hdds/docs/content/feature/Short-Circuit-Read.md
@@ -0,0 +1,90 @@
+---
+title: "Short Circuit Local Read in Datanode"
+weight: 2
+menu:
+ main:
+ parent: Features
+summary: Introduction to Ozone Datanode Short Circuit Local Read Feature
+---
+<!---
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
+
+By default, client reads data over GRPC from the Datanode. When the client
asks the Datanode to read a file, the Datanode reads that file off of the disk
and sends the data to the client over a GRPC connection.
+
+This short-circuit local read feature will bypass the Datanode, allowing the
client to read the file from local disk directly when the client is co-located
with the data on the same server.
+
+Short-circuit local read can provide a substantial performance boost to many
applications by removing the overhead of network communication.
+
+## Prerequisite
+
+Short-circuit local reads make use of a UNIX domain socket. This is a special
path in the filesystem that allows the client and the DataNodes to communicate.
+
+The Hadoop native library `libhadoop.so` provides support to for Unix domain
sockets. Please refer to Hadoop's [Native Libraries
Guide](https://hadoop.apache.org/docs/stable/hadoop-project-dist/hadoop-common/NativeLibraries.html)
for details.
+
+The Hadoop version used in Ozone is defined by `hadoop.version` in pom.xml.
Before enabling short-circuit local reads, find the `libhadoop.so` from the
release package of the corresponding Hadoop version, put it under one of the
directories specified by Java `java.library.path` property. The default value
of `java.library.path` depends on the OS and Java version. For example, on
Linux with OpenJDK 8 it is
`/usr/java/packages/lib/amd64:/usr/lib64:/lib64:/lib:/usr/lib`.
+
+The `ozone checknative` command can be used to detect whether `libhadoop.so`
can be found and loaded successfully by Ozone service.
+
+
+## Configuration
+
+Short-circuit local reads need to be configured on both the Datanode and the
client. By default, it is disabled.
+
+```XML
+<property>
+ <name>ozone.client.read.short-circuit</name>
+ <value>false</value>
+ <description>Disable or enable the short-circuit local read
feature.</description>
+</property>
+```
+
+It makes use of a UNIX domain socket, a special path in the filesystem. You
will need to set a path to this socket.
+
+```XML
+<property>
+ <name>ozone.domain.socket.path</name>
+ <value></value>
+ <description> This is a path to a UNIX domain socket that will be used for
+ communication between the Datanode and local Ozone clients.
+ If the string "_PORT" is present in this path, it will be replaced by
the TCP port of the Datanode.
+ </description>
+</property>
+```
+
+The Datanode needs to be able to create this path. On the other hand, it
should not be possible for any user except the user who launches Ozone service
or root to create this path. For this reason, paths under `/var/run` or
`/var/lib` are often used.
+
+If you configure the `ozone.domain.socket.path` to some value, for example
`/dir1/dir2/ozone_dn_socket`, please make sure that both `dir1` and `dir2` are
existing directories, but the file `ozone_dn_socket` does not exist under
`dir2`. `ozone_dn_socket` will be created by Ozone Datanode later during its
startup.
+
+### Example Configuration
+To enable short-circuit read, here is an example configuration.
+
+```XML
+<property>
+ <name>ozone.client.read.short-circuit</name>
+ <value>true</value>
+</property>
+<property>
+ <name>ozone.domain.socket.path</name>
+ <value>/var/run/ozone_dn_socket</value>
+</property>
+```
+
+### Security Consideration
+
+To ensure data security and integrity, Ozone will follow the same rules as
Hadoop to check permission on the `ozone.domain.socket.path` path as documented
in [Socket Path Security](https://wiki.apache.org/hadoop/SocketPathSecurity).
It will fail the `ozone.domain.socket.path` verification and disable the
feature if the filesystem permissions of the specified path are inadequate. The
verification failure message carries detail instruction about how to fix the
problem. Following is an example,
+
+`The path component: '/etc/hadoop' in '/etc/hadoop/ozone_dn_socket' has
permissions 0777 uid 0 and gid 0. It is not protected because it is
world-writable. This might help: 'chmod o-w /etc/hadoop'. For more information:
https://wiki.apache.org/hadoop/SocketPathSecurity`
\ No newline at end of file
diff --git a/hadoop-hdds/docs/content/feature/Short-Circuit-Read.zh.md
b/hadoop-hdds/docs/content/feature/Short-Circuit-Read.zh.md
new file mode 100644
index 0000000000..c43f84a1c0
--- /dev/null
+++ b/hadoop-hdds/docs/content/feature/Short-Circuit-Read.zh.md
@@ -0,0 +1,88 @@
+---
+title: "Datanode 本地短路读"
+weight: 2
+menu:
+ main:
+ parent: 特性
+summary: Ozone Datanode 本地短路读功能介绍
+---
+<!---
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
+
+当前在 Ozone 中，客户端使用 GRPC 通道从 Datanode 读取数据。当客户端向 Datanode 请求读取一个文件时，Datanode
将文件从本次磁盘读到内存，然后通过 GRPC 通道发回给客户端。
+
+Datanode 本地短路读功能，当客户端和 Datanode 在同一个机器时，允许客户端绕过 Datanode，直接从本地磁盘读取文件内容。通过绕过
Datanode，去掉网络通信带来的开销，Datanode 本地短路读功能将帮助许多 Ozone 应用，提升读性能。
+
+## 前提
+
+Datanode 本地短路读功能基于 Unix domain socket 实现。 Unix domain socket
是一个特殊的文件系统路径，支持客户端和 Datanode 通过它交互传递信息。
+
+Datanode 本地短路读功能需要用到 Hadoop 本地库 `libhadoop.so`。 `libhadoop.so` 提供了调用 Unix
domain socket 的功能。该本地库的详细信息，详见 [Native
Libraries](https://hadoop.apache.org/docs/stable/hadoop-project-dist/hadoop-common/NativeLibraries.html)。
+
+Ozone 依赖的 Hadoop 版本，由 pom.xml 里的 `hadoop.version` 变量定义. 在启用 Datanode
本地短路读功能前，从对应的 Hadoop 版本发布获取对应的libhadoop.so 文件，将该文件放置在任一 Java 变量
`java.library.path` 定义的目录下。`java.library.path` 的默认值取决于操作系统和 JAVA 版本。例如，在 Linux
上 OpenJDK 8 的默认值是
`/usr/java/packages/lib/amd64:/usr/lib64:/lib64:/lib:/usr/lib`。
+
+在放置好 `libhadoop.so` 后，可使用命令 `ozone checknative` 来查看 `libhadoop.so` 是否能被
Ozone的服务进程正确的搜寻和加载到。
+
+
+## 配置
+
+Datanode 本地短路读功能需要在客户端和 Datanode 端同时配置。 默认情况下，它是关闭的。
+
+```XML
+<property>
+ <name>ozone.client.read.short-circuit</name>
+ <value>false</value>
+ <description>Disable or enable the short-circuit local read
feature.</description>
+</property>
+```
+
+Datanode 本地短路读基于 UNIX domain socket。以下变量将配置 domain socket 路径。
+
+```XML
+<property>
+ <name>ozone.domain.socket.path</name>
+ <value></value>
+ <description>This is a path to a UNIX domain socket that will be used for
+ communication between the Datanode and local Ozone clients.
+ If the string "_PORT" is present in this path, it will be replaced by
the TCP port of the Datanode.
+ </description>
+</property>
+```
+
+Datanode 需要能创建该路径. 同时，除了启动 Ozone 服务的用户和 root 用户，其他用户不能创建该路径。 由于有这些限制，路径经常使用
`/var/run` 或者 `/var/lib` 下的子目录。
+
+如果将 `ozone.domain.socket.path` 值设置成比如 `/dir1/dir2/ozone_dn_socket`，请确保 `dir1`
和 `dir2` 是已存在的目录，并且 `dir2` 下还没有 `ozone_dn_socket` 文件。 `ozone_dn_socket` 将在
Datanode 启动的时候由 Datanode 创建。
+
+### 参考配置
+可参考如下配置，启用短路读功能。
+
+```XML
+<property>
+ <name>ozone.client.read.short-circuit</name>
+ <value>true</value>
+</property>
+<property>
+ <name>ozone.domain.socket.path</name>
+ <value>/var/run/ozone_dn_socket</value>
+</property>
+```
+
+### 安全考量
+
+为了确保数据的安全和完整性，Ozone 在 `ozone.domain.socket.path` 路径的权限检查上，将遵守和 Hadoop
[Socket路径安全](https://wiki.apache.org/hadoop/SocketPathSecurity) 一样的规则。 如果
`ozone.domain.socket.path` 路径权限检查失败，该功能将自动关闭。 检查失败返回的信息包含修复问题的指引，例如
+
+`The path component: '/etc/hadoop' in '/etc/hadoop/ozone_dn_socket' has
permissions 0777 uid 0 and gid 0. It is not protected because it is
world-writable. This might help: 'chmod o-w /etc/hadoop'. For more information:
https://wiki.apache.org/hadoop/SocketPathSecurity`
\ No newline at end of file
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
