General Information About Clusters

Once your network is set up and you have installed the necessary components, you are ready to create distributed processing clusters.

There are three approaches you can take to creating a cluster:

If you have questions about any concepts and terms used here, see Distributed Processing Basics.

Note: If you are an Apple Qmaster user and you want to create a cluster that includes computers that do not have Apple Qmaster installed, see the Apple Qmaster User Manual for instructions.

Options in the Apple Qmaster Sharing Window of Compressor

Following are optional settings you may want to use.

Important: If you are making changes to existing settings and this computer is already providing processing services, clicking OK immediately resets this computer’s services. If this computer is also the cluster controller, any current jobs are terminated.

For a complete list of the options and settings in the Apple Qmaster Sharing window of Compressor, see About Basic Settings in the Apple Qmaster Sharing Window and About Advanced Settings in the Apple Qmaster Sharing Window.

Setting the Name

By default, a computer is identified on the network by its computer name (as it is entered in the Sharing pane in System Preferences). You can change this name to something more meaningful if you like, since it is the name used to identify this computer in the Apple Qmaster distributed processing system. If you are setting up a QuickCluster, this is the name that will appear in the Compressor Cluster pop-up menu or the Apple Qmaster Submit To pop-up menu. If you are setting up a managed cluster controller, this is the name that will appear in the Apple Qadministrator Controller pop-up menu.

To enter a name for a QuickCluster
  • Enter the new name for the cluster in the “Identify this QuickCluster as” field.

To enter a name for a cluster controller for use with Apple Qadministrator
  1. Click Advanced to open the Advanced pane.

  2. Enter the new name in the “Identify this computer to Apple Qadministrator as” field.

Unmanaged Services

You can enable unmanaged services for a QuickCluster. For more information, see Managed vs. Unmanaged Services.

Setting the Password

To add a password requirement, select the “Require password” checkbox.

  • If you are setting up a QuickCluster: Other users will be required to enter this password before being allowed to submit requests to this computer.
  • If you are setting up a cluster to use with Apple Qadministrator: An administrator will be required to enter this password before being allowed to add this computer to a cluster.

For more information, see Setting a Service Password for Including a Computer in a Cluster. (If you configure the computer as both a cluster controller and a service node, this password is used for both.)

Setting Cluster Storage

You can change the default scratch storage location for processing that occurs on this computer in the Advanced pane. For more information, see Using Cluster Storage.

Managed vs. Unmanaged Services

You have flexibility in how you build clusters for distributed processing with Compressor or Apple Qmaster. When you configure processing services, you can choose to make them either managed services or unmanaged services (the default).

Figure. Services section in the Apple Qmaster pane of System Preferences.

Managed Services

Managed services can be assigned to serve one particular cluster controller. Once assigned, managed services remain exclusively dedicated to that cluster until they are removed with the Apple Qadministrator application. QuickClusters cannot use managed services from other nodes, except in the case of extended node clusters. For more information, see the Apple Qadministrator User Manual. See the Apple Qmaster User Manual for more information on extended node clusters.

Unmanaged Services

Unmanaged services automatically assign themselves to the first available This Computer Plus cluster or QuickCluster with enabled unmanaged service support. QuickClusters listen for unmanaged service advertisements and may mark or remember any of them for later use. An unmanaged service remains dedicated to its This Computer Plus cluster or QuickCluster only long enough to finish the current job. Once the current job is complete, an unmanaged service is once again a “free agent” and advertises its availability to all This Computer Plus clusters and QuickClusters.

Note: Managed clusters (those created with Apple Qadministrator) can also use unmanaged services. When unmanaged service support is enabled on a managed cluster, the cluster automatically adds any available unmanaged services in addition to its managed services (that were explicitly added using Apple Qadministrator).

Enabling Unmanaged Services on QuickClusters

Follow these steps to enable unmanaged services on QuickClusters.

