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

CasaOS implements Samba sharing functionality through a dual-layer architecture that combines HTTP API handlers in route/v1/samba.go for request orchestration with a low-level SMB client wrapper in 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 file defines Echo framework handlers that process frontend requests, while 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 checks whether the smbd systemd service is operational by calling systemctl.IsServiceRunning("smbd"). It also inspects the CasaOS-generated 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 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:

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

Response:

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

To create a local share:

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

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

To connect a remote Samba host:

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:

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

Summary

• CasaOS implements Samba sharing through route/v1/samba.go for HTTP API handling and 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. The handler also inspects the CasaOS-generated header in 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, 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}