docs: Add debug console to dev guide #74

jodh-intel · 2018-05-14T15:25:56Z

Add an appendix explaining how to setup a debug console to login to the
virtual machine for debugging.

Fixes #72.

Signed-off-by: James O. D. Hunt james.o.hunt@intel.com

jodh-intel · 2018-05-14T15:26:15Z

Hi @egernst, @devimc, @klynnrif - ptal.

jodh-intel · 2018-05-14T16:26:37Z

/cc @mcastelino.

klynnrif

Scrubbed for grammar, flow, and structure. A few changes and hopefully I did not change meaning. Thanks!

klynnrif · 2018-05-14T17:06:03Z

Developer-Guide.md

@@ -24,6 +24,15 @@
 * [Troubleshoot Kata Containers](#troubleshoot-kata-containers)
 * [Appendices](#appendices)
    * [Checking Docker default runtime](#checking-docker-default-runtime)
+    * [Setting up a debug console](#setting-up-a-debug-console)


Suggest changing this title to "Set up a debug console" to avoid using the gerund (ing) format.

klynnrif · 2018-05-14T17:06:55Z

Developer-Guide.md

@@ -277,10 +286,131 @@ To perform analysis on Kata logs, use the
 [`kata-log-parser`](https://github.com/kata-containers/tests/tree/master/cmd/log-parser)
 tool.

+See also [Setting up a debug console](#setting-up-a-debug-console).


Suggest removing "also": See Setting up a debug console.

klynnrif · 2018-05-14T17:14:36Z

Developer-Guide.md

+
+## Setting up a debug console
+
+By default, it is not possible to login to a virtual machine since this could


Lines 301-304 suggested rewrite (unless I've changed the meaning): By default you cannot login to a virtual machine since this can be sensitive from a security perspective. However a virtual machine also requires additional packages in the rootfs, which means the image used to boot each virtual machine is larger.

After a coffee, that paragraph reads rather strangely in both forms :)

I've tried to reword using your suggested phrasing and come up with:

By default you cannot login to a virtual machine since this can be sensitive
from a security perspective. Also allowing logins would require additional
packages in the rootfs, which would increase the size of the image used to
boot the virtual machine.

Ha! I like your phrasing. Thanks :)

klynnrif · 2018-05-14T17:18:44Z

Developer-Guide.md

+packages in the rootfs which means the image used to boot each virtual machine
+would be larger.
+
+If you wish to be able to login to a virtual machine that hosts your


Lines 306-307 suggested rewrite: If you want to login to a virtual machine that hosts your containers, complete the following steps, which assume a rootfs image.

klynnrif · 2018-05-14T17:19:52Z

Developer-Guide.md

+
+### Create a custom image containing a shell
+
+To be able to login to a virtual machine, you must [create a custom


To login to a virtual machine...

klynnrif · 2018-05-14T17:20:50Z

Developer-Guide.md

+EOT
+```
+
+**Note**: You may need to adjust the `ExecStart=` path.


Note: You might need to adjust the ExecStart= path.

klynnrif · 2018-05-14T17:22:00Z

Developer-Guide.md

+Next, modify the `image=` values in the `[hypervisor.qemu]` section of the
+[configuration file](https://github.com/kata-containers/runtime#configuration)
+to specify the full path to the image name specified in the previous code
+section. Alternatively, recreate the symbolic link so that it is pointing to


...Alternatively, recreate the symbolic link so it points to

klynnrif · 2018-05-14T17:23:04Z

Developer-Guide.md

+$ (cd /usr/share/kata-containers && sudo ln -sf "$name" kata-containers.img)
+```
+
+**Note**: You should take care to undo this change after finishing debugging


Note: You should take care to undo this change after you finish debugging

klynnrif · 2018-05-14T17:25:02Z

Developer-Guide.md

+
+### Obtain details of the image
+
+If the image was created using


If the image is created using

klynnrif · 2018-05-14T17:25:47Z

Developer-Guide.md

+
+If the image was created using
+[osbuilder](https://github.com/kata-containers/osbuilder), the following YAML
+file will exist and contain details of the image and how it was created:


file exists and contains details of the image and how it was created:

jodh-intel · 2018-05-15T08:56:33Z

Thanks @klynnrif - branch updated.

klynnrif

lgtm - thanks!

jodh-intel · 2018-05-17T06:18:20Z

ping @kata-containers/documentation.

caoruidong

LGTM, just a missing [

caoruidong · 2018-05-17T06:44:22Z

Developer-Guide.md

@@ -277,10 +286,132 @@ To perform analysis on Kata logs, use the
 [`kata-log-parser`](https://github.com/kata-containers/tests/tree/master/cmd/log-parser)
 tool.

+See Set up a debug console](#set-up-a-debug-console).


Good catch @caoruidong! ;) Branch updated.

You cannot remove an existing rootfs directory without being `root`, so use `sudo(8)` in the developer guide. Signed-off-by: James O. D. Hunt <james.o.hunt@intel.com>

Add an appendix explaining how to setup a debug console to login to the virtual machine for debugging. Fixes kata-containers#72. Signed-off-by: James O. D. Hunt <james.o.hunt@intel.com>

jodh-intel · 2018-05-17T10:37:45Z

Hi @egernst, @bergwolf - ptal.

When docker is used for building rootfs the EXTRA_PKGS should be passed as env var Fixes kata-containers#74 Signed-off-by: Harshal Patil <harshal.patil@in.ibm.com>

jodh-intel force-pushed the dev-guide-debug-console branch from 5de6200 to ece746e Compare May 14, 2018 15:38

klynnrif suggested changes May 14, 2018

View reviewed changes

jodh-intel force-pushed the dev-guide-debug-console branch 2 times, most recently from 0d80e62 to 2641e50 Compare May 15, 2018 08:54

klynnrif approved these changes May 16, 2018

View reviewed changes

caoruidong approved these changes May 17, 2018

View reviewed changes

docs: Use sudo to remove old rootfs in dev guide

b94fbf7

You cannot remove an existing rootfs directory without being `root`, so use `sudo(8)` in the developer guide. Signed-off-by: James O. D. Hunt <james.o.hunt@intel.com>

jodh-intel force-pushed the dev-guide-debug-console branch 2 times, most recently from ab49e57 to 6d6e750 Compare May 17, 2018 10:22

docs: Add debug console to dev guide

36e974b

Add an appendix explaining how to setup a debug console to login to the virtual machine for debugging. Fixes kata-containers#72. Signed-off-by: James O. D. Hunt <james.o.hunt@intel.com>

jodh-intel force-pushed the dev-guide-debug-console branch from 6d6e750 to 36e974b Compare May 17, 2018 10:36

egernst approved these changes May 17, 2018

View reviewed changes

egernst merged commit 561fead into kata-containers:master May 17, 2018

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs: Add debug console to dev guide #74

docs: Add debug console to dev guide #74

jodh-intel commented May 14, 2018

jodh-intel commented May 14, 2018

jodh-intel commented May 14, 2018

klynnrif left a comment

klynnrif May 14, 2018

klynnrif May 14, 2018

klynnrif May 14, 2018

jodh-intel May 15, 2018

klynnrif May 16, 2018

klynnrif May 14, 2018

klynnrif May 14, 2018

klynnrif May 14, 2018

klynnrif May 14, 2018

klynnrif May 14, 2018

klynnrif May 14, 2018

klynnrif May 14, 2018

jodh-intel commented May 15, 2018

klynnrif left a comment

jodh-intel commented May 17, 2018

caoruidong left a comment

caoruidong May 17, 2018

jodh-intel May 17, 2018

jodh-intel commented May 17, 2018


		## Setting up a debug console

		By default, it is not possible to login to a virtual machine since this could


		### Create a custom image containing a shell

		To be able to login to a virtual machine, you must [create a custom


		### Obtain details of the image

		If the image was created using

docs: Add debug console to dev guide #74

docs: Add debug console to dev guide #74

Conversation

jodh-intel commented May 14, 2018

jodh-intel commented May 14, 2018

jodh-intel commented May 14, 2018

klynnrif left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jodh-intel commented May 15, 2018

klynnrif left a comment

Choose a reason for hiding this comment

jodh-intel commented May 17, 2018

caoruidong left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jodh-intel commented May 17, 2018