Getting started

Muster is a suite of applications specifically designed to manage complex and multi-platform render farms. In the digital content creation industry, the term render farm is used to describe a set of computers fully or partially dedicated to the creation of digital images. This process is commonly called “rendering” and the resulting images “rendered images”.

The rendering is typically the last stage in 3D animation and 2D compositing software workflow and is a CPU intensive task; the time required for the generation of a single image can range from minutes to hours. In video or motion picture productions where contents are made by several minutes of digital effects, several days may be required to complete the production phase.

Spreading the render of image sequences on a set of computers dedicated to this task, helps reducing rendering times but tracking their status and managing errors can be really complicated. It’s here that comes Muster. Muster is a client/server suite of applications that provides production’s supervisor the right tools to manage their render farm made by hundreds or a bunch of computers.

Muster relies on a client/server architecture. A unique centralised server takes care of controlling several client modules. There are two client modules groups:

  • The Render Client service installed on every computer in the render farm allows Muster to manage the computer for you. It basically receives commands from the Dispatcher service that start and stop the Rendering process on behalf of it
  • The management and notification modules, that connect using socket connections to the Dispatcher service and allows monitoring and management on Muster itself.

The following figure shows a typical setup scenario:

This is a complete list of the modules available in a full Muster installation:

  • Dispatcher service
  • Render client service
  • Console
  • Notificator applet
  • Services control applet
  • Screen saver activator (available on Windows only)
  • Connectors plugins

Dispatcher Service: The Dispatcher service is the most important component of the whole suite. It manages connections with every client, retains a job queue, accepts commands from external client applications and sends notifications to the users. It may run in the background as a Windows Service or as UNIX daemon.

Render client Service: This is a service that must be installed on each render farm node. It retains a connection with the dispatcher service, waits for server commands and starts the scheduled render jobs. It may run in the background as a Windows Service or as a UNIX daemon.

Console: The Muster console is a complete graphical front-end to the Dispatcher service. It’s basically the Muster most used module. It allows the user to schedule jobs, change their order, manage and configure connected render clients and configure the dispatcher service.

Notificator applet: This is a very simple component that gathers notifications from the Dispatcher when important events are triggered including jobs completions and errors. It runs in the background as a task bar applet.

Services control applet: This applet let you interactively start and stop the installed services as well as configure them. It also lets you send controlling messages to the local render client service.

Screen saver activator: This is a screen saver that wraps another screen saver on the system by letting you start and stop the render client on the local workstation when the screen saver changes status.

Connectors: Those are plug-ins for external software allowing job submissions from within the software's GUI. At present the connector it is available for Maya, Cinema 4D, Nuke, 3D Studio Max and After Effects.

An important concept to take into account at the beginning of your installation is choosing the right machine to dedicate to the dispatching process. Before going further, we’ll take a look at the roles of the Dispatcher service and the way it interacts with your network, distributed file systems and the hosts in your render farm.

As seen before, the main role of the Dispatcher service is retaining a pool of persistent connections with your render farm hosts. The connections are established using the TCP/IP protocol. The decision of using TCP involves several pros and cons. This guarantees messaging ordering and consistency but requires a higher network overhead than UDP. This configuration requires a clever pre-setup brainstorming and in some cases, changes to the network routing and configurations.

Before going further, we must clarify an important concept: The data flow sent between the Dispatcher service and the Render client service is composed by synchronization and management messages. The files used by your jobs are not transferred through this connection.

How content composed by scene files, textures and renderings is transferred across hosts? Files are read and written using the standard network shares. This means that a machine that has enough disk space must be dedicated for this task. Depending on your network configurations and your bandwidth, even we suggest to use a Network Area Storage, you may use the same machine running the Dispatcher service.

Of course choosing the OS, disk configurations and physical layouts depends on personal preferences and budget limits. The flexibility of this system allows further expansions and rearrangements even during productions phases. Just keep in mind those important key concepts:

  • If you choose a Windows machine to host files, consider that each host accessing files on a share uses a new connection to the file server. Microsoft operating systems that are not part of the SERVER family, allow only 10 concurrent connections to a shared folder.
  • When working on a mixed platforms environment, you should be sure that the shared file system is exportable using a network protocol supported on every system.
  • If available, switch your network to Gigabit or Fibre Channel technology

Muster comes with a standard Windows Installer package. By clicking the .msi file you got from the web, you start the installer as shown below.

