SeaweedFS object storage (seaweedfs)

S3 compatible object storage of the platform, installed by default: documents, media, model files, exports, backups and the WORM audit archive, and the store meant for skills and MCP servers. Masters, volume servers, filers and the S3 gateway, single node or distributed with replicated volumes.

Generated from catalog/services/seaweedfs.yaml: do not edit by hand.

Summary

Version	4.51
Use	install and configure
Layer	infrastructure (shown apart)
Category	Storage
Installation methods	binary, podman
External connection	s3
Sandbox only	no
Foundation service	yes, selected by default by the install wizard

Licence

SPDX identifier	Apache-2.0
Licence policy	core licence (MIT or Apache-2.0)
Licence exception	-
Platform component	seaweedfs

Packages and artifacts

A package the project of the service publishes (its image, its binary archive, its Python or OS package) carries the licence of the service; a third-party package carries the licence written on its row, read from the official upstream metadata.

Kind	Package	Version	Licence	Details
container image	docker.io/chrislusf/seaweedfs	4.51	Apache-2.0	image key weed, used by master, volume, filer, s3, admin, digest sha256:f7a49e3f3972ebed5be2ed4befa4a0c68eb7bdddba6e692d42729ceb545134b8
binary archive	seaweedfs-4.51-linux_amd64.tar.gz	4.51	Apache-2.0	https://github.com/seaweedfs/seaweedfs/releases/download/4.51/linux_amd64.tar.gz, x86_64

Images are pinned by tag in the descriptor, and by digest when the descriptor declares one (the offline bundle then refuses a pulled image that does not carry it); the digest is recorded in the mirror of the Manager when the offline bundle is imported, and every pull or load is checked against it.

Supported systems and architectures

Method	Operating systems	Architectures
binary	RHEL family (dnf), Debian family (apt), Arch Linux (pacman)	x86_64 (architecture of the artifacts of the descriptor)
podman	RHEL family (dnf), Debian family (apt), Arch Linux (pacman)	x86_64, aarch64 (not restricted by the descriptor)

Certified host systems: RHEL 8/9/10, Rocky Linux 8/9/10, AlmaLinux 8/9/10, Oracle Linux 8/9, CentOS Stream 9/10, Ubuntu 22.04/24.04, Debian 12, Arch Linux (rolling). The host preflight accepts these systems (other releases of a known family give a warning, end of life releases are refused) and the x86_64 and aarch64 architectures.

Prerequisites

Host

• at least 1024 MB of memory (blocking, memory).
• at least 10240 MB free for /var/lib/navin (warning, disk).

Network and ports

Component	Port name	Port	Opened in the host firewall
master	http	9333/tcp	yes
master	grpc	19333/tcp	yes
master	metrics	9324/tcp	yes
volume	http	8180/tcp	yes
volume	grpc	18180/tcp	yes
volume	metrics	9325/tcp	yes
filer	http	8888/tcp	yes
filer	grpc	18888/tcp	yes
filer	metrics	9326/tcp	yes
s3	s3	8333/tcp	yes
s3	metrics	9327/tcp	yes
admin	admin	12535/tcp	yes

Services and connections needed

This service has no dependency.

Installation methods and modes

Method	Default	What the method uses
binary	yes	the binary archives of the descriptor, unpacked under the service directory
podman	-	the container images of the descriptor, run by Podman under systemd

Components

Component	Kind	Installation methods	Ports
Master (master)	master	binary, podman	9333/tcp, 19333/tcp, 9324/tcp
Volume server (volume)	worker	binary, podman	8180/tcp, 18180/tcp, 9325/tcp
Filer (filer)	master	binary, podman	8888/tcp, 18888/tcp, 9326/tcp
S3 gateway (s3)	worker	binary, podman	8333/tcp, 9327/tcp
Admin console (admin)	master	binary, podman	12535/tcp

Single node (single) (default)

One master, one volume server, one filer, one S3 gateway and the admin console.

What the mode deploys:

Component	Placement
master	min 1, max 1
volume	min 1, max 1
filer	min 1, max 1
s3	min 1, max 1
admin	min 1, max 1

Distributed (distributed)

Raft masters (odd count), replicated volume servers, several filers and S3 gateways behind the load balancer.

What the mode deploys:

Component	Placement
master	min 3, odd number, recommended 3
volume	min 3, recommended 3
filer	min 2, recommended 2
s3	min 2, recommended 2
admin	min 1, max 1

Install this service

The install wizard of the Navin Manager plans, validates and runs the installation; you need the services:install permission on the cluster.

1. Open the wizard. In Clusters, choose the row action Install services of the target cluster. The wizard opens on its first step, Service.

