Debian Codegraph @

README

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