Domain Controller

Information related to the TurnKey Linux Domain Controller appliance

Notes for TurnKey Domain-Controller v14.x/v15.x

As of v14.0 TurnKey's domain-controller (DC) appliance uses Samba4 to provide a Microsoft Active Directory domain.

However, it should be noted that the current appliance is a fairly bare-bones AD server. It is provided as a "better starting point" for those that wish to use Samba4 as an AD DC but is far from being feature complete.

Steps that need to be taken when first launched:

  • Set a static IP on your domain-controller
    • easiest via confconsole
    • if not using the DHCP assigned IP please re-run the domain provision inithook - copy/paste the following into commandline:
  • (optional) Create the DNS reverse lookup zone and PTR records.
    example details:
    hostname: dc1
    domain/realm: domain.lan
    ip address:
    # Substitute $ADMIN_PASS for the administrator password 
    # the 1.168.192 is from the "network IP" (backwards) i.e. this example is for 192.168.1.x
    samba-tool dns zonecreate dc1 \
        --username=administrator --password="$ADMIN_PASS"
    # as above but 50 is from the IP i.e.
    samba-tool dns add dom-controller PTR dc1.domain.lan \
        --username=administrator --password="$ADMIN_PASS"
  • (optional) Adjust DNS forwarder in /etc/samba/smb.conf
    • currently hardcoded to Google DNS (
      edit /etc/samba/smb.conf and adjust the field that is currently "dns forwarder ="

For how to join a Windows Desktop to a AD domain see the Samba Wiki:

Features to be added in the future:

  • Option to provision a fileserver AD member server
    • not yet sure on how this will be implemented...
    • see "Best Practice" notes below
  • Support for Roaming Profiles(?)
    • will require AD member fileserver
  • Configuration of PTR records for domain controller
    • strictly speaking they're not required but would be good
  • documentation on including a DHCP server


Currently TKLBAM won't properly backup a domain. If you wish to use TKLBAM hooks to script it there is info on the Samba Wiki:

Note: if you have multiple AD DCs then rather than restore from backup; just rejoin the server to the domain. Restoring a backup to a server that is already a member of a domain will likely cause DB corruption and/or multiple identical domain objects.

General best practice recommendations

General DC Notes

In production it is recommended that you have a minimum of 2 domain controllers in an AD domain.

File storage/fileserver

Samba advise against using a (Samba4) domain controller as a fileserver as well. Instead it is recommended that you create a dedicated fileserver (as a domain member server). The current TurnKey fileserver appliance is NOT useful for this with it's default config. See notes on the Samba wiki on setting up a member server:

Please note, that the TurnKey Fileserver appliance includes the same version of Sambas as the DC appliance, but is configured as "stand-alone" by default. You are welcome to reconfigure it to join an existing domain and that should work fine. Please post on the forums if you do that and would like to share your experience and/or need a hand.

Further domain configuration e.g. DNS

Samba recommend using Microsoft tools (from within a Windows workstation) to do additional AD (Samba4) configuration.


For production usage it is recommended to use a domain name that you have registered with a domain registrar as the realm. If you plan to use a domain that you already own (e.g. "") as your realm then add a unique subdomain to avoid potential problems (e.g. "")

Do not use ".local" realms/tlds as they can conflict with Apple (bonjour) and zeroconf type networked devices.

See also MS documentation:


Brian Candler's picture

Note that this appliance gives you samba 3.6.6, not samba 4. So if you're looking for a full Active Directory replacement, this is not it.

Jeremy Davis's picture

As noted in the Quick start guide...

I would anticipate that the next major revision of TurnKey appliances (v14.x) with Samba (i.e. Domain Controller and Fileserver) will utilise Samba4, but we'll have to wait and see. They will be some time away (at least 6 months, possibly longer)...

If you'd like to help develop a Samba4 appliance then that would be awesome! Have a look at TKLDev and go from there. If you have any questions then please feel free to post in the forums.

Jason's picture

Any update on a samba 4 version of this supporting AD? Doesn't seem like windows 10 machines will join the domain.

hopefully waiting's picture

would be great, if there is some update in the near future. waiting for news...

Russell Alphey's picture

I couldn't get my Win 7 64 machines to connect to my v13 PDC, so I grabbed v14.1...and nothing can connect to it. I don't think Samba is even starting properly, configuration tests show that th edomain doesn't even appear to be there.


Lloyd Carroll's picture

+1 on that. Nothing can join domain and the error I get when trying to start samba ad service is something like "has the domain been provisioned?"


Lloyd Carroll's picture

Ok, got it to work.

1. Once installed, login to the web interface.

2. Goto System->Software Packages

3. Select Package from APT and click Search APT.

4. Search for Winbind

5. Install and reboot.


You will then see Samba services running and domain will be available.

Lloyd Carroll's picture

Sorry, I forgot to mention. After you reboot, you have to run the domain py script


Jeremy Davis's picture

Thanks very much for posting your fix. It sounds like we need to tweak and rebuild it. I'm not sure but I'm suspecting that something within a security update has broken something (as noted elsewhere I tested it myself previously and all was well).

I know that Debian upgraded the version of Samba in the repos (to v4.2.x) since our last release. Generally they avoid that (as it often breaks things) but they had no real alternative as upstream were no longer supporting the previous version (v4.1.x) and the security patches were massive (apparently over 200 files needed patching) so would have been prone to error anyway.

The only thing that surprises me is that installing WinBind fixes it. WinBind should not be required for a Samba4 DC. In fact AFAIK it only applies to NT domains and non-domain networked Win machines. Although in fairness I don't use Windows much any more (only for testing TurnKey Samba based appliances).

The other possibilities that come to mind are that installing WinBind resolves some other issue when it installs/updates dependencies? Or perhaps it works around an issue introduced by a recent Windows update.

Regardless, thanks for providing the workaround. I have noted it on our Issue Tracker.

dfgas's picture

I can't join the domain at all. it shows a loging and password window but after 30s of waiting to log into the domain it will say the follow error occurred to join "DOMAIN" The spicified domain either does not exist or could not be reached.

dfgas's picture

How do you add a user?

dfgas's picture

got this working now and managed to get roaming profiles to work to... Thing I notice is that each user is not getting a UID without actually creating their UID and same with groups. The other big thing was yes you create the profile share in samba but you need to add the share to AD. 

Micah Roth's picture

Hey, hitting this right off the bat. Running tkl-dc instance on Proxmox 4.4 from tkl-domain-controller LXC template.  What am I doing wrong?
root@tkl-dc1 ~# samba-tool dns zonecreate dc1 --username=administrator --password=<<PASSWORD>>
ERROR(runtime): uncaught exception - (-1073741772, 'The object name is not found.')
  File "/usr/lib/python2.7/dist-packages/samba/netcmd/", line 175, in _run
    return*args, **kwargs)
  File "/usr/lib/python2.7/dist-packages/samba/netcmd/", line 850, in run
    dns_conn = dns_connect(server, self.lp, self.creds)
  File "/usr/lib/python2.7/dist-packages/samba/netcmd/", line 40, in dns_connect
    dns_conn = dnsserver.dnsserver(binding_str, lp, creds)