2. Choose the service. On the Service step, select SeaweedFS object storage. The card shows the licence Apache-2.0. Pick the Method among binary, podman (default binary). To register an existing s3 service of your organisation instead, turn on Use an existing external service. As a foundation service it is already selected when the cluster does not have it.

3. Choose the hosts and the mode. On the Hosts step, tick the hosts, then choose the Mode: single (default), distributed. Each mode deploys the components listed in Installation methods and modes. With several components, place each one on its hosts in Component placement (Suggest placement proposes a placement that respects the cardinalities).

4. Bindings. This service has no dependency: the Bindings step has nothing to bind.

5. Configure. On the Configure step, review the parameters (see Configuration parameters). Passwords left empty with a generated default are generated and sealed by the Manager.

6. Review and install. On the Install step the Manager validates the plan and shows the installation order; when it says "The plan is valid. Ready to install.", choose Install. A highly available mode is installed only when its HA checks pass.

7. Verify. The operation ends when the health checks of every instance pass (see Health checks); the service then shows as running in Services. Open the service and choose Run the smoke test in the Checks card: Creates a bucket, puts an object and reads it back through the S3 API (signature V4), then deletes both.

High availability

Cluster	native (native)
High availability	native (native)
Failover	load balancer (load-balancer)
Replication	native (native)
Quorum	Raft (raft)
Discovery	static (static)
Entry point	load balancer (load-balancer)
Official documentation	https://github.com/seaweedfs/seaweedfs/blob/master/note/slides/seaweedfs-production-setup.md
References	https://github.com/seaweedfs/seaweedfs/wiki/Production-Setup
Peer TLS parameter	tls_enabled
Cluster status command	volume_list

Topology per mode

Modes	Highest catalog level	Distribution	Quorum component	Fault domains	Description
single	standalone (standalone)	single (single)	-	1	One master, one volume server, one filer and one S3 gateway.
distributed	cluster (cluster)	active-active (active-active)	master	3	Raft masters, replicated volume servers, several filers and S3 gateways behind the load balancer.

Notes

• Optional when the bank already runs a highly available object storage: bind the services to it.
• Each filer keeps its metadata in a local leveldb2 store synchronised with its peers; a shared metadata store is the stronger option of the official documentation.

Configuration parameters

Network

Parameter	Type	Default	Allowed values	Required	Secret	Restart	Description
Master port (master_port)	port	9333	-	no	no	no	HTTP port of the masters; gRPC uses this port plus 10000.
Volume port (volume_port)	port	8180	-	no	no	no	HTTP port of the volume servers; gRPC uses this port plus 10000.
Filer port (filer_port)	port	8888	-	no	no	no	HTTP port of the filers; gRPC uses this port plus 10000.
S3 API port (s3_port)	port	8333	-	no	no	no	Port of the S3 gateway.
Metrics port of the master (master_metrics_port)	port	9324	-	no	no	no	Prometheus port of the master (distinct per process: one host can run every component).
Metrics port of the volume servers (volume_metrics_port)	port	9325	-	no	no	no	Prometheus port of the volume servers (distinct per process: one host can run every component).
Metrics port of the filers (filer_metrics_port)	port	9326	-	no	no	no	Prometheus port of the filers (distinct per process: one host can run every component).
Metrics port of the S3 gateways (s3_metrics_port)	port	9327	-	no	no	no	Prometheus port of the S3 gateways (distinct per process: one host can run every component).
Admin console port (admin_ui_port)	port	12535	-	no	no	no	HTTP port of the web console weed admin; the worker gRPC uses this port plus 10000.

Storage

Parameter	Type	Default	Allowed values	Required	Secret	Restart	Description
Region (region)	string	eu-west-3	-	no	no	no	S3 region announced to the clients (signature V4 scope).
Replication (replication)	enum	000	000, 001, 010, 100, 002	no	no	no	Default replica placement (xyz: other data centres, other racks, other servers). (recommended '000' if len(topology.volume) < 2 else ('001' if len(topology.volume) < 3 else '002'))
Volume size limit (volume_size_mb)	int	1024	min 64, max 30000, MB	no	no	no	Size at which a volume becomes read only and a new one is created.
Volumes per server (max_volumes)	int	100	min 1, max 10000	no	no	no	Maximum number of volumes of one volume server.

Security

