eos

Package
github.com/cs3org/reva/v3/pkg/storage/fs/eos
Source
pkg/storage/fs/eos · Go reference

Enable it

Select the driver in the service that uses it, and put its settings in the driver's own table:

[grpc.services.storageprovider]
driver = "eos"

[grpc.services.storageprovider.drivers.eos]
# settings below

Overview

This package implements a Storage Provider for EOS.

What is EOS?

EOS is a distributed storage system built around a namespace service (MGM, or Management node) and storage servers (FSTs, FileStore Targets). The MGM handles all metadata and namespace operations; actual file data lives on FSTs and is accessed via the XRootD protocol (or HTTP). EOS provides versioning, a recycle bin, extended attributes, ACLs, quotas, and file locking natively.

Package structure

pkg/storage/fs/eos/
├── eos.go               # Entry point: registers the "eos" driver, creates EosFS
├── client/
│   ├── eosclient.go     # EOSClient interface, shared types (FileInfo, Authorization, …)
│   ├── utils.go         # Version folder path helpers, attribute key utilities
│   ├── binary/
│   │   └── eosbinary.go # Client implementation: shells out to the `eos` CLI + xrdcopy
│   └── grpc/
│       ├── eosgrpc.go   # Client implementation: EOS gRPC for metadata
│       ├── eoshttp.go   # HTTP for data I/O (reads/writes to FSTs)
│       ├── acl.go       # ACL operations over gRPC
│       ├── attributes.go
│       ├── auth.go      # Token generation
│       ├── file_info.go
│       ├── file_ops.go
│       ├── quota.go
│       ├── recycle.go
│       └── versions.go
├── config.go             # Config struct with all tunables
├── eosfs.go              # Eosfs struct: init, path wrap/unwrap, convert, permission set
├── auth.go               # Auth resolution: UID/GID, tokens, daemon/single-user modes
├── file_ops.go           # Upload, Download, CreateDir, Move, Delete, ListFolder, …
├── file_info.go          # GetMD, GetPathByID, getPath (inode → path)
├── grant.go              # CS3 grant ↔ EOS ACL translation
├── locks.go              # File locking (app.lock + payload xattr)
├── recycle.go            # Recycle bin list / restore / purge
├── revisions.go          # File version list / download / restore
├── quota.go              # Quota reporting
└── arbitrary_metadata.go # user.* xattrs exposed as arbitrary metadata

Architecture

Client abstraction (client/eosclient.go)

The EOSClient interface decouples the filesystem logic from the transport used to reach EOS. Two implementations exist, selected at init time via the use_grpc config key:

Binary clientgRPC client
Metadata opsShells out to /usr/bin/eosEOS gRPC API (cern-eos/go-eosgrpc)
Data I/Oxrdcopy binaryHTTP to FSTs via eoshttp.go
AuthKeytab / uid-gid env varsKeytab or pre-shared auth key
StreamingNoYes (optional temp-file buffering)

The binary client was the original driver and remains useful when a full EOS installation is available on the same host. It is slower and less secure, but easier to set up. This can be used for demo’s.

The gRPC client is a more modern approach, and is recommended for production usage. For production usage, it is also recommended to set up TLS. For this, point http_client_certfile and http_client_keyfile to the correct files. If you want to force TLS, set allow_insecure to false (this is the default). The gRPC client uses two separate channels: gRPC to the MGM for all namespace operations (stat, list, mkdir, rename, ACL, xattr, quota, recycle, versions) and HTTP to the FSTs for actual file data.

Path handling

EOS paths are absolute on the cluster (/eos/user/j/jsmith/…). Storage providers operate on paths relative to the mount path, which is set up in the storage provider’s config under mount_path. So, paths that arrive at the SP are relative to this mount path. On file operations, a namespace is wrapped / unwrapped:

  • wrap(ctx, path) → prepends conf.Namespace to get the EOS-absolute path
  • unwrap(ctx, internal) → strips conf.Namespace to get the SP-relative path

