Pack libssh -- prolog/ssh

This module defines an embedded SSH server for SWI-Prolog on top of libssh. This module allows for a safe secondary access point to a running Prolog process. A typical use case is to provide a safe channal or inspection and maintenance of servers or embedded Prolog instances.

If possible, a login to the Prolog process uses a pseudo terminal to realise normal terminal interaction, including processing of ^C to interrupt running queries. If libedit (editline) is used as the command line editor this is installed (see el_wrap/0), providing advanced command line editing and history.

The library currently support login to the Prolog process. Future versions may also use the client access and exploit the SSH subsystem interface to achieve safe interaction between Prolog peers.

The client session

A new connection creates a Prolog thread that handles the connection. The new thread's standard streams (user_input, user_output, user_error, current_input and current_output) are attached to the new connection. Some of the environment is shared as Prolog flags. The following flags are defined:

ssh_tty: Provides the name of the pseudo terminal if such a terminal us allocated for this connection.
ssh_term: Provides the TERM environment variable passed from the client.
ssh_user: Provides the name of the user logged on.

If a pseudo terminal is used and the ssh_term flag is not dump, library(ansi_term) is connected to provide colorized output.

If a pseudo terminal is used and library(editline) is available, this library is used to enable command line editing.

Executing commands

Using ssh <options> <server> <command>, <command> is executed without a terminal (unless the -t option is given to ssh to force a terminal) and otherwise as a single Prolog toplevel command. For example:

ssh -p 2020 localhost "writeln('Hello world')"
Hello world
true.

If the query is nondeterministic alternative answers can be requested in the same way as using the interactive toplevel. The exit code is defined as follows:

0: The query succeeded
1: The query failed
2: The query produced an exception (the system prints a backtrace)
3: The query itself was not syntactically correct.

Aborting the server

If a Prolor process with an embedded ssh server misbehaves it can be forcefully aborted using the abort command. This calls C abort() as soon as possible and thus should function even if Prolog is, for example, stuck in a deadlock.

ssh -p 2020 localhost abort

To be done: - Currently only supports Unix. A Windows port is probably doable. It mostly requires finding a sensible replacement for the Unix pseudo terminal.; - Implement running other commands than the Prolog toplevel.

ssh_server is det

ssh_server(+PortOrOptions) is det

Create an embedded SSH server in the current Prolog process. If the argument is an integer it is interpreted as ssh_server([port(Integer)]). Options:

name(+Atom)

Name the server. Passed as first argument to verify_password/3 to identify multiple servers.

port(+Integer)

Port to listen on. Default is 2020.

bind_address(+Name)

Interface to listen to. Default is localhost. Use * to grant acccess from all network interfaces.

host_key_file(+File)

File name for the host private key. If omitted it searches for etc/ssh below the current directory and user_app_config('etc/ssh') (normally ~/.config/swi-prolog/etc/ssh). On failure it creates, a directory etc/ssh with default host keys and uses these.

auth_methods(+ListOfMethod)

Set allowed authentication methods. ListOfMethod is a list of

password: Allow password login (see verify_password/3)
public_key: Allow key based login (see authorized_keys_file below) The default is derived from the authorized_keys_file option and whether or not verify_password/3 is defined.

authorized_keys_file(+File)

File name for a file holding the public keys for users that are allows to login. Activates auth_methods([public_key]). This file is in OpenSSH format and contains a certificate per line in the format

<type> <base64-key> <comment>

The the file `~/.ssh/authorized_keys` is present, this will be used as default, granting anyone with access to this account to access the server with the same keys. If the option is present with value [] (empty list), no key file is used.

run_client(+Server, +In, +Out, +Err, +Command, -RetCode) is det

Run Command using I/O from the triple <In, Out, Err> and bind RetCode to the ssh shell return code.

verify_password(+ServerName, +User:atom, +Passwd:string) is semidet[multifile]

Hook that can be used to accept password based logins. This predicate must succeeds to accept the User/Passwd combination.

Arguments:

ServerName - is the name provided with the name(Name) option when creating the server or the empty list.

capture_messages(+Level) is det

Redirect all messages of the indicated level to the console of the current thread. This is part of the SSH library as it is notably practical when connected through SSH. Consider using trace/1 on some predicate. We catch capture the output using:

?- capture_messages(debug).
?- trace(p/1).

Re-exported predicates

The following predicates are exported from this file while their implementation is defined in imported modules or non-module files loaded by this module.