To enable unmanaged services on QuickClusters
  1. In Compressor, choose Apple Qmaster > Share This Computer.

  2. Select the “Share this computer” checkbox and the “as QuickCluster with services” button to create a QuickCluster.

  3. Select “Include unmanaged services from other computers.”

    Figure. QuickCluster section in the Apple Qmaster pane of System Preferences.
  4. Click OK.

For more information on creating QuickClusters, see Getting Started Quickly Using QuickClusters.

Enabling Unmanaged Services on Managed Clusters

Follow these steps to enable unmanaged services on managed clusters.

To enable unmanaged services on managed clusters
  1. In Apple Qadministrator, select a cluster in the Cluster list, or click the Add (+) button to add a new cluster.

  2. Select “Allow use of unmanaged services.”

For more information on creating managed clusters, see Creating Clusters with Apple Qadministrator.

Managing Processing Services

Follow the instructions below to manage the processing services on a computer in a cluster.

Important: If you are making changes to existing settings and this computer is already providing processing services, clicking OK immediately resets this computer’s services. If this computer is also the cluster controller, any current jobs are terminated.

To set managed processing services
  1. In Compressor, choose Apple Qmaster > Share This Computer.

  2. Do one of the following:

    • Select the “Require these services to only be used in managed clusters” checkbox to use this computer only in managed clusters.

    • Deselect the “Require these services to only be used in managed clusters” checkbox to use this computer in unmanaged as well as managed clusters.

  3. Click OK.

To turn off processing services
  1. In Compressor, choose Apple Qmaster > Share This Computer.

  2. In the Services section, do one of the following:

    • To turn off Compressor services: Deselect the Compressor checkbox.
    • To turn off Apple Qmaster services: Deselect the Rendering checkbox.
  3. Click OK.

Turning Cluster Controller Services On or Off

Use the Services area in the Apple Qmaster Sharing window of Compressor to turn the cluster controller on or off on a specific computer.

To turn on cluster controller services
  1. In Compressor, choose Apple Qmaster > Share This Computer to open the Apple Qmaster Sharing window.

  2. Select the “Share this computer” checkbox, then select one of the following buttons:

    • as QuickCluster with services: Select this option to create an “instant” cluster with unmanaged services.
    • as Services and cluster controller: Select this option to build a cluster in Apple Qadministrator. (See Creating Clusters with Apple Qadministrator for more information.)

    Also see Managed vs. Unmanaged Services for more information.

  3. In the Services area, select the Rendering and/or Compressor checkbox.

  4. Click OK.

    The cluster is enabled, making this computer a cluster controller.

To turn off cluster controller services
  1. In Compressor, choose Apple Qmaster > Share This Computer to open the Apple Qmaster Sharing window.

  2. Deselect the “Share this computer” checkbox and click OK.

    Important: If you are making changes to existing settings and this computer is already providing processing services, clicking OK immediately resets this computer’s services. If this computer is also the cluster controller, any current jobs are terminated.

Optionally, you can turn off the controller and just make the node a service node. To do this, select “as Services only” in the “Share this computer” section.

Using Virtual Clusters to Make the Most of Multicore Computers

You can adjust the number of instances of a processing service, essentially creating virtual clusters on individual computers. For processor-intensive work, having multiple instances may increase speed and efficiency, depending on the processing application. Too many instances, however, may actually decrease speed and efficiency.

A general rule you can use when choosing the number of instances is to allow two GB of memory for each instance. If you have a computer with eight GB of memory that offers eight instances in the pop-up menu, choosing four instances should provide good results. This number can vary widely though, depending on whether this computer is also being used for other duties.

Note: By default, the Apple Qmaster system creates one Rendering service instance for each processor. Rendering services are for Shake (with Apple Qmaster), Autodesk Maya, and other UNIX command-line programs, as opposed to Compressor services, which are solely for Compressor distributed processing. Consult the documentation that came with the application to see if using each processor individually is ideal.