As an example, imagine that EOS has paths like /eos/user/j/jsmith/…, but you want to expose them as /users/j/jsmith. Then you would set the mount_path to /users. Requests come in at the SP with paths like /j/jsmith. The namespace should then be set to /eos/user, which means requests go out to EOS as /eos/user/j/jsmith. Responses from EOS are then “unwrapped” to become /j/jsmith again, before being prepended by the mount_path again (which is done by the Storage Provider).

The UserLayout template (e.g. {{.Username}} or {{substr 0 1 .Username}}/{{.Username}}) is used when constructing home directories from the namespace root.

Authorization

Each call to EOS must carry authentication. The driver resolves the right auth on a per-request basis.

Rest of this: TODO after refactoring

UID/GID resolution cache

EOS stores file ownership as integer UIDs. Reva and CS3 work with opaque string user IDs. The driver maintains a TTL cache (userIDCache, up to user_id_cache_size entries) that maps between the two, using the Reva gateway (GetUser / GetUserByClaim) as the source of truth.

On startup a background goroutine (userIDcacheWarmup) walks the namespace to user_id_cache_warmup_depth levels and pre-populates the cache, which is important for latency on large deployments.

Versioning

EOS stores each version of a file in a hidden sibling folder named .sys.v#.<filename>. The driver:

  • Filters these folders from directory listings (matched by hiddenReg).
  • Exposes versions through ListRevisions / DownloadRevision / RestoreRevision.
  • With version_invariant: true (the default), performs an extra stat to ensure the inode returned for a file always refers to the current version, not the version folder. This keeps clients that cache inodes consistent after an overwrite.

Recycle bin

EOS recycle bins are per-user. The driver handles two cases:

  • User-owned spaces — EOS recycle bin of the file’s owner. The driver impersonates the owner when listing/restoring/purging.
  • Project spaces (ownerless) — Identified by the sys.forced.recycleid EOS xattr. In this case a fixed recycleid is passed to the EOS recycle APIs rather than a user identity.

ListRecycle enforces a configurable date window (max_days_in_recycle_list) and entry count (max_recycle_entries) to prevent unbounded responses.

ACLs and grants

EOS uses its own ACL syntax stored in the sys.acl extended attribute. The driver translates between EOS ACL entries and CS3 Grant objects:

  • User grants → EOS u:<uid>:<perms> entries.
  • Group grants → EOS egroup:<name>:<perms> entries.
  • Lightweight account grants — EOS has no concept of lightweight users. These are stored as plain xattrs (sys.reva.lwshare.<opaqueId> = <perms>) and merged into the ACL evaluation at permission-check time.

Grant evaluation (permissionSet) also handles public share roles (viewer/uploader/editor) and OCM share roles, short-circuiting before inspecting ACLs.

File locking

Locking uses two xattrs:

  • sys.app.lock — The EOS-native lock attribute. EOS enforces this server-side, blocking writes from applications with a mismatched tag. Format: expires:<unix>,type:shared,owner:<user>:<app>.
  • sys.reva.lockpayload — Base64-encoded JSON of the full CS3 Lock proto. Reva reads this to serve GetLock.

The EOS lock type is always shared (EOS does not have an exclusive lock), but is sufficient for WOPI-style app locking and checkout/checkin workflows.

The app parameter passed to every write and xattr operation is derived from the lock holder’s app name, encoded as http/reva_<appname>. This ensures EOS’s lock enforcement operates correctly.

Data I/O (gRPC client)

Reads and writes go through eoshttp.go, which speaks directly to EOS FSTs over HTTPS using mutual TLS or an auth key. The base URL is the MGM URL (EOS redirects to the actual FST).

Two modes are supported for both directions:

  • Streaming (default) — data flows directly between the caller and EOS without touching disk on the Reva host.
  • Local temp (read_uses_local_temp / write_uses_local_temp) — data is buffered in cache_directory first. Required when the FST does not support HTTP chunked encoding on uploads.

