What’s New in Samba 4

Samba 4


In December 2012, the open source world received the first, and very long awaited, release of the Samba 4.x series.

Samba 4 has been under development for 10 years. In that same time, the Samba 3.x series also has seen numerous releases and advancements. This parallel development has led to some confusion over the nature of Samba 4; and, some distributions release both samba3 and samba4 packages that can be installed in parallel, with varying degrees of success.

Samba 4.x is a full replacement and upgrade to Samba 3. Undoubtedly, it will be used in parallel with existing Samba 3.x installations for some time, but not because of any deficiency in Samba 4. In almost all cases, Samba 4 can be a drop-in replacement for maintained Samba 3.x versions and will continue to function and provide the same services. Samba 4 is not the Samba Active Directory Domain Controller; rather, it is a new version of Samba that provides new and improved services. Therefore, I will refer to the current Samba 4.x release throughout this article simply as “Samba.” Version numbers will only indicate a version of Samba other than the current release.

Some of this version confusion arises from the long development time required to bring out the new release. Over the years, various directions were taken and emphases made in the project, even including rumors of a potential fork. However, the project settled successfully on a direction and a method for integrating divergent approaches to the many technical problems that needed to be resolved.

In understanding the current structure of the software and the direction the project has taken, it is vital to reference only current material. The use of older documentation or mail list archives, especially those that reference Samba4 “test” and “alpha” releases, is strongly discouraged. Old mail messages and blog posts will mislead you. Configuration directives and command syntaxes have changed significantly during the evolution of the release, so you should expect old documentation to be wrong.

The ability to participate fully in an Active Directory (AD) domain is the elephant in the room and is immediately what many people want to talk about regarding the new Samba; however, AD integration is not the only important enhancement the latest Samba brings to the table. I’ll talk about AD functionality in a moment, but I’ll mention some other important changes first.

One important change regards the Samba project itself and the workflow used for Samba development. The Samba team’s new commit process requires that every commit be reviewed by two developers; once the commit is pushed, the entire test suite is run – on every commit. This process ensures a high quality of code and should catch almost all regressions before they make it into a release. Nearly all commits are also tracked in relation to Bugzilla entries that include regression tests.

First Glance

After installing Samba, the administrator will see a few changes. For traditional domain members, such as file servers, the expected smbd, nmbd, and winbind binaries are present and should continue to be used for those applications.

For servers providing domain control services, Samba runs as a single samba binary. Because samba does not fully support being a domain member, the appropriate daemons, depending on the server’s role, must be started. A new samba-tool is the primary means for controlling a Samba server providing domain services. The syntax is very similar to that used by the net command.

The traditional trivial database (TDB) tools, as well as smbcacls, smbclient, rpclient, and other binaries, are still provided as expected, but installing Samba 4.x and Samba 3.x in parallel on a single host can be perilous, as can building Samba yourself on a host that already has Samba 3 installed. If you do a parallel install, be sure to watch your PATH to ensure you are using the intended versions of the tools.

The most basic use of Samba is simply as a file server, in which Samba 4 excels. The internals of the file server are now highly asynchronous, providing higher throughput and improved utilization of server resources. Another file server-related performance enhancement is support for the SMB2.1 and SMB3 protocols. These higher level SMB versions are supported in increasing degrees on Microsoft Vista and greater clients. Higher levels of the SMB protocol provide encryption, symbolic link support, server-side copy, and high-availability features, such as multipath and failover. An SMB3 file server should outperform a lower SMB/CIFS-level file server.

Before moving on to Active Directory support, note that your server should be using a modern filesystem that has good support for extended attributes. If you are using an ext3 or ext4 filesystem on Linux, you should ensure that the filesystem is mounted with the user_xattr,acl,barrier=1 option. If an ext3/4 filesystem is mounted without barrier=1, the TDB databases used by Samba cannot be guaranteed to be consistent in the case of a system crash.

A broken TDB database can mean a corrupted Active Directory domain. If you are stranded on a system without a modern filesystem, the Samba wiki has information on a workaround, but upgrading the host is the preferable option.

Active Directory

