package emulator const ( connectHelp = ` RemoteCLI prompt is designed to help you establish a connection with a session. The session can be specified using either a banner name, store name and node hostname, or using the Banner Edge ID, Cluster Edge ID and Terminal ID of the node to connect to. NOTE: For RCLI Phase 1 version, you will need to provide the Project ID, along with Banner Edge ID, Cluster Edge ID and Terminal ID. Names cannot be used with this version. For Example > connect ======= connect ======= An example connect command would be: > connect If the and values have been set in your workspace (see rcliconfig docs below to update this), then connect to a terminal with: (NOTE that you cannot set a as the only parameter in workspace. It has to be a pair of and ) > connect The value always needs to be provided. The order of the arguments need to be respected. If has been set in the workspace but not , the command to connect would HAVE to be: > connect If an argument is set in your workspace but you provide a different argument at connect, the argument provided to connect will override the workspace argument. For example, if your workspace has and set as follows: Workspace: BannerID: banner-id-1, StoreID: store-id-1 then passing the connection command: > connect banner-id-2 store-id-2 terminal-id-2 would connect to banner-id-2 and not banner-id-1. Your workspace will however remain unchanged, so to connect to banner-id-1 and store-id-1 after disconnecting from terminal-id-2 the connection command would be: > connect terminal-id-1 ===== shell ===== While connect mode allows sending a single command to the IEN and returing the full output of the command in an interactive prompt, in some cases it may be desirable to interact with the command output, such as piping it into another command for further processing or saving it to a variable to be used in a pipeline. shell mode has been created to enable a limited subset of shell features with remote command output. shell mode can be entered from the remotecli prompt using the details of the terminal you wish to connect to: > shell This enters the local shell prompt, indicated by the "<> " prompt. Commands entered into the shell prompt are executed in a local shell, however the environment is set up to enable running the "remotecli exec" command. The "remotecli exec" command can be used to send a single non interactive command to the IEN, allowing it to be used in a pipeline. Examples: An example usage of the shell mode is to allow piping command output into another command, for example to find specific lines in a log file: <> remotecli exec "cat /var/log/boot.log.1" | grep ien-fw.service Another example may be to store the output of one command in a variable to use it as an argument of a subsequent command. The following command finds the pod name of the displayctl pod on the 1st worker node and saves it into a local variable called "displayctl". That local variable is then used as an argument to a subsequent command which executes "xrandr" within the pod via kubectl exec. <> node="s2-worker-1"; displayctl=$(remotecli exec "kubectl --kubeconfig /etc/kubernetes/zylevel0.conf get pods -n display --field-selector spec.nodeName=$node -l app.kubernetes.io/name=displayctl -o name"); remotecli exec "echo $displayctl"; remotecli exec "kubectl --kubeconfig /etc/kubernetes/zylevel0.conf exec -n display $displayctl -- xrandr" Note: Currently the stdout and stderr of the remote command appears as a single stdout of the remotecli exec command, which means the behaviour of running remotecli exec in local shell may be different if the command was run directly on a shell on the terminal. Currently the local shell in use is bash, and this shell must be present on the system for local shell mode to work. ========== rcliconfig ========== To avoid having to provide all arguments every time you connect, a workspace has been provided which can store and IDs/names. To set values in workspace, use the rcliconfig command and provide the variable you want to change and the value. For example, to set a new : > rcliconfig bannerID a-new-banner-id The same holds true for the . If you would like to unset the variables in the workspace, UNSET or "" can be provided as a value. For example: > rcliconfig bannerID UNSET or > rcliconfig bannerID "" would both result in the workspace being unset. NOTE: For RCLI Phase 1 version when connecting to a store the binary creates a new GCP subscription by default, allowing multiple users to connect to the same store at the same time. Some users may not have appropriate permissions for this action, which means the connecting to the prompt may fail with an error: Error creating subscription. If this occurs you can disable creation of a new subscription by running the following rcliconfig command > rcliconfig disablePerSessionSubscription Please note that only a single user with this setting enabled can connect to a single store at the same time. Once the per session subscription has been disabled, it will remain disabled until it is manually enabled again, with the following option. This setting is persisted in the workspace across binary restarts > rcliconfig enablePerSessionSubscription ======= History ======= Both the history and workspace are stored to disk in between runtimes. The binary can therefore be exited and restarted without losing information. ===================== Environment Variables ===================== - RCLI_SESSION_TIMEOUT - Specify length of time before session timeout after inactivity. Valid time units are "ns", "us" (or "µs"), "ms", "s", "m", "h". Examples: "300ms" or "2h45m". Default is 300s (5m). - RCLI_WORKSPACE_DIR - See workspace documentation. Defaults to the current working directory. ` sessionHelp = ` Session prompt is an interactive prompt similar to ssh that will submit commands to the connected IEN. There are however some key differences to a standard shell: 1. The session prompt will not return automatically on completion of a command, you will always need to press 'enter' again. 2. The commands are submitted asynchronously. 3. Whenever the prompt is active the output will not be displayed. In the example command: >>> echo hello world hello world upon return of the output you will notice the session prompt (>>>) has not returned. You will need to press enter to submit a new command. One can always press 'enter' again in order to submit a new command before the previous one has completed. For example: >>> sleep 4; echo after >>> echo before before after If you wait longer than 4 seconds in the above example, the output would be: after before since the "echo after" command has already been returned and buffered but will wait until the session prompt has exited before displaying. ======================= Session Command Options ======================= The session prompt allows setting options on commands to allow local processing of command responses. After typing a command before pressing enter to execute the command you can use the "Ctrl+S" key to enter an option. Options are specified after the option specifier ||||, and are composed of the option to be applied to the command, and any arguments that the option requires. Note you must use the Ctrl+S key to enter session options, if you directly type the option specifier, this will be interpreted as part of the command that is sent to the IEN. >>> command |||| option [arguments...] Everything before |||| will be interpreted as the command to be executed on the IEN, while everything after |||| will be the options applied to the command. Currently one option is defined: File Redirection: The file redirection option allows saving the command output to a file rather than printing it to screen. - Option: > - arguments: filename e.g. The following command will save the journal output to a local file on the gcloud shell. >>> sudo journalctl -u remote-access-agent.service |||| > journaloutput.txt ============= Troubleshoot ============= Session prompt not returning output: Things to check 1. Use GCP Store health dashboard to investigate if terminal is up and running and connected to the LAN 2. Use GCP Logs to investigate if remote access agent is up and running. The following GCP Log filter for systemd unit can be used - "jsonPayload._SYSTEMD_UNIT="remote-access-agent.service" 3. For RCLI Phase 1 if you provide an incorrect at connect, the session prompt will not return an error but will not respond when commands are submitted either. This is as a result of the underlying messaging architecture the emulator uses to communicate (pub/sub). If this happens please exit the session prompt and check the terminal id is correct and that the IEN is active on the cluster. Another reason the IEN can become unresponsive is if another emulator instance is connected to any IEN on the same store. Therefore, please ensure any other session prompts have exited before trying to connect. ` )