Complete Review & Update of the Object Mount Docs

.vscode/settings.json

@@ -3,8 +3,15 @@
     "*.md": "markdoc"
   },
   "cSpell.words": [
+    "cuno",
     "Gbps",
     "markdoc",
-    "Storj"
-  ]
+    "mdash",
+    "posix",
+    "Storj",
+    "Virtio",
+    "virtiofs"
+  ],
+  "editor.tabSize": 2,
+  "editor.detectIndentation": false
 }

CONTRIBUTING.md

@@ -36,7 +36,12 @@ The front matter is a section at the beginning of each Markdown file (page.md) t
 
 **title:** The title of the article or page. This is typically displayed at the top of the page.
 
-**docId:** A unique identifier for the document. This can be used for internal tracking and linking. See [Internal Linking](/CONTRIBUTING.md#internal-linking). If you're making a new page, generate a new unique ID with `pwgen -1 16` or something similar. 
+**docId:** A unique identifier for the document. This can be used for internal tracking and linking. See [Internal Linking](/CONTRIBUTING.md#internal-linking). If you're making a new page, generate a new unique ID with `pwgen -1 16` or something similar.
+
+`docid` Recommendations:
+- Online password generators such as [https://pwgen.io/](https://pwgen.io/) work well.
+- A length of 16 characters is preferred
+- Avoid special characters or symbols. Use only UPPER, lower and numbers (0-9).
 
 **redirects:** A list of URLs that should redirect to this page. This is useful for maintaining links when a page's URL changes or for creating aliases for a page.
 

app/(docs)/object-mount/appendix/POSIX/page.md

@@ -0,0 +1,128 @@
+---
+title: POSIX Explained
+hideTitle: false
+docId: ySneAEd79CVewSSr
+weight: 2
+redirects:
+  - /object-mount/faq/posix-mode
+metadata:
+  title: POSIX Explained
+  description:
+    Understanding POSIX and using Object Mount in POSIX Mode.
+hidden: false
+---
+
+## What is POSIX?
+
+The Portable Operating System Interface (🌐 [POSIX](https://en.wikipedia.org/wiki/POSIX)) is a set of IEEE specifications intended to encourage compatibility between disparate Linux/UNIX flavors through standardized definitions of APIs, shells, interfaces, commands, etc.
+
+Writing an application (or binary) which meets POSIX standards means that the program is “portable,” and is more likely to run correctly no matter what UNIX-based OS it is installed on.
+
+Some applications may (or may not) require _strict_ POSIX-compliance to work properly. 
+
+
+## Object Mount’s POSIX Mode
+
+To support those programs and applications that require POSIX-compliant interfaces, access-control, and metadata, Object Mount includes **POSIX Mode**. 
+
+When activated, POSIX Mode enables the necessary additional features to support applications that rely on the rigid, traditional UNIX-style file permissions and metadata.
+
+Object storage, by default, lacks concepts like file ownership, permissions, and modification timestamps that are normal features of most local drives and file system calls. Object Mount’s POSIX Mode recreates these features and behaviors in the object storage world.
+
+When enabled, POSIX Mode generates, stores, and maintains the metadata that is typically expected in a local file system, including:
+- File ownership (uid, gid)
+- Read/Write/Execute permissions
+- Timestamps (mtime, ctime, etc.)
+- Symbolic links and directory flags (where supported)
+
+To retain this metadata, Object Mount creates and writes to a hidden index file that is stored at the root of your object storage bucket.
+
+{% callout type="info" %}
+  **POSIX Mode Requirements**
+
+  To support POSIX Mode, ensure your S3 credentials allow, and your bucket supports, write access. Your credentials must allow `s3:PutObject` and `s3:DeleteObject`.
+{% /callout %}
+
+{% callout type="warning" %}
+  **Accessing Content Outside of Object Mount**
+
+  Using any non-Object Mount tool to rename, move, or copy your files will result in those objects _losing_ their POSIX metadata. You should only use Object Mount to manage POSIX-enabled files in order to preserve their metadata and attributes.
+{% /callout %}
+
+
+## When to Enable Object Mount’s POSIX Mode
+
+You should enable POSIX mode in Object Mount if:
+
+- You are working with software that checks for or enforces POSIX-style permissions
+- You require symbolic link emulation or fine-grained permission mapping
+- You are mounting object storage as a shared filesystem in team environments
+
+Enabling POSIX mode is recommended for workflows such as:
+
+- Media Production
+- Backup Solutions
+- Archive Systems
+- File Synchronization
+- File Manager/Tools
+
+
+## When NOT to Enable Object Mount’s POSIX Mode
+
+You should _not_ enable POSIX Mode in Object Mount for:
+
+- **Read-only Bucket Credentials**
+
+  POSIX Mode requires _write_ access to the object storage bucket in order to create and write to the hidden metadata file. If your credentials are read-only, POSIX mode will not function and may prevent the mount from working correctly.
+
+- **Lightweight Access** 
+
+  For read-only workflows or general content browsing, POSIX mode is typically unnecessary and can be left disabled.
+
+
+## Enabling POSIX Mode: macOS and Windows
+
+POSIX mode is enabled on a mount-by-mount basis: You can choose which mounts require it and which don’t.
+
+You enable POSIX mode when **creating a new mount** within Object Mount for macOS or Windows.
+
+{% callout type="warning" %}
+  **Important:** You cannot change the POSIX Mode setting after a mount has been created in Object Mount for macOS or Windows.
+{% /callout %}
+
+Enabling POSIX mode in **macOS** and **Windows** environments is done through Object Mount’s graphical user interface (GUI). 
+
+See the associated page for your operating system:
+
+- Enabling POSIX Mode when [creating a mount in macOS](docId:QpBba8p4bMTXAkBK#step-2-configure-s3-credentials-and-create-a-mount)
+- Enabling POSIX Mode [creating a mount in Windows](docId:khHGfZsyY9NJ2uGK#step-2-configure-s3-credentials-and-create-a-mount)
+
+{% callout type="info" %}
+  **POSIX Feature Support on Mac & Windows**
+
+  User and Group identity features are not supported on Mac and Windows platforms:
+  - The owner of cloud objects is always reported to be the current user.
+  - The directory mode is reported as `0777` and the file mode is reported as `0666`.
+
+  Also, POSIX access controls are not enforced by Object Mount on Mac and Windows.
+
+  For a deeper understanding of the full suite of POSIX Mode Features see the Linux Getting Started Guide article: [](docId:cbm3PcQXmLpuYcbg) and the Linux User Guide article: [](docId:Eegoo1teiJ8eerae).
+{% /callout %}
+
+
+## Enabling POSIX Mode: Linux
+
+POSIX support in Object Mount for Linux includes more options, more modes, and offers more controls for the end user to configure their environment according to their unique needs and use cases.
+
+Configuration of POSIX options in Object Mount for Linux is achieved:
+  - Via the command line interface (the Object Mount CLI)
+  - Through the setting of environment variables
+  - Applying “tags” directly to cloud buckets using your object storage provider’s dashboard
+
+Use the links below to **learn** about the many POSIX Modes, options, and settings — and then **enable** the correct POSIX Mode for you use case:
+
+| **Linux Next Steps** | **Description** |
+|----------------------|-----------------|
+| **Learn about** [POSIX Options](docId:cbm3PcQXmLpuYcbg) | Understanding POSIX Modes in Object Mount for Linux |
+| **Enable** [POSIX File Access](docId:cbm3PcQXmLpuYcbg#posix-file-access) | Enabling POSIX File Access Mode in Object Mount for Linux |
+| **Enable** [Enforced POSIX File Access](docId:Eegoo1teiJ8eerae) | Enabling _Enforced_ POSIX File Access Mode in Object Mount for Linux |

app/(docs)/object-mount/appendix/_meta.json

@@ -0,0 +1 @@
+{"title": "Appendix", "weight": 10}

app/(docs)/object-mount/appendix/core-concepts/page.md

@@ -0,0 +1,59 @@
+---
+title: Core Concepts
+hideTitle: false
+docId: xzAqS9Um7xjQSbmD
+weight: 1
+redirects:
+  - /object-mount/linux/user-guides/core-concepts
+metadata:
+  title: Core Concepts
+  description:
+    Core concepts of Object Mount.
+hidden: false
+---
+
+## Characteristics of Object Storage
+
+Object storage excels at high-throughput use-cases and is often considered best for “write-once, read-many” models. 
+
+Direct file editing with object storage is traditionally seen as too slow and often requires gateways, proprietary translations, and each file often needs to be completely rewritten — even for the slightest modification.
+
+Additionally, object storage technology differs significantly from the conventional block-and-file I/O calls used by local drives and network-attached solutions — especially for applications that expect strict POSIX compliance.
+
+Storj’s Object Mount solves these shortcomings, redirecting and translating file access calls, simplifying cloud storage implementations, and delivering the highest possible performance from your object storage. POSIX compliance and unique optimizations ensure compatibility and improve performance enabling fast editing and file access directly from the cloud.
+
+
+## Direct Use of Object Storage
+
+Object Mount enables the use of object storage as “hot storage” or as “first-class” storage.
+
+Prior to Object Mount, content workflows required you to “pre-stage” your files by copying content from the cloud down to local, faster drives. You would then run your tasks locally. When finished, you re-uploaded the resulting content back up to object storage to share with your team.
+
+Object Mount’s elegant simplicity and improved performance means you can now run your tasks _directly_ on your files in object storage — just mount and go.
+
+Object Mount overcomes the traditional inefficiencies of direct access to object storage by using prediction engines, partial writes, client-side write-caching and other optimizations to achieve much higher performance. Use your cloud storage like it was local storage.
+
+
+## Read/Write Interception
+
+Once installed, Object Mount transparently inserts itself between your applications and your host operating system. Object Mount dynamically detects and intercepts relevant file and system calls made by your application and redirects those requests to your object storage provider. This is called **Direct Interception**.
+
+Direct Interception also facilitates the translation of your application’s standard file system calls (reads and writes) into the appropriate object storage API calls.
+
+This enables _any_ application to instantly access cloud objects as if they were local files — no code changes or workflow alterations required. Object Mount intercepts file commands from _any_ application, binary or EXE, including those you’ve written yourself. It even works inside unprivileged containerized environments like Docker and virtual environments such as Hyper-V and Virtualbox.
+
+
+## What Object Mount Does
+
+- Provides applications high-speed access to object storage content as if it were a local drive
+- Allows standard file system operations to list, copy, move, add, remove, and modify files directly on object storage
+- Supports rich POSIX metadata including: users, groups, permissions, symbolic & hard links
+- Preserves NFS-equivalent POSIX consistency guarantees
+
+
+## What Object Mount Does NOT Do
+
+- Object Mount does _not_ interfere with how applications interact with local drives and any other non-S3 object data
+- Object Mount does _not_ alter or change the representation of your files on object storage — file data is not modified. This means your content can be accessed directly from your object storage using standard S3 tools and dashboards, bypassing Object Mount at any time.
+
+  **Note:** Content accessed _directly_ on your object storage (rather than through Object Mount) bypasses Object Mount’s consistency guarantees.

app/(docs)/object-mount/appendix/faq/page.md

@@ -0,0 +1,47 @@
+---
+title: FAQ
+hideTitle: false
+docId: dd27e33c-7804-4e15-bdc5-941f9a1a7e12
+weight: 10
+redirects:
+  - /object-mount/faq
+metadata:
+  title: Frequently Asked Questions
+  description:
+    Resource on various FAQs on topics related to Object Mount.
+hidden: false
+---
+
+## What S3 permissions are recommended to mount a bucket with Object Mount?
+Short answer, for a generic cloud: read, write, and list permissions for the bucket intended to be mounted.
+
+## Are full permissions required to achieve maximum performance of Object Mount?
+The maximum performance comes from Object Mount’s ability to prefetch data based on how it handle certain file types. It is not dependent on being able to write the POSIX-metadata file. With read-only permissions to a bucket, Object Mount will still achieve maximum performance — but it will not be able to update any POSIX-related metadata associated with the original files.
+
+## Why don’t read-only credentials work when POSIX is enabled in Object Mount?
+The POSIX mode needs to write a hidden file at the root of the bucket that tracks all the POSIX permissions, etc. This is why the read-only use case works _so long as_ you mount the bucket without POSIX enabled.
+
+## How can I mount all buckets with Object Mount?
+In order for Object Mount to “see” the buckets to be mounted when adding new credentials into Object Mount, the AWS equivalent of `ListAllMyBuckets` is required. In the absence of `ListAllMyBuckets`, you can specify what bucket to mount by manually pairing the bucket.
+
+## Where can I find the Object Mount logs?
+For Windows, logs are available at `C:\Users\%username%\AppData\Local\Object Mount\cunofs.log`.
+
+For macOS the logs are located at `/Users/$USER/Library/Application Support/Object Mount/cunoFS.log`.
+
+The default logging level is “error”, so changing this to “access” or “trace” will provide more verbose logs to better understand what is going on.
+
+## Where are the configs and license files located?
+For Windows:
+  - License key information is located along side the logs: `C:\Users\%username%\AppData\Local\Object Mount\license`.
+  - The `config.json` file is in the same directory where the mount/bucket information is kept
+
+For macOS:
+  - License key information is located along side the logs: `/Users/$USER/Library/Application Support/Object Mount/license`.
+  - The `config.json` file is in the same directory where the mount/bucket information is kept
+
+## I have multiple Mounts added but I can pnly activate one at a time?
+
+  - Object Mount for both Windows and Mac can only have **one active** mount at a time.
+  - Activating a second mount, will automatically de-activate the previously active mount.
+

app/(docs)/object-mount/appendix/release-notes/page.md

@@ -0,0 +1,15 @@
+---
+title: Release Notes
+hideTitle: false
+docId: ScTuUGKGH5DHVqZF
+weight: 11
+redirects:
+  - /object-mount/release-notes
+metadata:
+  title: Object Mount Release Notes
+  description:
+    Access to Object Mount Release Notes.
+hidden: false
+---
+
+Release notes for Object Mount can be found on our [GitHub page](https://github.com/storj/object-mount/releases).

app/(docs)/object-mount/appendix/s3-compatibility/page.md

@@ -0,0 +1,46 @@
+---
+title: Supported S3 Providers
+hideTitle: false
+docId: xCjeasn8SLQn2vfd
+weight: 4
+metadata:
+  title: Supported S3 Providers
+  description:
+    List of tested and supported s3 Providers.
+hidden: false
+---
+
+Object Mount can be used with any S3-compatible object storage provider, including these **Primary S3 Providers**:
+
+  - 🌐 [Storj’s Object Storage](https://www.storj.io/cloud-object-storage)
+  - 🌐 [Amazon Web Services S3](https://aws.amazon.com/s3/)
+  - 🌐 [Microsoft Azure Blob Storage](https://azure.microsoft.com/en-gb/services/storage/blobs/)
+  - 🌐 [Google Cloud Platform](https://cloud.google.com/storage/) 
+    - **Note:** For best GCP performance, we recommend using S3 with their 🌐 [S3 Access Point](https://cloud.google.com/storage/docs/interoperability), _not_ with their S3 Gateway.
+
+
+## Tested Storage Providers
+
+In theory, Storj’s Object Mount works with _any_ S3-compatible object storage provider. 
+
+In practice, each provider’s “S3-compatible API” implementation can have slightly different nuances and behaviors — some additional configuration may be necessary. 
+
+Object Mount has been successfully tested with the **Compatible S3 Providers** below:
+
+  - 🌐 [Oracle Cloud Infrastructure (OCI) Object Storage](https://www.oracle.com/cloud/storage/object-storage)
+  - 🌐 [Wasabi Cloud Object Storage](https://wasabi.com/cloud-object-storage)
+  - 🌐 [Min.IO AIStor](https://www.min.io/product/aistor)
+  - 🌐 [NetApp StorageGRID](https://www.netapp.com/data-storage/storagegrid)
+  - 🌐 [Dell ECS Object Storage](https://www.dell.com/en-us/lp/dt/elastic-cloud-storage)
+
+
+## Additional S3 Providers
+
+The following S3 storage providers have not yet been validated by Storj — however, users have reported success with the **Additional S3 Providers** below:
+
+  - 🌐 [IBM Cloud Object Storage](https://www.ibm.com/cloud/object-storage)
+  - 🌐 [Backblaze B2 Cloud Storage](https://www.backblaze.com/cloud-storage)
+  - 🌐 [DigitalOcean Spaces](https://www.digitalocean.com/products/spaces)
+  - 🌐 [Cloudflare R2](https://www.cloudflare.com/en-gb/developer-platform/r2)
+  - 🌐 [Scality](https://www.scality.com)
+  - 🌐 [DataDirect Networks (DDN) Storage](https://www.ddn.com)