CraftFileGate

CraftFileGate is a file server: an SFTP client, an HTTP script or a browser puts files on it and takes files from it, and the server stores them on one or more storages. It replaces a classic SFTP server (ProFTPD, OpenSSH internal-sftp) when the files do not all live on a local disk, or when the accounts come from an identity provider.

What it does

The words of this guide

The chapter Users, roles and mounts explains them with examples.

Quick start

A server on a local disk, a user alice who sees only her directory.

1. Generate a host key

ssh-keygen -t ed25519 -f /etc/craft-file-gate/host_ed25519 -N ""

A key listed in host_keys but missing refuses startup.

2. Write the configuration

Create /etc/craft-file-gate/config.toml:

#:schema ./config.schema.json
[server]
shutdown_grace_period_secs = 30
# max_sessions_per_user = 10  # optional, unlimited by default

[sftp]
listen = "0.0.0.0:2222"
host_keys = ["/etc/craft-file-gate/host_ed25519"]
# login_grace_secs = 120      # unauthenticated connection cut after this (0 = never)

[auth]
jwt_sentinel_username = "jwt"
timeout_secs = 5
# roles_file = "/etc/craft-file-gate/roles.toml"  # optional, otherwise inline [[roles]]
# authz_base_url = "https://authz.internal"  # optional, remote mapping service

[auth.jwt]
secret = "changez-moi-en-production"
# public_key_file = "/etc/craft-file-gate/jwt_public.pem"  # alternative to the secret
# jwks_url = "https://idp.interne/.well-known/jwks.json"   # alternative: identity provider keys
# jwks_refresh_interval_secs = 3600                        # default, minimum 1
# username_path = "/sub"       # default
# authorities_path = "/groups" # default

[auth.methods]
jwt   = { enabled = true }
# Password and public key are proofs of the local store, not separate
# methods: you declare them under `local`.
local = { enabled = true, password = true, pubkey = true }

[admin]
listen = "127.0.0.1:8080"
bearer_token = "changez-moi-en-production"

[log]
level = "info"
format = "json"

# ── Storage and rights ──
[[backends]]
name = "local"
type = "local"
root = "/srv/sftp"

[[roles]]
name = "utilisateurs"

[[roles.mounts]]
backend = "local"
home_dir = "/{username}"   # alice sees /srv/sftp/alice as her root /
create_home = true

[[roles.mounts.acl]]
path = "/"
rights = ["read", "write", "list", "delete", "rename"]
recursive = true

# ── Local users ──
[[users]]
username = "alice"
# password: changez-moi-en-production
password_hash = "$argon2id$v=19$m=19456,t=2,p=1$QzIrOEdtBZI4UL4ddXDbkg$yudDYsZSLamFZHWeKlFpFWtkP4kX6ALV8GNKs3pEXBk"
# authorized_keys = ["ssh-ed25519 AAAA... alice@poste"]
authorities = ["utilisateurs"]

The JWT secret, the admin token and alice’s password (changez-moi-en-production) are public. The server starts with them, but emits one WARN per example value still in place. To replace alice’s [[users]] block:

echo -n "mot-de-passe" | craft-file-gate hash-password --user alice

The process must be able to write to /srv/sftp: create_home creates alice/ there at her first login.

3. Start the server

craft-file-gate --config /etc/craft-file-gate/config.toml

For Docker and Kubernetes, see the guide (“Operating”).

4. Connect

sftp -P 2222 alice@votre-serveur

ls shows the content of /srv/sftp/alice, and nothing above it.

What next

Users, roles and mounts

user ──authorities──▶ role ──▶ mount ──▶ backend (storage)
                                │
                                └── ACL (rights per path)

No right is implicit: a backend that no role mounts is visible to nobody, and the admin token gives access to no file.

A complete example

[[backends]]                 # one storage, described once
name = "disque"
type = "local"
root = "/srv/sftp"

[[roles]]
name = "utilisateurs"

[[roles.mounts]]             # at least one per role
backend = "disque"           # a [[backends]] name
home_dir = "/{username}"     # where the mount starts on the storage
create_home = true

[[roles.mounts.acl]]         # the rights, relative to the mount
path = "/"
rights = ["read", "write", "list", "delete", "rename"]
recursive = true

[[users]]
username = "alice"
password_hash = "$argon2id$..."   # craft-file-gate hash-password
authorities = ["utilisateurs"]    # alice's roles

alice sees /; this / is /srv/sftp/alice on the disk.

The keys of a role and of a mount

All the keys, with their hot reload: Reference [[roles]], [[roles.mounts]].

Where the files go

A client path goes to the mount whose mount_path is its longest prefix; the rest is appended to home_dir, on the storage (what home_dir points to on each type). .. never climbs above home_dir.

{username}: one directory per user

home_dir = "/{username}" gives each user their own directory, with a single role. The name, never sanitized, is made of A-Z a-z 0-9 . _ -, 1 to 64 characters, with no leading dot.

One mount or several

The paths between mounts are synthetic directories. A rename stays within its mount.

Combining roles

A user often has several roles. Their session has the mounts of all of them.

Two different mounts of the same backend have disjoint home_dir values (/a and /b, not / and /a): each file is reached under one ACL only.

The doctrine: a role at / is complete

• a role at / is complete: on its own it gives everything its user sees, and it combines with no other;
• a role meant to be combined mounts under a name (/archives).

See the recipes.

Where roles come from

Roles are always defined in [[roles]] or roles_file. Only the authorities that are not role names go to the service.

The authorization service contract

POST <authz_base_url>/authz/resolve
Content-Type: application/json

{"authorities": ["CN=ACME-Partners,OU=Groups"]}

Expected response: 200 and

{"roles": ["partenaire-acme"]}

authz_base_url and timeout_secs: Reference [auth].

The named roles are added to those found locally; a name that [[roles]] does not define is ignored, and a service that is down leaves the local roles.

An SFTP session builds all its backends at authentication and keeps its mounts until it ends, even after a hot reload; a REST request builds the backend of the mount it reaches.

What you will see

A role that mounts several backends holds their credentials: keep it read only, for a dedicated user authenticated by key.

Mount recipes

Each recipe assumes this backend:

[[backends]]
name = "disque"
type = "local"
root = "/srv/sftp"

1. One directory per user

[[roles]]
name = "utilisateurs"

[[roles.mounts]]
backend = "disque"
home_dir = "/{username}"
create_home = true
acl = [{ path = "/", rights = ["read", "write", "list", "delete", "rename"], recursive = true }]

alice sees / = /srv/sftp/alice, created at her first login. A role at / does not combine.

2. A partner: inbound drop, outbound pickup

The partner drops into /in without being able to read back, and picks up from /out.

[[roles]]
name = "partenaire-acme"

[[roles.mounts]]
backend = "disque"
home_dir = "/partenaires/acme"
max_file_mb = 500
hidden_stores = { enabled = true, prefix = ".in.", extension = "" }
acl = [
  { path = "/in", rights = ["write", "list"], recursive = true },
  { path = "/out", rights = ["read", "list", "delete"], recursive = true },
]

/in is /srv/sftp/partenaires/acme/in; an upload there is published at the end of the transfer.

For ls / to show in and out, add a non-recursive entry: path = "/", rights = ["list"].

3. The operations account: every storage, read only

An account that sees each backend at the root and cannot modify anything.

[[backends]]
name = "archives"
type = "s3"
bucket = "archives"
region = "eu-west-3"
prefix = "sftp/"
credentials = { type = "iam_role" }

[[backends]]
name = "acme-amont"
type = "sftp"
host = "sftp.acme.example"
host_key_fingerprint = "SHA256:2hZbXq1b5Xb3vN2mQ6w7l3Fv0tXk4yJ8aUeYp9rS0cE"   # ssh-keygen -lf, checked out of band
auth = { type = "password", username = "relais", password = "changez-moi" }

[[roles]]
name = "exploitant"

[[roles.mounts]]
backend = "disque"
mount_path = "/disque"
acl = [{ path = "/", rights = ["read", "list"], recursive = true }]

[[roles.mounts]]
backend = "archives"
mount_path = "/archives"
acl = [{ path = "/", rights = ["read", "list"], recursive = true }]

[[roles.mounts]]
backend = "acme-amont"
mount_path = "/acme-amont"
home_dir = "/depot"
acl = [{ path = "/", rights = ["read", "list"], recursive = true }]

[[users]]
username = "exploitation"
password_hash = "$argon2id$..."   # of a random, discarded password: only the key is used
authorized_keys = ["ssh-ed25519 AAAA... exploitation@poste"]
authorities = ["exploitant"]

ls / shows acme-amont archives disque; /archives/2024/x is the S3 key sftp/2024/x.

At startup, INFO role mounts several backends: ... gives role=exploitant and writable=[]: check it after each change to the role.

4. Roles that combine

[[roles]]
name = "equipe-a"
[[roles.mounts]]
backend = "disque"
mount_path = "/equipe-a"
home_dir = "/equipes/a"
acl = [{ path = "/", rights = ["read", "list"], recursive = true }]

[[roles]]
name = "equipe-b"
[[roles.mounts]]
backend = "disque"
mount_path = "/equipe-b"
home_dir = "/equipes/b"
acl = [{ path = "/", rights = ["read", "write", "list"], recursive = true }]

A token whose groups claim is ["equipe-a", "equipe-b"] opens a session with /equipe-a (read) and /equipe-b (read and write).

Two roles on the same mount merge their ACLs: acme-depot (/in) and acme-releve (/out) on the mount of case 2 give /in and /out.

5. Organized mounts: /partenaires/<name>

With acme-amont from case 3:

[[roles]]
name = "gestion-partenaires"

[[roles.mounts]]
backend = "disque"
mount_path = "/partenaires/acme"
home_dir = "/partenaires/acme"
acl = [{ path = "/", rights = ["read", "list"], recursive = true }]   # "/": the root of the mount

[[roles.mounts]]
backend = "acme-amont"
mount_path = "/partenaires/amont"
home_dir = "/depot"
acl = [{ path = "/", rights = ["read", "list"], recursive = true }]

/ and /partenaires are synthetic; /partenaires/amont is the upstream’s /depot.

ACL

The ACL of a mount grants rights, path by path; everything else is refused. It is written under [[roles.mounts.acl]], and its path is relative to the mount.

Writing an ACL

[[roles.mounts]]
backend = "disque"
mount_path = "/partenaire"
home_dir = "/partenaires/acme"

[[roles.mounts.acl]]
path = "/"                    # /partenaire for the user
rights = ["list"]             # not recursive: this folder only

[[roles.mounts.acl]]
path = "/in"                  # /partenaire/in
rights = ["write", "list"]
recursive = true              # and everything below it

All the keys: Reference [[roles.mounts.acl]].

An ACL governs only its own mount, even on a backend mounted twice.

The rights

Each operation requires its right on each path it names:

A listing shows the whole directory, without filtering by the ACL. list on /in does not give list on /.

Which entry decides

1. Refusal by default: a path that no entry governs is refused.
2. The most specific entry decides: the one for the exact path, otherwise the closest recursive entry above it.
3. A more specific entry that does not grant the right refuses, even under a broader entry that grants it.

[[roles.mounts.acl]]
path = "/"
rights = ["read", "write", "list", "delete", "rename"]
recursive = true

