Samba Client

Summary

The project uses NFS by default but for Windows and MacOS it maybe preferred to have workstations connect using Samba.

Samba provides authentication and is widely supported.

Samba + Shaman Overlay

Flamenco uses Shaman file overlay which depends on symbolic links to reduce the amount of copying of project files and assets for Flamenco Jobs. Samba support for symlinks is not in-built but there are workarounds that most newer Samba clients support. This symlink support is documented in the Samba Server setup at documentation / technical / installation / samba.

Example

In this guide, the Samba user is called flamenco_smb_user and the Samba file store is intentionally explicitly called flamenco_shared_storage. We are also going to expect the Flamenco shared-storage to be mounted on a Windows client at F:\ so that Jobs can access the two-way variable path for Windows platform as F:\flamenco\.

We are assuming the two-variable shared-storage paths are correct in this example.

In summary…

Entity	Value
Samba username	flamenco_smb_user
Samba Share Name	flamenco_shared_storage
SAMBA-SERVER-IP	Network IP address of server

These are the example mount points…

Platform/Machine	Mount Point
Windows Client Remote Drive	F:\flamenco
MacOS Client Volume	/private/nfs/flamenco
Linux Client Mount	/media/shared/flamenco

Note, on this page, the SAMBA-SERVER-IP is flamenco.cluster.home in this project however it may not be hosted by the Gateway Device and could be its own appliance.

Server Setup

Please see documentation / technical / installation / samba for Samba Server setup on Linux host. Note, k8s cluster uses NFS, not Samba.

The Samba Server is setup in parallel to allow easier, secure access from Windows and MacOS workstations.

Flamenco Shared Storage

The NFS mounts may differ due to operation system (platform) or however your NAS/NFS environment is setup.

Flamenco has a mechanism to provide cross-platform conversion of NFS paths using Flamenco Two-Way Variables.

On Windows, MacOS and Linux it is likely the NFS mount point is different. Flamenco “Two-Way” Environment variables allow you to specify mapping and are useful in mapping NFS mount points across different platforms.

This has pre-configured Two-Way variable shared_storage that defines platform defined in the flamenco_manager.yaml that is co-located with the Flamenco Manager in the cluster.

The platform keyword is reserved and can be one of windows, linux or darwin.

  shared_storage:
    is_twoway: true
    values:
    - platform: linux
      value: /media/shared/flamenco
    - platform: windows
      value: F:\flamenco
    - platform: darwin
      value: /private/nfs/flamenco/

The Cluster Worker nodes use the linux Mount Point. (details)

See note on absolute bake cache paths.

Windows Client

In Windows, the typical way of mounting a Samba file share is to search for the network server and then “Map Network Drive”.

Depending on your setup, your Windows usernames and passwords may match those of the Samba server. If not, you can select “Login with different credentials”.

Once mounted as a Windows Drive (eg: F:) it is important to check access and permissions work as expected. Clients will need read-write access to the shared storage.

Specifically, if you navigate into the Flamenco Jobs sub folders you should see .blend files under each Job (assuming Jobs have been submitted). These will appear as files, with date and size as shown in the screenshot below.

When a Flamenco Worker is given a Flamenco Task from a Flamenco Job, it is this ‘copy’ of the Blender project file it will look to open.

If these files do not appear then there is a problem with Samba symlink support and you should consult the Troubleshooting section at the bottom of this page.

Windows Flamenco Worker opening a Blender project file as part of a Job Task.

_

Linux Client

There are two popular ways of mounting a Samba share:

GUI driven via the File Browser (eg: Nautlius) Network
Command Line.

The GUI based File Browser approach successfully mounts the Samba share but without symlink support. At the bottom of this page is an example of what this looks like with strange missing metadata and permission errors.

If you see a failure, there are more details looking in the Flamenco Console and opening the full task log for a Worker.

Checking Samba Servers

smbclient -L //SAMBA-SERVER-IP -U flamenco_smb_user
Password for [WORKGROUP\flamenco_smb_user]:

Sharename                  Type      Comment
---------                  ----      -------
print$                     Disk      Printer Drivers
flamenco_shared_storage    Disk      
IPC$                       IPC       IPC Service (Samba 4.13.13-Debian)
flamenco_smb_user          Disk      Home

Mount from Command Line

To mount Linux Samba file share using command line…

sudo mount -t cifs //flamenco.cluster.home/flamenco_shared_storage /media/smb/flamenco -o username=flamenco_smb_user,vers=3.0,uid=1001,gid=1001,soft,rsize=8192,wsize=8192,mfsymlinks

In the above example, the uid, gid = 1001 matches that of the flamenco_smb_user on the Linux host running the Samba server.

The flamenco_smb_user should also be added to the correct group permissions, in this case, nogroup. On the Samba server you want to ensure the Samba user is part of the group.

sudo adduser -a -U flamenco_smb_user -g nogroup

Troubleshooting

mfsymlink option

Samba doesn’t natively support symbolic links. There is a workaround that can be activated when the samba share is mounted. The option is mfsymlinks which is the Minshall and French Samba Extension.

This allows the client to create fake symlinks that look like symlinks from the clients perspective. (Flamenco currently doesn’t expect the Clients to create symlinks. The Flamenco Clients read symlinks to Blender files).

Corrupt Metadata

Depending on how the Samba share is mounted you may see garbage values for a symlink files date and size and be inaccessible. This is usually due to the symlinks being broken, or the way Samba share was mounted by the client.

For example, using the Ubuntu Nautilus File Browser to connect to a Network server, the underlying fuse mount gives results like the following…

File Browser

Command line

Mounting the same Samba share using cifs mount (as shown below) will provide correct permissions and file metadata.

Missing (Symlink) Files

Flamenco uses Shaman which relies on use of symlinks to organise Job files without having to create multiple copies.

If Samba isn’t configured to allow client to access symlinks then the Job will point to a Blender project file (and other files) that do not exist from the Clients perspective.

(The other main cause of this error is misconfigured two-way shared-storage variable in Flamenco Manager.)

Example error of Flamenco Worker unable to find Blender project file when it picks up a Job. In this example, lego-sakura-camera-spin.flamenco.blend is a symlink to an actual Blender project file.

2023-06-02T13:38:11Z task changed status queued -> active
going to run: D:\\Apps\\Blender\\blender.exe ["-b" "-y" "F:\\flamenco\\jobs\\lego-sakura-camera-spin-j982\\lego-sakura-camera-spin.flamenco.blend" "--render-output" "F:\\flamenco/output/lego-sakura-camera-spin/2023-05-26_155113/######" "--render-format" "PNG" "--render-frame" "30"]
pid=10356 > Blender 3.5.1 (hash e1ccd9d4a1d3 built 2023-04-24 23:56:35)
pid=10356 > Error: Cannot read file 'F:\flamenco\jobs\lego-sakura-camera-spin-j982\lego-sakura-camera-spin.flamenco.blend': No such file or directory
pid=10356 > 
pid=10356 > Blender quit