How Samba Sharing Is Implemented and Configured in CasaOS

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 – Contains Echo framework handlers for the REST API endpoints. This file defines GetSambaStatus, GetSambaSharesList, PostSambaSharesCreate, and connection management handlers.
• 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 calls systemctl.IsServiceRunning("smbd") to check the systemd service state. It also inspects the CasaOS-generated smb.conf header to determine if initial configuration is required.

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

A typical response indicates whether initialization is needed:

{
  "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.

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 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.

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 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.

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

Key Implementation Files

• route/v1/samba.go – Defines HTTP handlers for Samba status, local share CRUD, and remote connection management.
• 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 for the HTTP API and 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 file checked by GetSambaStatus.

How does CasaOS authenticate with remote Samba servers?

The system uses the go-smb2 library via 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.

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