.. SPDX-FileCopyrightText: 2025 Univention GmbH .. .. SPDX-License-Identifier: AGPL-3.0-only .. _nubus-domain-shares: ************* Shares module ************* Nubus offers the *Shares* management module to manage file shares on Nubus for UCS through Samba and NFS. The *Shares* management module appears in the installations for Kubernetes and UCS. However, administrators mostly use it in the context of Nubus for UCS with its share management capabilities. You find the *Shares* management module in the *Domain* category in the *Management UI*. To add a share, click :guilabel:`Add` in the *Shares* management module. :numref:`nubus-domain-shares-figure` shows the *General* tab with the *General settings* for a file share. The *Shares* management module has the following tabs: * :ref:`nubus-domain-shares-general-tab` * :ref:`nubus-domain-shares-nfs-tab` * :ref:`nubus-domain-shares-samba-tab` * :ref:`nubus-domain-shares-options-tab` This section provides a reference for the fields used in the *Shares* management module. .. _nubus-domain-shares-figure: .. figure:: /images/project-share.* :alt: General settings for file shares in the Shares management module :width: 871px General settings for file shares in the *Shares* management module .. dropdown:: Packaged service — only available for Nubus for UCS :color: info :icon: package-dependents :open: A packaged service using information from the *Shares* management module is only available for Nubus for UCS. You can manage the information in the Kubernetes deployment, as well. Nubus for UCS uses :program:`NFS` and :program:`Samba` for providing file shares. When you add, edit, or delete a share, Nubus directly changes the :file:`/etc/exports` configuration file for NFS and the Samba configuration, depending on the resulting effects of the change. .. _nubus-domain-shares-general-tab: General tab - Shares management ------------------------------- This section provides a reference for the *General* tab in the *Shares* management module. .. _nubus-domain-shares-general-tab-name-field: Name The name of the share. It can include letters, digits, periods, or blank spaces. It must start and end with a letter or a digit. Comment A free comment for this share, for example describing its purpose. The file browser in Microsoft Windows shows the comment of the share. Host The UCS system where the share locates. You can select any of the *UCS Directory Nodes* and *Managed Nodes* listed in the directory service for the domain and that are part of the DNS forward lookup zone. Directory The absolute path of the directory on the host that you want to use for the share. Don't use question marks or special characters in the absolute path, such as spaces. If the directory doesn't exist, the Nubus for UCS system selected as host automatically creates it. Nubus doesn't allow creating shares or move files to the following directories: * :file:`/proc` * :file:`/tmp` * :file:`/root` * :file:`/dev` * :file:`/sys` .. dropdown:: Packaged service — only available for Nubus for UCS :color: info :icon: package-dependents :open: If the :external+uv-ucs-operation:envvar:`listener/shares/rename` UCR variable has the value ``yes``, Nubus for UCS moves the content of the existing directory if you modify the absolute path for the share directory. Directory owner of the share's root The user to whom the root directory of the share belongs, see :external+uv-ucs-manual:ref:`shares-permissions`. Directory owner group of the share's root The user group to whom the root directory of the share belongs, see :external+uv-ucs-manual:ref:`shares-permissions`. Permissions for the share's root The read, write, and access permissions for the share's root directory, see :external+uv-ucs-manual:ref:`shares-permissions`. .. seealso:: .. TODO: Replace with a link to the role concept in the UCS Operation Manual, once it's available. :external+uv-architecture:ref:`concept-role` in :cite:t:`uv-architecture` for information about *Directory Nodes* and *Managed Node* as part of the role concept in Nubus for UCS. .. _nubus-domain-shares-nfs-tab: NFS tab - Shares management --------------------------- The *NFS* tab in the *Share* management module has the following fields. NFS write access If activated, grants write access to the share. Otherwise, the share is in read-only mode. Subtree checking If activated, the NFS server ensures that an accessed file in the share is in fact in that subtree. The NFS server runs the verification upon every access to the file and passes the path information to client for the verification. If activated, the function may cause problems in situations, where a file rename happens while a client has opened the file. Modify user ID for root user (root squashing) NFS identifies a user through the user ID. To prevent a local ``root`` user from working with ``root`` permissions on other shares, you can redirect ``root`` access. If this option is active, the NFS server runs access operations as user ``nobody``. .. important:: The local group ``staff`` owns privileges that come close to ``root`` permissions. By default, the user group ``staff`` has no members and is empty. However, the redirection mechanism doesn't consider this group. Keep this behavior in mind when you add users to the user group ``staff``. NFS synchronization Defines the synchronization mode for the share. ``synchronous`` Use the mode *synchronous* to write data directly to the underlying storage device. ``asynchronous`` Use the mode *asynchronous* for the opposite behavior to not write data directly to the underlying storage device. The mode can improve performance, but also involves the risk of data loss if the server shuts down incorrectly. Only allow access for these hosts, IP addresses or networks By default, all hosts have permission to access a share. Add hostnames or IP addresses to grant access permission to those hosts. For example, you can restrict access to a share containing mail data to the mail server of the domain. Custom NFS share settings Apart from the properties before, *Custom NFS share settings* allows defining further arbitrary NFS settings for the share. Nubus doesn't validate for duplicate entries. You find a list of available options in the man pages through :command:`man 5 exports`, or online at `exports(5) `_. .. caution:: The definition of extended NFS settings is only necessary in special use cases. You need to thoroughly validate the options, because they may have security-relevant effects. .. _nubus-domain-shares-samba-tab: Samba tab - Shares management ----------------------------- The *Samba* tab in the *Share* management module has the following sections: * :ref:`nubus-domain-shares-samba-tab-samba` * :ref:`nubus-domain-shares-samba-tab-samba-permissions` * :ref:`nubus-domain-shares-samba-tab-samba-extended-permissions` * :ref:`nubus-domain-shares-samba-tab-samba-options` * :ref:`nubus-domain-shares-samba-tab-samba-custom-settings` .. _nubus-domain-shares-samba-tab-samba: Section Samba - Shares management ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Windows name The NetBIOS name of the share. The share appears with this name in the network environment on Microsoft Windows computers. When you add a directory share, the *Share* management module adopts the name from the :ref:`nubus-domain-shares-general-tab-name-field` field on the *General* tab as default value. Show share in Windows network environment Specifies whether the share shows up in the network environment on Microsoft Windows clients. Allow anonymous read-only access with a guest user Permits access to the share without a password. Every access happens with the user rights of the common guest user ``nobody``. Export share as MSDFS root For description of this option, see :external+uv-ucs-manual:ref:`shares-msdfs`. Hide unreadable files/directories If activated, the share hides all files that aren't readable for the user, because of their file permissions. .. _nubus-domain-shares-samba-tab-samba-permissions: Section Samba permissions - Shares management ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Users with write access may modify permissions If activated, all users with write access to a file can change its permissions, access control list (ACL) entries, and ownership permissions. For more information, see :external+uv-ucs-manual:ref:`shares-permissions`. .. _nubus-domain-shares-samba-tab-samba-permissions-force-user-field: Force user The share uses this username, its permission and primary user group to perform all the file operations of the accessing user. The share uses the username only after the user established a connection to the Samba share with their real username and password. The use case for a forced user is for using data in a shared way. .. important:: However, improper use can raise security problems. Force group The share uses this user group as primary user group for all users connecting to it. Thereby, the permissions of this group automatically apply as the group permissions of all these users. A user group registered here has a higher priority than a user group assigned as the primary user group of a user through the :ref:`nubus-domain-shares-samba-tab-samba-permissions-force-user-field` field. If you prefix the user group name with a ``+``, Samba assigns the user group solely as primary user group to users who are already member of this group. All other users retain their primary user group. .. _nubus-domain-shares-samba-tab-samba-permissions-valid-groups-field: Valid users or groups Names of users or user groups with authorization to access the Samba share. Samba denies access to the share for all other users. If the field is empty, all users may access the share, if necessary after providing their password. This option is for securing access to a share at file server level beyond the file permissions. Separate the user or user group entries with spaces. Use the special characters ``@``, ``+``, and ``&`` in connection with the user group name to assign certain permissions to the users in the user group for accessing the Samba share. .. _nubus-domain-shares-samba-tab-samba-permissions-valid-groups-field-at: ``@`` Samba interprets a name beginning with the character ``@`` as a NIS net-group. If Samba doesn't find a NIS net-group with this name, it considers the name as a Unix group. .. _nubus-domain-shares-samba-tab-samba-permissions-valid-groups-field-plus: ``+`` Samba considers a name beginning with the character ``+`` exclusively as a Unix group. .. _nubus-domain-shares-samba-tab-samba-permissions-valid-groups-field-ampersand: ``&`` Samba considers a name beginning with the character ``&`` exclusively as a NIS net-group. .. _nubus-domain-shares-samba-tab-samba-permissions-valid-groups-field-plus-ampersand: ``+&`` Samba interprets a name beginning with the characters ``+&`` as a Unix group first. If Samba doesn't find a Unix group with this name, it considers the name as a NIS net-group. .. _nubus-domain-shares-samba-tab-samba-permissions-valid-groups-field-ampersand-plus: ``&+`` The characters ``&+`` at the beginning of the name correspond to the behavior for the character :ref:`nubus-domain-shares-samba-tab-samba-permissions-valid-groups-field-at`. Invalid users or groups The users or groups listed here can't access the Samba share. The syntax is identical to :ref:`nubus-domain-shares-samba-tab-samba-permissions-valid-groups-field`. Samba denies access to a user or a user group, if both options *Valid users or groups* and *Invalid users or groups* list them. Restrict read access to these users/groups Only the users and user groups listed here have read permission for the share. Allow Samba write access If activated, users can write to the share if they access it through Samba. If deactivated, users can still have write access if listed in :ref:`nubus-domain-shares-samba-tab-samba-permissions-restrict-write-access-field`. .. _nubus-domain-shares-samba-tab-samba-permissions-restrict-write-access-field: Restrict write access to these users/groups Only the users and user groups listed here have write permission for the share. .. _nubus-domain-shares-samba-tab-samba-permissions-allowed-hosts-field: Allowed hosts/networks Names of computers with authorization to access the Samba share. Samba denies access for all other computers. In addition to computer names, it's also possible to specify IP or network addresses, for example the network address ``192.0.2.0/255.255.255.0``. Denied hosts/networks The opposite to :ref:`nubus-domain-shares-samba-tab-samba-permissions-allowed-hosts-field`. If a computer appears in both lists, Samba permits access to the Samba share for the computer. Inherit ACLs If activated, each file created in the share inherits the access control list (ACL) of the directory of the share. Create files/directories with the owner of the parent directory If activated, Samba assign the owner of the parent directory to the created file instead of the user who created the file. Create files/directories with permissions of the parent directory If activated, Samba automatically assigns the Unix permissions of the parent directory to each file or directory that users create in the share. If users create a file on a Samba server through their Microsoft Windows client, Samba assigns file permission in the following order: #. Samba translates only the DOS file permissions into Unix file permissions. #. Samba filters the file permissions through the *File mode*. It only preserves Unix permissions marked in *File mode*. Samba removes permissions not marked in *File mode*. Therefore, to preserve permissions, you need to set them as Unix permissions and in *File mode*. #. Samba adds the permissions under *Force file mode*. As a result, the file has all the permissions that Samba set after step 2 or under *Force file mode*. This means, Samba sets permissions marked under *Force file mode* in any case. Accordingly, Samba initially assigns the same permissions to a newly created directory that are set both as Unix permissions and in *Directory mode* at the same time. After that, Samba assigns the permissions marked under *Force directory mode*. .. _nubus-domain-shares-samba-tab-samba-extended-permissions: Section Samba extended permissions - Shares management ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ File mode Defines the permissions that Samba assigns when users create a file in the share through Microsoft Windows. Directory mode Defines the permissions that Samba assigns when users create a directory in the share through Microsoft Windows. Force file mode Defines the permissions that Samba assigns in any case when users create a file. For this setting it doesn't matter if users work under Microsoft Windows or not. Force directory mode Defines the permissions that Samba assigns in any case when users create a directory. For this setting it doesn't matter if users work under Microsoft Windows or not. .. _nubus-domain-shares-samba-tab-samba-options: Section Samba options - Shares management ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ VFS Objects Samba uses Virtual File System (VFS) modules to perform actions before users access a share's file system. Examples * A virus scanner that stores every infected file accessed in the share in quarantine. * A server-side implementation of a recycle bin for deleting files. Hidden files Microsoft Windows can access files and directories, but they can also not be visible. Such files and directories have the DOS attribute *hidden* assigned. Ensure the following constraints for this setting: * The setting interprets names of files and directories case-sensitive. * Separate each entry by a slash (``/``). You can't use the slash in path names. * Names may include spaces and the wildcards ``*`` and ``?``. Samba hides all files and directories in the share that match the name. For example, ``/.*/test/`` hides all files and directories with names beginning with a period ``.``, or with names ``test``. .. note:: Entries in the *Hidden files* field affect Samba's performance because Samba validates all files and directories in a share according to the active filters each time it shows files. Postexec script A script or command that the server with the share runs after the connection to the share closed. Preexec script A script or command that the server with the share runs every time a client establishes a connection to the share. .. _nubus-domain-shares-samba-tab-samba-custom-settings: Section Samba custom settings - Shares management ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Option name in :file:`smb.conf` and its value You can define further arbitrary Samba settings for a share apart from the properties that you can configure as standard features in a Samba share. You find a list of available options in the man page :command:`man 5 smb.conf` or online at `smb.conf(5) `. The *Key* field contains the option and the *Value* contains the value for the option. Nubus doesn't validate for duplicate entries. .. caution:: You only need to define extended Samba settings in special use cases. Validate the options thoroughly, because they may have security-relevant effects. .. _nubus-domain-shares-options-tab: Options tab - Shares management ------------------------------- Export for Samba clients Defines if the Nubus exports the share for Samba clients, such as Microsoft Windows. Export for NFS clients Defines if the Nubus exports the share for NFS clients.