From Gentoo Wiki
< Samba
Jump to:navigation Jump to:search

This Samba guide is designed to help the reader move a network from many different clients speaking different languages, to many different machines that speak a common language. The ultimate goal is to help differing architectures and technologies, come together in a productive, happy coexisting environment.

Following the directions outlined in this article should provide an excellent step towards a peaceful cohabitation between Windows operating systems and virtually all known variations of *nix.



This article originally started as a FAQ, morphed into a HOWTO document, then was converted into a wiki article. The original intent was to explore the functionality and power of Gentoo, Portage, and the flexibility of USE flags. Like so many other projects, it was quickly discovered what was missing in the Gentoo realm: there were not any Samba guides catered for Gentoo users. Gentoo users are more demanding than most; they require performance, flexibility, and customization. This does not however imply that this article was not intended for other distributions; rather that it was designed to work with a highly customized version of Samba.

This article provides a details guide showing users how to share files and printers between Windows and *nix PCs. It will cover how to mount and manipulate shares.

In addition to shares few other topics will be mentioned, but they are out of the scope of this article. These will be noted as they are presented.

This article is based on a compilation and merge of an excellent HOWTO provided in the Gentoo forums by Andreas "daff" Ntaflos and the collected knowledge of Joshua Preston. The link to this discussion is provided below for reference purposes:

Before using this guide

There are a several other guides for setting up CUPS and/or Samba, please read them as well, as they may provide instructions concerning things left out of this article (intentional or otherwise). One such document is the very useful and well written Gentoo Printing Guide, as configuration issues and specific printer setup will not be discussed here.


The following software will be needed:

The main package used here is net-fs/samba, however, a kernel with CIFS support enabled is needed in order to mount a Samba or Windows share from another computer. CUPS will be emerged if it has not been already installed.

Getting acquainted with Samba

The USE flags

Before anything is emerging, take a look at some of the various USE flags available to Samba. Depending on the network topology and the specific requirements of the server, the USE flags outlined below will define what to include or exclude from the emerging of Samba.

USE flags for net-fs/samba Samba Suite Version 4

acl Add support for Access Control Lists
addc Enable Active Directory Domain Controller support
ads Enable Active Directory support
ceph Enable support for Ceph distributed filesystem via sys-cluster/ceph
client Enables the client part
cluster Enable support for clustering
cups Add support for CUPS (Common Unix Printing System)
debug Enable extra debug codepaths, like asserts and extra output. If you want to get meaningful backtraces see
fam Enable FAM (File Alteration Monitor) support
glusterfs Enable support for Glusterfs filesystem via sys-cluster/glusterfs
gpg Use app-crypt/gpgme for AD DC
iprint Enabling iPrint technology by Novell
json Enable json audit support through dev-libs/jansson
ldap Add LDAP support (Lightweight Directory Access Protocol)
llvm-libunwind Use sys-libs/llvm-libunwind instead of sys-libs/libunwind
pam Add support for PAM (Pluggable Authentication Modules) - DANGEROUS to arbitrarily flip
profiling-data Enables support for collecting profiling data
python Add optional support/bindings for the Python language
quota Enables support for user quotas
regedit Enable support for regedit command-line tool
selinux !!internal use only!! Security Enhanced Linux support, this must be set by the selinux profile or breakage will occur
snapper Enable vfs_snapper module (requires sys-apps/dbus)
spotlight Enable support for spotlight backend
syslog Enable support for syslog
system-heimdal Use app-crypt/heimdal instead of bundled heimdal.
system-mitkrb5 Use app-crypt/mit-krb5 instead of app-crypt/heimdal.
systemd Enable use of systemd-specific libraries and features like socket activation or session tracking
test Enable dependencies and/or preparations necessary to run tests (usually controlled by FEATURES=test but can be toggled independently)
unwind Enable libunwind usage for backtraces
winbind Enables support for the winbind auth daemon
zeroconf Support for DNS Service Discovery (DNS-SD)

Some things worth mentioning about the USE flags and different Samba functions include:

Server software installation

Emerging Samba