To change the number of instances of processing services on a computer
  1. In Compressor, choose Apple Qmaster > Share This Computer.

  2. Select Compressor or Rendering in the Services section, then click its Options button.

  3. In the dialog that appears, choose the number of instances from the pop-up menu and click OK.

    Figure. "Number of Instances" pop-up menu.
  4. Click OK in the Apple Qmaster Sharing window.

    Note: The Service Options dialog is also used to add extended nodes to a cluster, as described in the Apple Qmaster User Manual.

Setting a Service Password for Including a Computer in a Cluster

If you want to control who is able to include a specific service node or cluster controller in a cluster, you can create a password called a service password for the computer.

Note: A service password can be stored in a user’s keychain.

To set or change a service password
  1. On the computer designated as the service node or cluster controller, open Compressor and choose Apple Qmaster > Share This Computer.

  2. Do one of the following:

    • To require a password: Select Require Password.
    • To change an existing password: Click Change Password.

    The password dialog opens.

    Figure. Password dialog in the Apple Qmaster pane of System Preferences.
  3. Enter and verify a password, then click OK.

  4. Click OK in the Apple Qmaster Sharing window to apply this change.

    Important: If you are making changes to existing settings and this computer is already providing processing services, clicking OK immediately resets this computer’s services. If this computer is also the cluster controller, any current jobs are terminated.

Scheduling Service Availability

If you enabled unmanaged services, you can open a calendar interface and schedule the availability of these services to the distributed processing system.

The calendar interface of the work schedule dialog contains several useful features.

Figure. Work schedule dialog in the Apple Qmaster pane of System Preferences.

You can use the following controls to constrain the availability of unmanaged services for each day of the week:

  • Start time field: Enter a start time.
  • End time field: Enter an end time.

Scheduling Service Availability in the Work Schedule Dialog

Follow the steps below to schedule the availability of unmanaged services.

To schedule service availability
  1. In the Advanced Service Settings area of the Advanced pane within the Apple Qmaster preferences pane, click Set.

    The work schedule dialog appears.

  2. To constrain the availability of the services, choose one of the options from the pop-up menu next to a particular day of the week. See Scheduling Service Availability for details.

  3. Enter any constraining time periods in the appropriate start time and end time fields.

    Note: You must enter valid days and times. The time cannot overlap into the next day in one entry. There must be two entries when the range ends after 12 a.m. For more information, see Setting Availability from Sunday Night to Monday Morning.

  4. Click OK to save the settings and close the dialog.

  5. Click OK to apply the changes to this computer.

    Important: If you are making changes to existing settings and this computer is already providing processing services, clicking OK immediately resets this computer’s services. If this computer is also the cluster controller, any current jobs are terminated.

Setting Availability from Sunday Night to Monday Morning

You must enter valid days and times. The time cannot overlap into the next day in one entry. There must be two entries when the range ends after 12 a.m.

For example, to set the service availability from 6 p.m. on Sunday to 8 a.m. on Monday, follow the steps below.

To provide service availability from Sunday night to Monday morning
  • Make both of the following entries:

    • Sunday: On between 6:00 PM and 12:00 AM
    • Monday: On between 12:00 AM and 8:00 AM

Using Cluster Storage

By default, the Apple Qmaster distributed processing system saves temporary process files in the /Library/Application Support/Apple Qmaster/Storage directory on the cluster controller. You can also choose any other location on a local disk for this scratch storage. Computers in the cluster will access this location as needed.

Adjusting Cluster Storage Settings

Follow the steps below to change scratch storage settings for a cluster.

To change cluster storage settings
  1. On the cluster controller, open Compressor and choose Apple Qmaster > Share This Computer.

  2. Click Advanced to open the Advanced pane.

  3. Configure the following optional settings:

    • To change the cluster storage location: Click the “Storage location” Set button, then navigate to the folder in the dialog and click Choose.

      Note: If you are using the default This Computer setting in the Cluster pop-up menu in the Compressor Batch window and you choose Cluster Storage as the destination, the output file will be copied to the Source location.

    • To change how often cluster storage files are deleted: Enter a new number in the “Delete files older than N Days” field.
      Figure. The Delete Files Older Than N Days field, the Cluster storage Set button, and the Stop Sharing button in the Advanced pane in the Apple Qmaster pane of System Preferences.
  4. Click OK to apply the changes.

    Important: If you are making changes to existing settings and this computer is already providing processing services, clicking OK immediately resets this computer’s services. If this computer is also the cluster controller, any current jobs are terminated.

