Merge branch 'main' into 21841-missing-vocab
[arvados.git] / doc / user / debugging / container-shell-access.html.textile.liquid
1 ---
2 layout: default
3 navsection: userguide
4 title: Debugging workflows - shell access
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 {% include 'tutorial_expectations' %}
13
14 {% include 'notebox_begin' %}
15
16 To use this feature, your Arvados installation must be configured to allow container shell access. See "the install guide":{{site.baseurl}}/install/container-shell-access.html for more information.
17
18 {% include 'notebox_end' %}
19
20 The @arvados-client@ program can be used to connect to a container in a running workflow. It can be installed from packages (@apt install arvados-client@ or @dnf install arvados-client@). The @arvados-client shell@ command provides an ssh connection into a running container.
21
22 h2(#syntax). Syntax
23
24 The @arvados-client shell@ tool has the following syntax:
25
26 <notextile>
27 <pre><code>~$ <span class="userinput">arvados-client shell -h</span>
28 arvados-client shell: open an interactive shell on a running container.
29
30 Usage: arvados-client shell [options] [username@]container-uuid [ssh-options] [remote-command [args...]]
31
32 Options:
33   -detach-keys string
34       set detach key sequence, as in docker-attach(1) (default "ctrl-],ctrl-]")
35
36 </code></pre>
37 </notextile>
38
39 The @arvados-client shell@ command calls the ssh binary on your system to make the connection. Everything after _[username@]container-uuid_ is passed through to your OpenSSH client.
40
41 h2(#Examples). Examples
42
43 Connect to a running container, using the container request UUID:
44
45 <notextile>
46 <pre><code>~$ <span class="userinput">arvados-client shell ce8i5-xvhdp-e6wnujfslyyqn4b</span>
47 root@0f13dcd755fa:~#
48 </code></pre>
49 </notextile>
50
51 The container UUID also works:
52
53 <notextile>
54 <pre><code>~$ <span class="userinput">arvados-client shell ce8i5-dz642-h1cl0sa62d4i430</span>
55 root@0f13dcd755fa:~#
56 </code></pre>
57 </notextile>
58
59 SSH port forwarding is supported:
60
61 <notextile>
62 <pre><code>~$ <span class="userinput">arvados-client shell ce8i5-dz642-h1cl0sa62d4i430 -L8888:localhost:80</span>
63 root@0f13dcd755fa:~# nc -l -p 80
64 </code></pre>
65 </notextile>
66
67 And then, connecting to port 8888 locally:
68
69 <notextile>
70 <pre><code>~$ <span class="userinput">echo hello | nc localhost 8888</span>
71 </code></pre>
72 </notextile>
73
74 Which appears on the other end:
75
76 <notextile>
77 <pre><code>~$ <span class="userinput">arvados-client shell ce8i5-dz642-h1cl0sa62d4i430 -L8888:localhost:80</span>
78 root@0f13dcd755fa:~# nc -l -p 80
79 hello
80 </code></pre>
81 </notextile>