[[roles.mounts.acl]]
path = "/archives"
rights = ["read", "list"]
recursive = true

Here everything is writable, except /archives and its content, read only.

A move is judged again on what it carries: a folder that contains a protected subfolder does not move to a place governed by a broader entry, where the subtree would lose its protection.

Several roles on one mount

Two roles on the same mount put their ACLs together:

• two entries at the same path merge their rights, and a single recursive makes the union recursive;
• at different paths, the most specific entry decides, whichever role it comes from.

A narrow entry from one role can therefore restrict what a broad entry from another granted. The result is shown in the console, in the roles tab of a session (GET /admin/sessions/<id>/roles).

Synthetic directories

With several mounts under names, a path under no mount (/, /partenaires) is synthetic: it belongs to no backend.

A mount point (/partenaires/acme) is listed according to its ACL, but is not written, deleted or renamed.

Name case

When a backend’s ACL folds case (case_insensitive), /Archives and /archives are a single path: write it once per mount.

Doors: SFTP, REST API, file explorer, admin console

The file doors (SFTP, REST API, file explorer) share users, roles, mounts and ACLs: a right granted is granted everywhere. The admin console opens no file. SFTP holds sessions; the REST API has none, and the console shows its long transfers in progress (its activity).

SFTP

[sftp]
listen = "0.0.0.0:2222"
host_keys = ["/etc/craft-file-gate/host_ed25519"]

• Only the sftp subsystem is served: no shell, no scp, no exec, no port or agent forwarding.
• With JWT: the sentinel name (jwt by default) and the token as password, sftp -P 2222 jwt@serveur.
• The keys: The SFTP door.

REST file API

[admin]
listen = "0.0.0.0:8080"
bearer_token = "changez-moi-en-production"

[api]
enabled = true
prefix = "/api/v1/files"

# list a directory
curl -u alice:mot-de-passe 'http://serveur:8080/api/v1/files/in?list'
# upload a file
curl -u alice:mot-de-passe -T rapport.csv http://serveur:8080/api/v1/files/in/rapport.csv
# download
curl -u alice:mot-de-passe -o rapport.csv http://serveur:8080/api/v1/files/in/rapport.csv

All the keys: Reference [api].

• One credential per request; no cookie, no session.
• A downloaded file goes out as attachment, Cache-Control: no-store, Content-Security-Policy: sandbox, Accept-Ranges: bytes. A leaked ticket URL downloads that file until it expires.

Web file explorer

[api.ui]
enabled = true
path = "/files"

A page at http://serveur:8080/files, a client of the API: same credentials, same ACLs. See File explorer.

Admin console and API

[admin]
listen = "127.0.0.1:8080"
bearer_token = "changez-moi-en-production"
# control_listen = "127.0.0.1:8081"   # a separate door for administration

The console is at / of the admin listener: sessions and mounts, bans, configuration without secrets, logs, metrics, revocations. You log in with a username and password, or with a token. /metrics and the probes are on the same listener, or on control_listen, or on [server] probes_listen: see One door or two.

What you will see

Backends

A backend is a named storage, described once in [[backends]]; mounts refer to it by name.

[[backends]]
name = "disque"        # the name that mounts refer to
type = "local"         # local, sftp, s3 or webhdfs
root = "/srv/sftp"     # the type-specific keys

[[roles]]
name = "utilisateurs"

[[roles.mounts]]
backend = "disque"
home_dir = "/{username}"
acl = [{ path = "/", rights = ["read", "write", "list"], recursive = true }]

[[backends]] are written in config.toml or in roles_file, where they are reloaded at runtime with the roles.

The types

The published binaries and images carry all four types (The binary’s features).

The keys of every backend

All keys: Reference [[backends]].

A subtable ([backends.auth], [backends.credentials]) attaches to the [[backends]] before it: write it right after it. GET /admin/config and the Configuration tab show each backend, secrets replaced by ***.

Keys common to all types

What they do on each type is on the type’s page; their default and their effect, in the same Reference.

hidden_stores resolves from the mount, then the backend, then [server.hidden_stores]; stale_partials from the backend, then [uploads.stale_partials]; key by key (Uploads).

Reservation across instances

The first upload to a destination holds it until it ends (why). Across instances, this is a lock <lock_prefix><name> placed next to the destination. lock_prefix:

• is 8 characters to 64 bytes long, with no / and no control character;
• also names the server’s throwaway names (PPnew.<token>, PPprobe., PPstale. for a prefix P);
• reserves for the server any name that starts with it, regardless of case, like .craftfilegate-upload...: choose one that no user file carries.

Availability

Each instance visits each backend in the background ([server.backend_probe]): up, down after failures_before_down failed visits, unknown before the first one; a WARN at each change (Troubleshooting), the state in GET /admin/health, the Instances view and craftfilegate_backend_up (Metrics). On S3, a visit is a billed ListObjectsV2, every 15 s per instance by default.

Local

The local backend serves a directory of the server’s file system, its root (root). Each mount has its own subdirectory there, home_dir.

[[backends]]
name = "disque"
type = "local"
root = "/srv/sftp"

[[roles]]
name = "utilisateurs"

[[roles.mounts]]
backend = "disque"
home_dir = "/{username}"
create_home = true
acl = [{ path = "/", rights = ["read", "write", "list", "delete", "rename"], recursive = true }]

alice uploads /rapport.txt: the file is /srv/sftp/alice/rapport.txt.

The keys

All keys: Reference [[backends]] type = “local”; common keys: Backends.

The root and symbolic links

No operation leaves the mount’s root + home_dir, whatever links are there, including what the server does itself (in-flight file, lock, sweep). A link to another mount’s home_dir leaves it just as much as a link outside the root.

• A link is listed as a link (type l; "is_symlink": true in REST), or, when followed, as its target. Deleting or renaming acts on the link.
• With hidden_stores, an upload onto a file link replaces the link; the target stays intact.
• No door creates links: they come from another process or a restore.
• The root and its ancestors are trusted (a root through a link is followed): writable by the administrator only.
• On a shared volume (NFS…), mount the root nosymfollow (Linux 5.10 and later).

Case of ACL paths

On a storage that ignores case (NTFS, APFS and HFS+ by default, SMB/CIFS, ext4 or tmpfs casefold), the ACL compares folded paths: NFD, removal of ignorable code points (U+200B…), full case folding (straße = strasse), NFC.

The probe creates a lowercase file and looks for it in uppercase in each directory where an entry resolves (folding is set per directory, chattr +F): one folding directory makes the backend fold, an inconclusive result counts as folding. A missing directory or one under {username} is not probed, and a case-sensitive APFS volume stays insensitive to normalization: when in doubt, case_insensitive = true.

Where the ACL folds, and on a Windows server, a short 8.3 name (PROTEG~1) or one ending in . or a space is not a valid path: disable short names (fsutil 8dot3name).

The common keys on a local backend

The process acts under its own uid; file modes follow its umask.

On Linux 5.6 and later, the kernel enforces the confinement (openat2(2), RESOLVE_BENEATH); without openat2, each component is opened O_NOFOLLOW (reported once as INFO); on Windows, the parent is checked just before the call.

Performance and limits

• A rename and the publication of an upload use RENAME_NOREPLACE. Where the file system lacks it (NFS, FUSE including sshfs, 9p), they fall back to rename(2): a concurrent overwrite is not detected there, and the audit of an upload that overwrites says replaced=unknown.
• No fsync: a success does not promise durability on disk.
• mkdir creates one level; the missing parents of an upload are created one by one, each judged by the ACL.
• Deleting a tree is not counted: the audit says removed=unknown.

What you will see

SFTP proxy

The sftp backend stores files on an upstream SFTP server, reached over SSH with a service account that users do not know.

[[backends]]
name = "acme-amont"
type = "sftp"
host = "sftp.acme.example"
host_key_fingerprint = "SHA256:2hZbXq1b5Xb3vN2mQ6w7l3Fv0tXk4yJ8aUeYp9rS0cE"   # checked out of band

[backends.auth]
type = "password"
username = "relais"
password = "changez-moi"

[[roles]]
name = "acme"

[[roles.mounts]]
backend = "acme-amont"
home_dir = "/depot"
acl = [{ path = "/", rights = ["read", "write", "list"], recursive = true }]

A client of the acme role uploads /f.txt: the file is /depot/f.txt on the upstream.

The keys

All keys: Reference [[backends]] type = “sftp”; common keys: Backends. Key authentication:

[backends.auth]
type = "private_key"
username = "relais"
private_key_pem = """
-----BEGIN OPENSSH PRIVATE KEY-----
...
-----END OPENSSH PRIVATE KEY-----
"""

Prefer an ed25519 or ECDSA key. An RSA key signs with rsa-sha2-512 or rsa-sha2-256 depending on server-sig-algs, ssh-rsa (SHA-1) as a last resort.

The upstream host key

The proxy checks the upstream host key before authenticating: otherwise, a man in the middle would receive the service account credentials. The fingerprint:

ssh-keyscan -p 22 sftp.acme.example | ssh-keygen -lf -

• Pin the ED25519 fingerprint, failing that ECDSA, failing that RSA: this is the order in which the proxy negotiates.
• Verify it out of band: on the upstream, ssh-keygen -lf /etc/ssh/ssh_host_ed25519_key.pub.
• Lowercase sha256: and trailing = padding are accepted.
• A key presented as a certificate is judged on the key it certifies.
• Rotation: one fingerprint per backend; change it at switchover, the roles reload applies it to the next connections.

Uploads

With hidden_stores.enabled = true, an upload writes to an in-transfer file on the upstream, next to the destination, then publishes it:

At step 3, the destination is missing for one round trip. Without hidden_stores, the upload writes to the destination, and resume and append are served (Uploads).

The service account can create, rename and delete in the destination directory. An overwrite replaces the inode (mode, owner, ACL, extended attributes lost) and takes twice the space until publication.

Common keys on an SFTP proxy

Performance and limits

• Read: one READ request in flight per handle; a read that follows the previous one is served from the block already read. A download in order reads the file about once on the upstream.
• Write: packets as large as the upstream accepts, eight in flight.
• One SSH connection per SFTP session and per REST request: the handshake weighs on short REST requests.
• The proxy speaks SFTP v3 (statuses 0 to 8), like OpenSSH.
• Upstream links are not told apart: stat follows a link, a listing marks no entry as a link.

What you will see

S3 and compatibles

The s3 backend stores files as objects in an AWS S3 bucket or in a compatible storage (MinIO, Garage, Scaleway…).

[[backends]]
name = "archives"
type = "s3"
bucket = "archives"
region = "eu-west-3"
prefix = "sftp/"
endpoint_url = "https://minio.interne.example:9000"   # without this key: AWS

[backends.credentials]
type = "static"
access_key_id = "AKIAEXEMPLE"
secret_access_key = "changez-moi"

[[roles]]
name = "archivistes"

[[roles.mounts]]
backend = "archives"
home_dir = "/{username}"
acl = [{ path = "/", rights = ["read", "write", "list"], recursive = true }]

alice uploads /in/x.txt: the object is the key sftp/alice/in/x.txt.

The keys

All keys: Reference [[backends]] type = “s3”.

iam_role: AWS_* variables, profile, instance or pod role. Common keys: Backends.

