14.0 Virtual hosts
To support the use of resources for which there is no full port of the Legion system, Legion supports the notion of "virtual hosts," host objects that run on a fully-supported Legion platform and represent a resource on an unsupported platform (e.g., a Cray T3E). A virtual host object cannot be used to run normal Legion objects (since by definition there is no Legion port for the represented machine). Instead, it is used to run native jobs, such as existing serial and MPI programs, with the standard Legion tools (legion_run, legion_run_multi, and legion_native_mpi_run). The virtual nature of the host objects therefore remains transparent. The benefits of incorporating virtual hosts into the Legion system are many: transparent, simplified remote execution on the target machine; resource selection and scheduling of the machine through Legion mechanisms; etc.
To configure a virtual host object, use the following three steps:
- START A HOST OBJECT
Start a normal host object (any variety), with the standard legion_starthost command. Instead of starting the host on the desired target machine, however, start it on another machine that can conveniently be used to start jobs on the target machine (e.g., through a queue system, ssh, etc.). This machine is called the physical host. The target machine is called the virtual host.
For example, start a virtual host object to represent the host t3e.npaci.edu on the physical host gigan.sdsc.edu you would run:
$ legion_starthost -N /hosts/NPACI-T3E gigan.sdsc.edu \ /vaults/BootstrapVault
This gives you a normal host object, except that it is not on its host (Figure 14). It uses the physical host's bootstrap vault.
Figure 14: Newly created virtual host object
- SET THE VIRTUAL ARCHITECTURE FOR THE HOST OBJECT
When the host object is first created, it is assumed to represent the architecture of the physical machine on which it resides. You must tell Legion that the host object will actually represent a machine of a different architecture. The legion_set_varch command sets a virtual architecture for a host object.
Continuing the previous example, then, you must set the virtual architecture for host object NPACI-T3E to t3e:
legion_set_varch /hosts/NPACI-T3E t3e
- CONFIGURE THE VIRTUAL RUN SCRIPTS FOR THE HOST
Figure 15: Virtual host object scripts
When legion_run and other commands make use of a virtual host object to start native jobs, they require a mechanism for starting and managing jobs on the virtual host. To fill this need, the virtual host object has three scripts that can be called on the physical host to make use of the virtual host: legion_vrun_run, legion_vrun_status, legion_vrun_kill. These scripts are physically located on the machine host, along with the virtual host object (Figure 15).
Examples of these scripts are in the following locations:
These versions use simple Unix fork/exec to demonstrate the required interface.
These versions are configured for the t3e.npaci.edu system.
To configure the host with its required scripts, use the legion_set_vrun command, indicating the path at which the physical host can find the scripts. Continuing the above example:
$ legion_set_vrun /hosts/NPACI-T3E $LEGION/src/T3E/SDSC
The virtual host can be used normally for native jobs by registering programs for the (virtual host's) appropriate architecture and running them on the virtual host object. Only native jobs can be run on a virtual host. You can not run remote programs, because virtual hosts have no Legion binaries.
From the user's perspective, virtual and physical host objects are indistinguishable. For example, here we register a program for the T3E and run it on t3e.npaci.edu:
$ legion_register_program a.out /home/andrew/my_program t3e
$ legion_run /home/andrew/my_program
Notice that the program was registered and run from the physical host. In this case, there was no need to specify which host executes my_program, but you can use legion_run's -h flag to specify a virtual host, if necessary.