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.

Archil requires that you specify a list of “Disk Users” who are authorized to connect to your disk. When attempting to mount your Archil disk, only these users will be allowed access. There are multiple ways that you can authorize a user to connect to an Archil disk. The correct method will depend on the location of your Archil disk and the location of the server which wishes to mount the disk.
Archil enforces POSIX permissions for files and folders. However, we do not recommend that you rely on POSIX permissions as a security boundary between untrusted users. Archil does not limit the access of “Disk Users” beyond what POSIX enforces.
Disk tokens are not API keys. A disk token grants access to a single disk — it’s what a client presents when mounting or connecting. An API key authenticates requests to the Control Plane API for managing disks, mounts, and users. The two are created in different places and used in different contexts. This page is about disk tokens.

​
Which method should I use?

Use IAM role authorization if you’re mounting from an EC2 instance — no extra credentials needed. For everything else, use a disk token.

​
Authentication methods

We recommend using IAM Authorization whenever you are mounting an Archil disk located in AWS from a server that is located in the same AWS Region.

​
AWS role authorization

Archil natively supports using AWS IAM users or roles to authorize access to the disk. This is the recommended authorization method when mounting from AWS EC2 instances in the same region as your disk. Archil disks perform IAM authorization by matching the ARN of the mounting role to the list of that disks’ authorized users. As a result, your IAM user or role does not need any specific Archil permissions in its policy.

​
Setup steps

  1. Get your EC2 server’s IAM role ARN using the following command:
archil utils get-iam-role
  1. Copy the resulting IAM role ARN.
  2. Return to the disk’s Details page in the Archil console, and paste the role ARN as an Authorized User.

​
Mounting with IAM authentication

When using IAM authentication, mount your disk without specifying a disk token:
When using AWS IAM Roles Anywhere, you must set the AWS_EC2_METADATA_SERVICE_ENDPOINT and AWS_REGION environment variables before mounting. These can be set inline with the mount command or exported in your shell session.
sudo archil mount <disk-name> /mnt/data --region <disk-region>
The Archil client will automatically use your EC2 instance’s IAM role for authentication.

​
Disk token authorization

Outside of AWS, or when mounting from a different region, Archil can issue a disk token — a static credential scoped to a single disk.

​
Setup steps

  1. Navigate to the disk’s Details page in the Archil console
  2. Click Generate Token to create a new disk token
  3. Copy the disk token — you’ll need it when mounting the disk
  4. Keep the disk token secure; it grants full access to this disk
Archil does not store disk tokens in plaintext. Save the disk token somewhere secure when it’s created — it will not be visible again from the Archil console. If you lose it, generate a new one.

​
Mounting with a disk token

Set the ARCHIL_MOUNT_TOKEN environment variable to your disk token and pass it through sudo: 
export ARCHIL_MOUNT_TOKEN="<disk-token>"
sudo --preserve-env=ARCHIL_MOUNT_TOKEN archil mount <disk-name> /mnt/data --region <disk-region>
Using --preserve-env=ARCHIL_MOUNT_TOKEN passes the disk token through sudo’s environment rather than the command line, preventing it from being visible in process listings (ps aux). This is more secure than both sudo -E (which passes all environment variables) and inline assignment (which exposes the token in the process list).
The TypeScript SDK reads the same disk token from the ARCHIL_DISK_TOKEN environment variable (or the authToken connection option). Despite the different variable names, ARCHIL_MOUNT_TOKEN and ARCHIL_DISK_TOKEN refer to the same kind of credential — the disk token you generated above.