To start things correctly, be sure that all hostnames resolve correctly. Either have a working domain name system running on the network or appropriate entries in the /etc/hosts file. Certain things could break if hostnames do not point to the correct machines.

Hopefully an assessment can be made of what will actually be need in order to use Samba with the a particular setup. The setup used for this article is:

  • cups
  • readline
  • pam

To optimize performance, size, and the time of the build, USE flags are specifically included or excluded.

First, add USE flags to make sure that when samba is built, it has proper support:

root #echo "net-fs/samba readline cups pam" >> /etc/portage/package.use

Now install the Samba software:

root #emerge --ask net-fs/samba

This will emerge Samba and CUPS.

HP printers

The following package should be emerged if an HP printer will be used:

root #emerge --ask net-print/hplip

Server configuration

Configuring Samba

The main Samba configuration file is located at /etc/samba/smb.conf and can be modified using a standard text editor. Root permissions must be obtained to open the file. It is divided in sections indicated by [sectionname]. Comments are defined by either # (hash tags) or ; (semicolons). A sample smb.conf file is included below with comments and suggestions for modifications. If more details are required, see the man page for smb.conf (man smb.conf, the installed smb.conf.example, the Samba website, or any of the numerous Samba books available at local libraries or for purchase where ever such books are sold.

FILE /etc/samba/smb.confSamba configuration example
## # Replace MYWORKGROUPNAME with the appropriate workgroup/domain
workgroup = ## MYWORKGROUPNAME
## # Of course this has no REAL purpose other than letting
# everyone knows it is not Windows!
# %v prints the version of Samba being used.
server string = Samba Server %v
## # CUPS will be used; it should be inserted here
printcap name = cups
printing = cups
load printers = yes
## # This line enables the log file and limits its size to less than 50kb.
log file = /var/log/samba/log.%m
max log size = 50
## # We are going to set some options for our interfaces...
socket options = TCP_NODELAY SO_RCVBUF=8192 SO_SNDBUF=8192
## # This is a good idea, what we are doing is binding the
# samba server to our local network.
# For example, if eth0 is the local network interface:
interfaces = lo eth0
bind interfaces only = yes
## # Specifies which IP address range is allowed to access Samba
# (this is for added security since this configuration does
# not use passwords):
hosts allow =
hosts deny =
## # Other options for this are USER, DOMAIN, ADS, and SERVER
# The default is user
security = user
# previously set to share, but this no longer works
## # No passwords will be used so a guest account should be enabled:
guest ok = yes

## # Now set print drivers information:
comment = Printer Drivers
path = /etc/samba/printer ## # This path holds the driver structure
guest ok = yes
browseable = yes
read only = yes
## # Modify the following to "<username>,root" to add a second printer admin:
write list = root

## # Setup a printer to share. While the name is arbitrary it
# should be consistent throughout Samba and CUPS:
comment = HP DeskJet 930C Network Printer
printable = yes
path = /var/spool/samba
guest ok = yes
## # Modify the following to "<username>,root" to add a second printer admin:
printer admin = root

## # Now set the printer share. This should be
# browseable, printable, public, etc.:
comment = All Printers
browseable = no
printable = yes
writable = no
guest ok = yes
path = /var/spool/samba
## # Modify the following to "<username>,root" to add a second printer admin:
printer admin = root

## # Create a new share that can read from or written to anywhere.
# This is kind of like a temp public share; anyone can do what
# they want here:
comment = Public Files
browseable = yes
create mode = 0766
guest ok = yes
path = /home/samba/public
To use Samba's guest account to do anything concerning printing from Windows clients do not set guest only = yes in the [global] section. The guest account seems to cause problems when running cupsaddsmb sometimes when trying to connect from Windows machines. See below, too, when we talk about cupsaddsmb and the problems that can arise. Use a dedicated printer user, like printeruser,printer,printme, etc. It does not hurt and it will certainly protect users from many problems.

Create the directories required for the minimum configuration of Samba to share the installed printer throughout the network:

root #mkdir /etc/samba/printer
root #mkdir /var/spool/samba
root #mkdir /home/samba/public

At least one Samba user is required in order to install the printer drivers and to allow users to connect to the printer. Users must exist in the system's /etc/passwd file. The next example uses the root user, but others can be used as well.