Out of the box, Active Directory support works. Creating an Active Directory domain can be performed in a matter of seconds with the use of samba-tool. This interactive way to provision a domain will prompt you for your DNS zone, realm name, and preferred DNS mode (Listing 1).

Listing 1: Creating a New Active Directory

sudo ./bin/samba-tool domain provision
 Domain [EXAMPLE]:
 Server Role (dc, member, standalone) [dc]:
 DNS forwarder IP address (write 'none' to disable forwarding) []:
Administrator password:
Retype password:
Looking up IPv4 addresses
Fixing provision GUIDs
A Kerberos configuration suitable for Samba 4 has been generated at /opt/s4/private/krb5.conf
Once the above files are installed, your Samba4 server will be ready to use
Server Role:           active directory domain controller
Hostname:              workstation
NetBIOS Domain:        EXAMPLE
DNS Domain:            EXAMPLE.COM
DOMAIN SID:            S-1-5-21-1405516098-4140136852-3456372168

Now when you start samba, you have working Kerberos, DNS, LDAP, and Active Directory.

Although this process seems simple, the reality is that Active Directory support is as complicated as Active Directory itself. Before creating a new Samba-powered Active Directory domain, the administrator really needs to learn the basics of Active Directory – a topic far beyond the scope of this article – and integration of the underlying Unix-like operating system with Active Directory domain servers provides yet more complexity. Most importantly, administrators need to understand the following:

  • An Active Directory Domain is a DNS domain. The security domain and DNS are inextricably linked in a way that was not true with Windows NT 4.0 (NT4) domains. Changing to or creating an Active Directory domain almost certainly means the architecture of your existing DNS changes.
  • An Active Directory domain is a Kerberos domain. One requirement of Kerberos is accurate clock synchronization. Differences between servers or workstations of more that a few minutes from the clock of a domain controller will render services unavailable from that server or to that workstation. For servers, this also means that working Kerberos libraries and utilities must be available and properly configured. The most common problem with Kerberos versions is that Active Directory domain controllers can require encryption hashes that might not be available with older Kerberos clients.
  • Active Directory is an LDAP directory service with its own schema and security model.

Active Directory is Active Directory, regardless of whether you are using a Samba domain controller (DC), Windows Server DC, or a mixture of both. Questions on the Samba mail list regarding the use of Samba 4 are frequently just Active Directory questions. You can break a Samba AD domain in all the same ways you can break any AD domain. The Samba wiki provides very good step-by-step instructions on creating an Active Directory domain controller; you should primarily use that as your documentation. For the remainder of this article, I will focus on some of the various gotchas and information not made obvious on the wiki.

AD Integration

To provide full Active Directory integration, Samba itself must integrate closely with DNS, provide Kerberos domain controller services, and provide an LDAP directory service consistent with that expected by an Active Directory client (Figure 1).

Figure 1: Active Directory is a tightly integrated collection of services.

With previous NT4 domain support, Samba was able to “outsource” many of these functions to existing codebases that provided these services, such as BIND, OpenLDAP, and MIT or Heimdal Kerberos. With the exception of BIND for DNS, the ability to utilize third-party codebases in that role is gone.

A common practice with Samba NT4 domains was to use the ldapsam back end to host the domain’s security account manager (SAM) in an OpenLDAP data source adapter (DSA). That ability is gone. The LDAP service used in Samba is now Samba’s LDAP service. Sites utilizing OpenLDAP to migrate to Active Directory must migrate at least the SAM to Samba’s built-in LDAP server. The same is true if the site uses a standalone MIT or Heimdal key distribution center (KDC) – the KDC function must be migrated to the Samba host. This is no different than if the Active Directory domain controller were a Microsoft Windows server.

It would seem that Samba taking over all these functions is very much contrary to the concept of an open stack or support for standards; it is, and the project acknowledges that. Loss of the ability to use a third-party DSA such as OpenLDAP is regrettable, but providing a reliable and consistent domain model forged of disparate components proved too difficult.

One of the primary goals of this Samba release is to work out of the box, which means Samba must take over all these roles.

