Houdini 20.5 HQueue

Configuration

How to set configuration options for the HQueue server and clients.

On this page

Server Configuration

The HQueue server configuration file is located in the server installation root directory.

Linux

/opt/hqueue/hqserver.ini

Mac

/Library/HQueueServer/hqserver.ini

Windows

C:/HQueueServer/hqserver.ini

You can modify the options in the file and restart the server to modify the server’s behavior.

Linux

To restart the server on a Linux machine running systemd, run:

sudo systemctl restart hqueue-server

If your machine does not use systemd, run:

cd /opt/hqueue
sudo ./scripts/hqserverd restart

Mac

To restart the server on macOS, run:

sudo launchctl unload -F /Library/LaunchDaemons/com.sidefx.hqserver.plist
sudo launchctl load -F /Library/LaunchDaemons/com.sidefx.hqserver.plis

Windows

To restart the server on Windows, go to Control Panel ▸ Administrative Tools ▸ Services and restart the HQueueServer service.

Server Configuration Options

Tip

Use the string %(here)s in an option value to represent the directory that contains hqserver.ini. This is helpful to specify relative paths for file and directory path options such as the job_logs_dir option.

The following is a list of the available server configuration options. These options must be under the [main] section in the configuration file.

Option

Description

active_timeout

The number of minutes since a client’s last heartbeat before HQueue considers the client as inactive and unresponsive. When a client becomes inactive, it is marked as unavailable in HQueue and any jobs currently assigned to the client are marked as abandoned.

If an inactive client becomes active and reports a heartbeat again, then it is marked as available in HQueue and any jobs that the client is still running are marked as running instead of abandoned.

email_to

The email address that receives messages when a system error or notification occurs. smtp_server must also be set.

Note

The HQueue email feature does not currently support email configurations requiring authentication.

error_email_from

The email address that sends messages when a system error occurs or when a job notification is scheduled to be sent out. See the email options in the HQueue Render and HQueue Simulation nodes for more information on emailing job notifications.

The smtp_server server option must also be set for this option to take effect.

Note

The HQueue email feature does not currently support email configurations requiring authentication.

expire_jobs_days

The number of days since a job completed before HQueue permanently deletes the job from the farm. The job’s logs are deleted and the job’s information is purged from the server database.

job_logs_dir

The directory where job logs are saved. Use %(here)s in the directory path to refer to the root directory of the HQueue server installation.

max_fails_allowed

The maximum number of jobs under the same root job that can fail on a single client before HQueue adds a condition to the root job that excludes the client from running other jobs that are under the root job. For example, if max_fails_allowed is 3 and machineA failed 3 child jobs under root job My Job, then HQueue will add a condition to My Job that excludes machineA from running any child jobs in My Job.

Set the max_fails_allowed value to a positive integer. Set the value to zero to disable HQueue from excluding clients from jobs.

port

The server’s listen port. HQueue clients connect to the server at this port and the HQueue website is served on this port.

scheduling_algorithm

The HQueue job scheduler follows the algorithm to determine which job the next available client is assigned to. The possible values are sharecpu and fifo.

sharecpu - (default) The scheduler assigns clients in a way where client CPU resources are distributed roughly evenly across all queued jobs.

fifo - The scheduler assigns clients to the queued jobs with the oldest submission times.

smtp_server

The mail server that delivers messages when a system error occurs or when a job notification is scheduled to be sent out. See the email options in the HQueue Render and HQueue Simulation nodes for more information on emailing job notifications.

Note

The HQueue email feature does not currently support email configurations requiring authentication.

upgrade_priority

The job priority for system jobs that upgrade clients. Clients that need an upgrade are marked with NEEDS UPGRADE in the HQueue web interface’s clients web page.

The following is a list of the server logging configuration options. These options must be under the [logging] section in the configuration file.

Option

Description

file

The location of the server log file. Use %(here)s in the directory path to refer to the root directory of the HQueue server installation. Use stdout or stderr to redirect logging output to the standard out or standard error streams respectively instead of a file.

level

The severity of the messages that the HQueue server logs. HQueue accepts the following log levels~:

  • DEBUG: Low-level system information for debugging purposes.

  • INFO: (default) General system information.

  • WARNING: Information describing a minor problem that has occurred.

  • ERROR: Information describing a major problem that has occurred.

  • CRITICAL: Information describing an immediate failure that has occurred. The server is likely to shutdown in the case of a critical failure.

max_file_size

