# -*- mode: org; -*- [[./doc/logo-with-text.png]] Guile-SSH is a library that provides access to the [[https://en.wikipedia.org/wiki/Secure_Shell][SSH protocol]] for programs written in [[https://www.gnu.org/software/guile/][GNU Guile]] interpreter. It is built upon the [[https://www.libssh.org/][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 [[https://creativecommons.org/licenses/by-sa/4.0/][Creative Commons Attribution-ShareAlike 4.0 International]]. * Requirements - [[https://www.gnu.org/software/guile/][GNU Guile]], version 2.0.9 or later (known to work with 2.0.9, 2.0.12, 2.0.14, 2.2.2.3-0c102) - [[http://www.libssh.org/][libssh]], version 0.6.4 or later (0.7.3 or later is recommended due to [[https://www.libssh.org/2016/02/23/libssh-0-7-3-security-and-bugfix-release/][CVE-2016-0739 found in previous versions]].) * 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. - 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: - 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 - 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 [[https://hub.docker.com/r/avvp/debian-guile/][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. Please *note* that you will need [[https://www.gnu.org/software/automake/][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.