In the first you’re asked to specify the final destination for Muster files. This may be left untouched unless you need to install it in a different location.

The next steps asks you to select which Muster components will be installed. Select the option that best suits your needs.

Muster is able to run as a system service. A system service is an executable application that runs into the background. If you choose to start Muster as a system service, you won’t need later to logon on the machine and start the software manually, it will be up and running as soon as your boot sequence reaches the login window. Having the software installed as system service requires an additional step later in the setup sequence. Considering it won’t be bound to any logged user, a service requires its own user setting in order to access the network and be recognized by servers. Installing Muster as a system service is more complicated compared to the standard installation, but allows you to have independent modules.

If services is your choice, this is the window you’ll get during the installation process to configure the user assigned to the Muster services. You can either configure a user now or choose Use Local System Account. This will install the services with a default user. The setup will continue, but this user won’t be probably able to access the network content in most cases, so you’ll need to configure the user later as explained in the last part of the setup section of this manual.

If you choose to install the render client service, the installer will prompt you for changes in the default configuration. Unless you’ve a deep knowledge of network topics, the only field you should change is Dispatcher IP address or host name. This is where you need to enter the IP Address or the host name of the host where you installed the Dispatcher service. If you’re installing both the Dispatcher and the Client, just type the local system name in the IP Address field.

If you choose to install the dispatcher service, the installer will prompt you for changes in the default configuration. Unless you’ve a deep knowledge of network topics, you should not change the network ports settings. In this window, you can also choose the way the Dispatcher stores its data. If you want to store the data in an external database, change the settings according, otherwise, leave them unchanged.

If you choose to install the dispatcher service you can track down the HOST ID prompted by the installer from this window, you may need it later to request the license through our website.
Pressing the “next” button, the installer will start the installation process. It will copy the files in your file system, starts the services if required, and then completes. If you did not configure a user for the services, read carefully the next section about services users rights.

Defining Windows Services user rights on your network

A key concept of Muster is the understanding of how it works on the network and the steps you’ve to perform to avoid common pitfalls related to network access from the services.

When you work on a shared folder, the process that requests a file must supply valid credentials to the file server. ”Credentials” means at least a valid username and password pair that’s valid on both side of the communication (the client running the process and the server hosting the files).

When you access files on your network, the entire process is hidden to the user. The client sends the login and password pair of the user running the current process to the server.

To gain full access, a user should be successfully authenticated by the server (this means that he should be available on the server’s user list and its password should match with the one stored on the server).
In case of failure, depending on network policies, the system could pop up a dialog that asks for the user password and retries the connection.

The Muster Render Client Service must be able to access the network resources but its behaviour is a bit more complex. Windows services are basically software modules that run independently from the logged user.
The next figure shows the services installed by Muster. Depending on installed features, you will find at least one of the services listed below:

Services run even if no user is currently logged on the machine. For this reason, they have a dedicated configuration window where is possible to specify which user the service have to impersonate.
When a service impersonates a particular user, it runs as it was started from the user desktop and supply user credential to the various file servers.
The next picture shows the services properties window where you can configure the service properties and the service log on properties:

During the setup process, Muster installer will prompt for the username and password used to install the services or alternatively you can select to use the local system account. Even this account will let you to start the services, it won’t give any rights to the services to access the external network. That’s why you may need to manually create a dedicated account.

There are two scenarios: creating the user on a Windows Domain or creating it on a Windows Workgroup. You should refer to your network Administrator to obtain information about your current setup.

This is a description of the basic differences when setting up Muster on Domains or Workgroups:

  • Workgroup based networks: A Workgroup is basically a group of Windows computers that must share the same user accounts to allow access through each one. This means that there’s no server hosting a common list of users and their relative permissions. When a user tries to access a folder on another host, the authentication function simply checks that the user exists on the remote machines and that its credential matches. For this reason, the Muster installer, when detects a workgroup, creates the same user account of every host with same credentials and assign it to the Administrator group of the machine. In this way, each host can authenticate the Muster account and allow read/write access to the shared folders.
  • Domain based networks: The situation on a domain network is a bit different and much easier. A Domain is a group of computers that shares a server that hosts information about user accounts and permissions (the Primary Domain Controller). As you can image, setting up Muster in this configuration requires to just create the user on the Domain Controller. Automatically all the machines will recognize the user and will give access to it. The only important thing to be aware is that each machine must recognize the user as a member of the local Administrator group. This is different from the Domain Administrator group. If you decide to customize user creation or the Muster installer is unable to perform the setup for some domain policy, you should do this setup manually on each machine even if you assign the user to the Domain Administrators user group.

