From 3eced27f96d87eac1fc90325d7030167805309a1 Mon Sep 17 00:00:00 2001 From: Hans Nilsson Date: Thu, 8 Mar 2018 16:34:21 +0100 Subject: ssh: Document the exec option --- lib/ssh/doc/src/ssh.xml | 93 +++++++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 86 insertions(+), 7 deletions(-) (limited to 'lib') diff --git a/lib/ssh/doc/src/ssh.xml b/lib/ssh/doc/src/ssh.xml index acf94ff6af..d36be8431c 100644 --- a/lib/ssh/doc/src/ssh.xml +++ b/lib/ssh/doc/src/ssh.xml @@ -67,24 +67,41 @@ boolean() =

true | false

 + string() =

[byte()]

 + ssh_daemon_ref() =

opaque() - as returned by ssh:daemon/[1,2,3]

 + + ok_error(OKtype) = +

{ok,OKtype} | {error, term()}

 + + ok_error() = +

ok_error(term())

 + ssh_connection_ref() =

opaque() - as returned by ssh:connect/3

 + ip_address() = -

inet::ip_address

 +

inet::ip_address()

 + + port_number() = +

inet::port_number()

 + subsystem_spec() =

{subsystem_name(), {channel_callback(), channel_init_args()}}

 + subsystem_name() =

string()

 + channel_callback() =

atom() - Name of the Erlang module implementing the subsystem using the ssh_channel behavior, see ssh_channel(3)

 + key_cb() =

atom() | {atom(), list()}

@@ -94,6 +111,7 @@ case maybe.

list() - List of options that can be passed to the callback module.

 + channel_init_args() =

list()

 @@ -478,8 +496,8 @@ Option = client_version | server_version | user | peer | sockname Value = [option_value()] option_value() = {{Major::integer(), Minor::integer()}, VersionString::string()} | - User::string() | Peer::{inet:hostname(), {inet::ip_adress(), inet::port_number()}} | - Sockname::{inet::ip_adress(), inet::port_number()} + User::string() | Peer::{inet:hostname(), {ip_address(), port_number()}} | + Sockname::{ip_address(), port_number()}

Retrieves information about a connection.

@@ -541,22 +559,83 @@ The option can be set to the empty list if you do not want the daemon to run any subsystems.

- + pid() | fun(string() = User, ip_address() = PeerAddr) -> pid()}]]>

Defines the read-eval-print loop used when a shell is requested by the client. The default is to use the Erlang shell:

+

See the option exec + for a description of how the daemon execute exec-requests depending on + the shell- and exec-options.

+ + + + +
where: +
exec_spec() = +
fun(Cmd::string()) -> ok_error() +
| fun(Cmd::string(), User::string()) -> ok_error() +
| fun(Cmd::string(), User::string(), ClientAddr::{ip_address(), port_number()}) -> ok_error() + + +

This option changes how the daemon execute exec-requests from clients. The term in ok_error() + is formatted to a string if it is a non-string type. No trailing newline is added in the ok-case but in the + error case.

+

Error texts are returned on channel-type 1 which usually are piped to stderr on e.g Linux systems. + Texts from a successful execution will in similar manner be piped to stdout. The exit-status code + is set to 0 for success and -1 for errors. The exact results presented on the client side depends on the + client. +

+

The option cooperates with the daemon-option shell + in the following way:

+ + 1. If the exec-option is present (the shell-option may or may not be present): + +

The exec-option fun is called with the same number of parameters as the arity of the fun, + and the result is returned to the client. +

+ + + 2. If the exec-option is absent, but a shell-option is present with the default Erlang shell: + +

The default Erlang evaluator is used and the result is returned to the client.

+ + + 3. If the exec-option is absent, but a shell-option is present that is not the default Erlang shell: + +

The exec-request is not evaluated and an error message is returned to the client.

+ + + 4. If neither the exec-option nor the shell-option is present: + +

The default Erlang evaluator is used and the result is returned to the client.

+ + +

If a custom CLI is installed (see the option ssh_cli) + the rules above are replaced by thoose implied by the custom CLI. +

+ +

The exec-option has existed for a long time but has not previously been documented. The old + definition and behaviour are retained but obey the rules 1-4 above if conflicting. + The old and undocumented style should not be used in new programs.

+ - +

Provides your own CLI implementation, that is, a channel callback module that implements a shell and command execution. The shell read-eval-print loop can be customized, using the - option shell. This means less work than implementing - an own CLI channel. If set to no_cli, the CLI channels + option shell. This means less work than implementing + an own CLI channel. If ssh_cli is set to no_cli, the CLI channels + like shell + and exec are disabled and only subsystem channels are allowed.

 -- cgit v1.2.3