User Tools

Site Tools


manual:gbac

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revision Previous revision
Next revision
Previous revision
manual:gbac [2013/01/22 12:44]
atisu [Server side: BOINC project]
manual:gbac [2014/06/20 12:29] (current)
Line 12: Line 12:
   * A PC with virtualization capable INTEL/AMD CPU   * A PC with virtualization capable INTEL/AMD CPU
   * At least 1GB RAM   * At least 1GB RAM
-  * At least 1GB free disk space for the BOINC Client (considering the size of our sample virtual appliance and a typical application with inputs)+  * At least 2GB free disk space for the BOINC Client (considering the size of our sample virtual appliance and a typical application with inputs)
   * Windows XP, Windows 7, Linux (or Mac %%OS%% X)   * Windows XP, Windows 7, Linux (or Mac %%OS%% X)
   * VirtualBox 4.1.8+ installed   * VirtualBox 4.1.8+ installed
Line 23: Line 23:
 ==== Downloading GBAC ==== ==== Downloading GBAC ====
  
-The following components are available for download at https://​sourceforge.net/​projects/​gbac/​files/​+The following components are available for download ​in the downloads section ​at http://gbac.sourceforge.net
  
   * Precompiled GBAC binaries,   * Precompiled GBAC binaries,
Line 36: Line 36:
 In the following sections we detail the components of GBAC. In the following sections we detail the components of GBAC.
  
 +<WRAP box center>
 +{{ :​manual:​gbac:​gbac_components.png?​500 |The components of GBAC}}
 +<WRAP centeralign>​The components of GBAC</​WRAP>​
 +</​WRAP>​
 ==== The wrapper ==== ==== The wrapper ====
  
Line 44: Line 48:
 ==== Configuration file ==== ==== Configuration file ====
  
