View source for Setting up Samba as a Domain Member

= Introduction =

A Samba domain member is a Linux machine joined to a domain that is running Samba and does not provide domain services, such as an NT4 primary domain controller (PDC) or Active Directory (AD) domain controller (DC).

On a Samba domain member, you can:

* Use domain users and groups in local ACLs on files and directories.
* Set up shares to act as a file server.
* Set up printing services to act as a print server.
* Configure PAM to enable domain users to log on locally or to authenticate to local installed services.

For details about setting up a Samba NT4 domain or Samba AD, see [[Domain_Control|Domain Control]].


{{Imbox
| type = important
| text = For versions of Samba earlier than 4.15.0, never use <code>samba-tool domain provision</code> to create a Unix domain member, it will not work, you must follow the procedure laid out on this page.
}}

{{Imbox
| type = important
| text = All AD Domain members must be in the same <code>DNS</code> domain and the Realm must be the <code>DNS</code> domain in uppercase. For example, the <code>DNS</code> domain could be <code>samdom.example.com</code> and the Realm would be <code>SAMDOM.EXAMPLE.COM</code>.
}}



= Preparing the Installation =

== General Preparation ==

* Verify that no Samba processes are running:
 # ps ax | egrep "samba|smbd|nmbd|winbindd"
: If the output lists any <code>samba</code>, <code>smbd</code>, <code>nmbd</code>, or <code>winbindd</code> processes, shut down the processes.

* If you previously run a Samba installation on this host:
:* Backup the existing <code>smb.conf</code> file. To list the path to the file, enter:

 # smbd -b | grep "CONFIGFILE"
    CONFIGFILE: /usr/local/samba/etc/samba/smb.conf

:* Remove all Samba database files, such as <code>*.tdb</code> and <code>*.ldb</code> files. To list the folders containing Samba databases:

 # smbd -b | egrep "LOCKDIR|STATEDIR|CACHEDIR|PRIVATE_DIR"
   LOCKDIR: /usr/local/samba/var/lock/
   STATEDIR: /usr/local/samba/var/locks/
   CACHEDIR: /usr/local/samba/var/cache/
   PRIVATE_DIR: /usr/local/samba/private/

: Starting with a clean environment helps you to prevent confusion, and no files from your previous Samba installation are mixed with your new domain member installation.



== Preparing a Domain Member to Join an Active Directory Domain ==

=== Configuring DNS ===

{{:Linux and Unix DNS Configuration}}





=== Configuring Kerberos ===

Samba supports Heimdal and MIT Kerberos back ends. To configure Kerberos on the domain member, set the following in your <code>/etc/krb5.conf</code> file:

 [libdefaults]
 	default_realm = SAMDOM.EXAMPLE.COM
 	dns_lookup_realm = false
 	dns_lookup_kdc = true

The previous example configures Kerberos for the <code>SAMDOM.EXAMPLE.COM</code> realm.

The Samba teams recommends to not set any further parameters in the <code>/etc/krb5.conf</code> file.

If your <code>/etc/krb5.conf</code> contains an <code>include</code> line it will not work, you '''Must''' remove this line.

On some Linux distributions that use MIT Kerberos, it is necessary to add these lines for proper ID mapping:

 [plugins]
        localauth = {
              module = winbind:/usr/lib64/samba/krb5/winbind_krb5_localauth.so
              enable_only = winbind
        }

These settings could also be necessary <code>/etc/security/pam_winbind.conf</code>:

 [global]
       krb5_auth = yes
       krb5_ccache_type = FILE

With distributions with crypto-policies, this command must be issued to update the system policy support for Active Directory:

<code>update-crypto-policies --set DEFAULT:AD-SUPPORT</code>





=== Configuring Time Synchronisation ===

