guile-ssh/ARCHITECTURE.org at master · artyom-poptsov/guile-ssh · GitHub
Skip to content

ARCHITECTURE.org

Latest commit

 

History

History
129 lines (98 loc) · 5.17 KB

ARCHITECTURE.org

File metadata and controls

129 lines (98 loc) · 5.17 KB
Raw

Guile-SSH Architecture

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 GNU Guile (Scheme) interface to libssh library which in turn implements 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 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 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.