The maximum size in MB that the log file may reach before it moves to a backup file. Backup log files are created in the same directory as the active log file.

max_backup_files

The number of backup files to keep on disk. When the maximum is exceeded, then the oldest backup file is deleted.

The following is a list of the server database configuration options. These options must be under the [database] section in the configuration file.

Option

Description

engine

The database backend to use for the server. The supported database backends are:

  • SQLite: django.db.backends.sqlite3

  • PostgreSQL: django.db.backends.postgresql

  • MySQL: django.db.backends.mysql

The default database backend is SQLite.

name

The name of the database to use. For SQLite, it is the full path to the database file.

user

The username to use when connecting to the database. This option is not used with SQLite.

password

The password to use when connecting to the database. This option is not used with SQLite.

host

The host to use when connecting to the database. An empty string means localhost. This option is not used with SQLite.

port

The port to use when connecting to the database. An empty string means the default port, which is 3306 for MySQL and 5432 for PostgreSQL. This option is not used with SQLite.

The following is a list of the server’s waitress configuration options. waitress is the web server component that handles incoming network connections. The configuration options for waitress must be under the [waitress] section in the configuration file.

Option

Description

ignore_logging

If set to 1, then logging messages reported by waitress will not be outputted to the HQueue server log file. If set to any value other than 1, then logging messages reported waitress will be outputted to the server log file. Default value is 0.

threads

The number of threads started by waitress to process application logic. If you see “Task queue depth” warnings frequently in the HQueue server log file, then consider increasing the number of threads created by waitress. Default value is 4.

Client Configuration

The HQueue client configruation file is located in the client installation root directory.

Linux

/home/hquser/hqclient/hqnode.ini

Mac

/Library/HQueueClient/hqnode.ini

Windows

C:/HQueueClient/hqnode.ini

You can modify the options in the file and restart the client to modify the client’s behavior.

Linux

To restart the client on a Linux machine running systemd, run:

sudo systemctl restart hqueue-client

If your machine does not use systemd, run:

cd /home/hquser/hqclient
./hqclientd restart

Mac

To restart the client on macOS, run:

sudo launchctl unload -F /Library/LaunchDaemons/com.sidefx.hqclient.plist
sudo launchctl load -F /Library/LaunchDaemons/com.sidefx.hqclient.plist

Windows

To restart the client on Windows, go to Windows Start menu ▸ Task Scheduler. In the Task Scheduler, look for the HQueueClient task, then RMB-click the task and choose End. Then RMB-click the task again and choose Run.

Alternatively, to restart the client on Windows, open a Command Prompt with administrator privileges and in the command prompt, run:

cd C:\HQueueClient
hqclientd.bat restart

You can also restart the client on Windows by opening the Windows File Explorer, navigating to C:\HQueueClient and double-clicking the hqclientd.bat file.

Client Configuration Options

The following is a list of the available client configuration options. These options must be under the [main] section in the configuration file.

Option

Description

auto_upgrade

(optional) Control whether the client automatically upgrades on start up if an upgrade is available. Set the option to 0 to disable automatic upgrade. Set it to 1 to enable automatic upgrade (default).

cpus

(optional) The number of cpus available to the client for running jobs. If the option is not specified, then the number of cpus reported by the operating system are available to the client.

name

Specifying a name is only needed if you plan to run multiple clients on the same machine. Names must be unique for clients running on the same machine.

port

The HQueue server’s listen port. This option works in conjuction with the server option. The client uses the server and port options to locate and connect to the HQueue server.

server

The name or IP address of the machine hosting the HQueue server. This option works in conjuction with the server option. The client uses the server and port options to locate and connect to the HQueue server.

sharedNetwork.mount

(deprecated) The mount point to the HQROOT shared network folder on the client.

Job Environment

You can specify job environment variables in the client configuration file. The variables are defined in the environment of every job that runs on the client. Job environment variables must be set under the [job_environment] section in the client configuration file.

Note

You can set job environment variables to locally override network folder settings. For example, adding HQROOT = /path/to/hqroot under the [job_environment] section will cause the HQROOT network folder to map to /path/to/hqroot for jobs run on the client.

Mapped Network Drives (Windows only)

For Windows clients, you can add a [mapped_network_drives] section to list all of the network drive mappings that the client needs access to when running jobs. The HQueue client ensures that the listed network drives are mapped before the client starts up.

Here is an example of a [mapped_network_drives] section in the hqnode.ini configuration file:

[mapped_network_drives]
H = \\myServer\sharename
P = \\myProjectServer\projectname

