Houdini 20.5 Reference Stand-alone utilities

hserver

Houdini communicates through this proxy server to the sesinetd licensing daemon.

On this page

Options file
Controlling hserver from the command line
Changing Server Listing
License server chaining
HTTP communication support
Log file
- HTTP response logs entries
- Statistics manager log entries
API Key Licensing

Warning

An 18.5 HoudiniServer requires all connected license servers to be of version 18.0.287 or later.

hserver is a service that runs on the same computer running Houdini, Engine, Mantra, Karma, and other products. It acts as a proxy for the sesinetd server and ensures that multiple copies of the same product running on the computer only check out one license of that type from sesinted.

Unlike sesinetd, which is always running in the background, on Linux/OSX Houdini starts hserver “on demand” the first time it runs and Windows runs hserver as a service. The hserver process can continue running in the background after it starts (there is no need to stop and start hserver as you stop and start using Houdini). If you need to run different versions of Houdini it is recommended to start Hserver using the highest version of Houdini that needs to be run prior to starting any applications. On Windows hserver is a proper service so there is no need to manually start hserver.

If you start a Houdini command-line environment, hserver is on the command path. You can manually restart hserver with new command-line options. Or, if you run hserver while an instance is already running, it will communicate with the existing instance (see controlling hserver from the command line below).

New

Hserver is using a new command line and configuration file system. The command line now allows for both short character keys (same as they were in previous versions) but also in a more plain English system (i.e. –user-group=“Beta”). The configuration file is now a proper ini file and all regular syntax for this applies. This means all options MUST be specified as name=value. Be aware some older option files may not follow this syntax and thus hserver will not pickup these options.

Windows

Starting with Houdini 19 hserver can be run as a non-service application similar to hserver on Linux/OSX. This feature is opt-in and is based on if the service is installed which tells hserver if it should be run as a service or not.

Restarting hserver from Houdini is only supported with HTTP(S).
The .sesi_licenses.pref file is in C:\Users\<username>\AppData\Local
The log file location will be in the same houdini_temp houdini applications use.

For more information on how to setup licensing for your use case see the Installation and Licensing guide.

Options file ¶

You can specify hserver options in an options file. This file has different names and locations based on the operating system.

Mac

Put the hserver.ini options file in /Library/Preferences/sesi/hserver/. If hserver is not run as a service put the hserver.ini file in $HOME/Library/Application Support/sidefx/.

Windows

Put the hserver.ini options file in %SystemDrive%\ProgramData\SideFX\. If hserver is not run as a service put the hserver.ini file in %USERPROFILE%\AppData\Roaming\SideFX\.

Linux

Put the hserver.ini options file in /usr/lib/sesi/hserver/. If hserver is not run as a service put the hserver.ini file in $HOME/.local/share/sidefx/.

The options file can contain the following lines. Lines that begin with # are considered comments and ignored.

Log options ¶

logfile=‹path›

A file path to write the log to. See

enableConsole=‹0|1›

Specify if hserver should log to the console. This option does not apply to Windows as all logs are logged to the log file.

disableColor=‹0|1›

Specify if hserver should not use color when logging to the console.

minLogLevel=‹level›

This option is the file equivalent of -u. See -u to see the list of log level values.

minConsoleLogLevel=‹level›

This option is the file equivalent of -U. See -U to see the list of log level values.

logToSystem=‹0|1›

Log to the systems log file. Logging to the hserver log is not affected by this option.

Server options ¶

maxThreads=‹max›

Maximum number of threads this server will use internally. This should be larger than the maximum number of processes you expect will be communicating with hserver at the same time. The default is 6. Values less than 6 are ignored.

readIPMask=‹ip_mask›

Only clients with IP4 addresses matching this mask are allowed to request information from hserver. The default is empty to allow all clients to connect to hserver.

writeIPMask=‹ip_mask›

Only clients with IP4 addresses matching this mask are allowed to start hserver; shut down hserver; pause, resume, or kill a render; or change the license server. The default is empty to allow all clients to connect to hserver.

debugMode=‹0|1›

Specify if hserver should be in debug mode. This is helpful for SideFX developers to narrow down a bug.

useExperimental=‹0|1›

When requesting a license send a list of products we want to try and checkout instead of just sending one at a time.

This requires a connection to an 18.5 license server or higher.

storageLocation=‹file location›

The custom file location to store persistent information used by hserver.

Network render ¶

maxRenders=‹max›

