Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/artyom-poptsov/guile-ssh

Guile-SSH is a library that provides access to the SSH protocol for GNU Guile programs.
https://github.com/artyom-poptsov/guile-ssh

c distributed-computing guile libssh lisp scheme ssh

Last synced: 11 days ago
JSON representation

Guile-SSH is a library that provides access to the SSH protocol for GNU Guile programs.

Awesome Lists containing this project

README 

        
# -*- 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)

 - [[http://www.libssh.org/][libssh]], version 0.7.3 or later (older versions have [[https://www.libssh.org/2016/02/23/libssh-0-7-3-security-and-bugfix-release/][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.

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