1 package emulator
2
3 const (
4 connectHelp = `
5 RemoteCLI prompt is designed to help you establish a connection with a session. The session can be specified using either a banner name,
6 store name and node hostname, or using the Banner Edge ID, Cluster Edge ID and Terminal ID of the node to connect to.
7 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.
8 Names cannot be used with this version.
9 For Example
10 > connect <project-id> <banner-id> <store-id> <terminal-id>
11
12 =======
13 connect
14 =======
15 An example connect command would be:
16
17 > connect <banner> <store> <terminal>
18
19 If the <banner> and <store> values have been set in your workspace (see rcliconfig docs below to update this), then connect to a terminal with:
20 (NOTE that you cannot set a <store> as the only parameter in workspace. It has to be a pair of <banner> and <store>)
21
22 > connect <terminal>
23
24 The <terminal> value always needs to be provided. The order of the arguments need to be respected. If <banner> has been set in the workspace
25 but not <store>, the command to connect would HAVE to be:
26
27 > connect <store> <terminal>
28
29 If an argument is set in your workspace but you provide a different argument at connect, the argument provided to connect will override
30 the workspace argument.
31 For example, if your workspace has <banner> and <store> set as follows:
32
33 Workspace: BannerID: banner-id-1, StoreID: store-id-1
34
35 then passing the connection command:
36
37 > connect banner-id-2 store-id-2 terminal-id-2
38
39 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
40 after disconnecting from terminal-id-2 the connection command would be:
41
42 > connect terminal-id-1
43
44 =====
45 shell
46 =====
47
48 While connect mode allows sending a single command to the IEN and returing the full output of the command in an interactive prompt,
49 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.
50 shell mode has been created to enable a limited subset of shell features with remote command output.
51
52 shell mode can be entered from the remotecli prompt using the details of the terminal you wish to connect to:
53
54 > shell <banner> <store> <terminal>
55
56 This enters the local shell prompt, indicated by the "<> " prompt.
57 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.
58 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.
59
60 Examples:
61
62 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:
63
64 <> remotecli exec "cat /var/log/boot.log.1" | grep ien-fw.service
65
66 Another example may be to store the output of one command in a variable to use it as an argument of a subsequent command.
67 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".
68 That local variable is then used as an argument to a subsequent command which executes "xrandr" within the pod via kubectl exec.
69
70 <> 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"
71
72 Note:
73 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.
74
75 Currently the local shell in use is bash, and this shell must be present on the system for local shell mode to work.
76
77
78 ==========
79 rcliconfig
80 ==========
81 To avoid having to provide all arguments every time you connect, a workspace has been provided which can store <banner> and <store> IDs/names.
82 To set values in workspace, use the rcliconfig command and provide the variable you want to change and the value.
83 For example, to set a new <banner>:
84
85 > rcliconfig bannerID a-new-banner-id
86
87 The same holds true for the <store>. If you would like to unset the variables in the workspace, UNSET or "" can be provided as a value.
88 For example:
89
90 > rcliconfig bannerID UNSET
91
92 or
93
94 > rcliconfig bannerID ""
95
96 would both result in the workspace <banner> being unset.
97
98
99 NOTE: For RCLI Phase 1 version when connecting to a store the binary creates a new GCP subscription by default,
100 allowing multiple users to connect to the same store at the same time. Some users may not have appropriate permissions for this action,
101 which means the connecting to the prompt may fail with an error: Error creating subscription. If this occurs you can disable creation
102 of a new subscription by running the following rcliconfig command
103
104 > rcliconfig disablePerSessionSubscription
105
106 Please note that only a single user with this setting enabled can connect to a single store at the same time.
107
108 Once the per session subscription has been disabled, it will remain disabled until it is manually enabled again, with the following option.
109 This setting is persisted in the workspace across binary restarts
110
111 > rcliconfig enablePerSessionSubscription
112
113 =======
114 History
115 =======
116 Both the history and workspace are stored to disk in between runtimes. The binary can therefore be exited and restarted
117 without losing information.
118
119 =====================
120 Environment Variables
121 =====================
122 - RCLI_SESSION_TIMEOUT - Specify length of time before session timeout after inactivity.
123 Valid time units are "ns", "us" (or "µs"), "ms", "s", "m", "h". Examples: "300ms" or "2h45m". Default is 300s (5m).
124 - RCLI_WORKSPACE_DIR - See workspace documentation. Defaults to the current working directory.
125 `
126
127 sessionHelp = `
128 Session prompt is an interactive prompt similar to ssh that will submit commands to the connected IEN.
129 There are however some key differences to a standard shell:
130
131 1. The session prompt will not return automatically on completion of a command, you will always need to press 'enter' again.
132 2. The commands are submitted asynchronously.
133 3. Whenever the prompt is active the output will not be displayed.
134
135 In the example command:
136
137 >>> echo hello world
138
139 hello world
140
141 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.
142
143 One can always press 'enter' again in order to submit a new command before the previous one has completed.
144 For example:
145
146 >>> sleep 4; echo after
147
148 >>> echo before
149
150 before
151
152 after
153
154 If you wait longer than 4 seconds in the above example, the output would be:
155
156 after
157
158 before
159
160 since the "echo after" command has already been returned and buffered but will wait until the session prompt has exited before displaying.
161
162 =======================
163 Session Command Options
164 =======================
165
166 The session prompt allows setting options on commands to allow local processing of command responses.
167 After typing a command before pressing enter to execute the command you can use the "Ctrl+S" key to enter an option.
168 Options are specified after the option specifier |||| , and are composed of the option to be applied to the command,
169 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,
170 this will be interpreted as part of the command that is sent to the IEN.
171
172 >>> command |||| option [arguments...]
173
174 Everything before |||| will be interpreted as the command to be executed on the IEN,
175 while everything after |||| will be the options applied to the command.
176
177 Currently one option is defined:
178
179 File Redirection:
180 The file redirection option allows saving the command output to a file rather than printing it to screen.
181
182 - Option: >
183 - arguments: filename
184
185 e.g. The following command will save the journal output to a local file on the gcloud shell.
186
187 >>> sudo journalctl -u remote-access-agent.service |||| > journaloutput.txt
188
189 =============
190 Troubleshoot
191 =============
192 Session prompt not returning output:
193 Things to check
194 1. Use GCP Store health dashboard to investigate if terminal is up and running and connected to the LAN
195 2. Use GCP Logs to investigate if remote access agent is up and running.
196 The following GCP Log filter for systemd unit can be used - "jsonPayload._SYSTEMD_UNIT="remote-access-agent.service"
197 3. For RCLI Phase 1 if you provide an incorrect <terminal> at connect, the session prompt will not return an error but will
198 not respond when commands are submitted either. This is as a result of the underlying messaging architecture the emulator
199 uses to communicate (pub/sub). If this happens please exit the session prompt and check the terminal id is correct and
200 that the IEN is active on the cluster. Another reason the IEN can become unresponsive is if another emulator instance is
201 connected to any IEN on the same store. Therefore, please ensure any other session prompts have exited before trying to connect.
202 `
203 )
204
View as plain text