1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
|
# -*- 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.8.0 or later.
* 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.<version>
- 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.
|
