# -*- mode: org; -*-

[[./doc/logo-v2.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.


[[https://github.com/artyom-poptsov/guile-ssh/actions/workflows/guile2.2.yml][https://github.com/artyom-poptsov/guile-ssh/actions/workflows/guile2.2.yml/badge.svg]]
[[https://github.com/artyom-poptsov/guile-ssh/actions/workflows/guile3.0.yml][https://github.com/artyom-poptsov/guile-ssh/actions/workflows/guile3.0.yml/badge.svg]]
[[https://github.com/artyom-poptsov/guile-ssh/actions/workflows/fedora.yml][https://github.com/artyom-poptsov/guile-ssh/actions/workflows/fedora.yml/badge.svg]]
[[https://github.com/artyom-poptsov/guile-ssh/actions/workflows/guix.yml][https://github.com/artyom-poptsov/guile-ssh/actions/workflows/guix.yml/badge.svg]]

* 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 [[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.12 or later (known to work with 2.0.12, 2.0.14,
   2.2.4, 3.0.1 up to 3.0.11)
 - [[http://www.libssh.org/][libssh]], version 0.8.3 or later.
* Contributing

You can use Guix to build Guile-SSH non-interactively, like so:

#+begin_src sh
guix build -f guix.scm
#+end_src

You can build a variant against a specific libssh version, as in this example:

#+begin_src sh
guix build -L .guix/modules guile-ssh-with-libssh-0.8
#+end_src

Last, you can build the entire configuration matrix (several architectures, several libssh versions, several Guile versions) like so:

#+begin_src sh
guix build -L .guix/modules -m .guix/manifest.scm
#+end_src

* Installation
[[https://repology.org/badge/vertical-allrepos/guile-ssh.svg]]

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 [[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.

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:
#+BEGIN_EXAMPLE
$ autoreconf -vif
$ ./configure
$ make
$ make check
$ make install
#+END_EXAMPLE

Please *note* that you will need [[https://www.gnu.org/software/automake/][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:
 - 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.
