Render Environment

Job Environment Variables

Environment variables can be set for a job, and these variables will be applied to the rendering process’ environment. These variables can be set in the Job Properties in the Monitor, and they can be set during Manual Job Submission.

Manual Job Submission

For manual job submission, these variables can be specified in the job info file like this:

EnvironmentKeyValue0=mykey=myvalue
EnvironmentKeyValue1=anotherkey=anothervalue
EnvironmentKeyValue2=athirdkey=athirdvalue
...

There is also an IncludeEnvironment option that takes either True or False (False is the default). When IncludeEnvironment is set to True, Deadline will automatically grab all the environment variables from the submitter’s environment and set them as the job’s environment variables.

IncludeEnvironment=True

This can be used in conjunction with the EnvironmentKeyValue# options above, but note that the EnvironmentKeyValue# options will take precedence over any current environment variables with the same name.

Finally, there is a UseJobEnvironmentOnly option that takes either True or False (False is the default):

UseJobEnvironmentOnly=True

The UseJobEnvironmentOnly setting controls how the job’s environment variables are applied to the rendering environment. If True, ONLY the job’s environment variables will be used. If False, the job’s environment variables will be merged with the Worker’s current environment, with the job’s variables overwriting any existing ones with the same name.

Job Rendering

At render time, the job’s environment variables are applied to the rendering process. As explained above, the job’s environment can either be merged with the Worker’s current environment, or the job’s environment can be used exclusively.

Note though that if the job’s plugin defines any environment variables, those will take precedence over any job environment variables with the same name. In a job’s plugin, there are two functions that are available for the DeadlinePlugin object that can be used to set environment variables:

  • SetProcessEnvironmentVariable( key, value ):

    • This should be used in Advanced plugins only.

    • Any variables set by this function are applied to all process launched through Deadline’s plugin API.

    • Note that calling SetProcessEnvironmentVariable in Simple plugins or within ManagedProcess callbacks will not affect the current process’ environment.

    • When using SetProcessEnvironmentVariable in an Advanced plugin, make sure to call it outside of the ManagedProcess callbacks.

  • SetEnvironmentVariable( key, value ):

    • This is typically used in Simple plugins, or within ManagedProcess callbacks in Advanced plugins.

    • Any variables set by this function are only applied to the process they are starting up, and they take precedence over any variables set by SetProcessEnvironmentVariable.

See the Application Plugins documentation for more information.

Path Mapping

Environment variables in Deadline are NOT automatically path mapped as it is normal for env vars to be platform specific. However, if this is desired behaviour, you can intercept the environment variable and path map using a JobPreLoad.py script which executes in front of the app plugin script. Alternatively, it can be executed for ALL jobs (any app plugins) if you use a GlobalJobPreLoad.py script. It is important to control any environment variables using these py script entry points as the app plugin might need to ‘see’ these environment variables prior to launching. Here is an example where we need to query an already existing machine based environment variable and path map this env var and set the result accordingly to the render process without affecting the original machine environment variable:

import os
from Deadline.Scripting import *

def __main__(deadlinePlugin):
    incomingEnvVar = os.environ["MY_ENV_VAR"]
    convertedEnvVar = RepositoryUtils.CheckPathMapping(incomingEnvVar)
    deadlinePlugin.SetProcessEnvironmentVariable("MY_ENV_VAR", convertedEnvVar)

If you are already including the env var within the submitted job in Deadline (instead of it being on the system already), then retrieve this env var using the job properties:

from Deadline.Scripting import *

def __main__(deadlinePlugin):
    job = deadlinePlugin.GetJob()
    incomingEnvVar = job.GetJobEnvironmentKeyValue("MY_ENV_VAR")
    convertedEnvVar = RepositoryUtils.CheckPathMapping(incomingEnvVar)
    deadlinePlugin.SetProcessEnvironmentVariable("MY_ENV_VAR", convertedEnvVar)

Render Jobs As Job’s User

Deadline has some features that allow jobs to be rendered with the the job’s user account, rather than the user account that the Worker is running as.

  • On Windows, this is done by using the job’s user account credentials to start the rendering process using that account.

  • On Linux and Mac OS X, the Worker must be running as root. It will then use “su” or sudo” to start the rendering process using the job’s user account, depending on your Repository Options. Additionally, there is an option “Preserve Environment On Linux and Mac OS X” to preserve the current environment (ie: the Worker’s current environment). When it is disabled, su or sudo will start with a clean environment. This setting is ignored on Windows, and is ignored on Mac OS X when using ‘su’ instead of ‘sudo’. Note that when this option is disabled, any environment variables that are set for the process by the render plugin are ignored because su or sudo will reset the environment.

The following process environment variables will be present when a program or process is invoked as the job’s user account:

  • DEADLINE_USER: The job’s user name.

  • DEADLINE_BIN: The directory of the executable.

Enabling Render Jobs As User

To render jobs as the job’s user, you must enable Render Jobs As User in the User Security section of the Repository Options. Note that this setting affects all jobs, and requires users to ensure that their User Account Settings are configured properly (see below).

../_images/cro_user_security.png

Preserving Specific Environment Variables with Sudo

Certain applications require preservation of specific environment variables to function properly. As an example, Deadline’s Draft requires three variables to persist at render time. The sudo command can preserve these variables when Deadline is running as a user once the ‘/etc/sudoers’ file as been configured correctly.

Since a badly configured ‘sudoers’ file can lock you out of some systems permanently, edit the file with visudo on the command line. It should use the nano text editor on most modern distributions. This will do a sanity check before making changes to the actual ‘sudoers’ file so that a typo won’t disable administrative access.

To add variables, list them one at a time as ‘Defaults’ directives in the file like so:

Defaults        env_keep += "PYTHONPATH"
Defaults        env_keep += "MAGICK_CONFIGURE_PATH"
Defaults        env_keep += "LD_LIBRARY_PATH"

As many lines as are needed can be added here, so be sure to add as many variables as are needed. They should include everything across all the applications that will be used with Deadline.

User Account Settings

The user account settings used to start the rendering process are stored in the User Settings for each user. For Linux and OS X, only the User Name is required. For Windows, the Domain and Password must also be provided for authentication.

../_images/user_settings.png