Merge pull request #309330 from normesta/blobfuse2

BlobFuse2 import from GitHub

Author: v-ccolin

articles/storage/.openpublishing.redirection.storage.json

@@ -2879,6 +2879,11 @@
             "source_path_from_root": "/articles/storage/file-sync/file-sync-storsimple-cost-comparison.md",
             "redirect_url": "/previous-versions/azure/storage/file-sync/file-sync-storsimple-cost-comparison",
             "redirect_document_id": false
+        },
+        {
+            "source_path_from_root": "/articles/storage/blobs/blobfuse2-how-to-deploy.md",
+            "redirect_url": "/azure/storage/blobs/blobfuse2-mount-container",
+            "redirect_document_id": false
         }
     ]
 }

articles/storage/blobs/TOC.yml

@@ -2,12 +2,12 @@
 title: How to use the BlobFuse2 command set
 titleSuffix: Azure Storage
 description: Learn how to use the BlobFuse2 command set to mount blob storage containers as file systems on Linux, and manage them.
-author: akashdubey-ms
+author: normesta
 ms.service: azure-blob-storage
 ms.custom: linux-related-content
-ms.topic: how-to
+ms.topic: reference
 ms.date: 12/02/2022
-ms.author: akashdubey
+ms.author: normesta
 # Customer intent: As a Linux administrator, I want to use the BlobFuse2 command set to mount blob storage containers as file systems, so that I can efficiently manage and interact with cloud storage directly from the Linux environment.
 ---
 
@@ -48,6 +48,7 @@ The supported commands for BlobFuse2 are:
 | [secure](blobfuse2-commands-secure.md)                 | Encrypts or decrypts a configuration file, or gets or sets values in an encrypted configuration file |
 | [version](blobfuse2-commands-version.md)               | Displays the current version of BlobFuse2 |
 | [help](blobfuse2-commands-help.md)                     | Gives help information about any command |
+| **gen-config**                                         | Auto generate recommended BlobFuse2 config file |
 
 ## Arguments
 

articles/storage/blobs/blobfuse2-commands.md

@@ -0,0 +1,51 @@
+---
+title: BlobFuse and Linux file systems compared
+titleSuffix: Azure Storage
+description: Learn about the differences between a BlobFuse file system and a Linux file system.
+author: normesta
+ms.author: normesta
+
+ms.service: azure-blob-storage
+ms.topic: reference
+ms.date: 1/29/2026
+
+ms.custom: linux-related-content
+
+# Customer intent: "As a developer or system administrator using BlobFuse, I want to understand how BlobFuse-mounted storage differs from native Linux file systems, so that I can set proper expectations and avoid potential issues when working with blob data."
+---
+
+# BlobFuse and Linux file systems compared
+
+This article describes the similarities and differences between BlobFuse and native Linux file systems.
+
+## Similarities between BlobFuse and Linux file systems
+
+You can use BlobFuse-mounted storage similarly to a native Linux file system. The virtual directory scheme uses the same forward slash (`/`) delimiter. Basic file system operations such as `mkdir`, `opendir`, `readdir`, `rmdir`, `open`, `read`, `create`, `write`, `close`, `unlink`, `truncate`, `stat`, and `rename` work the same as in a native Linux file system.
+
+## Differences between BlobFuse and Linux file systems
+
+- **Hard link count in readdir**: For performance reasons, BlobFuse doesn't correctly report the number of hard links inside a directory. The hard link count for empty directories always returns as 2, and for nonempty directories always returns as 3, regardless of the actual number of hard links.
+
+- **Non-atomic renames**: Azure Blob Storage doesn't support atomic rename operations. Single-file renames are actually two operations: a copy followed by deletion of the original. Directory renames recursively enumerate all files in the directory and rename each file individually.
+
+- **Special files**: BlobFuse supports only directories, regular files, and symbolic links. Special files like device files, pipes, and sockets aren't supported.
+
+- **mkfifo**: Fifo creation isn't supported by BlobFuse. Attempting this action results in a "function not implemented" error.
+
+- **chown and chmod**: BlobFuse doesn't support `chown` operations for either block blob storage (FNS) or Data Lake Storage (HNS). FNS storage accounts don't support `chmod` operations. HNS storage accounts support `chmod` operations but only on child objects within the mount directory, not on the root mount directory itself.
+  
+- **Device files or pipes**: BlobFuse doesn't support creating device files or pipes.
+
+- **Extended-attributes (x-attrs)**: BlobFuse doesn't support extended-attributes (`x-attrs`) operations.
+
+- **Write streaming**: Concurrent read and write operations on large files might produce unpredictable results. Writing to the same blob simultaneously from different threads isn't supported.
+
+## Next steps
+
+- [Install BlobFuse](blobfuse2-install.md)
+- [Configure BlobFuse](blobfuse2-configure.md)
+- [Mount an Azure Blob Storage container](blobfuse2-mount-container.md)
+
+## See also
+
+- [What is BlobFuse?](blobfuse2-what-is.md)

