Houdini 18.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
License Server Chaining
HTTP communication support
Log File
- HTTP Response Logs Entries
- Statistics Manager Log Entries

Warning

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

hserver is a proxy for the sesinetd server. hserver is automatically started and used by Houdini.

Unlike sesinetd, which is always running in the background, Houdini starts hserver "on demand" the first time it runs. This means the process will be owned by whatever user first runs Houdini. 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). The recommended approach is to manually have hserver start when your computer first starts as leaving it to Houdini can cause multiple hserver instances to start which can cause multiple checkouts and various other problems. 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 similar to karma command line interface. 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.

With this new format you can run –help and –ini-help to view the help information for both the command line and options file.

Windows

Starting with Houdini 18.5.500 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:\Windows\<username>\AppData\Local
The log file location will be in the same houdini_temp folder houdini applications use.

Options file

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

Mac

You can put the hserver.opt options file anywhere in the Houdini path.

Windows

Put the hserver.ini options file in C:\Windows\system32.

Linux

You can put the hserver.opt options file anywhere in the Houdini path.

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.

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.

minConsoleLogLevel=level

This option is the file equivalent of -U.

logToSystem=0|1

Log to the systems log file.

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 the server.

The default is +.+.+.*, where + signs match the current host’s number in the same position, and * matches any number. So the default matches any machine whose IP4 address has the same first three octets as the server host.

For example, you could use 127.0.0.* to only allow local processes to communicate with the server.

writeIPMask=ip_mask

Only clients with IP4 addresses matching this mask are allowed to start the server; shut down the server; pause, resume, or kill a render; or change the license server.

For example, you could use 127.0.0.* to only allow local processes to control the server.

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.

disableFastFDSet=0|1

Use the slower legacy server implementation.

This option will be removed in the next release.

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. Non-graphical applications (hbatch) still cannot use a graphical license.

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.

APIKey=url client_id client_secret

This option is used for login based licensing where an API token is specified instead of logging in. This is very useful for render farm setups where the maintainer does not need to continually sign in.

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.

-D/--debug-mode

Place the server in debug mode.

-d/--run-in-foreground

Run hserver not in the background. This is only available on non-Windows platforms.

-t/--max-threads count

Sets the maxThreads option. The default is 4.

-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. For redundant configurations specify a comma-separated list of server names to contact (Maximum of 3).

-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.

License Partitioning

--user-group group name

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

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).

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".

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). Http communication is turned on by default in hserver.

Warning

Be very careful when using HTTP communication as an 18.0 product is required to properly handle the communication.

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.

The log entry Using fast fd set configuration... is just an entry to signify what mechanism the server is using for detecting data available on a socket. If the server is using fast fd set configuration then on Linux the server is using epoll and OSX its using kqueue (Windows currently does not support such a configuration). If its using the default fd set configuration then its using poll() on all platforms.

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