# How CasaOS Implements Samba Sharing Functionality: API and SMB Client Architecture

> Discover how CasaOS implements Samba sharing via its API and SMB client architecture, leveraging go-smb2 for seamless remote access and share management.

- Repository: [IceWhale/CasaOS](https://github.com/IceWhaleTech/CasaOS)
- Tags: internals
- Published: 2026-06-26

---

**CasaOS implements Samba sharing functionality through a dual-layer architecture that combines HTTP API handlers in [`route/v1/samba.go`](https://github.com/IceWhaleTech/CasaOS/blob/main/route/v1/samba.go) for request orchestration with a low-level SMB client wrapper in [`pkg/samba/smaba.go`](https://github.com/IceWhaleTech/CasaOS/blob/main/pkg/samba/smaba.go) that leverages the go-smb2 library for remote authentication and share enumeration.**

CasaOS provides a complete Samba (SMB) sharing stack for home cloud environments, enabling both local directory sharing and remote server mounting. The implementation centers on two core components: an API layer that exposes HTTP endpoints for service management and a dedicated SMB client library that handles NTLM authentication. This architecture cleanly separates request handling from protocol-specific operations, maintaining thin controllers while delegating database and filesystem operations to the service layer.

## Architecture Overview

The CasaOS Samba sharing functionality spans two primary packages. The [`route/v1/samba.go`](https://github.com/IceWhaleTech/CasaOS/blob/main/route/v1/samba.go) file defines Echo framework handlers that process frontend requests, while [`pkg/samba/smaba.go`](https://github.com/IceWhaleTech/CasaOS/blob/main/pkg/samba/smaba.go) contains the low-level SMB client implementation. The system distinguishes between **local share management** (publishing directories via the local Samba daemon) and **remote connection handling** (mounting external SMB servers).

All database operations delegate to the service layer through `service.MyService.Shares()` for local shares and `service.MyService.Connections()` for remote mounts, ensuring HTTP handlers remain focused on request validation and workflow orchestration.

## Service Status and Local Share Management

### Monitoring the Samba Daemon

The `GetSambaStatus` handler in [`route/v1/samba.go`](https://github.com/IceWhaleTech/CasaOS/blob/main/route/v1/samba.go) checks whether the `smbd` systemd service is operational by calling `systemctl.IsServiceRunning("smbd")`. It also inspects the CasaOS-generated [`smb.conf`](https://github.com/IceWhaleTech/CasaOS/blob/main/smb.conf) header to determine if the Samba daemon requires initialization, returning a `need_init` flag to the frontend.

### Creating and Managing Local Shares

Local share CRUD operations follow a strict validation workflow. The `PostSambaSharesCreate` handler validates each requested path to ensure it is not already shared, then sets directory permissions using `os.Chmod(v.Path, 0o777)` to guarantee accessibility. Share definitions persist through the service layer via `service.MyService.Shares().GetSharesList()` and corresponding create methods, storing records as `SharesDBModel` instances.

## Remote Samba Connection Handling

### Connecting to Remote Hosts

The `PostSambaConnectionsCreate` handler orchestrates remote mount creation through several coordinated steps:

1. **Host normalization**: Strips path components using `strings.Split(connection.Host, "/")[0]`
2. **Share enumeration**: Calls `samba.GetSambaSharesList` to authenticate and retrieve available shares
3. **Mount point creation**: Generates directories under `/mnt/<host>` for each discovered share
4. **Filesystem mounting**: Invokes `service.MyService.Connections().MountSmaba` to mount each share
5. **Persistence**: Stores connection details as `ConnectionsDBModel` records

### SMB Client Library Implementation

The [`pkg/samba/smaba.go`](https://github.com/IceWhaleTech/CasaOS/blob/main/pkg/samba/smaba.go) file wraps the third-party **go-smb2** library to provide NTLM authentication and share enumeration. The `GetSambaSharesList(host, port, username, password)` function establishes a TCP connection, performs NTLM authentication, and returns a slice of available share names. The `ConnectSambaService` function provides lightweight validation used during connection creation to verify share accessibility before mounting.

### Disconnecting and Cleanup

The `DeleteSambaConnections` handler manages connection teardown. When deleting a connection by ID, it unmounts all existing sub-folders under `/mnt/<host>` before removing the `ConnectionsDBModel` record from the database, ensuring no stale mount points remain.

## API Endpoints and Usage Examples

CasaOS exposes RESTful endpoints for Samba operations at `/api/v1/samba/`.

To check service health:

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

```

Response:

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

```

To create a local share:

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

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

```

To connect a remote Samba host:

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

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

```

This triggers the SMB client to enumerate shares like `["Public","Videos"]` and create corresponding mount points at `/mnt/192.168.1.50/Public` and `/mnt/192.168.1.50/Videos`.

To remove a connection:

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

```

## Summary

- CasaOS implements Samba sharing through [`route/v1/samba.go`](https://github.com/IceWhaleTech/CasaOS/blob/main/route/v1/samba.go) for HTTP API handling and [`pkg/samba/smaba.go`](https://github.com/IceWhaleTech/CasaOS/blob/main/pkg/samba/smaba.go) for SMB protocol operations.
- The system uses `systemctl.IsServiceRunning` to monitor the `smbd` daemon and manages local shares via `SharesDBModel` records with `0777` permissions.
- Remote connections rely on the go-smb2 library for NTLM authentication and enumerate shares before mounting them under `/mnt/<host>`.
- All database operations delegate to `service.MyService.Shares()` and `service.MyService.Connections()`, keeping HTTP handlers focused on validation and orchestration.

## Frequently Asked Questions

### How does CasaOS check if the Samba service is running?

CasaOS calls `systemctl.IsServiceRunning("smbd")` in the `GetSambaStatus` handler within [`route/v1/samba.go`](https://github.com/IceWhaleTech/CasaOS/blob/main/route/v1/samba.go). The handler also inspects the CasaOS-generated header in [`smb.conf`](https://github.com/IceWhaleTech/CasaOS/blob/main/smb.conf) to determine if initial configuration is required, returning a `need_init` status flag to indicate whether the service needs setup.

### What library does CasaOS use for SMB protocol operations?

According to the source code in [`pkg/samba/smaba.go`](https://github.com/IceWhaleTech/CasaOS/blob/main/pkg/samba/smaba.go), CasaOS wraps the **go-smb2** library to handle low-level SMB operations. This wrapper manages TCP connections, NTLM authentication, and share enumeration through functions like `GetSambaSharesList` and `ConnectSambaService`.

### Where does CasaOS mount remote Samba shares?

When creating a remote connection via `PostSambaConnectionsCreate`, CasaOS creates mount points under `/mnt/<host>` where `<host>` is the normalized hostname or IP address. Each individual share receives a subfolder within this directory, and the system mounts each share using `service.MyService.Connections().MountSmaba`.

### How does CasaOS handle permissions for local Samba shares?

During local share creation in `PostSambaSharesCreate`, CasaOS sets directory permissions to `0777` using `os.Chmod(v.Path, 0o777)` to ensure the Samba daemon can read and write the shared directory regardless of the accessing user. This occurs after path validation but before persisting the share record to the database.