SeaweedFS

https://seaweedfs.com/docs
Admin
SeaweedFS is a fast distributed storage system for objects, files, and arbitrary blobs, primarily...
Tokens:35,840
Snippets:523
Trust Score:7.5
Update:3 months ago
Show doc for...
Tokens:
Raw
### SeaweedFS Multi-Tenancy Quickstart Commands

Source: https://seaweedfs.com/docs/reference/multi_tenancy

A minimal end-to-end setup for multi-tenancy. This includes enabling the feature, bootstrapping an admin, creating a tenant, attaching a collection, creating a user, and verifying the setup.

```bash
# 1. Enable the feature flag on the filer
$ cat >> /etc/seaweedfs/filer.toml <<EOF
[filer.enterprise.multi_tenancy]
enabled = true
[filer.enterprise.audit]
enabled = true
file = "/var/log/seaweedfs/audit.jsonl"
EOF
$ systemctl restart seaweedfs-filer

# 2. Bootstrap the platform admin (one-time, creates a principal with the
#    platform-admin role binding)
$ weed shell
> platform.bootstrap -id alice -password "S3cret!" -name "Alice Admin"

# 3. Create a tenant
> tenant.create -id acme -name "Acme Corp" -quota-bytes-hard 10737418240

# 4. Attach a collection to the tenant (becomes an S3 bucket of the same name)
> tenant.collection.add -tenant acme -name acme-data

# 5. Create a user inside the tenant
> principal.create -id alice@acme -tenant acme -password "U5er!" -name "Alice at Acme"
> binding.create -subject-kind principal -subject-id alice@acme \
                 -role tenant-admin -scope tenant:acme

# 6. Verify
> tenant.list
> principal.list -tenant acme
> binding.list


```

--------------------------------

### Install SeaweedFS Kernel Module

Source: https://seaweedfs.com/docs/kernel_mount

Installs the kernel module and daemon, builds the module for your running kernel, and starts the daemon. Pass the filer address to have the daemon start ready to mount.

```bash
curl -fsSL https://raw.githubusercontent.com/seaweedfs/artifactory/main/seaweed-vfs/install.sh \
  | sudo FILER=filer.example.com:18888 bash

```

--------------------------------

### Start Other SeaweedFS Components

Source: https://seaweedfs.com/docs/deploy

Standard command to start other SeaweedFS components like volume and filer.

```bash
weed volume ...
weed filer ...
```

--------------------------------

### Start SeaweedFS Server with Environment Variable License

Source: https://seaweedfs.com/docs/deploy

Start the SeaweedFS server component after setting the SEAWEED_LICENSE environment variable.

```bash
weed server ...
```

--------------------------------

### Start SeaweedFS Master with Environment Variable License

Source: https://seaweedfs.com/docs/deploy

Start the SeaweedFS master component after setting the SEAWEED_LICENSE environment variable.

```bash
weed master ...
```

--------------------------------

### Start SeaweedFS Server with License Flag

Source: https://seaweedfs.com/docs/deploy

Use the -license flag to specify the path to your SeaweedFS Enterprise license file when starting the server component.

```bash
weed server -license=/path/to/seaweed-license.json ...
```

--------------------------------

### Install Precompiled Kernel Module for New Kernel

Source: https://seaweedfs.com/docs/reference/kernel_mount_operations

When using precompiled modules (SEAWEEDFS_VFS_KMOD=1), install the matching seaweedfs-vfs-kmod-<new-kver> package for the new kernel before booting into it.

```bash
SEAWEEDFS_VFS_KMOD=1
```

--------------------------------

### All-in-one Server Deployment

Source: https://seaweedfs.com/docs/reference/storage_compression

Example of running a server with default zstd compression enabled for a small deployment.

```bash
weed server -dir=/data -s3
```

--------------------------------

### Start SeaweedFS Master with License Flag

Source: https://seaweedfs.com/docs/deploy

Use the -license flag to specify the path to your SeaweedFS Enterprise license file when starting the master component.

```bash
weed master -license=/path/to/seaweed-license.json ...
```

--------------------------------

### Install RDMA Kernel-Mount Daemon

