.. include:: ../macros.hrst .. include:: ../abbreviations.hrst .. _chapter:ParallelDataVisualization: Remote and parallel visualization ################################# One of the goals of the |ParaView| application is enabling data analysis and visualization for large datasets. |ParaView| was born out of the need for visualizing simulation results from simulations run on supercomputing resources that are often too big for a single desktop machine to handle. To enable interactive visualization of such datasets, |ParaView| uses remote and/or parallel data processing. The basic concept is that if a dataset cannot fit on a desktop machine due to memory or other limitations, we can split the dataset among a cluster of machines, driven from your desktop. In this chapter, we will look at the basics of remote and parallel data processing using |ParaView|. For information on setting up clusters, please refer to the |ParaView| Wiki :cite:`ParaViewServerSetup`. .. admonition:: **Did you know?** :class: tip Remote and parallel processing are often used together, but they refer to different concepts, and it is possible to have one without the other. In the case of ParaView, remote processing refers to the concept of having a client, typically |paraview| or |pvpython|, connecting to a |pvserver|, which could be running on a different, remote machine. All the data processing and, potentially, the rendering can happen on the |pvserver|. The client drives the visualization process by building the visualization pipeline and viewing the generated results. Parallel processing refers to a concept where instead of single core --- which we call a ``rank`` --- processing the entire dataset, we split the dataset among multiple ranks. Typically, an instance of |pvserver| runs in parallel on more than one rank. If a client is connected to a server that runs in parallel, we are using both remote and parallel processing. In the case of |pvbatch|, we have an application that operates in parallel but without a client connection. This is a case of parallel processing without remote processing. Understanding remote processing =============================== Let's consider a simple use-case. Let's say you have two computers, one located at your office and another in your home. The one at the office is a nicer, beefier machine with larger memory and computing capabilities than the one at home. That being the case, you often run your simulations on the office machine, storing the resulting files on the disk attached to your office machine. When you're at work, to visualize those results, you simply launch |paraview| and open the data file(s). Now, what if you need to do the visualization and data analysis from home? You have several options: * You can copy the data files over to your home machine and then use |paraview| to visualize them. This is tedious, however, as you not only have to constantly keep copying/updating your files manually, but your machine has poorer performance due to the decreased compute capabilities and memory available on it! * You can use a desktop sharing system like *Remote Desktop* or *VNC*, but those can be flaky depending on your network connection. Alternatively, you can use |ParaView|'s remote processing capabilities. The concept is fairly simple. You have two separate processes: |pvserver| (which runs on your work machine) and a |paraview| client (which runs on your home machine). They communicate with each other over sockets (over an SHH tunnel, if needed). As far as using |paraview| in this mode, it's no different than how we have been using it so far -- you create pipelines and then look at the data produced by those pipelines in views and so on. The pipelines themselves, however, are created remotely on the |pvserver| process. Thus, the pipelines have access to the disks on your work machine. The ``Open File`` dialog will in fact browse the file system on your work machine, i.e., the machine on which |pvserver| is running. Any filters that you create in your visualization pipeline execute on the |pvserver|. While all the data processing happens on the |pvserver|, when it comes to rendering, |paraview| can be configured to either do the rendering on the server process and deliver only images to the client (remote rendering) or to deliver the geometries to be rendered to the client and let it do the rendering locally (local rendering). When remote rendering, you'll be using the graphics capabilities on your work machine (the machine running the |pvserver|). Every time a new rendering needs to be obtained (for example, when pipeline parameters are changed or you interact with the camera, etc.), the |pvserver| process will re-render a new image and deliver that to the client. When local rendering, the geometries to be rendered are delivered to the client and the client renders those locally. Thus, not all interactions require server-side processing. Only when the visualization pipeline is updated does the server need to deliver updated geometries to the client. .. %One of the main purposes of |ParaView| is to allow you to create %visualizations of large datasets that reside on remote systems %without first bringing the data to a local machine. Transferring the %data is often slow and wasteful of disk and network resources, and the %visualization of large datasets can easily overwhelm the processing %and especially memory resources of even high-performance %workstations. To overcome these challenges, |ParaView| enables processing %data on remote resources closer to where the data resides. % %To see how |ParaView| enables remote processing and explain where data is %stored in the different |ParaView| executables, we refer back to % :numref:`chapter:Introduction` where we saw how to create a simple %processing and visualization pipeline using |paraview|. In this section, we %will create that same pipeline while the |ParaView| client is connected to a %remote server. Because |ParaView| was designed from the beginning to support %remote processing, most of the steps involved in creating the pipeline %are exactly the same as when |ParaView| is used locally without being %connected to a remote server. .. _sec:RemoteVisualization: Remote visualization in ``paraview`` ==================================== Starting a remote server ^^^^^^^^^^^^^^^^^^^^^^^^ To begin using |ParaView| for remote data processing and visualization, we must first start the server application |pvserver| on the remote system. To do this, connect to your remote system using a shell and run: .. code-block:: shell > pvserver You will see this startup message on the terminal: .. code-block:: shell Waiting for client... Connection URL: cs://myhost:11111 Accepting connection(s): myhost:11111 This means that the server has started and is listening for a connection from a client. Configuring a server connection ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ To connect to this server with the |paraview| client, select :guilabel:`File > Connect` or click the |pqConnect| icon in the toolbar to bring up the ``Choose Server Configuration`` dialog. .. figure:: ../images/Server_connect_dialog.png :name: fig:server_connect_dialog :width: 60% :align: center The ``Choose Server Configuration`` dialog is used to connect to a server. .. admonition:: **Common Errors** :class: error If your server is behind a firewall and you are attempting to connect to it from outside the firewall, the connection may not be established successfully. You may also try reverse connections ( :numref:`sec:ReverseConnections`) as a workaround for firewalls. Please consult your network manager if you have network connection problems. Figure :numref:`fig:server_connect_dialog` shows the ``Choose Server Configuration`` dialog with a number of entries for remote servers. In the figure, a number of servers have already been configured, but when you first open this dialog, this list will be empty. Before you can connect to a remote server, you will need to add an entry to the list by clicking on the ``Add Server`` button. When you do, you will see the ``Edit Server Configuration`` dialog as in Figure :numref:`fig:edit_server_configuration_dialog`. .. figure:: ../images/ParaView_UsersGuide_ConfigureNewServerDialog.png :name: fig:edit_server_configuration_dialog :width: 80% :align: center The ``Edit Server Configuration`` dialog is used to configure settings for connecting to remote servers. You will need to set a name for the connection, the server type, the DNS name of the host on which you just started the server, and the port. The default ``Server Type`` is set to Client / Server, which means that the server will be listening for an incoming connection from the client. There are several other options for this setting that we will discuss later. When you are done, click the ``Configure`` button. Another dialog, as shown in :numref:`fig:ConfigureServerManualDialog`, will appear where you specify how to start the server. Since we started the server manually, we will leave the ``Startup Type`` on the default ``Manual`` setting. You can optionally set the ``Startup Type`` to ``Command`` and specify an external shell command to launch a server process. .. figure:: ../images/ParaView_UsersGuide_ConfigureServerManualDialog.png :name: fig:ConfigureServerManualDialog :width: 80% :align: center Configure the server manually. It must be started outside of ParaView. When you click the ``Save`` button, this particular server configuration will be saved for future use. You can go back and edit the server configuration by selecting the entry in the list of servers and clicking the ``Edit Server`` button in the ``Choose Server Configuration`` dialog. You can delete it by clicking the ``Delete`` button. Server configurations can be imported and exported through the ``Choose Server Configuration`` dialog. Use the ``Load Servers`` button to load a server configuration file and the ``Save Servers`` button to save a server configuration file. Files can be exchanged with others to access the same remote servers. .. admonition:: **Did you know?** :class: tip Visualization centers can provide system-wide server configurations on web servers to allow non-experts to simply select an already configured |ParaView| server. These site-wide settings can be loaded with the ``Fetch Servers`` button. Advanced users may also want to specify their own servers in more details. These features are provided thanks to ParaView Server Configuration files (:numref:`sec:ParaViewServerConfigurationfiles`). .. _subsec:ConnectToRemoteServer: Connect to the remote server ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ To connect to the server, select the server configuration you just set up from the configuration list, modify the timeout in the timeout combo box if needed and click ``Connect``. ParaView will try to connect to the server until it succeed or timeout is reached. In that case, you can just retry as needed. Once the connection steps succeed, we are now connected and ready to build the visualization pipelines. .. admonition:: **Common Errors** :class: error ParaView does not perform any kind of authentication when clients attempt to connect to a server. For that reason, we recommend that you do not run |pvserver| on a computing resource that is open to the outside world. ParaView also does not encrypt data sent between the client and server. If your data is sensitive, please ensure that proper network security measures have been taken. The typical approach is to use an SSH tunnel within your server configuration files using native SSH support (:numref:`sec:SecuredSSHTunnel`). Managing multiple clients ^^^^^^^^^^^^^^^^^^^^^^^^^ |pvserver| can be configured to accept connections from multiple clients at the same time. In this case only one, called the master, can interact with the pipeline. Others clients are only allowed to visualize the data. The ``Collaboration Panel`` shares information between connected clients. To enable this mode, |pvserver| must be started with the ``--multi-clients`` flag: .. code-block:: shell pvserver --multi-clients If your remote server is accessible from many users, you may want to restrict the access. This can be done with a connect id. If your client does not have the same connect-id as the server you want to connect to, you will be prompted for a connect-id. Then, if you are the master, you can change the connect-id in the ``Collaboration Panel``. Note that initial value for connect-id can be set by starting the |pvserver| (and respectively |paraview|) with the ``--connect-id`` flag, for instance: .. code-block:: shell pvserver --connect-id=147 The master client can also disable further connections in the ``Collaboration Panel`` so you can work alone, for instance. Once you are ready, you may allow other people to connect to the |pvserver| to share a visualization. This is the default feature when |pvserver| is started with ``--multi-clients --disable-further-connections``. Setting up a client/server visualization pipeline ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Using |paraview| when connected to a remote server is not any different than when it's being used in the default stand-alone mode. The only difference, as far as the user interface goes, is that the ``Pipeline Browser`` reflects the name of the server to which you are connected. The address of the server connection next to the |pqServer| icon changes from ``builtin`` to ``cs://myhost:11111`` . Since the data processing pipelines are executing on the server side, all file I/O also happens on the server side. Hence, the ``Open File`` dialog, when opening a new data file, will browse the file system local to the |pvserver| executable and not the |paraview| client. .. %Where does rendering occur? ^^^^^ % %When the |paraview| client is connected to a server, rendering may take %place on either the client or the server. When the memory footprint of %the geometry representing a pipeline module is below a threshold you %specify, the geometry will be sent to the client for local %rendering. For large data, transferring the geometry to the client may %take too long, or the computing resources on the client machine may be %insufficient to store and display the data. In such cases, rendering %takes place on the server, and rendered images are sent to the client %for display. The geometry memory size threshold used to determine when %rendering occurs on the client versus on the server is defined through %the :guilabel:`Edit > Settings` menu item on the ``Render View`` tab in %the ``Remote/Parallel Rendering Options`` section. % %The full geometry for a pipeline module is used for rendering still %frames when you are not interacting with the 3D scence. If this %geometry is smaller than the geometry memory size threshold, still %frames will be rendered locally on the client. Otherwise, they are %rendered on the server. % %A decimated version of the geometry is optionally available for %rendering while you are interacting with the 3D scene. Decimation is a %process where the number of vertices and faces in a geometry are %reduced in a way that attempts to preserve shape while reducing the %memory footprint of the geometry. If the decimated geometry is less %than the geometry memory size threshold, it will be sent to the client %for client-side rendering during interaction. A separate geometry %memory size threshold that controls when the decimated geometry is %used is available in the ``Interactive Rendering Options`` section of %the ``Render View`` settings panel. % %The use of decimated geometry for interactive rendering and full %geometry for still frames is meant to provide the advantages of local %rendering (higher frame rates and lower latency when interacting) and %remote rendering (greater large data capability) in a large number of %cases. % %Adding filters ^^^^^ % %Adding filters to the pipeline works exactly the same as %when |ParaView| is using the built-in server. To continue our example %from :numref:`chapter:Introduction`, click on the ``Sphere1`` %module in the ``Pipeline Browser`` and select :guilabel:`Filters > %Shrink`. When you click ``Apply`` , the Shrink filter will execute on %the |pvserver| and, depending on the geometry memory size thresholds %you, sends the output geometry to the |paraview| client to render. % %Loading remote data files ^^^^^ % %When the |ParaView| client is connected to a remote server, the files %displayed in the ``Open File`` dialog that appear when :guilabel:`File > %Open` is selected are all on the file system of the remote system. As %in the case when |paraview| is running without a remote connection, the %reader will appear as another pipeline module. .. _sec:RemoteVisualizationPython: Remote visualization in ``pvpython`` ==================================== The |pvpython| executable can be used by itself for visualization of local data, but it can also act as a client that connects to a remote |pvserver|. Before creating a pipeline in |pvpython|, use the ``Connect`` function: .. code-block:: python # Connect to remote server "myhost" on the default port, 11111 >>> Connect("myhost") # Connect to remote server "myhost" on a # specified port >>> Connect("myhost", 11111) Now, when new sources are created, the data produced by the sources will reside on the server. In the case of |pvpython|, all data remains on the server and images are generated on the server too. Images are sent to the client for display or for saving to the local filesystem. .. _sec:ReverseConnections: Reverse connections =================== It is frequently the case that remote computing resources are located behind a network firewall, making it difficult to connect a client outside the firewall to a server behind it. |ParaView| provides a way to set up a *reverse connection* that reverses the usual client server roles when establishing a connection. To use a remote connection, two steps must be performed. First, in |paraview|, a new connection must be configured with the connection type set to reverse. To do this, open the ``Choose Server Configuration`` dialog through the :guilabel:`File > Connect` menu item. Add a new connection, setting the ``Name`` to ``myhost (reverse)'', and select ``Client / Server (reverse connection)`` for ``Server Type`` . Click ``Configure`` . In the ``Edit Server Launch Configuration`` dialog that comes up, set the ``Startup Type`` to ``Manual`` . Save the configuration. Next, select this configuration and click ``Connect`` . A message window will appear showing that the client is awaiting a connection from the server. .. figure:: ../images/WaitingForServerConnection.png :name: fig:WaitingForServerConnection :width: 60% :align: center Message window showing that the client is awaiting a connection from a server. Second, |pvserver| must be started with the ``--reverse-connection`` (``-rc``) flag. To tell |pvserver| the name of the client, set the ``--client-host`` (``-ch``) command-line argument to the hostname of the machine on which the |paraview| client is running. You can specify a port with the ``--server-port`` (``-sp``) command-line argument. .. code-block:: shell pvserver -rc --client-host=mylocalhost --server-port=11111 When the server starts, it prints a message indicating the success or failure of connecting to the client. When the connection is successful, you will see the following text in the shell: .. code-block:: shell Connecting to client (reverse connection requested)... Connection URL: csrc://mylocalhost:11111 Client connected. To wait for reverse connections from a |pvserver| in |pvpython|, you use ``ReverseConnect`` instead of ``Connect`` . .. code-block:: python # To wait for connections from a 'pvserver' on the default port 11111 >>> ReverseConnect() # Optionally, you can specify the port number as the argument. >>> ReverseConnect(11111) .. _sec:ParaViewServerConfigurationFiles: ParaView Server Configuration Files =================================== In the ``Choose Server Configuration`` dialog, it is possible to ``Load Servers`` and ``Save Servers`` using the dedicated buttons. Server configurations are stored in ParView Server Configuration files (.pvsc). These files make it possible to extensively customize the server connection process. During startup, ParaView looks at several locations for server configurations to load by default. * On Unix-based systems and Mac OS X * ``default_servers.pvsc`` in the ParaView executable directory (you can do a ``ls -l /proc//exe`` to identify the executable directory) * ``/usr/share/ParaView/servers.pvsc`` * ``$HOME/.config/ParaView/servers.pvsc`` (ParaView will save user defined servers here) * On Windows * ``default_servers.pvsc`` in the ParaView executable directory * ``%COMMON_APPDATA%\ParaView\servers.pvsc`` * ``%APPDATA%\ParaView\servers.pvsc`` (ParaView will save user defined servers here) Here are a few examples of some common use-cases. Case One: Simple command server startup ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ In this use-case, we are connecting to a locally started pvserver (``localhost``) on the 11111 port, except that the command to start the server will be automatically called just before connecting to the server, we will wait for ``timeout`` seconds before aborting the connection. .. code-block:: xml Here, ``CommandStartup`` element specify that a command will be run before connecting to the server. The ``Command`` element contains the details about this command, which includes ``process_wait``, the time in seconds that paraview will wait for the process to start, ``delay``, the time in seconds paraview will wait after running the command to try to connect and finally, ``exec``, which is the command that will be run and usually contains the path to |pvserver| but could also contain a mpi command to start |pvserver| distributed or to any script or executable on the ``localhost`` filesystem. Case Two: Simple remote 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. .. code-block:: xml Here, ``name`` specify the name of the server as it will appear in the pipeline browser, ``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. Since the user starts |pvserver| processes manually, we use ``ManualStartup``. Case Three: Server connection with user-specified port ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ This is the same as case two except that we want to ask the user each time the port number to connect to the |pvserver| at. .. code-block:: xml Here the only difference is the ``Options`` element. This element is used to specify run-time options that the user specifies when connecting to the server, see this section for a list of available run-time options. In this case, we want to show the user an integral spin-box to select the port number, hence we use the ``Range`` element to specify the type of the option. When the user connects to this server, he is shown a dialog similarly to the following image: .. figure:: ../images/Server_connection_pvsc_case03.png :width: 20% :align: center Case Four: Simple connection to a data-server/render-server ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ This is the same as case two, except that instead of a single server (i.e. |pvserver|), we are connecting to a separate render-server/data-server with |pvdataserver| running on port 20230 on amber1 and |pvrenderserver| running port 20233 on node amber2. .. code-block:: xml The only difference with case two, is the ``resource`` specification. ``cdsrs`` indicates that it is a client-dataserver-renderserver configuration. The first ``host:port`` pair is the dataserver while the second one is the render server. Case Five: Connection to a data-server/render-server with user specified server port ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ This is a combination of case three and case four, where we want to ask the user for the port number for both the render server and the data server. .. code-block:: xml The XML is quite self-explanatory given what we has already been explained above. The options dialog produced by this XML looks as follows: .. figure:: ../images/Server_connection_pvsc_case05.png :width: 30% :align: center Case Six: Reverse Connection ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ By default the client connects to the server processes. However it is possible to tell the paraview client to wait for the server to connect to it instead. This is called a 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. .. code-block:: xml resource="csrc://localhost" -- connect to pvserver on localhost using reverse connection resource="cdsrsrc://localhost//localhost" -- connect to pvdataserver/pvrenderserver using reverse connection. So a simple local reverse connection server configuration, similarly to case one, would look like this .. code-block:: xml Here the ``--client-host=localhost`` in the ``exec`` is actually not needed has this is the default. Case Seven: Server command with option ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ As we have seen in case one, the server can be started by ParaView on connection, but this can be combined with the ``Option`` element as seen in case three to create a dynamically generated server command. .. code-block:: xml As with case one, we are using ``CommandStartup`` and ``Command`` elements. 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 Eight: Using connection-id and random port ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ In many cases, a server cluster may be running multiple 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 achieved (at a very basic level) with the connect-id option. 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 to connect. We also want to avoid port collision with other users, so we use a random port for the server connection. Here is an example similarly to case seven but with a connect-id option and random server port. .. code-block:: xml In this case, the ``readonly`` attribute on the ``Option`` indicates that the value cannot be changed by the user, it is only shown for information purposes. The default value for the ``PV_CONNECT_ID`` and ``PV_SERVER_PORT`` is set to random so that ParaView makes up a value at run time. Of course, in a production environnement they should be assigned by user instead of randomly generated. .. figure:: ../images/Server_connection_pvsc_case08.png :width: 20% :align: center Case Nine: Starting server using ssh ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ In this use case the server process is spawned on some remote host using specifically crafted ssh command. We want the user to be able to specify the ssh executable. We also want to preserve the ssh executable path across ParaView sessions so that the user does not have to enter it each time. .. code-block:: xml .. figure:: ../images/Server_connection_pvsc_case09.png :width: 30% :align: center Note here that the value for the ``exec`` attribute is set to ``$SSH_EXE$`` hence it gets replaced by the user selected ssh executable. We use the optional attribute ``save`` on the ``Option`` element to tell ParaView to preserve the user chosen value across ParaView sessions so that the user doesn't have to enter the username and the ssh executable every time he wants to connect to this server. .. admonition:: **Did you know?** :class: tip While SSH connection can be started by crafting the command, ParaView now support SSH connection natively by specyfing a ``SSHCommand``, see below for more information. Case Ten: Starting server using custom script with custom user-settable options ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ This example will illustrate the full capability of server configuration. Suppose we have a custom script "MyServerStarter" that takes in multiple 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: * ``--force-offscreen-rendering`` -- to indicate use of offscreen rendering * ``--force-onscreen-rendering`` -- to indicate on-screen rendering (this can be assumed from absence of ``--force-offscreen-rendering``, but we are using it as an example) * ``--session-name=`` -- some string identifying the session * ``--mpitype=`` -- choose between available MPI implementations * ``--num-procs=`` -- 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: .. code-block:: xml 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 is shown the following options dialog: .. figure:: ../images/Server_connection_pvsc_case10.png :width: 30% :align: center This can be extended to start the server processes using ssh or any batch scheduler etc. as may be the required by the server administrator. This can also be set up to use reverse connection (by changing the protocol in the resource attribute). Case Eleven: Case Ten + Switch Statement ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ This is same as case ten with one change: We no longer allow the user to choose the number of processes. Instead, the number of processes is automatically selected based on the value of the distribution combobox. .. code-block:: xml .. figure:: ../images/Server_connection_pvsc_case11.png :width: 30% :align: center The ``Switch`` statement can only have ``Case`` statements as children, while the ``Case`` statement can only have ``Set`` statements as children. ``Set`` statements are not much different from ``Option`` except that the value is fixed and the user is not prompted to set that value. Case Twelve: Simple SSH run server command ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ If ``Command`` element let you craft SSH commands, it can be quite complex to do so and the pipeline browser in ParaView may not show the correct server as it could connect through a ssh tunnel. Here, similarly to case one, we use native ssh support to start a pvserver process remotely, on amber1, before connecting to it directly on the default port: .. code-block:: xml First ``SSHCommand`` element is used instead of ``Command`` so that ParaView knows to use native ssh support. Then the ``SSHConfig`` element is used to configure the ssh connection. The ``user`` attribute is the SSH user to use with SSH. If a password is needed, it will be asked on the terminal used to run ParaView, which may not be visible in certain cases. Case Thirteen: SSH run server command with complex config ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Here, similarly to case twelve, we use native ssh support to start a pvserver process remotely, on amber1, before connecting to it directly, but we specify much more specifically the configuration to use. .. code-block:: xml Inside the ``SSHConfig`` element, we use different elements. Here, ``Terminal`` element is used to specify that ParaView will try to open a terminal to ask the user for his password. Here, the terminal executable is specified using the ``exec`` attribute. If it was not, ParaView would try to find one automatically (Linux and Windows). When troubleshooting server configuration, not using ``Terminal`` element is suggested as the terminal will close as soon as the command finish executing. On Linux, it is also possible to replace the ``Terminal`` element by the ``AskPass`` element to specify the ParaView should use SSH_ASKPASS so that a ask-pass binary is used when asking for the SSH password. Finally, the ``SSH`` element specify the SSH binary to use thanks to its ``exec`` attribute. We also use ``PV_SERVER_PORT``, similarly to case seven to let user select the port to connect to. Case Fourteen: SSH run server command with user chosen config ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Here, similarly to case thirteen and five, we use native ssh support to start a pvserver process remotely, on amber1, before connecting to it directly, but we let the user choose interactively some SSH options. .. code-block:: xml Similarly to all other options, SSH related options can be set interactively by the user. Here we let the user set the SSH user, the SSH executable as well as the Terminal executable to use when connecting through ssh. .. figure:: ../images/Server_connection_pvsc_case14.png :width: 30% :align: center Case Fifteen: Ssh run server command with reverse connection ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Similarly to case twelve and thirteen, we use native ssh support to start a reverse connection pvserver process remotely, on amber1, before letting it connect to ParaView using the hostname of the client on static non-default port. .. code-block:: xml The only difference with case twelve is in the ``ressource``, which now contain the reverse connection as well as the usage of ``$PV_CLIENT_HOST$`` in the arguments for the reverse connection, automatically set to the hostname of the client which the server should be able to resolve to an ip to connect to. .. _sec:SecuredSSHTunnel: Case Sixteen: Secured Connection to a Server trough SSH tunnel ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ To communicate securely trough a ssh tunnel, something usually done with a crafted command looking like this: ``ssh -L 8080:localhost:port user@remote /path/to/pvserver --sp=port`` You would then connect on a server on ``localhost:8080`` within ParaView. This is complex to set up either manually of with a ``Command`` element. Also, the true server and port will not appear in the pipeline browser in ParaView. This is however natively supported with ``SSHCommand`` element. Here we create a secured SSH tunnel to amber1 before connecting through the SSH tunnel on the 11111 port. .. code-block:: xml Similarly to case thirteen, we only add a ``PortForwarding`` element in the ``SSHConfig`` element with a ``local`` attribute port, so that ParaView creates a SSH tunnel to connect through. The ``$PV_SERVER_PORT$`` is automatically set to the value of the port to use within the SSH tunnel. In ParaView, the tunnel will be integrated nicely in the UI with the correct port and hostname in the pipeline browser, the server icon will look different with a small lock to note the secured nature of this connection: .. figure:: ../images/Server_connection_pvsc_case16.png :width: 30% :align: center Case Seventeen: Secured Reverse Connection from a Server trough SSH tunnel ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Similarly to case sixteen, a reverse connection through a SSH tunnel would require to craft a command like this one: ``ssh -R 8080:localhost:port user@remote /path/to/pvserver --rc --ch=localhost --sp=8080`` You would then connect on a reverse connection server on localhost:8080 on ParaView. This is complex to set up either manually or with a ``Command`` element. Also, the true server and port will not appear in the pipeline browser in ParaView. This is however natively supported with ``SSHCommand``. Here we create a reverse secured SSH tunnel to amber1 before reverse connecting through the SSH tunnel on a specific port. .. code-block:: xml We also specify a ``PortForwarding`` element in the ``SSHConfig`` with a ``local`` port to trigger the creation of the SSH tunnel. Finally, ``$PV_SSH_PF_SERVER_PORT$`` variable should be use by the server to connect through the SSH tunnel to the client. .. admonition:: **Did you know?** :class: tip While SSH native support can simplify the configuration file, some cases are still not covered and require complex custom command. Client/DataServer/RenderServer SSH setup are not supported natively, nested SSH tunnels are not supported natively either. To create such setup, use of complex Command is needed. PVSC file XML Schema ^^^^^^^^^^^^^^^^^^^^ Here is the exhaustive PVSC file XML schema * The ```` tag is the root element of the document, which contains zero-to-many ```` tags. * Each ```` tag represents a configured server: * The ``name`` attribute uniquely identifies the server configuration, and is displayed in the user interface. * The ``timeout`` attribute specifies the maximum amount of time (in seconds) that the client will wait for the server to start, -1 means forever, default to 60. * The ``resource`` attribute specifies the type of server connection, server host(s) and optional port(s) for making a connection. Values are * ``cs://:`` - for client-pvserver configurations with forward connection i.e. client connects to the server. If not specified, port default to 11111. * ``csrc://:`` - for client-pvserver configurations with reverse connection i.e. server connects to the client. If not specified, port default to 11111. * ``cdsrs://://:`` - for client-pvdataserver-pvrenderserver configurations with forward connection. If not specified, ds-port default to 11111, rs-port default to 22222. * ``cdsrsrc://://:`` - for client-pvdataserver-pvrenderserver configurations with reverse connection. If not specified, ds-port default to 11111, rs-port default to 22222. * The ```` tag is used to run an external command to start a server. * An optional ```` tag can be used to prompt the user for options required at startup. * Each ``