\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-2022 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

@section GNU Guix
The latest stable Guile-SSH is available from @url{https://guix.gnu.org/, GNU
Guix} repository:

@example
$ guix install guile-ssh
@end example

If you want to get the environment for Guile-SSH development there's
@file{guix.scm} file in the root of the repository that can be used with
@command{guix shell}:

@example
$ guix shell -D -f ./guix.scm
@end example

@section Ubuntu GNU/Linux
@example
$ sudo apt install guile-ssh
@end example

@section Other Platforms
Guile-SSH is also available from the default repositories at least on the
following platforms:
@itemize
@item @url{https://aur.archlinux.org/packages/guile-ssh/, Arch GNU/Linux}
@item @url{https://www.parabola.nu/packages/?q=guile-ssh, Parabola GNU/Linux}
@item @url{https://software.opensuse.org/package/guile-ssh, openSUSE GNU/Linux}
@item @url{https://github.com/aconchillo/homebrew-guile, macOS}
@end itemize

Please refer to the official document for each platform for the instructions
on how to install the package.

@section Manual 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 the manual 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
* Agent::        Interaction with SSH agent instances.
* 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-sessions.texi
@include api-auth.texi
@include api-agent.texi
@include api-keys.texi
@include api-channels.texi
@include api-tunnels.texi
@include api-popen.texi
@include api-shell.texi
@include api-logging.texi
@include api-version.texi
@include api-servers.texi
@include api-messages.texi
@include api-sftp.texi
@include api-dist.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 @file{AUTHORS} file that comes along with libssh distribution
for full authors list.

Also I'd like to thank all the people who contributed their precious time and
skills to send bug reports and patches for Guile-SSH.  Please see @file{THANKS}
file in the Guile-SSH repository for the full list of contributors.

Thank you.

- Artyom ``avp'' Poptsov

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

@include fdl.texi

@include indices.texi

@bye