Gentoo Wiki


This article is part of the HOWTO series.
Installation Kernel & Hardware Networks Portage Software System X Server Gaming Non-x86 Emulators Misc



Samba is a free software implementation of Microsoft's networking system. As of version 3, samba not only provides file and print services for various Microsoft Windows clients but can also integrate with a Windows Server domain, either as a Primary Domain Controller (PDC) or as a Backup Domain Controller. It can also be part of an Active Directory domain.samba software

Wikipedia has an article on:
Samba software


Samba has a nice amount of USE flags. Here are their explanation.

Table. Explanation of Samba3 flags.

USE flag Description
acl Include support for Kerberos. Enables Access Control Lists. The ACL support in Samba uses a patched ext2/ext3, or SGI's XFS in order to function properly as it extends more detailed access to files or directories; much more so than typical *nix GID/UID schemas.
automount Enables automount support
cups This enables support for the Common Unix Printing System. This provides an interface allowing local CUPS printers to be shared to other systems in the network.
kerberos Adds kerberos support for authentication to AD.
ldap Enables the Lightweight Directory Access Protocol (LDAP). If Samba is expected to use Active Directory, this option must be used. This would be used in the event Samba needs to login to or provide login to a Domain/Active Directory Server. The kerberos USE flag is needed for proper functioning of this option.
ldapsam Enables samba 2.2 ldap support (default passwd backend: ldapsam_compat)
pam Include support for pluggable authentication modules (PAM). This provides the ability to authenticate users on the Samba Server, which is required if users have to login to your server. The kerberos USE flag is recommended along with this option.
swat Includes the files necessary to use the Samba Web Administration Tool (SWAT)
winbind Enables support for the winbind auth daemon

When you know what you need, enable them by adding them to /etc/portage/package.use and run: emerge samba

This will install the samba package for use both as client and server.

You can also add the USE flag "samba" in your /etc/make.conf.


Kernel Requirements for Clients

To mount shares you need to have SMB file system support compiled as a module or in the kernel.

Switch to the directory of the current kernel source and launch the menuconfig utility by running: cd /usr/src/linux && make menuconfig

Linux Kernel Configuration: Required options for Samba
File systems  --->
  Network File Systems  --->
    <*> SMB file system support
    <*> CIFS support

If SMB support is not enabled, either compile as a module or enable it and recompile your kernel.


There is no configuration for samba client. Just use it!

Mounting shares

To access the Windows shares on the network, you can mount them quite like standard Unix mounts. Note that the SMB fstype is deprecated in favor of CIFS. You can use the mount command, instead of smbmount.

Using CIFS

Warning: If using Samba 3.0.25 or newer you must emerge mount-cifs

Mount the share with using the following command, replacing <shared folder>, <mountpoint>, <user> and <uid> with the relevant values.

Code: Command for mounting shares using CIFS
mount -t cifs //<windows machine name>/<shared folder> /<mountpoint> \
 -o "username=<user>,uid=<uid>,iocharset=cp850,dir_mode=0770,file_mode=0660"

The charset cp850 may not be correct, depending on your Windows setup. This charset was used in a Scandinavian production environment.

Warning: On some systems, "mount" doesn't support forward slashes in UNC path names as shown above -- you must use backslashes. Otherwise you get the error message below even when the UNC path you provided did start with //:
mount error: improperly formatted UNC name. /host/share does not begin with \\ or //

You can use forward slashes with mount.cfs, but not with mount (or in fstab).

This problem occurs on some systems but not others (even with exact same versions of samba and util-linux packages). It's not know what causes the failure, but using backslashes seems to be a reliable work-around.

Using SMB

Mount the share with the following command, replacing <shared folder>, <mountpoint>, <user> and <password> with the relevent values.

Code: Command for mounting shares using SMB
smbmount //<windows machine name>/<shared folder> /<mountpoint> \
 -o username=<user>,password=<pass>,uid=1000,umask=000

-o is used to pass option to smbmount.

Note: the user option, allowing a non privileged user to mount/umount the share, does not work on smbfs. The noauto standard option is neither recognized.

I also added some lines to /etc/fstab to auto-mount shares from machines that are always on and always connected (like my DVR box).

File: /etc/fstab
//<windows machine name>/<shared folder>   /<mountpoint>   smbfs   username=<user>,password=<pass>,uid=1000,umask=000   0 0

