<h1>torque_rm</h1>

<p>Example of configuration:</p>

<pre><code>TORQUE.qcommands_path='/usr/bin' TORQUE.server = “my_grid.remote.net” job = TORQUE::Qsub.new m: “abe”, name:“FirstTest”, shell: '/bin/bash', ppn: 4 job.script = “echo `hostname`; sleep 1000” job.submit stats=TORQUE::Qstat.new

# get all stats on all jobs stats.query

# select stats from only the submitted job stat.query job_id: job.id

# it is also possible to get the stats from a single job job.stat </code></pre>

<h2>HowItWorks</h2>

<p>TorqueRm uses Rye as interface with a local/remote computer/server, using ssh, so every command is a executed with ssh. Rye also guarantees a certain level of security disabling dangerous operations like moving, deleting files or traversing recursevely a directory. Obviously this feature can be disabled, but for now it is the default way TorqueRm operates.</p>

<h2>Job Configurations</h2>

<h3>Where files are saved ?</h3>

<p>By default torque_rm creates/transfers files in the user home directory ~. It's possible to change this default behaviour setting an internal variable when a job is created on managed. Considering the example above configuring the wrinting directory before submitting the job:</p>

<pre>job.root_directory = '/my/personal/path' </pre>

<p>or</p>

<pre>job.working_directory = '/my/personal/path' </pre>

<p>root has precedence on working directory. It is possible to configure the root/working directory at the time of creation of the new job using the usual hash key/value convention.</p>

<pre>:root_directory =&gt; '/my/personal/path' </pre>

<p>or </p>

<pre>:working_directory =&gt; '/my/personal/path' </pre>

<h2>Configuration</h2>

<h3>Saving</h3>

<p>It is possible to save in a configuration file server and path. User can sare a configuration file:</p>

<pre>TORQUE.qcommands_path='/usr/bin' TORQUE.server = "my_grid.remote.net" TORQUE.save_config </pre>

<p>it will create a YAML file ~/.torque_rm.yaml in the user home directory. In case the user wants to save the configuration in a custom location </p>

<pre>TORQUE.save_config "file_name" </pre>

<h3>Loading</h3>

<p>Read a configuration from the dafult location ~/.torque_rm.yaml</p>

<pre>TORQUE.load_config </pre>

<p>In case the user has a custom file</p>

<pre>TORQUE.load_config "file_name" </pre>

<h2>Define a job using a DSL</h2>

<pre><code>rhostname = TORQUE::Qsub.new do |job|

  job.m = "abe"
  job.name = "FirstTest"
  job.shell = '/bin/bash'
  job.ppn = 4
  job.script = "echo `hostname`; sleep 1000"
end

rhostname.submit rhostname.stat </code></pre>

<h2>Stats</h2>

<p>When a job is submitted, is possible to get some stats</p>

<pre><code>[{:job_id=&gt;“2750.sun.universe.space”@1387,

:job_name=&gt;"FirstTest"@1421,
:job_owner=&gt;"helios@sun.universe.space"@1447,
:job_state=&gt;"Q"@1489,
:queue=&gt;"bio"@1503,
:server=&gt;"sun.universe.space"@1520,
:checkpoint=&gt;"u"@1551,
:ctime=&gt;"Tue Aug 27 15:56:41 2013"@1565,
:error_path=&gt;
 "sun.universe.space:/home/helios/FirstTest.e2750"@1607,
:hold_types=&gt;"n"@1689,
:join_path=&gt;"n"@1707,
:keep_files=&gt;"n"@1726,
:mail_points=&gt;"abe"@1746,
:mtime=&gt;"Tue Aug 27 15:56:41 2013"@1762,
:output_path=&gt;
 "deep.space.nine:/home/helios/FirstTest.o2750"@1805,
:priority=&gt;"0"@1885,
:qtime=&gt;"Tue Aug 27 15:56:41 2013"@1899,
:rerunable=&gt;"True"@1940,
:resource_list_nodect=&gt;"1"@1972,
:resource_list_nodes=&gt;"1:ppn=4"@2000,
:shell_path_list=&gt;"/bin/bash"@2030,
:variable_list=&gt;
 "PBS_O_QUEUE=bio,PBS_O_HOST=deep.space.nine,PBS_O_HOME=/home/helios,PBS_O_LANG=it_IT.UTF-8,PBS_O_LOGNAME=helios,PBS_O_PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:/usr/games:/home/helios/.rvm/bin,PBS_O_MAIL=/var/mail/helios,PBS_O_SHELL=/bin/bash,PBS_SERVER=spark,PBS_O_WORKDIR=/home/helios\n"@2060,
:etime=&gt;"Tue Aug 27 15:56:41 2013"@2456,
:submit_args=&gt;"FirstTest.qsub"@2499,
:fault_tolerant=&gt;"False"@2535,

:submit_host=&gt;“sun.universe.space”@2559}] </code></pre>

