KSMBD.CONF(5)

📦
version 3.5.7 · 5 versions
, in nixpkgs unstable, ubuntu stonking

💖 ksmbd.conf — the config file for ksmbd.mountd 💖

okay bestie, gather round, because this is the manpage for ksmbd.conf in section 5 (File Formats and Conventions), and it's a chonky one. we're doing this together. part one. let's go 🫶

✨ NAME ✨

ksmbd.conf — the configuration file for ksmbd.mountd

🌸 DESCRIPTION 🌸

ksmbd.conf is the configuration file for the ksmbd.mountd(8) user mode daemon. like, this is where all the server's settings live. periodt.

you can hand-edit it (iconic behaviour), but there's also ksmbd.addshare(8), which is the tool for configuring shares in ksmbd.conf. heads up though: ksmbd.addshare modifies ksmbd.conf such that its existing formatting is not retained. so if you spent an hour aligning your equal signs for the aesthetic… yeah, it's gone. 😭

the good news? ksmbd.addshare notifies ksmbd.mountd of changes, if it had made any, by sending the SIGHUP signal to ksmbd.mountd. and changes made with ksmbd.addshare will never require restarting ksmbd.mountd and ksmbd to take effect. no restart era, we love to see it. 💅

if you're not using ksmbd.addshare, you can still ping the daemon about your changes with ksmbd.control --reload.

by default, ksmbd.conf is expected to be at /etc/ksmbd/ksmbd.conf. and there's a whole example file chilling at /etc/ksmbd/ksmbd.conf.example if you want to peek at what a real one looks like. 👀

🎀 FILE FORMAT 🎀

okay so the structure is genuinely not that deep, i promise.

ksmbd.conf is made of sections (aka groups), and each section marks the end of the one before it. a section starts with the section name wrapped in brackets ([]), followed by a newline. 🌈

a section can contain parameters separated by newlines. a parameter is a name (aka a key) and a value, in that order, separated by an equal sign (=).