Kerberos requires a synchronised time on all domain members. Thus it is recommended to set up an NTP client. For further details, see [[Time_Synchronisation#Configuring_Time_Synchronisation_on_a_Unix_Domain_Member|Configuring Time Synchronisation on a Unix Domain Member]].





=== Local Host Name Resolution ===

When you join the host to the domain, Samba tries to register the host name in the AD DNS zone. For this, the <code>net</code> utility must be able to resolve the host name using DNS or using a correct entry in the <code>/etc/hosts</code> file.

To verify that your host name resolves correctly, use the <code>getent hosts</code> command. For example:

 # getent hosts M1
 10.99.0.5      M1.samdom.example.com    M1

The host name and FQDN must not resolve to the <code>127.0.0.1</code> IP address or any other IP address other than the one used on the LAN interface of the domain member.

If no output is displayed or the host is resolved to the wrong IP address and you are not using dhcp, set the correct entry in the <code>/etc/hosts</code> file. For example:

 127.0.0.1      localhost
 10.99.0.5      M1.samdom.example.com    M1

If you are using dhcp, check that <code>/etc/hosts</code> only contains the '127.0.0.1' line shown above. If you continue to have problems, contact the sysadmin who controls your DHCP server.

if you need to add aliases to the machine hostname, add them to the end of the line that starts with the machines ipaddress, not the 127.0.0.1 line.




== Preparing a Domain Member to Join an NT4 Domain ==

For joining a host to an NT4 domain, no preparation is required.





= Installing Samba =

For details, see [[Installing_Samba|Installing Samba]].

{{Imbox
| type = note
| text = Install a maintained Samba version. For details, see [[Samba_Release_Planning|Samba Release Planning]].
}}





= Configuring Samba =



Samba can use various winbind idmap backends, The three main ones are:
* ad
* autorid
* rid


=== Choosing an idmap backend ===

It can appear to be a complex decision choosing which winbind idmap backend to use, hopefully reading this can point you to the one to use.


{{Imbox
| text = If you require users and groups to have the same IDs everywhere, or have different login shells and Unix home directory paths, then you need to use the winbind idmap 'ad' backend and add RFC2307 attributes to AD.
}}


{{Imbox
| text = If you use the 'ad' backend, the RFC2307 attributes (uidNumber, gidNumber, etc) are not added automatically when users or groups are created, you must add them manually.
}}


The ID numbers found on a Samba DC (numbers in the 3000000 range) are NOT rfc2307 attributes. They cannot and will not be used on Unix Domain Members, you can add uidNumber & gidNumber attributes to AD and use the winbind 'ad' backend on Unix Domain Members. If you do decide to add uidNumber & gidNumber attributes to AD, you do not need to use numbers in the 3000000 range and it would definitely be a good idea to use a different range.


{{Imbox
| text = If you only need users and groups to have Unix IDs, you can use the 'rid' or 'autorid' idmap winbind backend.
}}


The 'rid' or 'autorid' idmap winbind backends calculate the user and group IDs from the Windows RID. If you use the 'rid' idmap backend and the same [global] section of the smb.conf on every Unix domain member, you will get the same IDs. Using these idmap backends, you do not add anything to AD and any added RFC2307 attributes will be ignored. When using these backends you can set the 'template shell' and 'template homedir' parameters in the smb.conf global section and everyone will get the login shell and Unix home directory path you set. If you do not set 'template shell' or 'template homedir', the defaults, '/bin/false' and '/home/%D/%U' , will be used.


Once you Have decided which winbind idmap backend to use, you have to choose the ranges to use with 'idmap config' in smb.conf.

By default on a Unix domain member, there are multiple sources and types of users & groups:

* The local system users & groups: These will typically be from 0-999
* The local Unix users and groups: These typically start at 1000
* The (AD) domain users and groups 
* The default domain '*' used for the WellKnownSIDs and anything not in the 'AD' domain
* Trusted domains

As you can see from the above, if you are creating a new domain, you shouldn't set either the default domain '*' or the (AD) domain ranges to start at 999 or less, as they would interfere with the local system users & groups. You also should leave a space for any local Unix users & groups (for 'sudo' use etc.), so starting the 'idmap config' ranges at 3000 seems to be a good compromise.

Bearing the above information in mind, you could set the 'idmap config' ranges to the following:

:{| class="wikitable"
!Domain
!Range
|-
|<code>*</code>
|'''3000-7999'''
|-
|<code>DOMAIN</code>
|'''10000-999999'''
|}

You could also have any trusted domains starting at:

:{| class="wikitable"
!Domain
!Range
|-
|<code>TRUSTED</code>
|'''1000000-9999999'''
|}

If you set the default domain '*' range above the 'DOMAIN' domain range, the ranges will conflict if the domain grows to the point that the next ID would be the same as the default domain range start ID.

With the above suggested ranges, no range will overlap or interfere with another.

You may also have seen examples of the '*' range being used for everything, this should only be used with the 'autorid' idmap backend.

== Setting up a Basic <code>smb.conf</code> File ==


{{Imbox
| type = warning
| text = ID mapping back ends are not supported in the <code>smb.conf</code> file on a Samba Active Directory (AD) domain controller (DC).<br />Do not add any idmap config lines to a Samba Active Directory (AD) domain controller (DC) smb.conf<br />For details, see [[Updating_Samba#Updating_Samba#Failure_To_Access_Shares_on_Domain_Controllers_If_idmap_config_Parameters_Set_in_the_smb.conf_File|Failure to Access Shares on Domain Controllers If idmap config Parameters Set in the smb.conf File]].
}}


Before joining the domain, configure the domain member's <code>smb.conf</code> file:

* To locate the file, enter:

 # smbd  -b | grep CONFIGFILE
   CONFIGFILE: /etc/samba/smb.conf



The following table lists the most important idmap backends with links to their documentation, click the relevant <code>Documentation</code> link for how to setup each idmap backend:

:{| class="wikitable"
!Back End
!Documentation
!Man Page
|-
|<code>rid</code>
|'''[[Idmap_config_rid|idmap config rid]]'''
|<code>idmap_rid(8)</code>
|-
|<code>autorid</code>
|'''[[Idmap_config_autorid|idmap config autorid]]'''
|<code>idmap_autorid(8)</code>
|-
|<code>ad</code>
|'''[[Idmap_config_ad|idmap config ad]]'''
|<code>idmap_ad(8)</code>
|-
|<code>hash</code>
|'''<Do not use>'''
|<code>idmap_hash(8)</code>
|-
|<code>ldap</code>
|
|<code>idmap_ldap(8)</code>
|-
|<code>nss</code>
|
|<code>idmap_nss(8)</code>
|}

:{{Imbox
| type = important
| text = Add an additional ID mapping configuration for every trusted domain, unless you use the <code>autorid</code> idmap backend (where this is optional). The ID ranges of the default (<code>*</code>) domain and other domains configured in the <code>smb.conf</code> file must not overlap.
}}

{{Imbox
| type = note
| text = After selecting an idmap backend and configuring the <code>smb.conf</code> file, following the relevant wiki page for your chosen idmap backend, you should have a basic <code>smb.conf</code> file that will allow the computer to join the Active Directory domain. There are a multitude of other parameters that you can add to the <code>smb.conf</code> file, some will be relevant to your domain, others will not, please read the <code>smb.conf</code> manpage for your Samba version to find the available parameters. If in doubt, post a question to the samba mailing list.
}}





== Mapping the Domain Administrator Account to the Local <code>root</code> User ==

Samba enables you to map domain accounts to a local account. Use this feature to execute file operations on the domain member's file system as a different user than the account that requested the operation on the client.


{{Imbox
| type = note
| text = There is no real reason to map the domain Administrator account to the local <code>root</code> account. You can use a member of the <code>Domain Admins</code> group wherever you would use the domain Administrator on Unix instead.
}}



:{{Imbox
| type = important
| text = Never map the domain Administrator account to the local <code>root</code> account on a Samba AD DC, it is already mapped in idmap.ldb. Mapping Administrator to root, as shown below, on a DC will break AD.
}}


{{Imbox
| type = note
| text = You should only map the domain Administrator account to the local <code>root</code> account on a Unix domain member. Configuring the mapping allows the domain Administrator to execute file operations as <code>root</code> on the Unix domain member. When you map Administrator to the <code>root</code> account, you should not attempt to log onto a Unix domain member as Administrator. Only follow the method below to map <code>Administrator</code> to <code>root</code>.
}}

{{Imbox
| type = note
| text = If, for any reason, you change the domain Administrator account name, you must use your new name for <code>Administrator</code> in the following instead of <code>Administrator</code>. 
}}


To map the domain administrator to the local <code>root</code> account:

* Add the following parameter to the <code>[global]</code> section of your <code>smb.conf</code> file:

 username map = /usr/local/samba/etc/user.map

* Create the <code>/usr/local/samba/etc/user.map</code> file with the following content:
 
 !root = SAMDOM\Administrator


:{{Imbox
| type = important
| text = When using the <code>ad</code> ID mapping back end, never set a <code>uidNumber</code> attribute for the domain Administrator account. If the account has the attribute set, the value will override the local UID <code>0</code> of the <code>root</code> user on Samba AD DC's and thus the mapping fails.
}}

For further details, see <code>username map</code> parameter in the <code>smb.conf(5)</code> man page.

= Joining the Domain =

* To join the host to an Active Directory (AD), enter:

 # net ads join -U administrator
 Enter administrator's password: Passw0rd
 Using short domain name -- SAMDOM
 Joined 'M1' to dns domain 'samdom.example.com'

{{Imbox
| type = note
| text = When you join a computer to an AD domain with <code>net ads join</code>, the computers forward dns record should be created (if not already existing), but, if your computer has a fixed ipaddress, you will have to create the reverse PTR record yourself.  
}}


* To join the host to an NT4 domain, enter:

 # net rpc join -U administrator
 Enter administrator's password: Passw0rd
 Joined domain SAMDOM.



== Joining the Domain with samba-tool (>4.15.0 only) ==

{{Imbox
| type = important
| text = Before Samba 4.15.0 , you could not join a Unix domain member using <code>samba-tool domain join</code>, this option was unsupported, did not work and would cause problems with your AD replication. You can only use <code>samba-tool domain join</code> if the Unix domain member has Samba >= 4.15.0 installed.
}}

* To join the host to an Active Directory (AD), enter:

 # samba-tool domain join samdom.example.com MEMBER -U administrator

If you have problems joining the domain, check your configuration. For further help, see [[Troubleshooting_Samba_Domain_Members|Troubleshooting Samba Domain Members]].





= Configuring the Name Service Switch =

To enable the name service switch (NSS) library to make domain users and groups available to the local system:

* Append the <code>winbind</code> entry to the following databases in the <code>/etc/nsswitch.conf</code> file:

 passwd: files <u>winbind</u>
 group:  files <u>winbind</u>

:* Keep the <code>files</code> entry as first source for both databases. This enables NSS to look up domain users and groups from the <code>/etc/passwd</code> and <code>/etc/group</code> files before querying the Winbind service.

:* Do not add the <code>winbind</code> entry to the NSS <code>shadow</code> database. This can cause the <code>wbinfo</code> utility fail.

:{{Imbox
| type = note
| text = If there's a line containing an <code>initgroups</code> directive, add <code> [success=continue] winbind</code>, otherwise the NSS library will not ask winbindd for a user's additional group memberships. Do not add the <code>initgroups</code> line if it does not exist.
}}

:{{Imbox
| type = warning
| text = Do not use the same user names in the local <code>/etc/passwd</code> file as in the domain.
}}

:{{Imbox
| type = warning
| text = Do not use local Unix names when changing file and directory ownership on Samba domain shares.
}}

:{{Imbox
| type = note
| text = If you compiled Samba, add symbolic links from the <code>libnss_winbind</code> library to the operating system's library path. For details, see [[Libnss_winbind_Links|libnss_winbind Links]]. If you used packages to install Samba, the link is usually created automatically.
}}





= Starting the Services =

Start the following services to have a fully functioning Unix domain member:

* The <code>smbd</code> service
 
* The <code>nmbd</code> service

* The <code>winbindd</code> service


:{{Imbox
| type = note
| text = If you do not require Network Browsing, you do not need to start the <code>nmbd</code> service on a Unix domain member.
}}


:{{Imbox
| type = important
| text = The latest versions of Samba (from 4.11.0) now only use SMBv2 as the minimum client & server protocols. This means that anything that relies on SMBv1 will not work, unless you manually set <code>client min protocol = NT1</code> and <code>server min protocol = NT1</code> in <code>smb.conf</code>. Samba no longer recommends using SMBv1.
}}


:{{Imbox
| type = note
| text = You must not start the <code>samba</code> service on a domain member. This service is required only on Active Directory (AD) domain controllers (DC).
}}


Samba does not provide System V init scripts, <code>systemd</code>, <code>upstart</code>, or service files for other init services.
* If you installed Samba using packages, use the script or service configuration file provided by the package to start Samba.
* If you built Samba, see your distribution's documentation for how to create a script or configuration to start services.





= Testing the Winbindd Connectivity =

== Sending a Winbindd Ping ==

To verify if the Winbindd service is able to connect to Active Directory (AD) Domain Controllers (DC) or a primary domain controller (PDC), enter:

 # wbinfo --ping-dc
 checking the NETLOGON for domain[SAMDOM] dc connection to "DC.SAMDOM.EXAMPLE.COM" succeeded

If the previous command fails, verify:
* That the <code>winbindd</code> service is running.
* Your <code>smb.conf</code> file is set up correctly.



== Using Domain Accounts and Groups in Operating System Commands ==

=== Looking up Domain Users and Groups ===

The <code>libnss_winbind</code> library enables you to look up domain users and groups. For example:

* To look up the domain user <code>SAMDOM\demo01</code>:

 # getent passwd SAMDOM\\demo01
 SAMDOM\demo01:*:10000:10000:demo01:/home/demo01:/bin/bash

* To look up the domain group <code>Domain Users</code>:

 # getent group "SAMDOM\\Domain Users"
 SAMDOM\domain users:x:10000:



=== Assigning File Permissions to Domain Users and Groups ===

The name service switch (NSS) library enables you to use domain user accounts and groups in commands. For example to set the owner of a file to the <code>demo01</code> domain user and the group to the <code>Domain Users</code> domain group, enter:

 # chown "SAMDOM\\demo01:SAMDOM\\domain users" file.txt





= Setting up Additional Services on the Domain Member =

On a Samba domain member, you can additionally set up:
* File shares to act as a file server. For details, see [[Samba_File_Serving|Samba File Serving]].
* Print services to act as a print server. For details, see [[Print_Server_Support|Print Server Support]].
* PAM authentication of domain users for local services. For details, see [[Authenticating_Domain_Users_Using_PAM|Authenticating Domain Users Using PAM]].





= Troubleshooting =

For details, see [[Troubleshooting_Samba_Domain_Members|Troubleshooting Samba Domain Members]].





----
[[Category:Active Directory]]
[[Category:Domain Members]]
[[Category:NT4 Domains]]