articles/storage/blobs/blobfuse2-compare-linux-file-system.md

@@ -1,73 +1,66 @@
 ---
-title: How to configure settings for BlobFuse2
+title: How to configure settings for BlobFuse
 titleSuffix: Azure Storage
-description: Learn how to configure settings for BlobFuse2.
+description: Learn how to configure settings for BlobFuse.
 author: akashdubey-ms
 ms.author: akashdubey
+ms.reviewer: normesta
 
 ms.service: azure-blob-storage
 ms.topic: how-to
-ms.date: 12/02/2022
-# Customer intent: "As a cloud administrator, I want to configure settings for BlobFuse2, so that I can effectively manage access, logging, caching, and permissions in my deployment."
+ms.date: 01/29/2026
+# Customer intent: "As a cloud administrator, I want to configure settings for BlobFuse, so that I can effectively manage access, logging, caching, and permissions in my deployment."
 ---
 
-# How to configure settings for BlobFuse2
+# How to configure settings for BlobFuse
 
-You can use configuration settings to manage BlobFuse2 in your deployment. Through configuration settings, you can set these aspects of how BlobFuse2 works in your environment:
+You can configure BlobFuse by using various settings. Some of the typical settings include:
 
-- Access to a storage blob
-- Logging
-- Pipeline engagement
-- Caching behavior
-- Permissions
+- Logging location and options
+- Temporary file path for caching
+- Information about the Azure storage account and blob container to be mounted
 