<p>directly from the job</p>

<pre>job.stat </pre>

<p>or by requesting the information using the specific object</p>

<pre><code>stats=TORQUE::Qstat.new

# select stats from only the submitted job stat.query job_id: job.id </code></pre>

<p>it will return an hash but is also possible to return the raw string from TORQUE/PBS</p>

<pre>stat.query job_id: job.id, type: :raw </pre>

<p>Quering multiple jobs at the same time is possible as well (note the 's' after 'id'):</p>

<pre>stat.query job_ids: ["2751.sun.universe.space","2752.sun.universe.space","2754.sun.universe.space","2755.sun.universe.space"] </pre>

<h2>Delete Jobs</h2>

<p>From a qsub object if submitted:</p>

<pre>job.rm </pre>

<p>Directly from PBS:</p>

<pre>TORQUE::Qdel.rm("2750.sun.universe.space") </pre>

<h2>REST Api</h2>

<p>All objects returned from TORQUERMREST are in JSON format.</p>

<h3>Qstat</h3>

<h4>Get</h4>

<p>/qstat Returns an Array of Hash with the following keys, if available "job_id","job_name","job_owner","resources_used_cput","resources_used_mem","resources_used_vmem","resources_used_walltime","job_state","queue","server","checkpoint","ctime","error_path","exec_host","exec_port","hold_types","join_path","keep_files","mail_points","mail_users","mtime","output_path","priority","qtime","rerunable","resource_list","session_id","shell_path_list","variable_list","etime","exit_status","submit_args","start_time","start_count","fault_tolerant","comp_time","job_radix","total_runtime","submit_host" .</p>

<p>/qstat/fields Returns an Array of String, the available fields for a single qstat query.</p>

<p>/qstat/all/:field Return an Array of Strings, each String is the field requested by the user. If the field requested is not valid, it will return 404</p>

<h3>Job</h3>

<h4>Get</h4>

<p>/qstat/:job_id Returns an Hash with main key job and the JSON conversion of a TORQUE::Qstat::Job object. If the job_id does not exist will return 404</p>

<p>/qstat/job/fields Returns and Hash {"job_fields":["job_id","job_name","job_owner","resources_used_cput","resources_used_mem","resources_used_vmem","resources_used_walltime","job_state","queue","server","checkpoint","ctime","error_path","exec_host","exec_port","hold_types","join_path","keep_files","mail_points","mail_users","mtime","output_path","priority","qtime","rerunable","resource_list","session_id","shell_path_list","variable_list","etime","exit_status","submit_args","start_time","start_count","fault_tolerant","comp_time","job_radix","total_runtime","submit_host","is_runnig?","is_queued?","is_exited?","is_completed?","time","memory","node"]} </p>

<p>/qstat/:job_id/:field Returns and Hash with a single key which is the required field. If the job_id or field do not exist will return 404</p>

<h4>Post</h4>

<p>/qstat/:job_id/del Removes the job_id from the queue. If the job_id does not exist will return 404</p>

<h3>Interacting from CLI</h3>

<p>To perform a query or call a fucntion use curl setting the content type. Extension .json is not considering for now, why? Read <a href=“What-is-the-correct-json-content-typestackoverflow.com/questions/477816/what-is-the-correct-json-content-type”>What-is-the-correct-json-content-type> discussion on <a href=“Stackoverflowstackoverflow.com/”>Stackoverflow>

<p>curl -H “Content-type: application/json” “localhost:4567/qstat”>

<h3>WebApp</h3>

<p>A web application is under development and it will let you interact with you TORQUE/PBS server in a more fancy way, be patient and give us your feedback or request functionalities. A list of supported html pages:</p>

<ul> <li>get: /qstat</li> </ul>

<h3>HowIsItMade</h3>

<p><a href=“Sinatrawww.sinatrarb.com/”>Sinatra> is the low level framework used for developing the REST API and the web infrastructure. <a href=“Twitter”>getbootstrap.com/“>Twitter Bootstrap</a> is used to make the web app nice and fancy.</p>

<h2>Contributing to torque_rm</h2>

<ul> <li>Check out the latest master to make sure the feature hasn't been implemented or the bug hasn't been fixed yet.</li> <li>Check out the issue tracker to make sure someone already hasn't requested it and/or contributed it.</li> <li>Fork the project.</li> <li>Start a feature/bugfix branch.</li> <li>Commit and push until you are happy with your contribution.</li> <li>Make sure to add tests for it. This is important so I don't break it in a future version unintentionally.</li> <li>Please try not to mess with the Rakefile, version, or history. If you want to have your own version, or is otherwise necessary, that is fine, but please isolate to its own commit so I can cherry-pick around it.</li> </ul>

<h2>Copyright</h2>

<p>Copyright © 2013 Raoul Jean Pierre Bonnal. See LICENSE.txt for further details.</p>