From Gentoo Wiki
(Redirected from CIFS)
Jump to:navigation Jump to:search

Samba is a re-implementation of the SMB/CIFS networking protocol, a Microsoft Windows alternative to Network File System (NFS).



KERNEL Enabling CIFS and SMB2/SMB3 support
File Systems --->
    [*] Network File Systems --->
        [*] CIFS support (advanced network filesystem, SMBFS successor)--->
            [*] CIFS Statistics
                [*] Extended Statistics
            [*] CIFS Extended Attributes
                [*] CIFS POSIX Extentions
            [*] SMB2 and SMB3 network file system support
If a share fails to mount with the error CIFS VFS: Unknown vers= option specified: 2.1, enable the CONFIG_CIFS_SMB2 kernel option.


Samba is a full software suite capable of hosting file shares via SMB, connecting to SMB share hosted non-locally, along with many other features. If the system will only need to mount shares hosted on other systems, then jump to the CIFS section.

USE flags

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)

Especially when setting up an AD DC: Read the current Samba documentation and release notes. MIT kerberos support is still marked experimental in Samba. System Heimdal support also seems broken at the Samba side - That's why, system-heimdal keyword is currently hard masked. For AD DC production environments, running Samba with the bundled heimdal kerberos should be considered at the moment.


Install Samba:

root #emerge --ask --noreplace net-fs/samba

Samba can also be installed by setting the global USE flag samba and updating the system:

root #emerge --ask --changed-use --deep @world


CIFS utilities are capable of mounting hosted file shares via SMB. If the system will need to do more than mounting SMB shares, then jump to the Samba section.

USE flags

If the full Samba software suite is not needed, the net-fs/cifs-utils package is available:

USE flags for net-fs/cifs-utils Tools for Managing Linux CIFS Client Filesystems

acl Add support for Access Control Lists
ads Enable Active Directory support and create cifs.idmap binary - idmap support
caps Enable sys-libs/libcap-ng support
creds cifs credentials support
pam Add support for PAM (Pluggable Authentication Modules) - DANGEROUS to arbitrarily flip
python Enable support for python and install python tools
systemd Enable use of systemd-specific libraries and features like socket activation or session tracking


Emerge the CIFS user-space tools:

root #emerge --ask net-fs/cifs-utils




When using OpenRC, adding Samba to the default runlevel will enable the Samba service to start when the system boots:

root #rc-update add samba default

To start the Samba service now issue:

root # eselect rc start samba


For systemd users, the Samba service can be configured to start during boot using systemctl:

root #systemctl enable smb.service

To start the service immediately issue:

root #systemctl start smb.service

CIFS share

Mount the shared content via CLI

Once the client is fully configured, the shares can soon be accessed.

Create the mount points:

root #mkdir -p /mnt/My-Disk/{Media,Shared}

Manually mount the exported folders:

root #mount.cifs //O2-Foobar/Media /mnt/My-Disk/Media -o guest
root #mount.cifs //O2-Foobar/Shared /mnt/My-Disk/Shared -o guest

Mount the shared content automatically via fstab

To automatically mount guest shares on boot:

FILE /etc/fstab
//O2-Foobar/Media  /mnt/My-Disk/Media  cifs guest
//O2-Foobar/Shared /mnt/My-Disk/Shared cifs guest

To define user protected shared which can be mounted manually

FILE /etc/fstab
//O2-Foobar/Media  /mnt/My-Disk/Media  cifs _netdev,noauto,user=larry
//O2-Foobar/Shared /mnt/My-Disk/Shared cifs _netdev,noauto,user=larry

These mounts can be mounted with:

root #mount /mnt/My-Disk/{Media,Shared}
* In the case of permission problems are encountered when trying to create files and folders on the disk, try to use gid=<user's_gid>, uid=<user's_uid>
  • Be sure to replace <user's_gid> with the user ID of choice.


Some problems may occur when trying to mount new CIFS shares. The following sections attempt to provide resolutions to common problems.

Cannot resolve <server-name>

More specifically, the actual error:

root #mount.cifs ...
"mount error: could not find target server. TCP name foo/bar not found. No ip
address specified and hostname not found"

This can easily be fixed by editing /etc/nsswitch and appending wins next to the hosts entry:

FILE /etc/nsswitch
hosts: files dns wins

If this does not work, use the CIFS server's IP address instead of the O2-Foobar hostname. The nmblookup utility (provided by net-fs/samba) comes in handy when trying to find the IP address of an CIFS host:

root #nmblookup O2-Foobar

Shutdown process hangs when trying to unmount CIFS shares

If the system shutdown hangs at

* Unmounting network filesystems ...

then users must make sure the CIFS shares are unmounted properly before udev tries to stop. One way to work around this is to create local.d scripts to unmount the CIFS filesystems:

root #echo "umount -a -t cifs -f" > /etc/local.d/cifs.stop
root #chmod a+x /etc/local.d/cifs.stop

Client asking for share username/password

If Samba does not start after upgrading to Samba 4.2.11 with the following error:

WARNING: Ignoring invalid value 'share' for parameter 'security'
error opening config file '/etc/samba/smb.conf'

Change the Samba security parameter from share to user:

FILE /etc/samba/smb.conf
security = user

If guest access is enabled and the client is requesting the share username/password, set the map to guest parameter to bad user:

FILE /etc/samba/smb.conf
map to guest = bad user

Samba daemon fails to start without error

If Samba daemon does not start:

root #/etc/init.d/samba restart
 * samba -> start: smbd ...
 * start-stop-daemon: failed to start `/usr/sbin/smbd' [ !! ]
 * samba -> start: nmbd ...
 * start-stop-daemon: failed to start `/usr/sbin/nmbd' [ !! ]
 * Error: starting services (see system logs)
 * samba -> stop: smbd ...
 * start-stop-daemon: no matching processes found      [ ok ]
 * samba -> stop: nmbd ...
 * start-stop-daemon: no matching processes found      [ ok ]

And Samba logs do not indicate any errors:

FILE /var/log/samba/log.smbd
[2022/06/04 20:20:48.851120,  0] ../../source3/smbd/server.c:1741(main)
  smbd version 4.16.1 started.
  Copyright Andrew Tridgell and the Samba Team 1992-2022

Check that /var/lock has space:

root #df -h /var/lock
Filesystem      Size  Used Avail Use% Mounted on
tmpfs           1.0M  1.0M     0 100% /var/lock

See also

  • Samba (Security Handbook) - The Security Handbook's entry on how to secure a system running Samba.
  • Samba/Guide — provides a details guide showing users how to share files and printers between Windows and *nix PCs.
  • Samba/Samba 4 Migration — introduces the migration of Samba 3 to Samba 4 with LDAP on Gentoo boxes.
  • Smbnetfs — a FUSE-based filesystem for SMB/CIFS shares.
  • SSHFS — a secure shell client used to mount remote filesystems to local machines.
  • Nfs-utils — a file system protocol that allows client machines to access network attached filesystems (called exports) from a host system.

External resources