Parameter	Type	Default	Allowed values	Required	Secret	Restart	Description
Admin access key (admin_access_key)	string	navin-admin	^[A-Za-z0-9_-]{3,64}$	no	no	no	Access key of the S3 administrator identity.
Admin secret key (admin_secret_key)	password	generated	-	no	yes	no	Secret key of the S3 administrator (operator commands and smoke test only).
Admin console user (admin_ui_user)	string	admin	^[A-Za-z0-9_.-]{3,64}$	no	no	no	Login of the web console weed admin (WEED_ADMIN_USER).
Admin console password (admin_ui_password)	password	generated	-	no	yes	no	Password of the web console weed admin (WEED_ADMIN_PASSWORD), generated at each install and kept in the Manager vault; without it the console would run without authentication.
TLS (tls_enabled)	bool	false	-	no	no	yes	Mutual TLS on the gRPC of every component (security.toml) and HTTPS on every HTTP port (S3 API, filers, volume servers, masters, admin console) with the certificates issued by the manager CA.

Endpoints

Endpoint	Scheme	Component	Port	Path	TLS parameter	Binding parameters	Binding secrets	Provisioning command
s3	http	s3	8333 (s3_port)	-	tls_enabled	region, bucket, access_key, path_style	secret_key	provision_consumer
filer	http	filer	8888 (filer_port)	-	tls_enabled	-	-	-

Client configuration files

Files rendered for the client configuration download:

• seaweedfs.env (client.env.j2)

Commands

Command	Component	Target	Description
Provision a consumer bucket (provision_consumer)	s3	first host	Creates the bucket and an S3 identity limited to that bucket for one consumer (idempotent).
Volume list (volume_list)	s3	first host	Runs volume.list in weed shell (servers, volumes, replicas).

Command parameters

Command	Parameter	Type	Default	Required	Description
provision_consumer	Bucket (bucket)	string	-	yes	Bucket of the consumer.
provision_consumer	Access key (access_key)	string	-	yes	Identity of the consumer.
provision_consumer	Secret key (secret_key)	password	-	yes	Secret key of the identity (derived per consumer).

Health checks

Liveness (per instance)

Component	Check	Details
master	HTTP {{ 'https' if config.tls_enabled else 'http' }}://{{ host.fqdn }}:{{ config.master_port }}/cluster/status	Expected 200; 60 retries; interval 2 s; timeout 5 s
volume	HTTP {{ 'https' if config.tls_enabled else 'http' }}://{{ host.fqdn }}:{{ config.volume_port }}/status	Expected 200; 60 retries; interval 2 s; timeout 5 s
filer	HTTP {{ 'https' if config.tls_enabled else 'http' }}://{{ host.fqdn }}:{{ config.filer_port }}/healthz	Expected 200; 60 retries; interval 2 s; timeout 5 s
s3	HTTP {{ 'https' if config.tls_enabled else 'http' }}://{{ host.fqdn }}:{{ config.s3_port }}/healthz	Expected 200; 60 retries; interval 2 s; timeout 5 s
admin	HTTP {{ 'https' if config.tls_enabled else 'http' }}://{{ host.fqdn }}:{{ config.admin_ui_port }}/health	Expected 200; 60 retries; interval 2 s; timeout 5 s

Readiness (service check)

Check	Details
HTTP {{ 'https' if config.tls_enabled else 'http' }}://{{ host.fqdn }}:{{ config.master_port }}/cluster/healthz	Expected 200
HTTP {{ 'https' if config.tls_enabled else 'http' }}://{{ host.fqdn }}:{{ config.s3_port }}/healthz	Expected 200

Smoke test

Creates a bucket, puts an object and reads it back through the S3 API (signature V4), then deletes both. (s3: put, get, cleanup)

Preflight checks

Check	Type	Meaning	Severity	Components
memory	memory_mb {"min": 1024}	at least 1024 MB of memory	blocking	every component
disk	disk_free_mb {"path": "/var/lib/navin", "min": 10240}	at least 10240 MB free for /var/lib/navin	warning	volume
s3_port_free	port_free {"param": "s3_port"}	port 8333 free on the host	blocking	s3
master_port_free	port_free {"param": "master_port"}	port 9333 free on the host	blocking	master

Uninstall

Paths removed when the data is purged: {{ paths.data }}, {{ paths.log }}.

Quick links

• Admin console: {{ 'https' if config.tls_enabled else 'http' }}://{{ host.fqdn }}:{{ config.admin_ui_port }}/
• SeaweedFS master: {{ 'https' if config.tls_enabled else 'http' }}://{{ host.fqdn }}:{{ config.master_port }}/

Upstream documentation

• Homepage: https://seaweedfs.com
• Source: https://github.com/seaweedfs/seaweedfs
• High availability: https://github.com/seaweedfs/seaweedfs/blob/master/note/slides/seaweedfs-production-setup.md
• High availability: https://github.com/seaweedfs/seaweedfs/wiki/Production-Setup