The maximum number of renderer processes that can be used. The default is the number of processors on the machine. If you allow more renders than physical processors in a machine, performance can suffer.

maxUsage=‹pct›

Maximum percentage of CPU to use (do not include a percent sign). If the server process’s load average on its host machine is higher than this number, the server stops accepting renders. Specifying a value greater than 100 disables this check. The default is 101 (disabled).

Be careful using this option. Since it is based on a load average over time, the server may refuse multiple render request before the average falls below the threshold.

renderOnly=‹0|1›

If this is set to 1, only non-graphical licenses can be used. (If both this and graphicsOnly are 1, they are ignored.) This prevents “graphical” applications (applications with an interface, such as Houdini) from using this host.

graphicsOnly=‹0|1›

If this is set to 1, only graphical licenses can be used. (If both this and renderOnly are 1, they are ignored.) This prevents command-line applications (such as hbatch) from using this host.

relaxNonGraphics=‹0|1›

When this is 1, non-Graphical applications can use graphical licenses even when renderOnly is 1.

hold=‹license› ‹secs›

When hserver checks out a license for an application, you can specify that it “hold” the license after use instead of returning it. This makes re-acquiring the license on the same machine much faster, but ties up licenses.

The two arguments are a license type and a number of seconds to hold each license of that type. If the number of seconds is -1, the server holds licenses of that type indefinitely. The default is:

hold Houdini-Master 3600
hold Render -1

(That is, hold FX licenses for one hour, hold Render licenses indefinitely. Render licenses are free so it’s reasonable to hold them indefinitely for future use.)

mantra=version=X.X command="‹command›"

Specify render command to use when starting a remote render with a certain version of the Mantra renderer. This allows you to support multiple versions of the renderer on the same host.

vmantra=version=X.X command="‹command›"

Same as mantra option above.

Api options ¶

readTimeoutMs=‹milliseconds›

The maximum amount of time (in milliseconds) this server waits for a response from an endpoint. The default is 5 minutes. No API call should ever get anywhere near this timeout and it is recommended that this value does not change.

(If hserver is configured to use multiple license servers, this is the time before it gives up on one server in the list and moves on to the next.)

connectTimeoutMs=‹milliseconds›

Specify the connection timeout. This is the number of milliseconds hserver will try to connect to an endpoint before giving up. The default is 30 seconds.

ClientID=‹value›

The client id required to provide the API key. The ClientSecret must also be provided.

ClientSecret=‹value›

The client secret required to provide the API key. The ClientID must also be provided.

enableIPv6=‹value›

Enable IPv6 support.

APIKey=‹client id› ‹client secret›

Specify the client ID and client secret for API key information. See api key licensing for more information.

APIKeyFile=‹file location›

The file location that specifies API key information for use with hserver. See [hkey|hkey|api_key_licensing] for further details.

License partitioning ¶

userGroup=‹group_name›

The user group to request using when requesting a license from a license server.

Controlling hserver from the command line ¶

Information ¶

--help

Show this help.

--ini-help

Show the ini help.

--version

Print the hservers version string.

Log options ¶

-u/--min-logfile-level

Specify the minimum error log level for the log file.

0: None
1: Message (Default)
2: Prompt
3: Warning
4: Error
5: Fatal

-U/--min-console-log-level

Specify the minimum error log level for the console.

0: None
1: Message
2: Prompt (Default)
3: Warning
4: Error
5: Fatal

-B/--enable-console

Enable console logging.

-b/--disable-console-colors

Disable debug console colors.

-Y/--log-to-system

Same as logToSystem in the options file.

Server options ¶

-L/--logfile ‹file›

Sets the logfile option. See the log section for further details.

-D/--debug-mode

Place the server in debug mode.

-d/--run-in-foreground

Run hserver not in the background. This option is available on Linux/OSX and Windows when hserver is not run as a Windows service.

-t/--max-threads ‹count›

Sets the maxThreads option. The default is 6.

-m/--read-mask ‹ip_mask›

Sets the readIPMask option. The default is +.+.+.*.

-M/--write-mask ‹ip_mask›

Sets the writeIPMask option. The default is +.+.+.*.

-E/--enable-experimental

This is the same as useExperimental in the options file.

-C/--force-http

Regardless of the connection url use http communication and do not fallback to the legacy communication protocol.

Network render options ¶

-n/--render-only

Turns on the renderOnly option (only allow non-graphical renders). If both this and -G are given, they are ignored.

