ParaView:Server Configuration
Overview
Several sites have set of visualization clusters that are available to the users to connect to. These sites may want to provide a default set of server configurations available to the users. Additionally, there may be some options that may be needed to be specified before connecting to the server. All this can be managed using server configuration xmls. This document illustrates a few example use-cases.
Default Servers
When ParaView starts up, it looks for a default_servers.pvsc file in the following locations:
- On Unix-based systems
- ParaView executable directory
- $HOME/.config/ParaView/
- /usr/share/ParaView/
- On Windows
- ParaView executable directory
- %APPDATA%\ParaView\
- %COMMON_APPDATA%\ParaView\
XML Schema
This default_server.pvsc is an xml file describing either the available server configurations. The structure of this xml is as follows:
- The <Servers> tag is the root element of the document, which contains zero-to-many <Server> tags.
- Each <Server> tag represents a configured server:
- The "name" attribute uniquely identifies the server configuration, and is displayed in the user interface.
- The "resource" attribute specifies the type of server connection, server host(s) and optional port(s) for making a connection. See Server Resources.
- The "owner" attribute specifies where the configuration originated, current valid values are "builtin" (the configuration was hard-coded into the application), "site" (the configuration was setup by site administrators), or "user" (the configuration was setup by the user). The client uses this information to set policy, e.g: "builtin" and "site" configurations are read-only, only "user" configurations are stored in per-user preferences, etc.
- The <CommandStartup> tag is used to run an external command to start a server.
- An optional <Options> tag can be used to prompt the user for options required at startup.
- Each <Option> tag represents an option that the user will be prompted to modify before startup.
- The "name" attribute defines the name of the option, which will become its variable name when used as an environment variable, and for purposes of string-substitution in <Argument> tags.
- The "label" attribute defines a human-readable label for the option, which will be used in the user interface.
- The optional "readonly" attribute can be used to designate options which are user-visible, but cannot be modified.
- A <Range> tag designates a numeric option that is only valid over a range of values.
- The "type" attribute controls the type of number controlled. Valid values are "int" for integers and "double" for floating-point numbers, respectively.
- The "min" and "max" attributes specify the minimum and maximum allowable values for the option (inclusive).
- The "step" attribute specifies the preferred amount to increment / decrement values in the user interface.
- The "default" attribute specifies the initial value of the option.
- As a special-case for integer ranges, a default value of "random" will generate a random number as the default each time the user is prompted for a value. This is particularly useful with PV_CONNECT_ID.
- A <String> tag designates an option that accepts freeform text as its value.
- The "default" attribute specifies the initial value of the option.
- A <Boolean> tag designates an option that is either on/off or true/false.
- The "true" attribute specifies what the option value will be if enabled by the user.
- The "false" attribute specifies what the option value will be if disabled by the user.
- The "default" attribute specifies the initial value of the option, either "true" or "false".
- An <Enumeration> tag designates an option that can be one of a finite set of values.
- The "default" attribute specifies the initial value of the option, which must be one of its enumerated values.
- Each <Entry> tag describes one allowed value.
- The "name" tag specifies the value for that choice.
- The "label" tag provides human-readable text that will be displayed in the user interface for that choice.
- Each <Option> tag represents an option that the user will be prompted to modify before startup.
- A <Command> tag is used to specify the external command and its startup arguments.
- The "exec" attribute specifies the filename of the command to be run. The system PATH will be used to search for the command, unless an absolute path is specified.
- The "timeout" attribute specifies the maximum amount of time (in seconds) that the client will wait for the server to start (currently not implemented).
- The "delay" attribute specifies a delay (in seconds) between the time the startup command completes and the time that the client attempts a connection to the server.
- <Argument> tags are command-line arguments that will be passed to the startup command.
- String substitution is performed on each argument, replacing each $STRING$ with the value of a predefined or user-defined variable.
- Arguments whose value is an empty string are not passed to the startup command.
- An optional <Options> tag can be used to prompt the user for options required at startup.
- The <ManualStartup> tag indicates that the user will manually start the given server prior to connecting.
- An optional <Options> tag can be used to prompt the user for options required at startup. Note that PV_SERVER_PORT, PV_DATA_SERVER_PORT, PV_RENDER_SREVER_PORT, and PV_CONNECT_ID are the only variables that make sense in this context.
- Other startup type tags may be added in the future to support e.g: builtin SSH client functionality.
Use Cases
Case One: Simple server connection
In this use-case, we are setting a configuration for a simple server connection (to a pvserver processes) running on a node named "amber1", at port 20234. The pvserver process will be started manually by the user.
<Server name="case1" resource="cs://amber1:20234" owner="site"> <ManualStartup /> </Server>
Here, resource identifies the type if the connection (cs -- implying client-server), host name and port. If the port number i.e. :20234 part is not specified in the resource, then the default port number (which is 11111) is assumed; owner is simply used to determine edit-ability of the configuration from ParaView GUI (as explained earlier). Since the user starts pvserver processes manually, we use <ManualStartup /> tag.
Case Two: Server connection with user-specified port
This is case as Case One except that we want to ask the user each time the port number to connect to pvserver at.
<Server name="case2" resource="cs://amber1" owner="site">
<ManualStartup>
<Options>
<Option name="PV_SERVER_PORT" label="Server Port: ">
<Range type="int" min="1" max="65535" step="1" default="11111" />
</Option>
</Options>
</ManualStartup>
</Server>
Here the only different is the <Options/> element. This element is used to specify run-time options that the user specifies when connecting to the server. The Runtime Environment section defines some predefined variables that be obtained from the user. In this case, we want to show the user an integral spin-box to select the port number, hence we just the <Range /> element to specify the type of the option. When the user connects to this server, he's shown a dialog similar to the following image:
Case Three: Simple connection to a data-server/render-server
This is same as Case One, except that instead of a single server (i.e. pvserver) we are conneting to a separate render-server/data-server (pvrenderserver, pvdataserver) with data server running on port 20230 on amber1 and render server running port 20233 on node amber2
<Server name="case3" resource="cdsrs://amber1:20230//amber2:20233" owner="site"> <ManualStartup /> </Server>
The only different from case 1, is the resource specification. cdsrs indicates that it's a client-dataserver-renderserver configuration. The first host:port pair is the dataserver while the second one is the render server.
Case Four: Connection to a data-server/render-server with user specified server port
This is a combination of Case Two and Case Three, where we want to ask the user for the port number for both the render server and the data server.
<Server name="case4" resource="cdsrs://localhost//localhost" owner="site">
<ManualStartup>
<Options>
<Option name="PV_DATA_SERVER_PORT" label="Data Server Port: ">
<Range type="int" min="1" max="65535" step="1" default="11111" />
</Option>
<Option name="PV_RENDER_SERVER_PORT" label="Render Server Port: ">
<Range type="int" min="1" max="65535" step="1" default="22222" />
</Option>
</Options>
</ManualStartup>
</Server>
The XML is quite self-explanatory given what we have already seen. The options dialog produces by this XML looks as follows:
Case Five: Reverse Connection
By default the client connects to the server processes. However it's possible to tell paraview client to wait for the server to connect to it instead. This is referred to as reverse connection. In such a case the server processes must be started with --reverse-connection or -rc flag.
To indicate reverse connection in the server configuration xml, the only change is suffixing the resource protocol part with "rc" (for reverse connection). eg.
resource="csrc://localhost" -- connect to pvserver on localhost using reverse connection resource="cdsrsrc://localhost//localhost" -- connect to pvdataserver/pvrenderserver using reverse connection.
Case Six: Server connection including starting a pvserver
All the use-cases until now assumed that the user (or someone else) starts the server processes. That can be quite inconvenient. Fortunately, the server configuration is powerful enough to incorporate start of the server processes as well, as illustrated below:
<Server name="case6" resource="cs://localhost" owner="site">
<CommandStartup>
<Options>
<Option name="PV_SERVER_PORT" label="Server Port: ">
<Range type="int" min="1" max="65535" step="1" default="11111" />
</Option>
</Options>
<Command exec="/home/utkarsh/Kitware/ParaView3/ParaView3Bin/bin/pvserver"
delay="5">
<Arguments>
<Argument value="-sp=$PV_SERVER_PORT$" />
</Arguments>
</Command>
</CommandStartup>
</Server>
In this case, the <ManualStartup/> element has been replaced by a <CommandStartup/> element, which contains <Command> elements which are the commands executed to start the server processes. Here, exec is the executable to run while delay indicates the time in seconds the client waits before attempting to connect to the server process. Command line arguments can be passed to the command executed using the <Arguments/> element. All runtime environment variables specified as $name$ are replaced with the actual values eg. in this case $PV_SERVER_PORT$ gets replaced by the port number chosen by the user in the options dialog.
Case Seven: Using connection-id
In many cases, a server clusters may be running pvserver (or pvdataserver/pvrenderserver) processes for different users. In that case we need some level of authentication between the server and the client. This can be achived (at a very basic level) using the connect-id. If specified on the command line when starting the server processes (using --connect-id) then the server will allow only that client which reports the same connection id.
This can be set up as follows:
<Server name="case7" resource="cs://localhost" owner="site">
<CommandStartup>
<Options>
<Option name="PV_CONNECT_ID" label="Connect ID" readonly="true">
<Range type="int" min="1" max="65535" step="1" default="random" />
</Option>
</Options>
<Command exec="/usr/bin/pvserver" delay="5">
<Arguments>
<Argument value="--connect-id=$PV_CONNECT_ID$" />
</Arguments>
</Command>
</CommandStartup>
</Server>
Case Eight: Starting server using custom script with custom user-settable options
This example will illustrate the the server configuration in its full glory. Suppose we have a custom script "MyServerStarter" that takes in a bunch of arguments to start the server process. We want the user to be able to set up values for these arguments when he tries to connect to using this configuration. As an example, let's say MyServerStarter takes the following arguments:
- --use-offscreen -- to indicate use of offscreen rendering
- --use-onscreen -- to indicate on-screen rendering (this can be assumed from absence of --use-offscreen, but we are using it as an example)
- --session-name=<string> -- some string identifying the session
- --mpitype=<mpich1.2|mpich2|openmpi> -- choose between available MPI implementations
- --num-procs=<num> -- number of server processess
- --server-port -- port number passed the pvserver processes
All (except the --server-port) of these must be settable by the user at the connection time. This can be achieved as follows:
<Server name="case7" resource="cs://localhost" owner="site">
<CommandStartup>
<Options>
<Option name="OFFSCREEN" label="Use offscreen rendering">
<Boolean true="--use-offscreen" false="--use-onscreen" default="false" />
</Option>
<Option name="SESSIONID" label="Session Identifier">
<String default="session01"/>
</Option>
<Option name="MPITYPE" label="MPI Implementation">
<Enumeration default="mpich1.2">
<Entry value="mpich1.2" label="MPICH Ver. 1.2" />
<Entry value="mpich2" label="MPICH Ver 2.0" />
<Entry value="openmpi" label="Open MPI" />
</Enumeration>
</Option>
<Option name="NUMPROC" label="Number Of Processes">
<Range type="int" min="1" max="256" step="4" default="1" />
</Option>
</Options>
<Command exec="/tmp/MyServerStarter" delay="5">
<Arguments>
<Argument value="--server-port=$PV_SERVER_PORT$" />
<Argument value="--mpitype=$MPITYPE$" />
<Argument value="--num-procs=$NUMPROC$" />
<Argument value="$OFFSCREEN$" />
<Argument value="--session-name=$SESSIONID$" />
</Arguments>
</Command>
</CommandStartup>
</Server>
Each <Option /> defines a new run-time variable that can be accessed as ${name}$ in the <Command /> section. When the user tries to connect using this configuration, he's shown the following options dialog:
This can be extended to start the server processes using ssh or any scheduler etc. as may be the requirement with the system. This can also be set up to use reverse connection (by changing the protocol in the resource attribute).
