nodeconsole(8) -- Open a console to a confluent node
=====================================================

## SYNOPSIS
`nodeconsole [options] <noderange> [kill][-- [passthroughoptions]]`

## DESCRIPTION

**nodeconsole** opens an interactive console session to a given node.  This is the
text or serial console of a system.  Exiting is done by hitting `Ctrl-e`, then `c`,
 then `.`.  Note that console output by default is additionally logged to
`/var/log/confluent/consoles/`**NODENAME**.

When the console connection to the target is broken, then confluent on backend
will initiate an automatic retry interval that is randomized between 2 and 4 minutes.
The reopen escape sequence below requests an immediate retry, as does connecting
a new session.

When a windowed console is open the `nodeconsole <noderange> kill` command will kill the
console process which will result in the console window closing. 

## OPTIONS

* `-i N`, `--interval`:
  For screenshot mode, fetch new screenshots and overwrite old screenshots every N seconds.
  For example, `nodeconsole r3u[21:24] -tsi 3` will tile screenshots of r3u21 through r3u24 and
  refresh them every 3 seconds.

* `-t`, `--tile`:
  For text consoles, use tmux to arrange consoles of the given noderange into a tiled layout on
  the terminal screen.  If using 'screenshot' mode, divide the terminal and display the images
  in a grid. 

* `-l`, `--log`:
  Perform a log reply on the current, local log in /var/log/confluent/consoles.
  If in collective mode, this only makes sense to use on the current collective
  manager at this time.

  * `-T`, `--Timestamp`:
 Dump the log with Timestamps on the current, local log in /var/log/confluent/consoles.
  If in collective mode, this only makes sense to use on the current collective
  manager at this time.

* `-s`, `--screenshot`:
  Attempt to grab screenshot(s) and render using a terminal
  image protocol. The image protocol defaults to kitty, and
  can be selected by CONFLUENT_IMAGE_PROTOCOL environment variable.
  Supported protocols are kitty, iterm, and, sixel (sixel only
  if PySixel is installed).  This only presents screenshots, there
  is no input supported to graphical consoles from a terminal.
  
* `-w`, `--windowed`:
  Open terminal windows for each node.  The
  environment variable **NODECONSOLE_WINDOWED_COMMAND**
  should be set, which should be a text string corresponding
  to a command that can be used to open a windowed console,
  omitting the `nodeconsole <noderange>` part of the
  command, for example, to open a set of consoles for a
  range of nodes in separate xterm windows, set
  **NODECONSOLE_WINDOWED_COMMAND** to `xterm -e`.  To open a
  set of consoles for a range of nodes in separate
  GNOME Terminal windows with a size of 100 columns and
  31 rows, set **NODECONSOLE_WINDOWED_COMMAND**
  to `gnome-terminal --geometry 100x31 --` or in a WSL
  environment, to open a set of consoles for a range of
  nodes in separate Windows Terminal windows, with the
  title set for each node, set **NODECONSOLE_WINDOWED_COMMAND**
  to `wt.exe wsl.exe -d AlmaLinux-8 --shell-type login`.  If the
  NODECONSOLE_WINDOWED_COMMAND environment variable isn't set,
  xterm will be used by default.

## ESCAPE SEQUENCE COMMANDS

While connected to a console, a number of commands may be performed through escape
sequences.  To begin an command escape sequence, hit `Ctrl-e`, then `c`.  The next
keystroke will be interpreted as a command.  The following commands are available.

* `.`:
  Exit the session and return to the command prompt
* `b`:
  [send Break]
  Send a break to the remote console when possible (some console plugins may not support this)
* `o`:
  [reOpen]
  Request confluent to disconnect and reconnect to console.  For example if there is suspicion
  that the console has gone inoperable, but would work if reconnected.
* `po`:
  [Power Off]
  Power off server immediately, without waiting for OS to shutdown
* `ps`:
  [Power Shutdown]
  Request OS shut down gracefully, and then power off
* `pb<ent>`:
  [Power Boot]
  Cause system to immediately boot, resetting or turning on as appropriate.
  Hitting enter is required to execute the reboot rather than another pb sequence
* `pbs`:
  [Power Boot Setup]
  Request immediate boot ultimately landing in interactive firmware setup
* `pbn`:
  [Power Boot Network]
  Request immediate boot to network
* `r`:
  [send Resize]
  This queries the current terminal and sends stty commands to advertise the user terminal
  size to the remote console
* `?`:
  Get a list of supported commands
* `<ent>`:
  Hit enter to skip entering a command at the escape prompt.


## PASSTHROUGH OPTIONS

While opening a windowed console with xterm or any other console of choice. The
nodeconsole command gives capability to specify passthrough options targeted at
the console. All options after the -- will be passed to the console program. For
example, opening a windowed console using xterm with a black background.
`nodeconsole -w n1 -- -bg black`