The primary advantage of an Active Directory domain is that all the components (e.g., DNS, LDAP, KDC) are integrated and can be scaled up over multiple domain controllers. With the penalty of pushing out the transitional solutions to those network services, Samba now provides those same advantages: tight integration and an agreed-upon schema.

A Samba AD domain controller can peer with other Samba AD domain controllers or with other Windows AD domain controllers. You can bring up a Samba server and promote it to a DC in your existing domain. These domain controllers will replicate the domain information, providing the same level of failover that an all-Windows AD DC domain would provide … or almost. As of v4.0.3, a few small problems have been encountered:

  1. A Samba AD domain controller does not replicate completely when paired with a Windows AD read-only domain controller (RODC).
  2. DNS information does not replicate reliably between domain controllers when using Samba’s built-in DNS server.
  3. The sysvol volume, which stores the GPO policies, does not replicate automatically.
  4. Privilege delegation and ACLs with LDAP objects did experience difficulties early on, but these issues were resolved in version 4.0.3.
  5. In my experience on a Samba AD DC, a script specified using the wins hook parameter, which should work in the same manner as on previous versions, does not appear to be invoked. [Bug 9651]
  6. Windows clients complain that they cannot disable offline caching on the profile share [Bug 7810]. (This is a non-critical message and does not affect operation.)

Issues 2 and 3 are the most significant and need to be addressed when utilizing a Samba AD domain controller.

Migrating to Samba

If you already have an Active Directory domain using Microsoft Windows servers and they manage your DNS, then the entire DNS issue can be side-stepped unless your intention is to migrate entirely to Samba. Alternatively, you can use BIND DLZ integration, which allows the Samba DC to maintain a DNS domain in BIND and gives the administrator the same ability to perform BIND-based update notification, zone transfer, and so on. The downside of BIND DLZ integration is that it adds another component to the stack, albeit one with which most administrators are very familiar.

When creating or migrating an existing NT4 domain to Samba, the built-in DNS server will be used by default. This simple DNS server is adequate for small sites, but it lacks much of the power and flexibility of BIND. To change the default back end to BIND when creating or migrating a domain, specify the --dns-backend=BIND9_DLZ option.

If a domain is initially provisioned with the internal DNS server, it subsequently can be migrated to BIND DLZ using the samba_upgradedns script; then, you just configure the BIND DLZ module.

With either DNS back end, the DNS domain of the Active Directory domain can be managed with the Windows domain management tools. In fact, this is the case with all of Samba’s features: You can manage the Samba server in the same manner you would manage a Microsoft Windows server via the Microsoft Management Console (MMC). Administrators familiar with using MMC will be unaware that they are managing a non-Microsoft platform.

If you migrate or provision your domain initially using the built-in DNS server – which is the simplest route – and then decide you need the additional flexibility provided by BIND integration, you can migrate the domain’s DNS using the provided samba_upgradedns script.

The major caveat of using BIND integration is that you need an up-to-date version of BIND. Although it is possible to get BIND 9.7.x to function, a version of 9.8.x or greater is strongly recommended. The function of secure updates and support for Kerberos have been evolving parts of BIND rapidly; being current can help you avoid headaches.

A recommended approach to DNS is to use a separate domain or sub-domain for the DNS zone of Active Directory. This eases migration when adding Active Directory to an existing network. If your current domain is example.com and your DNS servers resolve the names in that domain, you can create your new AD domain as ad.example.com. Next, you can configure your existing DNS servers to delegate resolution of that domain to your DC DNS servers.

On a Samba DC that is a DNS server, you can add the following:

    dns forwarder =

to the global section of the smb.conf file. If is your existing DNS server, the DC will forward all requests for zones other than its own to your existing DNS server. With the delegation on your existing DNS and the forward in the AD DNS, you will be able to provide a seamless transition as you roll out AD. If you start with the Samba-provided internal DNS, once everything is working, you can then consider migrating to the BIND DLZ back-end DNS. It is much easier to isolate issues if you roll out the domain step by step.