Note: to mount shares with spaces use "\040" without the quotes in place of the space. And if you have to use parentheses, use \050 for ( and \051 for ) .

A quick explanation:

File: /etc/fstab example using credentials file
//<windows machine name>/<shared folder>   /<mountpoint>   smbfs  auto,credentials=/root/.credentials,uid=1000,umask=000,user  0 0

/root/.credentials takes the form

File: /root/.credentials example

and make the file only be read/writable by root by running: chmod 600 /root/.credentials

Once the /etc/fstab file as been edited and /root/.credentials file created and secured, it can be tested using mount -a with no need of rebooting as the /etc/fstab is used at boot time. using -a option tells to mount all of the mount points in /etc/fstab and write to the /etc/mtab accordingly. If mount runs into any errors reading the /etc/fstab file it should automaticly output an error message with good description, eg: invalid share name, access denied, invalid or non-existing mount point.

Optionally you can use mount <mountpoint> to mount just the mountpoint you just added to /etc/fstab. umount <mountpoint> will unmount the mountpoint.


The mounts are browsable using Konqueror and smb:// protocol. Works really well. :)

Another GUI client is smb4k. It works very well and makes it easy to mount and unmount remote samba shares. Unfortunately, for me smb4k failed while parsing my sudoers (it is correct according to visudo) so it can only mount to used folders, unless you alias mount='sudo mount'.

Gnome users can browse the network via the smb:// protocol with nautilus by simply enabling the samba use flag to gnome-base/gnome-vfs.

smbclient and smbmount

Before you can mount a share you must know where it is. List the shares on a foreign host with the following command, replacing <hostname> with the name of the host: smbclient -L <hostname> -U%

You'll see something like this:

Code: Shares
        Sharename       Type      Comment
        ---------       ----      -------
        public          Disk      shared
        IPC$            IPC       IPC Service
        ADMIN$          IPC       IPC Service

Now to mount directory "public" you need to find a place to mount this. It does not really matter where as long as it's an empty folder, for this example I'll use /mnt/samba

You can create this by running this command: mkdir /mnt/samba

One last thing before we mount our share we need know the user name and password if there is one. To mount the share run this command: smbmount //hostname/public /mnt/samba

NOTE: If there is a space in the sharename put the whole name in "" ""

NOTE: Use "mount -t cifs ..." if trying to mount to a windows 2003 fileserver

Example: mount -t cifs //server/share /mnt/samba -o username=username

Mount and umount as non privileged user

This require the smbmnt and smbumount commands promoted as root processes, setting the suid permission bit. Beware if any vulnerability might exist in such executables, they might be exploited by local users for a privilege escalation (that is, execute arbitrary instructions as root. Otherwise said, take complete control of the machine).

To change the suid bit set for the two commands, logged as root, use: chmod 4755 /usr/bin/smbmnt

You'll need to mount / umount this share on a directory owned (created) by the user.

To mount a share from the host in the directory /home/localuser/mydir, from the non privileged user shell, is to run: smbmount -o username=foouser // /home/localuser/mydir

The smbmount command will prompt for the remote foouser password.

To unmount a share, run smbumount /home/localuser/mydir

Common Issues

smbmount <remote share> <mountpoint> -o username=<username>,password=<password>
--Skeezer65134 05:50, 20 October 2005 (GMT)

mount.cifs is splitted to a new package named: net-fs/mount-cifs

emerge -av net-fs/mount-cifs

-- 13:33, 8 December 2007 (UTC) pho


GUI administration

If you are like me, lazy and prefer not to write the smb.conf file from scratch then you are in luck.


Lets call in the swat team. Samba offers a web page interface that will allow you to do just that. It is very similar to cups web interface. You need have xinetd installed on your machine as well as samba installed with the swat USE flag. Looking through the forums it seems that xinetd has changed a bit so if you currently have an older version installed you may need to update. Seems the older versions used to have all services setup in one single file xinetd.conf file. Now individual services have their own config files, which can be found in /etc/xinetd.d directory. The master config file is /etc/xinetd.conf which now has the includedir statement pointing to the xinetd.d directory.

Code: Adding swat and xinetd
emerge xinetd
rc-update add xinetd default

(remember to use ng-update instead if you are using initng for boot)