Chunked uploads (binary client / legacy)

The binary client handles the OwnCloud-style chunked upload protocol via chunking.ChunkHandler. Chunks are assembled on the local filesystem before being written to EOS. The gRPC client does not use this mechanism; chunked uploads should be disabled at the gateway level for gRPC deployments.

Configuration reference

Key config options (see fs/config.go for the full list):

KeyDescription
namespaceEOS path prefix (e.g. /eos/user/)
quota_nodeEOS path used for quota queries; defaults to namespace
use_grpctrue → gRPC+HTTP client; false (default) → binary client
master_grpc_urigRPC endpoint of the EOS MGM (e.g. eos-mgm.example.org:50051)
master_urlXRootD/HTTP base URL (e.g. root://eos-mgm.example.org)
grpc_auth_keyShared secret for gRPC calls
https_auth_keyShared secret for HTTP data calls
keytab / use_keytabKerberos keytab authentication
user_layoutGo template for user home path (e.g. {{substr 0 1 .Username}}/{{.Username}})
version_invariantStable inodes across file versions (default true)
enable_home_creationAllow CreateHome calls; requires create_home_hook
create_home_hookPath to a script invoked to provision new home directories
create_lightweight_home_hookScript creating a lightweight account’s home and sharing it with the account
force_single_user_mode / single_usernameImpersonate one account for all calls
read_uses_local_temp / write_uses_local_tempBuffer I/O via cache_directory
user_id_cache_sizeMax entries in the UID ↔ CS3 user ID cache (default 1 000 000)
user_id_cache_warmup_depthNamespace walk depth on startup for cache warmup (default 2)
max_recycle_entriesMax items returned by ListRecycle (default 2000)
max_days_in_recycle_listMax date span for ListRecycle (default 14 days)

Unsupported operations

The following storage.FS methods return errtypes.NotSupported:

  • GetHome — home path is handled by the spaces registry, not this driver.
  • CreateStorageSpace / ListStorageSpaces / UpdateStorageSpace — spaces are managed by an external spaces registry.
  • EmptyRecycle — only targeted purge of individual items is supported.

EOS documentation

Configuration

KeyTypeDefaultDescription
namespacestring"/"Namespace for metadata operations source
quota_nodestringsame as namespaceQuotaNode for storing quota information source
eos_binarystring"/usr/bin/eos"Location of the eos binary. Default is /usr/bin/eos. source
xrdcopy_binarystring"/opt/eos/xrootd/bin/xrdcopy"Location of the xrdcopy binary. Default is /opt/eos/xrootd/bin/xrdcopy. source
master_urlstring"root://eos-example.org"URL of the Master EOS MGM. Default is root://eos-example.org source
slave_urlstringsame as master_urlURL of the Slave EOS MGM. Default is root://eos-example.org source
cache_directorystringos.TempDir()Location on the local fs where to store reads. Defaults to os.TempDir() source
sec_protocolstring-SecProtocol specifies the xrootd security protocol to use between the server and EOS. source
keytabstring-Keytab specifies the location of the keytab to use to authenticate to EOS. source
single_usernamestring-SingleUsername is the username to use when SingleUserMode is enabled source
user_layoutstring"{{.Username}}"UserLayout wraps the internal path with user information. Example: if conf.Namespace is /eos/user and received path is /docs and the UserLayout is {{.Username}} the internal path will be: /eos/user//docs source
enable_loggingbool-Enables logging of the commands executed Defaults to false source
show_hidden_sys_filesbool-ShowHiddenSysFiles shows internal EOS files like .sys.v# and .sys.a# files. source
use_keytabbool-UseKeyTabAuth changes will authenticate requests by using an EOS keytab. source
enable_home_creationbool-EnableHome enables the creation of home directories. source
version_invariantbool-Whether to maintain the same inode across various versions of a file. Requires extra metadata operations if set to true source
use_grpcbool-UseGRPC controls whether we spawn eosclient processes or use GRPC to connect to EOS. source
gatewaysvcstringshared gatewaysvcGatewaySvc stores the endpoint at which the GRPC gateway is exposed. source
grpc_auth_keystring-GRPCAuthkey is the key that authorizes this client to connect to the EOS GRPC service source
https_auth_keystring-HTTPSAuthkey is the key that authorizes this client to connect to the EOS HTTPS service source
master_grpc_uristring-URI of the EOS MGM grpc server Default is empty source
user_id_cache_sizeint1000000Size of the cache used to store user ID and UID resolution. Default value is 1000000. source
user_id_cache_warmup_depthint2The depth, starting from root, that we’ll parse directories to lookup the owner and warm up the cache. For example, for a layout of {{substr 0 1 .Username}}/{{.Username}} and a depth of 2, we’ll lookup each user’s home directory. Default value is 2. source
read_uses_local_tempbool-Normally the eosgrpc plugin streams data on the fly. Setting this to true will make reva use the temp cachedirectory as intermediate step for read operations source
write_uses_local_tempbool-Normally the eosgrpc plugin streams data on the fly. Setting this to true will make reva use the temp cachedirectory as intermediate step for write operations Beware: in pure streaming mode the FST must support the HTTP chunked encoding source
allow_path_recycle_operationsbool-Whether to allow recycle operations on base paths. If set to true, we’ll look up the owner of the passed path and perform operations on that user’s recycle bin. source
max_idle_connsint-HTTP connections to EOS: max number of idle conns source
max_conns_per_hostint-HTTP connections to EOS: max number of conns per host source
max_idle_conns_per_hostint-HTTP connections to EOS: max number of idle conns per host source
idle_conn_timeoutint-HTTP connections to EOS: idle conections TTL source
http_client_certfilestring-HTTP connections to EOS: client certificate (usually a X509 host certificate) source
http_client_keyfilestring-HTTP connections to EOS: client certificate key (usually a X509 host certificate) source
http_client_cadirsstring-HTTP connections to EOS: CA directories source
http_client_cafilesstring-HTTP connections to EOS: CA files source
create_home_hookstring-Path of the script to run in order to create a user home folder source
create_lightweight_home_hookstring-Path of the script to run in order to create a lightweight account’s home and share it with the account. Takes the same arguments as CreateHomeHook. source
max_recycle_entriesint2000Maximum entries count a ListRecycle call may return: if exceeded, ListRecycle will return a BadRequest error source
max_days_in_recycle_listint14Maximum time span in days a ListRecycle call may return: if exceeded, ListRecycle will override the “to” date with “from” + this value source
allow_insecurebool-AllowInsecure determines whether EOS can fall back to no TLS Default is false source
enable_quota_cachebool-EnableQuotaCache enables an in-memory cache for GetQuota results. When enabled, cached values are returned immediately and refreshed in the background after QuotaCacheTTL seconds. Entries are never evicted, only refreshed. Default is false. source
quota_cache_ttlint600QuotaCacheTTL is the time-to-live in seconds for quota cache entries. After this period, the cached value is still returned but a background refresh is triggered. Default is 600. source
provides_space_typestring-ProvidesSpaceType is the type of spaces served by the storage provider this driver is instantiated by (e.g. personal, project). It is injected by the storage provider from its own provides_space_type setting, and should not be set in the driver configuration. source
external_accounts_user_namestring"cboxexternal"The ExternalAccountsUser is a user on whose behalf accesses to EOS are done when requests are made by an external user (such as lightweight or federated users). Since these users are unknown to EOS, access is done on behalf of this user. Note that this user will be added to the ACLs when such a request is made. source
external_accounts_user_uidstring"193339"UID of a user known to EOS on whose behalf accesses are done for external (lw, federated) users. source
external_accounts_user_gidstring"2766"GID of a user known to EOS on whose behalf accesses are done for external (lw, federated) users. source
Generated from pkg/storage/fs/eos. Edit its package doc comment or README.md to change this page.