# CasaOS Storage Mounting and Unmounting: How SMB, rclone, and Network Drives Work

> Learn how CasaOS manages storage mounting for SMB, rclone, and network drives. Discover a unified interface for all your storage needs. Explore the technical details.

- Repository: [IceWhale/CasaOS](https://github.com/IceWhaleTech/CasaOS)
- Tags: how-to-guide
- Published: 2026-06-27

---

**CasaOS abstracts storage operations through a service layer that communicates with the rclone HTTP API over a Unix socket and manages Samba configurations directly, enabling unified handling of SMB shares, WebDAV, and cloud remotes through a single interface.**

The CasaOS storage architecture unifies diverse network storage protocols under a consistent Go-based service layer. By delegating mount operations to the rclone HTTP API via `/var/run/rclone/rclone.sock` and maintaining custom Samba configurations in [`/etc/samba/smb.casa.conf`](https://github.com/IceWhaleTech/CasaOS/blob/main//etc/samba/smb.casa.conf), the system provides predictable mounting and unmounting behavior across SMB, cloud drives, and other network-attached storage.

## Storage Service Interface

The high-level storage API is defined in [`service/storage.go`](https://github.com/IceWhaleTech/CasaOS/blob/main/service/storage.go) through the `StorageService` interface. This contract declares the essential operations used throughout the CasaOS codebase:

```go
type StorageService interface {
    MountStorage(mountPoint, fs string) error
    UnmountStorage(mountPoint string) error
    GetStorages() (httper.MountList, error)
    // … other helpers for rclone config
}

```

The concrete implementation (`storageStruct`) delegates actual mounting logic to the **httper** helper package located in [`pkg/utils/httper/drive.go`](https://github.com/IceWhaleTech/CasaOS/blob/main/pkg/utils/httper/drive.go). This abstraction ensures that higher-level components interact with a unified interface regardless of whether the underlying storage is SMB, WebDAV, or a cloud provider.

## rclone HTTP Communication Layer

CasaOS communicates with rclone through a dedicated HTTP client implemented in [`pkg/utils/httper/drive.go`](https://github.com/IceWhaleTech/CasaOS/blob/main/pkg/utils/httper/drive.go). The client uses the `resty` library to send requests to the rclone HTTP API over a Unix socket at `/var/run/rclone/rclone.sock`.

**Mount operations** use a POST request to `/mount/mount` with the target filesystem and mount point:

```go
svc := service.NewStorageService()
err := svc.MountStorage("/mnt/smb-share", "smbremote:")
if err != nil {
    // handle error
}

```

**Unmount operations** send a POST to `/mount/unmount` specifying the mount point to release:

```go
svc := service.NewStorageService()
_ = svc.UnmountStorage("/mnt/smb-share")

```

The same client handles configuration management through methods like `CreateConfig`, `GetConfigByName`, `GetAllConfigName`, and `DeleteConfigByName`. Because all requests route through the same Unix socket, any storage backend supported by rclone—whether SMB, Nextcloud, WebDAV, or S3—can be managed through this single code path.

## SMB Share Management

For serving directories over SMB, CasaOS maintains a separate service in [`service/shares.go`](https://github.com/IceWhaleTech/CasaOS/blob/main/service/shares.go). This component manages a SQLite table of user-defined shares and handles the lifecycle of Samba configuration files.

When creating a share, the service generates a per-share stanza (e.g., `[MyShare] … path = /mnt/myshare`) and writes it to [`/etc/samba/smb.casa.conf`](https://github.com/IceWhaleTech/CasaOS/blob/main//etc/samba/smb.casa.conf). The `UpdateConfigFile()` function then aggregates these stanzas into [`/etc/samba/smb.conf`](https://github.com/IceWhaleTech/CasaOS/blob/main//etc/samba/smb.conf) while preserving CasaOS-specific defaults, and triggers `RestartSMBD` to reload the Samba daemon.

```go
share := model.SharesDBModel{
    Name:      "MyShare",
    Path:      "/mnt/smb-share",
    Anonymous: true,
}
shares := service.NewSharesService(db)
shares.CreateShare(share) // Writes config and restarts Samba

```

This separation allows CasaOS to distinguish between **mounting** remote storage (handled by rclone) and **serving** local directories via SMB (handled by the system Samba daemon).

## Automatic Mount Reconciliation

To ensure persistence across reboots, CasaOS implements `CheckAndMountAll()` in the storage service. This function iterates through every rclone remote returned by `GetAllConfigName()` and checks whether configured mount points are currently active by comparing against `GetMountList()`.

For each remote that defines a `mount_point` but is not currently mounted, the system automatically invokes `MountStorage(mountPoint, remote+":")`. This reconciliation loop ensures that network drives are reattached without manual intervention after system restarts or configuration changes.

## Unmount Cleanup Behavior

The `UnmountStorage()` method implements a two-phase cleanup process. First, it sends the unmount command to rclone via the HTTP API. If the unmount succeeds and the mount directory is empty, the function calls `file.RMDir` from [`pkg/utils/file/file.go`](https://github.com/IceWhaleTech/CasaOS/blob/main/pkg/utils/file/file.go) to remove the directory. This prevents orphaned empty mount points from accumulating in the filesystem.

To create a new rclone configuration for an SMB remote with automatic mounting:

```go
cfg := map[string]string{
    "type":          "smb",
    "host":          "192.168.1.100",
    "user":          "guest",
    "pass":          "guest",
    "mount_point":   "/mnt/smb-share",
}
svc := service.NewStorageService()
_ = svc.CreateConfig(cfg, "smbremote", "smb")
_ = svc.CheckAndMountByName("smbremote")

```

## Summary

- **Unified Interface**: [`service/storage.go`](https://github.com/IceWhaleTech/CasaOS/blob/main/service/storage.go) provides a consistent `StorageService` interface for all mount operations, delegating to rclone via [`pkg/utils/httper/drive.go`](https://github.com/IceWhaleTech/CasaOS/blob/main/pkg/utils/httper/drive.go).
- **rclone Integration**: All mount and unmount operations communicate with the rclone HTTP API over the Unix socket `/var/run/rclone/rclone.sock`, supporting any rclone-compatible backend.
- **Native SMB Handling**: [`service/shares.go`](https://github.com/IceWhaleTech/CasaOS/blob/main/service/shares.go) manages Samba configurations in [`/etc/samba/smb.casa.conf`](https://github.com/IceWhaleTech/CasaOS/blob/main//etc/samba/smb.casa.conf) and restarts the daemon via `RestartSMBD` to serve local directories.
- **Automatic Recovery**: `CheckAndMountAll()` ensures configured remotes are automatically mounted after reboots by reconciling rclone configurations against active mounts.
- **Cleanup Logic**: `UnmountStorage()` removes empty mount directories after successful unmounts to prevent filesystem clutter.

## Frequently Asked Questions

### How does CasaOS communicate with rclone?

CasaOS establishes a `resty` HTTP client in [`pkg/utils/httper/drive.go`](https://github.com/IceWhaleTech/CasaOS/blob/main/pkg/utils/httper/drive.go) that sends requests to the rclone HTTP API over a Unix domain socket at `/var/run/rclone/rclone.sock`. This allows the system to mount, unmount, and configure remotes using standard HTTP POST requests to endpoints like `/mount/mount` and `/mount/unmount`.

### Where does CasaOS store Samba share configurations?

User-defined SMB shares are stored in an SQLite database, but the actual Samba configuration is written to [`/etc/samba/smb.casa.conf`](https://github.com/IceWhaleTech/CasaOS/blob/main//etc/samba/smb.casa.conf). The `UpdateConfigFile()` function in [`service/shares.go`](https://github.com/IceWhaleTech/CasaOS/blob/main/service/shares.go) aggregates these into [`/etc/samba/smb.conf`](https://github.com/IceWhaleTech/CasaOS/blob/main//etc/samba/smb.conf) and triggers `RestartSMBD` to apply changes without restarting the entire system.

### What happens to mount points after unmounting?

When `UnmountStorage()` is called, CasaOS first requests the unmount from rclone. If successful and the directory is empty, the system removes the mount point using `file.RMDir` from [`pkg/utils/file/file.go`](https://github.com/IceWhaleTech/CasaOS/blob/main/pkg/utils/file/file.go). This ensures that unused directories do not persist in `/mnt` or other mount locations.

### How does CasaOS handle mounts after a system reboot?

The `CheckAndMountAll()` function iterates through all rclone configurations returned by `GetAllConfigName()`. For each remote that specifies a `mount_point` and is not currently listed in `GetMountList()`, it automatically executes the mount operation. This reconciliation ensures that network drives defined in the CasaOS database are automatically attached when the system starts.