By default xinetd services are disabled and you must turn them on. I didn't realize this and kept restarting samba/xinetd because I was getting a connection refused every time I pointed my browser to the port swat was supposed to be on. This was a WTF moment as I cursed at my box trying to figure out why swat was not starting and why I kept getting a connection refused message in the browser. So lets edit the swat service config file. Use your favorite editor and edit /etc/xinetd.d/swat file.

You should see something like:

Code: Edit /etc/xinetd.d/swat
service swat 
        port            = 901 
        socket_type     = stream 
        protocol        = tcp
        wait            = no 
        only_from       = localhost 
        user            = root 
        server          = /usr/sbin/swat 
        log_on_failure += USERID 
        disable         = no

By default disable may be set to "yes" make sure it is set to "no". You can modify the only_from line to allow machines besides the localhost to connect to this service if you wish. With Swat/Samba-3.0.22 you have to set "only_from" to allow any host. Deleting this line will deny any connection. I wouldn't recomend this but a good firewall and other security measures can make this a bit safer. You may also want to change the port number as well. Now that the config file has been changed let's start the service.

Code: Start swat
/etc/init.d/xinetd start

If all went well you should now be able to start the swat browser interface. Just enter http://localhost:901 as the url in your browser. You should be prompted for your username and password. To change the configuration you must enter root information, normal user info will only allow limited access. If that worked, you should now be able to create a smb.conf file on the fly using swat. The one thing I find handy about swat is the fact that most option entries have help links to help figure out what you need to do. Happy Swatting - GreyParrot(2/14/06)

Code: Copy example smb.conf
cp /etc/samba/smb.conf.example /etc/samba/smb.conf
smbpasswd -a root

Then set your samba root passwd. Now log in using this password.

KDE Control Center

Alternatively, if you fancy KDE, there is a samba interface which will edit your smb.conf file, add shares, and configure anything you like. The program is part of Kcontrol - swingkyd (4/4/06)

emerge -av kcontrol


Configuration file for Samba server is /etc/samba/smb.conf
Open it with your favorite text editor and let's edit. In the beginning of file (in global section) you'll see the following:

Code: smb.conf file

# workgroup = NT-Domain-Name or Workgroup-Name, eg: LINUX2
   workgroup = WORKGROUP
   netbios name = LINUXBOX

# server string is the equivalent of the NT Description field
   server string = Lets dance samba

# Security mode. Defines in which mode Samba will operate. Possible
# values are share, user, server, domain and ads. Most people will want
# user level security. See the HOWTO Collection for details.
   security = share

# Unix users can map to different SMB User names
   username map = /etc/samba/smbusers

"Netbios name" is your computer name (usually same as your hostname). "Workgroup" is your workgroup. "Server string" is description of the samba server. Make security = share if you want to share files without password. Easy for making anonymous access. (NOTE: Alternatively set security = user and specify a local user that would own the share. See below on how to add local_user). Set username map if you want to use aliases, otherwise they will not be accessible.

If you are interested in requiring your remote users to log into the share and protecting it with a password, you should set an alias for guest. This is because Windows (XP Pro in my case at least) uses the username "Guest" as the default login with the share security level. Do this as follows:

   guest account = local_user

The problem is that this will only work for authenticating 1 user. See the next topic for user-based access control.

To authenticate users individually, set up your smb.conf file like this:

File: /etc/samba/smb.conf
   workgroup = MSHOME
   security = user

   valid users = %S
   read only = no
   browseable = no

