| 1 |
# -*- mode: org; -*- |
| 2 |
|
| 3 |
[[./doc/logo-v2.png]] |
| 4 |
|
| 5 |
Guile-SSH is a library that provides access to the [[https://en.wikipedia.org/wiki/Secure_Shell][SSH protocol]] for programs |
| 6 |
written in [[https://www.gnu.org/software/guile/][GNU Guile]] interpreter. It is built upon the [[https://www.libssh.org/][libssh]] library. |
| 7 |
|
| 8 |
|
| 9 |
[[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]] |
| 10 |
[[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]] |
| 11 |
[[https://github.com/artyom-poptsov/guile-ssh/actions/workflows/fedora.yml][https://github.com/artyom-poptsov/guile-ssh/actions/workflows/fedora.yml/badge.svg]] |
| 12 |
[[https://github.com/artyom-poptsov/guile-ssh/actions/workflows/guix.yml][https://github.com/artyom-poptsov/guile-ssh/actions/workflows/guix.yml/badge.svg]] |
| 13 |
|
| 14 |
* Features |
| 15 |
- The API that is sufficient for building of standalone SSH clients and |
| 16 |
servers, or for embedding client/server functionality in your lispy Scheme |
| 17 |
applications. |
| 18 |
- Several authentication methods are supported, including password |
| 19 |
authentication, public key and SSH agent authentication methods. |
| 20 |
- Key management procedures: you can make key pairs, read keys from files, |
| 21 |
get key hashes, get public keys from private keys etc. DSS (only when |
| 22 |
=--enable-dsa= option is passed to the =configure= script), RSA, RSA1 and |
| 23 |
ECDSA (by means of OpenSSL) are supported. |
| 24 |
- Port forwarding procedures and high-level API for creating of SSH tunnels. |
| 25 |
- Distributed forms (=dist-map=, =distribute=, ...) that allow to spread the |
| 26 |
evaluation of Scheme code between remote hosts. Or you can just connect |
| 27 |
to a remote REPL from Scheme using =with-ssh= procedure and evaluate some |
| 28 |
expressions. No special server needed on the remote side, just an SSH |
| 29 |
daemon and GNU Guile installed! |
| 30 |
- SFTP client API allows you to read and write remote files, or do directory |
| 31 |
traversal over the SSH protocol right from the Scheme code. |
| 32 |
- Remote popen API that allows you to make either input, output or |
| 33 |
bidirectional pipes to remote processes. |
| 34 |
- Detailed documentation in Texinfo format with examples included, even more |
| 35 |
examples in =examples= directory. |
| 36 |
* License |
| 37 |
Guile-SSH is free software: you can redistribute it and/or modify it under |
| 38 |
the terms of the GNU General Public License as published by the Free |
| 39 |
Software Foundation, either version 3 of the License, or (at your option) |
| 40 |
any later version. Please see =COPYING= file for the terms of GNU General |
| 41 |
Public License. |
| 42 |
|
| 43 |
The logo (=doc/logo.svg=, =doc/logo-with-text.svg= and rasterised versions) |
| 44 |
is distributed under terms of [[https://creativecommons.org/licenses/by-sa/4.0/][Creative Commons Attribution-ShareAlike 4.0 |
| 45 |
International]]. |
| 46 |
* Requirements |
| 47 |
|
| 48 |
- [[https://www.gnu.org/software/guile/][GNU Guile]], version 2.0.12 or later (known to work with 2.0.12, 2.0.14, |
| 49 |
2.2.4, 3.0.1 up to 3.0.11) |
| 50 |
- [[http://www.libssh.org/][libssh]], version 0.8.3 or later. |
| 51 |
* Contributing |
| 52 |
|
| 53 |
You can use Guix to build Guile-SSH non-interactively, like so: |
| 54 |
|
| 55 |
#+begin_src sh |
| 56 |
guix build -f guix.scm |
| 57 |
#+end_src |
| 58 |
|
| 59 |
You can build a variant against a specific libssh version, as in this example: |
| 60 |
|
| 61 |
#+begin_src sh |
| 62 |
guix build -L .guix/modules guile-ssh-with-libssh-0.8 |
| 63 |
#+end_src |
| 64 |
|
| 65 |
Last, you can build the entire configuration matrix (several architectures, several libssh versions, several Guile versions) like so: |
| 66 |
|
| 67 |
#+begin_src sh |
| 68 |
guix build -L .guix/modules -m .guix/manifest.scm |
| 69 |
#+end_src |
| 70 |
|
| 71 |
* Installation |
| 72 |
[[https://repology.org/badge/vertical-allrepos/guile-ssh.svg]] |
| 73 |
|
| 74 |
The library can be installed by the following means: |
| 75 |
- Using GNU Guix: https://www.gnu.org/software/guix/ |
| 76 |
- Using Arch GNU/Linux AUR package: |
| 77 |
https://aur.archlinux.org/packages/guile-ssh/ |
| 78 |
- Using Parabola GNU/Linux package: |
| 79 |
https://www.parabola.nu/packages/?q=guile-ssh |
| 80 |
- Using openSUSE GNU/Linux package: |
| 81 |
https://software.opensuse.org/package/guile-ssh |
| 82 |
- Using a Homebrew Tap on macOS (thanks to Aleix Conchillo Flaqué): |
| 83 |
https://github.com/aconchillo/homebrew-guile |
| 84 |
- Manually. If you're considering manual installation, see the notes below. |
| 85 |
|
| 86 |
Thanks for all the people who helped with packaging of Guile-SSH! |
| 87 |
|
| 88 |
Also there is a [[https://hub.docker.com/r/avvp/debian-guile/][Docker image]] based on Debian GNU/Linux that contains the |
| 89 |
latest version of GNU Guile and Guile-SSH installed -- give it a try! |
| 90 |
|
| 91 |
For a basic explanation of the installation of the package, see the |
| 92 |
INSTALL file. |
| 93 |
|
| 94 |
But to make the long story short, you can try run the following in the project |
| 95 |
directory -- those commands will configure, build, check and install Guile-SSH |
| 96 |
in your system: |
| 97 |
#+BEGIN_EXAMPLE |
| 98 |
$ autoreconf -vif |
| 99 |
$ ./configure |
| 100 |
$ make |
| 101 |
$ make check |
| 102 |
$ make install |
| 103 |
#+END_EXAMPLE |
| 104 |
|
| 105 |
Please *note* that you will need [[https://www.gnu.org/software/automake/][Automake]] 1.12 or later to run self-tests with |
| 106 |
=make check= (although the library itself can be built with older Automake |
| 107 |
version such as 1.11, just leave out the =make check= step). |
| 108 |
|
| 109 |
*important* You probably want to call configure with the |
| 110 |
=--with-guilesitedir= option so that this package is installed in |
| 111 |
Guile's default path. But, if you don't know where your Guile site |
| 112 |
directory is, run =configure= without the option, and it will give you |
| 113 |
a suggestion. |
| 114 |
|
| 115 |
* Usage |
| 116 |
Please see the documentation in Info format for API documentation and usage |
| 117 |
examples -- you can open it by typing =info guile-ssh= in the shell, or using |
| 118 |
=C-h i m guile-ssh RET= combo in Emacs. Also take a look on examples in the |
| 119 |
=examples= directory: |
| 120 |
- ssshd.scm -- SSH server example. |
| 121 |
- sssh.scm -- SSH client example. |
| 122 |
+ echo/ |
| 123 |
- client.scm -- Echo client example. |
| 124 |
- server.scm -- Echo server example. |
| 125 |
+ rpc/ |
| 126 |
- client.scm -- A simple Guile-RPC client that makes an RPC call over |
| 127 |
a Guile-SSH tunnel. |
| 128 |
- server.scm -- A simple Guile-RPC server. |
| 129 |
- rrepl.scm -- Remote REPL example. |
| 130 |
- sscp.scm -- Scheme secure copy. |
| 131 |
- pg-tunnel.scm -- Connect to a PostgreSQL instance through an SSH tunnel. |
| 132 |
- uptop.scm -- Uppercase =top=, through a remote pipe. |