-For a list of all BlobFuse2 settings and their descriptions, see the [base configuration file on GitHub](https://github.com/Azure/azure-storage-fuse/blob/main/setup/baseConfig.yaml).
+The settings can be configured in a YAML configuration file, using environment variables, or as parameters passed to the BlobFuse commands. The preferred method is to use the configuration file.
 
-To manage configuration settings for BlobFuse2, you have three options (in order of precedence):
-
-- [Configuration file](#configuration-file)
-- [Environment variables](#environment-variables)
-- [CLI parameters](#cli-parameters)
-
-Using a configuration file is the preferred method, but the other methods might be useful in some circumstances.
+For details about each of the configuration parameters for BlobFuse and how to specify them, see these articles:
 
 ## Configuration file
 
-Creating a configuration file is the preferred method to establish settings for BlobFuse2. When you've specified the settings you want in the configuration file, reference the configuration file when you use `blobfuse2 mount` or other commands. 
+Creating a configuration file is the preferred method to establish settings for BlobFuse. When you've specified the settings you want in the configuration file, reference the configuration file when you use `blobfuse2 mount` or other commands.
 
 Here's an example:
 
 ````bash
 blobfuse2 mount ./mount --config-file=./config.yaml
 ````
 
-The [BlobFuse2 base configuration file](https://github.com/Azure/azure-storage-fuse/blob/main/setup/baseConfig.yaml) contains a list of all settings and a brief explanation of each setting.
+To learn more about how to create a configuration file, see [Create a BlobFuse configuration file](blobfuse2-configure.md).
+
+The [BlobFuse base configuration file](https://github.com/Azure/azure-storage-fuse/blob/main/setup/baseConfig.yaml) contains a list of all settings and a brief explanation of each setting.
 
 Use the [sample file cache configuration file](https://github.com/Azure/azure-storage-fuse/blob/main/sampleFileCacheConfig.yaml) to get started quickly by using some basic settings for each of those scenarios.
 
 ## Environment variables
 
-Setting environment variables is another way to configure some BlobFuse2 settings. The supported environment variables are useful for specifying the Azure Blob Storage container to access and the authorization method to use.
+Setting environment variables is another way to configure some BlobFuse settings. The supported environment variables are useful for specifying the Azure Blob Storage container to access and the authorization method to use.
 
-For more information about using environment variables and a list of all variables you can use, see the [BlobFuse2 README](https://github.com/Azure/azure-storage-fuse/tree/main#environment-variables).
+For more information about using environment variables and a list of all variables you can use, see the [BlobFuse README](https://github.com/Azure/azure-storage-fuse/tree/main#environment-variables).
 
 ## CLI parameters
 
-You also can set configuration settings when you pass them as parameters of the BlobFuse2 command set, such as by using the `blobfuse2 mount` command. The mount command typically references a configuration file that contains all the settings. But you can use CLI parameters to override individual settings in the configuration file. In this example, the *config.yaml* configuration file is referenced, but the container to be mounted and the logging options are overridden:
+You also can set configuration settings when you pass them as parameters of the BlobFuse command set, such as by using the `blobfuse2 mount` command. The mount command typically references a configuration file that contains all the settings. But you can use CLI parameters to override individual settings in the configuration file. In this example, the *config.yaml* configuration file is referenced, but the container to be mounted and the logging options are overridden:
 
 ```bash
 blobfuse2 mount ./mount_dir --config-file=./config.yaml --container-name=blobfuse2b --log-level=log_debug --log-file-path=./bobfuse2b.log
 ```
 
-For more information about the entire BlobFuse2 command set, including the `blobfuse2 mount` command, see [BlobFuse2 commands](blobfuse2-commands.md) and [BlobFuse2 mount commands](blobfuse2-commands-mount.md).
+For more information about the entire BlobFuse command set, including the `blobfuse2 mount` command, see [BlobFuse commands](blobfuse2-commands.md) and [BlobFuse2 mount commands](blobfuse2-commands-mount.md).
 
-## See also
+## Next steps
 
-- [Migrate to BlobFuse2 from BlobFuse v1](https://github.com/Azure/azure-storage-fuse/blob/main/MIGRATION.md)
-- [BlobFuse2 commands](blobfuse2-commands.md)
-- [Troubleshoot BlobFuse2 issues](blobfuse2-troubleshooting.md)
+- [Mount an Azure Blob Storage container on Linux by using BlobFuse](blobfuse2-mount-container.md)
 
-## Next steps
+## See also
 
-- [Mount an Azure Blob Storage container on Linux by using BlobFuse2](blobfuse2-how-to-deploy.md)
-- [Use Health Monitor to gain insights into BlobFuse2 mount activities and resource usage](blobfuse2-health-monitor.md)
+- [What is BlobFuse?](blobfuse2-what-is.md)
+- [BlobFuse2 commands](blobfuse2-commands.md)

articles/storage/blobs/blobfuse2-configuration.md

@@ -0,0 +1,107 @@
+---
+title: Configure BlobFuse for caching mode
+titleSuffix: Azure Storage
+description: Learn how to configure caching mode for BlobFuse mounts and optimize workloads for use with caching mode.
+author: normesta
+ms.author: normesta
+
+ms.service: azure-blob-storage
+ms.topic: how-to
+ms.date: 1/29/2026
+
+ms.custom: linux-related-content
+
+# Customer intent: "As a developer using BlobFuse, I want to configure caching mode for my Azure Blob Storage mount, so that I can optimize performance for workloads that require repeated access to files and benefit from local caching."
+---
+
+# Configure BlobFuse for caching mode
+
+This article helps you configure BlobFuse to mount a container in _caching mode_. In _caching mode_, BlobFuse downloads the entire file from Azure Blob Storage into a local cache directory before making it available to the application.
+
+> [!TIP]
+> You can mount a container in either _streaming mode_ or _caching mode_. To learn more about each mode, see [Streaming versus caching mode](blobfuse2-streaming-versus-caching.md).
+
+## Configuration parameters
+
+Specify the path of the local cache and an optional timeout in seconds.
+
+The local cache (or _temporary path_) is where BlobFuse stores all open file contents. The timeout is the maximum time in seconds before data is refreshed after an update. For example, if your workflow requires file contents to be refreshed within three seconds of an update, set this timeout to `3`. If your workflow requires an instant refresh, then set the timeout to `0`. Setting the timeout to `0` gives you instant refresh of contents but at the cost of higher REST calls to storage.
+
+The following example sets these values as parameters to the `mount` command.
+
+```bash
+blobfuse2 mount ~/mycontainer --tmp-path=/tmp/blobfusecache --file-cache-timeout=120
+```
+
+The following example shows how these settings appear in the BlobFuse configuration file.
+
+```yaml
+file_cache:
+path: /tmp/blobfusecache
+timeout-sec: 120 
+```
+
+For complete example, see [Sample file cache configuration](https://github.com/Azure/azure-storage-fuse/blob/main/sampleFileCacheConfig.yaml).
+
+> [!NOTE]
+> BlobFuse stores all open file contents in the temporary path. Make sure you have enough space to contain all open files.
+
+## Configuring a temporary path
+
+You can configure a temporary path on a local high performing disk, a RAM disk, or a solid state drive (SSD).
+
+If you use an existing local disk for caching, choose a disk that provides the best performance possible, such as a solid-state disk (SSD).
+
+In Azure, you can use the SSD ephemeral disks that are available on your virtual machines (VMs) to provide a low-latency buffer for BlobFuse. Depending on the provisioning agent you use, mount the ephemeral disk on `/mnt` for cloud-init or `/mnt/resource` for Microsoft Azure Linux Agent (waagent) VMs.
+
+Make sure that your user has access to the temporary path.
+
+```bash
+sudo mkdir /mnt/resource/blobfuse2tmp -p
+sudo chown <youruser> /mnt/resource/blobfuse2tmp
+```
+
+If you use a RAM disk, choose a size that meets your requirements. The following example creates a RAM disk of 16 GB and a directory for BlobFuse. BlobFuse uses the RAM disk to open files that are up to 16 GB in size.
+
+```bash
+sudo mkdir /mnt/ramdisk
+sudo mount -t tmpfs -o size=16g tmpfs /mnt/ramdisk
+sudo mkdir /mnt/ramdisk/blobfuse2tmp
+sudo chown <youruser> /mnt/ramdisk/blobfuse2tmp
+```
+
+## Optimize performance by preloading data
+
+In caching mode, BlobFuse waits for an open file system call. Upon receiving the open call, BlobFuse downloads the entire file to a local cache before using it. This behavior can make the initial load slower, especially for AI and machine learning tasks where the application is processing many files.
+
+The preload feature helps by downloading entire containers or subdirectories to the local cache when you mount them. Preload enhances data availability, boosting efficiency and reducing wait times. This improvement is vital for AI training with large datasets as it prepares all necessary files in advance, saving GPU time and reducing costs. By combining preload with the [Blob Filter](https://github.com/Azure/azure-storage-fuse/wiki/Blobfuse-Blob-Filter) feature, you can access specific files in a container or subdirectory, offering extensive flexibility and optimizing GPU cycles.
+
+To enable preload with file-cache mode, use the `--preload` parameter. The following command shows an example:
+
+```bash
+blobfuse2 mount --preload /mnt/blobfuse_mnt --tmp-path=/home/temp_path 
+```
+
+> [!NOTE]
+> Preloading blob data makes the mount read-only and prevents file eviction. To access updated files, unmount and remount the volume. Newly added files can still be accessed by reading them. If a blob filter is used with preload, only the filtered files are preloaded and accessible via the BlobFuse mount.
+
+### Considerations when using the preload feature
+
+- Enabling preload makes the BlobFuse mount read-only.
+
+- All file-caching options in CLI and config file are ignored except for the temporary path setting.
+
+- Ensure sufficient disk space for all or filtered contents in the container. Insufficient space might cause partial loading and block new file access until you manually delete files from the local cache.
+
+- Accessing a file immediately after mounting prioritizes it for download while preloading continues in the background.
+
+- BlobFuse logs show preload status and disk warnings.
+
+- The BlobFuse mount refreshes preloaded or opened files only if you manually delete them from the local cache and reopen them.
+
+- BlobFuse doesn't automatically download blobs added to the storage container after preload but can access them by reading.
+
+## Next steps
+
+- [Configure BlobFuse for streaming mode](blobfuse2-configure-streaming.md)
+- [Streaming versus caching mode](blobfuse2-streaming-versus-caching.md)