Source: https://seaweedfs.com/docs/reference/rdma

Install the RDMA-enabled VFS package using `apt` or `rpm`. This replaces the non-RDMA version and requires `rdma-core`.

```bash
apt install ./seaweedfs-vfs-rdma_<ver>_<arch>.deb   # or the .rpm
```

```bash
mount -t seaweedvfs none /mnt/seaweed                # same as the non-RDMA daemon
```

--------------------------------

### Start SeaweedFS Master Server

Source: https://seaweedfs.com

Starts the SeaweedFS master server with a specified port. This is a foundational step for any SeaweedFS cluster operation.

```bash
weed server -master.port=9333
```

--------------------------------

### Manual Install SeaweedFS VFS (RHEL/Fedora)

Source: https://seaweedfs.com/docs/reference/kernel_mount_operations

Installs SeaweedFS VFS packages manually on RHEL/Fedora systems using DNF. Supports DKMS modules.

```bash
# RHEL / Fedora  (on SUSE: zypper install)
sudo dnf install ./seaweedfs-vfs-dkms-<ver>-1.noarch.rpm ./seaweedfs-vfs-<ver>-1.x86_64.rpm

```

--------------------------------

### Upgrade SeaweedFS with Installer Script

Source: https://seaweedfs.com/docs/reference/kernel_mount_operations

Upgrade SeaweedFS by running the provided installation script. This script detects existing installations and reloads only necessary components.

```bash
curl -fsSL https://raw.githubusercontent.com/seaweedfs/artifactory/main/seaweed-vfs/install.sh | sudo bash
```

--------------------------------

### RDMA Volume Server Startup Log

Source: https://seaweedfs.com/docs/reference/rdma

Example log output indicating successful RDMA listener binding and activation on the specified IP and port.

```log
RDMA listener bound on 10.0.0.6:18516
RDMA listener active

```

--------------------------------

### Install SeaweedFS VFS with Precompiled Module

Source: https://seaweedfs.com/docs/reference/kernel_mount_operations

Installs the SeaweedFS VFS module using a precompiled kernel object (.ko) for systems that cannot compile modules (e.g., no toolchain or kernel headers). Requires an exact kernel version match.

```bash
curl -fsSL https://raw.githubusercontent.com/seaweedfs/artifactory/main/seaweed-vfs/install.sh \
  | sudo SEAWEEDFS_VFS_KMOD=1 FILER=filer.example.com:18888 bash

```

--------------------------------

### Setup SoftRoCE for RDMA Testing

Source: https://seaweedfs.com/docs/reference/rdma

Load the SoftRoCE kernel module, create an RDMA link using an existing network interface, and ensure the link is active. Unlimited memory locking is also configured.

```bash
sudo modprobe rdma_rxe
sudo rdma link add rxe0 type rxe netdev eth0
rdma link                       # rxe0 should be ACTIVE
ulimit -l unlimited             # let reg_mr pin memory regions
```

--------------------------------

### Start SeaweedFS Cluster with Multiple Interfaces

Source: https://seaweedfs.com

Run a SeaweedFS cluster with S3, WebDAV, and FUSE (POSIX mount) enabled. This command also starts the built-in Iceberg REST catalog.

```bash
weed server -s3 -webdav
```

--------------------------------

### Manual Install SeaweedFS VFS (Debian/Ubuntu)

Source: https://seaweedfs.com/docs/reference/kernel_mount_operations

Installs SeaweedFS VFS packages manually on Debian/Ubuntu systems. Supports both DKMS modules and precompiled modules.

```bash
# Debian / Ubuntu — DKMS module + daemon
sudo apt install ./seaweedfs-vfs-dkms_<ver>_all.deb ./seaweedfs-vfs_<ver>_amd64.deb
# ...or a precompiled module instead of DKMS (no compiler/headers on the box):
sudo apt install --no-install-recommends \
  ./seaweedfs-vfs-kmod-$(uname -r)_<ver>_amd64.deb ./seaweedfs-vfs_<ver>_amd64.deb

```

--------------------------------

### Example Redirect URLs

Source: https://seaweedfs.com/docs/reference/admin_oidc

