ggate/libssh2/vms

*These are the porting notes to OpenVMS, as of 7 April 2010
by Jose Baars. This file will be installed as 
libssh2*.release_notes by the product install kit.


LIBSSH2 
-------

LIBSSH2 is a client-side library written in C that aims to 
implement the SSH2 protocol. It is an open source project, 
to be found at https://libssh2.org.

GNV
---

The library uses the GNV prefix, on advise of the kind supporter
of the GNV project, John Malmberg.

Installing the PCSI kit
=======================

Prerequisites 
-------------
- VMS version 8.3 minimal. 
  See the remarks at prerequisites for building the kit
- TCP/IP stack, both TCP/IP services and Multinet should work. 
  See the remarks at prerequisites for building the kit
- HP OPENSSL V1.3 minimal. 
  See the remarks at prerequisites for building the kit
- JEM  ZLIB V1.2-3E1 minimal. 
  See the remarks at prerequisites for building the kit
  
The first three dependencies are tested at installation time, and 
installation will fail if any these products are not installed.
The ZLIB dependency is not tested by the product installation
procedure, as libssh2 will probably be installed as part of 
multiple libraries including zlib.

Install
-------


The kit will install gnv$libssh2.exe in a directory tree that might 
already be available on your system if you have installed other gnv* 
libraries or utilities. 

The directory tree for gnv$libssh2.exe will be like this:

[gnv] -- [usr] -- [include] -- [libssh2] include files for libssh2
                  [lib] gnv$libssh2_x_y_z.exe
                  [share]   -- [doc] -- [libssh2] libssh2.hlb, 
                                        release notes (this file), 
                                        libssh2 release notes   

optional:
                                        [example] libssh2_examples-x_y_z.bck 
                  [common_src] libssh2-x_y_z_src.bck

By default, it will install the shared image and include files to 
SYS$COMMON:[GNV...].

You can override this destination by specifying the destination
directory after /DESTINATION= on the product install command line.
This is particularly of use when installing the library on a cluster
without a common system disk.

Please ignore the following warnings, as the kit is not signed :

%PCSI-I-CANNOTVAL, cannot validate dev:[dir]JCB-AXPVMS-LIBSSH2-V0102-05D20100402-1.PCSI
-PCSI-I-NOTSIGNED, product kit is not signed and therefore has no manifest file

Optionally, you can install a backup saveset with some programming examples,
or a backupo saveset with the complete libssh2 source tree.
 
you will need to answer 'NO' to the question 
'Do you want the default for all options'. 

and 'YES' to either or both the following questions:

    Do you want the libssh2 C programming examples ?  [NO]

    Do you want the complete libssh2 source tree ?  [NO]


Post installation tasks
-----------------------

Although we will try to maintain upward compatibility of libssh2,
this can not be guaranteed by the libssh2 project itself for OpenVMS,
nor eternally by us.

To use libssh2 effectively, you will have to define a system logical
to point to the shared image. If you are willing to take the gamble,
define this logical in your systartup like so:

$ define/system/executive gnv$libssh2 dev:[dir..]gnv$libssh2_x_y_z.exe

Optionally, you can install the executbale like so:

$ mc sysgen install dev:[dir..]gnv$libssh2_x_y_z.exe/open/share/header

Link your programs against gnv$libssh2, and when upgrading libssh2 
test thoroughly.

If you want to be extra cautious define a system logical like this:

$ define/system/executive gnv$libssh2_x_y_z dev:[dir..]gnv$libssh2_x_y_z.exe

Link  programs against gnv$libssh2_x_y_z, and when upgrading libssh2 
link against new versions. 

It is probably more convenient in the last case to link against the object 
library provided in the source backup saveset. Both an uppercase and a
mixed case object library, called libssh2.olb and libssh2_asis.olb 
are provided.


Compiling and linking against libssh2
-------------------------------------

The  shared image library has a vector table with both uppercase and 
mixed case entry points, allowing to link directly against the shared 
image wether you need the /NAMES=AS_IS or not.

To link successfully, you MUST use /NAMES=shortened, as some function
names in libssh2 are longer than the VMS maximum of 32 characters.

If you chose to install the examples, you can unpack the backup
saveset by 

backup/sel=*.c device:[gnv.usr.share.doc.libssh2.examples]libssh2_examples-x_y_z.bck -
 []

They can by compiled and linked by these commands ( provided you have defined
the gnv$libssh2 logical) :

$ cc/include=dev:[gnv.usr.include.libssh2] xxx.c/names=shortened
$ link/opt=sys$input: xxx.obj
gnv$libssh2/share




Building gnv$libssh2
====================

You can build gnv$libssh2 yourself, which may have advantages, as the library is
in full development, very regularly new features are added.

For production use, it is probably advisable to use a stable version, and 
link against that. To check out new features, statically linking against
the object library is probably more practical, to avoid compatibility
issues.


Prerequisites
-------------

You will need to have the following available:

- An Alpha or Itanium VMS system. Due to dependencies on zlib, ssl and ODS-5,
  support on VAXen would be cumbersome at least.

