Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: Update wording and format for nfs.md #4008

Merged
merged 3 commits into from
Aug 18, 2023
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
23 changes: 13 additions & 10 deletions docs/en/deployment/nfs.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,7 @@
---
title: Creating NFS Shares
title: Create NFS Shares
sidebar_position: 9
description: Learn how to use the NFS protocol to share directories within the JuiceFS file system.
---

NFS (Network File System) is a network file-sharing protocol that allows different computers to share files and directories over a network. It was originally developed by Sun Microsystems and is a standard way of file sharing between Unix and Unix-like systems. The NFS protocol enables clients to access remote file systems as if they were local, achieving transparent remote file access.
Expand All @@ -11,27 +12,27 @@ When you need to share directories from the JuiceFS file system through NFS, you
`juicefs mount` mounts the file system as a local user-space file system through the FUSE interface, making it identical to the local file system in terms of appearance and usage. Hence, it can be directly used to create NFS shares.
:::

## Setp 1. Installing NFS
## Step 1. Install NFS

To configure NFS shares, you need to install the relevant software packages on both the server and client sides. Let's take Ubuntu/Debian systems as an example:

### 1. Server-Side Installation
### 1. Server-side installation

This refers to the host where the NFS shares will be created (and where the JuiceFS file system is also mounted).
Create a host for NFS sharing (with the JuiceFS file system also mounted on this server).

```shell
sudo apt install nfs-kernel-server
```

### 2. Client-Side Installation
### 2. Client-side installation

All Linux hosts that need to access NFS shares should install the client software.

```shell
sudo apt install nfs-common
```

## Setp 2. Creating Shares
## Step 2. Create shares

Assuming the JuiceFS is mounted on the server system at the path `/mnt/myjfs`, if you want to set the `media` subdirectory as an NFS share, you can add the following configuration to the `/etc/exports` file on the server system:

Expand All @@ -51,16 +52,18 @@ For example, if you want to restrict the mounting of this share to hosts in the
"/mnt/myjfs/media" 192.168.1.0/24(rw,async,no_subtree_check,no_root_squash,fsid=1)
```

**Explanation of the Share Options:**
### Share option description

**Explanation of the share options:**

- `rw`: Represents read and write permissions. If read-only access is desired, use `ro`.
- `sync` and `async`: `sync` enables synchronous writes, meaning that when writing to the NFS share, the client waits for the server's confirmation of successful data write before proceeding with subsequent operations. `async`, on the other hand, allows asynchronous writes. In this mode, the client does not wait for the server's confirmation of successful write before proceeding with subsequent operations.
- `no_subtree_check`: Disables subtree checking, allowing clients to mount both the parent and child directories of the NFS share. This can reduce some security but improve NFS compatibility. Setting it to `subtree_check` enables subtree checking, allowing clients to only mount the NFS share and its subdirectories.
- `no_root_squash`: Controls the mapping behavior of the client's root user when accessing the NFS share. By default, when the client mounts the NFS share as root, the server maps it to a non-privileged user (usually nobody or nfsnobody), which is known as root squashing. Enabling this option cancels the root squashing, giving the client the same root user privileges as the server. This option comes with certain security risks and should be used with caution.
- `fsid`: Filesystem identifier used to identify different filesystems on NFS. In NFSv4, the root directory of NFS is defined as fsid=0, and other filesystems need to be numbered uniquely under it. Here, JuiceFS is an externally mounted FUSE filesystem, so it needs to be assigned a unique identifier.
- `fsid`: A file system identifier used to identify different file systems on NFS. In NFSv4, the root directory of NFS is defined as fsid=0, and other file systems need to be numbered uniquely under it. Here, JuiceFS is an externally mounted FUSE file system, so it needs to be assigned a unique identifier.

### Choosing Between async and sync Modes
### Choosing between async and sync modes

For NFS shares, the sync (synchronous writes) mode can improve data reliability but always requires waiting for the server's confirmation before proceeding with the next operation, which may result in lower write performance. For JuiceFS, which is a cloud-based distributed filesystem, network latency also needs to be considered. Using the sync mode can often lead to lower write performance due to network latency.
For NFS shares, the sync (synchronous writes) mode can improve data reliability but always requires waiting for the server's confirmation before proceeding with the next operation. This may result in lower write performance. For JuiceFS, which is a cloud-based distributed file system, network latency also needs to be considered. Using the sync mode can often lead to lower write performance due to network latency.

In most cases, when creating NFS shares with JuiceFS, it is recommended to set the write mode to async (asynchronous writes) to avoid sacrificing write performance. If data reliability must be prioritized and sync mode is necessary, it is recommended to configure JuiceFS with a high-performance SSD as a local cache with sufficient capacity and enable the writeback cache mode.
15 changes: 9 additions & 6 deletions docs/zh_cn/deployment/nfs.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,7 @@
---
title: 创建 NFS 共享
sidebar_position: 9
description: 本文介绍如何通过 NFS 共享 JuiceFS 文件系统中的目录。
---

NFS(Network File System)是一种网络文件共享协议,允许不同计算机之间通过网络共享文件和目录。它最初由 Sun Microsystems 开发,是一种在 Unix 和类 Unix 系统之间进行文件共享的标准方式。NFS 协议允许客户端像访问本地文件系统一样访问远程文件系统,从而实现透明的远程文件访问。
Expand All @@ -17,7 +18,7 @@ NFS(Network File System)是一种网络文件共享协议,允许不同计

### 1. 服务端安装

即创建 NFS 共享的主机(JuiceFS 文件系统也挂载在该服务器上)。
创建 NFS 共享的主机(JuiceFS 文件系统也挂载在该服务器上)。

```shell
sudo apt install nfs-kernel-server
Expand Down Expand Up @@ -51,13 +52,15 @@ NFS 共享配置的语法为:
"/mnt/myjfs/media" 192.168.1.0/24(rw,async,no_subtree_check,no_root_squash,fsid=1)
```

### 共享选项说明

**其中涉及的共享选项:**

- `rw` - 代表允许读和写,如果只允许读则使用 `ro`。
- `sync` 与 `async` - sync 为同步写入,当向 NFS 共享写入文件时,客户端会等待服务端确认数据写入成功后再进行后续操作。async 为异步写入,写入操作是异步的,在写数据到 NFS 共享时,客户端不会等待服务器确认是否成功写入,而是立即执行后续操作。
- `no_subtree_check` - 禁用子目录检查,这将允许客户端挂载共享目录的父目录和子目录,会降低一些安全性但能提高 NFS 的兼容性。也可以设置为 subtree_check 来启用子目录检查,这样仅允许客户端挂载共享目录和它的子目录。
- `no_root_squash` - 用于控制客户端 root 用户访问 NFS 共享时的身份映射行为。默认情况下,客户端以 root 身份挂载 NFS 共享时,服务端会将其映射为非特权用户(通常是 nobody 或 nfsnobody),这被称为 root 挤压。设置该选项后,则取消这种权限挤压,从而让客户端拥有服务端相同的 root 用户权限。该选项有一定安全风险,建议谨慎使用。
- `fsid` - 文件系统标识符,用于在 NFS 上标识不同的文件系统。在 NFSv4 中,NFS 的根目录所在的文件系统被定义为 fsid=0,其他文件系统需要在它之下且编号唯一。在这里,JuiceFS 就是一个外挂的 FUSE 文件系统,因此需要给它设置一个唯一的标识。
- `rw`代表允许读和写,如果只允许读则使用 `ro`。
- `sync` 与 `async`:`sync` 为同步写入,当向 NFS 共享写入文件时,客户端会等待服务端确认数据写入成功后再进行后续操作。`async` 为异步写入,写入操作是异步的,在写数据到 NFS 共享时,客户端不会等待服务器确认是否成功写入,而是立即执行后续操作。
- `no_subtree_check`禁用子目录检查,这将允许客户端挂载共享目录的父目录和子目录,会降低一些安全性但能提高 NFS 的兼容性。也可以设置为 `subtree_check` 来启用子目录检查,这样仅允许客户端挂载共享目录和它的子目录。
- `no_root_squash`用于控制客户端 root 用户访问 NFS 共享时的身份映射行为。默认情况下,客户端以 root 身份挂载 NFS 共享时,服务端会将其映射为非特权用户(通常是 nobody 或 nfsnobody),这被称为 root 挤压。设置该选项后,则取消这种权限挤压,从而让客户端拥有服务端相同的 root 用户权限。该选项有一定安全风险,建议谨慎使用。
- `fsid`文件系统标识符,用于在 NFS 上标识不同的文件系统。在 NFSv4 中,NFS 的根目录所在的文件系统被定义为 fsid=0,其他文件系统需要在它之下且编号唯一。在这里,JuiceFS 就是一个外挂的 FUSE 文件系统,因此需要给它设置一个唯一的标识。

### async 与 sync 模式的选择

Expand Down