Examples of valid redirect URLs for the admin UI OIDC callback. Ensure the URL registered with your identity provider exactly matches the one configured in `security.toml`.

```plaintext
https://admin.example.com/login/oidc/callback
https://admin.example.com/seaweedfs/login/oidc/callback

```

--------------------------------

### Start Remote Vacuum Worker (Heavy Tasks)

Source: https://seaweedfs.com/docs/remote_vacuum

Start a worker process that handles heavy tasks, including remote vacuum. Ensure the worker has sufficient disk space in its working directory for downloaded and compacted objects.

```bash
weed worker -admin=admin.example.com:23646 -jobType=heavy \
  -workingDir=/var/lib/seaweedfs-plugin -maxExecute=2
```

--------------------------------

### Start SeaweedFS Remote Vacuum Worker

Source: https://seaweedfs.com/docs/reference/remote_vacuum

Start a worker handling all heavy tasks, which includes remote vacuum. This command specifies the admin server, job type, and working directory.

```bash
# Start a worker handling all heavy tasks (includes remote vacuum)
weed worker -admin=admin.example.com:23646 -jobType=heavy \
  -workingDir=/var/lib/seaweedfs-plugin -maxExecute=2

# Select remote vacuum explicitly (alias: tier.vacuum)
weed worker -admin=admin.example.com:23646 -jobType=remote_vacuum \
  -workingDir=/var/lib/seaweedfs-plugin

# Start a worker handling all available task types
weed worker -admin=admin.example.com:23646 -jobType=all \
  -workingDir=/var/lib/seaweedfs-plugin

```

--------------------------------

### Build and Manage SeaweedFS Kernel Module

Source: https://seaweedfs.com/docs/reference/kernel_mount_operations

Build the kernel module using make, load it with insmod, and unload it with rmmod. Ensure you have make, gcc, and kernel headers installed.

```bash
make 
sudo insmod seaweedvfs.ko 
# ...run the daemon (or the systemd unit), then mount as above
sudo rmmod seaweedvfs
```

--------------------------------

### Default Volume Server Configuration

Source: https://seaweedfs.com/docs/storage_compression

This command starts a volume server with default zstd compression enabled. No specific flags are needed as zstd is the default.

```bash
# Default: new data is compressed with zstd automatically — no flag needed
weed volume -dir=/data -mserver=master:9333
```

--------------------------------

### Opt Out to gzip Compression

Source: https://seaweedfs.com/docs/reference/storage_compression

Explicitly configure a process to use gzip compression instead of zstd, for example, if a license does not permit zstd writes.

```bash
weed volume -dir=/data -mserver=master:9333 -compression.method=gzip
```

--------------------------------

### Set Per-Access Key Concurrency Limits

Source: https://seaweedfs.com/docs/reference/s3_concurrency_limit

Limits concurrency for a specific access key. This example sets a cap of 20 concurrent requests for all action classes for the 'AKIA-nightly-batch' access key. Changes are applied persistently.

```bash
s3.concurrency -accessKeys AKIA-nightly-batch -maxRequests 20 -apply
```

--------------------------------

### Create User and Bind Role

Source: https://seaweedfs.com/docs/multi_tenancy

Create a new principal and then bind a role to a specific tenant scope. These commands are part of 'weed shell'.

```bash
principal.create
binding.create -role tenant-admin -scope tenant:acme
```

--------------------------------

### Create a Tenant with Hard Quota

Source: https://seaweedfs.com/docs/reference/multi_tenancy

Use this command to create a new tenant with specified soft and hard byte quotas. Ensure the tenant ID and name are unique.

```bash
> tenant.create -id billing -name "Billing Dept" \
                -quota-bytes-soft 53687091200 \
                -quota-bytes-hard 107374182400

```

--------------------------------

### Enable Delayed Garbage Collection (Retention)

Source: https://seaweedfs.com/docs/reference/data_recovery

Configure the master server to enable data recovery by setting a non-zero retention window. Restart the master to apply changes. The default is 0, disabling recovery. A trial license limits retention to 1 hour.

```bash
weed master -deletionRetention=72h
```