root@tkl-dc1 ~#
Jeremy Davis's picture

I must say, that's a new one to me. We haven;t had any other reports about that one, so I have no idea really.

The only thing I could suggest is that perhaps there is something funky going on because it's running in LXC?

In theory, it should be possible to get the Domain Controller appliance working on LXC (at least as far as I know). However, I do recall years ago (when I used Windows) that there were some issues running Samba on OpenVZ (the precursor to LXC, was what provided containers back in PVEv2.x, and 3.x too I think?). I ended up just installing to a VM and had no further issues, so never bothered going back and trying to troubleshoot the specific issue.

So if you're determined to get it running, I suggest that you get your google on. Whilst there may be some PVE and/or TurnKey idiosyncrasies, essentially they're both Debian. So you should be able to find some info via google.

Regardless, I suggest that you try the same thing in a VM first (even if you want to troubleshoot it running in LXC). That way, you'll be able to confirm that it's an LXC/Samba issue, rather than wasting time to find out it was something else.

Please let us know how you go

Micah Roth's picture

got one step farther with vm, but still failed with an uncaught exception. any help welcome
root@dc1 ~# samba-tool dns zonecreate dc1 --username=administrator --password=!!!
Zone created successfully
root@dc1 ~# samba-tool dns add dom-controller PTR dc1.ndgm.lan --username=administrator --password=!!!
ERROR(runtime): uncaught exception - (-1073741772, 'The object name is not found.')
  File "/usr/lib/python2.7/dist-packages/samba/netcmd/", line 175, in _run
    return*args, **kwargs)
  File "/usr/lib/python2.7/dist-packages/samba/netcmd/", line 1062, in run
    dns_conn = dns_connect(server, self.lp, self.creds)
  File "/usr/lib/python2.7/dist-packages/samba/netcmd/", line 40, in dns_connect
    dns_conn = dnsserver.dnsserver(binding_str, lp, creds)
root@dc1 ~#
Carl Nesbitt's picture

Micah - I have the exact same error, were you ever able to figure this out?
Ernesto.A's picture

Hi, you can't make it as unprivileged container, you must make it "normal".
SilentDis's picture

I assume that an LDAP system is 'included' in this, and the AD stuff is provided by Samba on top of that?   I have a bunch of Linux and Windows clients and I'd like unity across both, but I'm unsure if that's possible.
Jeremy Davis's picture

TBH, I don't know a lot about it, but AFAIK LDAP is only supported with the Samba "classic" (aka "Samba3" i.e. NT4 type) domain, not AD. Due to popular demand, our Domain Controller appliance provides a Samba4/AD domain which is not currently supported by LDAP.

My reading suggests that it may be possible, but with a fair bit of work. Here are some links from the Samba wiki which may help:

If you manage to get it working please feel free to post back with your solution as I'm sure it would be useful for others. Also if you think it could be integrated back into TurnKey in a useful way, please include as much detail of that and we'll see what we can do for the v15.1 release (v15.0 is really close so unlikely to be included for the next release).

Rubbaht0e's picture

Is it possible to use this appliance as a secondary DC in a windows environment to have the clients authenticate to? I would like to mix technologies to have layered security. 
Jeremy Davis's picture

The more recent versions support being added to an existing domain, so that should work fine. If you have any troubles, please start a new thread in the forums.

DBK's picture

Failed to start Samba servers : service smbd start ; service nmbd start failed   Fresh install in virtual box.  How do I fix this?
Jeremy Davis's picture

So this should do the trick:

service samba restart

If you want the smbd/nmbd services, then IIRC they are still the services to use on our fileserver appliance...?!

n00b's picture

After reading the pages availabale on it, I'm not sure if the services provided include computer registration to the domain. Am I supposed to add the pc to the domain?

I know the DC runs logon scripts, and can authenticate users. Besides user authentication and scripts, what are the TKL Domain Controller's function? I'm tyring to wrap my head around it to use it as intended.

Thank you.