From aa142c06584179f34a5ff631e7318f79a35b8226 Mon Sep 17 00:00:00 2001 From: Roman Penyaev Date: Sat, 21 Oct 2023 22:40:47 +0200 Subject: [PATCH] docs/DEBUGGING.md: add 'application console' section The application console section describes usage of application consoles. Signed-off-by: Roman Penyaev --- docs/DEBUGGING.md | 60 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 60 insertions(+) diff --git a/docs/DEBUGGING.md b/docs/DEBUGGING.md index 0f5e7aa9f5a..6f92a7132bf 100644 --- a/docs/DEBUGGING.md +++ b/docs/DEBUGGING.md @@ -93,6 +93,66 @@ tail -F /run/diag.out In addition this information is provided to application instances on the device using [the diag API endpoint](./ECO-METADATA.md). +## Application console + +A running application on an EVE device has a console for input or output. You can attach to the application console from the EVE device as a control terminal if the application (VM or Container) listens to the TTY line and communicates with the virtual console /dev/hvc0 device. For example for popular linux distributions deployed as VM application this is usually the case. + +First list applications consoles of all running QEMU (KVM) processes: + +```bash +# eve list-app-consoles +PID APP-UUID CONS-TYPE CONS-ID +--- -------- --------- --------- +3883 e4e2f56d-b833-4562-a86f-be654d6387ba VM e4e2f56d-b833-4562-a86f-be654d6387ba.1.1/cons +4072 f6d348cc-9c31-4f8b-8c4f-a4aae4590b97 CONTAINER f6d348cc-9c31-4f8b-8c4f-a4aae4590b97.1.2/cons +4072 f6d348cc-9c31-4f8b-8c4f-a4aae4590b97 VM f6d348cc-9c31-4f8b-8c4f-a4aae4590b97.1.2/prime-cons + +``` + +Choose console ID you need to attach and pass it as an argument to the `eve attach-app-console` command: + +```bash +# eve attach-app-console e4e2f56d-b833-4562-a86f-be654d6387ba.1.1/cons +[20:26:15.116] tio v1.37 +[20:26:15.116] Press ctrl-t q to quit +[20:26:15.116] Connected + + +Ubuntu 18.04.6 LTS user hvc0 + +user login: +``` + +Note: `tio` utility is used as a simple TTY terminal, so in order to quit the session please press `ctrl-t q` or read the `tio` manual for additional commands. + +The same 'cons' console ID can be used for the Container application, but please be aware if container does not start a shell then terminal is very limited and can be used only for reading for the console output, but not for executing commands. + +In order to attach to the console of the hosting Vm of the Container application another console ID should be used which is named `prime-cons`: + +```bash +# eve attach-app-console f6d348cc-9c31-4f8b-8c4f-a4aae4590b97.1.2/prime-cons +[20:41:47.124] tio v1.37 +[20:41:47.124] Press ctrl-t q to quit +[20:41:47.124] Connected + +~ # +``` + +The `prime-cons` console exists only for the Container applications and is always reachable for executing commands on the Vm which hosts corresponding container. + +Once terminal responds on the `prime-cons` console it is possible to enter container by executing the `eve-enter-container` command: + +```bash +~ # eve-enter-container +(none):/# ps awux +PID USER TIME COMMAND + 1 root 0:00 /bin/sh + 6 root 0:00 -ash + 7 root 0:00 ps awux +(none):/# exit +~ # +``` + ## Reboots EVE is architected in such a way that if any service is unresponsive for a period of time, the entire device will reboot. When this happens a BootReason is constructed and sent in the device info message to the controller. If there is a golang panic there can also be useful information found in `/persist/agentdebug/`.