root #pdbedit -a root

The Samba passwords need not be the same as the system passwords in /etc/passwd

You will also need to update the /etc/nsswitch.conf file so that Windows systems can be found easily using NetBIOS:

user $nano -w /etc/nsswitch.conf
hosts: files dns wins

Configuring CUPS

This section is a little more complicated. CUPS' main configuration file is /etc/cups/cupsd.conf Its structure is similar to Apache's httpd.conf file, so many may find it familiar. Outlined in the example are the directives that need to be changed:

FILE /etc/cups/cupsd.conf
ServerName PrintServer          ## # The printserver name
ServerAdmin root@PrintServer    ## # The person for printer-related hate-mail # e.g. The system administrator

AccessLog /var/log/cups/access_log ## # Probably does not need changing
ErrorLog  /var/log/cups/error_log  ## # Does not need changing either

LogLevel  debug ## # Set to debug only during installing and testing, should later be
                # changed to 'info'

MaxClients 100 ## # I've had to set this to 1000000000 or so because some time back,
               # there seemed to be a bug in CUPS' controlling of the web interface,
               # making CUPS think a denial of service attack was in progress when
               # I tried to configure a printer with the web interface. weird.

BrowseAddress @IF(eth0) ## # Set this value to internal NIC interface name

<Location />
Order Deny,Allow
Deny From All
Allow From 192.168.1.*  ## # The addresses of the internal network
                        # e.g. 192.168.1.* will allow connections from any host on
                        # the network. Modify as needed.

<Location /admin>
AuthType Basic
AuthClass System
Allow From 192.168.1.*  ## # Same as above, allows any host on the
                        # network to connect and do
                        # administrative tasks after authenticating.
Order Deny,Allow
Deny From All

Edit /etc/cups/mime.convs file to uncomment some lines. The changes to mime.convs and mime.types are needed to make CUPS print Microsoft Office document files.

The following line is found near the end of the file. Uncomment it:

FILE /etc/cups/mime.convs
application/octet-stream        application/vnd.cups-raw        0

Edit /etc/cups/mime.types to uncomment some lines.

The following line is found near the end of the file. Uncomment it:

FILE /etc/cups/mime.types

CUPS needs to be started on boot, and started immediately.

root #rc-update add cupsd default
root #/etc/init.d/cupsd restart

Installing a printer for and with CUPS

First, go to OpenPrinting to find and download the correct PPD file for the printer and CUPS. To do so, click the link Printer Listings to the left. Select the printers manufacturer and the model in the pull down menu, e.g. HP and DeskJet 930C. Click "Show". On the page coming up click the "recommended driver" link after reading the various notes and information. Then fetch the PPD file from the next page, again after reading the notes and introductions there. You may have to select your printers manufacturer and model again. Reading the CUPS quickstart guide is also very helpful when working with CUPS.

Now you have a PPD file for your printer to work with CUPS. Place it in /usr/share/cups/model . The PPD for the HP DeskJet 930C was named HP-DeskJet_930C-hpijs.ppd . You should now install the printer. This can be done via the CUPS web interface or via command line. The web interface is found at http://PrintServer:631 once CUPS is running.

root #lpadmin -p HPDeskJet930C -E -v usb:/dev/ultp0 -m HP-DeskJet_930C-hpijs.ppd
root #/etc/init.d/cupsd restart

Remember to adjust to what you have. Be sure to have the name (-p option) right (the name you set above during the Samba configuration!) and to put in the correct usb:/dev/usb/blah , parallel:/dev/blah or whatever device you are using for the printer.

The printer should now be available from the web interface and to print a test page.

Installing the Windows printer drivers

Now that the printer should be working it is time to install the drivers for the Windows clients to work. Samba 2.2 introduced this functionality. Browsing to the print server in the Network Neighbourhood, right-clicking on the printer share and selecting "connect" downloads the appropriate drivers automatically to the connecting client, avoiding the hassle of manually installing printer drivers locally.