here's the fine print, and yes it matters:

  • a name may contain leading and trailing tabs and spaces.
  • a value begins immediately after the equal sign, and it may contain leading tabs and spaces, or be empty.
  • a value may be a list of multiple values separated by commas, tabs, and spaces.
  • for a list of users: to give all the users in a system group, you give the group name prefixed with an at (@).
  • a value may have a number suffix, which is either K, M, G, T, P, or E.
  • a semicolon (;) or a hash (#) marks the beginning of a comment, and that comment continues until the end of the line.
  • if a section has the same name as a previous section, it's a continuation of that previous section — like, they're literally the same section. no cap.
  • a duplicate parameter in a section has its value updated only if its previous value was empty. so first-nonempty-wins energy. 🙈

🦋 SHARES 🦋

every section name, except the one for the global section, defines a shared resource — commonly called a share. yes bestie, that's the whole point of this file.

the section name is the share name, and it has rules:

  • it must be UTF-8
  • it must be [1, 64) bytes
  • it is case-insensitive

users that may be allowed to connect to a share are those present in the ksmbdpwd.db(5) user database. a share may also limit which users are allowed to connect to it (more on that in the parameters, we'll get there 💜).

when a user connects to a share, they get mapped to a system user, and the underlying filesystem permissions are enforced. by default that mapping is done by name — but it can also be done by mapping all users connected to the share onto a single system user and group.

and if someone connects as a user who isn't in the user database? only guest sessions may work. that's the vibe check.

👑 PARAMETERS 👑

before we dive into the list, here's the legend, because the letters actually mean something:

  • Share parameters, marked below with (S), can be given in any section. when given in a section that isn't global, it's specific to that particular share. when given under the global section, it sets the default value for all shares.
  • Global parameters, marked below with (G), can only be given in the global section, and they control functionality that applies to the server.
🚨 real talk: changes to global parameters apply only after restarting ksmbd.mountd and ksmbd. no SIGHUP shortcut for those, sorry bestie.
  • aapl model (G) — the model string sent in the SMB2 AAPL extension's server-capabilities response. macOS uses it to pick a Finder icon for the server (for example, Xserve gets you a rack-server icon 🖥️). only relevant to shares with time machine = yes. Default: aapl model = Xserve
  • bind interfaces only (G) — only bind to the interfaces given with interfaces. Default: bind interfaces only = no
  • browseable (S) — the share shows up in a net view and in the browse list. Default: browseable = yes
  • comment (S) — the description of the share, as seen in a net view and and in the browse list. Default: comment =
  • create mask (S) — octal bitmask that gets bitwise ANDed with DOS-to-UNIX-mapped permissions when creating a file. Default: create mask = 0744
  • crossmnt (S) — allow path lookup to cross a mountpoint to the root of a different filesystem. Default: crossmnt = yes
  • deadtime (G) — the number of minutes of inactivity before a connection is considered dead, and is then terminated. it will not be terminated if it has any open files. with deadtime = 0, no connection is considered dead due to inactivity. Default: deadtime = 0
  • directory mask (S) — octal bitmask that gets bitwise ANDed with DOS-to-UNIX-mapped permissions when creating a directory. Default: directory mask = 0755
  • durable handles (G) — can grant SMB2 durable file handles on a share. Default: durable handles = no
  • follow symlinks (S) — setting this parameter allows any file or directory that is a symbolic link to be followed. but ngl, this option does not allow following a symbolic link to /etc/passwd in their home directory. so don't get any ideas. 🙅‍♀️ Default: follow symlinks = no
  • force create mode (S) — octal bitmask that gets bitwise ORed after the bitmask given with create mask is applied. Default: force create mode = 0000
  • force directory mode (S) — octal bitmask that gets bitwise ORed after the bitmask given with directory mask is applied. Default: force directory mode = 0000
  • force group (S) — the system group that all users connected to the share are mapped to. Default: force group =
  • force user (S) — the system user that all users connected to the share are mapped to. with force group = , the primary group of the system user is the respective system group. Default: force user =
  • guest account (G) — the user that does not require a password when connecting to any share with guest ok = yes. when connecting to such a share with the user left empty, this parameter decides which system user to map to. Default: guest account = nobody
  • guest account (S) — the user that does not require a password when connecting to the share with guest ok = yes given. Default: guest account =
  • guest ok (S) — allow passwordless connections to the share as the user given with guest account, and with the user left empty. Default: guest ok = no
  • hide dot files (S) — files starting with a dot appear as hidden files. Default: hide dot files = yes
  • hide unreadable (S) — directory entries are hidden unless the connected user has read data, read extended attributes, and read attributes access. Default: hide unreadable = no
  • inherit owner (S) — ownership for new files and directories is controlled by the ownership of the parent directory. Default: inherit owner = no
  • interfaces (G) — list of the interfaces that are listened to, with bind interfaces only = yes given. Default: interfaces =
  • invalid users (S) — list of the users that are disallowed from connecting to the share. a user being in the list has precedence over that user being in valid users. with invalid users = , no user is disallowed. Default: invalid users =
  • ipc timeout (G) — the number of seconds user space has to reply to a heartbeat frame. if that's exceeded, all sessions and TCP connections will be closed. with ipc timeout = 0, user space can reply whenever. Default: ipc timeout = 0
  • kerberos keytab file (G) — the path of the keytab file for the service principal. if no value is given, it's the default keytab resolved with krb5_kt_default(3). Default: kerberos keytab file =
  • kerberos service name (G) — the service principal name. if no value is given, it's cifs/ followed by the FQDN resolved with getaddrinfo(3). Default: kerberos service name =
  • kerberos support (G) — support for Kerberos 5 authentication. for this parameter to actually take effect, ksmbd.mountd must be built against Kerberos 5. (iykyk 🔥) Default: kerberos support = no
  • map to guest (G) — when to map a user to the user given with guest account. with map to guest = bad user, it maps when the user does not exist. Default: map to guest = never
  • max active sessions (G) — maximum number of simultaneous sessions to all shares. Default: max active sessions = 1024
  • max connections (G) — maximum number of simultaneous connections to the server. with max connections = 0, the value will be set to the maximum allowed number of 65536. number suffixes are allowed. Default: max connections = 128
  • max connections (S) — maximum number of simultaneous connections to the share. with max connections = 0, the value will be set to the maximum allowed number of 65536. number suffixes are allowed. Default: max connections = 128
  • max ip connections (G) — maximum number of connections to the server per IP address. with max ip connections = 0, the value will be set to the maximum allowed number of 65536. number suffixes are allowed. Default: max ip connections = 8
  • max open files (G) — maximum number of simultaneous open files for a client. Default: max open files = 10000
  • netbios name (G) — the NetBIOS name. Default: netbios name = KSMBD SERVER
  • oplocks (S) — issue oplocks to file open requests on the share. Default: oplocks = yes
  • path (S) — the path of the directory that users connected to the share are given access to. Default: path =
  • read list (S) — list of the users that are allowed read-only access to the share. a user being in the list has precedence over read only = no or that user being in write list. Default: read list =
  • read only (S) — users are allowed read-only access to the share. with read only = no, the effect is the same as with writable = yes. this parameter has precedence over writable, writeable, and write ok. Default: read only = ; yes
  • restrict anonymous (G) — how to restrict connections to any share as the user given with guest account. with restrict anonymous = 1 or restrict anonymous = 2, it disallows connections to the IPC$ share and any share that gives guest ok = no. Default: restrict anonymous = 0

and that, bestie, is only part one 🌈 the parameter list is nowhere near done, so don't you dare close the tab — keep scrolling, we're so back 💅✨

Alright, the parameter parade continues — headphones on, no skipping, we're doing every single one of these 💅

  • root directory (G) — the path of the directory that gets prepended to the path of every share. It's giving chroot(2) but make it SMB. Lowkey a big deal. Default: root directory =
  • server max protocol (G) — the maximum protocol version we're willing to speak. Default: server max protocol = SMB3_11
  • server min protocol (G) — the minimum protocol version we'll tolerate. Anything older gets ghosted. Default: server min protocol = SMB2_10
  • server multi channel support (G) — whether SMB3 multi-channel is supported. Default: server multi channel support = no
  • server signing (G) — is the client allowed or required to use SMB2 signing? With server signing = disabled or server signing = auto, SMB2 signing is allowed if it's requested by the client. With server signing = mandatory, SMB2 signing is required, periodt. Default: server signing = auto
  • server string (G) — the string that shows up in browse lists right next to the machine name. Your little name tag ✨ Default: server string = SMB SERVER
  • share:fake_fscaps (G) — a decimal bitmask that gets bitwise ORed with the filesystem capability flags so we can fake them. With share:fake_fscaps = 64, the FILE_SUPPORTS_SPARSE_FILES flag is set. Default: share:fake_fscaps = 64
  • smb2 leases (G) — negotiate SMB2 leases on file open requests. Default: smb2 leases = yes
  • smb2 max credits (G) — the maximum number of outstanding simultaneous SMB2 operations. Number suffixes are allowed. Default: smb2 max credits = 8192
  • smb2 max read (G) — the maximum length that may be used in an SMB2 READ request sent by a client. Number suffixes are allowed. Default: smb2 max read = 4MB
  • smb2 max trans (G) — the maximum buffer size a client may use in a sent SET_INFO request, or in a received QUERY_INFO, QUERY_DIRECTORY, or CHANGE_NOTIFY response. Number suffixes are allowed. Default: smb2 max trans = 1MB
  • smb2 max write (G) — the maximum length that may be used in an SMB2 WRITE request sent by a client. Number suffixes are allowed. Default: smb2 max write = 4MB
  • smb3 encryption (G) — is the client disallowed, allowed, or required to use SMB3 encryption? With smb3 encryption = disabled, SMB3 encryption is disallowed even if the client asks for it. With smb3 encryption = auto, it's allowed if the client requests it. With smb3 encryption = mandatory, encryption is required — meaning clients that don't support encryption get denied access to all shares 😭 no exceptions. Default: smb3 encryption = auto
  • smbd max io size (G) — the maximum read/write size of SMB-Direct. Number suffixes are allowed. Default: smbd max io size = 8MB
  • store dos attributes (S) — store DOS attributes using xattr, and then use them in the DOS-to-UNIX-mapping of permissions. Default: store dos attributes = yes
  • tcp port (G) — the TCP port we're listening to. Default: tcp port = 445
  • time machine (S) — advertise the share as an Apple Time Machine backup target via the SMB2 AAPL extension. macOS stores Apple metadata such as com.apple.FinderInfo as named data streams, so the share also needs vfs objects = streams_xattr for it to work correctly — this option does not enable that on its own. macOS also requires the global durable handles = yes and smb2 leases = yes to reconnect a Time Machine destination after a network interruption; without them, macOS refuses to configure the backup destination's reconnect settings. Default: time machine = no
  • valid users (S) — the list of users that are allowed to connect to the share. With valid users = , all users are allowed. Default: valid users =
  • veto files (S) — names of files and directories that get made invisible and inaccessible. Names go between forward slashes (/), e.g. veto files = /foo/bar/ makes files and directories named foo and bar invisible and inaccessible. An asterisk (*) matches any number of characters and a question mark (?) matches a single character. Default: veto files =
  • vfs objects (S) — the list of VFS modules to overload I/O operations with. The available VFS modules are acl_xattr and streams_xattr. Default: vfs objects =
  • workgroup (G) — the workgroup the server will appear to be in when clients query it. Default: workgroup = WORKGROUP
  • writable (S) — users get read-write access to the share. With writable = yes, the effect is the same as read only = no. This parameter has precedence over writeable, and write ok. Default: writable =
  • writeable (S) — same effect as writable. This parameter has precedence over write ok. Default: writeable =
  • write list (S) — the list of users that are allowed read-write access to the share. If a user is in this list, that has precedence over read only = yes. Default: write list =
  • write ok (S) — same effect as writable. Default: write ok =

Copyright © 2015-2022 ksmbd-tools contributors. License GPLv2: GNU GPL version 2 https://www.gnu.org/licenses/old-licenses/gpl-2.0.en.html. 🫶

This is free software: you are free to change and redistribute it. There is NO WARRANTY, to the extent permitted by law. (Like, bestie, fr fr, no take-backs.) 💀

🐛 REPORTING BUGS 🐛

Found a bug? Not the vibe, but also very valid of you. For bug reports, use the issue tracker at https://github.com/cifsd-team/ksmbd-tools/issues 🙈 Please actually report it instead of just suffering in silence, the maintainers wanna know.

👀 SEE ALSO 👀

🛠️ Utilities

That's the whole page, bestie — you made it, and honestly? You ate. 🍓

This one's from ksmbd-tools 3.5.7, and the page itself is KSMBD.CONF(5). Go configure something iconic, and remember: smb3 encryption = mandatory means mandatory. Mwah 💅✨

📦 where this page comes from