When you perform the default installation, Services should be already configured by the Muster installer. If you skip the user creation, depending on your Windows version, you should open the Services Control Panel applet and assign log on information to the installed services.
After configuring the user account the next step consists in performing a final check to verify that the Muster account is able to access your shared folders. From now on, we’ll assume that we have created a shared folder, located on a file repository server called MASTER and that the server exports a share called RENDERFARM.
Logon a random machine where you’ve installed Muster and configured the account. Instead of your personal account, use the Muster account. If you’ve created a custom account, use it.
After logging in, try to open the shared folder (i.e. \\MASTER\RENDERFARM) , create some files inside it, try to rename them and finally try to delete them. If everything was successful, you have well configured well the user account and it’s able to access your file server.

Windows unattended installation

The Windows installer (msi) supports unattended installations from the command line. You just need to specify what kind of features you want to install from the list below:

  • ClientTools
  • Mrtool
  • Console
  • Client
  • Extras
  • Server
  • Notificator

Also, if you're going to install the services, you need to supply the IS_NET_API_LOGON_USERNAME and IS_NET_API_LOGON_PASSWORD value to the command line.

This is an example command line that installs just the Render client with the client tools:

msiexec /i ADDLOCAL=ClientTools,Mrtool,Console,Client,Extras CONF_CLIENT_SERVER=dispatcherhost.domain IS_NET_API_LOGON_USERNAME=%COMPUTERNAME%\administrateur IS_NET_API_LOGON_PASSWORD=ourpassword /qb

IF you need to customise further properties, you can run a sample installation with the following command line:

msiexec /i /l* loginstall.txt

This will log your installation where you can find the values of the properties you may need to change from the default value.

Muster comes on the MAC OS X platform as a self-mounting .dmg compressed image. Once you double-click the .dmg image, the following window will appear:

If you’re not going to upgrade your existing installation, the only required step to install Muster n the MAC OS X platform is dragging the Muster folder inside your Application folder.

If you’re going to upgrade an existing installation, please be sure that your existing services are stopped through the Services applet.

Once you copy the Muster folder inside the Application folder, locate it using the Finder:

then start the Services application that lets you start and stop the services, and install them as persistent system services:

From the Services applet, you can even configure some basic parameters before starting the services like the Dispatcher database and the network ports. If you’re not going to install the Dispatcher, just move to the Render client tab.

To install the Render client persistently, just click the Install Service button.

You can tell Muster to scan the local workstation for installed batch renders just clicking the “Rescan local applications”. Remember that this process may be time consuming and will scan in know locations on your system drive or your entire file system if you choose “perform a full scan on any local drive”. You can always skip this step and configure the paths to the render engines later through the Console.
After the service installation and configuring the engines, check the IP address of your Dispatcher and then click Start Service.
The services control panel applet can be minimized. It will stay in the Finder bar and can be recalled on demand right clicking on the icon

Muster comes on the linux platform as a gzip compressed tar file. Assuming you downloaded Muster on a temporary folder inside your home folder, open your shell and type:

tar –xvf Muster9.0.0.x64.linux.tar.gz

This will explode the archive into your current directory. Now you can start the textual installer with the following command:

sudo ./install

The installer will prompt you for the modules you’re interested in and copy the required files in the installation directory:

Muster 9 Copyright 2000-2018 Virtual Vertex
Welcome to the installation script for Muster 9
The script will attempt to install Muster on your local filesystem
Pay attention. The destination directory will be overwritten!
Where do you want to install Muster?[/usr/local/muster9]
Creating directory /usr/local/muster9
Do you want to install the Dispatcher service?[yes]
Do you want to install the Renderclient service and the client components?[yes]
Copying content to /usr/local/muster9...

If you choose to install the Dispatcher service, you’ll be prompted for Dispatcher installation properties:

Do you want to configure the Dispatcher service?[y]
Do you want to start the Dispatcher engine on service startup?[y]
Do you want to enable the Dispatcher integrated web server?[y]
Which database engine you want to use for the Muster queue?[sqlite/mysql]
Please provide the filename for your local database[muster.db]
Please provide the filename for your local history database[muster_history.db]
Do you want to configure Dispatcher network ports?[no]
Writing Dispatcher configuration file to /usr/local/muster9/dispatcher.conf