There are two sets of printer drivers for this. First, the Adobe PS drivers which can be obtained from Adobe (PostScript printer drivers). Second, there are the CUPS PS drivers, to be obtained by emerging net-print/cups-windows. There does not seem to be a difference between the functionality of the two, but the Adobe PS drivers need to be extracted on a Windows System since it's a Windows binary. Also the whole procedure of finding and copying the correct files is a bit more hassle. The CUPS drivers support some options the Adobe drivers don't.

This article uses the CUPS drivers for Windows. Install them as shown:

root #emerge --ask net-print/cups-windows

Now use the cupsaddsmb script provided by the CUPS distribution. Be sure to read its man page (man cupsaddsmb), as it will tell which Windows drivers are needed to be copied to the proper CUPS directory. Once the drivers have been copied, restart CUPS by issuing /etc/init.d/cupsd restart to the command line. Next, run cupsaddsmb as shown:

root #cupsaddsmb -H PrintServer -U root -h PrintServer -v HPDeskJet930C

Instead of HPDeskJet930C the -a option use be specified. This will "export all known printers":

root #cupsaddsmb -H PrintServer -U root -h PrintServer -a

The execution of this command often causes the most trouble. Read through the posts in this thread for some troubleshooting tips.

Here are common errors that may happen:

  • The hostname given as a parameter for -h and -H ( PrintServer ) often does not resolve correctly and does not identify the print server for CUPS/Samba interaction. If an error like: Warning: No PPD file for printer "CUPS_PRINTER_NAME" - skipping! occurs, the first thing to do is substitute PrintServer with localhost and try again.
  • The command fails with an NT_STATUS_UNSUCCESSFUL error. This error message is quite common, but can be triggered by many problems. It is unfortunately not very helpful. One thing to try is to temporarily set security = user in the smb.conf After/if the installation completes successfully, you should set it back to share, or whatever it was set to before.

This should install the correct driver directory structure under /etc/samba/printer . That would be /etc/samba/printer/W32X86/2/ The files contained should be the 3 driver files and the PPD file, renamed to YourPrinterName.ppd (the name given to the printer when installing it, see above).

Pending no errors or other complications drivers will now be installed.

Installing the Web Service Discovery host daemon


wsdd implements a Web Service Discovery host daemon. This enables (Samba) hosts, like your local NAS device, to be found by Web Service Discovery Clients like Windows.

Showing a SAMBA server in the Network Neighbourhood.

Since NetBIOS discovery is not supported by Windows anymore, wsdd makes hosts to appear in Windows again using the Web Service Discovery method. This is beneficial for devices running Samba, like NAS or file sharing servers on your local network.


With Windows 10 version 1511, support for SMBv1 and thus NetBIOS device discovery was disabled by default. Depending on the actual edition, later versions of Windows starting from version 1709 ("Fall Creators Update") do not allow the installation of the SMBv1 client anymore. This causes hosts running Samba not to be listed in the Explorer's "Network (Neighborhood)" views. While there is no connectivity problem and Samba will still run fine, users might want to have their Samba hosts to be listed by Windows automatically.

root #emerge net-misc/wsdd

Finalizing the setup

Lastly, setup the directories:

root #mkdir /home/samba
root #mkdir /home/samba/public
root #chmod 755 /home/samba
root #chmod 755 /home/samba/public

Testing the Samba configuration

Test the configuration file to ensure that it is formatted properly and to verify all options have the correct syntax. To do this, run the testparm program:

root #/usr/bin/testparm
Load smb config files from /etc/samba/smb.conf
Processing section "[printers]"
Global parameter guest account found in service section!
Processing section "[public]"
Global parameter guest account found in service section!
Loaded services file OK.
Press enter to see a dump of your service definitions

Starting the Samba service

Now configure Samba to start at boot and then start it.


root #rc-update add samba default
root #/etc/init.d/samba start


root #systemctl --now enable smbd.service
root #systemctl --now enable nmbd.service

Checking the services

It might be prudent to check out logs at this time. Take a peak at the Samba shares using the smbclient command:

root #smbclient -L localhost
## (A BIG list of services should be displayed here.)

Configuration of the clients

Printer configuration of *nix based clients

Despite the variation or distribution, the only thing needed is CUPS. Do the equivalent on any other UNIX/Linux/BSD client.

