Repository Settings Importer and Exporter¶

Overview¶

The Repository Settings Importer and Exporter feature uses a standalone file format to save or load repository settings via Deadline Command. This is particularly useful if your workflow requires frequent tear-down/redeploy of your Deadline render farm infrastructure as it can save you the hassle of having to manually reconfigure your farm.

How Is This Different to the Existing Import Repository Settings Feature?¶

Pros

Available via Deadline Command
Does not require a connection to a repository to import settings from
Can export your repository settings into a standalone file format

Cons

Not available via Deadline Monitor
Currently only supports a subset of the settings in Import Repository Settings

Supported Settings¶

The following settings are supported for exporting and importing through Deadline Command.

Exporting Repository Settings¶

To export repository settings use the ExportRepositorySettings command. To get information on the settings and flags that can be used, use the Help command:

deadlinecommand Help ExportRepositorySettings

The simplest way to use the ExportRepositorySettings command is as follows:

deadlinecommand ExportRepositorySettings

This will print the export to the console. Since exports can get quite lengthy, there is also the ability to export to a file path. This can be done by specifying the ExportFilePath as follows:

deadlinecommand ExportRepositorySettings -ExportFilePath C:\Desired\Export\Path\Export.txt

Specific settings may also be specified if it is desired to not include all settings in the export. This can be done by specifying the Settings as follows:

deadlinecommand ExportRepositorySettings -Settings setting1 setting2 setting3 <etc>

For example, to export only pools and groups to a file the following command would be used:

deadlinecommand ExportRepositorySettings -Settings Groups Pools -ExportFilePath C:\Desired\Export\Path\Export.txt

By default all settings will be exported if the Settings setting is not specified.

Importing Repository Settings¶

To import the repository settings use the ImportRepositorySettings command. To get information on the settings and flags that can be used, use the Help command:

deadlinecommand Help ImportRepositorySettings

The simplest way to use the ImportRepositorySettings command is as follows:

deadlinecommand ImportRepositorySettings -ImportFilePath C:\Desired\Export\Path\Export.txt -ImportOperation Append

One thing to note here is the ImportOperation. The import operation tells the importer how to import the settings. There are two main import operations: Append and Replace. The Append operation retains existing settings, and adds on to them where possible. The Replace operation will remove previous settings and replace them.

There is also the ability to do a dry run of an import to determine if there will be any errors or warnings. Doing a dry run will not modify the settings at all but can indicate if the import would be successful. To do a dry run of an import append the words DryRun to the import operation. For instance, AppendDryRun indicates a dry run using the append operation. This would be used as follows:

deadlinecommand ImportRepositorySettings -ImportFilePath C:\Desired\Export\Path\Export.txt -ImportOperation AppendDryRun

Only the settings the Import File included will be modified in the repository, while settings that are not included will remain the same as they were before the import.

File Format Specification¶

The importer/exporter uses JSON encoding. The various top-level JSON keys are documented below.

Groups

Pools

Limits

Path Mapping

Users

Permission Groups

Worker settings

Groups¶

Deadline Groups are represented by a JSON object that is a child of the root document having the "Groups" key. The schema is defined as:

{
  // ...
  "Groups": {
    "Version": <version>,
    "Settings": {
      "GroupList": [
        {
          "Name": <group_name>
        }
        // ...
      ]
    }
  }
  // ...
}

The possible fields include:

Field	Description
`<version>`	The version of the group schema. Currently there is only version (`1`).
`<group_name>`	The name of a group. Each group name must be unique and contain only alphanumeric characters, hyphens(-) and underscores(_).

Pools¶

Deadline Pools are represented by a JSON object that is a child of the root document having the "Pools" key. The schema is defined as:

{
  // ...
  "Pools": {
    "Version": <version>,
    "Settings": {
      "PoolList": [
        {
          "Name": <pool_name>
        }
        // ...
      ]
    }
  }
  // ...
}