If your choose to install the Render client service, you’ll be prompted for Render client installation properties:

Do you want to configure the Renderclient service?[y]
How many instances do you want to spawn?[1]
Please insert the IP address of your Dispatcher service[]
Please insert the Renderclient network port configured on your Dispatcher service[9680]
Please insert the Renderclient network port used for management connections[9685]
Do you want to let the client broadcast its presence on the network to allow automatic discovery?[y]
If you want to protect incoming management connection with a password, type it now[]
Do you want to start the Renderclient service in paused status?[y]
What selection priority do you want to give to the Renderclient?[1]
Where do you want to store the processes log files?[/usr/local/muster6/logs]
Writing Renderclient configuration file to /usr/local/muster9/rc.conf

After configuring the Render client properties, the installer will ask you to scan the local file system for installed batch renders. Remember that this process may be time consuming and will scan in know locations on your system drive or your entire file system if you choose “perform a full scan on any local drive”. You can always skip this step and configure the paths to the render engines later through the Console:

The Renderclient configuration file needs to be configured with the paths to external processes.This may be done automatically by this installations script but it may take a long time depending on your filesystem.
Do you want to scan your local filesystem for known applications and configure the Renderclient templates?[y] n

The last step will setup the required file permissions and copy if available, the init.d scripts for automatic services startup. At the time of this writing, we provide init.d scripts for Fedora, Suse and Debian distributions. Some distributions are direct forks of those ones, so there’s a chance that our scripts will work in a different distribution.

Setting files permissions...
Do you want to install and configure init.d startup scripts for the installed Muster daemons?[yes]
Copying ./scripts/fedora/muster6d to /etc/init.d/muster9d
Enabling runlevels...
Copying ./scripts/fedora/muster6rcd to /etc/init.d/muster9rcd
Enabling runlevels...
Installation completed. You can start Muster with /usr/local/muster9/dispatcher, /usr/local/muster9/rc or invoking the muster6d and muster9rcd init.d scripts.
Muster Console GUI can be started with /usr/local/muster9/xConsole and the Services applet with /usr/local/muster9/xServiceControl

Depending on the script availability and your choice, you may end with automatically started services, or you may need to start them from the command line. Just follow the paths and hints that the installer will provide at the end of the installation process.

This section explains the steps required to setup a full cross platform environment. The following picture shows the setup of our fake render farm, remember to swap the names of the shares with the ones matching your environment:

As you can see from the picture, we have a full set of mixed platforms, each one accessing a common shared folder hosted by a Windows server machine. In our example, the same machine also runs the Dispatcher server but the components may be on two distinct hosts.

The first step requires the mounting of the shared file system on each client. Beginning with Windows, there’s very little to do, considering the Dispatcher is running on Windows too. If we want to support an additional path through a drive mapping, the Z drive must be configured on each client and on the Dispatcher. This is done exclusively through the Muster preferences of each module in the Drive mappings section.

There’s no relation between what you map through the interface while you’re logged on the machine, and the network drives available to Muster. The Muster service lives in its own user space and has no visibility over the shares created by a user.

The following picture shows how the preferences should be configured on the clients:

The following picture shows you how the preferences should be configured on the Dispatcher:

Remember that after each configuration, you need to restart the services to activate the changes.

The second step requires the configuration of the Mac platforms. First, you need to mount the shares to make it visible on the Mac. Assuming as the IP address of the network shares, the following pictures shows how to mount it using the Finder Connect to Server option:

Connect to the server

Select the share and mount it

Shares is now available in the /Volumes folder

As you can see from the last picture, the Data share is now available under /Volumes/Data.
If you’re going to run Muster as a Mac service, you need to mount the volume in a different way. Considering Muster will run even with no users logged at all, if you restart your Mac, the share will be unmounted and won’t be available until someone remount it. That’s why you require a static mount, where the Mac will take care of mounting back the volume each time it performs the boot sequence. There’re several ways to do that on a Mac platform, the most reliable we found until now is changing the /etc/auto_master file. This is a fast walk-trough:

To start with open up the Terminal application as an administrative user and then use sudo to create a bash shell:

sudo bash (enter)

You will be prompted to enter your administrator password at this point.
We will now create a file entitled auto.smb in the /etc/ directory to hold our server details

pico /etc/auto.smb (enter)

In this file enter the following line (add more lines for extra servers/shares)

