Alfserver provides remote execution services for Pixar's NetRender and Alfred products. Typically the server runs as an unattended service or 'daemon' on each remote host in the renderfarm. It waits for connection requests on a specified set of network service ports, and processes the requests it receives; usually this means launching the Pixar's RenderMan renderer, prman.
Connections typically originate from Alfred dispatchers, either directly due to RemoteCmd directives, or indirectly due to netrender jobs.
alfserver [options]
Options:
-help ... print a brief description, and option list
-version ... print the program version and exit
-v or -l ... enable verbose diagnostics
-q ... quiet, no diagnostics
-debug ... extra diagnostics, and does not become a service/daemon
-a nnn ... accept nnn parallel jobs (the slot count)
Note: defaults to the number of CPUs on the host.
-log file ... specify 'file' as the log file (stderr by default)
-lc file ... specify the license location for the alfserver license,
usually this is taken from $RMANTREE/etc/rendermn.ini.
-supercede ... causes any existing alfserver to 'shutdown drain'
before the new one begins accepting connections.
-p nnn ... use tcp port nnn for nrmserver requests
-s nnn ... use tcp port nnn for alfserver requests
-alf ... enable alfserver (and nrmservice), this is
the default if invoked as 'alfserver'
-nrm ... no alfserver services, this is the default
if invoked as 'nrmserver'
-xnrm ... no nrmserver services (alfserver only)
-xmetrics ... do not report server metrics
-k file ... periodically monitor the given 'kill file'.
If it exists, then temporarily disable this server.
An empty file disables all slots, otherwise only the
slots named in the file are disabled. A file containing
only '0' (the character zero) will enable all slots.
-rmap file ... the named file maps renderer versions to executables.
This is used with cooperating netrender clients to allow a
single server to launch renderers from multiple RenderMan
Toolkit releases: netrender -R xyz -h host ribfile
The map file contains simple key-value pairs, one per line:
xyz /opt/pixar/RenderManProServer-11.5/bin/prman
An alternate 'template' form is also supported, in this case
the argument is not the name of a map file, but is instead a
template for renderer names. This template path must contain
'%s' somewhere within it, this will be replaced by the
version-specific string sent from netrender:
-rmap /installs/prman-%s/bin/prman
-n nnn ... 'nice' increment for netrender jobs, see nice(2), unix only
The options described above can be specified on the command line when the server is launched, this can be desirable because they also appear in current process listings.
If servers are started automatically during system boot-up, then command-line options are usually specified in the rc2 script (or equivalent) which started the server. Explicitly enumerating the options is usually a good idea in these situations, for clarity. This is also useful in cases when options vary from host to host.
Alfserver will also read start-up options from configuration files and environment variables. The most important of these is the alfserver.ini file. The primary version of this file is located in $RMANTREE/etc.
For backward compatibility with the older nrmserver program, $RMANTREE/etc is used as alfserver's default "home directory."
Additional options can be specified in netrman.ini and rendermn.ini. The standard prman locations are searched for these files. The options affecting alfserver are:
Some sites occasionally need to have access to several installed versions of Pixar's RenderMan renderer simultaneously. This happens when testing a new release, or when there are several productions sharing a renderfarm but each is locked into a specific tool set.
New features in alfserver and netrender now allow a single renderfarm server to selectively launch a different renderer on each request.
The version-selection mechanism is driven by the new -R option to netrender, the distributed rendering client program:
netrender -R version_key -h remote_host ribfileThe -R option specifies a site-defined keyword which will be used by alfserver to select a particular version of the renderer. For example:
netrender -R 11.0.1 -h host123 frame01.rib
MTOR users can specify this key in the Render Globals dialog.
In addition, a cooperating alfserver must be launched (once) on each server host. It must be started with the -rmap option which describes how keywords are mapped to renderers.
alfserver -rmap mappingThe mapping string is analyzed by alfserver and interpreted in one of two ways:
alfserver -rmap /opt/pixar/prman-%s/etc/prman
alfserver -rmap /opt/pixar/site/our.mappings
Here are the contents of an example mapping file:
#
# Comments and blank lines are skipped!
#
default /opt/pixar/RenderManProServer-11.5.1/bin/prman
11.5 /opt/pixar/RenderManProServer-11.5/bin/prman
11 /opt/pixar/prman-11.0.1/bin/prman
10 /opt/pixar/prman-10.3/bin/prman
3.9 /usr/local/prman-3.9.0.1/etc/prman
Note: When the -rmap option to alfserver is specified, alfserver may reset RMANTREE before invoking the renderer.
Environment variables can be used in place of some explicit command-line options. In some situations it may be convenient to launch netrender without the "-R" option, but instead control versions using a client-side environment variable. The variable NRMRENDERER will be used as the version keyword if "-R" is not specified.
setenv NRMRENDERER 11.0.1
netrender -h host ribfile
There is no environment variable to control the alfserver mapping
definition, but a master netrman.ini can be configured to contain
an entry for the /alfserver/rmap:
/alfserver/rmap /usr/local/prman-%s/etc/prman
Note: In the case where an -rmap mapping has been specified, but the connecting netrender client has not set an explicit version keyword (i.e. the default netrender case), then alfserver must pick a renderer to use. The default renderer is the one in $RMANTREE/etc, in the the alfserver start-up environment. If RMANTREE is not set in alfserver's environment, then it assumes that it has been started from within a prman/etc directory and looks in "." configuration files.
A more general configuration mechanism is available for commands launched using the alfred RemoteCmd directive. The alfserver.ini file contains the definition of a procedure called AlfEnvConfig, which is used to provide customization of the environment prior to executing each RemoteCmd received from dispatchers. Sites can, and should, customize this procedure to match their requirements.
Alfserver will call AlfEnvConfig each time a RemoteCmd request is received. It will pass in three arguments which can be used to configure the actual command to be executed and its environment. The arguments are:
| $envkey | will contain an arbitrary name (list) as specified in the client alfred script via "Job -envkey" or "RemoteCmd -envkey". It can be used to switch between preset configurations, for example on a shot or project basis. | |
| $client | will contain the requesting client's name in the form "user@host". This can be used to inform per-user configuration settings. | |
| $argv | will contain the command to be executed, such as "prman frame1.rib". This can be used to make per-command configurations. |
The main idea is this: you might have several productions going on simultaneously that all want to share the same renderfarm servers; the AlfEnvConfig procedure allows you to customize the alfserver execution environment appropriately on a per-commmand or per-client basis. A simple pipeline approach is to have everyone on one production use one envkey setting, while everyone on a another should use a different setting. Then your AlfEnvConfig procedure can simply apply hardcoded environment and path settings according to the envkey setting. Obviously you can get more complicated by also taking into account the user's name and the command to be launched.
The return value from the procedure is important! AlfEnvConfig must be careful to return a valid value to its caller. The return value can either be an empty string {} or a modified version of $argv. Alfserver will substitute the returned string for the client-requested command line. If AlfEnvConfig returns an empty string, then the client's command (the initial $argv) will be used.
The global array variable "AlfEnv" will be collected and used as the environment settings for the new process. It is preset to contain a copy of alfserver's environment (the Tcl global array "env"). You can use standard tcl commands to query and modify AlfEnv, for example:
set haveDisplay [info exists AlfEnv(DISPLAY)] set tmpdir $AlfEnv(TMPDIR) set AlfEnv(TEST_MODE) "1" append AlfEnv(PATH) ":/usr/local/bin"
The default AlfEnvConfig defined in alfserver.ini provides additional details on what can be configured, and provides some useful examples as well.
One of the settings that AlfEnvConfig let's you define on a per-command basis is the process ownership. Different sites will have different requirements for remote process attributes, so alfserver supports several "setuid" modes. Modes are set using the built-in function AlfProcessOwnerConfig.
set p [split $client "@"]
set dispatcherUser [lindex $p 0]
set dispatcherHost [lindex $p 1]
AlfProcessOwnerConfig setuid $dispatcherUser
The default alfserver.ini contains an example of using these settings.
Alfred server metrics are used to report various server status values to the dispatching system. Metrics are typically defined in a site-wide manner in the alfred.schedule file, using the metrics definition directives.
These same directives can appear in alfserver.ini (or one of its addendums in RAT_SCRIPT_PATHS). These settings can be used to specify metrics on a per-server basis. Any metrics from alfserver.ini will override identically named definitions from the maitre-d.
Sometimes it is desirable to temporarily disable some or all of the server slots on a particular machine. This can be accomplished in a variety of ways. The master schedule itself can be temporarily altered using the simple schedule editor. For desktop workstations which are also used as servers, users can run the alfred -nimby desktop utility to temporarily block dispatching to their system.
Alfserver provides an additional blocking mechanism, when it is being run on a server machine. This is a kill file which alfserver periodically checks for status changes. The file name must be specified as one of the alfserver start-up options, for example:
alfserver -k /usr/tmp/alfserver.offlineWhen the -k option is specified then alfserver will periodically check to see if the named file exists. If the file exists, and it is empty, then alfserver will disallow any new alfred-dispatched work on the given host.
So, if the system administrators needs to temporarily prevent new renderings from being launched on a particular server, they can just touch the given file>. This causes new work to be blocked, existing tasks will continue to completion. Removing the file unblocks the machine and new work will begin arriving shortly.
The filename chosen is arbitrary, but it is probably best to place it in a public place, with the appropriate permissions. Note: the /tmp directory should probably not be used since it is usually cleared on reboot; if an administrator is servicing a machine, they probably don't want alfred service to be restored immediately on reboot.
In addition to the all-or-nothing existence test, the file can contain text which provides finer granularity of control:
It should be noted that unlike the NIMBY capability, the settings in this file are permanent until the file is changed or modified. So if users start using this file to get remote users "out of their hair," they need to remember to remove it when appropriate.
Alfserver is intended to provide manageable remote execution services for server farms in typical production studios. It is not designed to provide secure remote execution across public networks.
In particular, alfserver represents a potential security risk since it executes all commands as the user who started the server, by default, or it can run as root and temporarily impersonate any requesting user. Therefore, sites should strongly consider the following:
Please contact Pixar customer support for more information.
|
Pixar Animation Studios
|