# How Samba Sharing Is Implemented and Configured in CasaOS

> Learn how CasaOS implements Samba sharing using its Go API layer. Discover configuration, service management, and automated remote SMB mounting with go-smb2.

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

---

**CasaOS implements Samba sharing through a Go-based API layer that manages local share definitions, monitors the `smbd` service status, and provides automated mounting of remote SMB shares using the `go-smb2` library.**

CasaOS is an open-source home cloud system that provides native Samba (SMB) integration for both sharing local directories and connecting to remote Windows or NAS shares. Understanding how Samba sharing is implemented and configured in CasaOS reveals a clean separation between HTTP handlers, low-level SMB client operations, and persistent storage layers. The implementation spans two critical packages: the API routing layer and a dedicated SMB client wrapper.

## Architecture Overview

The Samba functionality is split between **HTTP handlers** and **SMB protocol wrappers**, with database operations delegated to a service layer.

- **[`route/v1/samba.go`](https://github.com/IceWhaleTech/CasaOS/blob/main/route/v1/samba.go)** – Contains Echo framework handlers for the REST API endpoints. This file defines `GetSambaStatus`, `GetSambaSharesList`, `PostSambaSharesCreate`, and connection management handlers.
- **[`pkg/samba/smaba.go`](https://github.com/IceWhaleTech/CasaOS/blob/main/pkg/samba/smaba.go)** – Wraps the third-party `go-smb2` library to handle TCP connections, NTLM authentication, and share enumeration on remote hosts.
- **Service layer** – `service.MyService.Shares()` and `service.MyService.Connections()` manage persistence for `SharesDBModel` and `ConnectionsDBModel` records.

## Checking Samba Service Health

Before managing shares, the system verifies that the Samba daemon is operational. The `GetSambaStatus` handler in [`route/v1/samba.go`](https://github.com/IceWhaleTech/CasaOS/blob/main/route/v1/samba.go) calls `systemctl.IsServiceRunning("smbd")` to check the systemd service state. It also inspects the CasaOS-generated [`smb.conf`](https://github.com/IceWhaleTech/CasaOS/blob/main/smb.conf) header to determine if initial configuration is required.

```http
GET /api/v1/samba/status HTTP/1.1
Host: casaos.local

```

A typical response indicates whether initialization is needed:

```json
{
  "success": 0,
  "message": "Success",
  "data": { "need_init": "true" }
}

```

## Managing Local Samba Shares

Local share management follows a standard CRUD pattern, with handlers validating paths and setting permissions before persisting records.

### Listing Existing Shares

The `GetSambaSharesList` handler retrieves share definitions by calling `service.MyService.Shares().GetSharesList()`. This returns the current database records mapped to the API response format.

### Creating New Shares

When creating shares via `PostSambaSharesCreate`, the handler performs several validation steps:

1. Validates that each requested path exists and is not already shared.
2. Sets directory permissions to `0o777` using `os.Chmod(v.Path, 0o777)` to ensure the Samba daemon has full access.
3. Persists a `SharesDBModel` record via the shares service.

```http
POST /api/v1/samba/shares HTTP/1.1
Content-Type: application/json

[
  { "path": "/share/media", "anonymous": true }
]

```

## Connecting to Remote Samba Hosts

CasaOS can mount shares from remote Windows servers or NAS devices. The `PostSambaConnectionsCreate` handler orchestrates this process by coordinating validation, mount point creation, and persistence.

### Connection Workflow

The handler executes the following sequence:

- **Host normalization** – Strips any protocol prefixes using `strings.Split(connection.Host, "/")[0]`.
- **Share enumeration** – Calls `samba.GetSambaSharesList(host, port, username, password)` from [`pkg/samba/smaba.go`](https://github.com/IceWhaleTech/CasaOS/blob/main/pkg/samba/smaba.go) to verify credentials and retrieve available share names.
- **Mount point creation** – Creates a directory at `/mnt/<host>` and subdirectories for each remote share.
- **Mount execution** – Invokes `service.MyService.Connections().MountSmaba` to mount each share.
- **Persistence** – Stores connection details in a `ConnectionsDBModel` record.

```http
POST /api/v1/samba/connections HTTP/1.1
Content-Type: application/json

{
  "host": "192.168.1.50",
  "username": "guest",
  "password": "",
  "port": "445"
}

```

### SMB Client Implementation

The [`pkg/samba/smaba.go`](https://github.com/IceWhaleTech/CasaOS/blob/main/pkg/samba/smaba.go) file provides the low-level SMB protocol interaction:

- **`GetSambaSharesList`** – Establishes a TCP connection, authenticates with NTLM, and returns a slice of available share names.
- **`ConnectSambaService`** – Performs a lightweight existence check for a specific share, used during connection validation.

### Disconnecting Remote Hosts

To remove a connection, `DeleteSambaConnections` unmounts all sub-folders under `/mnt/<host>` and deletes the corresponding database entry.

```http
DELETE /api/v1/samba/connections/42 HTTP/1.1

```

## Key Implementation Files

- **[`route/v1/samba.go`](https://github.com/IceWhaleTech/CasaOS/blob/main/route/v1/samba.go)** – Defines HTTP handlers for Samba status, local share CRUD, and remote connection management.
- **[`pkg/samba/smaba.go`](https://github.com/IceWhaleTech/CasaOS/blob/main/pkg/samba/smaba.go)** – Wraps the `go-smb2` library to provide share listing and connection validation for remote SMB servers.

## Summary

- **CasaOS** uses [`route/v1/samba.go`](https://github.com/IceWhaleTech/CasaOS/blob/main/route/v1/samba.go) for the HTTP API and [`pkg/samba/smaba.go`](https://github.com/IceWhaleTech/CasaOS/blob/main/pkg/samba/smaba.go) for SMB protocol handling.
- **Local shares** are stored in `SharesDBModel` records with `0o777` permissions set via `os.Chmod`.
- **Remote connections** use the `go-smb2` library for NTLM authentication and share enumeration.
- **Mount points** for remote shares are created under `/mnt/<host>` with individual subdirectories per share.
- **Service health** is monitored via `systemctl.IsServiceRunning("smbd")` to ensure the Samba daemon is active.

## Frequently Asked Questions

### Where does CasaOS store Samba share configurations?

Share definitions are persisted in `SharesDBModel` records accessed through `service.MyService.Shares()`, while the actual Samba daemon configuration is managed through the generated [`smb.conf`](https://github.com/IceWhaleTech/CasaOS/blob/main/smb.conf) file checked by `GetSambaStatus`.

### How does CasaOS authenticate with remote Samba servers?

The system uses the `go-smb2` library via [`pkg/samba/smaba.go`](https://github.com/IceWhaleTech/CasaOS/blob/main/pkg/samba/smaba.go) to establish TCP connections and authenticate using NTLM credentials provided in the `POST /api/v1/samba/connections` request.

### What permissions does CasaOS set on shared directories?

When creating a local share via `PostSambaSharesCreate`, the system executes `os.Chmod(v.Path, 0o777)` to ensure the Samba daemon can read and write the directory contents.

### Can CasaOS mount multiple shares from the same remote host?

Yes, `PostSambaConnectionsCreate` enumerates all available shares using `GetSambaSharesList` and automatically creates individual mount points under `/mnt/<host>/` for each share discovered on the remote server.