$Sharename -fstype=smbfs ://$Username:$Password@$Server/$Share

$Sharename = the name you want to give the mount point $Username = the user to connect to the server as $Password = password of the user $Server = the name of the server (dns/wins entry) $Share = the name of the share on the server

That means, considering our scenario:

Data -fstype=smbfs ://$Username:$Password@

As this file stores the username and password to the server in plain text set the permissions of the file so that only the root user can read it.

chmod 600 /etc/auto.smb (enter)

Now edit the /etc/auto_master file and append the auto.smb record at the end of the file. The auto_master file controls all the automounts for the system, leave everything about this file alone except for the extra line at the end.

pico /etc/auto_master (enter)
# Automounter master map
+auto_master # Use directory service
/net -hosts -nobrowse,nosuid
/home auto_home -nobrowse
/Network/Servers -fstab
/-  -static
/Volumes auto.smb

This will tell the automounter to mount the shares defined in the /etc/auto.smb file under the /Volumes directory. You can force an automout update with: automount -vc (enter)
The next step requires a similar work on the linux platform. You can mount a share manually using the “mount –t cifs” command line syntax but we would like to do is have the share mounted statically. You can accomplish this task by editing the /etc/fstab file and adding this line:

//  /mnt/data smbfs username=$Username,password=$Password 0 0

Remember to change the $Username and $Password placeholders with your network credentials.

Ok, we almost done the work. We have the shares ready and mounted on each platform. The last step to perform requires the configuration of Muster to tell it how the shares are visible on each platform so it can exchange paths when required. This is done through the Configure repositories voice in the Management menu. Once you open the dialog, you have to create a path like the one shown in the next picture:

As you can see, we are telling Muster how paths are seen for each platform. The Server side field is a Dispatcher side path. Considering we’re running the Dispatcher on Windows, the path matches with the Windows one. If we had installed the Dispatcher on a different platform, the field should have been configured according.

We almost done. Remember the Windows drive mapping ? If you want the freedom of using it as well as the direct network paths, you have to add an additional substitution rule with the drive Z as the source.

That’s all. Restart the Dispatcher service and start submitting and rendering cross platform!

The next step will be preparing a test scene for network rendering. You can use a scene built for this example following the instructions or you can adapt an existing scene taken from your works.

The most important concept to take care when launching networked jobs is file referencing.
When you link any external file in your scene, you should check carefully that it’s linked in a relative way. A relative link basically means that the path refers to the file assuming the project path prefix.

Let’s make an example with Maya:
Open Maya and create a new project called MusterTest. For this example we’ll assume that the project has been created inside C:\MayaProjects.
Create a test texture with your favourite painting software and save it as MusterTexture.tga on the root of your C drive.
Next, open Maya and create a NURBS Sphere, open the Hypershade and create a basic Phong shader. Create a new texture node on the color channel of the shader and select MusterTexture.tga on the root of your drive.
As you can see, after selecting the texture, Maya store the path to the file as an absolute path. This happened because the file is not inside the project structure but lives on an external path.
If we try to render this scene using Muster , the render won’t be able to load the texture, unless you launch it from the workstation that generated the files and contains the files in their original position. You’ll end with an incorrect result on the others nodes because they won’t be able to load the files from their root drive.
You can solve the problem copying the textures inside the sourceimages folder of the Maya project or create a dedicated folder that must be inside the project structure like C:\MayaProjects\MusterTest.
At this time, if we delete the file node and create a new one, when selecting the file, Maya will link it as sourceimages\MusterTexture.tga. THIS IS A RELATIVE PATH!
Key concept: Check always that your textures are linked in a relative way. There are several scripts on the web that do exactly this. Some of them allows you to automatically move an out-of-the-project texture inside the project structure.
Even if we link our textures in a relative way, we must be sure that the rendering hosts will be able to access the entire project structure. If we leave it on the C drive of our workstation, it will be impossible for the hosts to access the project. So the next step requires to copy the entire MusterTest folder on our file repository, \\MASTER\RENDERFARM for this example.

Because we want to render an animation , animate the rotation of the ball across 10 frames and then save the scene as test.mb inside the SCENES folder. You are ready to start network rendering with Maya and Muster.

Those concepts applies for any rendering application. What we call a project may be called in a different way but the concept is always the same. Some applications are also able to automatically relocate the external references if they are inside the same or a child path of the job file.

We strongly suggest to read the batch rendering documentation of the software you’re going to use with Muster for further information.