From nobody Thu Jan 16 18:58:14 2025 X-Original-To: dev-commits-doc-all@mlmmj.nyi.freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2610:1c1:1:606c::19:1]) by mlmmj.nyi.freebsd.org (Postfix) with ESMTP id 4YYsZb2jybz5kndp for ; Thu, 16 Jan 2025 18:58:15 +0000 (UTC) (envelope-from git@FreeBSD.org) Received: from mxrelay.nyi.freebsd.org (mxrelay.nyi.freebsd.org [IPv6:2610:1c1:1:606c::19:3]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest SHA256 client-signature RSA-PSS (4096 bits) client-digest SHA256) (Client CN "mxrelay.nyi.freebsd.org", Issuer "R11" (verified OK)) by mx1.freebsd.org (Postfix) with ESMTPS id 4YYsZb1pDVz3hVf; Thu, 16 Jan 2025 18:58:15 +0000 (UTC) (envelope-from git@FreeBSD.org) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=freebsd.org; s=dkim; t=1737053895; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding; bh=AuPz3dgKIzFTafhQWfSaSVWvBLRwAkq7wZ5WPz799mA=; b=IJNloAJvf49M+9e9IlJXhOtDayobBq5FAZJhlSv2wO7odhGQjKroUbwAv+Iv9zFb4ocI8q ufmgOiH9ZtbjdVqMAFjJhxknL4y2RdC4uP+4Dl31h346LWgAp2fDUZaQk1G6otbH9hODs6 h3OvD7CFeU46yTgV7PxjOKqJ3pbZSGKvT/gW40ZQ3mci/SyAjUjScxp8BFCBG/JEgQ5SLb DGLVz4mXQSPRzZkPqq7/A6BuTPitRUA+judlAWTLWUKtCF1khELwpNv3QNJNTPDtMliB6+ t+fVwF31b5vwuJR4poACvlbyXgMn3lnj45WWaqQVKMOjBWKhxm0vcSxRTUmbhQ== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=freebsd.org; s=dkim; t=1737053895; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding; bh=AuPz3dgKIzFTafhQWfSaSVWvBLRwAkq7wZ5WPz799mA=; b=wpATMNZqpaw2CKV/qcKYzI9iPJJ1c9nV4lRMgQoQEF0WNiAtggxvF1nDG6mOFbWsi5wr0l irweR8bIG1VD1pv+F2DUJh0tDlUL4GfRWR4m38cQnLwmi2oL03lmfsV3hx2sXLyDVmSo5J q99AZpbGJDal7lkmnTPXhS06YsbiHD8M6/U1YPRlmL/OiKLv7YDbe1a/fPG7hVmxSGTN+2 QLoo7tam5UYZ0Ln8hECEgCbkQuhWWDGUhQmxAHGOcE0jl5c7SGq/yvy/Qk4zFgp/Y+jBlr 5euEQ4s0DCRyEBdi7dgGHD+3+OHuomNIEVEYKEnWso0jlho6SIrZj+kzbOsIQg== ARC-Seal: i=1; s=dkim; d=freebsd.org; t=1737053895; a=rsa-sha256; cv=none; b=cHr3VQl4pEv/9yXg0LT20xfSUVRBpQ3Vlj6SYpg2lhi7N47wWv8sAVspp4pKNLvZGyuwtt keanYT5mBIYNdn9H5B/K/Wr0Ny7Zlo1VvFNdmE5I2Z3LzJsDQdQgqBiKIO7HMFgTCtySZk GvRsTY3jCDVc3p5ThM4oK/Q8ZKG0DR5+oQjQlAoVa1qpoRUrF1TYqXtgrc/YutwDsT1W89 giL+PV1etT9DfGmG2mIYf/CUpbHTPgyahCWNAByEg9J5oI698KYEy7zlvocuKTdDx3hQ8c 867osQ61HikiJKeriV8z3iHUvhID12IhB5q9ZA8I/AluzD8jtdFjZvZbsFTYXg== ARC-Authentication-Results: i=1; mx1.freebsd.org; none Received: from gitrepo.freebsd.org (gitrepo.freebsd.org [IPv6:2610:1c1:1:6068::e6a:5]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest SHA256) (Client did not present a certificate) by mxrelay.nyi.freebsd.org (Postfix) with ESMTPS id 4YYsZb0rfXzl8D; Thu, 16 Jan 2025 18:58:15 +0000 (UTC) (envelope-from git@FreeBSD.org) Received: from gitrepo.freebsd.org ([127.0.1.44]) by gitrepo.freebsd.org (8.18.1/8.18.1) with ESMTP id 50GIwEq1087386; Thu, 16 Jan 2025 18:58:14 GMT (envelope-from git@gitrepo.freebsd.org) Received: (from git@localhost) by gitrepo.freebsd.org (8.18.1/8.18.1/Submit) id 50GIwE46087383; Thu, 16 Jan 2025 18:58:14 GMT (envelope-from git) Date: Thu, 16 Jan 2025 18:58:14 GMT Message-Id: <202501161858.50GIwE46087383@gitrepo.freebsd.org> To: doc-committers@FreeBSD.org, dev-commits-doc-all@FreeBSD.org From: Sergio Carlavilla Delgado Subject: git: fd5d316a9a - main - Handbook WG - Filesystems: Rework filesystems chapter List-Id: Commit messages for all branches of the doc repository List-Archive: https://lists.freebsd.org/archives/dev-commits-doc-all List-Help: List-Post: List-Subscribe: List-Unsubscribe: X-BeenThere: dev-commits-doc-all@freebsd.org Sender: owner-dev-commits-doc-all@FreeBSD.org MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: 8bit X-Git-Committer: carlavilla X-Git-Repository: doc X-Git-Refname: refs/heads/main X-Git-Reftype: branch X-Git-Commit: fd5d316a9ae7912ceff6f27db22b26b4c58e887f Auto-Submitted: auto-generated The branch main has been updated by carlavilla: URL: https://cgit.FreeBSD.org/doc/commit/?id=fd5d316a9ae7912ceff6f27db22b26b4c58e887f commit fd5d316a9ae7912ceff6f27db22b26b4c58e887f Author: Sergio Carlavilla Delgado AuthorDate: 2025-01-16 18:56:18 +0000 Commit: Sergio Carlavilla Delgado CommitDate: 2025-01-16 18:56:18 +0000 Handbook WG - Filesystems: Rework filesystems chapter PR: 254191 Reviewed by: arrowd@, bcr@, fernape@, jrm@, ziaee@ Differential Revision: https://reviews.freebsd.org/D48400 Sponsored by: Siracusa --- .../content/en/books/handbook/disks/_index.adoc | 84 +--------- .../en/books/handbook/filesystems/_index.adoc | 180 ++++++++++++++++++--- 2 files changed, 157 insertions(+), 107 deletions(-) diff --git a/documentation/content/en/books/handbook/disks/_index.adoc b/documentation/content/en/books/handbook/disks/_index.adoc index bc03eedbfb..c66a4ad31f 100644 --- a/documentation/content/en/books/handbook/disks/_index.adoc +++ b/documentation/content/en/books/handbook/disks/_index.adoc @@ -4,7 +4,7 @@ part: Part III. System Administration prev: books/handbook/audit next: books/handbook/geom description: This chapter covers the use of disks and storage media in FreeBSD. This includes SCSI and IDE disks, CD and DVD media, memory-backed disks, and USB storage devices. -tags: ["storage", "disks", "gpart", "mount", "quotas", "encrypt", "GPT", "cdrecord", "NTFS", "quotas", "swap", "HAST", "CD", "DVD", "resizing", "growing"] +tags: ["storage", "disks", "gpart", "mount", "quotas", "encrypt", "GPT", "cdrecord", "quotas", "swap", "HAST", "CD", "DVD", "resizing", "growing"] showBookMenu: true weight: 24 path: "/books/handbook/disks/" @@ -1140,88 +1140,6 @@ The disk is now ready for use. To use the floppy, mount it with man:mount_msdosfs[8]. One can also install and use package:emulators/mtools[] from the Ports Collection. -[[using-ntfs]] -== Using NTFS Disks - -This section explains how to mount NTFS disks in FreeBSD. - -NTFS (New Technology File System) is a proprietary journaling file system developed by Microsoft(R). -It has been the default file system in Microsoft Windows(R) for many years. -FreeBSD can mount NTFS volumes using a FUSE file system. -These file systems are implemented as user space programs which interact with the man:fusefs[5] kernel module via a well defined interface. - -[.procedure] -==== -*Procedure: Steps to Mount a NTFS Disk* - -. Before using a FUSE file system we need to load the man:fusefs[5] kernel -module: -+ -[source,shell] -.... -# kldload fusefs -.... -+ -Use man:sysrc[8] to load the module at startup: -+ -[source,shell] -.... -# sysrc kld_list+=fusefs -.... - -. Install the actual NTFS file system from packages as in the example (see crossref:ports[pkgng-intro,Using pkg for Binary Package Management]) or from ports (see crossref:ports[ports-using,Using the Ports Collection]): -+ -[source,shell] -.... -# pkg install fusefs-ntfs -.... - -. Last we need to create a directory where the file system will be mounted: -+ -[source,shell] -.... -# mkdir /mnt/usb -.... - -. Suppose a USB disk is plugged in. The disk partition information can be viewed with man:gpart[8]: -+ -[source,shell] -.... -# gpart show da0 -=> 63 1953525105 da0 MBR (932G) - 63 1953525105 1 ntfs (932G) -.... - -. We can mount the disk using the following command: -+ -[source,shell] -.... -# ntfs-3g /dev/da0s1 /mnt/usb/ -.... -The disk is now ready to use. -+ -. Additionally, an entry can be added to /etc/fstab: -+ -[.programlisting] -.... -/dev/da0s1 /mnt/usb ntfs mountprog=/usr/local/bin/ntfs-3g,noauto,rw 0 0 -.... -+ -Now the disk can be now mounted with: -+ -[source,shell] -.... -# mount /mnt/usb -.... - -. The disk can be unmounted with: -+ -[source,shell] -.... -# umount /mnt/usb/ -.... -==== - [[backup-basics]] == Backup Basics diff --git a/documentation/content/en/books/handbook/filesystems/_index.adoc b/documentation/content/en/books/handbook/filesystems/_index.adoc index a735a241d8..c0748ddc83 100644 --- a/documentation/content/en/books/handbook/filesystems/_index.adoc +++ b/documentation/content/en/books/handbook/filesystems/_index.adoc @@ -4,7 +4,7 @@ part: Part III. System Administration prev: books/handbook/zfs next: books/handbook/virtualization description: This chapter shows the other filesystems supported by FreeBSD -tags: ["filesystem", "ext2", "ext3", "ext4", "ext2fs"] +tags: ["filesystem", "ext2", "ext3", "ext4", "ext2fs", "FAT", "exFAT", "NTFS", "HFS", "HFS+", "Apple", "Microsoft", "Linux"] showBookMenu: true weight: 27 path: "/books/handbook/filesystems/" @@ -51,32 +51,28 @@ endif::[] [[filesystems-synopsis]] == Synopsis -File systems are an integral part of any operating system. -They allow users to upload and store files, provide access to data, and make hard drives useful. -Different operating systems differ in their native file system. -Traditionally, the native FreeBSD file system has been the Unix File System UFS which has been modernized as UFS2. -Since FreeBSD 7.0, the Z File System (ZFS) is also available as a native file system. -See crossref:zfs[zfs,The Z File System (ZFS)] for more information. +File systems are a fundamental component of any operating system. +They enable users to store, manage, and access data, making storage devices like hard drives, flash drives, and USB storage devices practical for everyday use. +Different operating systems use different file systems natively. -In addition to its native file systems, FreeBSD supports a multitude of other file systems so that data from other operating systems can be accessed locally, such as data stored on locally attached USB storage devices, flash drives, and hard disks. -This includes support for the Linux(R) Extended File System (EXT). +FreeBSD has traditionally used the Unix File System (UFS), with the modernized UFS2 as its primary native file system. +FreeBSD also uses the Z File System (ZFS), known for its advanced features, robustness, and reliability. +See crossref:zfs[zfs,The Z File System (ZFS)] for more details. -There are different levels of FreeBSD support for the various file systems. -Some require a kernel module to be loaded and others may require a toolset to be installed. -Some non-native file system support is full read-write while others are read-only. - -After reading this chapter, you will know: - -* The difference between native and supported file systems. -* Which file systems are supported by FreeBSD. -* How to enable, configure, access, and make use of non-native file systems. +In addition to its native file systems, FreeBSD supports a broad range of file systems from other operating systems. +Support for these file systems varies, some require loading kernel modules, while others need additional userland tools. Before reading this chapter, you should: -* Understand UNIX(R) and crossref:basics[basics,FreeBSD basics]. -* Be familiar with the basics of crossref:kernelconfig[kernelconfig,kernel configuration and compilation]. +* Be familiar with UNIX(R) concepts and crossref:basics[basics,FreeBSD basics]. * Feel comfortable crossref:ports[ports,installing software] in FreeBSD. -* Have some familiarity with crossref:disks[disks,disks], storage, and device names in FreeBSD. +* Have some understanding of crossref:disks[disks,disks], storage devices, and FreeBSD's naming conventions for devices. + +After reading this chapter, you will: + +* Understand the differences between native and supported file systems. +* Know which file systems are supported by FreeBSD and the level of support available. +* Learn how to enable, configure, access, and work with non-native file systems. [[filesystems-linux]] == Linux(R) File Systems @@ -84,12 +80,13 @@ Before reading this chapter, you should: FreeBSD provides built-in support for several Linux(R) file systems. This section demonstrates how to load support for and how to mount the supported Linux(R) file systems. -=== ext2 / ext3 / ext4 +[[ext]] +=== Extended File System (EXT) -Kernel support for ext2 file systems has been available since FreeBSD 2.2. +Kernel support for Extended File System (EXT) file systems has been available since FreeBSD 2.2. The man:ext2fs[5] driver allows the FreeBSD kernel to both read and write to ext2, ext3, and ext4 file systems. -[NOTE] +[WARNING] ==== Journalling and encryption are not supported yet. ==== @@ -101,3 +98,138 @@ This example mounts [.filename]#/dev/ada1s1# on [.filename]#/mnt#: .... # mount -t ext2fs /dev/ada1s1 /mnt .... + +[[filesystems-windows]] +== Windows(R) File Systems + +FreeBSD supports FAT, exFAT, and NTFS file systems, enabling access to Windows-formatted storage. + +[[fat]] +=== FAT File System + +The FAT file system is a simple and robust file system. +Although it lacks the performance, reliability, and scalability of modern alternatives, its availability on many different operating systems makes it a common choice for data exchange between devices. + +To access a FAT file system, mount the FAT volume by specifying its FreeBSD partition name and an existing mount point. +This example mounts [.filename]#/dev/ada0s1# on [.filename]#/mnt#: + +[source,shell] +.... +# mount -t msdosfs /dev/ada0s1 /mnt +.... + +[[ex-fat]] +=== exFAT File System + +exFAT (Extended File Allocation Table) is a lightweight file system optimized for flash storage devices, such as USB drives and SD cards. +It supports large file sizes and is widely used across various platforms, making it ideal for external storage. + +To use exFAT on FreeBSD, install the package:filesystems/exfat[] package, load the FUSE kernel module, and mount the file system as shown below: + +Install the exFAT package: + +[source,shell] +.... +# pkg install exfat +.... + +Before using a FUSE file system, load the man:fusefs[5] kernel module: + +[source,shell] +.... +# kldload fusefs +.... + +Use man:sysrc[8] to load the module at startup: + +[source,shell] +.... +# sysrc kld_list+=fusefs +.... + +Mount the exFAT volumne by specifying its FreeBSD partition name and an existing mount point. +This example mounts [.filename]#/dev/ada0s1# on [.filename]#/mnt#: + +[source,shell] +.... +# mount.exfat /dev/ada0s1 /mnt +.... + +[[using-ntfs]] +=== NTFS File System + +NTFS is a robust file system developed by Microsoft(R) and commonly used in Windows operating systems. +FreeBSD provides full read and write support for NTFS through the package:filesystems/ntfs[] package, making it easy to access and modify NTFS-formatted storage devices. + +To use NTFS on FreeBSD, install the package:filesystems/ntfs[] package, load the FUSE kernel module, and mount the file system as shown below: + +Install the NTFS package: + +[source,shell] +.... +# pkg install ntfs +.... + +Before using a FUSE file system, load the man:fusefs[5] kernel module: + +[source,shell] +.... +# kldload fusefs +.... + +Use man:sysrc[8] to load the module at startup: + +[source,shell] +.... +# sysrc kld_list+=fusefs +.... + +Mount the NTFS volumne by specifying its FreeBSD partition name and an existing mount point. +This example mounts [.filename]#/dev/ada0s1# on [.filename]#/mnt#: + +[source,shell] +.... +# ntfs-3g /dev/ada0s1 /mnt +.... + +[[filesystems-macos]] +== MacOS(R) File Systems + +FreeBSD provides support for MacOS(R) file systems, including HFS/HFS+, allowing access to storage devices formatted for Apple(R) systems. + +[[hfs]] +=== HFS/HFS+ File System + +HFS/HFS+ was the primary file system for MacOS prior to APFS, commonly used on older Mac devices and external drives. +FreeBSD provides read-only support for HFS/HFS+ through the package:filesystems/hfsfuse[] package. + +To use HFS/HFS+ on FreeBSD, install the package:filesystems/hfsfuse[] package, load the FUSE kernel module, and mount the file system as shown below: + +Install the HFS/HFS+ package: + +[source,shell] +.... +# pkg install fusefs-hfsfuse +.... + +Before using a FUSE file system, load the man:fusefs[5] kernel module: + +[source,shell] +.... +# kldload fusefs +.... + +Use man:sysrc[8] to load the module at startup: + +[source,shell] +.... +# sysrc kld_list+=fusefs +.... + +Mount the HFS/HFS+ volumne by specifying its FreeBSD partition name and an existing mount point. +This example mounts [.filename]#/dev/ada0s1# on [.filename]#/mnt#: + +[source,shell] +.... +# hfsfuse /dev/ada0s1 /mnt +....