Google Git
Sign in
apache / aurora-website / f61d4606ea08e5f997f847db81cac6e2e8088f80 / . / publish / documentation / latest / client-commands / index.html
blob: 707e937fd078dbbaac24623a683f3020061e62a1 [file] [log] [blame]
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>Apache Aurora</title>
<link rel="stylesheet" href="https://maxcdn.bootstrapcdn.com/bootstrap/3.3.1/css/bootstrap.min.css">
<link href="/assets/css/main.css" rel="stylesheet">
<!-- Analytics -->
<script type="text/javascript">
var _gaq = _gaq || [];
_gaq.push(['_setAccount', 'UA-45879646-1']);
_gaq.push(['_setDomainName', 'apache.org']);
_gaq.push(['_trackPageview']);
(function() {
var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;
ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);
})();
</script>
</head>
<body>
<div class="container-fluid section-header">
<div class="container">
<div class="nav nav-bar">
<a href="/"><img src="/assets/img/aurora_logo_white_bkg.svg" width="300" alt="Transparent Apache Aurora logo with dark background"/></a>
<ul class="nav navbar-nav navbar-right">
<li><a href="/documentation/latest/">Documentation</a></li>
<li><a href="/community/">Community</a></li>
<li><a href="/downloads/">Downloads</a></li>
<li><a href="/blog/">Blog</a></li>
</ul>
</div>
</div>
</div>
<div class="container-fluid">
<div class="container content">
<h1 id="aurora-client-commands">Aurora Client Commands</h1>
<p>The most up-to-date reference is in the client itself: use the
<code>aurora help</code> subcommand (for example, <code>aurora help</code> or
<code>aurora help create</code>) to find the latest information on parameters and
functionality. Note that <code>aurora help open</code> does not work, due to underlying issues with
reflection.</p>
<ul>
<li><a href="#introduction">Introduction</a></li>
<li><a href="#cluster-configuration">Cluster Configuration</a></li>
<li><a href="#job-keys">Job Keys</a></li>
<li><a href="#modifying-aurora-client-commands">Modifying Aurora Client Commands</a></li>
<li><a href="#regular-jobs">Regular Jobs</a>
<ul>
<li><a href="#creating-and-running-a-job">Creating and Running a Job</a></li>
<li><a href="#running-a-command-on-a-running-job">Running a Command On a Running Job</a></li>
<li><a href="#killing-a-job">Killing a Job</a></li>
<li><a href="#updating-a-job">Updating a Job</a>
<ul>
<li><a href="#user-content-asynchronous-job-updates-beta">Asynchronous job updates (beta)</a></li>
</ul></li>
<li><a href="#renaming-a-job">Renaming a Job</a></li>
<li><a href="#restarting-jobs">Restarting Jobs</a></li>
</ul></li>
<li><a href="#cron-jobs">Cron Jobs</a></li>
<li><a href="#comparing-jobs">Comparing Jobs</a></li>
<li><a href="#viewingexamining-jobs">Viewing/Examining Jobs</a>
<ul>
<li><a href="#listing-jobs">Listing Jobs</a></li>
<li><a href="#inspecting-a-job">Inspecting a Job</a></li>
<li><a href="#versions">Versions</a></li>
<li><a href="#checking-your-quota">Checking Your Quota</a></li>
<li><a href="#finding-a-job-on-web-ui">Finding a Job on Web UI</a></li>
<li><a href="#getting-job-status">Getting Job Status</a></li>
<li><a href="#opening-the-web-ui">Opening the Web UI</a></li>
<li><a href="#sshing-to-a-specific-task-machine">SSHing to a Specific Task Machine</a></li>
<li><a href="#templating-command-arguments">Templating Command Arguments</a></li>
</ul></li>
</ul>
<h2 id="introduction">Introduction</h2>
<p>Once you have written an <code>.aurora</code> configuration file that describes
your Job and its parameters and functionality, you interact with Aurora
using Aurora Client commands. This document describes all of these commands
and how and when to use them. All Aurora Client commands start with
<code>aurora</code>, followed by the name of the specific command and its
arguments.</p>
<p><em>Job keys</em> are a very common argument to Aurora commands, as well as the
gateway to useful information about a Job. Before using Aurora, you
should read the next section which describes them in detail. The section
after that briefly describes how you can modify the behavior of certain
Aurora Client commands, linking to a detailed document about how to do
that.</p>
<p>This is followed by the Regular Jobs section, which describes the basic
Client commands for creating, running, and manipulating Aurora Jobs.
After that are sections on Comparing Jobs and Viewing/Examining Jobs. In
other words, various commands for getting information and metadata about
Aurora Jobs.</p>
<h2 id="cluster-configuration">Cluster Configuration</h2>
<p>The client must be able to find a configuration file that specifies available clusters. This file
declares shorthand names for clusters, which are in turn referenced by job configuration files
and client commands.</p>
<p>The client will load at most two configuration files, making both of their defined clusters
available. The first is intended to be a system-installed cluster, using the path specified in
the environment variable <code>AURORA_CONFIG_ROOT</code>, defaulting to <code>/etc/aurora/clusters.json</code> if the
environment variable is not set. The second is a user-installed file, located at
<code>~/.aurora/clusters.json</code>.</p>
<p>A cluster configuration is formatted as JSON. The simplest cluster configuration is one that
communicates with a single (non-leader-elected) scheduler. For example:</p>
<pre class="highlight javascript"><span class="p">[{</span>
<span class="s2">&quot;name&quot;</span><span class="err">:</span> <span class="s2">&quot;example&quot;</span><span class="p">,</span>
<span class="s2">&quot;scheduler_uri&quot;</span><span class="err">:</span> <span class="s2">&quot;localhost:55555&quot;</span><span class="p">,</span>
<span class="p">}]</span>
</pre>
<p>A configuration for a leader-elected scheduler would contain something like:</p>
<pre class="highlight javascript"><span class="p">[{</span>
<span class="s2">&quot;name&quot;</span><span class="err">:</span> <span class="s2">&quot;example&quot;</span><span class="p">,</span>
<span class="s2">&quot;zk&quot;</span><span class="err">:</span> <span class="s2">&quot;192.168.33.7&quot;</span><span class="p">,</span>
<span class="s2">&quot;scheduler_zk_path&quot;</span><span class="err">:</span> <span class="s2">&quot;/aurora/scheduler&quot;</span>
<span class="p">}]</span>
</pre>
<p>For more details on cluster configuration see the
<a href="/documentation/latest/client-cluster-configuration/">Client Cluster Configuration</a> documentation.</p>
<h2 id="job-keys">Job Keys</h2>
<p>A job key is a unique system-wide identifier for an Aurora-managed
Job, for example <code>cluster1/web-team/test/experiment204</code>. It is a 4-tuple
consisting of, in order, <em>cluster</em>, <em>role</em>, <em>environment</em>, and
<em>jobname</em>, separated by /s. Cluster is the name of an Aurora
cluster. Role is the Unix service account under which the Job
runs. Environment is a namespace component like <code>devel</code>, <code>test</code>,
<code>prod</code>, or <code>stagingN.</code> Jobname is the Job&rsquo;s name.</p>
<p>The combination of all four values uniquely specifies the Job. If any
one value is different from that of another job key, the two job keys
refer to different Jobs. For example, job key
<code>cluster1/tyg/prod/workhorse</code> is different from
<code>cluster1/tyg/prod/workcamel</code> is different from
<code>cluster2/tyg/prod/workhorse</code> is different from
<code>cluster2/foo/prod/workhorse</code> is different from
<code>cluster1/tyg/test/workhorse.</code></p>
<p>Role names are user accounts existing on the slave machines. If you don&rsquo;t know what accounts
are available, contact your sysadmin.</p>
<p>Environment names are namespaces; you can count on <code>prod</code>, <code>devel</code> and <code>test</code> existing.</p>
<h2 id="modifying-aurora-client-commands">Modifying Aurora Client Commands</h2>
<p>For certain Aurora Client commands, you can define hook methods that run
either before or after an action that takes place during the command&rsquo;s
execution, as well as based on whether the action finished successfully or failed
during execution. Basically, a hook is code that lets you extend the
command&rsquo;s actions. The hook executes on the client side, specifically on
the machine executing Aurora commands.</p>
<p>Hooks can be associated with these Aurora Client commands.</p>
<ul>
<li><code>cancel_update</code></li>
<li><code>create</code></li>
<li><code>kill</code></li>
<li><code>restart</code></li>
<li><code>update</code></li>
</ul>
<p>The process for writing and activating them is complex enough
that we explain it in a devoted document, <a href="/documentation/latest/hooks/">Hooks for Aurora Client API</a>.</p>
<h2 id="regular-jobs">Regular Jobs</h2>
<p>This section covers Aurora commands related to running, killing,
renaming, updating, and restarting a basic Aurora Job.</p>
<h3 id="creating-and-running-a-job">Creating and Running a Job</h3>
<pre class="highlight text">aurora create &lt;job key&gt; &lt;configuration file&gt;
</pre>
<p>Creates and then runs a Job with the specified job key based on a <code>.aurora</code> configuration file.
The configuration file may also contain and activate hook definitions.</p>
<p><code>create</code> can take four named parameters:</p>
<ul>
<li><code>-E NAME=VALUE</code> Bind a Thermos mustache variable name to a
value. Multiple flags specify multiple values. Defaults to <code>[]</code>.</li>
<li><code>-o, --open_browser</code> Open a browser window to the scheduler UI Job
page after a job changing operation happens. When <code>False</code>, the Job
URL prints on the console and the user has to copy/paste it
manually. Defaults to <code>False</code>. Does not work when running in Vagrant.</li>
<li><code>-j, --json</code> If specified, configuration argument is read as a
string in JSON format. Defaults to False.</li>
<li><code>--wait_until=STATE</code> Block the client until all the Tasks have
transitioned into the requested state. Possible values are: <code>PENDING</code>,
<code>RUNNING</code>, <code>FINISHED</code>. Default: <code>PENDING</code></li>
</ul>
<h3 id="running-a-command-on-a-running-job">Running a Command On a Running Job</h3>
<pre class="highlight text">aurora run &lt;job_key&gt; &lt;cmd&gt;
</pre>
<p>Runs a shell command on all machines currently hosting shards of a
single Job.</p>
<p><code>run</code> supports the same command line wildcards used to populate a Job&rsquo;s
commands; i.e. anything in the <code>{{mesos.*}}</code> and <code>{{thermos.*}}</code>
namespaces.</p>
<p><code>run</code> can take three named parameters:</p>
<ul>
<li><code>-t NUM_THREADS</code>, <code>--threads=NUM_THREADS</code>The number of threads to
use, defaulting to <code>1</code>.</li>
<li><code>--user=SSH_USER</code> ssh as this user instead of the given role value.
Defaults to None.</li>
<li><code>-e, --executor_sandbox</code> Run the command in the executor sandbox
instead of the Task sandbox. Defaults to False.</li>
</ul>
<h3 id="killing-a-job">Killing a Job</h3>
<pre class="highlight text">aurora kill &lt;job key&gt; &lt;configuration file&gt;
</pre>
<p>Kills all Tasks associated with the specified Job, blocking until all
are terminated. Defaults to killing all shards in the Job.</p>
<p>The <code>&lt;configuration file&gt;</code> argument for <code>kill</code> is optional. Use it only
if it contains hook definitions and activations that affect the
kill command.</p>
<p><code>kill</code> can take two named parameters:</p>
<ul>
<li><code>-o, --open_browser</code> Open a browser window to the scheduler UI Job
page after a job changing operation happens. When <code>False</code>, the Job
URL prints on the console and the user has to copy/paste it
manually. Defaults to <code>False</code>. Does not work when running in Vagrant.</li>
<li><code>--shards=SHARDS</code> A list of shard ids to act on. Can either be a
comma-separated list (e.g. 0,1,2) or a range (e.g. 0-2) or any
combination of the two (e.g. 0-2,5,7-9). Defaults to acting on all
shards.</li>
</ul>
<h3 id="updating-a-job">Updating a Job</h3>
<pre class="highlight text">aurora update [--shards=ids] &lt;job key&gt; &lt;configuration file&gt;
aurora cancel_update &lt;job key&gt; &lt;configuration file&gt;
</pre>
<p>Given a running job, does a rolling update to reflect a new
configuration version. Only updates Tasks in the Job with a changed
configuration. You can further restrict the operated on Tasks by
using <code>--shards</code> and specifying a comma-separated list of job shard ids.</p>
<p>You may want to run <code>aurora diff</code> beforehand to validate which Tasks
have different configurations.</p>
<p>Updating jobs are locked to be sure the update finishes without
disruption. If the update abnormally terminates, the lock may stay
around and cause failure of subsequent update attempts.
<code>aurora cancel_update</code>unlocks the Job specified by
its <code>job_key</code> argument. Be sure you don&rsquo;t issue <code>cancel_update</code> when
another user is working with the specified Job.</p>
<p>The <code>&lt;configuration file&gt;</code> argument for <code>cancel_update</code> is optional. Use
it only if it contains hook definitions and activations that affect the
<code>cancel_update</code> command. The <code>&lt;configuration file&gt;</code> argument for
<code>update</code> is required, but in addition to a new configuration it can be
used to define and activate hooks for <code>update</code>.</p>
<p><code>update</code> can take four named parameters:</p>
<ul>
<li><code>--shards=SHARDS</code> A list of shard ids to update. Can either be a
comma-separated list (e.g. 0,1,2) or a range (e.g. 0-2) or any
combination of the two (e.g. 0-2,5,7-9). If not set, all shards are
acted on. Defaults to None.</li>
<li><code>-E NAME=VALUE</code> Binds a Thermos mustache variable name to a value.
Use multiple flags to specify multiple values. Defaults to <code>[]</code>.</li>
<li><code>-j, --json</code> If specified, configuration is read in JSON format.
Defaults to <code>False</code>.</li>
<li><code>--updater_health_check_interval_seconds=HEALTH_CHECK_INTERVAL_SECONDS</code>
Time interval between subsequent shard status checks. Defaults to <code>3</code>.</li>
</ul>
<h4 id="asynchronous-job-updates-(beta)">Asynchronous job updates (beta)</h4>
<p>As of 0.6.0, Aurora will coordinate updates (and rollbacks) within the
scheduler. Performing updates this way also allows the scheduler to display
update progress and job update history in the browser.</p>
<p>There are several sub-commands to manage job updates:</p>
<pre class="highlight text">aurora2 beta-update start &lt;job key&gt; &lt;configuration file
aurora2 beta-update status &lt;job key&gt;
aurora2 beta-update pause &lt;job key&gt;
aurora2 beta-update resume &lt;job key&gt;
aurora2 beta-update abort &lt;job key&gt;
aurora2 beta-update list &lt;cluster&gt;
</pre>
<p>When you <code>start</code> a job update, the command will return once it has sent the
instructions to the scheduler. At that point, you may view detailed
progress for the update with the <code>status</code> subcommand, in addition to viewing
graphical progress in the web browser. You may also get a full listing of
in-progress updates in a cluster with <code>list</code>.</p>
<p>Once an update has been started, you can <code>pause</code> to keep the update but halt
progress. This can be useful for doing things like debug a partially-updated
job to determine whether you would like to proceed. You can <code>resume</code> to
proceed.</p>
<p>You may <code>abort</code> a job update regardless of the state it is in. This will
instruct the scheduler to completely abandon the job update and leave the job
in the current (possibly partially-updated) state.</p>
<h3 id="renaming-a-job">Renaming a Job</h3>
<p>Renaming is a tricky operation as downstream clients must be informed of
the new name. A conservative approach
to renaming suitable for production services is:</p>
<ol>
<li> Modify the Aurora configuration file to change the role,
environment, and/or name as appropriate to the standardized naming
scheme.</li>
<li><p>Check that only these naming components have changed
with <code>aurora diff</code>.</p>
<pre class="highlight text">aurora diff &lt;job_key&gt; &lt;job_configuration&gt;
</pre></li>
<li><p>Create the (identical) job at the new key. You may need to request a
temporary quota increase.</p>
<pre class="highlight text">aurora create &lt;new_job_key&gt; &lt;job_configuration&gt;
</pre></li>
<li><p>Migrate all clients over to the new job key. Update all links and
dashboards. Ensure that both job keys run identical versions of the
code while in this state.</p></li>
<li><p>After verifying that all clients have successfully moved over, kill
the old job.</p>
<pre class="highlight text">aurora kill &lt;old_job_key&gt;
</pre></li>
<li><p>If you received a temporary quota increase, be sure to let the
powers that be know you no longer need the additional capacity.</p></li>
</ol>
<h3 id="restarting-jobs">Restarting Jobs</h3>
<p><code>restart</code> restarts all of a job key identified Job&rsquo;s shards:</p>
<pre class="highlight text">aurora restart &lt;job_key&gt; &lt;configuration file&gt;
</pre>
<p>Restarts are controlled on the client side, so aborting
the <code>restart</code> command halts the restart operation.</p>
<p><code>restart</code> does a rolling restart. You almost always want to do this, but
not if all shards of a service are misbehaving and are
completely dysfunctional. To not do a rolling restart, use
the <code>-shards</code> option described below.</p>
<p><strong>Note</strong>: <code>restart</code> only applies its command line arguments and does not
use or is affected by <code>update.config</code>. Restarting
does <strong><em>not</em></strong> involve a configuration change. To update the
configuration, use <code>update.config</code>.</p>
<p>The <code>&lt;configuration file&gt;</code> argument for restart is optional. Use it only
if it contains hook definitions and activations that affect the
<code>restart</code> command.</p>
<p>In addition to the required job key argument, there are eight
<code>restart</code> specific optional arguments:</p>
<ul>
<li><code>--updater_health_check_interval_seconds</code>: Defaults to <code>3</code>, the time
interval between subsequent shard status checks.</li>
<li><code>--shards=SHARDS</code>: Defaults to None, which restarts all shards.
Otherwise, only the specified-by-id shards restart. They can be
comma-separated <code>(0, 8, 9)</code>, a range <code>(3-5)</code> or a
combination <code>(0, 3-5, 8, 9-11)</code>.</li>
<li><code>--batch_size</code>: Defaults to <code>1</code>, the number of shards to be started
in one iteration. So, for example, for value 3, it tries to restart
the first three shards specified by <code>--shards</code> simultaneously, then
the next three, and so on.</li>
<li><code>--max_per_shard_failures=MAX_PER_SHARD_FAILURES</code>: Defaults to <code>0</code>,
the maximum number of restarts per shard during restart. When
exceeded, it increments the total failure count.</li>
<li><code>--max_total_failures=MAX_TOTAL_FAILURES</code>: Defaults to <code>0</code>, the
maximum total number of shard failures tolerated during restart.</li>
<li><code>-o, --open_browser</code> Open a browser window to the scheduler UI Job
page after a job changing operation happens. When <code>False</code>, the Job
url prints on the console and the user has to copy/paste it
manually. Defaults to <code>False</code>. Does not work when running in Vagrant.</li>
<li><code>--restart_threshold</code>: Defaults to <code>60</code>, the maximum number of
seconds before a shard must move into the <code>RUNNING</code> state before
it&rsquo;s considered a failure.</li>
<li><code>--watch_secs</code>: Defaults to <code>45</code>, the minimum number of seconds a
shard must remain in <code>RUNNING</code> state before considered a success.</li>
</ul>
<h2 id="cron-jobs">Cron Jobs</h2>
<p>You will see various commands and options relating to cron jobs in
<code>aurora -help</code> and similar. Ignore them, as they&rsquo;re not yet implemented.
You might be able to use them without causing an error, but nothing happens
if you do.</p>
<h2 id="comparing-jobs">Comparing Jobs</h2>
<pre class="highlight text">aurora diff &lt;job_key&gt; config
</pre>
<p>Compares a job configuration against a running job. By default the diff
is determined using <code>diff</code>, though you may choose an alternate
diff program by specifying the <code>DIFF_VIEWER</code> environment variable.</p>
<p>There are two named parameters:</p>
<ul>
<li><code>-E NAME=VALUE</code> Bind a Thermos mustache variable name to a
value. Multiple flags may be used to specify multiple values.
Defaults to <code>[]</code>.</li>
<li><code>-j, --json</code> Read the configuration argument in JSON format.
Defaults to <code>False</code>.</li>
</ul>
<h2 id="viewing/examining-jobs">Viewing/Examining Jobs</h2>
<p>Above we discussed creating, killing, and updating Jobs. Here we discuss
how to view and examine Jobs.</p>
<h3 id="listing-jobs">Listing Jobs</h3>
<pre class="highlight text">aurora list_jobs
Usage: `aurora list_jobs cluster/role
</pre>
<p>Lists all Jobs registered with the Aurora scheduler in the named cluster for the named role.</p>
<p>It has two named parameters:</p>
<ul>
<li><code>--pretty</code>: Displays job information in prettyprinted format.
Defaults to <code>False</code>.</li>
<li><code>-c</code>, <code>--show-cron</code>: Shows cron schedule for jobs. Defaults to
<code>False</code>. Do not use, as it&rsquo;s not yet implemented.</li>
</ul>
<h3 id="inspecting-a-job">Inspecting a Job</h3>
<pre class="highlight text">aurora inspect &lt;job_key&gt; config
</pre>
<p><code>inspect</code> verifies that its specified job can be parsed from a
configuration file, and displays the parsed configuration. It has four
named parameters:</p>
<ul>
<li><code>--local</code>: Inspect the configuration that the <code>spawn</code> command would
create, defaulting to <code>False</code>.</li>
<li><code>--raw</code>: Shows the raw configuration. Defaults to <code>False</code>.</li>
<li><code>-j</code>, <code>--json</code>: If specified, configuration is read in JSON format.
Defaults to <code>False</code>.</li>
<li><code>-E NAME=VALUE</code>: Bind a Thermos Mustache variable name to a value.
You can use multiple flags to specify multiple values. Defaults
to <code>[]</code></li>
</ul>
<h3 id="versions">Versions</h3>
<pre class="highlight text">aurora version
</pre>
<p>Lists client build information and what Aurora API version it supports.</p>
<h3 id="checking-your-quota">Checking Your Quota</h3>
<pre class="highlight text">aurora get_quota --cluster=CLUSTER role
</pre>
<p>Prints the production quota allocated to the role&rsquo;s value at the given
cluster.</p>
<h3 id="finding-a-job-on-web-ui">Finding a Job on Web UI</h3>
<p>When you create a job, part of the output response contains a URL that goes
to the job&rsquo;s scheduler UI page. For example:</p>
<pre class="highlight text">vagrant@precise64:~$ aurora create devcluster/www-data/prod/hello /vagrant/examples/jobs/hello_world.aurora
INFO] Creating job hello
INFO] Response from scheduler: OK (message: 1 new tasks pending for job www-data/prod/hello)
INFO] Job url: http://precise64:8081/scheduler/www-data/prod/hello
</pre>
<p>You can go to the scheduler UI page for this job via <code>http://precise64:8081/scheduler/www-data/prod/hello</code>
You can go to the overall scheduler UI page by going to the part of that URL that ends at <code>scheduler</code>; <code>http://precise64:8081/scheduler</code></p>
<p>Once you click through to a role page, you see Jobs arranged
separately by pending jobs, active jobs and finished jobs.
Jobs are arranged by role, typically a service account for
production jobs and user accounts for test or development jobs.</p>
<h3 id="getting-job-status">Getting Job Status</h3>
<pre class="highlight text">aurora status &lt;job_key&gt;
</pre>
<p>Returns the status of recent tasks associated with the
<code>job_key</code> specified Job in its supplied cluster. Typically this includes
a mix of active tasks (running or assigned) and inactive tasks
(successful, failed, and lost.)</p>
<h3 id="opening-the-web-ui">Opening the Web UI</h3>
<p>Use the Job&rsquo;s web UI scheduler URL or the <code>aurora status</code> command to find out on which
machines individual tasks are scheduled. You can open the web UI via the
<code>open</code> command line command if invoked from your machine:</p>
<pre class="highlight text">aurora open [&lt;cluster&gt;[/&lt;role&gt;[/&lt;env&gt;/&lt;job_name&gt;]]]
</pre>
<p>If only the cluster is specified, it goes directly to that cluster&rsquo;s
scheduler main page. If the role is specified, it goes to the top-level
role page. If the full job key is specified, it goes directly to the job
page where you can inspect individual tasks.</p>
<h3 id="sshing-to-a-specific-task-machine">SSHing to a Specific Task Machine</h3>
<pre class="highlight text">aurora ssh &lt;job_key&gt; &lt;shard number&gt;
</pre>
<p>You can have the Aurora client ssh directly to the machine that has been
assigned a particular Job/shard number. This may be useful for quickly
diagnosing issues such as performance issues or abnormal behavior on a
particular machine.</p>
<p>It can take three named parameters:</p>
<ul>
<li><code>-e</code>, <code>--executor_sandbox</code>: Run <code>ssh</code> in the executor sandbox
instead of the task sandbox. Defaults to <code>False</code>.</li>
<li><code>--user=SSH_USER</code>: <code>ssh</code> as the given user instead of as the role in
the <code>job_key</code> argument. Defaults to none.</li>
<li><code>-L PORT:NAME</code>: Add tunnel from local port <code>PORT</code> to the remote
named port <code>NAME</code>. Defaults to <code>[]</code>.</li>
</ul>
<h3 id="templating-command-arguments">Templating Command Arguments</h3>
<pre class="highlight text">aurora run [-e] [-t THREADS] &lt;job_key&gt; -- &lt;&lt;command-line&gt;&gt;
</pre>
<p>Given a job specification, run the supplied command on all hosts and
return the output. You may use the standard Mustache templating rules:</p>
<ul>
<li><code>{{thermos.ports[name]}}</code> substitutes the specific named port of the
task assigned to this machine</li>
<li><code>{{mesos.instance}}</code> substitutes the shard id of the job&rsquo;s task
assigned to this machine</li>
<li><code>{{thermos.task_id}}</code> substitutes the task id of the job&rsquo;s task
assigned to this machine</li>
</ul>
<p>For example, the following type of pattern can be a powerful diagnostic
tool:</p>
<pre class="highlight text">aurora run -t5 cluster1/tyg/devel/seizure -- \
&#39;curl -s -m1 localhost:{{thermos.ports[http]}}/vars | grep uptime&#39;
</pre>
<p>By default, the command runs in the Task&rsquo;s sandbox. The <code>-e</code> option can
run the command in the executor&rsquo;s sandbox. This is mostly useful for
Aurora administrators.</p>
<p>You can parallelize the runs by using the <code>-t</code> option.</p>
</div>
</div>
<div class="container-fluid section-footer buffer">
<div class="container">
<div class="row">
<div class="col-md-2 col-md-offset-1"><h3>Quick Links</h3>
<ul>
<li><a href="/downloads/">Downloads</a></li>
<li><a href="/community/">Mailing Lists</a></li>
<li><a href="http://issues.apache.org/jira/browse/AURORA">Issue Tracking</a></li>
<li><a href="/documentation/latest/contributing/">How To Contribute</a></li>
</ul>
</div>
<div class="col-md-2"><h3>The ASF</h3>
<ul>
<li><a href="http://www.apache.org/licenses/">License</a></li>
<li><a href="http://www.apache.org/foundation/sponsorship.html">Sponsorship</a></li>
<li><a href="http://www.apache.org/foundation/thanks.html">Thanks</a></li>
<li><a href="http://www.apache.org/security/">Security</a></li>
</ul>
</div>
<div class="col-md-6">
<p class="disclaimer">Apache Aurora is an effort undergoing incubation at The Apache Software Foundation (ASF), sponsored by the Apache Incubator. Incubation is required of all newly accepted projects until a further review indicates that the infrastructure, communications, and decision making process have stabilized in a manner consistent with other successful ASF projects. While incubation status is not necessarily a reflection of the completeness or stability of the code, it does indicate that the project has yet to be fully endorsed by the ASF.</p>
<p class="disclaimer">Copyright 2014 <a href="http://www.apache.org/">Apache Software Foundation</a>. Licensed under the <a href="http://www.apache.org/licenses/">Apache License v2.0</a>. The <a href="https://www.flickr.com/photos/trondk/12706051375/">Aurora Borealis IX photo</a> displayed on the homepage is available under a <a href="https://creativecommons.org/licenses/by-nc-nd/2.0/">Creative Commons BY-NC-ND 2.0 license</a>. Apache, Apache Aurora, and the Apache feather logo are trademarks of The Apache Software Foundation.</p>
</div>
</div>
</div>
</body>
</html>