archil CLI to mount an Archil disk locally to an already running Linux server — such as an Amazon EC2 instance,
a microVM sandbox, or a VPS.
Archil is compatible out-of-the-box with all programs that run on Linux, such as git, SQLite, or ffmpeg. For more details, see
Application compatibility.
This article is for servers which are running their own Linux kernel. If you’re trying to mount Archil into a container
such as Docker, Podman, or a container platform (such as Amazon ECS) see Mount in a container.
How the client mounts
The Linux client is a FUSE file system.archil mount runs in user space, serves the mount through the kernel’s FUSE device, and talks to Archil’s servers over Archil’s own file protocol, encrypted with TLS. It doesn’t use NFS or SMB, so no NFS client or kernel module other than FUSE is needed. On macOS, the client mounts through Apple’s FSKit instead; see Mount on macOS.
Requirements
Any Linux host can mount an Archil disk witharchil mount if it meets these requirements. This applies to VMs,
containers, and other providers’ sandboxes alike.
A mounted disk persists only what is written under its mount point. The rest of the host’s filesystem, including
packages you installed, stays on the host. In Archil sandboxes,
the root filesystem is itself on an Archil disk.
Where mounting works
Where you can’t mount, you can still use the disk without FUSE or root: run commands next to it with
serverless execution, or read and write files with the
TypeScript or Python SDK or
the S3 API.
Mount a disk
1
Install the client
The
archil client provides support for mounting Archil disks on Linux. First, install it on your server:2
Authorize your server
Each server that connects to the Archil disk needs to be authorized. You can managed which servers are authorized
in the Archil console, by navigating to the disk that you want to use, then selecting Connections in the left-bar,
and clicking Add User to authorize a new server.Select Disk Token, and save the token somewhere you can retrieve it, you will not be able to see it again.
Archil disks also support IAM authentication for users mounting from within AWS. For more details on how disks
authenticate users, see Disk users.
3
Mount the disk
First, create the directory that you intend to use to mount Archil:Using the token that you just saved from the console, you can now mount the disk with
archil mount./mnt/archil, and running commands.
Upgrading the client
Thearchil CLI prints a notice when a newer release is available. To upgrade, run:
archil config.
Disk ownership
By default, new Archil disks are owned by the root user (Linuxuid:0). When you mount your disk to a folder such as
/mnt/archil, that folder will become owned by the root user.
When not running as the root user, you will see EACCES: Permission denied for file operations. You can change the owner
of the root directory with the command:
sudo chown "$(id -u):$(id -g)" /mnt/archil
The ownership change persists on the disk.
Mounting on multiple hosts
By default, your disk is mounted in exclusive-ownership mode, and a second server can only mount it with--read-only.
To write to the disk from several servers, mount it on each one with --conditional or --shared. See
Sharing Disks for how the modes compare.
When you mount an Archil disk with --conditional, every server can write to any part of the disk without calling
archil checkout. See Conditional mode for how writes from several servers
interact.
When you mount an Archil disk with --shared, each server can only write to paths it holds a delegation on. Creating a
file or directory, or opening a file for writing, takes one automatically; for anything else, call archil checkout <path>
before writing and archil checkin <path> after. Otherwise, the operation fails with EROFS: Read-only file system.
Each server caches what it reads, so it can briefly serve an older version of a file another server changed. See
Consistency for the exact rules.
Ensuring that data is persisted on shutdown
Like all local file systems, Archil automatically stages recently written data in-memory until an explicitfsync or a periodic
background flush job writes it to durable storage. This means that recently-written data may not be persisted if a machine
is unexpectedly powered off.
Archil sandboxes automatically manage this persistence on shutdown. On other sandbox providers, make sure that you explicitly
call archil unmount before powering off the sandbox. See Crashes and forced ownership
for what a client that stops without unmounting loses and leaves behind.
We recommend always using archil unmount instead of the built-in Linux umount command, which does not automatically flush
data to Archil’s servers.
Mount automatically on startup
If your service automatically launches new instances, such as in a load-based auto scaling group, you’ll want to ensure that new servers automatically mount Archil at startup. In addition to service startup scripts, you can achieve this by adding Archil to the server’s/etc/fstab with a line like the following:
<disk-name>: An owner-qualified disk name (organization/disk-nameoremployee@email.com/disk-name) or disk ID (dsk-0123456789abcdef).<mountpoint>: Local directory where the disk should be mounted (e.g.,/mnt/archil).archil: Filesystem type for Archil disks._netdev: Tells systemd this is a network filesystem that needs network connectivity before mount.region=<region>: The region your disk is in (e.g.,aws-us-east-1).