The possible fields include:

Field	Description
`<version>`	The version of the pool schema. Currently there is only version (`1`).
`<pool_name>`	The name of a pool. Each pool name must be unique and contain alphanumeric characters, hyphens(-) and underscores(_).

Limits¶

Limits and Machine Limits are represented by a JSON object that is a child of the root document having the "Limits" key. The schema is defined as:

{
  // ...
  "Limits": {
    "Version": 1,
    "Settings": {
      "LimitList": [
          {
            "Name": <limit_name>,
            "Limit": <limits>,
            "LimitType": "<limit_type>",
            "ReleasePercentage": <release_limit>,
            "UsageLevel": "<usage_level>",
            "UBLSettings": {
              "Limit": <ubl_limit>,
              "Application": "<ubl_application>",
              "Enabled": true,
              "DenyListedWorkers": [ <deny_workers> ],
              "ExcludedWorkers": [ <excl_workers> ],
              "AllowListedWorkers": [ <allow_workers> ],
            }
          }
          // ...
      ]
    }
    // ...
  }
}

UBLSettings is an optional section and can be used only for the limits with type License.

The possible fields include:

Field	Description
`<version>`	The version of the limits schema. Currently there is only version (`1`).
`<limit_name>`	The name of a limit. Each limit name must be unique and contain only lower-case alphanumeric characters, spaces, underscores (_), and hyphens (-).
`<limits>`	The maximum number of Resources/Licenses that can simultaneously be used for this limit. For an unlimited license type, use (`-1`).
`<limit_type>`	There are two types of limits that can be configured: License Limits - use value (`License`) Resource Limits - use value (`Resource`) More details about license types you can be found here.
`<release_limit>`	Limit will be released when task reaches this progress. Used only for Resource limits. To disable this option use (`0.0`)
`<usage_level>`	The level at which a Limit Count will be checked out. Value must be one of the following three values: `Worker`, `Machine` or `Task`
`<ubl_limit>`	UBL count that can be checked out at a time. For no limit use (`-1`)
`<ubl_application>`	This is the application that 3rd Party UBL is being used for.
`<deny_workers>`	The list of workers names that will not render jobs that require this limit.
`<allow_workers>`	The list of workers names that will render jobs that require this limit, providing that the limit has not been reached.
`<excl_workers>`	The list of workers names that will render jobs that require this limit, regardless of whether or not the limit has been reached.

Path Mapping¶

Path Mapping (Cross-Platform Rendering) are represented by a JSON object that is a child of the root document having the "PathMapping" key. The schema is defined as:

{
  // ...
  "PathMapping": {
    "Version": <version>,
    "Settings": {
      "GlobalRules": [
        {
          "Path": "<replace_path>",
          "WindowsPath": "<windows_path>",
          "LinuxPath": "<linux_path>",
          "MacPath": "<mac_path>",
          "CaseSensitive": <case_sensitive>,
          "RegularExpression": <regular_exp>,
          "Region": "<region_name>"
        }
        // ...
      ],
      "SubmissionTimeRules": [
        // ...
      ],
      "RecursivelyApplyRules": <recursive_rule>
    }
  }
  // ...
}

Two types of rules can be configured for path mapping.

Global rules will be applied to any known paths prior to rendering any job. Configured under the GlobalRules key.
Submission-Time rules are defined globally, but are tied to individual jobs as Job-Specific Rules at the time of submission. Configured under the SubmissionTimeRules key.

All rule types are configured similarly, and only differ in the ways mentioned above.

The possible fields include:

Field	Description
`<version>`	The version of the path mapping schema. Currently there is only version (`1`).
`<replace_path>`	The original path that will be replaced.
`<windows_path>`	The path that will replace the original path on Windows.
`<linux_path>`	The path that will replace the original path on Linux.
`<mac_path>`	The path that will replace the original path on Mac.
`<case_sensitive>`	Boolean parameter that is responsible for case sensitivity when replacing a path.
`<regular_exp>`	Boolean parameter responsible for treating the text in the Replace Path entry as a regular expression.
`<region_name>`	The region that this pathmapping will be apply to. For all region use (`All`)
`<recursive_rule>`	Boolean parameter that is responsible for the sequential application of several rules when mapping paths.