```bash
weed server -master.deletionRetention=72h
```

--------------------------------

### Configure Standalone SeaweedFS Daemon

Source: https://seaweedfs.com/docs/reference/kernel_mount_operations

Sets up a standalone SeaweedFS daemon that boots at startup and can be used for mounting without a direct filer association. This is less common as _netdev typically handles per-filer daemons.

```bash
printf 'FILER=filer.example.com:18888
EXTRA_ARGS=
' | sudo tee /etc/seaweedfs-vfs/config
sudo systemctl enable --now seaweed-vfs.service
sudo mount -t seaweedvfs none /mnt/seaweed     # no filer — uses the standalone daemon

```

--------------------------------

### Enable RDMA on SeaweedFS Volume Server

Source: https://seaweedfs.com/docs/reference/rdma

Configure the volume server to enable RDMA listener. Ensure the `--rdma.ip` is on the RDMA network interface. RDMA is opt-in and fails safely to HTTP.

```bash
weed-volume \
  --ip 10.0.0.6 --port 8080 --master <master>:9333 --dir /data/vol --max 100 \
  --rdma.enabled \
  --rdma.ip 10.0.0.6        # must be an IP on the RDMA netdev; defaults to --ip
```

--------------------------------

### Start EC Vacuum Worker

Source: https://seaweedfs.com/docs/reference/ec_vacuum

Start a worker process for EC tasks, including EC encoding, repair, and vacuum. Ensure the admin server address and job type are correctly specified.

```bash
# Start a worker for EC tasks (includes EC encoding, EC repair, and EC vacuum)
weed worker -admin=admin.example.com:23646 -jobType=erasure_coding \
  -workingDir=/var/lib/seaweedfs-plugin -maxExecute=2
```

```bash
# Start a worker handling all heavy tasks
weed worker -admin=admin.example.com:23646 -jobType=heavy \
  -workingDir=/var/lib/seaweedfs-plugin -maxExecute=4
```

```bash
# Start a worker handling all available task types
weed worker -admin=admin.example.com:23646 -jobType=all \
  -workingDir=/var/lib/seaweedfs-plugin
```

--------------------------------

### Start EC Repair Worker

Source: https://seaweedfs.com/docs/reference/ec_repair

Start a worker process for EC tasks. Ensure the admin server address and job type are correctly specified. The working directory is used for temporary shard data.

```bash
# Start a worker for EC tasks (includes both EC encoding and EC repair)
weed worker -admin=admin.example.com:23646 -jobType=erasure_coding \
  -workingDir=/var/lib/seaweedfs-plugin -maxExecute=2

# Start a worker handling all heavy tasks (EC encoding, EC repair, volume balancing, etc.)
weed worker -admin=admin.example.com:23646 -jobType=heavy \
  -workingDir=/var/lib/seaweedfs-plugin -maxExecute=4

# Start a worker handling all available task types
weed worker -admin=admin.example.com:23646 -jobType=all \
  -workingDir=/var/lib/seaweedfs-plugin

```

--------------------------------

### Create a Tenant with Quota

Source: https://seaweedfs.com/docs/multi_tenancy

Create a new tenant with a specified hard quota in bytes. This command is executed within 'weed shell'.

```bash
tenant.create -id acme -name "Acme Corp" -quota-bytes-hard 10737418240
```

--------------------------------

### Start EC Vacuum Worker

Source: https://seaweedfs.com/docs/ec_vacuum

Starts a `weed worker` process to handle erasure coding tasks, including EC vacuum. Ensure the `erasure_coding` handler is enabled on the admin server. The worker will automatically pick up EC vacuum jobs.

```bash
# Start a worker for EC tasks (includes EC encoding, EC repair, and EC vacuum)
weed worker -admin=admin.example.com:23646 -jobType=erasure_coding \
  -workingDir=/var/lib/seaweedfs-plugin -maxExecute=2

```

--------------------------------

### Start Remote Vacuum Worker (Explicit Task)

Source: https://seaweedfs.com/docs/remote_vacuum

Start a worker process that explicitly handles only the remote vacuum task. This is useful for dedicated remote vacuum operations. The worker's working directory should accommodate twice the size of the largest tiered object.

