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
|
#+TITLE: Guile-SSH Architecture
#+STARTUP: content hidestars
Copyright (C) Artyom V. Poptsov <poptsov.artyom@gmail.com>
Copying and distribution of this file, with or without modification,
are permitted in any medium without royalty provided the copyright
notice and this notice are preserved.
* Architecture
The main goal of this project is to provide a [[https://www.gnu.org/software/guile/][GNU Guile]] (Scheme) interface to
[[https://www.libssh.org/][libssh]] library which in turn implements [[https://en.wikipedia.org/wiki/Secure_Shell][SSH protocol]] (RFC 4250 and others.)
There are two main reasons that Guile-SSH uses libssh:
1. It was originally started as a wrapper to the libssh.
2. It's not easy to do the implementation of SSH protocol right; as it is the
foundation for secure communication there's a great burden of maintaining
the security of the code. =libssh= has comprehensive testing, it is passed
at least one [[https://www.libssh.org/2019/12/10/libssh-0-9-3-and-libssh-0-8-8-security-release/][security audit]] and it has many users.
In addition to the basic SSH client/server API (provided by libssh itself)
Guile-SSH provides high-level procedures for operations over SSH channels.
The project is split into two parts: a C library (=libguile-ssh=) and a Scheme
=ssh= library.
** Versioning
Guile-SSH uses [[https://semver.org/][semantic versioning]].
Starting from the version 1.0.0, the format is =MAJOR.MINOR.PATCH=, where the
rules for incrementing each part are:
- =MAJOR= version is incremented when incompatible API changes are introduced.
- =MINOR= version is incremented when some functionality is added in a
backward compatible manner.
- =PATCH= version is incremented when backward compatible bug fixes are
introduced.
** Code Map
*** Overview
C library code is in =libguile-ssh= directory. All the GNU Guile modules are
in =modules= directory.
Files are usually installed according to the prefix specified to =configure=
script (=/usr/local= by default.)
Auxiliary files include:
- =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.
*** C API
C API is not public at the moment as it is not important for the task
Guile-SSH tries accomplish.
Nevertheless public and stable C API might be advantageous in some situations
like writing other low-level Scheme libraries or low-level Guile-SSH testing.
Each SMOB (Small Object) -- a GNU Guile object described in C -- is split into
three files:
- =*-type.c= contains the implementation of a SMOB and some very basic
procedures for it.
- =*-func.c= contains the most of the procedures for working with that SMOB.
- =*-main.c= contains the =init= procedure that initializes the SMOB.
There are some common procedures that are written in separate files not
related to any SMOB (like =log= procedures.)
All C code compiles into a =libguile-ssh.so= shared library that is being
copied into the target system during the installation process.
*** Scheme API
Scheme API is public and should be kept stable when it's possible. When this
API changes a note must be issued in the =NEWS= file.
All Scheme module source files are in =modules/ssh= directory.
Scheme modules are being installed into =${GUILE_SITE}/ssh= directory on the
target system. All the modules will be compiled and produced =.go= files will
be installed to =site-ccache= directory which is something like this:
=${libdir}/guile/3.0/site-ccache/ssh/=.
Guile-SSH includes the following Guile modules:
- =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.
*** Examples
Examples are important as they provide a hint how the library can be used for
real tasks.
Guile-SSH examples are stored in =examples= directory in the root of the
repository.
Examples are being copied into =${prefix}/share/guile-ssh/examples= directory
during the installation process.
*** Tests
Tests are in =tests= directory. They are written using SRFI-61.
When a new functionality is being added a new test case (or several test
cases) should be written for it.
Tests are using SSH client and a server written in Guile-SSH from =examples=.
*** Documentation
Documentation is written in Texinfo format and can be found in =doc=
directory. It compiles into =guile-ssh.info= Info file and is being copied
into =${prefix}/share/info/= during the installation process.
|