root #emerge --ask net-print/cups
root #nano -w /etc/cups/client.conf
ServerName PrintServer      ## # your printserver name

That should be it. Nothing else will be needed.

When using only one printer, it will be set as the default printer. If the print server manages several printers, the administrator will have defined a default printer on the server. If a user would like to define a different default printer, use the lpoptions command.

First list the available printers:

root #lpstat -a
HPDeskJet930C accepting requests since Jan 01 00:00
laser accepting requests since Jan 01 00:00

Now define the printer (in the example, HPDeskJet930C) as the default printer:

root #lpoptions -d HPDeskJet930C

To enable printing on the Unix/Linux systems, either specify the printer to be used, or just use the default printer (second example):

root #lp -d HPDeskJet930C anything.txt
root #lp

Point a web browser to http://printserver:631 on the client to manage the printers and their jobs via a nice web interface. Replace printserver with the name of the machine which acts as the print server. Be careful to not use the name given to the cups print server if a different name was used.

Mounting a Windows or Samba share in GNU/Linux

Do not forget to install net-fs/samba on the client(s) that will be accessing the shares.

Now is time to configure our kernel to support CIFS. Since I'm assuming we've all compiled at least one kernel, we'll need to make sure we have all the right options selected in our kernel. For simplicity's sake, make it a module for ease of use. It is the author's opinion that kernel modules are a good thing and should be used whenever possible.

KERNEL Kernel support

Then make the module/install it; insert it with:

root #modprobe cifs

Once the module is loaded, mounting a Windows or Samba share is possible. Use mount to accomplish this, as detailed below.

The syntax for mounting a Windows/Samba share is:

root #mount -t cifs [-o username=xxx,password=xxx] //server/share /mnt/point

You can drop the username and password options if no password is needed.

root #mount -t cifs //PrintServer/public /mnt/public

After mounting the share, it can be accessed as if it were a local drive.

Printer configuration for Windows NT/2000/XP clients

Configuring printers is simply a bit of point-and-click. Browse to \\PrintServer and right click on the printer (HPDeskJet930C) and click connect. This will download the drivers to the Windows client which will enable applications (such as Word or Acrobat) to offer HPDeskJet930C as an available printer.

Access for Windows XP clients

The Samba server smb.conf requires at least the following for enabling access from Windows XP clients.

FILE /etc/samba/smb.conf
server min protocol = LANMAN2
lm announce = no
lanman auth = no
# If ntlm=yes triggers success for winxp, see Enable NTLMv2 note below
ntlm auth = no
client lanman auth = no
client ntlmv2 auth = yes

Modify the Windows XP registery with the following, exporting/saving the original default first:

HKEY_LOCAL_MACHINE, SYSTEM, CurrentControlSet, Control, LSA

Change LMCompatibilityLevel=0 to LMCompatibilityLevel=5

Restart the Samba server and Windows XP client.

Debugging Samba server access

Can view more Samba server debug info by adding the following to the /etc/smb.conf and restarting the Samba server:

FILE /etc/samba/smb.conf
# Output more debug/verbose logging
#log level = 3
# Check good pass auth
#log level = 3 passdb:5 auth:5
#log level = 10 passdb:5 auth:5

If logins are failing, the following should output the server authentication protocol and reason after enabling verbose debugging as previously mentioned.

# tail -f /var/log/samba/log.smbd

Once logins are almost successful, logging will output to the client's hostname log.

# tail -f /var/log/samba/log.YOUR_HOSTNAME

KDE Plasma 5

kio-extras contains Samba support, but it requires the samba USE flag.

See also

  • Printing — covers the installation and maintenance of printers using CUPS and Samba.

External resources


See this page from Kurt Pfeifle's "Printing Support in Samba 3.0" manual. Lots of useful tips there! Be sure to look this one up before posting questions and problems. Using this resource the solution may be quickly found.

This page is based on a document formerly found on our main website
The following people contributed to the original document: Andreas "daff" Ntaflos, Joshua Preston, Joshua Saddler
They are listed here because wiki history does not allow for any external attribution. If you edit the wiki article, please do not add yourself here; your contributions are recorded on each article's associated history page.