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:\Windows\<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
You can put the hserver.ini
options file anywhere in the Houdini path. The user preference directory ($HOUDINI_USER_PREF_DIR) is in the path by default so can be used.
Windows
Put the hserver.ini
options file in C:\Program Files\Side Effects Software\Houdini Server\
.
Linux
You can put the hserver.ini
options file anywhere in the Houdini path. The user preference directory ($HOUDINI_USER_PREF_DIR) is in the path by default so can be used.
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 variableLicenseServer
. -
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.
≤ 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.
Houdini license system ¶
New
Starting with Houdini 19 there is a new license system available. Add HOUDINI19_CHECKOUT_SYSTEM=1
to the houdini.env file to enable.
Warning
This system requires hserver to be Houdini 19 or above and a sesinetd of 18.5 or above. Also not all options, behaviors, and environment variables are available in this system. Either they are not needed anymore or can be done via a better method/workflow.
The license products are ordered based on a hierarchy. The hierarchy is based on the financial cost and features available for that product (i.e. FX > Core > Engine). The system works based on a list of lists. Each sub list represents a license mode (Commercial, Education, Indie, Non Commercial). The order of the lists also tells hserver which are more important and which are less important (the first sublist being the most important). The order of the sublists are [Commercial, Education, Indie, Non Commercial]
.
[ [Engine, Core, FX], [Engine EDU, EDU], [Engine Indie, Indie], [Apprentice] ]
License Mode |
License List |
---|---|
Commercial |
Engine, Core, FX |
Education |
Engine EDU, EDU |
Indie |
Engine Indie, Indie |
Apprentice |
Apprentice |
In this example the list of lists can be transformed into [Engine, Core, FX, Engine EDU, EDU, Engine Indie, Indie, Apprentice]
as another way of thinking about the license checkout order. If we take a closer look at the Commercial mode list for hython we have [Engine, Core, FX]
. Engine is listed first because its the best license type that suits the application and it also happens to be the cheapest so most customers will want to use up all of these licenses before trying Core or FX. Since FX is the most expensive and isnt exactly meant for hython but can be used to run hython its placed last as most customers will only want to use this as a last resort. Each list within the main list is for each of the license modes and the items within that list are the individual licenses order by their hierarchies based on the application.
Scenario that can take advantage of this system flexible design:
If a studio has multiple projects with some artists working on show A, some on show B, and some working between the two. Lets say show A can never use FX licenses for any applications. A simple launch script could be created for show A to skip FX licenses by adding --skip-licenses="Houdini-Master"
to the command line or environment for any application that is launched with the launch script. System admins don’t need to manage environment variables, hservers, or any other applications. Instead, they can create launch scripts that are checked into versioning control systems that manage the shows desired license behavior. This allows admins to update the license behavior, push it to the VCS, and the next time the artist updates they will have the new license behavior.
Product Exchanging ¶
Product exchanging is the process of exchanging one license for a lesser or more important license based on the list of lists for the applications requesting licenses. An example of product exchanging:
-
Houdini Core is opened. Checks out a Core license.
-
Houdini FX is opened. Checks out an FX license. The core license is returned and the Houdini Core application is running off of the FX license.
-
Houdini FX is closed. A Core license is checked out and the FX license is returned. The Core application is now running off of the Core license.
Command line options ¶
Note
All command line options here apply to the application and not to hserver.
--list-license-checks
With all of these options its important to be able to view the list of licenses that the application will try to ask for. This option will have the application print out the list of lists used to request a license from hserver. If an entry has a -
character in front of it that means its currently being omitted from the request to hserver. To enable a license to be checked add its internal name to --check-licenses
. To disable a license from being checked add its internal name to --skip-licenses
.
--check-licenses
Some applications may have extra licenses that it can check but may not be checked by default. In the case of Houdini Core, it does not check Houdini FX licenses and with --check-licenses="Houdini-Master"
Houdini Core will turn on checking Houdini FX. To add extra licenses to check add ',' between license names.
Note
Some applications cannot checkout specific licenses regardless of this option. For example, Houdini FX cannot checkout a Houdini Engine license.
Tip
If running Houdini Core and Houdini FX at the same time is common its recommended to add --check-licenses="Houdini-Master"
to Houdini Core environment variable. See below for details.
--skip-licenses
With some setups it might be desired to skip certain licenses for a number of different reasons. A studio might reserve FX licenses for specific roles or projects and might want everyone else to use Core in the meantime. In some cases it might make sense that an artist never wants to grab a Houdini Non Commercial license. With this option specific licenses can be skipped. The syntax for this option is --skip-licenses="Houdini-Non-Commercial"
with ,
being the separator between license names.
--skip-license-modes
This option allows entire license categories to be skipped when requesting a license. This option can be handy when a user does not want to checkout a non-commercial license. commercial
, education
, indie
, and apprentice
are the available options.
--check-license-modes
This option is only useful if a license mode needs to be reverted from a previous --skip-license-modes
option. This has the same options available as --skip-license-modes
.
Environment variables ¶
Since this system uses the application to dictate the license behavior each application has its own environment variable for adding application wide license options. When a set of licensing behaviors is desired for all applications of a specific type (i.e. Houdini Core) the applications license environment variable can be used. The contents of these environment variables is the exact same as the command line options for the application. As an example if every Houdini Core should check for Houdini FX licenses then environment variable would be HOUDINI_CORE_LIC_OPT="--check-licenses=Houdini-Master"
.
Tip
The environment variable for the application is processed and then the command line options are processed. When the command line options get processed it may overwrite any options used in the environment variable.
Environment Name |
Applications |
---|---|
HOUDINI_LIC_OPT |
Houdini |
HOUDINI_CORE_LIC_OPT |
Houdini Core |
HOUDINI_FX_LIC_OPT |
Houdini FX |
HOUDINI_INDIE_LIC_OPT |
Houdini Indie |
HOUDINI_NC_LIC_OPT |
Houdini Apprentice |
HOUDINI_EXPER_LIC_OPT |
Houdini Experimental |
HOUDINI_PDG_LIC_OPT |
PilotPDG |
HOUDINI_HYTHON_LIC_OPT |
Hython and Hbatch |
HOUDINI_MANTRA_LIC_OPT |
Mantra |
HOUDINI_KARMA_LIC_OPT |
Karma |
HOUDINI_MPLAY_LIC_OPT |
Mplay |
HOUDINI_PLUGIN_LIC_OPT |
All Supported Plugins (i.e. Unity, Unreal, Maya, etc). |
When an application is started under this system the application specific license environment variable is checked and then the command line options are checked. For example if Houdini Core is launched the HOUDINI_CORE_LIC_OPT
environment variable is checked and then the command line options are checked for license options.
Guide to moving to Houdini 19 Licensing System ¶
Note
Since these two systems are fundamentally different this guide is only a guide to give an approximately similar behavior in licensing and should not be taken as a way to get the exact licensing behavior from the previous system.
With the new features and change in how this system works there are some items that you should be aware of prior to switching over to this system. The biggest change is all previously existing licensing environment variables and options have been deprecated with this release in favor of the options provided by this new system. Since this system is a fundamental change in how an application can control its licensing it is not possible to change the licensing system at runtime and can only be selected at startup.
Warning
All previously existing licensing options (i.e. environment variables) have been deprecated in this release and will be fully removed in the next release.
The tables below give a rough guide for converting some environment variable values over to Houdini 19 licensing. Some values have been omitted as they no longer apply with this new system.
HOUDINI_SCRIPT_LICENSE |
Houdini 19 Environment Options |
---|---|
hbatch -R |
Add |
PDG_LICENSE_MODE |
Houdini 19 Environment Options |
pdg_only |
No action should be taken as this just uses the existing pdg license list when the application uses one (i.e. PilotPDG). |
engine_only |
Add |
houdini_core_only |
Add |
houdini_fx_only |
Add |
Houdini command line |
Houdini 19 Options |
-apprentice |
Add |
-indie |
Add |
-core |
Add |
Houdini 19 licensing goes from hserver and a complex network of environment variables controlling behavior to the application deciding the full list of licenses that it should be allowed to use. As such hserver options --relax-non-graphical/-g
and --render-only/-n
are no longer used with this system. These options can still be set for applications using the old system but will simply be ignored for this system as they are not necessary as the application controls the licensing behavior for Houdini 19 licensing.
Houdini 19 licensing uses HTTP(S) exclusively and will make NO no attempt at providing any backwards compatibility in behavior of the old system or in communication protocol with the old system. Hserver is able to run using both systems at the same time but upgrading/downgrading will be disabled as hserver is unable to make a decision on what to do as older systems will not provide the necessary information.