Houdini 20.5 Reference Stand-alone utilities

hserver

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

On this page

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:

  1. If the application is not hserver then it will query hserver for the listing.

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

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

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

  5. The DNS SRV entry is checked. The application will look for _sesi-lm.

  6. mDNS entry is checked. Note sesinetd will set this up if the system allows it. There is no action required for the user.

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

Stand-alone utilities

  • abcconvert

    Convert between Alembic formats.

  • abcecho

    Print information about an Alembic file.

  • abcinfo

    Print information about an Alembic file.

  • chchan

    Copies channel collection to/from action channel format.

  • chcp

    Copies channel collection file to another format.

  • chinfo

    Prints information about a channel collection file.

  • claudio

    Copies CHOP data (clip) to/from audio formats.

  • clchan

    Copies CHOP data (clip) to/from action channel format.

  • clchn

    Copies CHOP data (clip) to/from channel collection format.

  • clcp

    Copies CHOP data (clip) to another format.

  • clinfo

    Prints information about a CHOP data (clip) file.

  • dsmconvert

  • dsmmerge

  • dsparse

    Parses and displays dialog scripts.

  • gabc

    Convert between Alembic and Houdini geometry.

  • gconvert

    Convert between Houdini polygon formats.

  • gdxf

    Converts DXF polygons to/from Houdini format.

  • geodiff

    Display Geometry Differences.

  • geps

    Converts EPS files to Houdini polygon format.

  • giges

  • ginfo

    Prints polygon file statistics.

  • glightwave

    Converts LightWave files to/from Houdini format.

  • gpdb

    Converts .pdb files to/from Houdini format.

  • gplay

    Geometry viewer.

  • gply

    Converts .ply files to/from Houdini format.

  • gptex

    Makes a ptexture image file from a geometry file.

  • greduce

    Reduces polygons in a file.

  • gwavefront

    Converts .obj files to/from Houdini format.

  • hcollapse

    Collapses a directory structure.

  • hcpio

  • hexpand

    Expands hip files into a directory structure.

  • hkey / License Administrator

    Opens a graphical user interface for viewing and managing licenses and license server options.

  • hoiiotool

    Swiss-army knife of image operation tools.

  • hotl utility

    Command line utility to work with .hda/.otl files.

  • hrender

  • hsc

  • hscript

    Command line HScript interpreter.

  • hserver

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

  • htexcache

    Query or modify the disk texture cache.

  • husk

    Command line utility for rendering a USD file using Karma or some other Hydra client.

  • i3dconvert

  • iautocrop

    Crops images based on pixel values.

  • icineon

    Convert images from 10-bit Cineon format to an 8 bit format.

  • icomposite

  • iconvert

    Converts an image of one type to another type.

  • icp

    Isolate a region of an image in a new image.

  • idenoise

    Removes noise from an image file.

  • idiff

    Display Image Differences.

  • iflip - Flip Image

  • iinfo

    Outputs information about an image.

  • ilut

    Generates a lookup table (LUT) from standard channel formats or another LUT.

  • ilutcomp

    Generates a single lookup table (LUT) from from two LUTs.

  • ilutinfo

    Prints information about a lookup table (LUT) file.

  • imaketx

    Creates mipmapped .exr or .rat textures from image files.

  • imdisplay

    Sends an image to an mdisplay window.

  • iprint

    Prints the RGBA values for an image as text.

  • iquantize

    Reduces the number of colors in an image.

  • isixpack

    Generates an environment/reflection map from six images representing the six sides of a cube, or a cross image.

  • itilestitch

    Assemble a series of image files with crop windows into a single image.

  • izg

    Converts Z-depth images to 8-bit grayscale images.

  • Launcher

    The Houdini Launcher downloads, installs, upgrades, and uninstall Houdini and its components.

  • mcacclaim

    Converts an Acclaim motion file to a Houdini script and channel file(s).

  • mcbiovision

    Converts a BioVision motion file to a Houdini script and channel file(s).

  • mcmotanal

    Converts a Motion Analysis TRC motion file to a Houdini script and channel file(s).

  • mcp

    Convert an image sequence to a movie file.

  • minfo

    Prints information about movie files.

  • mqserver

    Message Queue Server for PDG/TOPs

  • py23convert

    Convert Python 2 expressions in HDAs to Python 2/3.

  • renderstatsoverlay

    Generates a (possibly scaled down) version of a rendered image with render statistics baked in.

  • renderstatsreport

    Generates an HTML page containing render statistics from an EXR image.

  • sesictrl

    Sets Houdini license server options from the command line.

  • sesinetd

    The Houdini license server. This program runs in the background managing Houdini licenses.

  • siminfo

    Prints simulation cache file statistics.

  • spiff

    Display Text Differences.

  • spy

    Shell utility for navigating the UNIX filesystem.

  • usdview

    Command line utility for viewing and inspecting USD scenes.

  • vexcache

    Query or modify the VEX compile cache.

  • vexexec

    Execute a cvex shader.