- VMS version 8.3 minimal. This is a requirement of gnv$zlibshr.exe against 
  which shared image library libssh2 is linked. If you use another zlib
  to link against, you can make it work under lower versions of VMS.
  I have made it work on VMS 7.3-2 with not a lot of difficulty.
  Also, if you are not interested in compression, you can choose not
  to link against zlib at all; in that case comment out the 
  #define  LIBSSH2_HAVE_ZLIB in libssh2_config.h.

- TCP/IP services or Multinet for OpenVMS.
  TCPWare has not been tested.

- The HP OpenSSL product. Of course, with tweaking, you can probably link 
  it against the OpenSSL library, but that is not what I have used.
 
- A C compiler. I don't know any other working C compilers than 
  the DEC/Compac/HP-C compiler on VMS.

- An ODS-5 disk. With tweaking you'll get it to work on an ODS-2
  disk, but it is unpractical to do so.

- A version of VMSTAR that understands ODS-5 disks and extended
  filenames. Look here:
  http://ftp.process.com/ftp/vms-freeware/fileserv/vmstar.zip

- gunzip, available for instance at Steven M Schweda's website:
  http://antinode.info/ftp/gzip/gzip-1_3_12b_vms/gzip-1_3_12b_vms.zip

Optional:

- curl, to be found at  https://curl.haxx.se
  You might want to use curl to download the libssh2 kit directly
  to you VMS machine. Interestingly, sftp in curl is implemented using
  libssh2, soon to be expected on VMS as well, hopefully.

Downloading libssh2
-------------------

At the website of libssh2, you can find stable and daily gzipped
tarballs. if you have a computer connected to internet you can 
download a daily build yourself by a procedure that looks a lot like
this ( fill out your own proxy user/password, set up right symbols to
gunzip, vmstar and curl and set up the libssh2 build version):

$ libssh2_version = "1.2.6"
$!
$ proxy_line = " ""-U"" ""''proxy_userpass'""  ""-x"" ""''proxy_hostport'"" "
$!
$ currentday = f$cvtime(,,"date") - "-" - "-"
$!
$ set def mydev:[mydir.libssh2]
$!
$ if f$search("libssh2-''libssh2_version'-''currentday'.tar.gz") .nes. "" 
$ then 
$   delete libssh2-'libssh2_version'-'currentday'.tar.gz;*
$ endif
$!
$ curl 'proxy_line' "https://libssh2.org/snapshots/libssh2-''libssh2_version'-''currentday'.tar.gz" -
                    -o libssh2-'libssh2_version'-'currentday'.tar.gz
$!
$!
$ if f$search("libssh2-''libssh2_version'-''currentday'.tar.;") .nes. "" 
$ then 
$   delete libssh2-'libssh2_version'-'currentday'.tar.;*
$ endif
$!
$ gunzip libssh2-'libssh2_version'-'currentday'.tar.gz
$!
$ tarfile = f$search("libssh2-''libssh2_version'-''currentday'.tar.;")
$ vmstar xf 'tarfile' 

Downloading a stable build will need you to get rid of the currentday.

After the download, you should have a directory tree with a toplevel
directory called [libssh2-x.y.z-yyyymmdd].
One of the subdirectories is called vms.

Getting the libssh2 sources from the source backup in the binary kit
--------------------------------------------------------------------

During installation of the binary kit, you are given the option
of installing the sources. If chosen, a backup saveset with 
the complete libssh2 directory is made available in 
[gnv.common_src].

By restoring this backup saveset, you end up with the same
set of files as by the direct download from libssh2.org.


Building the library
--------------------

To avoid all kinds of misunderstandings caused by firewalls thinking that
a .com file must be an MS-DOS executable, all command procedures are called
.dcl.

Go to the vms subdirectory in the download tree, and issue the following
command:

@libssh2_make_lib.dcl

This should produce libssh2_x_y_z.exe in this same vms directory.
 


Building the examples
---------------------

A number of examples are also part of the full libssh2 delivery.
You can compile and link them either against the object library
produced when building the shared image, or against the shared image
produced in the step before.

You can compile only one of the examples by giving only the
name part of the filename of the example as p1 to the 
build procedure:

@libssh2_make_example.dcl 

or for instance

@libssh2_make_example.dcl sftp 

By default, libssh2_make_example.dcl links to the object libraries 
produced by the libssh2_make_lib.dcl procedure. If you want to link
against the shared image library made in the same procedure, invoke
the procedure like so:

@libssh2_make_example.dcl sftp "SHARED"

The procdure defines a process logical gnv$libssh2 pointing to the shared
image library in the directory, which obviously will not survive a logout. 


Building the help library
-------------------------

The man pages can be converted to a VMS help library by issuing
this command :

@libssh2_make_help.dcl

It uses a simple but fairly effective c program man2help.c
to achieve this.

Building a PCSI kit
-------------------

When you have built the shared library and the help library,
you can build a PCSI kit by issueing this command:

@libssh2_make_kit.dcl