In the example above, the HQueue client maps the H: drive to \\myServer\sharename and the P: drive to \\myProjectServer\projectname before the client starts up and runs jobs.

Netwtork Folders Configuration

Network folders are defined in a configuration file on the HQueue server.

Linux

/opt/hqueue/network_folders.ini

Mac

/Library/HQueueServer/network_folders.ini

Windows

C:/HQueueServer/network_folders.ini

You can manage network folders either from the HQueue website or by modifying the network_folders.ini configuration file directly and then restarting the HQueue server.

Linux

To restart the server on a Linux machine running systemd, run:

sudo systemctl restart hqueue-server

If your machine does not use systemd, run:

cd /opt/hqueue
sudo ./scripts/hqserverd restart

Mac

To restart the server on macOS, run:

sudo launchctl unload -F /Library/LaunchDaemons/com.sidefx.hqserver.plist
sudo launchctl load -F /Library/LaunchDaemons/com.sidefx.hqserver.plis

Windows

To restart the server on Windows, go to Control Panel ▸ Administrative Tools ▸ Services and restart the HQueueServer service.

Network Folder Configuration Sections

To register a network folder with HQueue, create a new section in the network_folders.ini configuration file. Choose a section name consisting of only alphanumeric characters and underscores. The section name is an environment variable name in jobs. The environment variable evaluates to the network folder’s path.

You can register multiple network folders with HQueue.

Note

HQueue requires an HQROOT network folder in the configuration. HQROOT is referenced in a few places in Houdini such as the HQueue Render ROP and HQueue Simulation ROP.

If an entry for HQROOT does not exist, then HQueue will create one when the server starts up.

Here is an example of a simple network configuration for a Linux farm:

[HQROOT]
linux = /mnt/hq

[PROJECT_PATH]
linux = /mnt/project

The configuration registers two network folders, HQROOT and PROJECT_PATH, which creates $HQROOT and $PROJECT_PATH environment variables in jobs that run on Linux machines. The $HQROOT and $PROJECT_PATH variables evaluate to /mnt/hq and /mnt/project in the jobs respectively.

Network Folder Configuration Options

The following is a list of the network folder configuration options that can appear under a network folder section. You only need to set the options for the operating system(s) you use in your farm, including the operating system(s) on the workstations that you submit jobs from.

Option

Description

linux

The mount point path to the network folder as it appears on Linux machines.

macos

The mount point path to the network folder as it appears on macOS machines.

windows

The mapped drive letter that connects to the network folder on Windows machines. Alternatively, you can set this option to the UNC path of the network folder.

linux_host_path (deprecated, for backwards compatibility only)

The host server and path of the network folder. This option was used when requesting HQueue to create mount points on Linux machines.

macos_host_path (deprecated, for backwards compatibility only)

The host server and path of the network folder. This option was used when requesting HQueue to create mount points on macOS machines.

windows_host_path (deprecated, for backwards compatibility only)

The host server and path of the network folder in the form of a UNC path. This option was used by HQueue to resolve network folder paths on Windows client machines.

If specified, this option takes precedence over the windows option such that Windows client machines will resolve to this option’s value.

Here is an example of a network folders configuration for a farm consisting of Windows and macOS machines:

[HQROOT]
macos = /Users/Shared/HQShared
windows = H:

[JOB_FILES]
macos = /Users/Shared/job_files
windows = //server_storage/job_files

HQueue

Getting started

  • About HQueue

    HQueue is a general-purpose job scheduling system. You can use it to distribute renders, simulations, and other work to remote clients.

  • Installation

    How to set up a basic HQueue farm.

  • Configuration

    How to set configuration options for the HQueue server and clients.

  • How to submit jobs

    How to put work on the farm.

Managing the farm

  • Managing jobs

    How to view and manage jobs on the farm.

  • Managing clients

    How to use the web interface or local logins to add, remove, restart, and manage client machines.

  • Managing client groups

    How to use the web interface or local logins to create and manage groups of client machines.

  • Network Folders

    How to use the Network Folder management page.

  • Resources

    You can specify what resources (such as licenses) are available on each client, so jobs can be scheduled on clients where they can run.

  • Notes

    Each client and job can have informational notes attached.

Next steps

  • Logging

    HQueue stores separate logs for server errors and scheduling events, and each client also generates a log.

  • Uninstalling

    How to uninstall the HQueue server or client software.

  • FAQs

    Answers to frequently asked questions.

Guru level