(Note that this is a complete file, you don't have to include everything shown above, but you can if you want.)

The [homes] section creates a share for each user who logs in that gives them access to their home directory. For example, if john is logged into the server, he'd see a share named john with the contents of his home directory. This section is optional, but convenient.

Now you have to add users to samba's authentication database. Once you've created a local user account for the user:

   # useradd -m -G users john
   # passwd john

add their account to the samba database:

   # smbpasswd -a john

Now continue with creating shares if you need more than home directories shared.

Make a particular directory for samba log files. And set maximum log size, because we don't want to be flooded with huge logs.

   log file = /var/log/smb/samba.%m
   max log size = 50

Now proceed in the file and find this part:

# Browser Control Options:
# set local master to no if you don't want Samba to become a master
# browser on your network. Otherwise the normal election rules apply
#   local master = yes

If you don't want windows users to blame you, change option local master to "no" and uncomment the line. With this option = yes your linux box and windows hosts will argue about local master browser rights on your LAN. Make this change:

   local master = no

If you'd like to share your printers over samba (assuming your printers are running under a cups server), you need to add the following lines somewhere in the global section:

#added for remote printer use over samba
printcap name = cups
disable spoolss = Yes
show add printer wizard = No
printing = cups

This will require that the remote machines install the drivers for the printer locally. In the case of Windows machines, you will need to install the drivers first and then connect to the share over the network.

We're finished with global section of smb.conf file. Now proceed in the next chapter to see how to share directories. --Skeezer65134 12:07am, 27 June 2005 (CST)

Adding a Share

Sharing on Linux is as simple as on a Windows box. Just go to the end of smb.conf and add this:

Code: Sharing directories with Samba
        comment = shared
        path = /mnt/public
        guest ok = yes
        browseable = yes

Make neccessary changes, where "comment" is your share comment, "path" is your shared directory path and "public" is your shared directory name. This will allow users on your network to connect to this share with access rights of user nobody.

If you are interested in using user authentication, you need to specify what users may access this share. Change the above to look like this:

Code: Sharing directories with user access control with Samba
        comment = shared
        path = /mnt/public
        valid users = local_user
        guest ok = no
        browseable = yes

This will allow a remote machine to connect to the samba share by logging in as local_user and entering the correct password. Note that we use the 'guest account = local_user' above in the global configuration. Again, Windows will default to logging in as Guest, and you will not be able to change this (actually you can. Go into user management, and on the left pane, you will have an option to change network passwords, add the proper name there.), so the above makes a nice work-around.

If you want to give write permissions to your samba users, just add writable = yes, as follows (make sure that permissions in those directories you are offering are right. If not, use chmod, of course):

        comment = shared
        path = /mnt/public
        valid users = local_user
        guest ok = no
        browseable = yes
        writable = yes

Perhaps you want a share that is public but only writable to some persons (in this case the group "users" and the user "fathergoat"), this can be achieved like this:

        comment = shared
        path = /path/to/your/share
        public = yes
        writable = no
        write list = @users fathergoat

To add all local printers that connect via the CUPS server, add something like this:

        comment = All Printers
        path = /var/spool/samba
        printer admin = root, local_user
        create mask = 0600
        guest ok = Yes
        printable = Yes
        use client driver = Yes
        browseable = No

This will list ALL of your local CUPS printers and list them based on their names and descriptions as defined in the CUPS configuration. Once again, the local machine connecting to the printer over samba will need to install the drivers first for it to work.

Don't forget you need to start your Samba server before you can set the user's Samba password.

Code: Starting Samba
#/etc/init.d/samba start
 * Caching service dependencies ...                                       [ ok ]
 * samba -> start: smbd ...                                               [ ok ]
 * samba -> start: nmbd ...                                               [ ok ]

Adding a Valid User

For user access control, please note that you MUST specify a password for local_user using smbpasswd. The reason being that the user must also exist in /etc/samba/smbusers AND be a valid user on the computer running the samba server for Samba to have enough information to go through with authentication.

Code: Setting samba user passwords
#smbpasswd -a local_user
New SMB password: <type password>
Reenter smb password: <type password again>
Added user local_user.
Code: /etc/samba/smbusers
local_user = local_user

Note that the second name you enter can be a separate alias for local_user to log in to the samba share. More clearly, the name to the right of the = can be anything and will be used to log into the samba share. The Linux username to the left of the = must match the "valid user" statement in the share's definition. This means, in the case of the example below, that you can use username 'dozebox' to login to all the shares the "valid user" 'smb_remote' has access to.

Code: Using Aliases in smbusers
local_user = local_user
smb_remote = jim dozebox
smb_admin = admin administrator backup

In this example five additional samba login names are aliasing two system user names. In Samba 3.0.22 you must specify the location of smbusers in smb.conf or aliases will not be able to log in.

Tip: User names must not be equal with the NetBIOS Name of your PC. For instance, smb://Fenix@FENIX/ will result in an error.

Starting Samba on Boot

To start samba on boot, add it to the default runlevel by running: rc-update add samba default

See also

Official gentoo documentation

Retrieved from ""

Last modified: Tue, 07 Oct 2008 11:37:00 +0000 Hits: 148,788