Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.archil.com/llms.txt

Use this file to discover all available pages before exploring further.

Shared disks are useful whenever multiple machines need access to the same data. Common examples include multiple inference servers sharing cached model weights so each new instance avoids a cold download from S3, or a fleet of log collectors writing to different subdirectories of a single disk for centralized storage. Any workload where several servers read the same reference data, or partition writes by directory, is a good fit for shared disks. Archil supports sharing disks between multiple servers simultaneously. This allows, for example, a single application to share a disk filled with reference data, or provide an infinite location to write logs. To enable mounting a disk from multiple Archil clients, you should mount with the --shared flag on each server. Every file or folder on an Archil disk can always be read from multiple servers simultaneously. However, to support local-like performance, only a single Archil client can edit any particular file or folder — including file creation, renaming, or deletion — at a time. Archil disks introduce the concept of “ownership” to track which Archil client has exclusive access to a particular file or folder. By default, when a client mounts an Archil disk, it requests ownership of the entire disk, and other clients cannot perform the same mount. When you mount with the --shared flag, the Archil client does not request ownership of the entire disk, allowing multiple clients to mount the same disk. You can then use the granular checkout and checkin commands, as detailed below, to track which Archil clients have exclusive access to which files and folders.
Using checkin and checkout on shared disks is, today, mandatory outside of the dynamic ownership rules. We’re actively working on making checkin/checkout optional for workloads which do not need performance better than a traditional NFS disk. To be notified when ownership is no longer mandatory, please email Archil support.

​
Ownership rules

When an Archil client has “ownership” over a directory, it automatically has recursive ownership over all of that directory’s children. For example, if a client owns the /group/models directory, then it also owns all files and subdirectories within /group/models. Conversely, no client can have ownership of the / or /group directories, as this would conflict with the first client’s ownership claim on /group/models.
Example File Structure
/(cannot be owned)
group/(cannot be owned)
models/(owned by client A)
model1.txt
model2.txt
data/(ownership available)
data.txt
When you unmount the file system with archil unmount, the client automatically releases all of its ownership claims on the file system, to allow another server to use the disk.

​
Ownership management

The Archil client supports two commands for managing ownership at a file or directory level: checkout and checkin.

​
Requesting ownership with checkout

To get exclusive access to a file or directory, use the checkout command: 
# Get a delegation on a specific file
archil checkout /path/to/file.txt

# Get a delegation on a directory (includes all contents)
archil checkout /path/to/directory/

​
Releasing ownership with checkin

When you’re done with exclusive access, release the delegation: 
# Release delegation on a specific file
archil checkin /path/to/file.txt

​
Dynamic ownership rules

Some operations, such as when creating a file/directory or opening a file for write, automatically handle ownership if you attempt to use them in a directory that’s not currently owned by any client. For example, when calling mkdir in a directory that is not owned by any client, the Archil server will create the directory (if no conflicting directory exists) and grant ownership to the client. Using our earlier example, any client can create a new directory in /, /group, or /data and receive ownership over the new directory. 
# Create a new directory in a directory that is not owned by any client
mkdir -p /mnt/data/group/new_dir
Dynamic ownership supports creating new files and directories, but does not support removing existing files or directories. Therefore, it’s possible to (on a shared disk) run a mkdir and then not be able to call rm on the folder. In order to remove the created file, your client will need to checkout the parent directory.

​
Viewing current delegations

To view the set of files and directories that your Archil client has current ownership over, use the delegations command. 
# List all your current delegations
archil delegations /mount/point

​
Forcing ownership

In some cases, your client may not be able to release ownership over a file or directory that it’s no longer using. For example, if your cloud instance has a power failure and does not cleanly unmount the file system. If this happens, the Archil server will continue to believe that the original client maintains its ownership claim, and no other client will be able to edit the directory. To take ownership over part of the file system regardless of whether other clients have an outstanding ownership claim, you can use the checkout command with the --force flag. 
# Force checkout (revokes conflicting delegations)
archil checkout /path/to/file.txt --force
When using the --force flag, the Archil server will revoke ownership from other clients immediately. If those clients have outstanding writes which have not yet been fsynced to the disk, then those writes will be lost, and the eventual call to fsync will fail with EIO.