The issue of sysvol replication is more tedious. In the sysvol replication are the files that represent the Group Policy objects of the domain, as well as any login scripts. This shared volume must be present on all the DCs accessible to clients.

When changes are made to login scripts or GPOs, these files must be pushed out from the origin DC to all other DCs. On a Samba DC, this replication must be performed using tools like rsync and csync. The Samba mail list archive has a script for this purpose. The ACLs applied to the files on the sysvol volume are critical to the correct operation of clients. If manually, or by attempted replication, you end up with incorrect ACLs, samba-tool can be used to reset them to the expected values:

samba-tool ntacl sysvolreset

This command also should be performed when Samba is upgraded from one release to another. Fortunately, replication of the sysvol volume does not need to occur in real time. With tools such as rsync or csync, this process can be performed efficiently as a scheduled job.

Once the domain is provisioned and DNS and Kerberos have been tested, you can begin joining workstations to your domain. If you migrated to the Active Directory domain from a Samba NT domain, the workstations should retain their domain membership; they will switch to using Active Directory automatically.

Upgrading from NT4 to AD

Upgrading is almost as seamless as provisioning a new domain. The most important thing to know about an upgrade to Active Directory is that it is one-way. Once a workstation joined to an NT domain sees an AD domain with the same SID or NetBIOS name, it switches into Active Directory mode, and it will never go back to using the NT-mode DC.

Therefore, you should test the upgrade of your domain carefully, isolated from your production network, or you could end up committed to a test instance of your DC. Microsoft’s Active-Directory-enabled clients naturally work this way and is not specific to using a Samba AD DC.

To perform the upgrade, you can use samba-tool domain upgrade support. The tool must have access to a copy of the smb.conf file used by one of your DCs, as well as copies of the TDB files. These files can be transferred to your testing server, for example, via rsync or scp. If your NT4 DC is using ldapsam, the testing host must also have access to the DSA as configured in the smb.conf file. The migration script only reads from the ldapsam, so nothing in the existing NT4 SAM will be modified:

samba-tool domain classicupgrade --dbdir=/tmp/x --use-xattrs=yes \
                                 --realm=EXAMPLE /tmp/x/smb.conf

The dbdir option specifies the location of the NT4 domain controller’s TDB files, and realm specifies the DNS zone for the new AD domain and the location of a copy of the NT4 DC’s smb.conf file.

Provided your NT4 SAM is coherent, the migration script should migrate all your users, groups, and machine accounts. When migrating from an ldapsam, especially, you likely will run into some inconsistencies (e.g., duplicate usernames, SIDs, or missing groups) that will cause the migration to fail; fortunately, the error messages tend to be self-explanatory. If you are migrating from an ldapsam that has existed for a long time, it can become apparent why Samba needs to manage all services itself: The lazy NT4 DC will continue to operate in spite of numerous inconsistencies. Assume that any errors are legitimate problems with your NT4 SAM, address the issues there, and then re-attempt migration until it completes.

One real advantage Samba lends to sites still using NT4 domains is that it provides an upgrade path to Active Directory. All the migration tools I am aware of for migrating an NT4 domain to an Active Directory domain are no longer available for current Windows Server versions, Current Windows clients will not interoperate with an NT4-style domain without some registry hacking and, even then, not completely. Samba can at least provide a path for such sites to migrate to AD by adding Windows DCs and demoting the Samba DC, leaving an all-Windows AD domain, although one hopes the administrators of such sites will recognize the benefits and flexibility of the Samba DC and choose to keep it around.

Now that your Samba AD is up and running, you can fire up MMC on a Windows client and start managing your domain (Figure 2).

Figure 2: Editing a DNS on a Samba DC via MMC.

Alternatively, many common operations, such as adding a user or DNS entries, can be accomplished with samba-tool (Listing 2).

Listing 2: Adding a User with samba-tool

samba-tool user add fbaggins
   --random-password --use-username-as-cn
   --surname="Baggins" --given-name="Frodo"
   --initials=S --mail-address=fbaggins@example.com
   --company="Hobbiton Inc." --script-path=shire.bat
   --job-title="Goes there and back again"

