Guile-SSH is a library that provides access to the SSH protocol for programs written in GNU Guile interpreter. It is built upon the libssh library.

Features

• The API that is sufficient for building of standalone SSH clients and servers, or for embedding client/server functionality in your lispy Scheme applications.
• Several authentication methods are supported, including password authentication, public key and SSH agent authentication methods.
• Key management procedures: you can make key pairs, read keys from files, get key hashes, get public keys from private keys etc. DSS (only when --enable-dsa option is passed to the configure script), RSA, RSA1 and ECDSA (by means of OpenSSL) are supported.
• Port forwarding procedures and high-level API for creating of SSH tunnels.
• Distributed forms (dist-map, distribute, …) that allow to spread the evaluation of Scheme code between remote hosts. Or you can just connect to a remote REPL from Scheme using with-ssh procedure and evaluate some expressions. No special server needed on the remote side, just an SSH daemon and GNU Guile installed!
• SFTP client API allows you to read and write remote files, or do directory traversal over the SSH protocol right from the Scheme code.
• Remote popen API that allows you to make either input, output or bidirectional pipes to remote processes.
• Detailed documentation in Texinfo format with examples included, even more examples in examples directory.

License

Guile-SSH is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version. Please see COPYING file for the terms of GNU General Public License.

The logo (doc/logo.svg, doc/logo-with-text.svg and rasterised versions) is distributed under terms of Creative Commons Attribution-ShareAlike 4.0 International.

Requirements

• GNU Guile, version 2.0.12 or later (known to work with 2.0.12, 2.0.14, 2.2.4, 3.0.1)
• libssh, version 0.7.3 or later (older versions have CVE-2016-0739 – don’t use them, really.)

Distribution

Files:

• AUTHORS contains list of people who contributed to the library development.
• COPYING contains the terms of GNU General Public License.
• INSTALL contains general instructions for building/installing of Guile-SSH.
• NEWS describes user-visible changes.
• TODO contains plans for the further development and list of known bugs.

Directories:

• examples – Examples of Guile-SSH usage.
• libguile-ssh – Sources of the Guile-SSH library.
• modules – Scheme modules.
• doc – Documentation in Texinfo format.
• tests – Unit tests.

Files are usually installed according to the prefix specified to configure script, /usr/local by default. Building and installing gives you:

Libraries, in ${prefix}/lib:

• libguile-ssh.so.<version>
• libguile-ssh.la
• libguile-ssh.a

Guile modules, in ${GUILE_SITE}/ssh:

• auth.scm – User authentication.
• agent.scm – Interaction with SSH authentication agent instances.
• channel.scm – Channel manipulation.
• dist.scm – Distributed forms.
  • dist/job.scm – Low-level distributed job API.
  • dist/node.scm – Low-level distributed node API.
• key.scm – Keys management.
• log.scm – Interface to libssh logging facilities
• message.scm – Procedures for working with SSH messages.
• popen.scm – Remote popen API.
• server.scm – Server API.
• session.scm – Session management.
• sftp.scm – SFTP client API.
• shell.scm – High-level API to a remote shell.
• tunnel.scm – SSH tunnels.
• version.scm – Information about versions.

All the modules will be compiled and produced .go files will be installed to site-ccache directory which is something like this: ${libdir}/guile/2.0/site-ccache/ssh/.

Documentation in Info format, in ${prefix}/share/info/:

• guile-ssh.info

Examples, in ${prefix}/share/guile-ssh/examples:

• ssshd.scm – SSH server example.
• sssh.scm – SSH client example.
• echo/
  • client.scm – Echo client example.
  • server.scm – Echo server example.
• rpc/
  • client.scm – A simple Guile-RPC client that makes an RPC call over a Guile-SSH tunnel.
  • server.scm – A simple Guile-RPC server.
• rrepl.scm – Remote REPL example.
• sscp.scm – Scheme secure copy.
• pg-tunnel.scm – Connect to a PostgreSQL instance through an SSH tunnel.
• uptop.scm – Uppercase top, through a remote pipe.

Installation

The library can be installed by the following means:

• Using GNU Guix: https://www.gnu.org/software/guix/
• Using Arch GNU/Linux AUR package: https://aur.archlinux.org/packages/guile-ssh/
• Using Parabola GNU/Linux package: https://www.parabola.nu/packages/?q=guile-ssh
• Using openSUSE GNU/Linux package: https://software.opensuse.org/package/guile-ssh
• Using a Homebrew Tap on macOS (thanks to Aleix Conchillo Flaqué): https://github.com/aconchillo/homebrew-guile
• Manually. If you’re considering manual installation, see the notes below.

Thanks for all the people who helped with packaging of Guile-SSH!

Also there is a Docker image based on Debian GNU/Linux that contains the latest version of GNU Guile and Guile-SSH installed – give it a try!

For a basic explanation of the installation of the package, see the INSTALL file.

But to make the long story short, you can try run the following in the project directory – those commands will configure, build, check and install Guile-SSH in your system:

$ autoreconf -vif
$ ./configure
$ make
$ make check
$ make install

Please note that you will need Automake 1.12 or later to run self-tests with make check (although the library itself can be built with older Automake version such as 1.11, just leave out the make check step).

important You probably want to call configure with the --with-guilesitedir option so that this package is installed in Guile’s default path. But, if you don’t know where your Guile site directory is, run configure without the option, and it will give you a suggestion.

Usage

Please see the documentation in Info format for API documentation and usage examples – you can open it by typing info guile-ssh in the shell, or using C-h i m guile-ssh RET combo in Emacs. Also take a look on examples in the examples directory.