docs/DEBUGGING.md: add 'application console' section

The application console section describes usage of application consoles. Signed-off-by: Roman Penyaev <[email protected]>
lf-edge · Oct 22, 2023 · b9a9708 · b9a9708
1 parent 289a643
commit b9a9708
Showing 1 changed file with 53 additions and 0 deletions.
diff --git a/docs/DEBUGGING.md b/docs/DEBUGGING.md
@@ -93,6 +93,59 @@ 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. Here is the way how to attach to the VM console:
+
+```bash
+# eve enter debug
+# ls /run/hypervisor/kvm/*/cons
+/run/hypervisor/kvm/5c9b86e2-bd60-4140-9ea7-b0ffa65ddb7a.1.1/cons
+# eve attach-app-console /run/hypervisor/kvm/5c9b86e2-bd60-4140-9ea7-b0ffa65ddb7a.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
+<PRESS ENTER>
+
+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 sessiom please press `ctrl-t q` or read the `tio` manual for additional commands.
+
+The same 'cons' file 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 file should be used:
+
+```bash
+# eve enter debug
+# ls /run/hypervisor/kvm/*/prime-cons
+/run/hypervisor/kvm/52e796b4-9cf1-4262-9f72-0cbeded0cbad.1.1/prime-cons
+# eve attach-app-console /run/hypervisor/kvm/52e796b4-9cf1-4262-9f72-0cbeded0cbad.1.1/prime-cons
+[20:41:47.124] tio v1.37
+[20:41:47.124] Press ctrl-t q to quit
+[20:41:47.124] Connected
+<PRESS ENTER>
+~ #
+```
+
+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/`.