```bash
weed worker -admin=admin.example.com:23646 -jobType=remote_vacuum \
  -workingDir=/var/lib/seaweedfs-plugin
```

--------------------------------

### Start EC Repair Worker

Source: https://seaweedfs.com/docs/ec_repair

Start a `weed worker` process for erasure coding tasks, including EC encoding and repair. Specify the admin server address, job type, working directory, and maximum concurrent executions. Run at least two workers for high availability.

```bash
weed worker -admin=admin.example.com:23646 -jobType=erasure_coding \
  -workingDir=/var/lib/seaweedfs-plugin -maxExecute=2
```

--------------------------------

### Get File Version Timeline

Source: https://seaweedfs.com/docs/reference/point_in_time_recovery

Retrieves the version timeline for a specific file, showing its history.

```APIDOC
## Get File Version Timeline

### Description
Retrieves a single file's version timeline.

### Method
GET

### Endpoint
`/api/pitr/file`

### Parameters
#### Query Parameters
- **path** (string) - Required - The path to the file.

### Response
#### Success Response (200)
- **versions** (array) - A list of historical versions of the file.
```

--------------------------------

### Enable Multi-Tenancy in filer.toml

Source: https://seaweedfs.com/docs/reference/multi_tenancy

Configure multi-tenancy and audit logging by editing the `filer.toml` file. Ensure JWT signing key is also configured.

```toml
[filer.enterprise.multi_tenancy]
enabled = true

[filer.enterprise.audit]
enabled = true
file = "/var/log/seaweedfs/audit.jsonl"
stdout = false


```

```toml
[jwt.filer_signing]
key = "replace-me-with-a-strong-random-key"


```

--------------------------------

### Get Deletion Event Details

Source: https://seaweedfs.com/docs/reference/data_recovery

Retrieves detailed information for a specific deletion event identified by its event ID.

```APIDOC
## GET /api/undelete/event/{eventId}

### Description
Details for a single deletion.

### Method
GET

### Endpoint
/api/undelete/event/{eventId}

### Parameters
#### Path Parameters
- **eventId** (string) - Required - The unique identifier of the deletion event.
```

--------------------------------

### Import MOK key with mokutil

Source: https://seaweedfs.com/docs/reference/kernel_mount_operations

Import a Machine Owner Key (MOK) for signing kernel modules. This is a one-time operation required for Secure Boot.

```bash
mokutil --import /path/to/signing/certificate.pem
```

--------------------------------

### Get PITR Settings

Source: https://seaweedfs.com/docs/reference/point_in_time_recovery

Retrieves the current Point-in-Time Recovery (PITR) settings, including whether it is enabled and the retention window.

```APIDOC
## Get PITR Settings

### Description
Retrieves whether PITR is enabled, and the retention window.

### Method
GET

### Endpoint
`/api/pitr/settings`

### Response
#### Success Response (200)
- **enabled** (boolean) - Whether PITR is enabled.
- **retention_window_seconds** (integer) - The retention window in seconds.
```

--------------------------------

### Create S3 User with Tenant

Source: https://seaweedfs.com/docs/reference/multi_tenancy

Use this command to create a new S3 user and associate them with a specific tenant. The tenant ID is stamped in the account's Id.

```bash
> s3.user.create -name alice@acme -accessKey ALICE... -secretKey ... -tenant acme
```

--------------------------------

### Get Undelete Owners

Source: https://seaweedfs.com/docs/reference/data_recovery

Fetches a list of owners (account ID and label) that can be used for filtering by user in undelete operations.

```APIDOC
## GET /api/undelete/owners

### Description
Owners (account id + label) for the by-user filter.

### Method
GET

### Endpoint
/api/undelete/owners
```

--------------------------------

### Get Undelete Settings

Source: https://seaweedfs.com/docs/reference/data_recovery

Retrieves the current undelete settings, including whether recovery is enabled and the retention window duration.

```APIDOC
## GET /api/undelete/settings

### Description
Whether recovery is enabled, and the retention window.

### Method
GET

### Endpoint
/api/undelete/settings
```
Tokens:
Raw