You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@mina.apache.org by lg...@apache.org on 2019/02/21 18:50:50 UTC
[mina-sshd] 05/05: [SSHD-897] Updated documentation regarding PTY
and/or environment configuration when using a shell or command channel
This is an automated email from the ASF dual-hosted git repository.
lgoldstein pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/mina-sshd.git
commit 8a4a3e0fb43500afa446524af477e6fcca095cd0
Author: Lyor Goldstein <lg...@apache.org>
AuthorDate: Wed Feb 20 12:20:17 2019 +0200
[SSHD-897] Updated documentation regarding PTY and/or environment configuration when using a shell or command channel
---
CHANGES.md | 5 +++-
docs/cli.md | 76 +++++++++++++++++++++++++++++++++++++++++++++++++---
docs/client-setup.md | 41 ++++++++++++++++++++++++++--
3 files changed, 116 insertions(+), 6 deletions(-)
diff --git a/CHANGES.md b/CHANGES.md
index 9e82712..d108ad9 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -80,4 +80,7 @@ client.setSignatureFactories(
BuiltinSignatures.dsa));
```
-* [SSHD-896](https://issues.apache.org/jira/browse/SSHD-896) - Added support for [KEX extension negotiation](https://tools.wordtothewise.com/rfc/rfc8308)
+* [SSHD-896](https://issues.apache.org/jira/browse/SSHD-896) - Added support for [KEX extension negotiation](https://tools.ietf.org/html/rfc8308)
+
+* [SSHD-897](https://issues.apache.org/jira/browse/SSHD-897) - The default CLI code automatically tries to detect the PTY settings to use
+if opening a shell or command channel.
diff --git a/docs/cli.md b/docs/cli.md
index b0d6b6b..6c4604d 100644
--- a/docs/cli.md
+++ b/docs/cli.md
@@ -19,9 +19,14 @@ In order to use this CLI code as part of another project, one needs to include t
</dependency>
```
-### Command line clients
+In general, the CLI clients accept most of their Linux counterpart arguments. Furthermore, one can use the `-o Option=Value`
+argument in order to provide **internal** SSHD code configurations (in addition to the ones specified as system
+properties via `-Dprop=value` JVM option.
-* **SftpCommandMain** - by default uses an internal `SftpClientFactory`. This can be overridden as follows:
+### `SftpCommandMain`
+
+A CLI client reminiscent of [sftp(1)](https://linux.die.net/man/1/sftp). By default uses an internal `SftpClientFactory`.
+This can be overridden as follows:
1. Provide a `-o SftpClientFactory=XXX` command line argument where the option specifies the fully-qualified name of
the class that implements this interface.
@@ -31,7 +36,72 @@ the class that implements this interface. **Note:** if more than one such instan
**Note:** The specified class(es) must be public and contain a public no-args constructor.
-### Command line SSH daemon
+The CLI client provides a few extra "commands" that can be used to view metadata information about the current session
+
+* `session` - Show current SSH session details - including ID, client/server identification line, peer, etc..
+* `kex` - Show KEX details - client proposal, server one and negotiated parameters.
+* `info` - General details about the SFTP protocol - e.g., supported extensions by the server.
+* `version` - The negotiated SFTP protocol version.
+* `help` - List all available commands.
+* `exit` - Quit the SFTP session
+
+### `SshClientMain`
+
+A CLI client compatible with the [ssh(1)](https://linux.die.net/man/1/ssh) command line options, with a few extra options:
+
+* `-io` - select a specific `IoServiceFactoryFactory`:
+
+```
+ java -cp ... org.apache.sshd.cli.client.SshClientMain -io <value>
+```
+
+Where value can be:
+
+ * One of the default builtin values (NIO2, MINA, NETTY)
+
+ * A fully qualified class name implementing this interface
+
+ If no specific value provided NIO2 is used.
+
+* `-w <password>` - provide a password as part of the command instead of waiting to be prompted.
+
+```
+ java -cp ... org.apache.sshd.cli.client.SshClientMain -l <login> -w <password> ...host...
+```
+
+* `SetEnv/SendEnv` - can be used to send specific environment variables to the server when executing a command
+or opening a shell. Example:
+
+```
+ java -cp ... org.apache.sshd.cli.client.SshClientMain -o SetEnv=X=7,Y=8
+
+ # Can also be used as separate options
+
+ java -cp ... org.apache.sshd.cli.client.SshClientMain -o SetEnv=X=7 -o SetEnv=Y=8
+```
+
+* `RequestTTY` - can be `no`, `yes` or `auto` (default). If `auto` the CLI client will attempt to initialize
+the PTY options according to the O/S. In **addition** to the auto-detected PTY modes, one can override them
+by using the `PtyMode` option:
+
+```
+ java -cp ... org.apache.sshd.cli.client.SshClientMain -o PtyMode=VINTR,TTY_OP_ISPEED=4200
+
+ # Can also be used as separate options
+
+ java -cp ... org.apache.sshd.cli.client.SshClientMain -o PtyMode=VINTR -o PtyMode=TTY_OP_ISPEED=4200
+```
+
+Any option that does not have a specific value specified for it is assumed to use `1` - therefore, in order
+to **disable** an option one must use `-o PtyMode=WHATEVER=0`.
+
+### `ScpCommandMain`
+
+Reminiscent of the [scp(1)](https://linux.die.net/man/1/scp) CLI client.
+
+### `SshServerMain`
+
+Command line SSH daemon
* **Port** - by default the SSH server sets up to list on port 8000 in order to avoid conflicts with any running SSH O/S daemon.
This can be modified by providing a `-p NNNN` or `-o Port=NNNN` command line option.
diff --git a/docs/client-setup.md b/docs/client-setup.md
index a640153..fbdd284 100644
--- a/docs/client-setup.md
+++ b/docs/client-setup.md
@@ -45,7 +45,7 @@ file to validate the server key. One can use this class + some existing code to
Of course, one can implement the verifier in whatever other manner is suitable for the specific code needs.
-### ClientIdentityLoader/KeyPairProvider
+### `ClientIdentityLoader/KeyPairProvider`
One can set up the public/private keys to be used in case a password-less authentication is needed. By default, the client is configured to automatically
detect and use the identity files residing in the user's *~/.ssh* folder (e.g., *id_rsa*, *id_ecdsa*) and present them as part of the authentication process.
@@ -98,7 +98,7 @@ The usual _OpenSSH_ default seems to be 16, but users can ask for more (or less)
Various discussions on the net seem to indicate that 64 is the value at which many computers start to slow down noticeably, so
our default limit seems quite suitable (and beyond) for most cases we are likely to encounter "in the wild".
-### UserInteraction
+### `UserInteraction`
This interface is required for full support of `keyboard-interactive` authentication protocol as described in [RFC 4256](https://www.ietf.org/rfc/rfc4256.txt).
The client can handle a simple password request from the server, but if more complex challenge-response interaction is required, then this interface must be
@@ -153,3 +153,40 @@ sessions depends on the actual changed configuration. Here is how a typical usag
client.stop();
```
+
+## Running a command or opening a shell
+
+When running a command or opening a shell, there is an extra concern regarding the PTY configuration and/or the
+reported environment variables. By default, unless specific instructions are provided the code uses some internal
+defaults - which however, might not be adequate for the specific client/server.
+
+```java
+ // Assuming one has obtained a ClientSession as already shown
+ try (ClientChannel channel = session.createShellChannel(/* use internal defaults */)) {
+ channel.setIn(...stdin...);
+ channel.setOut(...stdout...);
+ channel.setErr(...stderr...);
+ ... spawn the thread that will pump the STDIN/OUT/ERR
+ channel.open().verify(...some timeout...);
+ // Wait (forever) for the channel to close - signalling shell exited
+ channel.waitFor(EnumSet.of(ClientChannelEvent.CLOSED), 0L);
+ }
+
+ // In order to override the PTY and/or environment
+ Map<String, ?> env = ...some environment...
+ PtyChannelConfiguration ptyConfig = ...some configuration...
+ try (ClientChannel channel = session.createShellChannel(ptyConfig, env)) {
+ ... same code as before ...
+ }
+
+ // the same code can be used when opening a ChannelExec in order to run a single command
+
+```
+
+One possible source of PTY configuration is code that provides some default initializations based on the detected O/S
+type - `PtyChannelConfigurationMutator#setupSensitiveDefaultPtyConfiguration`. Of course, the user may use whatever other
+considerations when opening such a channel.
+
+**Caveat Emptor:** If the detected O/S type is Unix/Linux, then the `setupSensitiveDefaultPtyConfiguration` code issues an `stty` command
+and parses the results (see `SttySupport` class). Since this involves using `System#exec` it is a source of concern as it may hang, throw
+an exception, provide corrupted data, etc...