Configuration

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

On this page

Server Configuration
- Server Configuration Options
Client Configuration
Netwtork Folders Configuration
- Network Folder Configuration Sections
- Network Folder Configuration Options

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

Configuration

Server Configuration ¶

Server Configuration Options ¶

Client Configuration ¶

Client Configuration Options ¶

Job Environment ¶

Mapped Network Drives (Windows only) ¶

Netwtork Folders Configuration ¶

Network Folder Configuration Sections ¶

Network Folder Configuration Options ¶

HQueue

Getting started ¶

Managing the farm ¶

Next steps ¶

Guru level ¶