Users¶

User Management are represented by a JSON object that is a child of the root document having the "Users" key. The schema is defined as:

{
  // ...
  "Users": {
    "Version": <version>,
    "Settings": {
      "UserList": [
        {
          "UserName": "<user_name>",
          "MachineName": "<machine_name>",
          "EmailAddress": "<email_address>",
          "SendEmailNotifications": <email_notification>,
          "SendPopupNotifications": <popup_notification>,
          "NotificationTypes": {
            "JobCompleted": <job_complete>,
            "JobFailed": <job_failed>,
            "JobWarning": <job_warning>,
            "JobTimeout": <job_timeout>
          },
          "RenderAsUserName": "<render_as_user>",
          "RenderAsUserDomain": "<render_as_user_domain>"
        }
        // ...
      ]
    }
  }
  // ...
}

The possible fields include:

Field	Description
`<version>`	The version of the user schema. Currently there is only version (`1`).
`<user_name>`	The name of a user. Each user name must be unique and can contain any Unicode character except for any of the following: `*=+?\|:;"<>/\[]%`.
`<machine_name>`	The user’s machine name (for Popup notifications).
`<email_address>`	The Email address of the user (for Email notifications).
`<email_notification>`	Boolean parameter responsible for if the user will receive Email notifications for the jobs when they complete, fail, or time out.
`<popup_notification>`	Boolean parameter responsible for if the user will receive Popup notifications for the jobs when they complete, fail, or time out.
`<job_complete>`	Boolean parameter responsible for if the user will receive notifications for the jobs when they complete.
`<job_failed>`	Boolean parameter responsible for if the user will receive notifications for the jobs when they fail.
`<job_warning>`	Boolean parameter responsible for if the user will receive notifications for the jobs when they generate a certain number of errors.
`<job_timeout>`	Boolean parameter responsible for if the user will receive notifications for the jobs when they timeout.
`<render_as_user>`	If Render Job As User is enabled, this is the user that the job will render as.
`<render_as_user_domain>`	If Render Job As User is enabled, this is the domain that will be used to start the rendering process as this user. This is only used on Windows.

Permission Groups¶

Permission Groups are represented by a JSON object that is a child of the root document having the "PermissionGroups" key. The schema is defined as:

{
  // ...
  "PermissionGroups": {
    "Version": <version>,
    "Settings": {
      "PermissionGroupList": [
        {
          "Name": "<permission_group>",
          "Enabled": true,
          "Expires": <group_expires>,
          "ExpiryDate": "<expire_date>",
          "FeatureAccessLevels": {},
          "GroupMembers": [<list_of_users>],
          "IsTimeRestricted": <time_restricted>,
          "RestrictedDays": {
            "Sunday": true,
            "Monday": true,
            "Tuesday": true,
            "Wednesday": true,
            "Thursday": true,
            "Friday": true,
            "Saturday": true
          },
          "RestrictedStartTime": "<restriction_start>",
          "RestrictedEndTime": "<restriction_end>",
          "CanSubmitJobs": <submit_jobs>,
          "CanModifyAllJobs": <modify_jobs>,
          "CanSeeAllJobs": <see_all_jobs>,
          "CanHandleProtectedJobs": <handle_prot_jobs>
        }
        // ...
      ]
    }
  }
  // ...
}

You can specify different features access levels under the key ``FeatureAccessLevels``.
More detailed information about features you can find  :ref:`here <controlling_feature_access_ref_label>`.

The possible fields include:

Field	Description
`<version>`	The version of the permission group schema. Currently there is only version (`1`).
`<permission_group>`	The name of a permission group. Each group name must be unique.
`<group_expires>`	Boolean parameter responsible for enabling control of expiry date for this permission group.
`<expire_date>`	Date and time in ISO 8601 format.
`<list_of_users>`	List of group members
`<time_restricted>`	Boolean parameter responsible for the permission group to only be active during the specified time span, from <restriction_start> to <restriction_end>
`<restriction_start>`	The start time when group will be active if Time-Restricted access is enabled. Should be provided in format `HH:MM:SS`
`<restriction_end>`	The end time when group will be active if Time-Restricted access is enabled. Should be provided in format `HH:MM:SS`
`<submit_jobs>`	Boolean parameter that is responsible for allowing users in this permission group to submit jobs.
`<modify_jobs>`	Boolean parameter that is responsible for allowing users in this permission group to modify jobs
`<see_all_jobs>`	Boolean parameter that is responsible for allowing users in this permission group to view other users’ jobs.
`<handle_prot_jobs>`	Boolean parameter that is responsible for allowing users in this permission group to delete or archive protected jobs.

Worker Settings¶

Worker Settings are represented by a JSON object that is a child of the root document having the "WorkerSettings" key. The schema is defined as:

{
  // ...
  "WorkerSettings": {
    "Version": <version>,
    "Settings": {
      "StdOutLimitEnable": <std_out_limit_enable>,
      "StdOutLimit": <std_out_limit>,
      "AutoRemovalDaysEnabled": <auto_removal_days_enabled>,
      "AutoRemovalDays": <auto_removal_days>,
      "OverrideListeningPort": <override_listening_port>,
      "ListeningPort": <listening_port>,
      "GatherResourceUsageDuringRendering": <gather_resource_usage>,
      "UseFullyQualifiedDomainNames": <use_domain_name>,
      "UseIPAddress": <use_ip_address>,
      "ExcludeInNonePool": <exclude_in_none_pool>,
      "ExcludeInNoneGroup": <exclude_in_none_group>,
      "SandboxRunsInJobEnvironment": <sandbox_runs_in_job_env>,
      "StalledDelay": <stalled_delay>,
      "PowerManagementScanInterval": <power_management_scan_interval>,
      "ExtraInfo0Name": <extra_info_name_0>,
      "ExtraInfo1Name": <extra_info_name_1>,
      "ExtraInfo2Name": <extra_info_name_2>,
      "ExtraInfo3Name": <extra_info_name_3>,
      "ExtraInfo4Name": <extra_info_name_4>,
      "ExtraInfo5Name": <extra_info_name_5>,
      "ExtraInfo6Name": <extra_info_name_6>,
      "ExtraInfo7Name": <extra_info_name_7>,
      "ExtraInfo8Name": <extra_info_name_8>,
      "ExtraInfo9Name": <extra_info_name_9>,
      "ThrottleLimitEnabled": <throttle_limit_enabled>,
      "ThrottleLimit": <throttle_limit>,
      "ThrottleWaitInterval": <throttle_wait_interval>,
      "ThrottleTimeoutMultiplier": <throttle_timeout_multiplier>
    }
  }
  // ...
}

The possible fields include:

Field	Description
`<version>`	The version of the worker settings schema. Currently there is only version (`1`).
`<std_out_limit_enable>`	Boolean parameter responsible for enabling limit the number of characters per line for standard output handling.
`<std_out_limit>`	Limit the number of characters per line for standard output handling. This value cannot be less than 1 or greater than 10,000.
`<auto_removal_days_enabled>`	Boolean parameter responsible for enabling deletion offline and stalled AWS Portal Workers.
`<auto_removal_days>`	The number of days before offline and stalled AWS Portal Workers will be deleted. This value cannot be less than 1 or greater than 10,000.
`<override_listening_port>`	Boolean parameter responsible for overriding Global Remote Command Port.
`<listening_port>`	Worker Global Remote Command Port Override to. This value cannot be less than 1 or greater than 65,536.
`<gather_resource_usage>`	Boolean parameter responsible for gathering System Resources (CPU and RAM) when rendering Tasks on Linux/Mac.
`<use_domain_name>`	Boolean parameter responsible for using fully qualified domain name (FQDN) for Machine Name instead of host name.
`<use_ip_address>`	Boolean parameter responsible for using Worker’s IP address for Remote Control.
`<exclude_in_none_pool>`	Boolean parameter responsible for excluding Jobs in the ‘none’ Pool.
`<exclude_in_none_group>`	Boolean parameter responsible for excluding Jobs in the ‘none’ Group.
`<sandbox_runs_in_job_env>`	Boolean parameter responsible for running Plugin Sandbox in Job’s Environment.
`<stalled_delay>`	Number of minutes before an unresponsive Worker is marked as Stalled. This value cannot be less than 5 or greater than 10,000.
`<power_management_scan_interval>`	Number of seconds between Thermal Shutdown checks if Pulse is offline. This value cannot be less than 5 or greater than 999,999.
`<extra_info_name_0>`	The human readable name for the ExtraInfo0 Worker property.
`<extra_info_name_1>`	The human readable name for the ExtraInfo1 Worker property.
`<extra_info_name_2>`	The human readable name for the ExtraInfo2 Worker property.
`<extra_info_name_3>`	The human readable name for the ExtraInfo3 Worker property.
`<extra_info_name_4>`	The human readable name for the ExtraInfo4 Worker property.
`<extra_info_name_5>`	The human readable name for the ExtraInfo5 Worker property.
`<extra_info_name_6>`	The human readable name for the ExtraInfo6 Worker property.
`<extra_info_name_7>`	The human readable name for the ExtraInfo7 Worker property.
`<extra_info_name_8>`	The human readable name for the ExtraInfo8 Worker property.
`<extra_info_name_9>`	The human readable name for the ExtraInfo9 Worker property.
`<throttle_limit_enabled>`	Boolean parameter responsible for the Worker throttle limit is enabling.
`<throttle_limit>`	The maximum number of Workers that throttling will allow to be starting their jobs simultaneously. Set to 0 to disable throttling. This value cannot be less than 0 or greater than 100,000.
`<throttle_wait_interval>`	The amount of time (in seconds) a Worker will wait between sending checks and updates to the throttle queue. This value cannot be less than 1 or greater than 100,000.
`<throttle_timeout_multiplier>`	Throttling will use this multiplier on the `<throttle_wait_interval>` property value to determine the total Worker Throttle Update Timeout. The specified value cannot be less than 3 or greater than 100,000.

FAQ¶

Can Passwords/Keys and other Secret/Classified parameters be imported or exported through this?

No. Passwords, keys and other secret/classified parameters are not exposed through this interface.

How is a backup and restore performed through this?
To backup your repository you can simply export the setting to a file:
deadlinecommand ExportRepositorySettings -ExportFilePath C:\Desired\Export\Path\Backup.txt
To restore from the backup, a Replace import operation is suggested:
deadlinecommand ImportRepositorySettings -ImportFilePath C:\Desired\Export\Path\Backup.txt -ImportOperation Replace
How is an import file created?

There are two main workflows that are suggested to create an import file. The first and easiest workflow is to configure an existing repository with the desired setting configuration, and then export the settings to create the file. The second workflow is to export your repository and manually edit values to create the import file.

Repository Settings Importer and Exporter¶

Overview¶

How Is This Different to the Existing Import Repository Settings Feature?¶

Supported Settings¶

Exporting Repository Settings¶

Importing Repository Settings¶

File Format Specification¶

Groups¶

Pools¶

Limits¶

Path Mapping¶

Users¶

Permission Groups¶

Worker Settings¶

FAQ¶

Table of Contents

Previous topic

Next topic