-G/--graphics-only

Turns on the graphicsOnly option (only allow graphical renders). If both this and -n are given, they are ignored.

-g/--relax-non-graphical

Turns on the relaxNonGraphics option.

-r/--max-renders ‹max›

Sets the maxRenders option.

-a/--max-usage ‹pct›

Sets the maxUsage option.

Client options ¶

-h/--host ‹host›

Optionally specify a remote host to query/control.

-l/--info

Contact the running hserver for information about it.

-V/--mantra-commands

List all version specific mantra commands.

-q/--quit

Close the running hserver.

-Q/--blocking-quit

Close the running hserver. Before responding to the client the server will relinquish all licenses and any running tasks. This is effectively a blocking shutdown designed to only be used for systems where a graceful shutdown is not possible such as in Docker.

-p/--reload-options

Have the running hserver reload the options file.

-P/--pause-pid ‹pid›

Pause an hservers task by pid.

-R/--resume-pid ‹pid›

Resume an hservers task by pid.

-S/--server ‹servers›

Specify the server by name to select which license server to use.

-K/--kill-pid ‹pid›

Specify the hservers task to kill by pid.

-H/--hold-license ‹license› ‹time›

Specify a license and time to hold the license after its no longer needed by a process.

Api options ¶

-T/--read-timeout-ms ‹millis›

Sets the readTimeout option. The default is 15s.

--connect-timeout-ms ‹millis›

Max amount of time to try and connect to a server.

--clientid ‹value›

The client id required to provide the API key. The ClientSecret must also be provided.

--clientsecret ‹value›

The client secret required to provide the API key. The ClientID must also be provided.

License partitioning ¶

--user-group ‹group name›

The user group to request using when requesting a license from a license server.

Changing Server Listing ¶

When configuring a client machines licensing setup its often required to change the server list to point to the remote license server. The server can either be changed through Hkey ▸ File ▸ Change License Server or through hserver -S <hostname>. Both of these options require intervention from a person which is typically fine for non-studio setusp. The recommended approach for studios looking to automate the installation of Houdini is to use a DNS SRV entry. The advantage with using a DNS SRV entry is that the IT department can update the server listing without needing to push an update to a script or update each client machine manually. Additionally using a DNS SRV integrates nicely with a redundant server setup for your studio.

The order in which an application determines the server listing is as follows:

If the application is not hserver then it will query hserver for the listing.
If the application is hserver and running as a proper service on Windows. The registry key is checked. The location for the registry key is hklm\software\Side Effects Software\Houdini with variable LicenseServer.
If the application is running on Linux/OSX or is not running as a proper service on Windows then the environment variable SESI_LMHOST is checked.

Windows

Since hserver runs under a system account the environment variable must be accessible from the user account along with the system account.
If the application is running on Linux/OSX or is not running as a proper service on Windows then the .sesi_licenses.pref is used.

Windows

Location is %USERPROFILE%/AppData/Local/.sesi_licenses.pref. The location of this file is different for hserver running as a proper service since it runs under a system account. As such its not recommended to adjust this file manually. Let the licensing software adjust this for you.

Linux

Location is $HOME/.sesi_licenses.pref.

Mac

Location is $HOME/.sesi_licenses.pref.
The DNS SRV entry is checked. The application will look for _sesi-lm.
mDNS entry is checked. Note sesinetd will set this up if the system allows it. There is no action required for the user.
If all above options fail to find a listing then localhost is used. Note this is the case for all new installs of Houdini on a fresh machine.

License server chaining ¶

This configuration allows License Servers (sesinetd) to be chained together. This allows license servers to be broken up based on whatever specification you may have (i.e. license product type). When in this configuration Houdini will try to checkout licenses from the first sesinetd server in the list, then if none are free will try the next server, and so on.

To setup this configuration list a set of license servers separated by a semi-colon instead of specifying a single sesinetd to connect to. The first sesinetd in the list will try to execute the command (i.e. checkout) if that fails for some reason (cannot connect, command failed, etc.) then the next sesinetd is tried, then the next and so on. Make sure to place the connection list in quotes when specify the list using “hserver -S”. For example, hserver -S “sesinetd1;sesinetd2”.

If a comma is used instead of a semi-colon (used for a previous unsupported configuration) the application will log an error and internally use reconfigure itself as if a semi-colon was used. The application will not update the cached server info locations as its entirely possible this choice was intentional for previous Houdini versions.

