doc/user/tutorials/tutorial-keep-get.html.textile.liquid

   1 ---
   2 layout: default
   3 navsection: userguide
   4 title: "Downloading data"
   5 ...
   6 {% comment %}
   7 Copyright (C) The Arvados Authors. All rights reserved.
   8
   9 SPDX-License-Identifier: CC-BY-SA-3.0
  10 {% endcomment %}
  11
  12 Arvados Data collections can be downloaded using either the arv commands or using Workbench.
  13
  14 # "*Download using Workbench*":#download-using-workbench
  15 # "*Sharing collections*":#download-shared-collection
  16 # "*Download using command line tools*":#download-using-arv
  17
  18 h2(#download-using-workbench). Download using Workbench
  19
  20 You can also download Arvados data collections using the Workbench.
  21
  22 When you visit a project in Workbench (for instance, the <i class="fa fa-fw fa-folder"></i> *Home Projects* or any projects under it), the collections will show up on the project details page, with "_Data collection_" in the *Type* column.
  23
  24 Clicking on a collection will bring you to its details page. There, the <span class="btn btn-sw btn-primary">FILES</span> panel acts like a file manager where you can navigate to or search for files, select them for actions, and download them.
  25
  26 To download a file, simply click on the file, or bring up the context menu using right-click or the triple-dot button on its row, and then select the menu item *Download*.
  27
  28 h2(#download-shared-collection). Sharing collections
  29
  30 Collections or their parent projects can be shared with other users on the Arvados cluster.  First, locate the collection or project using any available means (for instance, by manually navigating in the Workbench, or using the Search bar). Then right-click on its link in a listing, or click on the triple-dot button in the details page. You will find the menu item *Share*, which opens the dialog box *Sharing settings*.
  31
  32 h3. Sharing with other Arvados users
  33
  34 To share with other Arvados users, select the *WITH USERS/GROUPS* tab in the *Sharing settings* dialog box. Under *Add people and groups*, in the input field you can search for the user or group names. Select one you will be sharing with, choose the *Authorization* level (Read/Write/Manage) in the drop-down menu, and click on the plus sign (+) on the right. This can be repeated for other users or groups, each with their own *Authorization* level. The selected ones will appear under *People with access*. You can revisit the *Sharing settings* dialog box to modify the users or their access levels at a later time.
  35
  36 The *General access* drop-down menu controls the default sharing setting, with the following choices:
  37
  38 * *Private*: This is the initial state when no users or groups have been selected for sharing. At any time, by setting *General access* to private, the current sharing setting will be cleared, and any users or groups formerly with access will lose that access.
  39 * *Public*: This means the list of *People with access* will include _Anonymous users_, even if they are not users of the current cluster. You can further set their access level in the *Authorization* level.
  40 * *All users*: This means sharing with other users who are logged in on the current cluster.
  41 * *Shared*: When you choose to share with specific people or groups, *General access* will be set to *Shared*. From this state, you can further specify the default sharing settings for *Public* and *All users*.
  42
  43 h3. Creating a special download URL for a collection
  44
  45 To share a collection with users that do not have an account on your Arvados cluster, locate the collection and then go to the *Sharing settings* dialog box as described above. There, select the *SHARING URLS* tab.
  46
  47 You can then generate a new sharing URL using the <span class="btn btn-sm btn-primary">CREATE SHARING URL</span> button, with the option to set an expiration time for the URL. You can then copy the URL to the clipboard for sharing with others. To revoke (that is, delete) a sharing URL, click on the cross icon beside it.
  48
  49 <figure>!{width: 80%}{{ site.baseurl }}/images/sharing-collection-url.png!<figcaption>_The_ *SHARING URLS* _tab in the_ *Sharing settings* _dialog box, showing the created URL with an expiration time_</figcaption></figure>
  50
  51 Any user with the sharing URL can download this collection by simply accessing this URL using browser. It will present a downloadable version of the collection as shown below.
  52
  53 !{display: block;margin-left: 25px;margin-right: auto;border:1px solid lightgray;}{{ site.baseurl }}/images/download-shared-collection.png!
  54
  55 When a collection is being shared by URL, in the *WITH USERS/GROUS* tab of *Sharing settings*, the following message will appear if *General access* is Private: _Although there aren't specific permissions set, this is publicly accessible via Sharing URL(s)._
  56
  57 * *Note:* Sharing by URL is specific to collections. Projects or individual files cannot be shared in this way.
  58
  59 h2(#download-using-arv). Download using command line tools
  60
  61 {% include 'tutorial_expectations' %}
  62
  63 You can download Arvados data collections using the command line tools @arv-ls@ and @arv-get@.
  64
  65 Use @arv-ls@ to view the contents of a collection:
  66
  67 <notextile>
  68 <pre><code>~$ <span class="userinput">arv-ls ae480c5099b81e17267b7445e35b4bc7+180</span>
  69 ./HWI-ST1027_129_D0THKACXX.1_1.fastq
  70 ./HWI-ST1027_129_D0THKACXX.1_2.fastq
  71 </code></pre>
  72
  73 Use @-s@ to print file sizes, in kilobytes, rounded up:
  74
  75 <notextile>
  76 <pre><code>~$ <span class="userinput">arv-ls -s ae480c5099b81e17267b7445e35b4bc7+180</span>
  77      12258 ./HWI-ST1027_129_D0THKACXX.1_1.fastq
  78      12258 ./HWI-ST1027_129_D0THKACXX.1_2.fastq
  79 </code></pre>
  80 </notextile>
  81
  82 Use @arv-get@ to download the contents of a collection and place it in the directory specified in the second argument (in this example, @.@ for the current directory):
  83
  84 <notextile>
  85 <pre><code>~$ <span class="userinput">$ arv-get ae480c5099b81e17267b7445e35b4bc7+180/ .</span>
  86 23 MiB / 23 MiB 100.0%
  87 ~$ <span class="userinput">ls</span>
  88 HWI-ST1027_129_D0THKACXX.1_1.fastq  HWI-ST1027_129_D0THKACXX.1_2.fastq
  89 </code></pre>
  90 </notextile>
  91
  92 You can also download individual files:
  93
  94 <notextile>
  95 <pre><code>~$ <span class="userinput">arv-get ae480c5099b81e17267b7445e35b4bc7+180/HWI-ST1027_129_D0THKACXX.1_1.fastq .</span>
  96 11 MiB / 11 MiB 100.0%
  97 </code></pre>
  98 </notextile>
  99
 100 h3. Federated downloads
 101
 102 If your cluster is "configured to be part of a federation":{{site.baseurl}}/admin/federation.html you can also download collections hosted on other clusters (with appropriate permissions).
 103
 104 If you request a collection by portable data hash, it will first search the home cluster, then search federated clusters.
 105
 106 You may also request a collection by UUID.  In this case, it will contact the cluster named in the UUID prefix (in this example, @zzzzz@).
 107
 108 <notextile>
 109 <pre><code>~$ <span class="userinput">arv-get zzzzz-4zz18-fw6dnjxtkvzdewt/ .</span>
 110 </code></pre>
 111 </notextile>