This repository has been archived by the owner on Dec 21, 2022. It is now read-only.
-
Notifications
You must be signed in to change notification settings - Fork 0
/
rsh.1
188 lines (184 loc) · 6.31 KB
/
rsh.1
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
.ad l
.\" generated with Ronn/v0.7.3
.\" http://github.com/rtomayko/ronn/tree/0.7.3
.
.TH "RSH" "1" "February 2018" "" ""
.
.SH "NAME"
\fBrsh\fR \- Rancher SHell
.
.SH "SYNOPSIS"
\fBrsh\fR [\fB\-GqTtv\fR] [\fB\-E\fR \fIlog_file\fR] [\fB\-e\fR \fIchar\fR] [\fB\-F\fR \fIconfig_file\fR] [\fB\-h\fR|\fB\-\-help\fR] [\fB\-l\fR \fIlogin_name\fR] [\fB\-o\fR \fIopt\fR] [\fB\-p\fR \fIport\fR] [\fB\-V\fR|\fB\-\-version\fR] [\fIprotocol\fR://][\fIuser\fR@]\fIhost\fR[:\fIport\fR][[/\fIenvironment\fR]/\fIstack\fR]/\fIservice\fR [\fIcommand\fR]
.
.SH "DESCRIPTION"
\fBrsh\fR aims to replicate the features and experience of ssh, but for docker containers running within Rancher, as such it is a program for connecting into a remote container and for executing commands on a remote container\.
.
.P
\fBrsh\fR queries the Rancher API at \fIhost\fR to find a container within the specified \fIenvironment\fR, \fIstack\fR, and \fIservice\fR then connects to the first available container\.
.
.P
If \fIcommand\fR is specified, it is executed on the remote host instead of a login shell\.
.
.SH "OPTIONS"
.
.TP
\fB\-E\fR \fIlog_file\fR
Append debug logs to \fIlog_file\fR instead of standard error\.
.
.TP
\fB\-e\fR \fIchar\fR
Sets the escape character for sessions with a pty (default: \'~\')\. The escape character is only recognised at the beginning of a line\. The escape character followed by a dot (\'\.\') closes the connection; followed by control\-Z suspends the connection; and followed by itself sends the escape character once\. Setting the character to "none" disables any escapes and makes the session fully transparent\.
.
.TP
\fB\-F\fR \fIconfig_file\fR
Specifies an alternative per\-user configuration file\. If a configuration file is given on the command line, the system\-wide configuration file (\fI/etc/rsh/rsh_config\fR) will be ignored\. The default for the per\-user configuration file is \fI~/\.rsh/config\fR\.
.
.TP
\fB\-G\fR
Causes \fBrsh\fR to print its configuration after evaluating Host blocks and exit\.
.
.TP
\fB\-h\fR, \fB\-\-help\fR
Causes \fBrsh\fR to print a short help message and exit\.
.
.TP
\fB\-l\fR \fIlogin_name\fR
Specifies the user to log in as on the remote machine\. This also may be specified on a per\-host basis in the configuration file\.
.
.TP
\fB\-o\fR \fIopt\fR
Can be used to give options in the format used in the configuration file\. This is useful for specifying options for which there is no separate command\-line flag\. For full details of the options listed below, and their possible values, see rsh_config(5)\.
.
.IP "" 4
.
.nf
Container
Environment
EscapeChar
HostName
LogLevel
Port
Protocol
RemoteCommand
RequestTty
SendEnv
Service
Stack
User
.
.fi
.
.IP "" 0
.
.TP
\fB\-p\fR \fIport\fR
Port to connect to on the remote host\. This can be specified on a per\-host basis in the configuration file\.
.
.TP
\fB\-q\fR
Quiet mode\. Causes most warning and diagnostic messages to be suppressed\.
.
.TP
\fB\-T\fR
Disable pseudo\-terminal allocation\.
.
.TP
\fB\-t\fR
Force pseudo\-terminal allocation\. This can be useful when executing a shell or console program directly, rather than performing a login\. Multiple \fB\-t\fR options force tty allocation, even if rsh has no local tty\.
.
.TP
\fB\-V\fR, \fB\-\-version\fR
Display the version number and exit\.
.
.TP
\fB\-v\fR
Verbose mode\. Causes \fBrsh\fR to print debugging messages about its progress\. This is helpful in debugging connection, authentication, and configuration problems\. Multiple \fB\-v\fR options increase the verbosity\. The maximum is 3\.
.
.SH "EXAMPLES"
Start a login shell as the \fIroot\fR user on a container in the \fIapi\fR service of the \fIweb\fR stack in the \fIproduction\fR environment of \fIhttps://example\.com\fR\. The current directory will be the home directory of the root user:
.
.IP "" 4
.
.nf
rsh https://root@example\.com/production/web/api
.
.fi
.
.IP "" 0
.
.P
Execute a shell directly on a container in the \fIapi\fR service of the \fIweb\fR stack in the \fIproduction\fR environment of \fIhttps://example\.com\fR\. The user and working directory will match those configured in the service\'s Dockerfile:
.
.IP "" 4
.
.nf
rsh \-t https://example\.com/production/web/api /bin/sh
.
.fi
.
.IP "" 0
.
.SH "AUTHENTICATION"
Upon first connecting to a Rancher server that requires authentication \fBrsh\fR will request a username and password to log into the Rancher server\. It will then create a user API key, and save this to \fI~/\.rsh/\fIhost\fR\fR, using the API key for all further requests\.
.
.P
Currently only LDAP authenticated and unauthenticated Rancher servers have been tested\.
.
.SH "ESCAPE CHARACTERS"
When a pseudo\-terminal has been requested, \fBrsh\fR supports a number of functions through the use of an escape character\.
.
.P
A single tilde character can be sent as ~~ or by following the tilde by a character other than those described below\. The escape character must always follow a newline to be interpreted as special\. The escape character can be changed in configuration files using the \fBEscapeChar\fR configuration directive or on the command line by the \fB\-e\fR option\.
.
.P
The supported escapes (assuming the default \'~\') are:
.
.TP
\fB~\.\fR
Disconnect\.
.
.TP
\fB~^Z\fR
Background rsh\.
.
.TP
\fB~?\fR
Display a list of escape characters\.
.
.TP
\fB~V\fR
Decrease the verbosity (\fBLogLevel\fR) when errors are being written to stderr\.
.
.TP
\fB~v\fR
Increase the verbosity (\fBLogLevel\fR) when errors are being written to stderr\.
.
.SH "FILES"
.
.TP
\fB~/\.rsh/\fR
This directory is the default location for all user\-specific configuration and authentication information\.
.
.TP
\fB~/\.rsh/config\fR
This is the per\-user configuration file\. The file format and configuration options are described in rsh_config(5)\.
.
.TP
\fB/etc/rsh/rsh_config\fR
Systemwide configuration file\. The file format and configuration options are described in rsh_config(5)\.
.
.SH "ENVIRONMENT"
\fBrsh\fR will normally set the following environment variables:
.
.TP
\fBTERM\fR
Set to the value of \fBTERM\fR on the client machine\.
.
.P
Additional environment variables can be forwarded by setting the \fBSendEnv\fR option in rsh_config(5)\.
.
.SH "AUTHORS"
\fBavvoenv\fR is heavily inspired by OpenSSH, and portions of the man page have been directly copied\. It is written and maintained by the Avvo Infrastructure Team \fIinfrastructure@avvo\.com\fR\.
.
.SH "SEE ALSO"
rsh_config(5)