Guile-SSH is a library that provides access to the SSH protocol for GNU Guile programs.
Scheme C M4 Shell Makefile Emacs Lisp
Permalink
Failed to load latest commit information.
am
build-aux
doc
examples
libguile-ssh
m4
modules
tests
.dir-locals.el
.gitignore
AUTHORS
COPYING
ChangeLog
INSTALL
Makefile.am
NEWS
README
README.org
THANKS
TODO
configure.ac

README.org

./doc/logo-with-text.png

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, 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 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

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.
  • 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:

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

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

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

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.