Ceph SMB file shares for Windows and macOS users on CephFS
The smb manager module lets cephadm deploy a clustered Samba service that exports CephFS directories to Windows and macOS clients as SMB shares, so users can reach data already stored in Ceph without a separate Windows file server. The service runs as containers managed by the orchestrator, and each share maps to a CephFS path. This fits organizations with established Windows workflows, such as mapped drives, group policy, roaming profiles or applications that expect SMB paths, and mixed fleets where macOS and Windows users need the same files. It also fits teams that already run Ceph and want one storage platform for file access rather than a second system to patch and back up. Before committing, confirm in the Ceph documentation for your release which SMB protocol versions, share options and authentication modes the module exposes, because the module's feature set has changed between releases.
CephFS with native kernel or FUSE clients, or with NFS exports through NFS-Ganesha, is usually the better fit when every client is a Linux host that can mount CephFS directly, when workloads are HPC or application-to-application rather than user-driven, or when the SMB gateway layer would add latency and an extra support surface without a clear user benefit. Teams should also weigh where authentication lives. Active Directory membership and local user accounts lead to different operating models, and the choice affects how permissions, password policy and offboarding are handled. Ask your identity team which model they will support, and test a representative share with real Windows and macOS clients, including file locking and large-file copies, before you size the gateway. Plan to verify SMB2 and SMB3 behavior against your own client builds rather than assuming parity with a dedicated NAS.
Active Directory membership or local users: which identity model fits
With Active Directory membership, the SMB service joins your domain and users authenticate with their existing domain accounts. The directory team keeps ownership of the user and group lifecycle, so joiners, movers and leavers are handled in the process your organization already runs. Access follows group membership: you grant share permissions to directory groups, and a change made in the directory changes what a user can reach without a separate change on the cluster.
- Lifecycle ownership: Account creation, password policy, disablement and group changes stay with the directory team, which usually already controls them under existing change management.
- Group-based access: Map each share to a small set of security groups. Naming conventions and nested group design decide how easy the access review will be later.
- Service accounts: Plan a dedicated account with only the rights needed to join the domain, and agree with the directory team how its credentials are stored and rotated.
- DNS and time: Clients and cluster nodes need resolvable names for the domain controllers and consistent time sources, because Kerberos authentication fails when clocks drift.
- Domain join: Confirm who approves the join, where the computer accounts are created and how a failed join is repaired.
Before committing, ask your directory team to confirm service account policy, DNS zones and time sources for every site that will mount the shares.
With local users, the accounts are defined on the Samba side and not in a directory. The storage team creates, changes and removes every account, sets every password and answers every question about who had access. That work recurs for as long as the cluster runs, and it grows with headcount, contractors and service users. The model is simpler to start but places the identity lifecycle on a team that usually does not run identity operations at scale.
- Credential lifecycle: Each password needs rotation, reset and expiry handling that your organization must document and perform, often outside the change process used for other systems.
- Offboarding: A departing user keeps access until someone removes the account from every cluster that holds it, so the offboarding checklist needs a named owner and a verification step.
- Audit trail: Records of who created, changed or used an account live with the storage team, which must produce evidence in a form your auditors will accept.
- Where it fits: Local users suit small isolated groups, lab environments, or a transitional period while a directory is being prepared for the file service.
- Scope creep: A temporary local account tends to outlive the project it was created for, so set a review date at the moment of creation.
Before you choose this model, ask who will perform each offboarding and review step, how often it happens and where the evidence is stored.
The identity options exposed by the smb manager module, the way Kerberos is configured and the way domain join is performed all depend on your Ceph release and on the cephadm service specification you deploy. Treat these as open questions until you have checked them against the documentation for your release, typically in the cephadm documentation, and tested them in a lab cluster that mirrors your domain layout.
- Release support: Confirm which identity models the smb module supports in your release, and whether one cluster can serve directory-joined and local-user shares at the same time.
- Protocol floor: Confirm that the service accepts only SMB2 and SMB3 connections, then check every client operating system in your fleet against that requirement before cutover.
- Kerberos handling: Confirm whether the module manages keytabs and the Kerberos realm settings, or whether your team must supply and rotate them.
- Domain join: Confirm the credentials used for the join, the directory location of the computer accounts and the procedure for re-joining after a failure.
- Per-share settings: Confirm which settings can differ from share to share, such as access groups and permissions, and which apply to the whole cluster.
Record each answer with the release number and the test result, because identity behavior changes between releases and your auditors will ask what you verified.
Deploying clustered Samba through cephadm, step by step
This sequence takes a Ceph cluster from a confirmed cephadm-managed release to CephFS-backed SMB shares that Windows and macOS clients can reach with the access you planned. Each step ends with a check so you know the layer below is sound before you build on it.
Confirm the Ceph release and cephadm management
Start by checking which Ceph release runs your cluster and that cephadm manages it. The cephadm documentation states it was introduced in v15.2.0 (Octopus) and does not support older releases, so a cluster deployed another way needs to be brought under cephadm first. Confirm the running release against the Ceph releases page and choose a release that is still within its supported window for your rollout. Check that the orchestrator reports every host and daemon as managed before continuing. You are done when the cluster health is understood, every host is visible to cephadm, and the release is recorded in your change record.
Prepare CephFS and the subvolume layout
Create the CephFS file system that will back the shares, then define the subvolume groups and subvolumes that map to your departments or projects. Decide the directory tree before any user writes data, because moving data between subvolumes later is slower and riskier. Set quotas where you need size limits, and record which directories each share will expose. Confirm the metadata pool sits on enterprise-class SSDs, as the Ceph hardware recommendations advise for metadata, and that the storage hosts use a dedicated drive per OSD with bonded network links across two switches. You are done when the file system reports active, the subvolumes exist with the expected quotas, and a test mount from a Ceph client shows the expected layout.
Prepare the identity source
Decide whether the SMB service joins Active Directory or uses local users, and prepare the source you chose. For Active Directory, confirm the domain, the join account and the DNS records the cluster needs, and check that the cluster hosts can reach the domain controllers. For local users, create the accounts and document who owns each password and how it rotates. Create one test user in the identity source with the group membership you intend to grant. You are done when the test user can be resolved from a Ceph host and the join account or local account is recorded with its owner.
Deploy the clustered SMB service with cephadm
Deploy the SMB service through cephadm using the smb manager module, specifying the cluster identifier, the authentication mode and the placement of the service across hosts. Use the cephadm documentation for the current service specification syntax and confirm it against your release before applying it. Keep the placement on at least two hosts if you need failover between cluster members, and check the bonded links and firewall rules for the SMB ports on each host. You are done when cephadm reports the SMB daemons as running on every planned host and the cluster status shows them healthy.
Create shares mapped to CephFS paths
Create each SMB share and point it at the CephFS path it should expose, using the subvolume layout from the second step. Name shares for their business purpose, and keep the number of shares small enough that each one has a clear owner. Grant access to the directory groups you prepared in the identity step rather than to individual users where possible. Verify that the share resolves on the SMB service and that the underlying path matches the subvolume you intended. You are done when each share lists the expected path and group in the configuration, and no share exposes the root of the file system.
Set per-share options
Apply the per-share settings your design requires, such as read-only or read-write mode, browseability and the permissions model for each share. Confirm that the service only negotiates SMB2 and SMB3 protocol versions, and record the setting in your configuration so reviewers can see it. Document each option with its owner and the reason it was chosen, because options are easy to change later and hard to explain without notes. You are done when the effective configuration for every share matches your written design and the protocol settings are recorded.
Validate access from Windows and macOS clients
Test the finished setup with a test user from a Windows client and a macOS client. Confirm that each client authenticates, lists only the shares it should see, and can read and write where the design allows. Also confirm that read-only shares reject writes and that a user outside the granted group is refused. Repeat the test after a restart of one SMB daemon to confirm the failover path you planned works as expected. Record the results in your acceptance notes, and keep the test user list so you can repeat the checks after upgrades. You are done when every planned access case has a recorded pass or a documented exception.
Why SMB2 and SMB3 only changes client compatibility
Restricting the share service to SMB2 and SMB3 only means any client that can speak only SMB1 will fail to connect, and the failure often looks like a generic network or authentication error on the device rather than a protocol refusal. Windows versions and macOS releases that still need SMB1 for some workflows, older multifunction printers and scanners that push scans to a share, and line-of-business applications that open files through legacy APIs are the usual casualties. Before go-live, build an inventory that lists every client type, its operating system or firmware version, the account it authenticates with, and the share paths it touches. Ask each device vendor in writing which SMB dialects the device supports, because a device that advertises SMB2 in its manual may still fail on the signing or dialect combination your cluster negotiates.
Test with the clients the business actually uses, not with a single administrator workstation. Build a short test matrix that covers reads, writes, rename, lock and delete operations, scan-to-folder jobs, and the applications your staff open from shares every day. Run the tests from the same network segment and with the same identity source that production uses, and record the dialect each client negotiates. Confirm how the Samba version bundled with your Ceph release handles protocol negotiation, including the minimum and maximum dialects the server offers and whether any legacy option is available or disabled in that build. Check the current Ceph documentation and release notes for your version rather than relying on older blog posts, since these defaults change between releases.
When a legacy device must stay, treat it as an exception with a named owner, a documented risk, and an end date, rather than as a reason to re-enable SMB1 on the whole service. The usual options are to replace the device or its firmware, move the device's output to a separate isolated share or gateway host that your team controls, or route its traffic through a supported intermediate such as a scan-to-email path. Each option has its own cost, and the vendor, your security team and the business owner should agree on which one applies. Document the decision in your change records, restrict the device's network path and share permissions to the minimum needed, and schedule a review date so the exception does not become permanent.
Security controls for shares that hold user data
An SMB gateway on Ceph puts identity, permissions, transport, host management and recovery in one path, so a weak link in any of them exposes user files. The cards below name each control and what you must confirm before users connect.
Identity and authentication
Decide whether the share joins Active Directory or uses local users, and confirm the domain join account, service account rights and password policy before go-live. Confirm the join method for each share, because local users sit outside your directory's lockout, expiry and audit rules. Ask the partner which accounts the gateway uses to query the domain and whether those accounts are limited to the minimum read rights needed.
Share and file permissions
Share-level settings and file-level permissions are separate controls, and both must allow a user before access is granted. Map each share to a CephFS path with only the directories it needs, so a compromised share cannot reach the wider file system. Confirm who owns the mapping, how changes are reviewed, and how access is removed when a team member leaves.
Transport encryption
Confirm which SMB3 encryption options your clients and the gateway support, and require SMB2 and SMB3 only so legacy dialects stay off. Separately, enable msgr2 secure mode for traffic between Ceph daemons and the gateway hosts, since it encrypts post-authentication traffic with AES-GCM and adds integrity checks. If the admin plane uses the Dashboard, confirm the SSO method, either SAML 2.0 or OAuth2 through the Management Gateway and OAuth2 Proxy services.
Host access and patching
The cephadm orchestrator manages gateway containers, so anyone with orchestrator rights can change services and images. Restrict SSH access to cephadm hosts to named administrators with logged sessions. Confirm the patch cadence for container images, and confirm you will move only to releases still in maintenance, checking the Ceph releases page for end-of-life dates.
Auditing and recovery
Access logs from the gateway and the cluster are only useful if they reach a system your security team reviews, so confirm where they are shipped and how long they are kept. Pair CephFS snapshots and an off-cluster backup with the shares, and test a restore of a deleted user folder. Ask the partner to show how a ransomware-encrypted share would be rolled back, and who signs off that restore.
What Ceph SMB file shares cost to set up and run
What does the implementation cost depend on for Ceph SMB file shares?
The cost depends mostly on how much work sits outside the Ceph cluster itself. The main drivers are the scope of identity integration (Active Directory membership or local users), the number of shares and their per-share settings, how mature the existing Ceph and CephFS deployment is, the mix of Windows and macOS clients and their applications, and how much validation testing the business requires before cutover. A cluster that already runs cephadm and CephFS with documented access patterns usually means less discovery. A greenfield cluster or a directory with unclear group design adds design time. Ask the partner to break the quote into these drivers so you can see which ones you control.
What part of Ceph SMB file share work is one-time and what recurs?
One-time work covers the design of the share layout and identity model, deploying the clustered Samba service through cephadm, joining or configuring the directory, creating shares and their settings, client testing, and handover documentation. Recurring work covers patching the Ceph release line and the SMB service, applying backports and security fixes, monitoring share health and capacity, reviewing access as people change roles, and planning upgrades when a release approaches end of life. Ask whether the quote includes the first year of patching, whether upgrades are priced separately, and whether a support retainer covers after-hours response.
What does the work need from our own team?
Expect to supply three groups of people. Directory administrators provide service accounts, group structures, and the rights needed for domain membership and access policy. Storage administrators provide access to the Ceph cluster, decisions on the CephFS file system and subvolume layout, and a change window for the cephadm service changes. Network and client owners confirm routing and firewall rules between clients, domain controllers and the cluster, and they test Windows and macOS clients with real applications. Name a decision owner for share permissions, because most delays come from unresolved questions about who should see which folder.
How long does a Ceph SMB file share project take?
Timelines are best described in phases rather than fixed durations, and the written scope should set the exact dates. A typical sequence starts with discovery of the identity model, client mix and existing Ceph state. Next comes a design phase for shares, permissions and network paths, followed by a build phase in a non-production environment. A test phase covers Windows and macOS clients, permission checks and failover of the clustered service. The final phase covers cutover, handover and documentation. Identity decisions and client testing usually set the pace more than the cephadm deployment itself, so ask for the phase plan with named owners and entry criteria for each phase.
Can our team set up Ceph SMB file shares without a partner?
Yes, if your team already runs cephadm and CephFS and has someone comfortable with Active Directory and Samba administration. The smb manager module and cephadm handle the clustered service, but the decisions still need to be made: domain or local authentication, SMB2 and SMB3 only settings, per-share permissions, and how Windows and macOS clients behave with your applications. Teams without recent SMB or directory experience often underestimate the client testing and the troubleshooting of permission mismatches. A partner can build the design and test plan, or run the work with your staff so knowledge transfers. Check the current Ceph release notes and documentation before you start, because module behavior changes between releases.
What should we ask for in a written quote for this work?
Ask for a written scope that lists the identity model, the number of shares and their per-share settings, the Ceph and CephFS state assumed at the start, and the client types in scope. Require the quote to state which Ceph release line it targets and how patching and upgrades are handled after handover. Ask what testing is included, which clients and applications are covered, and what the customer must provide, with named roles. Confirm the deliverables, including configuration records, runbooks and a handover session. Finally, ask which items are fixed scope and which are billed as changes, and how change requests are approved. DeployOpen agrees scope, deliverables and timelines in writing before work starts, and any quote follows from that written scope.
What risks should the quote address before cutover to SMB shares?
The main risks are permission drift between Active Directory groups and CephFS paths, clients that depend on SMB features not enabled in your configuration, and an unclear rollback plan if clients fail after cutover. Also check that the clustered Samba service has tested failover behavior, that monitoring covers the SMB service as well as the Ceph cluster, and that the team knows how to add shares later. Ask the partner to show how they will test each risk and who signs off on the cutover criteria.
What to confirm in your environment before go-live
Several parts of a clustered Samba deployment on CephFS depend on the exact Ceph release, client mix and hardware in your environment. The cards below list the items to verify before go-live, so that support dates, feature availability, client behavior, limits and performance are confirmed against your own setup rather than inferred from general documentation.
Release and support window
Confirm which Ceph release you will run and when its support ends. The Ceph releases page lists Squid with an estimated end of life of October 31, 2026, and Tentacle with an estimated end of life of June 1, 2027. A share service that goes live on Squid will need an upgrade plan well before that date, and the upgrade will also change which smb manager features are available. Ask for the current status of both releases at the time of your decision.
Smb module features per release
Do not assume that every smb manager option in the documentation exists in your release. Check which settings for clustering, domain membership, per-share options and SMB protocol versions your target release supports, and confirm the behavior of any feature you plan to rely on in a test cluster built from the same release. Write the confirmed list into the design record so that later upgrades are checked against it.
Client OS and protocol behavior
Windows and macOS clients differ in how they negotiate SMB2 and SMB3, sign and encrypt traffic, and handle oplocks and durable handles. Build a test matrix with the exact client builds your users run, including older releases still in use, and record which protocol version each one negotiates. Confirm the behavior of applications that rely on file locking, such as databases or CAD tools, because a mismatch often appears only under load.
CephFS limits for large trees
Large file trees and high metadata load place demands on CephFS that are separate from raw capacity. Confirm the number of files and directories you expect in each share, the rate of metadata operations from your largest users, and how many active and standby metadata servers you have. Test directory listing, large copies and antivirus scans against a realistic copy of the data, because these operations stress metadata most and show limits first.
Identity integration prerequisites
Active Directory membership depends on working DNS, time synchronization, a reachable domain controller set and an account with the rights the join process needs. Confirm these before the cluster is designed, because a membership problem found after go-live blocks access for every user of the share. Decide whether local users are acceptable for any workload, and document who owns the directory account used for joins and how its password rotates.
Performance on your hardware
The Ceph hardware recommendations say that no two clusters are alike and advise benchmarking before buying. Measure SMB throughput, latency and metadata performance on the actual drives, network links and CPU that you will run, using your real share settings and client count. Compare results against the performance targets agreed with the business owners, and repeat the tests after any change to network, media or the number of Samba gateway nodes.
How DeployOpen scopes, delivers and supports Ceph SMB file shares
DeployOpen plans, implements, documents and supports self-hosted open-source platforms inside your own infrastructure, so the Ceph SMB file share service runs in your cloud accounts, data centers or air-gapped networks. Engagements are fixed-scope, with scope, deliverables and timelines agreed in writing before work starts.
How we scope
- We confirm which Ceph release line, cephadm deployment and CephFS file system the SMB service will use.
- We record whether clients join Active Directory or use local users, and which domain and identity settings apply.
- We list each share, its clients, permissions and per-share settings, and agree the scope in writing before work starts.
How we build
- We deploy the clustered Samba service through cephadm, placing gateway daemons on the hosts you approve.
- We configure SMB2 and SMB3 only, then test connections from the Windows and macOS client versions you run.
- We validate share permissions, quotas and snapshot behavior against the access model agreed during scoping.
How we hand over
- We document the deployed service specification, share definitions, identity configuration and the client connection steps.
- We provide runbooks for adding shares, rotating join credentials and checking the health of the SMB daemons.
- We walk your administrators through the test results and open items so your team can operate the service independently.
How we support
- Ongoing support, upgrades and continuous testing are available as a retainer, covering the SMB service and its CephFS dependencies.
- We plan Ceph upgrades with the SMB service in mind, and confirm compatibility before any release change is applied.
- We ask you to confirm each support request, change window and rollback plan in writing before we act on your cluster.