To use this configuration you need at least an 18.0 Houdini License Server (hserver). The sesinetd and Houdini version do not currently have any requirements for this configuration.

HTTP communication support ¶

To enable http communication for the HoudiniServer specify the protocol in the connection url (i.e. hserver -S http://licenseserver) or force http communication by adding -C to the command line (enableHttp 1 to the HoudiniServer options file). Starting with Houdini 18.5 HTTP communication is turned on by default for all applications.

Prior to HTTP support Houdini would use a custom format typically called sesi protocol. This protocol was very rigged and was incredibly difficult to inform the client when something went wrong. Whereas with HTTP the entire protocol is well defined and is well supported in third party applications.

HTTP support table

	≤ 17.5	18.0	18.5	19.0
Hserver (as server)	No	Yes (minimal support)	Yes	Yes (full HTTPS support)
Hserver (as client)	No	Yes	Yes	Yes
Sesinetd	No	Yes (minimal support)	Yes	Yes (full HTTPS support)
Sesictrl/Hkey	No	Yes	Yes	Yes

Log file ¶

The log file is where the server will output information about its health, connection information, and other useful information.

Each log entry is of the form YYYY-MM-DD HH:MM::SS: SYSTEM - MESSAGE.

HTTP Client are messages coming from curl or messages relating to connection/client systems.

Note

If verbose curl is turned on then the output will be logged under this system. Please see curls webpage for a more detailed explanation of their log entries.

Sqlite are messages coming from sqlite itself. Sqlite is mostly used for cookie storing or any other persisten storage needs.
Network Manager is the most common message in the log file. This message typically will come from the server itself. In most cases its used to log information about an incoming connection or response to a request.
Stats Manager are messages that come from the statistics manager. This is typically messages regarding statistics about the running server (i.e. max process time of a request).
Error with api response are messages that are a result of an error with an API response.
Access Token are messages that come from API keys. Typically a message about an invalid API token or unable to update the API token.
Service are messages that come from the service itself.
Application are messages that are related to the application. This error message is extremely uncommon.

The log entry Starting release server v18.5.296 at http://127.0.1.1.:1714 displays if the server is a development server or a release server, the server version, the ip address and the port the server is running on. This can come in handy if you need to know the server version you are running on. This also makes it easier to see what version produced what inside a log file that might have multiple server versions in it.

HTTP response logs entries ¶

A typical HTTP response log entry is of the format METHOD ROUTE HTTP/VERSION" CODE CODE_MESSAGE COMMAND RESPONSE_TIME.

Example entry: 2020-06-17 19:48:02: Network Manager - "POST /api HTTP/1.1" 200 Ok cmd_ping 0.0022450001s

METHOD: POST, GET, HEAD, etc.
ROUTE: /api, /login, /
VERSION: 1.1, 1.0, 0.9
CODE: 200, 400, 404
CODE_MESSAGE: Ok, Bad Request, Not Found
COMMAND: cmd_ping
RESPONSE_TIME: 0.001s

Statistics manager log entries ¶

The process time entry displays the average process time and maximum process time of all requests over the lifetime of the running server. This is measured from the time the request starts processing to the time the process replies.

Example entry: 2020-06-17 19:46:51: Stats Manager - Process Time: avg 0.010118s, max 0.020763s

The queue wait time displays the average and maximum time all requests wait in the queue to be processed by a worker thread. These numbers are from the entire lifetime of the server.

Example entry: 2020-06-17 19:46:51: Stats Manager - Queue Wait Time: avg 3.6666667e-05s, max 6.5e-05s

The queue size displays the current queue size and the maximum size the queue ever got to. These numbers are from the entire lifetime of the server.

Example entry: 2020-06-17 19:46:51: Stats Manager - Queue Size: current 0, max 1

The connection count log entry displays the current number of connections the server is holding onto. For instance, if the server is reusing connections then this count will be representative of these reused connections.

Example entry: 2020-06-17 19:46:51: Stats Manager - Connection Count: 0

API Key Licensing ¶

To add API keys for use in hserver add individual api keys with option APIKey or use an API key file with option APIKeyFile. Option APIKeyFile can point to the same file used with HOUDINI_API_KEY_FILE. To generate a new API key go to sidefx.com and select Register a new application. API keys should be treated with the same level of caution and security as email/password credentials.

See hkey for further details on how to setup API keys for hkey and sesictrl.