Files and directories

A key and a directory with the same name can coexist, except with refuse_upload_over_directory = true.

An object is written whole: no resume (reput), no append. Only a file can be renamed.

Bucket permissions

On the bucket and <prefix>/*:

A read-only backend only needs s3:ListBucket and s3:GetObject.

Multipart uploads

A multipart upload that is never completed is billed until it is aborted:

• Give each backend a prefix: the sweep only works under it.
• A slow upload sends an empty part every 15 s, which dates it for the other instances; they have the same uploads.idle_timeout_secs.
• A lifecycle rule is still recommended:

{"Rules": [{"ID": "abort-incomplete-multipart", "Status": "Enabled", "Filter": {"Prefix": ""},
            "AbortIncompleteMultipartUpload": {"DaysAfterInitiation": 2}}]}

Its delay, counted from initiation, exceeds the longest upload. MinIO expires incomplete uploads on its own (stale_uploads_expiry).

Conditional writes

replaced in the audit and the reservation marker rely on If-None-Match: * and If-Match of PutObject. Behind an endpoint_url (and on AWS with cross_instance_reservation), the server measures them at startup, on the key <prefix>/.craftfilegate-upload-precondition.<16 hex>, deleted afterwards; the verdict holds until the next restart. MinIO: honoured.

Common keys on S3

Performance and limits

• Each upload in progress holds an 8 MiB buffer (Memory); its writes are sequential.
• An upload outside the root pays one listing per parent level.
• The client addresses the bucket in the URL path (path-style), AWS included.
• 10,000 parts at most per object, about 78 GiB at 8 MiB per part.
• On a versioned bucket, the self-test leaves two empty versions and one delete marker per startup.

What you will see

WebHDFS (Knox)

The webhdfs backend reads HDFS, read-only, through the WebHDFS of Apache Knox: HTTPS, a service account over Basic, on behalf of the user (doAs). Knox carries Kerberos to the cluster. It also serves an HttpFS or a WebHDFS without Kerberos; Hadoop 2.8 and later.

[[backends]]
name = "datalake"
type = "webhdfs"
url = "https://knox.example.com:8443/gateway/default"
auth = { type = "basic", username = "svc-sftp", password_file = "/run/secrets/knox-password" }
ca_bundle = "/etc/craft-file-gate/knox-ca.pem"   # the private CA of Knox

[[roles]]
name = "analystes"

[[roles.mounts]]
backend = "datalake"
mount_path = "/datalake"
home_dir = "/data/projets"
acl = [{ path = "/", rights = ["read", "list"], recursive = true }]

alice reads /datalake/2026/x.csv: the request targets <url>/webhdfs/v1/data/projets/2026/x.csv?op=OPEN&doAs=alice.

The keys

All keys: Reference [[backends]] type = “webhdfs”.

The connection to Knox opens in 5 s at most; HTTPS_PROXY is not followed. Common keys: Backends.

The mount on WebHDFS

With doAs, the user name is made of A-Z a-z 0-9 . _ -, 64 characters at most.

hidden_stores, refuse_upload_over_directory, stale_partials, cross_instance_reservation and lock_prefix do not apply: nothing is written. case_insensitive: leave it out, HDFS compares byte by byte.

Prerequisites

The right to name a user (doAs), with impersonate = true. Who grants it depends on what is behind url:

<property>
  <name>hadoop.proxyuser.svc-sftp.hosts</name>
  <value>sftp-gateway.example.com</value>  <!-- where it connects from -->
</property>
<property>
  <name>hadoop.proxyuser.svc-sftp.groups</name>
  <value>sftp-users</value>                <!-- on whose behalf it acts -->
</property>

At startup, the server runs a GETFILESTATUS of the HDFS root as the service account, without doAs, 5 s at most.

What the backend does

• Read-ahead: 10 MiB read in 32 KiB SFTP packets cost 3 OPEN with the default; a read that skips only asks for its size.
• Listings: read to the end, capped at 10,000 pages, 1,000,000 entries and 64 MiB per response.
• Redirects: a 307 from Knox is followed once, only to the same origin (scheme, host, port) as url.
• A SYMLINK entry is shown as a link, and cannot be read; HDFS compares names byte by byte, and so does the ACL.

Performance and limits

• Knox is the bottleneck: each stat, page and range is an HTTPS request it relays to the cluster. The sessions of a backend share one HTTP client.
• timeout_secs covers a whole range: on a slow link, raise it rather than lowering read_ahead_bytes.
• Small files each cost one GETFILESTATUS and one OPEN: this backend is for browsing HDFS, not for everyday storage.
• The body of a Knox error is never copied into a log: only the exception name and the code.

The configuration file

One file, named at launch

craft-file-gate --config /etc/craft-file-gate/config.toml

-c is the short form. Only [auth] is required, with at least one role and one door: [sftp], or [api] with [admin]. All the keys: the reference.

Splitting: users_file and roles_file

Users, roles and backends can live in separate files. These files are reloaded at runtime; config.toml almost not.

[auth]
users_file = "users.toml"   # the [[users]]
roles_file = "roles.toml"   # the [[roles]] and the [[backends]]

users_file and inline [[users]] do not add up: when users_file is given, only that file is read.

Relative paths

A relative path to a file the server reads (host_keys, users_file, roles_file, public_key_file, the persist_file keys, the pair and the directory of [admin.tls]) starts from the directory of config.toml, not from the launch directory: a configuration and its files travel together, including in a container. The other paths (root of a local backend, log.dir, the files of a WebHDFS backend) start from the launch directory: write them as absolute paths.

The environment

A CRAFT_FILE_GATE_* variable replaces the key it overrides, after the file is read, at startup and on every reload: the list is in Environment variables. For a secret, prefer the _FILE form: a file read once, judged as a trusted file.

The binary’s tools

hash-password and verify-password read neither the configuration nor the secrets; healthcheck reads the listeners of --config, nothing else.

What you will see

Checking a configuration

config check applies the startup validation to a file, without starting: no port opened, no file created, no secret read, no network reached.

craft-file-gate config check /etc/craft-file-gate/config.toml
craft-file-gate config check config.toml --format json
craft-file-gate config schema > config.schema.json
craft-file-gate config explain sftp.ban.max_failures
craft-file-gate config effective /etc/craft-file-gate/config.toml

config check

Environment variables count as at startup. A secret (host key, _FILE, password_file, variable) is judged present, with its owner and mode; its content is not read. Left to startup, reported as info: the JWKS, the Kubernetes API, a storage probe, the upstream SFTP, the log files, the OTLP exporter.

A CI job or an AI assistant writes the configuration, runs config check --format json, fixes each error with the help of key and doc, and starts again until exit 0.

config schema

The JSON schema (draft 2020-12) of config.toml, users_file and roles_file: types, defaults, bounds, allowed values, description of each key, x-reload (hot reload), x-env (variables), x-doc (link). An unknown key is refused; none is required.

A first line #:schema ./config.schema.json hands it to Taplo (Even Better TOML): completion and underlining in the editor, as in config.example.toml. The schema ships with each release and lives in the images at /usr/share/craft-file-gate/config.schema.json; config schema > config.schema.json writes it next to the configuration.

config explain <key>

One key: type, default, allowed values, hot reload (⟳), variables, effect, spec, link to its section. --format json for a machine; an unknown key exits with 2 and the closest ones.

config effective <file>

The configuration applied: the file, its linked files, the environment variables, the defaults of the reference; --format toml (default) or json. Every secret and every password hash shows as ***, as does the identifier that goes with a secret (access_key_id) and any value of a key named like a secret or under headers. Offline like config check, which runs first: a refused configuration exits with 1 and its finding.

Authentication

Two sources, three doors

A connection is authenticated by a single source, which gives its roles. A local account alice and the sub alice of a token are two distinct users.

Choosing the methods

[auth.methods]
jwt   = { enabled = false }
local = { enabled = true, password = true, pubkey = true }

A keys-only deployment turns the password off:

local = { enabled = true, password = false, pubkey = true }

The keys: [auth.methods].

Local accounts

[[users]]
username = "alice"
password_hash = "$argon2id$v=19$m=19456,t=2,p=1$..."   # craft-file-gate hash-password
authorized_keys = ["ssh-ed25519 AAAA... alice@poste"]
authorities = ["utilisateurs"]                         # their roles

The keys: [[users]]. In users_file, they change without a restart.

Hashes

echo -n "mot-de-passe" | craft-file-gate hash-password              # the hash only
echo -n "mot-de-passe" | craft-file-gate hash-password --user alice # a [[users]] block

The password is read on stdin, never as an argument. The hash goes to stdout, its parameters to stderr. The Hash tools tab of the admin console does the same in the browser, without sending the password.

A check costs what the stored hash says: the server never re-hashes. Keep a single profile per file: an unknown name then costs exactly the time of a wrong password, and cannot be guessed from the response time.

The argon2 formats ($argon2id$, $argon2i$, $argon2d$) are accepted. To migrate from another server without knowing the passwords, allow_sha512_crypt = true or allow_bcrypt = true under [auth.methods] local also accepts these formats: Reference [auth.methods].

Each time the file is loaded, the line password hashes in use counts the accounts per format, and so does the metric craftfilegate_local_users{hash_format}: when a format drops to zero, remove its flag. local.max_argon2_memory_kib (19456: the m of the owasp-min profile) names at load time every account whose hash asks for more; that account still connects: re-hashing it with the default profile brings it under the budget.

The check runs on a bounded thread pool, outside the runtime: see Password hashing.

The public key

The client offers a key, then signs if it is in its authorized_keys. Offered keys do not count: an SSH agent that tries five before the right one is not banned; a connection that ends without authenticating, after a declined key, counts one failure.

The signature algorithms of a key

[sftp.algorithms] user_key sets the algorithms allowed to everyone (see The SFTP door); ssh-rsa (SHA-1) is not in it by default. A role can allow others to its users:

[[roles]]
name = "partenaire-ancien"
user_key_algorithms = ["ssh-rsa"]   # in addition to user_key

[[roles.mounts]]
backend = "disque"
home_dir = "/partenaire"

The exception applies to every user who holds this role, never to a single user. Only the roles of the server’s files grant it, not the roles reached through the authorization service.

JWT

The jwt method is enabled by default.

[auth.jwt]
secret = "remplacez-moi"     # or CRAFT_FILE_GATE_JWT_SECRET_FILE
algorithm = "HS256"
username_path = "/sub"       # the user's name
authorities_path = "/groups" # their roles

One key source, your choice: secret (HS256, HS384, HS512), public_key_file (the issuer’s PEM public key: RS256, RS384, RS512, ES256, ES384) or jwks_url (the key set of an identity provider, each key stating its algorithm). The keys: [auth.jwt].

A token is accepted if its signature verifies, if exp is present and in the future, and if nbf, when present, is past (60 s of leeway for both). With issuer or audience, the iss or aud claim must be present and equal. The user name is read at username_path, the roles at authorities_path (an array of strings).

Plugging in an identity provider (jwks_url)

[auth.jwt]
jwks_url = "https://idp.example.com/.well-known/jwks.json"
algorithm = "RS256"
jwks_refresh_interval_secs = 3600
issuer = "https://idp.example.com/"

The cache age is the gauge craftfilegate_jwks_cache_age_seconds: alert on it (see Metrics).

What you will see

SFTP door and SSH algorithms

An example

[sftp]
listen = "0.0.0.0:2222"
host_keys = ["/etc/craft-file-gate/host_ed25519"]

[server]
max_sessions_per_user = 10

[sftp] is optional: without it, the SFTP door is off.

Create the host key once, before the first start:

ssh-keygen -t ed25519 -f /etc/craft-file-gate/host_ed25519 -N ""

The [sftp] keys

All keys: Reference [sftp]; timeouts: Timeouts.

[sftp.ban], [sftp.rate_limit]: Bans. In [server], shared by all doors: max_sessions_per_user (concurrent sessions of the same name, across all instances with [cluster]), shutdown_grace_period_secs (Shutdown), [server.hidden_stores] (Uploads).

The door advertises the password and publickey methods. It serves only the sftp subsystem, once per connection: no shell, no exec, no port forwarding.

Host keys

Each loaded key is reported with its SHA256:... fingerprint, the one that ssh-keygen -l gives and that a client sees on its first connection. GET /admin/config and the Configuration tab of the console give the same ones.

generate_host_key creates the key only if its file is missing, in 0600, and gives its fingerprint. An existing file is read as is: the key does not change from one start to the next. Keep it for a single instance on persistent storage; in Kubernetes, mount a Secret (see Kubernetes secrets).

A table entry chooses the algorithms a key advertises, with the [sftp.algorithms] syntax applied to the host_key list:

[sftp]
listen = "0.0.0.0:2222"
host_keys = [
  "/etc/craft-file-gate/host_ed25519",
  { path = "/etc/craft-file-gate/host_rsa", algorithms = ["rsa-sha2-512", "rsa-sha2-256"] },
]

An algorithm is advertised only if a loaded key can sign with it.

Algorithms

[sftp.algorithms] sets the algorithms offered, per category. Each list starts from a modern default and is edited as in OpenSSH:

The defaults, list by list: Reference [sftp.algorithms].

• kex, ciphers, macs and host_key are negotiated before the user is known: they apply to the whole server.
• user_key gives the algorithms a user key may sign its connection with (OpenSSH’s PubkeyAcceptedAlgorithms). A role can allow others for its own users only (user_key_algorithms, see Authentication).
• The ext-info-* and kex-strict-* markers are always added to kex.
• The server-sig-algs extension advertises to the client the host_key list in force, then the user_key algorithms that no host key signs.

Weak algorithms

diffie-hellman-group1-sha1, diffie-hellman-group14-sha1, diffie-hellman-group-exchange-sha1, aes*-cbc, hmac-sha1, hmac-sha1-etm@openssh.com and ssh-rsa (RSA signed with SHA-1) are in no default. Added with +, they are offered. diffie-hellman-group-exchange-sha256 can also be added, outside the default.

An old client

# An old JSch client: neither curve25519 nor ML-KEM
[sftp.algorithms]
kex = ["+diffie-hellman-group14-sha1"]

The sessions list of the console shows, for each session, the negotiated algorithms and those that are weak (weak_algorithms).

What you will see

Uploads and atomic writes

Atomic writes (hidden stores)

By default, an upload writes into the destination file, like HiddenStores off in ProFTPD: a reader can see a partial file while the transfer lasts.

With enabled = true, the upload writes into an in-flight file in the same directory, then renames it to the destination at the end. The destination appears, or changes, only once the file is complete.

[server.hidden_stores]
enabled = true
prefix = ".in."
extension = "."

All the keys: Reference [server.hidden_stores].

The in-flight file is named <prefix><name>.<token><extension>: .in.rapport.csv.3f9a1c04b7e25d68. with the defaults. The token, 16 hexadecimal characters, is unique to each upload. A .in.* pattern matches them all.

In-flight files are listed and read like the others. They concern the local and sftp (proxy) backends; an S3 object appears only once its upload is finished, with no file next to it.

Per backend, per mount

The same table can be set at three levels. Each key resolves on its own: the mount wins over the backend, which wins over [server.hidden_stores], which wins over the defaults. SFTP and REST resolve the same value.

[server.hidden_stores]            # the whole server
enabled = true

[[backends]]
name = "disque"
type = "local"
root = "/srv/sftp"
hidden_stores = { enabled = false }   # this backend writes in place

[[roles]]
name = "depot"

[[roles.mounts]]
backend = "disque"
mount_path = "/depot"
home_dir = "/depot"
hidden_stores = { enabled = true }    # except this mount
acl = [{ path = "/", rights = ["write", "list"], recursive = true }]

Leftovers of an interrupted transfer

A process killed in the middle of an upload leaves its in-flight file behind. The server deletes it later, when an upload goes through the same directory, once the file is older than grace_secs.

[uploads.stale_partials]
grace_secs = 900
age_check = true

All the keys: Reference [uploads.stale_partials].

The same table can be set per backend (stale_partials = { grace_secs = 1800 } in its [[backends]]), key by key on top of [uploads.stale_partials]. On an S3 backend, it sets the cleanup of abandoned multipart uploads (see S3).

A leftover is deleted only if its name has the exact form the server writes, if nobody holds its lock, and if its age exceeds grace_secs on the storage clock. At the slightest doubt, it stays. Each deletion leaves an INFO line.

The instances that share a storage have the same uploads.idle_timeout_secs: the threshold is computed from that of the instance that sweeps.

Two uploads to the same destination

The first upload to open keeps the destination until it ends. A second one, from the same account or another, through the same door or another, is refused as soon as it opens, before sending a byte.

A stuck upload (client suspended by Ctrl+Z) is taken over by a retry from the same account on the same instance, after uploads.takeover_idle_secs without data.

Between several instances, a lock set on the storage, next to the destination, carries the same rule. It is refreshed every 20 s; the lock of a process that is gone is taken over after 2 x idle_timeout_secs + 60 s (120 s by default). cross_instance_reservation and lock_prefix: Reference [[backends]].

What the lock is on each type: Local, S3, SFTP proxy. Names that start with .craftfilegate-upload or with the lock_prefix belong to the server: you can list and read them, not write to them. With a single instance, cross_instance_reservation = false is enough.

Capping the size of a file

max_file_mb, on a mount, caps the size of each uploaded file (1 MB = 1,048,576 bytes). It is not a space counter.

[[roles.mounts]]
backend = "disque"
home_dir = "/{username}"
max_file_mb = 500

What you will see

Bans and rate limits

An example

[sftp.ban]
max_failures = 5
window_secs = 300
ban_duration_secs = 600
whitelist_ips = ["10.0.0.0/8"]

[admin]
listen = "0.0.0.0:8080"

[admin.ban]
max_failures = 10
trusted_proxies = ["10.0.0.5"]   # the reverse proxy in front of the API

[api]
enabled = true

[api.ban]
max_failures = 5
trusted_proxies = ["10.0.0.5"]   # the same one: a single listener

Without the section, the door bans nothing.

One list per door

The three lists are independent: an address banned on the file API still opens the admin console, and the other way around.

The keys of a ban

The same under [sftp.ban], [api.ban] and [admin.ban], read at startup.

All the keys: Reference [sftp.ban], [api.ban], [admin.ban].

What counts as a failure

A failure is a credential presented and judged wrong, whatever the account tried.

These do not count: a disabled method, an expired or not yet valid token, a refused download ticket, whatever it is, a refusal after an accepted credential (no role, session limit), a refusal by the rate limiter, the refusal of an address already banned. A successful connection does not reset the counter.

With [api] cors_origins = ["*"], any web page can make a visitor’s browser send wrong credentials, which count toward the ban of the visitor’s address: list the origins of your applications.

The life of a ban

An IPv4-mapped address (::ffff:10.1.2.3) is the same as 10.1.2.3, for the ban, the whitelist and the proxies.

Lifting a ban

GET /admin/bans (Bans tab of the admin console) lists them; lifting one requires the unban permission, {protocol} is sftp, api or admin:

curl -X DELETE -H "Authorization: Bearer $TOKEN" \
  http://localhost:8080/admin/bans/sftp/203.0.113.7

A lift is a dated decision: it cancels the verdicts decided before it, never a later verdict. It does not reset the counter.

Sharing bans between instances

The three lists can share a file or a ConfigMap. The merge keeps, per address, the longest ban and the most recent verdict; a ban learned from a peer cuts the SFTP sessions of the address, with no ip_banned line (the one from the instance that decided it is enough). On shutdown, each list is published, 5 s at most each.

The address of an HTTP client: trusted_proxies

The HTTP doors take the TCP peer as the address. When this peer is in the trusted_proxies of their list ([api.ban] for the file API, [admin.ban] for the admin API), they take the rightmost address of X-Forwarded-For that is not a trusted proxy, failing that X-Real-IP. The ban, the limiter, the share of the hashing queue and the audit use this address. The SFTP door reads only the TCP peer.

Without [admin] control_listen, the file API and the admin API share a listener: [api.ban] and [admin.ban] then carry the same trusted_proxies.

Rate limits

A token bucket per address: burst connections or requests in a row, then the rate per minute. Without the section, no limit.

[sftp.rate_limit]
connections_per_minute = 30
burst = 10

[api.rate_limit]
requests_per_minute = 600

All the keys: Reference [sftp.rate_limit], [api.rate_limit].

The admin API has no rate limit. A rate refusal does not count toward the ban.

What you will see

Timeouts

What each timeout detects

Uploads: [uploads]

[uploads]
idle_timeout_secs = 30
min_rate_bytes_per_sec = 1024   # 1 KiB/s on average; absent or 0: disabled
min_rate_grace_secs = 60

All the keys: Reference [uploads].

The idle timeout

The clock runs only while the server waits for the client. The time the server spends on its storage (slow S3, stalling NFS) never counts.

When the timeout expires, the partial file is dropped (in-flight file deleted, S3 multipart aborted) and nothing is published.

A live upload reaches its file at least every 2 x idle_timeout_secs: the cleanup of leftovers and the takeover of locks rely on it, so give the same value to all instances that share a storage. Raise it for clients that keep a file open without writing (sshfs, a graphical client that asks for a confirmation, a very slow link: at the default, a 32 KiB packet needs ~1.1 KB/s).

The minimum rate

Once min_rate_grace_secs of waiting have passed, an upload must have received on average at least min_rate_bytes_per_sec, like Apache’s RequestReadTimeout ... MinRate. The average runs from the start: a bursty client keeps the credit of its bursts, a trickle is cut at the end of the grace period. The bytes counted are those of accepted WRITE packets, not the offset reached.

Below it, the upload is cut as for idleness. 1 KiB/s cuts a trickle and lets through a 10 KiB/s link that stalls.

TCP keepalive: [tcp_keepalive]

Set on each accepted connection, on the SFTP port and on the HTTP port.

All the keys: Reference [tcp_keepalive].

Network loss in the middle of a transfer: TCP_USER_TIMEOUT

Keepalive probes only a connection with nothing in flight. When the server sends something to a client that is gone (the replies to the WRITE packets of an SFTP upload, a download), TCP_USER_TIMEOUT cuts.

The connection is thus cut 5 s after the upload is abandoned. On Linux, this timeout replaces count: an idle connection whose peer is gone is cut at the first probe that exceeds it (around 70 s on SFTP). It also applies to a client that stops reading: a REST download whose client is suspended is cut at 35 s. A longer network loss (coverage loss, VPN reconnecting) kills the transfer; raise user_timeout_secs if your clients go through such losses.

Outside Linux, nothing is set.

SSH: [sftp]

login_grace_secs and inactivity_timeout_secs cut the connection (0: never); keepalive_interval_secs (0: none) probes the client, keepalive_max (3) cuts after that many probes without an answer. The keys: [sftp].

The answer to an SSH keepalive counts as activity: with a keepalive shorter than inactivity_timeout_secs, a live but idle session is no longer cut for inactivity, only a client that no longer answers is. That is why SSH keepalive is disabled by default.

HTTP: header read timeout

admin.header_read_timeout_secs (10 s, from 1 to 300, CRAFT_FILE_GATE_ADMIN_HEADER_READ_TIMEOUT_SECS) bounds, on the port of the admin API and the file API, the wait for the headers of a request: from the connection, the TLS handshake or the previous response in keep-alive. Beyond it, the connection is closed without a response. It bounds neither a body nor a response.

The port serves only HTTP/1.1; over HTTPS, ALPN offers only http/1.1, and HTTP/2 clients fall back to it.

What you will see

Logs

Two streams

Both go to stdout. With log.dir, they also go to two separate files.

[log]

[log]
level = "info"
format = "json"
audit = "all"
dir = "/var/log/craft-file-gate"

All the keys: Reference [log].

The volume of the trail: log.audit

log.audit removes only successes. A refusal, an error or an unknown outcome is always written.

Always written, whatever log.audit: connection_rejected, connection_rejected_summary, ip_banned, everything the admin API writes, and the session_end of a cut session (administrator, shutdown, ban, internal error).

The log level does not touch the trail: the audit target stays at info whatever log.level.

Log files: log.dir

• Rotation: on the first write of a new UTC day, and before a write that would exceed max_file_size_mb. The archive carries the moment it was opened, craft-file-gate.2026-09-27T00-00-00Z.log.gz, and holds only lines from that UTC day.
• Retention: an archive goes once its day plus the retention has passed, judged on its name. The other files of the directory are not touched.
• Files in 0640, .gz archives always complete; one directory per process.

In a container, stdout and the platform’s rotation (kubelet, journald, Docker) remain the normal way; dir needs a volume there. The Helm chart offers it: logFiles.enabled: true.

Repeated refusals: one summary line

An anonymous client that insists (scanner, misconfigured client) would produce one line per attempt. Per door, address, reason and result, the first refusal_summary_threshold refusals of a window of refusal_summary_window_secs keep their line; the next ones are counted, then summarized in one connection_rejected_summary line at the end of the window, with suppressed, threshold and window_secs.

Only refusals that judged no credential are summarized: missing credential, empty credential, malformed credential, method disabled, verifier unavailable, banned, rate limit, password checks saturated, password checks saturated for address, shutting down. A wrong password always keeps its line.

Beyond refusal_summary_max_addresses tracked keys, the extra refusals are summarized together (overflow=true).

SFTP session ends

The application line for the end of a session states its cause:

The trail carries one session_end line per session, with the same cause in reason.

A connection that ends before the session (a client that does not speak SSH, a negotiation with no common algorithm) writes INFO SSH session ended: <reason>, with peer and client_version. These are ordinary ends: alert on their number, not on each one.

What you will see

Log level and diagnostics

Changing the level at runtime

[log]
level = "debug"

Saving the file is enough: the level changes within moments, without a restart, as for the users and roles files. On Unix, kill -HUP applies the edit without waiting for the file watcher.

level takes a single value, not a directive string. The audit trail does not depend on it: it stays at info.

In [log], only level, audit and the refusal_summary_* keys are reloaded at runtime; the rest waits for a restart (see Hot reload).

Who decides the level

The first line of the log gives the filter in force and its source:

INFO log filter in force  filter="info,craft_file_gate=info,audit=info,opentelemetry_sdk=off" source="config [log] level"

RUST_LOG, to go further

RUST_LOG gives the detail of a dependency, for example the russh trace. It replaces the whole string, including the audit=info that the server always adds: write it yourself.

RUST_LOG=warn,russh=trace,audit=info

Understanding an authentication refusal

The audit line of a refused password does not say why: telling “unknown user” from “wrong password” would reveal which accounts exist, and logs travel far. The detail is at the debug level, for the operator only.

DEBUG local password authentication rejected  username=alice reason="password does not match the stored hash"
DEBUG local password authentication rejected  username=bob reason="no such user in the users file"

debug also gives the loaded accounts (local user store contents, field usernames); info gives only their count (local user store loaded).

To check a hash without a server:

echo -n "mot-de-passe" | craft-file-gate verify-password '$argon2id$v=19$...'

Go back to info once the diagnosis is done. Other refusals carry their cause in reason: Troubleshooting.

A runtime change writes INFO log level reloaded (level, source, filter). Under level = "warn" or more severe, these announcements go to stderr, prefixed craft-file-gate:: the announcement of a filter is never silenced by it.

Telemetry

An example

[telemetry]
enabled = true
otlp_endpoint = "http://otel-collector:4318"
protocol = "http"
service_name = "craft-file-gate"
metrics = true

[telemetry]

All keys: Reference [telemetry].

The endpoint

• https:// is encrypted in both protocols; the collector’s certificate is checked against the system roots (see TLS trust roots).
• protocol is authoritative: OTEL_EXPORTER_OTLP_PROTOCOL and OTEL_EXPORTER_OTLP_TRACES_PROTOCOL, which some operators inject, do not change it.
• The exporter reads OTEL_EXPORTER_OTLP_HEADERS (authentication headers) and OTEL_EXPORTER_OTLP_TIMEOUT (10 s by default).

What is exported

The export receives the spans and events of CraftFileGate and of the audit trail from info up, whatever the log level: a server set to warn still exports its spans.

The audit line of an operation is an event of its span; a failure sets the span to status=error.

For a Tempo or Jaeger panel:

• a transfer that reaches close has two sftp_operation spans with the same operation (upload, download): the opening, then the commit, which alone carries bytes. Count the spans that carry bytes;
• an rmdir of a non-empty directory has an rmdir span then an rmdir_recursive span, for a single rmdir_recursive audit line;
• reads and writes have no per-packet span.

A path or a username that contains a control character or a Unicode separator (U+2028, bidirectional controls) arrives escaped, in a visible form (\u{2028}). The exact value is in the audit line.

Metrics over OTLP

With metrics = true, the server pushes its metrics every metrics_interval_secs, in addition to GET /metrics, which is still served; the name mapping: Metrics.

Sends, retries and shutdown

Lost spans are counted on /metrics:

ended - exported - export_failed is what is still in flight (up to 2560 spans: the queue and the current batch), plus what a full queue rejected. A gap that grows beyond that means lost spans.

increase(craftfilegate_otel_spans_ended_total[5m])
  - increase(craftfilegate_otel_spans_exported_total[5m])

What you will see

Trust files and TLS

Trust files

These files decide who gets in and what they can do: anyone who can write them can grant themselves access. The server judges them at startup, and at reload for those that reload.

The file, and every directory crossed from / to reach it (symbolic links included), is judged on its mode bits, its owner and its group. The server then reads the file through the descriptor it judged.

Setting them up

The recommended setup:

chown root:root /etc/craft-file-gate /etc/craft-file-gate/*
chmod 755 /etc/craft-file-gate
chmod 644 /etc/craft-file-gate/config.toml /etc/craft-file-gate/roles.toml
chmod 640 /etc/craft-file-gate/users.toml /etc/craft-file-gate/host_ed25519
chgrp craft-file-gate /etc/craft-file-gate/users.toml /etc/craft-file-gate/host_ed25519

In a container, mount the configuration read-only (readOnly: true, :ro): a Kubernetes Secret in 0440 with the pod’s fsGroup works as is.

[security]

All keys: Reference [security].

Read at startup. Keep it for a deployment where the server’s group contains only the server.

What the server creates itself

The process sets umask(077) at startup.

Instances that share a bans volume run under the same uid.

Client paths

A client path is judged on its virtual form, then the backend resolves it under its root. On a local backend, a symbolic link never leaves the root: see Local.

TLS trust roots

This is outgoing TLS: S3 backend over HTTPS, jwks_url, authorization service, OTLP collector over https://, WebHDFS backend. Incoming TLS for the console is set in [admin.tls] (see Admin API and console).

The server embeds no root: it reads the system store.

When set, either variable replaces the system store, it does not add to it. To trust an internal authority and the public roots, concatenate:

cat /etc/ssl/certs/ca-certificates.crt ca-interne.pem > bundle.pem

Without a variable, the first file found among the usual paths wins (/etc/ssl/certs/ca-certificates.crt, /etc/pki/ca-trust/extracted/pem/tls-ca-bundle.pem, /etc/pki/tls/certs/ca-bundle.crt, /etc/ssl/ca-bundle.pem, /etc/ssl/cert.pem), then the directories /etc/ssl/certs and /etc/pki/tls/certs. The :latest and :alpine images carry a store; the :scratch image has none.

Mounting a set of roots

The Mozilla bundle maintained by the curl project works:

curl -fsSLo bundle.pem https://curl.se/ca/cacert.pem

Mount it at the default path (/etc/ssl/certs/ca-certificates.crt, read-only), or anywhere with SSL_CERT_FILE; in Kubernetes, a ConfigMap is enough, it is not a secret.

A deployment without outgoing TLS connections (local backend or SFTP proxy, local accounts or static JWT key, no OTLP) needs no root.

Deployment recommendations

Operating

Docker

ssh-keygen -t ed25519 -f ./host_ed25519 -N ""   # the host key
sudo chown 65532 host_ed25519                   # readable by the image's user
docker run -d --name craft-file-gate \
  -v ./config.toml:/config/config.toml:ro \
  -v ./host_ed25519:/config/host_ed25519:ro \
  -v ./roles.toml:/config/roles.toml:ro -v ./users.toml:/config/users.toml:ro \
  -v data:/data \
  -p 2222:2222 -p 8080:8080 -p 8081:8081 \
  craftogether/craft-file-gate:latest

config.toml follows the quick start with what a container changes: listeners on 0.0.0.0, a key path relative to the directory of config.toml, the console by account and password (the doors are published), storage and accounts in their own files. docker run --rm craftogether/craft-file-gate:latest config schema > config.schema.json writes next to it the schema that #:schema names (Checking a configuration); the image carries it at /usr/share/craft-file-gate/config.schema.json.

#:schema ./config.schema.json
[sftp]
listen = "0.0.0.0:2222"
host_keys = ["host_ed25519"]        # /config/host_ed25519

[auth.methods]
local = { enabled = true }          # the accounts in users.toml
jwt = { enabled = false }           # no identity provider

[admin]
listen = "0.0.0.0:8080"             # file API, file explorer
control_listen = "0.0.0.0:8081"     # admin console, /admin, probes, /metrics

[[admin.roles]]                     # a [[users]] account with authorities = ["admins"]
name = "admins"
permissions = ["overview", "sessions", "kick", "bans", "unban", "config", "logs", "audit", "revoke", "grant"]

[admin.ban]
max_failures = 5

[api]
enabled = true

[api.ban]
max_failures = 5

[api.ui]
enabled = true

The first mount and its ACL: roles.toml ([[backends]], [[roles]]) and users.toml ([[users]]), next to config.toml, are picked up without being declared.

#:schema ./config.schema.json
[[backends]]                        # roles.toml
name = "donnees"
type = "local"
root = "/data"                      # the data:/data volume

[[roles]]
name = "utilisateurs"

[[roles.mounts]]
backend = "donnees"
home_dir = "/{username}"            # alice sees /data/alice as her root /
create_home = true

[[roles.mounts.acl]]
path = "/"
rights = ["read", "write", "list", "delete", "rename"]
recursive = true

#:schema ./config.schema.json
[[users]]                           # users.toml
username = "alice"
password_hash = "$argon2id$..."     # output of hash-password (below)
authorities = ["utilisateurs", "admins"]   # her files, and the admin console

The console: http://host:8081/, the file explorer: http://host:8080/files (Console sessions, File explorer).

The image exposes 2222 (SFTP) and 8080; control_listen publishes a third one. The HEALTHCHECK runs craft-file-gate healthcheck on /config/config.toml. ENTRYPOINT is the binary alone, the command --config /config/config.toml; the binary handles SIGTERM as PID 1.

• Mount read-only (:ro) the files the server trusts: configuration, users, roles, host key, TLS pair (Security).
• In the image, /data belongs to its user, and a named volume inherits that; a host directory mounted in its place must belong to it: sudo chown 65532 data (65534 for :alpine).
• :scratch has no certificate roots: an outbound TLS connection (S3, JWKS, OTLP, Knox) needs a mounted bundle and SSL_CERT_FILE.
• Subcommands pass through as is: echo -n 'mot-de-passe' | docker run -i --rm craftogether/craft-file-gate hash-password.
• Keep Docker’s stop timeout above the server’s: docker stop -t 90. See Shutdown.

Docker Compose

services:
  craft-file-gate:
    image: craftogether/craft-file-gate:latest
    restart: unless-stopped
    stop_grace_period: 90s
    ports:
      - "2222:2222"   # SFTP
      - "8080:8080"   # file API, file explorer
      - "8081:8081"   # admin console, /admin, probes, metrics
    volumes:
      - ./config.toml:/config/config.toml:ro
      - ./roles.toml:/config/roles.toml:ro
      - ./users.toml:/config/users.toml:ro
      - ./host_ed25519:/config/host_ed25519:ro
      - data:/data

volumes:
  data:

The binary’s features

Each backend type and each door is a Cargo feature, all enabled by default. The published binaries and images carry them all, plus k8s. A binary built with fewer features refuses at startup the table of a door or the type of a backend it does not carry, naming the feature.

The console, the probes and /metrics have no feature: every binary carries them.

Subcommands (hash-password, verify-password, healthcheck): The configuration file.

Kubernetes

The Docker walkthrough under the chart: local storage on a volume, the accounts in a Secret, the roles in config.toml.

kubectl create secret generic sftp-host-keys --from-file=host_ed25519
kubectl create secret generic sftp-users --from-file=users.toml
kubectl apply -f - <<'EOF'
apiVersion: v1
kind: PersistentVolumeClaim
metadata: { name: sftp-data }
spec: { accessModes: [ReadWriteOnce], resources: { requests: { storage: 10Gi } } }
EOF
helm install sftp deploy/helm/craft-file-gate -f sftp-values.yaml \
  --set-file config.inline=config.toml

# sftp-values.yaml
hostKeys:
  existingSecret: sftp-host-keys                         # /keys/host_ed25519
extraVolumes:
  - name: data
    persistentVolumeClaim: { claimName: sftp-data }
  - name: users
    secret: { secretName: sftp-users, defaultMode: 0440 }
extraVolumeMounts:
  - { name: data, mountPath: /data }                     # the backend's root = "/data"
  - { name: users, mountPath: /secrets/users, readOnly: true }

config.toml is the Docker one followed by the content of its roles.toml (the chart mounts only config.toml), with host_keys = ["/keys/host_ed25519"] under [sftp] and users_file = "/secrets/users/users.toml" under [auth]. Listeners stay on 0.0.0.0 (the probes reach the pod by its IP) and [[admin.roles]] opens the console, since the chart sets the static token aside. The volume belongs to the pod’s group (fsGroup 65532): create_home creates alice/ there. Beyond one pod, the volume is ReadWriteMany.

The chart

• One Service per exposure: publishing SFTP through a LoadBalancer (service.sftp.type) publishes neither the console, nor /metrics, nor the probes.
• The kubelet probes come from the pod’s node, which most CNIs let through despite the NetworkPolicy; otherwise, add the node CIDR as an ipBlock to networkPolicy.controlFrom. To restrict Prometheus and the ingress, list their namespaces in networkPolicy.controlFrom.

Probes

/livez and /readyz (Probes and health) are probed on the probe port when one is given, otherwise on the control port, otherwise on the admin port.

A port for the probes

service.probes.port: 9090 sets [server] probes_listen: the probes and /metrics get a port of their own, in plain HTTP, even under [admin.tls] (One door or two). The kubelet and Prometheus (per pod: PodMonitor or annotations) no longer need the certificate or the console port; the port is on the Service <release>-control only with service.probes.expose: true. An SFTP pod without [admin] thus has its probes, with /readyz ready as soon as the SFTP door listens.

Pod hardening

The chart applies the restricted profile of the Pod Security Standards. Each field can be overridden in podSecurityContext and securityContext; null removes a field or a block.

The root of a local backend is a volume from extraVolumes. Host keys and the TLS pair come from a Secret (cert-manager for TLS), never from an emptyDir: auto_generate of [admin.tls] does not apply under this chart.

Several pods

Each Role covers a single name, without create: get, update on the Secret; get, update, patch on each ConfigMap, watch on their collection for bans (helm template ... --show-only templates/rbac.yaml).

Sharing through a ConfigMap

Feature k8s (in the published images). The pod reads the ConfigMap before serving; each publication is conditioned on the resourceVersion it read, and a data.bans erased by kubectl edit is published again on the next one. Without watch, propagation falls back to a re-read every 30 s; a deployment that does not create the ConfigMap adds create on the collection.

[sftp.ban]           # same under [api.ban] and [admin.ban]; the chart provides the name
backend = "configmap"

inotify on a shared node

fs.inotify.max_user_instances (128 by default) is counted per UID, across the whole node. The server takes only one. When other pods have used them up and you cannot tune the node:

[reload]
watch = "poll"   # no inotify instance; a Secret update is seen within 5 s

See Hot reload.

Kubernetes secrets

• A Secret mounted as a volume is updated by Kubernetes, which repoints the ..data link: configuration, users, roles and TLS pair are reloaded at runtime. See Hot reload.
• A Secret mounted with subPath is never updated: avoid subPath.
• Mount Secrets and ConfigMaps readOnly: true, as the chart does, never on a writable emptyDir or hostPath (Trust files and TLS).
• A Secret passed through envFrom (extraEnvFrom) is read only at startup: run kubectl rollout restart for a new value.
• The server does not read Secrets through the Kubernetes API: mount them. The only exception is the pods’ shared Secret (below).

A file rather than a variable

Mount the Secret as a file through the chart values, and name it with the _FILE variable (the same for the admin token, with config.allowStaticToken: true):

extraVolumes:
  - name: jwt
    secret: { secretName: sftp-jwt, defaultMode: 0440 }
extraVolumeMounts:
  - { name: jwt, mountPath: /secrets/jwt, readOnly: true }
extraEnv:
  - { name: CRAFT_FILE_GATE_JWT_SECRET_FILE, value: /secrets/jwt/jwt-secret }

The file is read once, at startup; /proc/<pid>/environ shows only a path. See Environment variables. users.toml is mounted the same way, named by users_file: see Kubernetes.

The pods’ shared Secret

The pods of a release share the key that signs admin console sessions, so that a pod accepts the token another pod issued. The chart creates an empty Secret and gives the pods get and update on that name only. The first pod that does not find the admin-session.key entry generates it and writes it; the others read it. Each entry has its own life: the certificate of the channel between pods lives there too (tls.crt, tls.key).

With replicaCount above 1, clusterSecret.enabled: false requires a key_file under [admin.session] in config.inline, and a shared key requires shared revocations (adminRevocations.backend: configmap, or persist_file under [admin.session]).

To change the key: remove the entry (kubectl patch secret ... --type=json -p '[{"op":"remove","path":"/data/admin-session.key"}]') then restart the pods; open sessions are lost.

SSH host key

Create the key once, keep it in a Secret, mount it. Do not let the server generate it (generate_host_key) in a pod: each pod, or each restart without a volume, would have its own key, and clients would see “host key changed”.

ssh-keygen -t ed25519 -f host_ed25519 -N ""
ssh-keygen -l -f host_ed25519.pub          # the fingerprint to give to clients
kubectl create secret generic sftp-host-keys --from-file=host_ed25519

hostKeys.existingSecret: sftp-host-keys mounts it in /keys (The chart), and the configuration points to it: host_keys = ["/keys/host_ed25519"]. The fingerprint at startup (loaded host key, field fingerprint) and in GET /admin/config is the one from ssh-keygen -l.

Several instances

The instances of a deployment find and talk to each other on a port of their own, over TLS 1.3 in both directions, admitted by the certificate they share. The Kubernetes chart sets all of this up as soon as replicaCount exceeds 1.

[cluster]
listen = "0.0.0.0:8083"
peers = "dns:craft-file-gate-cluster:8083"
cert_file = "/var/lib/craft-file-gate/cluster/tls.crt"
key_file = "/var/lib/craft-file-gate/cluster/tls.key"

All keys: Reference [cluster].

The shared certificate

Its SHA-256 fingerprint is the identity of the cluster: neither name nor date is checked, expiry is reported by craftfilegate_cluster_cert_not_after_seconds. To change it, remove the pair and restart every instance; during the rollout, a peer with the old certificate is certificate_mismatch.

kubectl patch secret sftp-cluster --type=json \
  -p '[{"op":"remove","path":"/data/tls.crt"},{"op":"remove","path":"/data/tls.key"}]'
kubectl rollout restart deployment/sftp

Detectors and withdrawal from service

After each round, each instance evaluates three detectors: storage_alone (a backend down here that a reachable peer sees up: an outage that everyone sees does not count), isolated (fewer than min_peers reachable peers for isolated_after_secs) and isolated_and_storage_down (isolated, and every non-local backend down here; a local backend, the pod’s disk, does not count: without a non-local backend, it never fires). By default they only alert: WARN cluster detector active, craftfilegate_unready_detector{detector}, craftfilegate_cluster_isolated, checks.cluster of /admin/health.

Named in unready_when, they withdraw the instance from service: /readyz not ready after unready_after_secs of an active detector, ready again after ready_after_secs with none; /livez does not change. storage_alone only withdraws a pod if another pod, in service and with no backend down, sees each of its failed backends available, and only one pod at a time: if every pod has an outage somewhere, none leaves.

[cluster]
min_peers = 1                    # the chart: floor(replicaCount / 2)
unready_when = ["storage_alone", "isolated_and_storage_down"]  # the chart: auto

isolated alone can withdraw every pod: cut of the cluster port, loss of a majority of nodes, split into two equal halves, manual reduction of the replica count. Only name it knowingly, and never go below 2 × min_peers + 1 replicas without helm upgrade.

With the defaults, a storage outage is seen in 35 s at worst, the withdrawal follows 60 s later, and Kubernetes takes the pod out of the Service after 3 readiness probes at 10 s: about 2 min.

What you will see

At startup, INFO cluster channel listening (TLS 1.3, pinned on the shared certificate); for each peer that answers, INFO cluster peer reachable; per status: craftfilegate_cluster_peers{status}. The Instances, Sessions and Bans tabs of the console read each peer with your credential, which the peer judges itself (scope=cluster); a kick goes only to the peer that holds the session, a lift to every peer, except on a ConfigMap list; per call: craftfilegate_cluster_relay_total{route,result}.

A ban there is a guard against attempts, not a withdrawal of access: an address banned on a peer still reads it through another instance with a valid credential (a revoked session stays refused).

Admin API and console

[admin]
listen = "0.0.0.0:8080"           # file API, file explorer
control_listen = "0.0.0.0:8081"   # admin console, /admin, /metrics, probes
bearer_token = "changez-moi-en-production"

[api]
enabled = true
prefix = "/api/v1/files"

The keys: reference.

One door or two

With the file API, set control_listen: bans, kicks, /metrics and probes stay reachable when transfers saturate the server. The Helm chart does it (service.control.port). probes_listen gives probes and Prometheus a port without TLS or console; without [admin], it is the only HTTP listener (Kubernetes). The console reads its health on /admin/health, served next to it in every case.

Authenticating

Each protected route requires Authorization: Bearer <token>.

An admin role names permissions; an authority that carries its name grants them.

[[admin.roles]]
name = "support"
permissions = ["overview", "sessions", "logs"]

[[admin.roles]]
name = "admins"
permissions = ["overview", "sessions", "kick", "bans", "unban", "config", "logs", "audit", "revoke", "grant"]

The names of admin roles and those of [[roles]] are distinct. An account that carries both kinds opens the console and the file doors; an account that carries only admin roles opens only the console. The authorization service never receives an admin role name, and no admin token opens a file. Failures count in [admin.ban] (Bans).

Sessions

{"total": 1, "offset": 0, "limit": 50, "server_time": "2026-10-07T14:42:10.125Z", "inactivity_timeout_secs": 600,
 "sessions": [{"session_id": "550e8400-e29b-41d4-a716-446655440000", "username": "alice", "remote_addr": "192.168.1.42:54321", "auth_method": "password",
   "mounts": [{"mount_path": "/", "backend": "disque", "home_dir": "/alice", "acl": [{"path": "/", "rights": ["read", "write", "list", "delete", "rename"], "recursive": true}]}],
   "connected_at": "2026-10-07T14:30:00Z", "idle_since": null, "last_sftp_op_at": "2026-10-07T14:41:25.402Z", "last_traffic_at": "2026-10-07T14:42:05.871Z",
   "bytes_read": 1048576, "bytes_written": 524288, "sftp_ops": 412, "has_active_transfer": false, "pod_name": "craft-file-gate-0", "authorities": ["utilisateurs"],
   "client_version": "SSH-2.0-OpenSSH_9.6", "algorithms": {"kex": "curve25519-sha256", "host_key": "ssh-ed25519", "cipher": "chacha20-poly1305@openssh.com",
     "mac_client_to_server": "hmac-sha2-256", "mac_server_to_client": "hmac-sha2-256"}, "user_key": null, "weak_algorithms": [], "type": "sftp"}]}

The list also carries REST transfers (upload, download) in progress for long_request_threshold_secs (30 s by default, 0: all, reloaded at runtime): "type": "rest" (an SFTP session has "sftp"), session_id, username, remote_addr, method (PUT, GET), direction (upload, download), path (the path seen by the user), mounts (mount_path, backend), connected_at (its start), bytes, bytes_read, bytes_written, bytes_per_sec (the average since the start).

Logs and streams

With [log] dir, GET /admin/logs/{app|audit} returns the last entries of the current file, filtered by the server. See Logs.

Parameters: lines (500, 5000 at most; 4 MiB scanned at most), level (ERROR to TRACE), since and until (RFC 3339), q (text, 256 bytes), field=key:value (16 at most). 3 concurrent reads at most.

SSE streams (text/event-stream) follow activity live:

At most 8 open streams, 2 per identity; a stream ends at the exp of its token or on its revocation, at the latest after 15 minutes.

Probes and health

The console

http://serveur:8081/: a page that calls /admin/*. It loads nothing from a third party. Its login: Console sessions.

• Filters and sorts (ip:, user:, role:, backend:, type:) live in the URL: /#sessions?q=user:bob&sort=-last_op. The token never appears there.
• The page and its files (/ui/*) carry a strict CSP (default-src 'none', everything from the same origin, 'wasm-unsafe-eval'); a reverse proxy that sets its own allows at least as much.

What you will see

Console session and revocations

A local account whose authorities name an admin role signs in to the admin console with a username and password; the server gives it back a session token that it signs itself.

[auth.methods]
local = { enabled = true, password = true }

[[users]]
username = "eric"
password_hash = "$argon2id$..."
authorities = ["admins"]

[[admin.roles]]
name = "admins"
permissions = ["overview", "sessions", "kick", "bans", "unban", "config", "logs", "audit", "revoke", "grant"]

[admin.ban]
max_failures = 5

[admin.session]
key_file = "/secrets/admin-session.key"   # at least 32 bytes, the same on every instance
ttl_secs = 3600
max_age_secs = 43200

Sign-in counts its failures in [admin.ban], which it requires (Bans), and goes through the password hashing queue (Password hashing).

Signing in

The token carries only the account: each request re-reads the account in effect ([[users]] or users_file) and recomputes its permissions. A reload of users_file that removes a role, changes the password or removes the account applies to the next request.

The session key

The key that signs tokens is the same on every instance: key_file, or under Kubernetes secret_name (Secrets). Without either, the key is drawn at startup: sessions live with the process, on this instance only. All the keys: Reference [admin.session].

Revoking, signing out

Streams opened under a revoked token (/admin/events, log follows) are closed.

Sharing revocations

[admin.session]
persist_file = "/var/lib/craft-file-gate/admin-revocations.json"  # a file of their own
# or, on Kubernetes:
# backend = "configmap"                                  # the chart sets it with the shared Secret
# revocation_configmap_name = "craft-file-gate-access"
reread_interval_secs = 5

All the keys: Reference [admin.session].

A shared key goes with shared revocations, and with synchronized clocks (NTP): a revocation is dated, and an instance whose clock runs ahead or behind applies it with that offset.

In the console

• Username and password when the door signs in accounts; “Sign in with a token” takes the static token or a provider JWT, and is the only form otherwise.
• The token lives in the page: reloading, opening a tab or closing the browser asks for sign-in again. The browser keeps only the theme and the table views.
• The session is renewed as long as the page is open, up to max_age_secs after sign-in; a closed tab lets it end at ttl_secs. The header shows the account, its admin roles and the token’s end.
• Logout calls POST /admin/logout: one session signs out every tab and device of the account.

Temporary access

A temporary access gives a file role to a user name until a date, on top of the roles it already holds: a contractor for a delivery, support staff for a day. The name can be a local account or an identity brought by a JWT or the authorization service.

[[admin.roles]]
name = "support"
permissions = ["overview", "sessions", "grant"]

[admin.grants]
persist_file = "/var/lib/craft-file-gate/grants.json"   # or backend = "configmap"
max_duration_secs = 604800                              # 7 days

All keys: Reference [admin.grants].

• Who grants: an admin role that holds the grant permission, from the “Temporary access” tab of the console or POST /admin/grants (Authenticating). Any role of [[roles]] can be granted, never an admin role. A reason is mandatory; the grant and its revocation are in the trail (grant_add, grant_revoke).
• The name: the console offers the local accounts and the names that a file door authenticated in the last 7 days, on this instance. A name never seen is accepted with a warning: it opens nothing until someone connects under that name.
• The duration: 1 h, 8 h, 24 h, 48 h, 7 days or an end date, at most max_duration_secs.
• At the end (date reached or revocation): the SFTP sessions the access served and the REST transfers in progress under its mounts are cut, an upload in progress is abandoned; each following REST request is judged without it. A session opened before the grant does not see it.
• Several instances: the access lives in a file or the ConfigMap <release>-access (one of the two with [cluster]), reread every reread_interval_secs; another instance applies it and cuts it at its next reread. Clocks are assumed to be synchronized (NTP).

File explorer

[admin]
listen = "0.0.0.0:8080"
bearer_token = "changez-moi-en-production"

[api]
enabled = true
prefix = "/api/v1/files"

[api.ui]
enabled = true
path = "/files"

The page is at http://serveur:8080/files.

Options

Both keys are read at startup. All the keys: Reference [api.ui].

What the page does

The page is a client of the REST file API, and of nothing else. It has no rights of its own: what the ACL refuses, the API refuses, and the page shows the server’s detail.

• A button whose right is missing on the current folder is grayed out.
• Requests go one at a time, plus the upload in progress, to stay under [auth] hash_per_address with Basic.
• Uploads go one file after the other, with a progress panel (name, percentage, throughput, cancel).
• The list is paginated by 200, sortable by name, size or date, folders first.
• The current folder is in the URL (#/rapports/2026): back, forward and links work.

Signing in

Username and password (Basic, local user), or “Use a token instead” (Bearer, a JWT). The credential stays in memory only: reloading the page signs you out. Only the theme is kept (craft-admin-theme). Failures count for [api.ban].

Mounts

The page starts at /, the home that GET ?rights returns. A mount at / shows its home_dir there; mounts under names show the synthetic root that lists them.

Downloading: the ticket

A browser link carries no Authorization header: the page asks for a ticket (this file, this user, ten minutes; see The file API), then the browser downloads as a stream. During those ten minutes, “Retry” and the browser’s resume reuse the same URL.

The page’s files are public, under the same CSP as the console; the data goes through the API.

Limits

Interface in English or French (?lang=fr, otherwise the browser’s language); under 720 px, the actions move into a menu.

Audit: reading the trail

The audit trail says who did what, on which file, and whether it worked; refusals and errors included. The vocabulary of the lines (actions, fields, reason) is in the reference.

{"timestamp":"2026-10-07T14:41:25.402Z","level":"INFO","target":"audit","fields":{"message":"audit: operation succeeded","source":"sftp","action":"upload","session_id":"550e8400-e29b-41d4-a716-446655440000","remote_addr":"192.168.1.42","username":"alice","path":"/in/rapport.csv","backend":"disque","new_path":"","count":524288,"replaced":"no","removed":"","result":"success"}}

Where it goes

Rotation, retention and level: Logs.

What it keeps

log.audit (all, changes, failures) only removes successes; repeated anonymous refusals are summarized as connection_rejected_summary. See The volume of the trail and Repeated refusals.

Severity

An alert on the trail’s WARN lines therefore does not fire for an anonymous scanner.

Filtering

In the console, Logs tab, source audit (permission audit): filters by level, period, text and field:value; each read writes an audit_read line. See Admin API and console.

# the admin console API
curl -H "Authorization: Bearer $TOKEN" \
  'http://serveur:8081/admin/logs/audit?field=username:alice&level=WARN&since=2026-10-07T00:00:00Z'

# the files; without [log] dir: docker logs ... | jq -c 'select(.target == "audit")'
jq -c 'select(.fields.username == "alice")' /var/log/craft-file-gate/craft-file-gate-audit.log

The text of a storage error is not in the trail: look for it in the application log, at the same time, with the same path.

An incomplete trail

A line the server cannot write (closed pipe, full disk) is lost: craftfilegate_log_write_errors_total counts it, stderr says so at most once per minute, and the server keeps serving. Alert on increase(craftfilegate_log_write_errors_total[5m]) > 0.

Metrics

curl http://serveur:8081/metrics          # Prometheus text, no credential

# prometheus.yml
scrape_configs:
  - job_name: craftfilegate
    static_configs:
      - targets: ['serveur:8081']   # probes_listen, else control_listen, else admin.listen

• Values are cumulative since startup, per pod. Compute a rate between two reads (rate()).
• An unknown value is absent (null in JSON, no data point in OTLP), never 0: the “Absent when” column says when.
• The OTLP name is the Prometheus name without _total.

Catalog

craftfilegate_connections_rejected_total counts per attempt, several per connection: its ratio to craftfilegate_connections_total is not a failure rate per connection.

Console thresholds

[admin.metrics_thresholds] only decides where the Metrics tab flags a tile; the server does not alert. The keys and their defaults: reference.

Alerts

groups:
  - name: craftfilegate
    rules:
      - alert: CraftFileGateAdminCertExpiringSoon
        expr: craftfilegate_admin_tls_cert_not_after_seconds - time() < 30 * 86400
        for: 1h
      - alert: CraftFileGateAdminCertExpiryUnknown
        expr: craftfilegate_admin_tls_cert_expiry_unreadable == 1
      - alert: CraftFileGateBackendErrors
        expr: increase(craftfilegate_backend_errors_total[5m]) > 0
      - alert: CraftFileGateBackendDown
        expr: craftfilegate_backend_up == 0
      - alert: CraftFileGateStorageAlone
        expr: craftfilegate_unready_detector{detector="storage_alone"} == 1
      - alert: CraftFileGateIsolated
        expr: craftfilegate_cluster_isolated == 1

Alerting on a stale JWKS cache

      - alert: CraftFileGateJwksStale
        expr: craftfilegate_jwks_cache_age_seconds > 2 * 3600   # 2 x jwks_refresh_interval_secs
        for: 5m
      - alert: CraftFileGateJwksNeverLoaded
        expr: absent(craftfilegate_jwks_cache_age_seconds) and on() craftfilegate_jwks_cached_keys >= 0
        for: 5m

A stale cache keeps its keys: tokens signed by a key rotated since then are refused. jwks_age_secs makes the same judgment for /admin/status.

Hot reload

vi /etc/craft-file-gate/users.toml          # the server sees the edit and reloads
kill -HUP $(pidof craft-file-gate)          # or: reload right away

[reload]
watch = "auto"            # auto | inotify | poll
poll_interval_secs = 5    # period of the periodic reread

What is watched

config.toml always; users_file, roles_file and the [admin.tls] pair when they are configured. The server watches the directory of each file: an atomic replacement (sed -i, mv) and the switch of the ..data link of a ConfigMap or Secret volume are seen. Events are grouped in 200 ms bursts, and a single task re-reads. SIGHUP triggers a reload, even without watching.

What a reload does

It re-reads every watched file, whichever one changed.

An authentication, or a REST request, reads the users in effect when it arrives. A re-read file is judged as at startup. A defined environment variable keeps the last word.

What a reload applies, key by key

The keys marked ⟳ in the reference; a key without the mark is read at startup. The [[users]], [[roles]] and [[backends]] entries are reloaded when they live in users_file or roles_file; written in config.toml, they are read at startup. The [admin.tls] paths need a restart; the content of the pair, however, is re-read at every reload.

inotify or periodic re-read

All the keys: Reference [reload].

Both keys are read at startup.

• A single inotify instance per process, shared with the ban files; poll fits where they are scarce (fs.inotify.max_user_instances, per UID and for the whole node).
• The periodic re-read compares date, size, inode, ctime, owner and mode; an interval without change writes nothing.
• When the kernel event queue overflows (fs.inotify.max_queued_events), every file is re-read. Repeated overflows mean that a neighbor is churning the configuration directory: move the configuration, or raise the limit.

What you will see

Shutdown

[server]
shutdown_grace_period_secs = 30   # wait for work in progress, all doors

docker stop -t 90 craft-file-gate                  # Docker
# Kubernetes: terminationGracePeriodSeconds: 90

The steps

SIGTERM or SIGINT (Ctrl-C) trigger the shutdown, even when the server is PID 1.

Steps 5, 7 and 8 share a single delay, counted from the announcement. Without a transfer in progress, the shutdown does not wait for it.

Tuning the orchestrator

The worst case of a shutdown:

The orchestrator’s shutdown delay must exceed it: docker stop -t 90, terminationGracePeriodSeconds: 90, which the chart sets (grace period plus 60 s). A SIGKILL before the end cuts transfers without an audit line, leaves S3 multipart uploads open and loses unexported spans.

What you will see

Each step writes its INFO line: shutdown signal received, ban files written out before the shutdown sequence, idle sessions disconnected (idle_kicked), waiting for active transfers to complete (only if there are any), remaining sessions disconnected (force_kicked, 0 included), graceful shutdown complete. Cut sessions end with session_end reason=shutdown_idle (step 4) or shutdown (step 6).

Performance and memory

Memory

The formula

peak ≈ 12 MiB                                 base (14.5 MiB with glibc)
    + 5.5 MiB                                 if an S3 backend is used
    + hash_workers × m + 2 MiB                password checks
    + sessions × 0.15 MiB
    + connections in the hash queue × 70 KiB  at most hash_queue
    + local transfers × 4 MiB
    + S3 uploads × 26 MiB + S3 downloads × 8 MiB
    + addresses tracked by bans × 225 B

m is the largest argon2 m in the users file: 19 MiB with the owasp-min profile (default of hash-password), 64 MiB with the rfc9106-low-mem profile. The startup line gives this term: peak_memory="1 thread × 19 MiB = 19 MiB". See Password hashing.

The formula is an upper bound: it adds up peaks that do not all happen at the same moment. No measured case has exceeded it. File size does not enter it: transfers are streamed.

The terms are measurements on the published image (static musl binary, x86_64), with an OpenSSH client. A connection in the hashing queue weighs ~42 KiB in Basic, a local download 2.3 MiB. At large scale with S3, uploads dominate: 4 threads at m=65536 and 10 S3 uploads measure 415 MiB (formula: 537). Nothing caps the number of concurrent S3 uploads; max_sessions_per_user sets a bound per user.

A small deployment under 80 MB

30 users, ~900 files per day: a few concurrent clients.

[auth]
hash_workers = 1      # one check at a time: 1 × 19 MiB
hash_queue = 32       # a full queue: 32 × 70 KiB = 2.2 MiB

With hash-password hashes (profile owasp-min), and no rfc9106-low-mem hash in the file:

glibc binaries

The Docker images (musl) give memory back after each peak. A glibc binary (releases, glibc host) keeps the memory of the hashes in its arenas: 95 MiB retained after a burst (4 threads, m=19456), 19 MiB with MALLOC_MMAP_THRESHOLD_=4194304. Set this variable (Environment= in the systemd unit) and do not set MALLOC_ARENA_MAX, which raises the peak.

Kubernetes

The chart ships requests.memory: 64Mi and limits.memory: 256Mi. With its default (1 thread, derived from requests.cpu: 100m), 1000 SSH connections queued with the rfc9106-low-mem profile reach 146 MiB. On a busy node, raise the request toward the expected peak.

A pod without limits.cpu sees the node’s CPUs: see Password hashing to set the pool size.

Watching memory

/metrics exposes process_resident_memory_bytes and process_peak_resident_memory_bytes (Linux only), and the admin console plots them live. See Metrics.

Not measured: REST transfers, SFTP proxy, active telemetry, thousands of users, aarch64 and Windows.

Checking passwords

[auth]
hash_workers = 2         # threads that compute the hashes
hash_queue = 1024        # attempts waiting for a thread
hash_per_address = 4     # slots one address can hold at once

Options

The three keys are read at startup; a reload does not change the size of the pool. All the keys: Reference [auth].

How it works

An argon2id, bcrypt or sha512-crypt hash is pure computation: from 16 ms (owasp-min) to more than a second (heavy argon2). Checks run on dedicated threads (craft-file-gate-hash-0, -1… in ps -L), off the runtime that serves transfers, the API and the probes.

An attempt takes its place before the account lookup: a known name and an unknown name get the same response. Rate limiters and bans (Bans) bound what a burst costs the queue.

Behind a reverse proxy, declare it in trusted_proxies: each client counts at its own address. A NAT address goes in the door’s whitelist_ips ([sftp.ban], [api.ban], [admin.ban]), which is not capped. Console sign-in (POST /admin/login) goes through the same pool.

Choosing the sizes

What you will see

At startup, one line gives each number and its source:

INFO password hashing pool started: passwords are checked on these threads, off the async runtime, ...
     workers=2 workers_source="detected (8 CPUs ...), capped at 2 by default: ..."
     queue=1024 queue_source="default (1024, ...)"
     per_address=4 per_address_source="default (4 per address, ...)"
     peak_memory="2 threads × 19 MiB = 38 MiB"
     tokio_workers=8 tokio_workers_source="detected (std::thread::available_parallelism)"

tokio_workers: the threads of the async runtime, from the same detection with no cap, or TOKIO_WORKER_THREADS.

A reload of users.toml that changes the largest m says so: INFO password hashing peak memory changed with the users file.

Kubernetes

A pod without limits.cpu sees the node’s CPUs (32, 64). The cap at 2 protects the default pool, not the tokio runtime. To follow what the pod requests, pass requests.cpu through the Downward API (rounded up to the next integer):

env:
  - name: CRAFT_FILE_GATE_HASH_WORKERS
    valueFrom:
      resourceFieldRef:
        containerName: craft-file-gate
        resource: requests.cpu
        divisor: "1"
  # same for TOKIO_WORKER_THREADS

An explicit value has no cap: requests.cpu: 8 gives 8 threads and 8 x m of memory. The Helm chart does it with passwordHashing.workers (empty: requests.cpu) and passwordHashing.queue.

Troubleshooting

An index of errors: the exact word you see (startup message, reason of an audit line, SFTP status, REST code) leads to the guide page that defines the option at fault, then, in parentheses, to its table in the reference, and to the identifier of the behaviour rule, to quote to support. <...> marks a variable part. The full vocabulary of audit lines is in the reference.

Startup and configuration

A broken setting refuses to start; a setting with no effect starts with a WARN that names the key.

Hot reload

A file refused at reload keeps what is in force. See Hot reload.

Connection and authentication

reason of the connection_rejected lines, and what the client sees. The HTTP doors answer an error in application/problem+json, field detail.

File operations

reason of the operation lines, SFTP status and REST code.