-GBAC requires the configuration file to have the BOINC logical name of ''​vbox_job.xml''​ (see Section [[manual:genwrapper#​Deployment]] for more details). As its name suggests it uses an XML-like sytax, below is shown an example. All parameters of the file must use the ''<​foo>​value</​foo>''​ or ''<​bar/>''​ syntax and the file must begin with ''<​vbox_job_desc>''​ and end with ''</​vbox_job_desc>''​. The following parameters can be used:+GBAC requires the configuration file to have the BOINC logical name of ''​vbox_job.xml''​ (see Section [[manual:gbac#​Deployment]] for more details). As its name suggests it uses an XML-like sytax, below is shown an example. All parameters of the file must use the ''<​foo>​value</​foo>''​ or ''<​bar/>''​ syntax and the file must begin with ''<​vbox_job_desc>''​ and end with ''</​vbox_job_desc>''​. The following parameters can be used:
  
   * **os_name**:​ OS type to be used. A complete list can be obtained by running the ''​VBoxManage list ostypes''​ command. Usually set here Linux26, Debian for 32bit Linux and Linux26_64 or Debian_64 for 64bit Linux installed in the virtual appliance.   * **os_name**:​ OS type to be used. A complete list can be obtained by running the ''​VBoxManage list ostypes''​ command. Usually set here Linux26, Debian for 32bit Linux and Linux26_64 or Debian_64 for 64bit Linux installed in the virtual appliance.
   * **memory_size_mb**:​ Size of memory in MB to be allocated for the VM.   * **memory_size_mb**:​ Size of memory in MB to be allocated for the VM.
-  * **image_filename**:​ the logical filename of the virtual appliance GBAC will use.+  * **image_filename**:​ the logical filename of the virtual appliance GBAC will use. <wrap important>​ **NOTE:** The filname can end with .gz, in this case GBAC will ungzip it to the current working folder before the VM is created. </​wrap>​
   * **enable_shared_directory**:​ Must be always defined, or filetransfer between guest and host is not possible.   * **enable_shared_directory**:​ Must be always defined, or filetransfer between guest and host is not possible.
 +  * **enable_network**:​ OPTIONAL. Enable network access for the guest. To disable network access remove the line from vbox_job.xml. By default it is disabled. The VA must support network (i.e., DHCP client must be available and enabled) to make use of this feature.
  
 <file xml vbox_job.xml-example>​ <file xml vbox_job.xml-example>​
Line 55: Line 60:
   <​os_name>​Linux26</​os_name> ​   <​os_name>​Linux26</​os_name> ​
   <​memory_size_mb>​512</​memory_size_mb> ​   <​memory_size_mb>​512</​memory_size_mb> ​
-  <​image_filename>​gbac-debian-x86.vdi</​image_filename>​  +  <​image_filename>​gbac-debian-x86.vdi.gz</​image_filename>​  
-  <​enable_shared_directory/> ​+  <​enable_shared_directory/> 
 +  <​enable_network/> 
 </​vbox_job_desc>​ </​vbox_job_desc>​
 </​file>​ </​file>​
-==== GBAC guest extensions ==== 
- 
-The virtual appliance for GBAC contains several additions and modifications compared to a standard Linux installation:​ 
- 
-  * The VirtualBox guest additions (for Linux) installed 
-  * Init script for the GBAC guest addition: ''/​etc/​init.d/​gbac''​ 
-  * The client script which manages the application in the virtual machine: ''/​root/​runme.sh''​ 
-  * A guest-host shared directory named ''/​mnt/​shared/''​ which is mounted during boot time. 
- 
-The GBAC guest extensions are responsible for (a) mounting the guest-host shared directory, (b) copying the legacy application files to the sandbox or extracting the legacy application bundle (see Section [[manual:​gbac#​Legacy application bundle]]) to the sandbox and ( c) executing the legacy application. 
 ==== Legacy application bundle ==== ==== Legacy application bundle ====
  
Line 87: Line 83:
  
   * user name: ''​root''​   * user name: ''​root''​
-  * password: ''​abc123.'' ​-- <wrap important>​**Note**:​ the period at the end is part of the password</​wrap>​+  * password: ''​abc123.''​ <wrap important>​**Note**:​ the period at the end is part of the password</​wrap>​ 
 + 
 +=== GBAC guest extensions === 
 + 
 +The virtual appliance for GBAC contains several additions and modifications compared to a standard Linux installation:​ 
 + 
 +  * The VirtualBox guest additions (for Linux) installed 
 +  * Init script for the GBAC guest addition: ''/​etc/​init.d/​gbac''​ 
 +  * The client script which manages the application in the virtual machine: ''/​root/​runme.sh''​ 
 +  * A guest-host shared directory named ''/​mnt/​shared/''​ which is mounted during boot time. 
 + 
 +The GBAC guest extensions are responsible for (a) mounting the guest-host shared directory, (b) copying the legacy application files to the sandbox or extracting the legacy application bundle (see Section [[manual:​gbac#​Legacy application bundle]]) to the sandbox and ( c) executing the legacy application. 
 + 
 ===== Functionality ===== ===== Functionality =====
  
Line 109: Line 118:
 === Deployment with ''​boinc_appmgr''​ === === Deployment with ''​boinc_appmgr''​ ===
  
-<WRAP important>​**NOTE**:​ You must download the virtual appliance for the GBAC binary package(s) separately from the //​virtual_appliance//​ folder on SourceForge (''​gbac-debian-x86_vdi-rXXXX.tar.bz2''​) or else the installation will fail (''​Required file '​gbac-debian-x86.vdi'​ is missing''​). </​WRAP>​+<WRAP important>​**NOTE**:​ You must download the virtual appliance for the GBAC binary package(s) separately from the //​virtual_appliance//​ folder on SourceForge (''​gbac-debian-x86_vdi-rXXXX.gz''​) ​and rename it to ''​gbac-debian-x86.vdi.gz'' ​or else the installation will fail (''​Required file '​gbac-debian-x86.vdi.gz' is missing''​). You don't need to uncompress the .gz, GBAC will uncompress it when started on a client resource.</​WRAP>​
  
 Easiest way to deploy GBAC is with the //​boinc_appmgr//​ tool. There are three .xml files present in the GBAC binary bundle as shown in the next listing ​ with the **<​PLATFORM>​** part replaced by the current application bundle platform name (e.g., i686-pc-linux-gnu or windows_intelx86):​ Easiest way to deploy GBAC is with the //​boinc_appmgr//​ tool. There are three .xml files present in the GBAC binary bundle as shown in the next listing ​ with the **<​PLATFORM>​** part replaced by the current application bundle platform name (e.g., i686-pc-linux-gnu or windows_intelx86):​
  
 <​code>​ <​code>​
-  gbac-client-<​PLATFORM>​-debug.xml +  gbac-<​PLATFORM>​-client-debug.xml 
-  gbac-client-<​PLATFORM>​.xml ​+  gbac-<​PLATFORM>​-client.xml 
   gbac-master.xml   gbac-master.xml
 </​code>​ </​code>​
Line 121: Line 130:
 These files are passed as parameters (detailed later in this section) for ''​boinc_appmgr'',​ and are for the following: These files are passed as parameters (detailed later in this section) for ''​boinc_appmgr'',​ and are for the following:
  
-  * ''​gbac-client-<​PLATFORM>​-debug.xml''​ - Deploy the GBAC BOINC application with debugging enabled (see section sec:debug for more details on debugging). +  * ''​gbac-<​PLATFORM>​-client-debug.xml''​ - Deploy the GBAC BOINC application with debugging enabled (see section sec:debug for more details on debugging). 
-  * ''​gbac-client-<​PLATFORM>​.xml''​ - Deploy the GBAC BOINC application without debugging enabled.+  * ''​gbac-<​PLATFORM>​-client.xml''​ - Deploy the GBAC BOINC application without debugging enabled.
   * ''​gbac-master.xml''​ - Deploy GBAC server side components, i.e. the validator (''​sample_trivial_validator''​).   * ''​gbac-master.xml''​ - Deploy GBAC server side components, i.e. the validator (''​sample_trivial_validator''​).
  
-From these .xml files you need one client file (either ''​gbac-client.xml''​ or ''​gbac-client-debug.xml''​) and the server file. To deploy GBAC perform the following steps and execute the following commands as the project administrator user:+From these .xml files you need one client file (either ''​gbac-<​PLATFORM>​-client.xml''​ or ''​gbac-client-debug.xml''​) and the server file. To deploy GBAC perform the following steps and execute the following commands as the project administrator user:
  
   - Deploy the GBAC BOINC client application   - Deploy the GBAC BOINC client application
-     * without debugging enabled: <​code>​boinc_appmgr --add --client gbac-client-<​PLATFORM>​.xml</​code>​ +     * without debugging enabled: <​code>​boinc_appmgr --add --client gbac-<​PLATFORM>​-client.xml</​code>​ 
-     * with debugging: <​code>​boinc_appmgr --add --client gbac-client-<​PLATFORM>​-debug.xml</​code>​+     * with debugging: <​code>​boinc_appmgr --add --client gbac-<​PLATFORM>​-client-debug.xml</​code>​
   - Deloy the GBAC server components (i.e. validator): <​code>​boinc_appmgr --add --master gbac-master.xml</​code>​   - Deloy the GBAC server components (i.e. validator): <​code>​boinc_appmgr --add --master gbac-master.xml</​code>​
  
 === Manual deployment === === Manual deployment ===
  
-<WRAP important>​**NOTE**:​ You must download the virtual appliance for the GBAC binary package(s) separately from the //​virtual_appliance//​ folder on SourceForge (''​gbac-debian-x86_vdi-rXXXX.tar.bz2''​) or else the installation will fail (''​Required file '​gbac-debian-x86.vdi'​ is missing''​).</​WRAP>​+<WRAP important>​**NOTE**:​ You must download the virtual appliance for the GBAC binary package(s) separately from the //​virtual_appliance//​ folder on SourceForge (''​gbac-debian-x86_vdi-rXXXX.gz''​) ​and rename it to ''​gbac-debian-x86.vdi.gz'' ​or else the installation will fail (''​Required file '​gbac-debian-x86.vdi.gz' is missing''​). You don't need to uncompress the .gz, GBAC will uncompress it when started on a client resource.</​WRAP>​
  
 In the following we will deploy GBAC for Linux 64bit. GBAC is a BOINC application so the procedure contains no different steps than for any other BOINC application,​ but still there are some specific requirements which we want to detail here. In the following we will deploy GBAC for Linux 64bit. GBAC is a BOINC application so the procedure contains no different steps than for any other BOINC application,​ but still there are some specific requirements which we want to detail here.
Line 150: Line 159:
 </​boinc></​code>​ </​boinc></​code>​
   - Deploy GBAC binaries at the BOINC project.   - Deploy GBAC binaries at the BOINC project.
-     * Create the directory structure ''​gbac/​gbac_1.00_x86_64-pc-linux-gnu''​ inside ''/​apps/''​ for GBAC. The first part (''​gbac/''​) is for the application and the second part inside the first one (''​gbac_1.00_x86_64-pc-linux-gnu''​) is for the current version (''​1.00''​) of the Linux 64 bit application (''​x86_64-pc-linux-gnu''​).+     * Create the directory structure ''​gbac/​gbac_1.80_x86_64-pc-linux-gnu''​ inside ''/​apps/''​ for GBAC. The first part (''​gbac/''​) is for the application and the second part inside the first one (''​gbac_1.80_x86_64-pc-linux-gnu''​) is for the current version (''​1.80''​) of the Linux 64 bit application (''​x86_64-pc-linux-gnu''​).
   - The GBAC files should be copied to the directory created previously with some additional files. The directory should contain the following files: <​code>​   - The GBAC files should be copied to the directory created previously with some additional files. The directory should contain the following files: <​code>​
-gbac_1.00_x86_64-pc-linux-gnu  +gbac_1.80_x86_64-pc-linux-gnu  
-gbac_1.00_x86_64-pc-linux-gnu-debian60-x86.vdi  +gbac_1.80_x86_64-pc-linux-gnu-debian60-x86.vdi.gz  
-gbac_1.00_x86_64-pc-linux-gnu-debian60-x86.vdi.file_ref_info  +gbac_1.80_x86_64-pc-linux-gnu-debian60-x86.vdi.gz.file_ref_info  
-gbac_1.00_x86_64-pc-linux-gnu-vbox_job.xml  +gbac_1.80_x86_64-pc-linux-gnu-vbox_job.xml  
-gbac_1.00_x86_64-pc-linux-gnu-vbox_job.xml.file_ref_info+gbac_1.80_x86_64-pc-linux-gnu-vbox_job.xml.file_ref_info
 </​code>​ </​code>​
-     * The GBAC wrapper binary renamed to ''​gbac_1.00_x86_64-pc-linux-gnu''​. +     * The GBAC wrapper binary renamed to ''​gbac_1.80_x86_64-pc-linux-gnu''​. 
-     * The virtual appliance renamed to ''​gbac_1.00_x86_64-pc-linux-gnu-debian60-x86.vdi''​. +     * The compressed ​virtual appliance renamed to ''​gbac_1.80_x86_64-pc-linux-gnu-debian60-x86.vdi.gz''​. 
-     * An info file for the VA named ''​gbac_1.00_x86_64-pc-linux-gnu-debian60-x86.vdi.file_ref_info''​ with the following contents:<​code>​+     * An info file for the VA named ''​gbac_1.80_x86_64-pc-linux-gnu-debian60-x86.vdi.gz.file_ref_info''​ with the following contents:<​code>​
 <​copy_file> ​ <​copy_file> ​
-<​open_name>​debian60-x86.vdi</​open_name>​+<​open_name>​gbac-debian-x86.vdi.gz</​open_name>​
 </​code> ​ </​code> ​
-     * The configuration file for GBAC named ''​gbac_1.00_x86_64-pc-linux-gnu-vbox_job.xml''​ with the following contents:<​code>​+     * The configuration file for GBAC named ''​gbac_1.80_x86_64-pc-linux-gnu-vbox_job.xml''​ with the following contents:<​code>​
 <​vbox_job_desc> ​ <​vbox_job_desc> ​
  <​os_name>​Linux26</​os_name> ​  <​os_name>​Linux26</​os_name> ​
Line 172: Line 181:
 </​vbox_job_desc>​ </​vbox_job_desc>​
 </​code>​ </​code>​
-     * An info file for the configuration file named ''​gbac_1.00_x86_64-pc-linux-gnu-vbox_job.xml.file_ref_info''​ with the following contents: <​code>​+     * An info file for the configuration file named ''​gbac_1.80_x86_64-pc-linux-gnu-vbox_job.xml.file_ref_info''​ with the following contents: <​code>​
 <​copy_file> ​ <​copy_file> ​
 <​open_name>​vbox_job.xml</​open_name>​ <​open_name>​vbox_job.xml</​open_name>​
Line 188: Line 197:
 The ''​wsclient''​ utilility of 3G Bridge will be used for task submission in Section sec:​usecase.,​ but first 3G Bridge has to be configured for GBAC. We assume that it is already deployed and configured for the BOINC project through the ''​DC-%%API%%-Single''​ plug in and only the GBAC related configuration is missing. See the [[manual:​3gbridge|3g-bridge manual]] for more information and examples how to deploy 3G Bridge on a BOINC project. The following steps should be performed for GBAC: The ''​wsclient''​ utilility of 3G Bridge will be used for task submission in Section sec:​usecase.,​ but first 3G Bridge has to be configured for GBAC. We assume that it is already deployed and configured for the BOINC project through the ''​DC-%%API%%-Single''​ plug in and only the GBAC related configuration is missing. See the [[manual:​3gbridge|3g-bridge manual]] for more information and examples how to deploy 3G Bridge on a BOINC project. The following steps should be performed for GBAC:
  
-  - Open the ''/​master/​3g-bridge/​dc-api.conf''​ and add the following contents to the end of the file:<​code>​[Client-gbac]  +  - Open the ''/​master/​3g-bridge/​dc-api.conf''​ and add the following contents to the end of the file:<​code>​[Client-gbac] 
-MaxOutputSize = 210485760  +MaxOutputSize = 210485760 
-MaxDiskUsage = 2048000000  +MaxDiskUsage = 2048000000 
-MaxMemUsage = 768MiB  +MaxMemUsage = 768MiB 
-EnableSuspend = false  +EnableSuspend = false 
-MinQuorum = 1  +MinQuorum = 1 
-TargetNResults = 1  +TargetNResults = 1 
-MaxErrorResults = 2  +MaxErrorResults = 2 
-MaxTotalResults = 5  +MaxTotalResults = 5 
-MaxSuccessResults = 5 +MaxSuccessResults = 5
 MaxFPOps = 1.0e+16 MaxFPOps = 1.0e+16
 </​code>​ The options set here are detailed in the DC-%%API%% manual((SZTAKI Desktop Grid - DC-%%API%% per-client configuration options. http://​www.desktopgrid.hu/​storage/​dcdoc/​backends.html#​id2593385)) in section '​Per-client configuration'​. The parameter ''​MaxFPOps''​ determines maximum floating-point operations and thus the run time limit for workunits. Increase this (and restart the project) when GBAC is terminated by the BOINC Client because it reached this limit. Same applies for ''​MaxOutputSize'',​ ''​MaxDiskUsage''​ and ''​MaxMemUsage''​.</​p>​ </​code>​ The options set here are detailed in the DC-%%API%% manual((SZTAKI Desktop Grid - DC-%%API%% per-client configuration options. http://​www.desktopgrid.hu/​storage/​dcdoc/​backends.html#​id2593385)) in section '​Per-client configuration'​. The parameter ''​MaxFPOps''​ determines maximum floating-point operations and thus the run time limit for workunits. Increase this (and restart the project) when GBAC is terminated by the BOINC Client because it reached this limit. Same applies for ''​MaxOutputSize'',​ ''​MaxDiskUsage''​ and ''​MaxMemUsage''​.</​p>​
Line 207: Line 216:
 GBAC requires the BOINC Client and VirtualBox to be installed on all resources. Installing VirtualBox is a straightforward procedure which we don't detail here. Installing and configuring BOINC for GBAC is also simple, but there are some specific steps required which we detail here. GBAC requires the BOINC Client and VirtualBox to be installed on all resources. Installing VirtualBox is a straightforward procedure which we don't detail here. Installing and configuring BOINC for GBAC is also simple, but there are some specific steps required which we detail here.
  
-  - During install make sure that //Protected application execution// is not selected (see Figure fig:​boincinstall). If you need the //Protected application execution// option please see Section sec:protected ​for more details. {{ :​manual:​gbac:​boinc_install_1.png?​ |BOINC install dialog on Windows}}+  - During install make sure that //Protected application execution// is not selected (see next figure). If you need the //Protected application execution// option please see [[:manual:​gbac#​BOINC Client on Windows: sandboxed and service installation]] ​for more details. ​<WRAP box center>{{ :​manual:​gbac:​boinc_install_1.png?​ |BOINC install dialog on Windows}}<WRAP centeralign>​BOINC install dialog on Windows</​WRAP></​WRAP>​
   - After the BOINC Manager started select //Advanced View// (see figures below).   - After the BOINC Manager started select //Advanced View// (see figures below).
-  - In Advanced View select the //Run always// option of the //​Activity//​ option (see Figure fig:​boincadvancedview.). This is required as a workaround for a bug in the current version, see Section fig:cpususpend. ​for more details.+  - In Advanced View select the //Run always// option of the //​Activity//​ option (see next figure). This is required as a workaround for a bug in the current version, see [[:manual:​gbac#​Non-BOINC workload too high and client suspends computation]] ​for more details.
   - Finally connect the Client to the BOINC Project where GBAC is deployed.   - Finally connect the Client to the BOINC Project where GBAC is deployed.
  
  
-{{ :​manual:​gbac:​boinc_activity_cut.png?​600 | //Advanced view// mode of the BOINC Manager with //Run always// option selected in the //​Activity//​ menu}} +<WRAP box center>​ 
 +{{ :​manual:​gbac:​boinc_activity_cut.png?​600 | //Advanced view// mode of the BOINC Manager with //Run always// option selected in the //​Activity//​ menu}}<WRAP centeralign>//​Advanced view// mode of the BOINC Manager with //Run always// option selected in the //​Activity//​ menu</​WRAP>​ 
 +</​WRAP>​
  
 +<WRAP box center>
 {{ :​manual:​gbac:​boinc_simple_view.png?​ | BOINC simple view}} {{ :​manual:​gbac:​boinc_simple_view.png?​ | BOINC simple view}}
 +<WRAP centeralign>​BOINC simple view</​WRAP>​
 +</​WRAP>​
  
 +<WRAP box center>
 {{ :​manual:​gbac:​boinc_advanced_view.png?​600 | BOINC advanced view}} {{ :​manual:​gbac:​boinc_advanced_view.png?​600 | BOINC advanced view}}
- +<WRAP centeralign>​BOINC advanced view</​WRAP>​ 
- +</​WRAP>​
 ==== Use case: job submission via 3G Bridge and execution ==== ==== Use case: job submission via 3G Bridge and execution ====
  
Line 269: Line 281:
    ​LPSolvOutput.txt http://​example.com/​3g-bridge-gbacsample/​b8/​b82ca283-e9c1-49bf-98be-335adc4b4252/​LPSolvOutput.txt    ​LPSolvOutput.txt http://​example.com/​3g-bridge-gbacsample/​b8/​b82ca283-e9c1-49bf-98be-335adc4b4252/​LPSolvOutput.txt
 </​code>​ </​code>​
 +
 +==== Passing environment variables for jobs ====
 +
 +GBAC allows to pass environment variables to the job/ application executed in the VM. For the job a separate environment will be set up and the variables will be exported there. GBAC has a ''​gbac_job.xml''​ configuration file that that serves two purposes: ​
 +
 +   - The main executable and command line can be defined here as an alternative to the ''<​MAIN_EXE>​.app.tar.gz''​ app bundle format
 +   - Environment variables can be passed to the application.
 +
 +The format of ''​gbac_job.xml''​ is as follows:
 +
 +<file xml gbac_job.xml-example>​
 +<​gbac_job>​
 +  <​setenv>​FOO="​foo"</​setenv>​
 +  <​setenv>​BAR="​bar"</​setenv>​
 +  <​main_executable>​emmil_i686-pc-linux-gnu</​main_executable>​
 +</​gbac_job>​
 +</​file>​
 +
 +   * It may contain multiple ''<​setenv>​VARIABLE="​VALUE"</​setenv>''​ statements where the ''​VARIABLE''​ with value ''​VALUE''​ will be exported for the application in the VM. 
 +   * It may contain a single ''<​main_executable><​MAIN_EXE></​main_executable>''​ line defining the main executable (''​MAIN_EXE''​) of the application.
 +   * The application bundle (''​*.app.tar.gz''​) can not contain the ''​gbac_job.xml'',​ it must be  separate input file for the job.
 +
 ===== Application development ====== ===== Application development ======
  
Line 277: Line 311:
   * Any operating system, library or piece of software can be used, but open source licensed ones are preferred, otherwise each host where GBAC job is running requires licenses.   * Any operating system, library or piece of software can be used, but open source licensed ones are preferred, otherwise each host where GBAC job is running requires licenses.
   * Each virtual appliance must contain the VirtualBox guest extensions installed otherwise it is not possible to transfer files between guest and host.   * Each virtual appliance must contain the VirtualBox guest extensions installed otherwise it is not possible to transfer files between guest and host.
-  * Each virtual appliance must contain the GBAC guest extensions (see Section ​sec:guestextensions).+  * Each virtual appliance must contain the GBAC guest extensions (see Section ​[[manual:gbac#GBAC guest extensions|GBAC guest extensions]]). 
 + 
 +In the following section we detail the steps for deploying GBAC Guest Tools in the CernVM VA, that is a Scientific Linux (Red Hat) based image. 
 + 
 +=== CernVM === 
 + 
 +The following steps needed to deploy GBAC Guest Tools in the CernVM VA: 
 + 
 +  - Install VirtualBox Guest Additions 
 +  - Create a user named ‘vmsandbox'​ with its home in /​home/​vmsandbox/:​ <​code>​ 
 +adduser vmsandbox 
 +</​code>​ 
 +  - Add vmsandbox to the wheel group: <​code>​ 
 +usermod -a -G wheel vmsandbox 
 +</​code>​ 
 +  - Create the shared mount directory: <​code>​ 
 +mkdir -p /​mnt/​shared 
 +</​code>​ 
 +  - Create a log directory inside the vmsandbox users home directory: <​code>​ 
 +mkdir -p /​home/​vmsandbox/​logs 
 +</​code>​ 
 +  - Note the user and group id of vmsandbox user, by running the ‘id vmsandbox’ command. The output should be similar to this: <​code>​ 
 +$>id vmsandbox 
 +uid=500(vmsandbox) gid=501(vmsandbox) groups=10(wheel),​501(vmsandbox) 
 +</​code>​ The number after uid= is the user id (500 in this case), and the number after gid= is the group id (501 in this case). 
 +  - Add the following line to /etc/fstab where the number after gid= is the group id and  the number after uid is the user id: <​code>​ 
 +shared ​    /​mnt/​shared ​    ​vboxsf ​    ​gid=501,​uid=500 ​    0 0 
 +</​code>​ 
 +  - Copy the GBAC guest tools to the VM (Here it is assumed the shared directory ‘shared’ contains these files. Add a share named ‘shared’ to the vm in VirtualBox and reboot it): <​code>​ 
 +cp /​mnt/​shared/​gbac /​etc/​init.d/​ 
 +cp /​mnt/​shared/​guest-tools.sh /​home/​vmsandbox 
 +</​code>​ 
 +  - Add gbac script to chkconfig: <​code>​ 
 +chkconfig --add gbac 
 +</​code>​ 
 +  - Enable gbac script for runlevel 3 (and disable for runlevel 2): <​code>​ 
 +chkconfig —level 2 gbac off 
 +chkconfig —level 3 gbac on 
 +</​code>​ 
 +  - Add the following to the END of /​etc/​sudoers (make sure sudoers is installed): <​code>​ 
 +Defaults:​vmsandbox ​       !requiretty 
 +vmsandbox ALL = (root) NOPASSWD: /​sbin/​shutdown -h now 
 +</​code>​
  
 ==== Debugging applications ==== ==== Debugging applications ====
Line 301: Line 377:
   * '''​not_standalone''':​ For vm name generation debugging, assume false where standalone mode is checked in the wrapper code.   * '''​not_standalone''':​ For vm name generation debugging, assume false where standalone mode is checked in the wrapper code.
  
 +<WRAP box center>
 {{ :​manual:​gbac:​boinc_gbac_vm.png?​600 | GBAC with ''<​display_gui/>''​ set in the debug config file}} {{ :​manual:​gbac:​boinc_gbac_vm.png?​600 | GBAC with ''<​display_gui/>''​ set in the debug config file}}
 +<WRAP centeralign>​GBAC with ''<​display_gui/>''​ set in the debug config file</​WRAP>​ 
 +</​WRAP>​
 === Disabling automatic shutdown of the virtual machine === === Disabling automatic shutdown of the virtual machine ===
  
 The virtual machine started by GBAC will shutdown automatically when the task finished (or if no task can be started). For debugging purposes it is possible to disable this behavior: if a file named ''​no_shutdown''​ is present in the guest-host shared directory the virtual machine will keep running and can be shut down only by hand (either from the console or from the VirtualBox menu). The virtual machine started by GBAC will shutdown automatically when the task finished (or if no task can be started). For debugging purposes it is possible to disable this behavior: if a file named ''​no_shutdown''​ is present in the guest-host shared directory the virtual machine will keep running and can be shut down only by hand (either from the console or from the VirtualBox menu).
 +
 +To run the GBAC VA as a "​standalone"​ virtual machine do the following steps:
 +
 +  - Create a new virtual machine in VirtualBox
 +  - Add a SATA controller and bind the VA to Port 0
 +  - Add a shared folder named ''​shared''​ with ''​Full''​ access to the virtual machine. <wrap important>​Make sure that the //​automount//​ option is not selected!</​wrap>​
 +  - Place a file named ''​no_shutdown''​ into this shared folder.
 +  - Optional: Enable networking (e.g., NAT). It will be detected and the network interface enabled.  ​
 +  - Start up the virtual machine. It won't shut itself down automatically. (The root password is '​abc123.'​) ​
 +
 +=== Display VBox VM Window ===
 +
 +Place a file named ''​display_gui''​ in the working directory of GBAC before the VM is started to start VirtualBox in windowed mode (same as the display_gui option of vbox_debug.xml).
 ==== Installing additional components in the default VA via network ==== ==== Installing additional components in the default VA via network ====
  
Line 324: Line 415:
   - You can use ''​apt-get install ...''​ to install additional packages.   - You can use ''​apt-get install ...''​ to install additional packages.
  
 +==== Log files ====
 +
 +GBAC provides 3 log files when requested:
 +
 +  * Standard error (''​gbac-app.stdout''​), ​
 +  * Standard output (''​gbac-app.stderr''​) and 
 +  * a full debug log (''​gbac-exec.log''​)
 +
 +These files should be specified as output files e.g., with ''​wsclient''​ (see code below) and will be automatically generated by GBAC.
 +
 +<WRAP box center><​code bash>
 + ​wsclient \
 + [...]
 + -o gbac-app.stdout \
 + -o gbac-app.stderr \
 + -o gbac-exec.log
 +</​code>​
 +<WRAP centeralign>​A GBAC log example with ''​wsclient''</​WRAP>​
 +</​WRAP>​
 ===== Known limitations and workarounds ===== ===== Known limitations and workarounds =====
  
Line 336: Line 446:
 **(L)** We found that BOINC has sometimes trouble detecting VirtualBox (//registry virtualization//​),​ thus GBAC is also not able to detect it and will permanently fail. **(L)** We found that BOINC has sometimes trouble detecting VirtualBox (//registry virtualization//​),​ thus GBAC is also not able to detect it and will permanently fail.
  
-**(R)** We are investigating this issue, ​currently we don't have any workaround for it.+**(R)** We are investigating this issue, ​and __still__ ​don't have any workaround for it.
 ==== BOINC Client on Windows: sandboxed and service installation ==== ==== BOINC Client on Windows: sandboxed and service installation ====
  
Line 365: Line 475:
 ===== Contact ====== ===== Contact ======
  
-Please report bugs and provide feedback to desktopgrid@lpds.sztaki.hu+Please report bugs and provide feedback ​via email to //desktopgrid ​**AT** ​lpds **DOT** ​sztaki ​**DOT** hu//.
  
manual/gbac.txt · Last modified: 2014/06/20 12:29 (external edit)