Once up and running, Samba stores your domain information in a set of interlined LDB files. The database (SAM) content can be modified via samba-tool, via LDAP, or with Samba’s ldbsearch, ldbmodify, ldbdel, and other corresponding commands. Once your domain is up, you might want to add additional information about users, such as phone numbers. You can generate LDIF files to import using LDAP or LDB tools or directly via LDAP using any Python bindings that support the Kerberos Generic Security Services API (GSSAPI).

Winbind and other services on Samba 3 or Samba 4 domain member servers (not DCs) work just as they did previously. Just remember to run smbd, nmbd, and windbind – on member servers, not the unified samba daemon.


After you have domain workstations and servers joined to the domain, you will notice that clocks drift. Occasionally, you will lose access because of Kerberos’s time sync requirements, so you must verify that Samba and NTP configurations correspond and that both have adequate access to the specified directory:

# Check the configuration of Samba
$ testparm --parameter-name="ntp signd socket directory"
# Check configuration of NTP
$ cat /etc/ntp.conf
ntpsigndsocket /opt/s4/lib/ntp/
restrict default mssntp
# Change permissions of target folder
$ chown ntp /opt/s4/lib/ntp

Microsoft domain clients will not synchronize to your standard NTP time service because they require one that has been signed by a DC they trust; therefore, you must install a version of the NTP server on your DCs that supports packet signing (i.e., any version of ntpd after v4.2.6, provided it was built with the --enable-ntp-signd flag). The version of NTP that shipped with RHEL6/CentOS6 and Ubuntu 11.04 is too old and does not support signing.

Provided you have an adequate version of NTP installed, you now need to configure Samba and NTP to communicate with each other. This occurs via a filesystem socket. Samba will create a socket to which NTP can submit clock responses to be signed. NTP will then reply to the client with those signed responses.

The default location of the socket created by Samba is <prefix>/var/ntp/, where <prefix> is the installation prefix of your Samba build or package. Alternatively, you can specify the location using the ntp signd socket directory directive in the global section of the smb.conf file. In the ntp.conf file, ntpsigndsocket is used to indicate the same directory.

The very confusing aspect of this setup, in both Samba and NTP, is that these configuration directives do not indicate a file, they indicate a folder where a filesystem socket named socket is created and then expected to be found. When you restart samba, you should see a socket named socket in the directory you specified and Samba listening on that socket:

$ sudo ls -l /opt/s4/var/ntp/socket
srwxrwxrwx 1 root root 0 Feb 12 14:42 /opt/s4/var/ntp/socket
$ sudo fuser -u /opt/s4/var/ntp/socket
/opt/s4/var/ntp/socket: 1124(root)

The output from the fuser utility verifies that the automatically created socket is open by process 1124 (samba). On a Windows client, it is critical that the command

w32tm /resync /rediscover

completes successfully; you should see the message, The command completed successfully. If this command does not complete, time signing is not configured, and you are at risk of clock drift disabling parts of your domain.

With time synchronization, you now have a completely functional and stable Active Directory domain up and running – courtesy of GPL code.


Samba 4 does more than just provide improved networking services. Samba 4 integrates fully with Active Directory, and you can migrate an Active Directory domain to Samba 4 or use Samba 4 to provide a reliable upgrade path from NT4 to Active Directory.

Related content

  • Samba 4

    Samba 4 has been around for more than three years, but some users still shy from it. If you are still sitting on the fence, this tour through some of the new features and capabilities might help you decide whether it is finally time to upgrade.

  • Samba 4

    Since the release of the final version, Samba 4 has become increasingly significant in IT practice; now it has found its way into Jessie, the next Debian release. We take a look at the new features.

  • Samba 4

    A technical preview version of Samba 4 became available at the end of January. We took a look at what’s coming in the next version of the Samba file and print service suite.

  • Books
  • Samba 4.0 Released

    The Samba team announces Samba 4.0 – the latest version of the free software file, print, and authentication server suite designed for compatibility with Windows networks.

comments powered by Disqus

Issue 195/2017

Buy this issue as a PDF

Digital Issue: Price $9.99
(incl. VAT)