guile-ssh/doc/guile-ssh.texi

\input texinfo
@c -*-texinfo-*-
@c %**start of header
@setfilename guile-ssh.info
@documentencoding UTF-8
@settitle Guile-SSH Reference Manual
@c %**end of header
@include version.texi

@copying
This manual documents Guile-SSH version @value{VERSION}.

Copyright (C) 2014, 2015, 2016, 2017 Artyom V. Poptsov

Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
any later version published by the Free Software Foundation; with no
Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.  A
copy of the license is included in the section entitled ``GNU Free
Documentation License.''
@end copying

@dircategory The Algorithmic Language Scheme
@direntry
* Guile-SSH: (guile-ssh).      Guile bindings to libssh.
@end direntry

@setchapternewpage odd

@titlepage
@sp 10

@title Guile-SSH Reference Manual
@subtitle For Guile-SSH @value{VERSION}

@author Artyom V. Poptsov

@page
@vskip 0pt plus 1filll
@vskip 0pt plus 1filll
@insertcopying
@end titlepage

@finalout
@headings double

@ifnottex
@node Top, Introduction, (dir), (dir)
@top The Guile-SSH Reference Manual

@insertcopying
@sp 1
@end ifnottex

@menu
* Introduction::
* Installation::
* API Reference::
* Examples::

* Acknowledgments::

Appendices

* GNU Free Documentation License::  The license of this manual.

Indices

* Type Index::
* Procedure Index::
* Concept Index::

@end menu

@contents

@node Introduction
@chapter Introduction

Guile-SSH is a library that provides access to the @acronym{SSH}
protocol for programs written in
@url{https://www.gnu.org/software/guile/, GNU Guile}.  It is a wrapper
to the underlying @url{http://www.libssh.org/, libssh} library.  This
manual is partly based on libssh documentation.

@section The goals of this (humble) project
@quotation
Most projects are humble, it's the combination that's interesting :-)
@author Ludovic Courtès
@end quotation

Now let me explain what are the goals of the whole project.  Aside from the
fact that I am having lots of fun with the project itself (and the project is
helping me to grow as a free software developer, many thanks to all advices
and comments from the community!), there are practical goals that the project
struggling to achieve.

For me, the main goal is to provide convenient means to write truly
distributed applications in my favourite programming language.

Computers are getting cheaper and more and more ubiquitous, and so different
kind of networks.  In my opinion the question is -- how we are going to
utilize those new computational resources?  Using multi-core systems
effectively may be tricky; fortunately some languages (such as Scheme/GNU
Guile) already provide convenient API to utilize those systems.  But what
about systems that distributed over a network?

I am dreaming of the times when using computer resources distributed over a
network in GNU Guile will be as easy as using local ones.  You should not be
asking question ``how to do it?'' -- what you should be asking yourself is
``how can I use it?''

But Guile-SSH itself is just a library; a tool that can be used to solve some
problems (and, perhaps, to cause new ones ;-)).  So, as was noted in the
quotation above, it's the combination of projects that may lead to the most
interesting results.  With that said, I would love to see Guile-SSH used in
another projects, and to hear positive (and negative) feedback from you.

Happy hacking!

- avp

@node Installation
@chapter Installation

Guile-SSH sources are available from GitHub at
@url{https://github.com/artyom-poptsov/guile-ssh/}.  This section
describes requirements of Guile-SSH and installation process.

Guile-SSH depends on the following packages:

@itemize
@item @url{https://www.gnu.org/software/guile/, GNU Guile}, version 2.0.9 or later
@item @url{http://www.libssh.org/, libssh}, version 0.6.4 or later
@end itemize

Get the sources of Guile-SSH from GitHub:

@example
$ git clone git@@github.com:artyom-poptsov/guile-ssh.git
@end example

Configure the sources:

@example
$ cd guile-ssh/
$ autoreconf -if
$ ./configure
@end example

Build and install the library:

@example
$ make
$ make install
@end example

For a basic explanation of the installation of the package, see the
@file{INSTALL} file.

Please @strong{note} that you will need
@url{https://www.gnu.org/software/automake/, Automake} version 1.12 or
later to run self-tests with @command{make check} (but the library
itself can be built with older Automake version such as 1.11).

@strong{important} You probably want to call @command{configure} with
the @option{--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 @command{configure} without the option,
and it will give you a suggestion.

@node API Reference
@chapter API Reference

@menu
* Sessions::     Session management
* Auth::         Authentication procedures
* Keys::         Public and private keys
* Channels::     Channel manipulation procedures
* Tunnels::      SSH tunnels
* Remote Pipes:: Creating of input, output or bidirectional pipes to remote
                 processes
* Shell::        A high-level interface to remote shell built upon remote
                 pipes
* Logging::      Interface to the libssh logging
* Version::      Get information about versions

Guile-SSH Server API
* Servers::      Creating and managing Guile-SSH servers
* Messages::     Handling of messages

SFTP
* SFTP::         Guile-SSH SFTP client API.

Distributed Computing
* Distributed Forms::

@end menu

@include api-auth.texi
@include api-channels.texi
@include api-tunnels.texi
@include api-sessions.texi
@include api-keys.texi
@include api-messages.texi
@include api-servers.texi
@include api-logging.texi
@include api-version.texi
@include api-dist.texi
@include api-sftp.texi
@include api-popen.texi
@include api-shell.texi

@include examples.texi

@node Acknowledgments
@chapter Acknowledgments

The @url{http://www.libssh.org/, libssh} that is used by Guile-SSH is
initially written by Aris Adamantiadis and being developed by the
developer community.  See AUTHORS file that comes along with libssh
distribution for full authors list.

Thanks to the following people who contributed to Guile-SSH
through bug reports or patches:

@itemize @bullet
@item Ludovic Courtès @email{ludo@@gnu.org}
@item David Thompson @email{davet@@gnu.org}
@item SaffronSnail @url{https://github.com/SaffronSnail}
@item David Kastrup @email{dak@@gnu.org>}
@end itemize


Thank you.

@node GNU Free Documentation License
@appendix GNU Free Documentation License

@include fdl.texi

@include indices.texi

@bye