Cluster Storage Capacity

If you are processing large source media files that exceed the available storage space on the startup disk, you may run out of storage space on that disk. There are a number of things you can do to address this.

Cleaning Up Cluster Storage

If you are using cluster storage and an error occurs, partial files may be left on the designated cluster storage location. Check the designated cluster storage location to make sure no partial media files are left there. If you find partial media files, delete them and submit the job again.

QuickTime Reference Movies

If you submit a reference movie for distributed processing, the Apple Qmaster distributed processing system will automatically copy the appropriate media files to the processing cluster. For the best performance, you can avoid this file transfer step by making sure that the media files specified in the reference movie are available to each node of the Apple Qmaster cluster.

Defining Ports for Service Advertisements

You can define which ports Apple Qmaster uses for service advertisements with the Enable Port Range checkbox and text fields in the Network section of the Advanced pane within the Apple Qmaster Sharing window of Compressor.

To define ports for Apple Qmaster service advertisements
  1. In Compressor, choose Apple Qmaster > Share This Computer.

  2. Click Advanced to open the Advanced pane.

  3. Select Enable Port Range.

  4. In the From field, enter any integer value between 50,000 and 65,535 to set the start of the range.

  5. In the “Number of ports” field, enter the size of the range, such as 1000.

Recovery and Failure Notification Features

The Apple Qmaster distributed processing system has a number of built-in features designed to attempt recovery if there is a problem, and to notify you when the system attempts a recovery.

Recovery Features

The recovery actions described next occur automatically if failures occur in the Apple Qmaster distributed processing system. There is no need for you, as the administrator, to enable or configure these features.

If a Service Stops Unexpectedly

If either the cluster controller service or the processing enabled on a service node stops unexpectedly, the Apple Qmaster distributed processing system restarts the service. To avoid the risk of endless stopping and restarting, the system restarts the failed service a maximum of four times. The first two times, it restarts the service right away. If the service stops abruptly a third or fourth time, the system restarts the service only if it had been running for at least 10 seconds before it stopped.

If a Batch Is Interrupted

When a service stops suddenly while in the middle of processing an Apple Qmaster batch, the cluster controller resubmits the interrupted batch in a way that prevents the reprocessing of any batch segments that were complete before the service stopped. The cluster controller delays resuming the batch for about a minute from the time it loses contact with the service.

If a Batch Fails

When the service is running, but one batch fails to process, a service exception occurs. When this happens, the cluster controller resubmits the batch immediately. The cluster controller resubmits the batch a maximum of two times. If the job fails on the third submission, the distributed processing system stops resubmitting the job. In Share Monitor, the job’s status is set to Failed.

Failure Notification

There are two different ways that the Apple Qmaster distributed processing system can provide information about a problem.

Email Notification

When a processing service stops unexpectedly, Apple Qmaster sends a notification email to the address that was entered in the Apple Qadministrator Cluster Preferences dialog for that cluster. If no address was entered there, the email is sent to the address in the Internet settings of the computer on which the cluster controller is enabled.

Note: Apple Qmaster does not currently support SMTP servers that require authentication.

Log Files for Individual Jobs or Batches

If a particular job or batch fails, a log file is generated that describes this failure. You can find the name and location of this log file through Share Monitor by selecting the batch or job, clicking the Show Info icon, then clicking the Show Log button.

Notification and Log Labels

The following table lists the service labels used in the email notifications and logs.

Processing service type
Notification label
Local Compressor service
servicecontroller:com.apple.stomp.transcoder
Distributed Compressor service
servicecontroller:com.apple.stomp.transcoderx
Distributed Apple Qmaster service
servicecontroller:com.apple.qmaster.executor